diff --git a/.github/cli/grab-cli-texts.js b/.github/cli/grab-cli-texts.js new file mode 100755 index 000000000..6340e8df3 --- /dev/null +++ b/.github/cli/grab-cli-texts.js @@ -0,0 +1,52 @@ +#!/usr/bin/env node + +// CLI Help Extractor +// ============================ +// runs "npm exec --package= -c " to extract the command output and version +// of the latest tool version and writes it to stdout + +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 toOutput = (str) => [ + '', + `
`,
+    `> ${cmd}`,
+    '',
+    str
+        .replace(/\n.*home.*[|:].*/g, '') // remove absolute cds home path as it's system-specific
+        .replace(/\<(.*?)\>/g, '<$1>') //  -> <foo>
+        .replace(/^\x1b\[1m(.*?)\x1b\[(:?0|39|49)m\n/gm, '$1') // bold at beginning of line -> strong
+        .replace(/(\s*)\x1b\[4m(.*?)\x1b\[(:?0|39|49)m/g, '$1$2') // underline -> i
+        .replace(/(\s*)\x1b\[\d+m(.*?)\x1b\[(:?0|39|49)m/g, '$1$2') // other colors -> em
+    ,
+    `
` +].join('\n') + +try { + const version = (await exec(`npm view ${pkg} version`)).stdout.trim() + if (!/\d+\.\d+\.\d+/.test(version)) { + throw new Error(`unexpected version: ${version}`) + } + + const cmdString = `npm exec --package=${pkg}@${version} -c "${cmd}"` + // const cmdString = `${cmd}` // for local testing + console.error(`> ${cmdString}`) // use stderr for debugging output + 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 (!cmdOut || !cmdOut.includes('\n')) { + throw new Error(`no or invalid output from: ${cmdString}`) + } + // result is on stdout + console.log(toOutput(cmdOut.trim(), version.trim())) +} catch (e) { + console.error(`could not generate synopsis: ${e.message}`, e) +} diff --git a/.github/cli/grab-cli-texts.sh b/.github/cli/grab-cli-texts.sh new file mode 100755 index 000000000..6f76d18b9 --- /dev/null +++ b/.github/cli/grab-cli-texts.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash + +dir=`dirname -- "$0"` + +# create a temp project to run the commands in +proj=/tmp/your-project +rm -rf ${proj} +mkdir -p `dirname ${proj}` +pushd `dirname ${proj}` && cds init `basename ${proj}` && pushd `basename ${proj}` && npm i && popd && popd + +echo +echo "Grabbing CLI texts..." +${dir}/grab-cli-texts.js @cap-js/cds-typer "cds-typer --help" ${proj} > ${dir}/../../tools/assets/help/cds-typer.out.md +${dir}/grab-cli-texts.js @sap/cds-dk "cds --help" ${proj} > ${dir}/../../tools/assets/help/cds-help.out.md +${dir}/grab-cli-texts.js @sap/cds-dk "cds watch --help" ${proj} > ${dir}/../../tools/assets/help/cds-watch.out.md +${dir}/grab-cli-texts.js @sap/cds-dk "cds version" ${proj} > ${dir}/../../tools/assets/help/cds-version.out.md +${dir}/grab-cli-texts.js @sap/cds-dk "cds version --markdown" ${proj} > ${dir}/../../tools/assets/help/cds-version-md.out.md +${dir}/grab-cli-texts.js @sap/cds-dk "cds env requires.db" ${proj} > ${dir}/../../tools/assets/help/cds-env-requires-db.out.md +${dir}/grab-cli-texts.js @sap/cds-dk "cds env ls requires.db" ${proj} > ${dir}/../../tools/assets/help/cds-env-ls-requires-db.out.md +${dir}/grab-cli-texts.js @sap/cds-dk "cds -e .env.requires.db" ${proj} > ${dir}/../../tools/assets/help/cds-eval-env-requires-db.out.md diff --git a/.github/renovate.json b/.github/renovate.json index 6ca15c2a5..3168cb8b8 100644 --- a/.github/renovate.json +++ b/.github/renovate.json @@ -54,65 +54,5 @@ "depNameTemplate": "com.sap.cds:cds4j-api", "datasourceTemplate": "maven", "versioningTemplate": "maven" - }, - { - "customType": "regex", - "fileMatch": ["\\.md$"], - "matchStrings": [ - "\\s*@sap/cds:\\s*\\s*(?\\d+\\.\\d+\\.\\d+)", - "\\|\\s*@sap/cds\\s*\\|\\s*(?\\d+\\.\\d+\\.\\d+)\\s*\\|" - ], - "depNameTemplate": "@sap/cds", - "datasourceTemplate": "npm" - }, - { - "customType": "regex", - "fileMatch": ["\\.md$"], - "matchStrings": [ - "\\s*@sap/cds-compiler:\\s*\\s*(?\\d+\\.\\d+\\.\\d+)", - "\\|\\s*@sap/cds-compiler\\s*\\|\\s*(?\\d+\\.\\d+\\.\\d+)\\s*\\|" - ], - "depNameTemplate": "@sap/cds-compiler", - "datasourceTemplate": "npm" - }, - { - "customType": "regex", - "fileMatch": ["\\.md$"], - "matchStrings": [ - "\\s*@sap/cds-dk:\\s*\\s*(?\\d+\\.\\d+\\.\\d+)", - "\\|\\s*@sap/cds-dk\\s*\\|\\s*(?\\d+\\.\\d+\\.\\d+)\\s*\\|" - ], - "depNameTemplate": "@sap/cds-dk", - "datasourceTemplate": "npm" - }, - { - "customType": "regex", - "fileMatch": ["\\.md$"], - "matchStrings": [ - "\\s*@sap/cds-mtxs:\\s*\\s*(?\\d+\\.\\d+\\.\\d+)", - "\\|\\s*@sap/cds-mtxs\\s*\\|\\s*(?\\d+\\.\\d+\\.\\d+)\\s*\\|" - ], - "depNameTemplate": "@sap/cds-mtxs", - "datasourceTemplate": "npm" - }, - { - "customType": "regex", - "fileMatch": ["\\.md$"], - "matchStrings": [ - "\\s*@sap/eslint-plugin-cds:\\s*\\s*(?\\d+\\.\\d+\\.\\d+)", - "\\|\\s*@sap/eslint-plugin-cds\\s*\\|\\s*(?\\d+\\.\\d+\\.\\d+)\\s*\\|" - ], - "depNameTemplate": "@sap/eslint-plugin-cds", - "datasourceTemplate": "npm" - }, - { - "customType": "regex", - "fileMatch": ["\\.md$"], - "matchStrings": [ - "\\s*Node.js:\\s*\\s*(?v\\d+\\.\\d+\\.\\d+)", - "\\|\\s*Node.js\\s*\\|\\s*(?v\\d+\\.\\d+\\.\\d+)\\s*\\|" - ], - "depNameTemplate": "nodejs", - "datasourceTemplate": "node" } ]} diff --git a/.github/workflows/extract-docs.yml b/.github/workflows/extract-docs.yml index ae99cf4cf..6f71e7d47 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,8 +6,12 @@ on: # Runs every Wednesday at 02:45 AM (UTC) - cron: '45 2 * * 3' +permissions: + contents: write + pull-requests: write + jobs: - run_script_and_create_pr: + run: runs-on: ubuntu-latest steps: @@ -19,34 +23,25 @@ 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 + .github/cli/grab-cli-texts.sh - name: Check for changes run: | git config --global user.name 'github-actions[bot]' git config --global user.email 'github-actions[bot]@users.noreply.github.com' - git add -A - if git diff --cached --exit-code; then + if git diff --exit-code; then echo "No changes detected. Exiting." exit 0 fi - - 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')" - 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." - base: main \ No newline at end of file + branch: "update-cds-cli-texts" + commit-message: "Update CLI texts" + title: "chore: Update CLI texts" + body: "Updates the output of cds CLI texts to the latest version." diff --git a/node.js/cds-env.md b/node.js/cds-env.md index 51ddfd232..c17c66bcd 100644 --- a/node.js/cds-env.md +++ b/node.js/cds-env.md @@ -30,41 +30,26 @@ cds env ? #> get help For example: -
-$ cds env ls requires.sql
-requires.sql.credentials.database = :memory:
-requires.sql.impl = @sap/cds/lib/db/sql-service
-requires.sql.kind = sqlite
-
+ -
-$ cds env get requires.sql
-{
-  credentials: { database: ':memory:' },
-  impl: '@sap/cds/lib/db/sql-service',
-  kind: 'sqlite'
-}
-
+
+ + Alternatively, you can also use the `cds eval` or `cds repl` CLI commands to access the `cds.env` property, which provides programmatic access to the effective settings: -
-$ cds -e .env.requires.sql
-{
-  credentials: { database: ':memory:' },
-  impl: '@sap/cds/lib/db/sql-service',
-  kind: 'sqlite'
-}
-
+ + +
 $ cds -r
 Welcome to cds repl ...
-> cds.env.requires.sql
+> cds.env.requires.db
 {
-  credentials: { database: ':memory:' },
-  impl: '@sap/cds/lib/db/sql-service',
+  impl: '@cap-js/sqlite',
+  credentials: { url: ':memory:' },
   kind: 'sqlite'
 }
diff --git a/tools/assets/help/cds-env-ls-requires-db.out.md b/tools/assets/help/cds-env-ls-requires-db.out.md new file mode 100644 index 000000000..f618c3428 --- /dev/null +++ b/tools/assets/help/cds-env-ls-requires-db.out.md @@ -0,0 +1,8 @@ + +
+> cds env ls requires.db
+
+requires.db.credentials.url = ':memory:'
+requires.db.impl = '@cap-js/sqlite'
+requires.db.kind = 'sqlite'
+
diff --git a/tools/assets/help/cds-env-requires-db.out.md b/tools/assets/help/cds-env-requires-db.out.md new file mode 100644 index 000000000..248cfe53f --- /dev/null +++ b/tools/assets/help/cds-env-requires-db.out.md @@ -0,0 +1,10 @@ + +
+> cds env requires.db
+
+{
+  impl: '@cap-js/sqlite',
+  credentials: { url: ':memory:' },
+  kind: 'sqlite'
+}
+
diff --git a/tools/assets/help/cds-eval-env-requires-db.out.md b/tools/assets/help/cds-eval-env-requires-db.out.md new file mode 100644 index 000000000..41dde178d --- /dev/null +++ b/tools/assets/help/cds-eval-env-requires-db.out.md @@ -0,0 +1,10 @@ + +
+> cds -e .env.requires.db
+
+{
+  impl: '@cap-js/sqlite',
+  credentials: { url: ':memory:' },
+  kind: 'sqlite'
+}
+
diff --git a/tools/assets/help/cds-help.out.md b/tools/assets/help/cds-help.out.md new file mode 100644 index 000000000..215581b59 --- /dev/null +++ b/tools/assets/help/cds-help.out.md @@ -0,0 +1,39 @@ + +
+> 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
+      | 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..64bdac8a7 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 +
+> 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..58b3e93b0 --- /dev/null +++ b/tools/assets/help/cds-version-md.out.md @@ -0,0 +1,20 @@ + +
+> cds version --markdown
+
+| your-project           | <Add your repository here>                      |
+| ---------------------- | ----------------------------------------------- |
+| @cap-js/asyncapi       | 1.0.2                                           |
+| @cap-js/cds-types      | 0.6.5                                           |
+| @cap-js/db-service     | 1.13.0                                          |
+| @cap-js/openapi        | 1.0.5                                           |
+| @cap-js/sqlite         | 1.7.3                                           |
+| @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..bc3307c75 --- /dev/null +++ b/tools/assets/help/cds-version.out.md @@ -0,0 +1,19 @@ + +
+> cds version
+
+@cap-js/asyncapi: 1.0.2
+@cap-js/cds-types: 0.6.5
+@cap-js/db-service: 1.13.0
+@cap-js/openapi: 1.0.5
+@cap-js/sqlite: 1.7.3
+@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..570d83cba --- /dev/null +++ b/tools/assets/help/cds-watch.out.md @@ -0,0 +1,44 @@ + +
+> 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..ef48d9b22 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 @@ -445,14 +349,7 @@ cds add handler --filter submitOrder Use `cds env` to inspect currently effective config settings: -
-$ cds env get requires.db
-{
-  impl: '@sap/cds/libx/_runtime/sqlite/Service.js',
-  credentials: { url: ':memory:' },
-  kind: 'sqlite'
-}
-
+ ## cds compile @@ -527,7 +424,7 @@ Use `cds repl` to live-interact with Node.js APIs: 
 $ cds repl
-Welcome to cds repl v6.7.0
+Welcome to cds repl
 > SELECT.from(Foo)
 Query {
   SELECT: { from: { ref: [ 'Foo' ] } }
@@ -535,9 +432,8 @@ Query {
 
 > cds.requires.db
 {
-  impl: '@sap/cds/libx/_runtime/sqlite/Service.js',
+  impl: '@cap-js/sqlite',
   credentials: { url: ':memory:' },
-  use: [Getter],
   kind: 'sqlite'
 }
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