Generic CLI output grabbing

.github/cli/grab-cli-out.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// CLI Help Extractor
+// ============================
+// runs "npm exec <tool> --help" to extract the synopsis and version
+// of the latest tool version and writes it to a markdown file
+// that is included in a documentation page.
+
+import * as proc from 'node:child_process'
+import * as util from 'node:util'
+
+const exec = util.promisify(proc.exec)
+const pkg = process.argv[2]
+if (!pkg) throw new Error('Missing package')
+const cmd = process.argv[3] || pkg.split('/').pop()
+const cwd = process.argv[4] || process.cwd()
+const unstyled = process.argv.some(a => a === '--unstyled')
+
+const toMarkdown = (version, str) => [
+    '<!-- this file is automatically generated and updated by a github action -->',
+    `${unstyled ? '```log' : '<pre class="log">'}`,
+    `> ${pkg}@${version} ${cmd}`,
+    '',
+    str
+        .replace(/\n.*home.*[|:].*/g, '') // remove absolute cds home path as it's system-specific
+        .replace(/\<(.*?)\>/g, '&lt;$1&gt;') // <foo> -> &lt;foo&gt;
+        .replace(/^\x1b\[1m(.*?)\x1b\[0m\n/gm, '<strong>$1</strong>') // bold at beginning of line -> strong
+        .replace(/(\s*)\x1b\[4m(.*?)\x1b\[0m/g, '$1<i>$2</i>') // underline -> i
+        .replace(/(\s*)\x1b\[\d+m(.*?)\x1b\[0m/g, '$1<em>$2</em>') // other colors -> em
+    , `${unstyled ? '```' : '</pre>'}`
+].join('\n')
+
+try {
+    const cmdString = `npm exec --package=${pkg} -c "${cmd}"`
+    const { stdout: version }  = await exec(`npm view ${pkg} version`)
+    const { stdout: cmdOut }   = await exec(cmdString, {cwd, env: { FORCE_COLOR: 'true', ...process.env }})
+
+    // some very basic plausibility checks to make sure we don't
+    // end up with garbage or npx errors in the markdown
+    if (!/\d+\.\d+\.\d+/.test(version)) {
+        throw new Error(`unexpected version: ${version}`)
+    }
+    if (!cmdOut) {
+        throw new Error(`no output from: ${cmdString}`)
+    }
+    if (cmd.includes('help') && !/SYNOPSIS|USAGE/.test(cmdOut)) {
+        throw new Error(`unexpected synopsis: ${cmdOut}`)
+    }
+    console.log(toMarkdown(version.trim(), cmdOut.trim()))
+} catch (e) {
+    console.error(`could not generate synopsis: ${e.message}`, e)
+}

.github/workflows/extract-docs.yml

@@ -6,6 +6,9 @@ on:
     # Runs every Wednesday at 02:45 AM (UTC)
     - cron: '45 2 * * 3'
 
+permissions:
+  contents: write
+
 jobs:
   run_script_and_create_pr:
     runs-on: ubuntu-latest
@@ -19,8 +22,14 @@ jobs:
         with:
           node-version: '20'
 
-      - name: Extract cds-typer --help text
-        run: node .github/typer/grab-typer-synopsis.js
+      - name: Extract CLI (help) texts
+        run: |
+          pushd /tmp && rm -rf your-project && cds init your-project && pushd your-project && npm i && popd && popd
+          .github/cli/grab-cli-out.js @cap-js/cds-typer "cds-typer --help"        /tmp/your-project > tools/assets/help/cds-typer.out.md
+          .github/cli/grab-cli-out.js @sap/cds-dk       "cds --help"              /tmp/your-project > tools/assets/help/cds-help.out.md
+          .github/cli/grab-cli-out.js @sap/cds-dk       "cds watch --help"        /tmp/your-project > tools/assets/help/cds-watch.out.md
+          .github/cli/grab-cli-out.js @sap/cds-dk       "cds version"             /tmp/your-project > tools/assets/help/cds-version.out.md
+          .github/cli/grab-cli-out.js @sap/cds-dk       "cds version --markdown"  /tmp/your-project > tools/assets/help/cds-version-md.out.md
 
       - name: Check for changes
         run: |
@@ -35,7 +44,7 @@ jobs:
       - name: Commit changes
         run: |
           git commit -m "Update cds-typer synopsis"
-      
+
       - name: Push changes
         run: |
           BRANCH_NAME="update-cds-typer-synopsis-$(date +'%Y%m%d%H%M%S')"

tools/assets/help/cds-help.out.md

@@ -0,0 +1,39 @@
+<!-- this file is automatically generated and updated by a github action -->
+<pre class="log">
+> @sap/[email protected] cds --help --help
+
+<strong>USAGE</strong>
+    <em>cds</em> &lt;command&gt; [&lt;args&gt;]
+    <em>cds</em> &lt;src&gt;  =  <em>cds compile</em> &lt;src&gt;
+    <em>cds</em>        =  <em>cds help</em>
+
+<strong>COMMANDS</strong>
+    <em>i</em> | <em>init</em>        jump-start cds-based projects
+    <em>a</em> | <em>add</em>         add a feature to an existing project
+    <em> </em> | <em>gen</em>         generate models/data using a descriptive prompt [beta]
+    <em>y</em> | <em>bind</em>        bind application to remote services
+    <em>m</em> | <em>import</em>      add models from external sources
+    <em>c</em> | <em>compile</em>     compile cds models to different outputs
+    <em>p</em> | <em>parse</em>       parses given cds models
+    <em>s</em> | <em>serve</em>       run your services in local server
+    <em>w</em> | <em>watch</em>       run and restart on file changes
+    <em> </em> | <em>mock</em>        call <i>cds serve</i> with mocked service
+    <em>r</em> | <em>repl</em>        read-eval-event loop
+    <em>e</em> | <em>env</em>         inspect effective configuration
+    <em>b</em> | <em>build</em>       prepare for deployment
+    <em>d</em> | <em>deploy</em>      deploy to databases or cloud
+    <em> </em> | <em>subscribe</em>   subscribe a tenant to a multitenant SaaS app
+    <em> </em> | <em>unsubscribe</em> unsubscribe a tenant from a multitenant SaaS app
+    <em>l</em> | <em>login</em>       login to extensible multitenant SaaS app
+    <em> </em> | <em>logout</em>      logout from extensible multitenant SaaS app
+    <em> </em> | <em>pull</em>        pull base model of extensible SaaS app
+    <em> </em> | <em>push</em>        push extension to extensible SaaS app
+    <em>t</em> | <em>lint</em>        run linter for env or model checks
+    <em>v</em> | <em>version</em>     get detailed version information
+    <em> </em> | <em>completion</em>  add/remove cli completion for cds commands
+    <em>?</em> | <em>help</em>        get detailed usage information
+
+  Learn more about each command using:
+  <em>cds help</em> &lt;command&gt; or
+  <em>cds</em> &lt;command&gt; <em>--help</em>
+</pre>

tools/cds-typer_help-output.md → tools/assets/help/cds-typer.out.md

@@ -1,6 +1,6 @@
 <!-- this file is automatically generated and updated by a github action -->
-```log
-> @cap-js/[email protected] --help
+<pre class="log">
+> @cap-js/[email protected] cds-typer --help
 
 SYNOPSIS
 
@@ -16,52 +16,45 @@ OPTIONS
 
     This text.
 
-  --inlineDeclarations
-  --inline_declarations: <flat | structured>
+  --IEEE754Compatible: &lt;true | false&gt;
+    (default: false)
+
+    If set to true, floating point properties are generated
+    as IEEE754 compatible '(number | string)' instead of 'number'.
+
+  --inlineDeclarations: &lt;flat | structured&gt;
     (default: structured)
 
     Whether to resolve inline type declarations
     flat: (x_a, x_b, ...)
     or structured: (x: {a, b}).
 
-  --IEEE754Compatible
-  --ieee754compatible: <true | false>
-    (default: false)
-
-    If set to true, floating point properties are generated
-    as IEEE754 compatible '(number | string)' instead of 'number'.
-
-  --jsConfigPath
-  --js_config_path: <string>
+  --jsConfigPath: &lt;string&gt;
 
     Path to where the jsconfig.json should be written.
     If specified, cds-typer will create a jsconfig.json file and
     set it up to restrict property usage in types entities to
     existing properties only.
 
-  --logLevel
-  --log_level SILENT | ERROR | WARN | INFO | DEBUG | TRACE | SILLY | VERBOSE
+  --logLevel SILENT | ERROR | WARN | INFO | DEBUG | TRACE | SILLY | VERBOSE
     (default: ERROR)
 
     Minimum log level that is printed.
     The default is only used if no explicit value is passed
     and there is no configuration passed via cds.env either.
 
-  --outputDirectory
-  --output_directory: <string>
+  --outputDirectory: &lt;string&gt;
     (default: ./)
 
     Root directory to write the generated files to.
 
-  --propertiesOptional
-  --properties_optional: <true | false>
+  --propertiesOptional: &lt;true | false&gt;
     (default: true)
 
     If set to true, properties in entities are
     always generated as optional (a?: T).
 
-  --useEntitiesProxy
-  --use_entities_proxy: <true | false>
+  --useEntitiesProxy: &lt;true | false&gt;
     (default: false)
 
     If set to true the 'cds.entities' exports in the generated 'index.js'
@@ -74,5 +67,4 @@ OPTIONS
   --version
 
     Prints the version of this tool.
-
-```
+</pre>

tools/assets/help/cds-version-md.out.md

@@ -0,0 +1,17 @@
+<!-- this file is automatically generated and updated by a github action -->
+<pre class="log">
+> @sap/[email protected] cds version --markdown
+
+| your-project           | &lt;Add your repository here&gt;                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| @cap-js/asyncapi       | 1.0.2                                                                                    |
+| @cap-js/openapi        | 1.0.5                                                                                    |
+| @sap/cds               | 8.3.0                                                                                    |
+| @sap/cds-compiler      | 5.3.0                                                                                    |
+| @sap/cds-dk (global)   | 8.4.0                                                                                    |
+| @sap/cds-fiori         | 1.2.7                                                                                    |
+| @sap/cds-foss          | 5.0.1                                                                                    |
+| @sap/cds-mtxs          | 2.1.1                                                                                    |
+| @sap/eslint-plugin-cds | 3.0.6                                                                                    |
+| Node.js                | v22.8.0                                                                                  |
+</pre>

tools/assets/help/cds-version.out.md

@@ -0,0 +1,16 @@
+<!-- this file is automatically generated and updated by a github action -->
+<pre class="log">
+> @sap/[email protected] cds version
+
+<em>@cap-js/asyncapi</em>: 1.0.2
+<em>@cap-js/openapi</em>: 1.0.5
+<em>@sap/cds</em>: 8.3.0
+<em>@sap/cds-compiler</em>: 5.3.0
+<em>@sap/cds-dk (global)</em>: 8.4.0
+<em>@sap/cds-fiori</em>: 1.2.7
+<em>@sap/cds-foss</em>: 5.0.1
+<em>@sap/cds-mtxs</em>: 2.1.1
+<em>@sap/eslint-plugin-cds</em>: 3.0.6
+<em>Node.js</em>: v22.8.0
+<em>your-project</em>: 1.0.0
+</pre>

tools/assets/help/cds-watch.out.md

@@ -0,0 +1,44 @@
+<!-- this file is automatically generated and updated by a github action -->
+<pre class="log">
+> @sap/[email protected] cds watch --help
+
+<strong>SYNOPSIS</strong>
+  <em>cds watch</em> [&lt;project&gt;]
+
+  Tells cds to watch for relevant things to come or change in the specified
+  project or the current work directory. Compiles and (re-)runs the server
+  on every change detected.
+
+  Actually, cds watch is just a convenient shortcut for:
+  <em>cds serve all --with-mocks --in-memory?</em>
+
+<strong>OPTIONS</strong>
+  <em>--port</em> &lt;number&gt;
+
+    Specify the port on which the launched server listens.
+    If you specify '0', the server picks a random free port.
+    Alternatively, specify the port using env variable <i>PORT</i>.
+
+  <em>--ext</em> &lt;extensions&gt;
+
+    Specify file extensions to watch for in a comma-separated list.
+    <em>Example:</em> cds w --ext cds,json,js.
+
+  <em>--livereload</em> &lt;port | false&gt;
+
+    Specify the port for the livereload server. Defaults to '35729'.
+    Disable it with value <i>false</i>.
+
+  <em>--open</em> &lt;url&gt;
+
+    Open the given URL (suffix) in the browser after starting.
+    If none is given, the default application URL will be opened.
+
+  <em>--profile</em> &lt;profile,...&gt;
+
+    Specify from which profile(s) the binding information is taken.
+    <em>Example:</em> cds w --profile hybrid,production
+
+<strong>SEE ALSO</strong>
+  <em>cds serve --help</em> for the different start options.
+</pre>