@runa-cmd/completions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Runa CLI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# @runa-cmd/completions
+
+Auto-generate shell completion scripts for any Runa CLI. One command, three shells — bash, zsh, and fish.
+
+Your Zod schema is the source of truth: enum values become completion candidates, commands and subcommands get tab-completed, and option flags (including `--no-*` booleans) work out of the box.
+
+## Install
+
+```bash
+pnpm add @runa-cmd/completions
+```
+
+> Peer dependencies: `@runa-cmd/core` and `zod ^4.0.0`.
+> Zero runtime dependencies.
+
+## Quick Start
+
+```ts
+import { defineCLI, defineCommand } from '@runa-cmd/core';
+import { z } from '@runa-cmd/core/zod';
+import { completionsPlugin } from '@runa-cmd/completions';
+
+const deploy = defineCommand({
+  meta: { name: 'deploy', description: 'Deploy a service' },
+  options: {
+    env: z.enum(['staging', 'production']).describe('Target environment'),
+  },
+  run({ options }) {
+    console.log(`Deploying to ${options.env}...`);
+  },
+});
+
+const cli = defineCLI({
+  meta: { name: 'my-tool', version: '1.0.0' },
+  commands: { deploy },
+  plugins: [completionsPlugin()],
+});
+
+cli.run();
+```
+
+```bash
+# Generate and install bash completions
+$ my-tool completions bash > ~/.local/share/bash-completion/completions/my-tool
+
+# Or get install instructions
+$ my-tool completions bash --instructions
+
+# Tab-complete in action
+$ my-tool d<TAB>         → deploy
+$ my-tool deploy --e<TAB> → --env
+$ my-tool deploy --env <TAB> → staging  production
+```
+
+## Supported Shells
+
+| Shell | Script Type | Features |
+|---|---|---|
+| **Bash** | `complete -F` with `compgen` | Commands, subcommands, options, enum values, `--no-*` booleans |
+| **Zsh** | `_arguments -C` with state dispatch | Same + grouped option specs with descriptions |
+| **Fish** | `complete -c` directives | Same + native condition-based filtering |
+
+## How It Works
+
+1. The plugin registers a `completions` command with `addCommands` capability
+2. The command takes a positional `shell` arg (`bash`, `zsh`, or `fish`)
+3. On execution, it introspects the CLI schema via `api.getSchema()`
+4. A shell-specific generator produces a self-contained completion script
+5. The script is written to stdout — pipe it to a file or eval it
+
+### What Gets Completed
+
+| Element | Example | Completed? |
+|---|---|---|
+| Top-level commands | `my-tool de<TAB>` → `deploy` | ✅ |
+| Nested subcommands | `my-tool config g<TAB>` → `get` | ✅ |
+| Long options | `my-tool deploy --e<TAB>` → `--env` | ✅ |
+| Short aliases | `my-tool deploy -e<TAB>` | ✅ |
+| Boolean negation | `my-tool --no-<TAB>` → `--no-color` | ✅ |
+| Enum values | `--env <TAB>` → `staging production` | ✅ |
+| Command descriptions | Shown in zsh/fish completions | ✅ |
+
+## API
+
+### `completionsPlugin(options?)`
+
+Creates the completions plugin. Returns a `PluginConfig` compatible with `defineCLI`.
+
+```ts
+import { completionsPlugin } from '@runa-cmd/completions';
+
+completionsPlugin({
+  commandName: 'complete', // Override command name (default: 'completions')
+});
+```
+
+### `CompletionsPluginOptions`
+
+```ts
+interface CompletionsPluginOptions {
+  commandName?: string; // Override the command name (default: 'completions')
+}
+```
+
+### Direct Generator Functions
+
+For advanced use cases (custom output, testing, etc.), the generators are exported directly:
+
+```ts
+import {
+  generateBashCompletions,
+  generateZshCompletions,
+  generateFishCompletions,
+} from '@runa-cmd/completions';
+
+// schema: CLISchema from api.getSchema()
+const bashScript = generateBashCompletions(schema, 'my-tool');
+const zshScript = generateZshCompletions(schema, 'my-tool');
+const fishScript = generateFishCompletions(schema, 'my-tool');
+```
+
+### `getInstallInstructions(shell, binName)`
+
+Returns shell-specific install instructions as a string:
+
+```ts
+import { getInstallInstructions } from '@runa-cmd/completions';
+
+console.log(getInstallInstructions('bash', 'my-tool'));
+// # Bash completions for my-tool
+// #
+// # Option 1: Add to your .bashrc (loads on every shell start)
+// #   echo 'eval "$(my-tool completions bash)"' >> ~/.bashrc
+// ...
+```
+
+## Install Instructions by Shell
+
+### Bash
+
+```bash
+# Option 1: Source in .bashrc
+echo 'eval "$(my-tool completions bash)"' >> ~/.bashrc
+
+# Option 2: Save to bash-completion directory (recommended)
+my-tool completions bash > ~/.local/share/bash-completion/completions/my-tool
+```
+
+### Zsh
+
+```bash
+# Save to a completions directory in your fpath
+mkdir -p ~/.zsh/completions
+my-tool completions zsh > ~/.zsh/completions/_my-tool
+
+# Add to .zshrc (before compinit):
+#   fpath=(~/.zsh/completions $fpath)
+#   autoload -Uz compinit && compinit
+```
+
+### Fish
+
+```bash
+# Save to fish completions directory (auto-loaded)
+my-tool completions fish > ~/.config/fish/completions/my-tool.fish
+```
+
+## With Other Plugins
+
+Completions work alongside help and MCP — just add all plugins:
+
+```ts
+import { helpPlugin } from '@runa-cmd/help';
+import { mcpPlugin } from '@runa-cmd/mcp';
+import { completionsPlugin } from '@runa-cmd/completions';
+
+const cli = defineCLI({
+  meta: { name: 'my-tool', version: '1.0.0' },
+  commands: { deploy, init },
+  plugins: [helpPlugin(), mcpPlugin(), completionsPlugin()],
+});
+```
+
+```bash
+$ my-tool --help              # Human-readable help
+$ my-tool --mcp               # MCP server for AI agents
+$ my-tool completions bash    # Shell completions script
+```
+
+## Shell Escaping
+
+All values (command names, descriptions, enum values) are properly escaped for each shell context:
+
+| Shell | Escaping Strategy |
+|---|---|
+| Bash | Single-quote context: `'` → `'\''` |
+| Zsh | Same as bash |
+| Fish | `'` → `\'`, `\` → `\\` |
+
+Descriptions are truncated to 80 characters and newlines are collapsed to spaces.
+
+## Architecture
+
+```
+completionsPlugin()
+    │
+    ├── plugin.ts          Runa plugin (adds completions command)
+    ├── generators/
+    │   ├── bash.ts        Bash completion script generator
+    │   ├── zsh.ts         Zsh completion script generator
+    │   ├── fish.ts        Fish completion script generator
+    │   └── escape.ts      Shell-specific string escaping
+    ├── install.ts         Install instruction templates
+    └── types.ts           Shell type and plugin options
+```
+
+Zero runtime dependencies. Everything is derived from `CLISchema` at generation time.
+
+## License
+
+MIT

package/dist/generators/bash.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @runa-cmd/completions — Bash completion script generator
+ *
+ * Generates a self-contained bash completion script from a CLISchema.
+ * Uses raw COMP_WORDS/COMP_CWORD — no dependency on bash-completion package.
+ */
+import type { CLISchema } from '@runa-cmd/core';
+/**
+ * Generate a complete bash completion script from a CLISchema.
+ *
+ * @param schema - Full CLI schema from api.getSchema()
+ * @param binName - The CLI binary name
+ * @returns Complete bash script as a string
+ */
+export declare function generateBashCompletions(schema: CLISchema, binName: string): string;
+//# sourceMappingURL=bash.d.ts.map

package/dist/generators/bash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../src/generators/bash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAA+B,MAAM,gBAAgB,CAAC;AAoG7E;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAkElF"}

package/dist/generators/bash.js

@@ -0,0 +1,155 @@
+/**
+ * @runa-cmd/completions — Bash completion script generator
+ *
+ * Generates a self-contained bash completion script from a CLISchema.
+ * Uses raw COMP_WORDS/COMP_CWORD — no dependency on bash-completion package.
+ */
+import { escapeBash } from './escape.js';
+/** Replace non-identifier characters with underscores */
+function safeName(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+/** Build --long option names for an option, including --no-* for booleans */
+function optionFlags(opt) {
+    const flags = [`--${opt.name}`];
+    if (opt.type === 'boolean') {
+        flags.push(`--no-${opt.name}`);
+    }
+    if (opt.alias) {
+        for (const a of opt.alias) {
+            flags.push(a);
+        }
+    }
+    return flags;
+}
+/** Build the list of all option flag strings for a command context */
+function buildOptWords(options, globalOptions) {
+    const all = [...options, ...globalOptions];
+    return all.flatMap(optionFlags).join(' ');
+}
+/** Build prev-matching case entries for enum options */
+function buildPrevCases(options, globalOptions) {
+    const lines = [];
+    const all = [...options, ...globalOptions];
+    for (const opt of all) {
+        if (opt.type === 'enum' && opt.enumValues?.length) {
+            const triggers = [`--${opt.name}`];
+            if (opt.alias) {
+                for (const a of opt.alias) {
+                    triggers.push(a);
+                }
+            }
+            const pattern = triggers.join('|');
+            const values = opt.enumValues.map((v) => escapeBash(v)).join(' ');
+            lines.push(`            ${pattern})`);
+            lines.push(`                COMPREPLY=($(compgen -W '${values}' -- "$cur"))`);
+            lines.push('                return ;;');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Recursively collect all case entries for the command tree.
+ * Each command becomes a case pattern based on its path.
+ */
+function collectCases(commands, globalOptions, prefix) {
+    const entries = [];
+    for (const cmd of commands) {
+        const path = prefix ? `${prefix}_${cmd.name}` : `_${cmd.name}`;
+        const optWords = buildOptWords(cmd.options, globalOptions);
+        const hasSubcmds = cmd.subcommands && cmd.subcommands.length > 0;
+        const subcmdNames = hasSubcmds ? (cmd.subcommands ?? []).map((s) => s.name).join(' ') : '';
+        const lines = [];
+        lines.push(`        "${path}")`);
+        // prev-matching for enum values in this command's context
+        const prevCases = buildPrevCases(cmd.options, globalOptions);
+        if (prevCases) {
+            lines.push('            case "$prev" in');
+            lines.push(prevCases);
+            lines.push('            esac');
+        }
+        if (hasSubcmds) {
+            lines.push('            if [[ "$cur" == -* ]]; then');
+            lines.push(`                COMPREPLY=($(compgen -W '${optWords}' -- "$cur"))`);
+            lines.push('            else');
+            lines.push(`                COMPREPLY=($(compgen -W '${subcmdNames}' -- "$cur"))`);
+            lines.push('            fi');
+        }
+        else {
+            lines.push('            if [[ "$cur" == -* ]]; then');
+            lines.push(`                COMPREPLY=($(compgen -W '${optWords}' -- "$cur"))`);
+            lines.push('            fi');
+        }
+        lines.push('            ;;');
+        entries.push(lines.join('\n'));
+        if (hasSubcmds) {
+            entries.push(...collectCases(cmd.subcommands ?? [], globalOptions, path));
+        }
+    }
+    return entries;
+}
+/**
+ * Generate a complete bash completion script from a CLISchema.
+ *
+ * @param schema - Full CLI schema from api.getSchema()
+ * @param binName - The CLI binary name
+ * @returns Complete bash script as a string
+ */
+export function generateBashCompletions(schema, binName) {
+    const funcName = `_${safeName(binName)}_completions`;
+    const { commands, globalOptions } = schema;
+    const globalOptWords = globalOptions.flatMap(optionFlags).join(' ');
+    const topCmdNames = commands.map((c) => c.name).join(' ');
+    // Top-level prev cases for global enum options
+    const topPrevCases = buildPrevCases([], globalOptions);
+    // Nested command cases
+    const cmdCases = collectCases(commands, globalOptions, '');
+    // Build the top-level option words (commands' options don't apply here)
+    const topOptWords = globalOptWords;
+    const lines = [];
+    lines.push('#!/usr/bin/env bash');
+    lines.push(`# Bash completions for ${escapeBash(binName)}`);
+    lines.push('# Generated by @runa-cmd/completions');
+    lines.push('');
+    lines.push(`${funcName}() {`);
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: these are bash variables, not JS template literals
+    lines.push('    local cur="${COMP_WORDS[COMP_CWORD]}"');
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: bash variable
+    lines.push('    local prev="${COMP_WORDS[COMP_CWORD-1]}"');
+    lines.push('');
+    lines.push('    # Build command path from COMP_WORDS');
+    lines.push('    local cmd_path=""');
+    lines.push('    local i=1');
+    lines.push('    while [[ $i -lt $COMP_CWORD ]]; do');
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: bash variable
+    lines.push('        case "${COMP_WORDS[i]}" in');
+    lines.push('            -*) ;;');
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: bash variable
+    lines.push('            *) cmd_path="${cmd_path}_${COMP_WORDS[i]}" ;;');
+    lines.push('        esac');
+    lines.push('        ((i++))');
+    lines.push('    done');
+    lines.push('');
+    lines.push('    case "$cmd_path" in');
+    lines.push('        "")');
+    // Top-level prev cases
+    if (topPrevCases) {
+        lines.push('            case "$prev" in');
+        lines.push(topPrevCases);
+        lines.push('            esac');
+    }
+    lines.push('            if [[ "$cur" == -* ]]; then');
+    lines.push(`                COMPREPLY=($(compgen -W '${topOptWords}' -- "$cur"))`);
+    lines.push('            else');
+    lines.push(`                COMPREPLY=($(compgen -W '${topCmdNames}' -- "$cur"))`);
+    lines.push('            fi');
+    lines.push('            ;;');
+    for (const entry of cmdCases) {
+        lines.push(entry);
+    }
+    lines.push('    esac');
+    lines.push('}');
+    lines.push(`complete -F ${funcName} ${binName}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=bash.js.map

package/dist/generators/bash.js.map

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

package/dist/generators/escape.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @runa-cmd/completions — Shell escape helpers
+ *
+ * Per-shell escape functions for safely embedding strings in generated
+ * completion scripts. Each function handles the quoting rules of its
+ * target shell. Descriptions are truncated to 80 chars.
+ */
+/**
+ * Escape a string for embedding in a single-quoted bash context.
+ *
+ * In bash single quotes, the ONLY special character is `'` itself.
+ * We end the current quote, insert an escaped quote, and restart: `'\''`
+ */
+export declare function escapeBash(str: string): string;
+/**
+ * Escape a string for embedding in a single-quoted zsh context.
+ *
+ * Zsh single-quote escaping is identical to bash: `'\''`
+ */
+export declare function escapeZsh(str: string): string;
+/**
+ * Escape a string for embedding in a single-quoted fish context.
+ *
+ * Fish uses backslash escaping inside single quotes:
+ * - `\` → `\\`
+ * - `'` → `\'`
+ */
+export declare function escapeFish(str: string): string;
+//# sourceMappingURL=escape.d.ts.map

package/dist/generators/escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../../src/generators/escape.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/generators/escape.js

@@ -0,0 +1,43 @@
+/**
+ * @runa-cmd/completions — Shell escape helpers
+ *
+ * Per-shell escape functions for safely embedding strings in generated
+ * completion scripts. Each function handles the quoting rules of its
+ * target shell. Descriptions are truncated to 80 chars.
+ */
+const MAX_DESC_LENGTH = 80;
+/** Truncate and collapse newlines for safe embedding */
+function sanitize(str) {
+    const collapsed = str.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= MAX_DESC_LENGTH)
+        return collapsed;
+    return `${collapsed.slice(0, MAX_DESC_LENGTH - 1)}\u2026`;
+}
+/**
+ * Escape a string for embedding in a single-quoted bash context.
+ *
+ * In bash single quotes, the ONLY special character is `'` itself.
+ * We end the current quote, insert an escaped quote, and restart: `'\''`
+ */
+export function escapeBash(str) {
+    return sanitize(str).replace(/'/g, "'\\''");
+}
+/**
+ * Escape a string for embedding in a single-quoted zsh context.
+ *
+ * Zsh single-quote escaping is identical to bash: `'\''`
+ */
+export function escapeZsh(str) {
+    return sanitize(str).replace(/'/g, "'\\''");
+}
+/**
+ * Escape a string for embedding in a single-quoted fish context.
+ *
+ * Fish uses backslash escaping inside single quotes:
+ * - `\` → `\\`
+ * - `'` → `\'`
+ */
+export function escapeFish(str) {
+    return sanitize(str).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+//# sourceMappingURL=escape.js.map

package/dist/generators/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../../src/generators/escape.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B,wDAAwD;AACxD,SAAS,QAAQ,CAAC,GAAW;IAC5B,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACtE,IAAI,SAAS,CAAC,MAAM,IAAI,eAAe;QAAE,OAAO,SAAS,CAAC;IAC1D,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,CAAC,QAAQ,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACrC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACrC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAClE,CAAC"}

package/dist/generators/fish.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @runa-cmd/completions — Fish completion script generator
+ *
+ * Generates fish completions as a flat list of `complete` directives.
+ * Uses __fish_use_subcommand and __fish_seen_subcommand_from for context.
+ */
+import type { CLISchema } from '@runa-cmd/core';
+/**
+ * Generate a complete fish completion script from a CLISchema.
+ *
+ * @param schema - Full CLI schema from api.getSchema()
+ * @param binName - The CLI binary name
+ * @returns Complete fish script as a string
+ */
+export declare function generateFishCompletions(schema: CLISchema, binName: string): string;
+//# sourceMappingURL=fish.d.ts.map

package/dist/generators/fish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fish.d.ts","sourceRoot":"","sources":["../../src/generators/fish.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAA+B,MAAM,gBAAgB,CAAC;AA4E7E;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA4BlF"}

package/dist/generators/fish.js

@@ -0,0 +1,86 @@
+/**
+ * @runa-cmd/completions — Fish completion script generator
+ *
+ * Generates fish completions as a flat list of `complete` directives.
+ * Uses __fish_use_subcommand and __fish_seen_subcommand_from for context.
+ */
+import { escapeFish } from './escape.js';
+/** Generate complete directives for a single option */
+function optionDirectives(binName, opt, condition) {
+    const lines = [];
+    const desc = opt.description ? ` -d '${escapeFish(opt.description)}'` : '';
+    const shortAlias = opt.alias?.find((a) => a.startsWith('-') && !a.startsWith('--'));
+    const shortFlag = shortAlias ? ` -s ${shortAlias.replace(/^-/, '')}` : '';
+    const condPart = condition ? ` -n '${condition}'` : '';
+    if (opt.type === 'boolean') {
+        // Boolean flags don't take values — no -r
+        lines.push(`complete -c ${binName}${condPart}` + ` -l ${opt.name}${shortFlag}${desc}`);
+        // --no-* variant
+        lines.push(`complete -c ${binName}${condPart}` + ` -l no-${opt.name}${desc}`);
+    }
+    else if (opt.type === 'enum' && opt.enumValues?.length) {
+        const vals = opt.enumValues.map((v) => escapeFish(v)).join(' ');
+        lines.push(`complete -c ${binName}${condPart}` +
+            ` -l ${opt.name}${shortFlag}${desc}` +
+            ` -r -a '${vals}'`);
+    }
+    else {
+        // string, number, array — require argument
+        lines.push(`complete -c ${binName}${condPart}` + ` -l ${opt.name}${shortFlag}${desc} -r`);
+    }
+    return lines;
+}
+/**
+ * Recursively generate complete directives for commands.
+ */
+function generateCommandDirectives(binName, commands, globalOptions, parentCondition, _parentName) {
+    const lines = [];
+    for (const cmd of commands) {
+        const desc = cmd.description ? ` -d '${escapeFish(cmd.description)}'` : '';
+        // Command itself
+        lines.push(`complete -c ${binName}` +
+            ` -n '${parentCondition}'` +
+            ` -a '${escapeFish(cmd.name)}'${desc}`);
+        // Command options
+        const cmdCondition = `__fish_seen_subcommand_from ${cmd.name}`;
+        for (const opt of cmd.options) {
+            lines.push(...optionDirectives(binName, opt, cmdCondition));
+        }
+        // Subcommands
+        if (cmd.subcommands && cmd.subcommands.length > 0) {
+            lines.push(...generateCommandDirectives(binName, cmd.subcommands, globalOptions, cmdCondition, cmd.name));
+        }
+    }
+    return lines;
+}
+/**
+ * Generate a complete fish completion script from a CLISchema.
+ *
+ * @param schema - Full CLI schema from api.getSchema()
+ * @param binName - The CLI binary name
+ * @returns Complete fish script as a string
+ */
+export function generateFishCompletions(schema, binName) {
+    const { commands, globalOptions } = schema;
+    const lines = [];
+    lines.push(`# Fish completions for ${escapeFish(binName)}`);
+    lines.push('# Generated by @runa-cmd/completions');
+    lines.push('');
+    lines.push(`complete -c ${binName} -f`);
+    lines.push('');
+    // Global options (no condition — available everywhere)
+    if (globalOptions.length > 0) {
+        lines.push('# Global options');
+        for (const opt of globalOptions) {
+            lines.push(...optionDirectives(binName, opt, ''));
+        }
+        lines.push('');
+    }
+    // Commands
+    if (commands.length > 0) {
+        lines.push('# Commands');
+        lines.push(...generateCommandDirectives(binName, commands, globalOptions, '__fish_use_subcommand', null));
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=fish.js.map

package/dist/generators/fish.js.map

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

package/dist/generators/zsh.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @runa-cmd/completions — Zsh completion script generator
+ *
+ * Generates a zsh completion script using _arguments -C with state
+ * machine dispatch. One function per command level.
+ */
+import type { CLISchema } from '@runa-cmd/core';
+/**
+ * Generate a complete zsh completion script from a CLISchema.
+ *
+ * @param schema - Full CLI schema from api.getSchema()
+ * @param binName - The CLI binary name
+ * @returns Complete zsh script as a string
+ */
+export declare function generateZshCompletions(schema: CLISchema, binName: string): string;
+//# sourceMappingURL=zsh.d.ts.map

package/dist/generators/zsh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zsh.d.ts","sourceRoot":"","sources":["../../src/generators/zsh.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAA+B,MAAM,gBAAgB,CAAC;AAkI7E;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA0DjF"}

package/dist/generators/zsh.js

@@ -0,0 +1,180 @@
+/**
+ * @runa-cmd/completions — Zsh completion script generator
+ *
+ * Generates a zsh completion script using _arguments -C with state
+ * machine dispatch. One function per command level.
+ */
+import { escapeZsh } from './escape.js';
+/** Replace non-identifier characters with underscores */
+function safeName(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+/** Format an option spec for _arguments */
+function formatOptionSpec(opt) {
+    const specs = [];
+    const desc = opt.description ? escapeZsh(opt.description) : '';
+    const shortAlias = opt.alias?.find((a) => a.startsWith('-') && !a.startsWith('--'));
+    if (opt.type === 'boolean') {
+        // Boolean with alias
+        if (shortAlias) {
+            specs.push(`'(${shortAlias} --${opt.name})'` + `{${shortAlias},--${opt.name}}` + `'[${desc}]'`);
+            specs.push(`'--no-${opt.name}[${desc}]'`);
+        }
+        else {
+            specs.push(`'--${opt.name}[${desc}]'`);
+            specs.push(`'--no-${opt.name}[${desc}]'`);
+        }
+    }
+    else if (opt.type === 'enum' && opt.enumValues?.length) {
+        const vals = opt.enumValues.map((v) => escapeZsh(v)).join(' ');
+        if (shortAlias) {
+            specs.push(`'(${shortAlias} --${opt.name})'` +
+                `{${shortAlias},--${opt.name}}` +
+                `'[${desc}]:${opt.name}:(${vals})'`);
+        }
+        else {
+            specs.push(`'--${opt.name}[${desc}]` + `:${opt.name}:(${vals})'`);
+        }
+    }
+    else {
+        // string, number, array — require value but no candidates
+        if (shortAlias) {
+            specs.push(`'(${shortAlias} --${opt.name})'` +
+                `{${shortAlias},--${opt.name}}` +
+                `'[${desc}]:${opt.name}:'`);
+        }
+        else {
+            specs.push(`'--${opt.name}[${desc}]` + `:${opt.name}:'`);
+        }
+    }
+    return specs;
+}
+/** Build _arguments option specs for a list of options */
+function buildArgSpecs(options, globalOptions) {
+    const all = [...globalOptions, ...options];
+    return all.flatMap(formatOptionSpec);
+}
+/**
+ * Recursively generate zsh functions for a command tree.
+ * Returns an array of function definition strings.
+ */
+function generateCommandFunctions(commands, globalOptions, parentFunc) {
+    const blocks = [];
+    for (const cmd of commands) {
+        const funcName = `${parentFunc}_${safeName(cmd.name)}`;
+        const hasSubcmds = cmd.subcommands && cmd.subcommands.length > 0;
+        const argSpecs = buildArgSpecs(cmd.options, globalOptions);
+        const lines = [];
+        lines.push(`${funcName}() {`);
+        if (hasSubcmds) {
+            lines.push('    local -a commands');
+            lines.push('    local state line');
+            lines.push('');
+            lines.push('    _arguments -C \\');
+            for (const spec of argSpecs) {
+                lines.push(`        ${spec} \\`);
+            }
+            lines.push("        '1:command:->cmds' \\");
+            lines.push("        '*::arg:->args'");
+            lines.push('');
+            lines.push('    case "$state" in');
+            lines.push('        cmds)');
+            lines.push('            commands=(');
+            for (const sub of cmd.subcommands ?? []) {
+                const d = sub.description ? escapeZsh(sub.description) : '';
+                lines.push(`                '${escapeZsh(sub.name)}:${d}'`);
+            }
+            lines.push('            )');
+            lines.push("            _describe 'command' commands");
+            lines.push('            ;;');
+            lines.push('        args)');
+            lines.push('            case "$line[1]" in');
+            for (const sub of cmd.subcommands ?? []) {
+                lines.push(`                ${sub.name})`);
+                lines.push(`                    ${funcName}_${safeName(sub.name)}`);
+                lines.push('                    ;;');
+            }
+            lines.push('            esac');
+            lines.push('            ;;');
+            lines.push('    esac');
+        }
+        else {
+            // Leaf command — just _arguments with options
+            if (argSpecs.length > 0) {
+                lines.push('    _arguments \\');
+                for (let i = 0; i < argSpecs.length; i++) {
+                    const suffix = i < argSpecs.length - 1 ? ' \\' : '';
+                    lines.push(`        ${argSpecs[i]}${suffix}`);
+                }
+            }
+        }
+        lines.push('}');
+        blocks.push(lines.join('\n'));
+        // Recurse into subcommands
+        if (hasSubcmds) {
+            blocks.push(...generateCommandFunctions(cmd.subcommands ?? [], globalOptions, funcName));
+        }
+    }
+    return blocks;
+}
+/**
+ * Generate a complete zsh completion script from a CLISchema.
+ *
+ * @param schema - Full CLI schema from api.getSchema()
+ * @param binName - The CLI binary name
+ * @returns Complete zsh script as a string
+ */
+export function generateZshCompletions(schema, binName) {
+    const funcName = `_${safeName(binName)}`;
+    const { commands, globalOptions } = schema;
+    const globalArgSpecs = buildArgSpecs([], globalOptions);
+    const lines = [];
+    lines.push(`#compdef ${binName}`);
+    lines.push(`# Zsh completions for ${escapeZsh(binName)}`);
+    lines.push('# Generated by @runa-cmd/completions');
+    lines.push('');
+    // Main function
+    lines.push(`${funcName}() {`);
+    lines.push('    local -a commands');
+    lines.push('    local state line');
+    lines.push('');
+    lines.push('    _arguments -C \\');
+    for (const spec of globalArgSpecs) {
+        lines.push(`        ${spec} \\`);
+    }
+    lines.push("        '1:command:->cmds' \\");
+    lines.push("        '*::arg:->args'");
+    lines.push('');
+    lines.push('    case "$state" in');
+    lines.push('        cmds)');
+    lines.push('            commands=(');
+    for (const cmd of commands) {
+        const d = cmd.description ? escapeZsh(cmd.description) : '';
+        lines.push(`                '${escapeZsh(cmd.name)}:${d}'`);
+    }
+    lines.push('            )');
+    lines.push("            _describe 'command' commands");
+    lines.push('            ;;');
+    lines.push('        args)');
+    lines.push('            case "$line[1]" in');
+    for (const cmd of commands) {
+        lines.push(`                ${cmd.name})`);
+        lines.push(`                    ${funcName}_${safeName(cmd.name)}`);
+        lines.push('                    ;;');
+    }
+    lines.push('            esac');
+    lines.push('            ;;');
+    lines.push('    esac');
+    lines.push('}');
+    lines.push('');
+    // Command functions
+    const cmdFuncs = generateCommandFunctions(commands, globalOptions, funcName);
+    for (const fn of cmdFuncs) {
+        lines.push(fn);
+        lines.push('');
+    }
+    // Call the main function
+    lines.push(funcName);
+    return lines.join('\n');
+}
+//# sourceMappingURL=zsh.js.map

package/dist/generators/zsh.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @runa-cmd/completions — Public API
+ *
+ * Barrel re-exports for the completions plugin package.
+ */
+export { generateBashCompletions } from './generators/bash.js';
+export { generateFishCompletions } from './generators/fish.js';
+export { generateZshCompletions } from './generators/zsh.js';
+export { getInstallInstructions } from './install.js';
+export { completionsPlugin } from './plugin.js';
+export type { CompletionsPluginOptions, Shell } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,YAAY,EAAE,wBAAwB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @runa-cmd/completions — Public API
+ *
+ * Barrel re-exports for the completions plugin package.
+ */
+// Generators (for advanced use / direct invocation)
+export { generateBashCompletions } from './generators/bash.js';
+export { generateFishCompletions } from './generators/fish.js';
+export { generateZshCompletions } from './generators/zsh.js';
+// Install instructions
+export { getInstallInstructions } from './install.js';
+// Plugin
+export { completionsPlugin } from './plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oDAAoD;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,uBAAuB;AACvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,SAAS;AACT,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/install.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @runa-cmd/completions — Install instructions
+ *
+ * Returns shell-specific installation instructions for the
+ * generated completion scripts.
+ */
+import type { Shell } from './types.js';
+/**
+ * Get shell-specific installation instructions for the completion script.
+ *
+ * @param shell - Target shell
+ * @param binName - CLI binary name
+ * @returns Multi-line instruction string
+ */
+export declare function getInstallInstructions(shell: Shell, binName: string): string;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAS5E"}

package/dist/install.js

@@ -0,0 +1,73 @@
+/**
+ * @runa-cmd/completions — Install instructions
+ *
+ * Returns shell-specific installation instructions for the
+ * generated completion scripts.
+ */
+/**
+ * Get shell-specific installation instructions for the completion script.
+ *
+ * @param shell - Target shell
+ * @param binName - CLI binary name
+ * @returns Multi-line instruction string
+ */
+export function getInstallInstructions(shell, binName) {
+    switch (shell) {
+        case 'bash':
+            return getBashInstructions(binName);
+        case 'zsh':
+            return getZshInstructions(binName);
+        case 'fish':
+            return getFishInstructions(binName);
+    }
+}
+function getBashInstructions(binName) {
+    return `# Bash completions for ${binName}
+#
+# Option 1: Add to your .bashrc (loads on every shell start)
+#
+#   echo 'eval "$(${binName} completions bash)"' >> ~/.bashrc
+#
+# Option 2: Save to bash-completion directory (recommended)
+#
+#   ${binName} completions bash > ~/.local/share/bash-completion/completions/${binName}
+#
+# Then restart your shell or run:
+#
+#   source ~/.bashrc
+`;
+}
+function getZshInstructions(binName) {
+    return `# Zsh completions for ${binName}
+#
+# Option 1: Save to a completions directory in your fpath
+#
+#   mkdir -p ~/.zsh/completions
+#   ${binName} completions zsh > ~/.zsh/completions/_${binName}
+#
+#   Then add to your .zshrc (before compinit):
+#
+#     fpath=(~/.zsh/completions $fpath)
+#     autoload -Uz compinit && compinit
+#
+# Option 2: Add to your .zshrc directly
+#
+#   echo 'eval "$(${binName} completions zsh)"' >> ~/.zshrc
+#
+# Then restart your shell or run:
+#
+#   source ~/.zshrc
+`;
+}
+function getFishInstructions(binName) {
+    return `# Fish completions for ${binName}
+#
+# Save to fish completions directory (auto-loaded by convention):
+#
+#   ${binName} completions fish > ~/.config/fish/completions/${binName}.fish
+#
+# Fish automatically loads completions from this directory.
+# No additional configuration needed.
+`;
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAY,EAAE,OAAe;IACnE,QAAQ,KAAK,EAAE,CAAC;QACf,KAAK,MAAM;YACV,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACrC,KAAK,KAAK;YACT,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACpC,KAAK,MAAM;YACV,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;AACF,CAAC;AAED,SAAS,mBAAmB,CAAC,OAAe;IAC3C,OAAO,0BAA0B,OAAO;;;;oBAIrB,OAAO;;;;MAIrB,OAAO,kEAAkE,OAAO;;;;;CAKrF,CAAC;AACF,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAe;IAC1C,OAAO,yBAAyB,OAAO;;;;;MAKlC,OAAO,0CAA0C,OAAO;;;;;;;;;oBAS1C,OAAO;;;;;CAK1B,CAAC;AACF,CAAC;AAED,SAAS,mBAAmB,CAAC,OAAe;IAC3C,OAAO,0BAA0B,OAAO;;;;MAInC,OAAO,kDAAkD,OAAO;;;;CAIrE,CAAC;AACF,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @runa-cmd/completions — completionsPlugin()
+ *
+ * A Runa plugin that adds a `completions` command for generating
+ * shell completion scripts. Each shell (bash, zsh, fish) gets a
+ * self-contained script derived from the CLI's schema.
+ */
+import type { PluginConfig } from '@runa-cmd/core';
+import type { CompletionsPluginOptions } from './types.js';
+/**
+ * Create a completions plugin that adds a `completions` command.
+ *
+ * Usage:
+ *   mycli completions bash    → outputs bash completion script
+ *   mycli completions zsh     → outputs zsh completion script
+ *   mycli completions fish    → outputs fish completion script
+ *
+ * Add --instructions flag to get install instructions instead.
+ */
+export declare function completionsPlugin(opts?: CompletionsPluginOptions): PluginConfig;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAOnD,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,YAAY,CAAC;AAWlE;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,wBAA6B,GAAG,YAAY,CA0CnF"}

package/dist/plugin.js

@@ -0,0 +1,61 @@
+import { defineCommand, definePlugin } from '@runa-cmd/core';
+import { z } from 'zod';
+import { generateBashCompletions } from './generators/bash.js';
+import { generateFishCompletions } from './generators/fish.js';
+import { generateZshCompletions } from './generators/zsh.js';
+import { getInstallInstructions } from './install.js';
+const generators = {
+    bash: generateBashCompletions,
+    zsh: generateZshCompletions,
+    fish: generateFishCompletions,
+};
+/**
+ * Create a completions plugin that adds a `completions` command.
+ *
+ * Usage:
+ *   mycli completions bash    → outputs bash completion script
+ *   mycli completions zsh     → outputs zsh completion script
+ *   mycli completions fish    → outputs fish completion script
+ *
+ * Add --instructions flag to get install instructions instead.
+ */
+export function completionsPlugin(opts = {}) {
+    const commandName = opts.commandName ?? 'completions';
+    return definePlugin({
+        meta: {
+            name: '@runa-cmd/completions',
+            version: '0.1.0',
+            description: 'Shell completion script generation',
+        },
+        capabilities: { addCommands: true },
+        setup(api) {
+            const completionsCmd = defineCommand({
+                meta: {
+                    name: commandName,
+                    description: 'Generate shell completion script',
+                },
+                args: {
+                    shell: z.enum(['bash', 'zsh', 'fish']).describe('Target shell'),
+                },
+                options: {
+                    instructions: z
+                        .boolean()
+                        .optional()
+                        .default(false)
+                        .describe('Print install instructions instead of the script'),
+                },
+                run({ args, options }) {
+                    const schema = api.getSchema();
+                    const binName = schema.meta.name;
+                    if (options.instructions) {
+                        process.stdout.write(getInstallInstructions(args.shell, binName));
+                        return;
+                    }
+                    process.stdout.write(generators[args.shell](schema, binName));
+                },
+            });
+            api.addCommand(commandName, completionsCmd);
+        },
+    });
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAGtD,MAAM,UAAU,GAGZ;IACH,IAAI,EAAE,uBAAuB;IAC7B,GAAG,EAAE,sBAAsB;IAC3B,IAAI,EAAE,uBAAuB;CAC7B,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC,EAAE;IACpE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,aAAa,CAAC;IAEtD,OAAO,YAAY,CAAC;QACnB,IAAI,EAAE;YACL,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,OAAO;YAChB,WAAW,EAAE,oCAAoC;SACjD;QACD,YAAY,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;QACnC,KAAK,CAAC,GAAG;YACR,MAAM,cAAc,GAAG,aAAa,CAAC;gBACpC,IAAI,EAAE;oBACL,IAAI,EAAE,WAAW;oBACjB,WAAW,EAAE,kCAAkC;iBAC/C;gBACD,IAAI,EAAE;oBACL,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC;iBAC/D;gBACD,OAAO,EAAE;oBACR,YAAY,EAAE,CAAC;yBACb,OAAO,EAAE;yBACT,QAAQ,EAAE;yBACV,OAAO,CAAC,KAAK,CAAC;yBACd,QAAQ,CAAC,kDAAkD,CAAC;iBAC9D;gBACD,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE;oBACpB,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;oBAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;oBAEjC,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;wBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;wBAClE,OAAO;oBACR,CAAC;oBAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC/D,CAAC;aACD,CAAC,CAAC;YAEH,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QAC7C,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @runa-cmd/completions — Type definitions
+ *
+ * Plugin options and shell type for completionsPlugin().
+ */
+/** Supported shells for completion generation */
+export type Shell = 'bash' | 'zsh' | 'fish';
+/** Options for completionsPlugin() */
+export interface CompletionsPluginOptions {
+    /** Override the command name (default: 'completions') */
+    commandName?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iDAAiD;AACjD,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5C,sCAAsC;AACtC,MAAM,WAAW,wBAAwB;IACxC,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * @runa-cmd/completions — Type definitions
+ *
+ * Plugin options and shell type for completionsPlugin().
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@runa-cmd/completions",
+  "version": "0.1.0",
+  "description": "Shell completion script generation for Runa CLIs. Auto-generate bash, zsh, and fish completions from your Zod schemas.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "cli",
+    "completions",
+    "bash",
+    "zsh",
+    "fish",
+    "shell",
+    "tab-completion",
+    "runa"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "@runa-cmd/core": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jrodrigopuca/runa-cmd.git",
+    "directory": "packages/completions"
+  },
+  "homepage": "https://github.com/jrodrigopuca/runa-cmd/tree/main/packages/completions#readme",
+  "bugs": {
+    "url": "https://github.com/jrodrigopuca/runa-cmd/issues"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.2",
+    "zod": "^4.3.6",
+    "@runa-cmd/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "clean": "rm -rf dist"
+  }
+}