diff --git a/.github/cli/grab-cli-texts.js b/.github/cli/grab-cli-texts.js new file mode 100755 index 000000000..fbd56ab92 --- /dev/null +++ b/.github/cli/grab-cli-texts.js @@ -0,0 +1,52 @@ +#!/usr/bin/env node + +// CLI Help Extractor +// ============================ +// runs "npm exec --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) => [ + '', + `${unstyled ? '```log' : '
'}`,
+    `> ${pkg}@${version} ${cmd}`,
+    '',
+    str
+        .replace(/\n.*home.*[|:].*/g, '') // remove absolute cds home path as it's system-specific
+        .replace(/\<(.*?)\>/g, '<$1>') //  -> <foo>
+        .replace(/^\x1b\[1m(.*?)\x1b\[0m\n/gm, '$1') // bold at beginning of line -> strong
+        .replace(/(\s*)\x1b\[4m(.*?)\x1b\[0m/g, '$1$2') // underline -> i
+        .replace(/(\s*)\x1b\[\d+m(.*?)\x1b\[0m/g, '$1$2') // other colors -> em
+    , `${unstyled ? '```' : '
'}` +].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) +} diff --git a/.github/workflows/extract-docs.yml b/.github/workflows/extract-docs.yml index ae99cf4cf..575735200 100644 --- a/.github/workflows/extract-docs.yml +++ b/.github/workflows/extract-docs.yml @@ -1,4 +1,4 @@ -name: PR Latest cds-typer Output +name: Update CLI Texts on: workflow_dispatch: @@ -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,15 @@ jobs: with: node-version: '20' - - name: Extract cds-typer --help text - run: node .github/typer/grab-typer-synopsis.js + - name: Extract CLI texts + run: | + npm i -g @sap/cds-dk + pushd /tmp && rm -rf your-project && cds init your-project && pushd your-project && npm i && popd && popd + .github/cli/grab-cli-texts.js @cap-js/cds-typer "cds-typer --help" /tmp/your-project > tools/assets/help/cds-typer.out.md + .github/cli/grab-cli-texts.js @sap/cds-dk "cds --help" /tmp/your-project > tools/assets/help/cds-help.out.md + .github/cli/grab-cli-texts.js @sap/cds-dk "cds watch --help" /tmp/your-project > tools/assets/help/cds-watch.out.md + .github/cli/grab-cli-texts.js @sap/cds-dk "cds version" /tmp/your-project > tools/assets/help/cds-version.out.md + .github/cli/grab-cli-texts.js @sap/cds-dk "cds version --markdown" /tmp/your-project > tools/assets/help/cds-version-md.out.md - name: Check for changes run: | @@ -34,19 +44,20 @@ jobs: - name: Commit changes run: | - git commit -m "Update cds-typer synopsis" - + git commit -m "Update CLI texts" + - name: Push changes + id: push_changes run: | - BRANCH_NAME="update-cds-typer-synopsis-$(date +'%Y%m%d%H%M%S')" + BRANCH_NAME="update-cds-cli-texts-$(date +'%Y%m%d%H%M%S')" git checkout -b "$BRANCH_NAME" git push origin "$BRANCH_NAME" - name: Create Pull Request - uses: peter-evans/create-pull-request@v5 + uses: peter-evans/create-pull-request@v7 with: token: ${{ secrets.GITHUB_TOKEN }} branch: ${{ steps.push_changes.outputs.BRANCH_NAME }} - title: "chore: Update synopsis for cds-typer" - body: "Updates the output of `cds-typer --help` to the latest version." + title: "chore: Update CLI texts" + body: "Updates the output of cds CLI texts to the latest version." base: main \ No newline at end of file diff --git a/tools/assets/help/cds-help.out.md b/tools/assets/help/cds-help.out.md new file mode 100644 index 000000000..00afbec3c --- /dev/null +++ b/tools/assets/help/cds-help.out.md @@ -0,0 +1,39 @@ + +
+> @sap/cds-dk@8.3.0 cds --help --help
+
+USAGE
+    cds <command> [<args>]
+    cds <src>  =  cds compile <src>
+    cds        =  cds help
+
+COMMANDS
+    i | init        jump-start cds-based projects
+    a | add         add a feature to an existing project
+      | gen         generate models/data using a descriptive prompt [beta]
+    y | bind        bind application to remote services
+    m | import      add models from external sources
+    c | compile     compile cds models to different outputs
+    p | parse       parses given cds models
+    s | serve       run your services in local server
+    w | watch       run and restart on file changes
+      | mock        call cds serve with mocked service
+    r | repl        read-eval-event loop
+    e | env         inspect effective configuration
+    b | build       prepare for deployment
+    d | deploy      deploy to databases or cloud
+      | subscribe   subscribe a tenant to a multitenant SaaS app
+      | unsubscribe unsubscribe a tenant from a multitenant SaaS app
+    l | login       login to extensible multitenant SaaS app
+      | logout      logout from extensible multitenant SaaS app
+      | pull        pull base model of extensible SaaS app
+      | push        push extension to extensible SaaS app
+    t | lint        run linter for env or model checks
+    v | version     get detailed version information
+      | completion  add/remove cli completion for cds commands
+    ? | help        get detailed usage information
+
+  Learn more about each command using:
+  cds help <command> or
+  cds <command> --help
+
diff --git a/tools/cds-typer_help-output.md b/tools/assets/help/cds-typer.out.md similarity index 75% rename from tools/cds-typer_help-output.md rename to tools/assets/help/cds-typer.out.md index 0aa209592..0a59e8a63 100644 --- a/tools/cds-typer_help-output.md +++ b/tools/assets/help/cds-typer.out.md @@ -1,6 +1,6 @@ -```log -> @cap-js/cds-typer@0.26.0 --help +
+> @cap-js/cds-typer@0.26.0 cds-typer --help
 
 SYNOPSIS
 
@@ -16,52 +16,45 @@ OPTIONS
 
     This text.
 
-  --inlineDeclarations
-  --inline_declarations: 
+  --IEEE754Compatible: <true | false>
+    (default: false)
+
+    If set to true, floating point properties are generated
+    as IEEE754 compatible '(number | string)' instead of 'number'.
+
+  --inlineDeclarations: <flat | structured>
     (default: structured)
 
     Whether to resolve inline type declarations
     flat: (x_a, x_b, ...)
     or structured: (x: {a, b}).
 
-  --IEEE754Compatible
-  --ieee754compatible: 
-    (default: false)
-
-    If set to true, floating point properties are generated
-    as IEEE754 compatible '(number | string)' instead of 'number'.
-
-  --jsConfigPath
-  --js_config_path: 
+  --jsConfigPath: <string>
 
     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: 
+  --outputDirectory: <string>
     (default: ./)
 
     Root directory to write the generated files to.
 
-  --propertiesOptional
-  --properties_optional: 
+  --propertiesOptional: <true | false>
     (default: true)
 
     If set to true, properties in entities are
     always generated as optional (a?: T).
 
-  --useEntitiesProxy
-  --use_entities_proxy: 
+  --useEntitiesProxy: <true | false>
     (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.
-
-```
\ No newline at end of file
+
diff --git a/tools/assets/help/cds-version-md.out.md b/tools/assets/help/cds-version-md.out.md new file mode 100644 index 000000000..91b420106 --- /dev/null +++ b/tools/assets/help/cds-version-md.out.md @@ -0,0 +1,17 @@ + +
+> @sap/cds-dk@8.3.0 cds version --markdown
+
+| your-project           | <Add your repository here>                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| @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                                                                                  |
+
diff --git a/tools/assets/help/cds-version.out.md b/tools/assets/help/cds-version.out.md new file mode 100644 index 000000000..b4c055e9d --- /dev/null +++ b/tools/assets/help/cds-version.out.md @@ -0,0 +1,16 @@ + +
+> @sap/cds-dk@8.3.0 cds version
+
+@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
+your-project: 1.0.0
+
diff --git a/tools/assets/help/cds-watch.out.md b/tools/assets/help/cds-watch.out.md new file mode 100644 index 000000000..1d8c2e241 --- /dev/null +++ b/tools/assets/help/cds-watch.out.md @@ -0,0 +1,44 @@ + +
+> @sap/cds-dk@8.3.0 cds watch --help
+
+SYNOPSIS
+  cds watch [<project>]
+
+  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:
+  cds serve all --with-mocks --in-memory?
+
+OPTIONS
+  --port <number>
+
+    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 PORT.
+
+  --ext <extensions>
+
+    Specify file extensions to watch for in a comma-separated list.
+    Example: cds w --ext cds,json,js.
+
+  --livereload <port | false>
+
+    Specify the port for the livereload server. Defaults to '35729'.
+    Disable it with value false.
+
+  --open <url>
+
+    Open the given URL (suffix) in the browser after starting.
+    If none is given, the default application URL will be opened.
+
+  --profile <profile,...>
+
+    Specify from which profile(s) the binding information is taken.
+    Example: cds w --profile hybrid,production
+
+SEE ALSO
+  cds serve --help for the different start options.
+
diff --git a/tools/cds-cli.md b/tools/cds-cli.md index 99b38699e..ade8d5662 100644 --- a/tools/cds-cli.md +++ b/tools/cds-cli.md @@ -40,29 +40,12 @@ npm i -g @sap/cds-dk Use `cds version` to get information about your installed package version: -
-$ cds version
-
-@capire/samples: 2.0.0
-@sap/cds: 8.3.0
-@sap/cds-compiler: 5.3.0
-@sap/cds-dk: 8.3.0
-@sap/cds-dk (global): 7.9.3
-@sap/cds-mtxs: 2.2.0
-@sap/eslint-plugin-cds: 3.1.0
-Node.js: v18.13.0
-home: .../node_modules/@sap/cds
-
-$ cds version --markdown
-
-| @capire/samples        | https://github.com/sap-samples/cloud-cap-samples.git |
-|------------------------|------------------------------------------------------|
-| Node.js                | v18.13.0                                             |
-| @sap/cds               | 8.3.0                                                |
-| @sap/cds-compiler      | 5.3.0                                                |
-| @sap/cds-dk            | 8.3.0                                                |
-| @sap/eslint-plugin-cds | 3.1.0                                                |
-
+ + +Using `--markdown` you can get the information in markdown format: + + + ## cds completion @@ -95,90 +78,11 @@ Then source or restart your shell. Use `cds help` to see an overview of all commands: -
-$ cds help
-
-USAGE
-
-    cds <command> [<args>]
-    cds <src>  =  cds compile <src>
-    cds        =  cds help
-
-COMMANDS
-
-    i | init       jump-start cds-based projects
-    a | add        add a feature to an existing project
-    y | bind       bind application to remote services
-    m | import     add models from external sources
-    c | compile    compile cds models to different outputs
-    p | parse      parses given cds models
-    s | serve      run your services in local server
-    w | watch      run and restart on file changes
-    r | repl       read-eval-event loop
-    e | env        inspect effective configuration
-    b | build      prepare for deployment
-    d | deploy     deploy to databases or cloud
-    l | login      login to extendable SaaS application
-    t | lint       [beta] run linter for env or model checks
-    v | version    get detailed version information
-    ? | help       get detailed usage information
-      | pull       pull base model for a SaaS app extension
-      | push       push extension to SaaS app to enable or update it
-      | subscribe  subscribe a tenant to a multitenant SaaS app
-      | completion add/remove shell completion for cds commands
-      | mock       call cds serve with mocked service
-      | handler    add handler stubs for actions and functions
-
-  Learn more about each command using:
-  cds help <command> or
-  cds <command> --help
-
- + Use `cds help ` or `cds ?` to get specific help: -
-$ cds watch --help
-
-SYNOPSIS
-
-  cds watch [<project>]
-
-  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:
-  cds serve all --with-mocks --in-memory?
-
-OPTIONS
-
-  --port <number>
-
-    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 PORT.
-
-  --ext <extensions>
-
-    Specify file extensions to watch for in a comma-separated list.
-    Example: cds w --ext cds,json,js.
-
-  --livereload <port | false>
-
-    Specify the port for the livereload server. Defaults to '35729'.
-    Disable it with value false.
-
-  --open <url>
-
-    Open the given URL (suffix) in the browser after starting.
-    If none is given, the default application URL will be opened.
-
-SEE ALSO
-
-  cds serve --help for the different start options.
-
- + ## cds init diff --git a/tools/cds-typer.md b/tools/cds-typer.md index 47e2c4dd1..17d95d80c 100644 --- a/tools/cds-typer.md +++ b/tools/cds-typer.md @@ -310,7 +310,7 @@ npx @cap-js/cds-typer /home/mybookshop/db/schema.cds --outputDirectory /home/myb The CLI offers several parameters which you can list using the `--help` parameter. ::: details You should then see the following output: - + ::: ### Configuration