goke 6.1.3 → 6.2.1

package/README.md

@@ -51,7 +51,7 @@ cli
   .option('--minify', 'Minify output')
   .example('build src/index.ts')
   .example('build src/index.ts --minify')
-  .action((entry, options) => {
+  .action(async (entry, options) => { // options is type safe! no need to type it
     console.log(entry, options)
   })
 
@@ -89,6 +89,196 @@ cli.help()
 cli.parse()
 ```
 
+### Rich Multi-line Command Descriptions (`string-dedent`)
+
+When a command needs a long description (with bullets, quotes, inline code, and
+multiple examples), use [`string-dedent`](https://www.npmjs.com/package/string-dedent)
+to keep the source readable while preserving clean help output.
+
+Install:
+
+```bash
+npm install string-dedent
+```
+
+Example with detailed command descriptions:
+
+```ts
+import { goke } from 'goke'
+import dedent from 'string-dedent'
+
+const cli = goke('acme')
+
+cli
+  .command(
+    'release <version>',
+    dedent`
+      Publish a versioned release to your distribution channels.
+
+      - **Validates** release metadata and changelog before publishing.
+      - **Builds** production artifacts with reproducible settings.
+      - **Tags** git history using semantic version format.
+      - **Publishes** to npm and creates release notes.
+
+      > Recommended flow: run with \`--dry-run\` first in CI to verify output.
+
+      Examples:
+      - \`acme release 2.4.0 --channel stable\`
+      - \`acme release 2.5.0-rc.1 --channel beta --dry-run\`
+      - \`acme release 3.0.0 --notes-file ./docs/releases/3.0.0.md\`
+    `,
+  )
+  .option('--channel <name>', 'Target channel: stable, beta, alpha')
+  .option('--notes-file <path>', 'Markdown file used as release notes')
+  .option('--dry-run', 'Preview every step without publishing')
+  .action((version, options) => {
+    console.log('release', version, options)
+  })
+
+cli
+  .command(
+    'db migrate',
+    dedent`
+      Apply pending database migrations in a controlled sequence.
+
+      - Runs migrations in timestamp order.
+      - Stops immediately on first failure.
+      - Prints SQL statements when \`--verbose\` is enabled.
+      - Supports smoke-testing with \`--dry-run\`.
+
+      > Safety: always run this command against staging before production.
+
+      Examples:
+      - \`acme db migrate\`
+      - \`acme db migrate --target 20260210120000_add_users\`
+      - \`acme db migrate --dry-run --verbose\`
+    `,
+  )
+  .option('--target <migration>', 'Apply up to a specific migration id')
+  .option('--dry-run', 'Print plan only, do not execute SQL')
+  .option('--verbose', 'Show each executed statement')
+  .action((options) => {
+    console.log('migrate', options)
+  })
+
+cli.help()
+cli.parse()
+```
+
+Why this pattern works well:
+
+- `dedent` keeps template literals readable in source files.
+- Help text stays aligned without extra leading whitespace.
+- You can include rich formatting patterns users already recognize:
+  lists, quotes, and inline command snippets.
+- Long descriptions remain maintainable as your CLI grows.
+
+### Rich `.example(...)` Blocks with `dedent`
+
+You can also use `dedent` in `.example(...)` so examples stay readable in code and
+render nicely in help output. A useful pattern is to make the **first line a `#`
+comment** that explains the scenario.
+
+```ts
+import { goke } from 'goke'
+import dedent from 'string-dedent'
+
+const cli = goke('tuistory')
+
+cli
+  .command('start', 'Start an interactive session')
+  .example(dedent`
+    # Launch and immediately check what the app shows
+    tuistory launch "claude" -s ai && tuistory -s ai snapshot --trim
+  `)
+  .example(dedent`
+    # Start a focused coding session with explicit context
+    tuistory start --agent code --context "Fix OAuth callback timeout"
+  `)
+  .example(dedent`
+    # Recover recent activity and inspect the latest run details
+    tuistory runs list --limit 5 && tuistory runs show --latest
+  `)
+  .action(() => {
+    // command implementation
+  })
+
+cli
+  .command('deploy', 'Deploy current workspace')
+  .example(dedent`
+    # Dry-run deployment first to validate plan
+    tuistory deploy --env staging --dry-run
+  `)
+  .example(dedent`
+    # Deploy production with release notes attached
+    tuistory deploy --env production --notes ./docs/release.md
+  `)
+  .action(() => {
+    // command implementation
+  })
+
+cli.help()
+cli.parse()
+```
+
+Notes:
+
+- Keep each example focused on one workflow.
+- Use the first `#` line as a human-readable intent label.
+- Keep command lines copy-pastable (avoid placeholder-heavy examples).
+
+Where examples are rendered today:
+
+- For root help (`deploy --help`), examples from the root/default command appear in an **Examples** section at the end.
+- For subcommand help (`deploy logs --help`), examples from that specific subcommand appear in its own **Examples** section at the end.
+
+Inline snapshot-style output (many commands):
+
+```txt
+deploy
+
+Usage:
+  $ deploy [options]
+
+Commands:
+  deploy               Deploy the current project
+  init                 Initialize a new project
+  login                Authenticate with the server
+  logout               Clear saved credentials
+  status               Show deployment status
+  logs <deploymentId>  Stream logs for a deployment
+
+Options:
+  --env <env>  Target environment
+  --dry-run    Preview without deploying
+  -h, --help   Display this message
+
+Examples:
+# Deploy to staging first
+deploy --env staging --dry-run
+```
+
+```txt
+deploy
+
+Usage:
+  $ deploy logs <deploymentId>
+
+Options:
+  --follow     Follow log output
+  --lines <n>  Number of lines (default: 100)
+  -h, --help   Display this message
+
+Description:
+  Stream logs for a deployment
+
+Examples:
+# Stream last 200 lines for a deployment
+deploy logs dep_123 --lines 200
+# Keep following new log lines
+deploy logs dep_123 --follow
+```
+
 ### Many Commands with a Root Command
 
 Use `''` as the command name to define a root command that runs when no subcommand is given. This is useful for CLIs that have a primary action alongside several subcommands:
@@ -229,11 +419,39 @@ cli
 cli.parse()
 ```
 
-The second argument accepts any object implementing [Standard JSON Schema V1](https://github.com/standard-schema/standard-schema), including:
+**Important:** When using a schema with `.default()`, do **not** repeat the default in the description string. The framework automatically appends `(default: <value>)` to help output from the schema default. Writing `.default(100).describe('Number of lines (default: 100)')` would display the default twice.
+
+The second argument accepts any object implementing [Standard Schema](https://github.com/standard-schema/standard-schema), including:
 
 - **Zod** v4.2+ (e.g. `z.number()`, `z.string()`, `z.array(z.number())`)
 - **Valibot**, **ArkType**, and other Standard Schema-compatible libraries
-- **Plain JSON Schema** via `wrapJsonSchema({ type: "number", description: "Port" })`
+
+### Hiding Deprecated Options
+
+Mark options as deprecated using Zod's `.meta({ deprecated: true })`. Deprecated options are hidden from help output but still work for parsing — useful for backward compatibility.
+
+```ts
+import { goke } from 'goke'
+import { z } from 'zod'
+
+const cli = goke()
+
+cli
+  .command('serve', 'Start server')
+  // Deprecated option: hidden from --help, still parses
+  .option('--old-port <port>', z.number().meta({ deprecated: true, description: 'Use --port instead' }))
+  // Current option: visible in help
+  .option('--port <port>', z.number().describe('Port number'))
+  .action((options) => {
+    const port = options.port ?? options.oldPort
+    console.log('Starting on port', port)
+  })
+
+cli.help()
+cli.parse()
+```
+
+When users run `--help`, deprecated options won't appear, but `--old-port 3000` still works.
 
 ### Brackets
 
@@ -267,6 +485,48 @@ cli
   })
 ```
 
+### Double-dash `--` (end of options)
+
+The `--` token signals the end of options. Everything after `--` is available via `options['--']` as a separate array, not mixed into positional args. This lets you distinguish between your command's own arguments and passthrough args — the same pattern used by `doppler`, `npm`, `pnpm`, and `docker`.
+
+```ts
+import { goke } from 'goke'
+import { z } from 'zod'
+import { execSync } from 'child_process'
+
+const cli = goke('runner')
+
+cli
+  .command('run <script>', 'Run a script with injected environment variables')
+  .option('--env <env>', z.enum(['dev', 'staging', 'production']).describe('Target environment'))
+  .example('# Pass extra flags to the child script via --')
+  .example('runner run --env staging server.js -- --port 3000 --verbose')
+  .action((script, options) => {
+    // runner run --env staging server.js -- --port 3000 --verbose
+    // script = 'server.js'           (positional arg)
+    // options.env = 'staging'         (runner's own option)
+    // options['--'] = ['--port', '3000', '--verbose']  (passthrough)
+
+    const secrets = loadSecrets(options.env)
+    const extraArgs = (options['--'] || []).join(' ')
+    execSync(`node ${script} ${extraArgs}`, {
+      env: { ...process.env, ...secrets },
+      stdio: 'inherit',
+    })
+  })
+
+cli.help()
+cli.parse()
+```
+
+```bash
+runner run --env staging server.js -- --port 3000 --verbose
+#          ^^^^^^^^^^^^  ^^^^^^^^^    ^^^^^^^^^^^^^^^^^^^^^^^^^
+#          runner option  positional   passthrough (options['--'])
+```
+
+Without `--`, flags like `--port` would be parsed as runner options and fail with "Unknown option `--port`". The `--` tells goke to stop parsing and collect the rest separately.
+
 ### Dot-nested Options
 
 Dot-nested options will be merged into a single option.
@@ -386,6 +646,24 @@ Add a global option. The second argument is either:
 
 - Type: `() => CLI`
 
+Print the help message to stdout.
+
+#### cli.helpText()
+
+- Type: `() => string`
+
+Return the formatted help string without printing it. Useful for embedding help text in documentation, tests, or other programmatic uses.
+
+```ts
+const cli = goke('mycli')
+cli.command('build', 'Build project')
+cli.option('--watch', 'Watch mode')
+cli.help()
+
+const help = cli.helpText()
+// => "mycli\n\nUsage:\n  $ mycli ..."
+```
+
 #### cli.usage(text)
 
 - Type: `(text: string) => CLI`