goke 6.6.0 → 6.6.2

package/README.md

@@ -654,6 +654,60 @@ When using brackets in option name, angled brackets indicate that a string / num
 
 **Optionality is determined solely by bracket syntax, not by the schema.** `[square brackets]` makes an option optional regardless of whether the schema is `z.string()` or `z.string().optional()`. The schema's `.optional()` is never consulted for this — it only affects type coercion. This means `z.string()` with `[--name]` is treated as optional: if the flag is omitted, `options.name` is `undefined` even though the schema has no `.optional()`.
 
+### Optional-value flags — `--flag` vs `--flag value` vs omitted
+
+A flag declared with square brackets (`--host [host]`) has **three distinct runtime states**, not two. The user can:
+
+1. **Omit the flag entirely** — no `--host` on the command line at all
+2. **Pass the flag bare** — `--host` by itself, with no value following it
+3. **Pass the flag with a value** — `--host example.com`
+
+goke surfaces all three cases through a single `string | undefined` type. There is no `boolean` in the union — bare flags are normalized to the **empty string `''`** so callers only ever deal with strings:
+
+```ts
+cli
+  .command('serve', 'Start the server')
+  .option('--host [host]', 'Optional host override')
+  .action((options) => {
+    // options.host: string | undefined
+    //   --host              → ''                (flag present, no value)
+    //   --host example.com  → 'example.com'
+    //   (omitted)           → undefined
+  })
+```
+
+**Detecting each case:**
+
+```ts
+.action((options) => {
+  if (options.host === undefined) {
+    // Flag was not passed at all — use a sensible default
+    console.log('using default host: localhost')
+  } else if (options.host === '') {
+    // Flag was passed bare: `--host` with no value following it
+    // Treat this as an explicit "opt in, but use the default/automatic value"
+    console.log('host flag passed with no value — enabling auto-discovery')
+  } else {
+    // Flag was passed with an explicit value
+    console.log(`host = ${options.host}`)
+  }
+})
+```
+
+**In most cases you don't need the three-way distinction** — a plain truthy check collapses "omitted" and "bare flag" into the same "fall back to default" branch:
+
+```ts
+.action((options) => {
+  // `--host` bare AND omitted both fall through to the default
+  const host = options.host || 'localhost'
+  startServer({ host })
+})
+```
+
+Reserve the `=== ''` check for cases where "opt in without a value" is a meaningful signal distinct from "flag omitted" — for example, `--direct` meaning "auto-discover a Chrome instance" vs `--direct ws://…` meaning "connect to this specific endpoint" vs no `--direct` meaning "don't use direct mode".
+
+> **Breaking change note (goke 6.6.0):** prior versions surfaced bare flags as `boolean` `true` inside a `string | boolean | undefined` union, forcing every call site to write `typeof options.host === 'string' ? options.host : undefined`. Code that used `options.host === true` to detect the bare-flag case must be updated to `options.host === ''`. Schema-based optional flags with `.default(...)` are unaffected — the default still kicks in when the flag is passed bare.
+
 ### Negated Options
 
 To allow an option whose value is `false`, you need to manually specify a negated option:
@@ -684,6 +738,8 @@ cli
 
 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`.
 
+`options['--']` is **always present** on the inferred options type as `string[]`. When no `--` token appears on the command line, it's the empty array — you never need to guard with `||` or `?.` or an `Array.isArray` cast.
+
 ```ts
 import { goke } from 'goke'
 import { z } from 'zod'
@@ -700,10 +756,10 @@ cli
     // 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)
+    // options['--'] = ['--port', '3000', '--verbose']  (passthrough, always string[])
 
     const secrets = loadSecrets(options.env)
-    const extraArgs = (options['--'] || []).join(' ')
+    const extraArgs = options['--'].join(' ')
     execSync(`node ${script} ${extraArgs}`, {
       env: { ...process.env, ...secrets },
       stdio: 'inherit',
@@ -915,6 +971,90 @@ Always run `acme --help` before using this CLI.
 For subcommand details: `acme <command> --help`
 ````
 
+## YAML Output for Agent-Friendly CLIs
+
+When a command returns structured data, print it as YAML on stdout. YAML is the best middle ground between human-readable output and machine-processable output:
+
+- Humans can read it at a glance — no surrounding quotes on keys, less punctuation noise than JSON.
+- Agents can process it with [`yq`](https://github.com/mikefarah/yq), the YAML equivalent of `jq`, to extract specific fields or filter results.
+- It is more context-efficient than verbose prose: a compact YAML block conveys the same information in fewer tokens.
+
+```ts
+import { goke } from 'goke'
+import { stringify } from 'yaml'
+
+const cli = goke('deploy')
+
+cli
+  .command('status', 'Show deployment status')
+  .action(async (options, { console }) => {
+    const status = await fetchStatus()
+    // Output structured data as YAML on stdout
+    console.log(stringify(status))
+  })
+```
+
+Example output:
+
+```yaml
+deployment: prod-v2
+status: running
+replicas: 3
+lastDeploy: "2026-01-15T10:30:00Z"
+health:
+  cpu: 42%
+  memory: 1.2GB
+```
+
+### Processing YAML output with yq
+
+Agents can pipe the output through `yq` to extract specific fields or filter results — the same way they would use `jq` with JSON, but with cleaner, more readable output:
+
+```bash
+# Extract a single field
+deploy status | yq '.deployment'
+
+# Access nested fields
+deploy status | yq '.health.cpu'
+
+# Filter an array of results
+deploy list | yq '.[] | select(.status == "running")'
+
+# Combine multiple fields
+deploy list | yq '.[] | {name: .name, status: .status}'
+
+# Count items matching a condition
+deploy list | yq '[.[] | select(.status == "error")] | length'
+```
+
+### Keep stdout clean — send non-YAML to stderr
+
+If a command outputs YAML on stdout, all unrelated content must go to stderr: error messages, progress indicators, informational logs, warnings. This keeps stdout pipeable through `yq` without breaking the YAML parse.
+
+```ts
+cli
+  .command('deploy <env>', 'Deploy to environment')
+  .action(async (env, options, { console }) => {
+    // Progress and logs → stderr (won't pollute yq pipes)
+    console.error(`Deploying to ${env}...`)
+    console.error('Building artifacts...')
+
+    const result = await deploy(env)
+
+    // Structured result → stdout as YAML
+    console.log(stringify(result))
+  })
+```
+
+Now agents can process the output cleanly:
+
+```bash
+# Only the YAML result reaches yq — progress lines go to the terminal
+deploy deploy production | yq '.version'
+```
+
+If an error occurs, throw or write to `console.error` / `process.stderr`, and exit with a non-zero code. Never mix error text into stdout when the command is expected to output YAML.
+
 ## Contributor Notes
 
 ### Rules

package/dist/coerce.d.ts

@@ -78,13 +78,35 @@ export declare namespace StandardJSONSchemaV1 {
 /**
  * Wraps a plain JSON Schema object into a StandardJSONSchemaV1-compatible object.
  *
- * @internal This is an internal helper used by @goke/mcp to wrap MCP tool schemas.
- * Users should pass Zod or other StandardSchema-compatible schemas to `.option()`.
+ * Originally built for @goke/mcp to wrap MCP tool schemas, but also useful for
+ * any consumer that has a hand-written JSON Schema (e.g. an array of strings
+ * or a tagged union) and wants goke's `.action()` callback to infer the right
+ * option type without reaching for Zod. Pass an explicit `Output` type
+ * parameter to tell TypeScript what the coerced value will look like at
+ * runtime — goke does not validate the output shape, it just propagates it
+ * into the inferred options type for `.action()` callbacks.
+ *
+ * @example
+ * ```ts
+ * cli
+ *   .command('diff', 'Show diff')
+ *   .option(
+ *     '--filter <glob>',
+ *     wrapJsonSchema<string[]>({
+ *       type: 'array',
+ *       items: { type: 'string' },
+ *       description: 'Glob pattern (repeatable)',
+ *     }),
+ *   )
+ *   .action((options) => {
+ *     // options.filter: string[] | undefined
+ *   })
+ * ```
  *
  * @param jsonSchema - A plain JSON Schema object (e.g. `{ type: "number" }`)
  * @returns A StandardJSONSchemaV1-compatible object that Goke can use for coercion
  */
-export declare function wrapJsonSchema(jsonSchema: Record<string, unknown>): StandardJSONSchemaV1;
+export declare function wrapJsonSchema<Output = unknown>(jsonSchema: Record<string, unknown>): StandardJSONSchemaV1<unknown, Output>;
 /** Minimal JSON Schema interface — only what we need for CLI coercion. */
 export interface JsonSchema {
     type?: string | string[];

package/dist/coerce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../src/coerce.ts"],"names":[],"mappings":"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"}

package/dist/coerce.js

@@ -50,8 +50,30 @@ export class GokeError extends Error {
 /**
  * Wraps a plain JSON Schema object into a StandardJSONSchemaV1-compatible object.
  *
- * @internal This is an internal helper used by @goke/mcp to wrap MCP tool schemas.
- * Users should pass Zod or other StandardSchema-compatible schemas to `.option()`.
+ * Originally built for @goke/mcp to wrap MCP tool schemas, but also useful for
+ * any consumer that has a hand-written JSON Schema (e.g. an array of strings
+ * or a tagged union) and wants goke's `.action()` callback to infer the right
+ * option type without reaching for Zod. Pass an explicit `Output` type
+ * parameter to tell TypeScript what the coerced value will look like at
+ * runtime — goke does not validate the output shape, it just propagates it
+ * into the inferred options type for `.action()` callbacks.
+ *
+ * @example
+ * ```ts
+ * cli
+ *   .command('diff', 'Show diff')
+ *   .option(
+ *     '--filter <glob>',
+ *     wrapJsonSchema<string[]>({
+ *       type: 'array',
+ *       items: { type: 'string' },
+ *       description: 'Glob pattern (repeatable)',
+ *     }),
+ *   )
+ *   .action((options) => {
+ *     // options.filter: string[] | undefined
+ *   })
+ * ```
  *
  * @param jsonSchema - A plain JSON Schema object (e.g. `{ type: "number" }`)
  * @returns A StandardJSONSchemaV1-compatible object that Goke can use for coercion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goke",
-  "version": "6.6.0",
+  "version": "6.6.2",
   "type": "module",
   "description": "Simple yet powerful framework for building command-line apps. Inspired by cac.",
   "repository": {

package/src/coerce.ts

@@ -127,13 +127,37 @@ export declare namespace StandardJSONSchemaV1 {
 /**
  * Wraps a plain JSON Schema object into a StandardJSONSchemaV1-compatible object.
  *
- * @internal This is an internal helper used by @goke/mcp to wrap MCP tool schemas.
- * Users should pass Zod or other StandardSchema-compatible schemas to `.option()`.
+ * Originally built for @goke/mcp to wrap MCP tool schemas, but also useful for
+ * any consumer that has a hand-written JSON Schema (e.g. an array of strings
+ * or a tagged union) and wants goke's `.action()` callback to infer the right
+ * option type without reaching for Zod. Pass an explicit `Output` type
+ * parameter to tell TypeScript what the coerced value will look like at
+ * runtime — goke does not validate the output shape, it just propagates it
+ * into the inferred options type for `.action()` callbacks.
+ *
+ * @example
+ * ```ts
+ * cli
+ *   .command('diff', 'Show diff')
+ *   .option(
+ *     '--filter <glob>',
+ *     wrapJsonSchema<string[]>({
+ *       type: 'array',
+ *       items: { type: 'string' },
+ *       description: 'Glob pattern (repeatable)',
+ *     }),
+ *   )
+ *   .action((options) => {
+ *     // options.filter: string[] | undefined
+ *   })
+ * ```
  *
  * @param jsonSchema - A plain JSON Schema object (e.g. `{ type: "number" }`)
  * @returns A StandardJSONSchemaV1-compatible object that Goke can use for coercion
  */
-export function wrapJsonSchema(jsonSchema: Record<string, unknown>): StandardJSONSchemaV1 {
+export function wrapJsonSchema<Output = unknown>(
+  jsonSchema: Record<string, unknown>,
+): StandardJSONSchemaV1<unknown, Output> {
   return {
     "~standard": {
       version: 1,