@camunda8/cli 2.8.0-alpha.1 → 2.8.0-alpha.11

package/dist/commands/completion.js

@@ -1,693 +1,14 @@
 /**
- * Shell completion commands — derived from COMMAND_REGISTRY + plugins.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir, platform } from "node:os";
-import { join } from "node:path";
-import { defineCommand } from "../command-framework.js";
-import { COMMAND_REGISTRY, GLOBAL_FLAGS, RESOURCE_ALIASES, } from "../command-registry.js";
-import { getUserDataDir } from "../config.js";
-import { getLogger } from "../logger.js";
-import { getPluginCommandsInfo, } from "../plugin-loader.js";
-import { c8ctl } from "../runtime.js";
-// ─── Typed helpers (same pattern as help.ts) ─────────────────────────────────
-/** Typed entries for COMMAND_REGISTRY — avoids per-loop casts. */
-function registryEntries() {
-    return Object.entries(COMMAND_REGISTRY);
-}
-/** Typed entries for a flag record — avoids per-loop casts. */
-function flagEntries(flags) {
-    return Object.entries(flags);
-}
-// ─── Derived completion data ─────────────────────────────────────────────────
-/** Reverse map: canonical resource → all names that resolve to it (including itself). */
-function buildCanonicalToAliases() {
-    const map = new Map();
-    // Seed with every known canonical name from the registry
-    for (const [, def] of registryEntries()) {
-        for (const r of def.resources) {
-            const canonical = RESOURCE_ALIASES[r] ?? r;
-            if (!map.has(canonical)) {
-                map.set(canonical, [canonical]);
-            }
-        }
-    }
-    // Add every alias
-    for (const [alias, canonical] of Object.entries(RESOURCE_ALIASES)) {
-        if (!map.has(canonical)) {
-            map.set(canonical, [canonical]);
-        }
-        const arr = map.get(canonical) ?? [];
-        if (!arr.includes(alias)) {
-            arr.push(alias);
-        }
-    }
-    return map;
-}
-/** All accepted forms for a verb's resources (canonical + all aliases). */
-function resourceFormsForVerb(def, canonicalToAliases) {
-    const seen = new Set();
-    for (const r of def.resources) {
-        const canonical = RESOURCE_ALIASES[r] ?? r;
-        for (const form of canonicalToAliases.get(canonical) ?? [canonical]) {
-            seen.add(form);
-        }
-    }
-    return [...seen];
-}
-function deriveVerbInfos(pluginCommandsInfo) {
-    const canonicalToAliases = buildCanonicalToAliases();
-    const infos = [];
-    for (const [verb, def] of registryEntries()) {
-        // Skip mcp-proxy — not a user-facing verb
-        if (verb === "mcp-proxy")
-            continue;
-        const resources = resourceFormsForVerb(def, canonicalToAliases);
-        const fileComplete = !def.requiresResource &&
-            def.resources.length === 0 &&
-            ["deploy", "run", "watch"].includes(verb);
-        infos.push({
-            verb,
-            description: def.description,
-            resources,
-            aliases: def.aliases ?? [],
-            fileComplete,
-        });
-    }
-    // Plugin-provided verbs (e.g. cluster)
-    for (const cmd of pluginCommandsInfo) {
-        // Skip if already in registry
-        if (cmd.commandName in COMMAND_REGISTRY)
-            continue;
-        infos.push({
-            verb: cmd.commandName,
-            description: cmd.description ?? "",
-            resources: (cmd.subcommands ?? []).map((s) => s.name),
-            aliases: [],
-            fileComplete: false,
-        });
-    }
-    return infos;
-}
-/** Collect all unique flag names across all commands + global + search flags. */
-function deriveAllFlagNames() {
-    const names = new Set();
-    for (const name of Object.keys(GLOBAL_FLAGS)) {
-        names.add(name);
-    }
-    for (const [, def] of registryEntries()) {
-        for (const [name] of flagEntries(def.flags)) {
-            names.add(name);
-        }
-        if (def.resourceFlags) {
-            for (const rf of Object.values(def.resourceFlags)) {
-                for (const name of Object.keys(rf)) {
-                    names.add(name);
-                }
-            }
-        }
-    }
-    return [...names].map((n) => `--${n}`);
-}
-/** Collect all flags with descriptions and types for rich completions (zsh/fish). */
-function deriveAllFlags() {
-    const seen = new Map();
-    function addFlags(flags) {
-        for (const [name, def] of flagEntries(flags)) {
-            if (!seen.has(name)) {
-                seen.set(name, {
-                    description: def.description,
-                    type: def.type,
-                    short: def.short,
-                });
-            }
-        }
-    }
-    addFlags(GLOBAL_FLAGS);
-    for (const [, def] of registryEntries()) {
-        addFlags(def.flags);
-        if (def.resourceFlags) {
-            for (const rf of Object.values(def.resourceFlags)) {
-                addFlags(rf);
-            }
-        }
-    }
-    return [...seen].map(([name, info]) => ({
-        name,
-        ...info,
-    }));
-}
-/** Get resources for the `help` verb: verbs with hasDetailedHelp + special topics. */
-function deriveHelpResources() {
-    const items = [];
-    for (const [verb, def] of registryEntries()) {
-        if (def.hasDetailedHelp) {
-            items.push({ name: verb, description: `Show ${verb} command help` });
-        }
-    }
-    // Special topics that aren't verbs but have help pages
-    items.push({
-        name: "profiles",
-        description: "Show profile management help",
-    }, {
-        name: "profile",
-        description: "Alias for profile management help",
-    }, {
-        name: "plugin",
-        description: "Show plugin management help",
-    }, {
-        name: "plugins",
-        description: "Alias for plugin management help",
-    });
-    // Plugin verbs
-    const pluginCmds = getPluginCommandsInfo();
-    for (const cmd of pluginCmds) {
-        if (!items.some((i) => i.name === cmd.commandName) &&
-            !(cmd.commandName in COMMAND_REGISTRY)) {
-            items.push({
-                name: cmd.commandName,
-                description: cmd.description
-                    ? `Show ${cmd.commandName} command help`
-                    : `No detailed help; use c8ctl help for general usage`,
-            });
-        }
-    }
-    return items;
-}
-// ─── Bash completion ─────────────────────────────────────────────────────────
-function generateBashCompletion() {
-    const pluginCmds = getPluginCommandsInfo();
-    const verbInfos = deriveVerbInfos(pluginCmds);
-    const allFlags = deriveAllFlagNames();
-    const helpResources = deriveHelpResources();
-    // All verb names (including aliases)
-    const allVerbs = new Set();
-    for (const v of verbInfos) {
-        allVerbs.add(v.verb);
-        for (const a of v.aliases)
-            allVerbs.add(a);
-    }
-    const verbsStr = [...allVerbs].join(" ");
-    const flagsStr = allFlags.join(" ");
-    // Build per-verb resource variables
-    const resourceVars = [];
-    const caseBranches = [];
-    for (const v of verbInfos) {
-        if (v.verb === "help") {
-            // Help completes to verbs/topics, not resources
-            resourceVars.push(`  local help_resources="${helpResources.map((r) => r.name).join(" ")}"`);
-            caseBranches.push(`        help)\n          COMPREPLY=( $(compgen -W "\${help_resources}" -- "\${cur}") )\n          ;;`);
-            continue;
-        }
-        if (v.fileComplete) {
-            // deploy/run/watch complete with files
-            caseBranches.push(`        ${v.verb})\n          COMPREPLY=( $(compgen -f -- "\${cur}") )\n          ;;`);
-            continue;
-        }
-        if (v.resources.length === 0)
-            continue;
-        const varName = `${v.verb.replace(/-/g, "_")}_resources`;
-        resourceVars.push(`  local ${varName}="${v.resources.join(" ")}"`);
-        // Include aliases in the case pattern
-        const casePattern = v.aliases.length > 0 ? `${v.verb}|${v.aliases.join("|")}` : v.verb;
-        caseBranches.push(`        ${casePattern})\n          COMPREPLY=( $(compgen -W "\${${varName}}" -- "\${cur}") )\n          ;;`);
-    }
-    return `# c8ctl-completion-version: ${c8ctl.version}
-# c8ctl bash completion
-_c8ctl_completions() {
-  local cur prev words cword
-  
-  # Initialize completion variables (standalone, no bash-completion dependency)
-  COMPREPLY=()
-  cur="\${COMP_WORDS[COMP_CWORD]}"
-  prev="\${COMP_WORDS[COMP_CWORD-1]}"
-  words=("\${COMP_WORDS[@]}")
-  cword=\${COMP_CWORD}
-
-  # Commands (verbs)
-  local verbs="${verbsStr}"
-  
-  # Resources by verb
-${resourceVars.join("\n")}
-
-  # Global flags
-  local flags="${flagsStr}"
-
-  case \${cword} in
-    1)
-      # Complete verbs
-      COMPREPLY=( $(compgen -W "\${verbs}" -- "\${cur}") )
-      ;;
-    2)
-      # Complete resources based on verb
-      local verb="\${words[1]}"
-      case "\${verb}" in
-${caseBranches.join("\n")}
-      esac
-      ;;
-    *)
-      # Complete flags or files
-      if [[ \${cur} == -* ]]; then
-        COMPREPLY=( $(compgen -W "\${flags}" -- "\${cur}") )
-      else
-        COMPREPLY=( $(compgen -f -- "\${cur}") )
-      fi
-      ;;
-  esac
-}
-
-complete -F _c8ctl_completions c8ctl
-complete -F _c8ctl_completions c8
-`;
-}
-// ─── Zsh completion ──────────────────────────────────────────────────────────
-function generateZshCompletion() {
-    const pluginCmds = getPluginCommandsInfo();
-    const verbInfos = deriveVerbInfos(pluginCmds);
-    const allFlags = deriveAllFlags();
-    const helpResources = deriveHelpResources();
-    // Verb entries: 'verb:description'
-    const verbEntries = verbInfos.map((v) => {
-        const items = [`    '${v.verb}:${escZsh(v.description)}'`];
-        for (const a of v.aliases) {
-            items.push(`    '${a}:${escZsh(v.description)}'`);
-        }
-        return items.join("\n");
-    });
-    // Flag entries: '--flag[description]:hint:' or '--flag[description]'
-    const flagEntryLines = allFlags.map((f) => {
-        const desc = escZsh(f.description);
-        if (f.short) {
-            return `    '-${f.short}[${desc}]'\n    '--${f.name}[${desc}]${f.type === "string" ? `:${f.name}:` : ""}'`;
-        }
-        return `    '--${f.name}[${desc}]${f.type === "string" ? `:${f.name}:` : ""}'`;
-    });
-    // Per-verb resource case branches
-    const resourceCases = [];
-    for (const v of verbInfos) {
-        if (v.verb === "help") {
-            const entries = helpResources.map((r) => `            '${r.name}:${escZsh(r.description)}'`);
-            resourceCases.push(`        help)\n          resources=(\n${entries.join("\n")}\n          )\n          _describe 'resource' resources\n          ;;`);
-            continue;
-        }
-        if (v.fileComplete) {
-            const casePattern = v.aliases.length > 0 ? `${v.verb}|${v.aliases.join("|")}` : v.verb;
-            resourceCases.push(`        ${casePattern})\n          _files\n          ;;`);
-            continue;
-        }
-        if (v.resources.length === 0)
-            continue;
-        const entries = v.resources.map((r) => `            '${r}:${escZsh(capitalize(v.verb))} ${resourceDisplayName(r)}'`);
-        const casePattern = v.aliases.length > 0 ? `${v.verb}|${v.aliases.join("|")}` : v.verb;
-        resourceCases.push(`        ${casePattern})\n          resources=(\n${entries.join("\n")}\n          )\n          _describe 'resource' resources\n          ;;`);
-    }
-    return `#compdef c8ctl c8
-# c8ctl-completion-version: ${c8ctl.version}
-
-_c8ctl() {
-  local -a verbs resources flags
-
-  verbs=(
-${verbEntries.join("\n")}
-  )
-
-  flags=(
-${flagEntryLines.join("\n")}
-  )
-
-  case $CURRENT in
-    2)
-      _describe 'command' verbs
-      ;;
-    3)
-      case "\${words[2]}" in
-${resourceCases.join("\n")}
-      esac
-      ;;
-    *)
-      _arguments \${flags[@]}
-      ;;
-  esac
-}
-
-if (( $+functions[compdef] )); then
-  compdef _c8ctl c8ctl c8
-fi
-`;
-}
-// ─── Fish completion ─────────────────────────────────────────────────────────
-function generateFishCompletion() {
-    const pluginCmds = getPluginCommandsInfo();
-    const verbInfos = deriveVerbInfos(pluginCmds);
-    const allFlags = deriveAllFlags();
-    const helpResources = deriveHelpResources();
-    const lines = [
-        "# c8ctl fish completion",
-        "",
-        "# Remove all existing completions for c8ctl and c8",
-        "complete -c c8ctl -e",
-        "complete -c c8 -e",
-        "",
-    ];
-    // Global flags
-    lines.push("# Global flags");
-    for (const f of allFlags) {
-        const desc = escFish(f.description);
-        const req = f.type === "string" ? " -r" : "";
-        if (f.short) {
-            lines.push(`complete -c c8ctl -s ${f.short} -l ${f.name} -d '${desc}'${req}`);
-            lines.push(`complete -c c8 -s ${f.short} -l ${f.name} -d '${desc}'${req}`);
-        }
-        else {
-            lines.push(`complete -c c8ctl -l ${f.name} -d '${desc}'${req}`);
-            lines.push(`complete -c c8 -l ${f.name} -d '${desc}'${req}`);
-        }
-    }
-    lines.push("");
-    // Verb completions
-    lines.push("# Commands (verbs) - only suggest when no command is given yet");
-    for (const v of verbInfos) {
-        const desc = escFish(v.description);
-        lines.push(`complete -c c8ctl -n '__fish_use_subcommand' -a '${v.verb}' -d '${desc}'`);
-        lines.push(`complete -c c8 -n '__fish_use_subcommand' -a '${v.verb}' -d '${desc}'`);
-        for (const a of v.aliases) {
-            lines.push(`complete -c c8ctl -n '__fish_use_subcommand' -a '${a}' -d '${desc}'`);
-            lines.push(`complete -c c8 -n '__fish_use_subcommand' -a '${a}' -d '${desc}'`);
-        }
-    }
-    lines.push("");
-    // Per-verb resource completions
-    for (const v of verbInfos) {
-        if (v.verb === "help") {
-            lines.push(`# Resources for 'help' command`);
-            for (const r of helpResources) {
-                const desc = escFish(r.description);
-                lines.push(`complete -c c8ctl -n '__fish_seen_subcommand_from help' -a '${r.name}' -d '${desc}'`);
-                lines.push(`complete -c c8 -n '__fish_seen_subcommand_from help' -a '${r.name}' -d '${desc}'`);
-            }
-            lines.push("");
-            continue;
-        }
-        if (v.fileComplete || v.resources.length === 0)
-            continue;
-        const seenFrom = [v.verb, ...v.aliases].join(" ");
-        lines.push(`# Resources for '${v.verb}' command`);
-        for (const r of v.resources) {
-            const desc = escFish(`${capitalize(v.verb)} ${resourceDisplayName(r)}`);
-            lines.push(`complete -c c8ctl -n '__fish_seen_subcommand_from ${seenFrom}' -a '${r}' -d '${desc}'`);
-            lines.push(`complete -c c8 -n '__fish_seen_subcommand_from ${seenFrom}' -a '${r}' -d '${desc}'`);
-        }
-        lines.push("");
-    }
-    lines.unshift(`# c8ctl-completion-version: ${c8ctl.version}`);
-    return `${lines.join("\n")}\n`;
-}
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-function capitalize(s) {
-    return s.charAt(0).toUpperCase() + s.slice(1);
-}
-/** Human-readable name from resource alias. */
-function resourceDisplayName(resource) {
-    const canonical = RESOURCE_ALIASES[resource] ?? resource;
-    return canonical.replace(/-/g, " ") + (resource !== canonical ? "s" : "");
-}
-function escZsh(s) {
-    return s.replace(/'/g, "'\\''");
-}
-function escFish(s) {
-    return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-}
-// ─── Public API ──────────────────────────────────────────────────────────────
-/**
- * Show completion command
+ * Thin handler wrapper for the `completion` verb.
  *
- * Throws on missing/unknown shell; framework wrapper adds the
- * `Failed to completion ...` prefix. Do NOT reintroduce `process.exit` —
- * `tests/unit/no-process-exit-in-handlers.test.ts` enforces this.
+ * All shell-completion implementation logic (rendering, install,
+ * detection, refresh) lives in `src/completion.ts` so it can be unit
+ * tested without violating the test→commands import boundary (#291).
+ * This file holds only the `defineCommand` wrapper that dispatches the
+ * verb at runtime.
  */
-export function showCompletion(shell) {
-    if (!shell) {
-        throw new Error("Shell type required. Usage: c8 completion <bash|zsh|fish>");
-    }
-    const normalizedShell = shell.toLowerCase();
-    switch (normalizedShell) {
-        case "bash":
-            console.log(generateBashCompletion());
-            break;
-        case "zsh":
-            console.log(generateZshCompletion());
-            break;
-        case "fish":
-            console.log(generateFishCompletion());
-            break;
-        default:
-            throw new Error(`Unknown shell: ${shell}. Supported shells: bash, zsh, fish. Usage: c8 completion <bash|zsh|fish>`);
-    }
-}
-// ─── Completion install ──────────────────────────────────────────────────────
-/** Version header prefix used to tag generated completion files. */
-const VERSION_HEADER_PREFIX = "# c8ctl-completion-version: ";
-/** Completions subdirectory under the user data dir. */
-const COMPLETIONS_DIR = "completions";
-/** Shell file extensions. */
-const SHELL_EXTENSIONS = {
-    bash: "bash",
-    zsh: "zsh",
-    fish: "fish",
-};
-/** Detect the user's shell from $SHELL. Returns lowercase shell name or undefined. */
-export function detectShell() {
-    const shellPath = process.env.SHELL;
-    if (!shellPath)
-        return undefined;
-    const base = shellPath.split("/").pop();
-    if (!base)
-        return undefined;
-    const name = base.toLowerCase();
-    if (name === "bash" || name === "zsh" || name === "fish")
-        return name;
-    return undefined;
-}
-/** Get the appropriate RC file path for a given shell. */
-export function getShellRcFile(shell) {
-    const home = homedir();
-    switch (shell) {
-        case "bash":
-            // macOS uses .bash_profile by default; Linux uses .bashrc
-            return platform() === "darwin"
-                ? join(home, ".bash_profile")
-                : join(home, ".bashrc");
-        case "zsh":
-            return join(home, ".zshrc");
-        case "fish":
-            // fish auto-loads from completions dir — no rc edit needed
-            return undefined;
-        default:
-            return undefined;
-    }
-}
-/** Get the path where the completion file will be written. */
-export function getCompletionFilePath(shell) {
-    const ext = SHELL_EXTENSIONS[shell] ?? shell;
-    return join(getUserDataDir(), COMPLETIONS_DIR, `c8ctl.${ext}`);
-}
-/** Get the fish completions dir (fish auto-loads from here). Respects XDG_CONFIG_HOME. */
-function getFishCompletionsDir() {
-    const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-    return join(configHome, "fish", "completions");
-}
-/** Generate the source line that goes into the shell RC file.
- *  Uses single quotes to prevent shell expansion of the path. */
-function buildSourceLine(completionFilePath) {
-    // Reject control characters (newlines, null, etc.) that could inject
-    // additional commands into the shell RC file.
-    for (const ch of completionFilePath) {
-        const code = ch.charCodeAt(0);
-        if (code <= 0x1f || code === 0x7f) {
-            throw new Error("Completion file path contains control characters.");
-        }
-    }
-    const escaped = completionFilePath.replaceAll("'", "'\\''");
-    return `source '${escaped}'`;
-}
-/** Generate the comment+source block for the RC file. */
-function buildRcBlock(completionFilePath) {
-    return `\n# c8ctl shell completion\n${buildSourceLine(completionFilePath)}\n`;
-}
-/** Check if the RC file already contains the source line.
- *  Checks for both the current single-quoted source line and the legacy
- *  double-quoted form, so upgrades are detected without false-positiving
- *  on the raw path appearing in unrelated lines. */
-function rcAlreadyConfigured(rcFile, completionFilePath) {
-    if (!existsSync(rcFile))
-        return false;
-    try {
-        const content = readFileSync(rcFile, "utf-8");
-        // Check for current single-quoted source line
-        if (content.includes(buildSourceLine(completionFilePath)))
-            return true;
-        // Check for legacy double-quoted source line
-        const escaped = completionFilePath.replaceAll('"', '\\"');
-        if (content.includes(`source "${escaped}"`))
-            return true;
-        return false;
-    }
-    catch {
-        return false;
-    }
-}
-/** Generate the completion script content for a given shell. */
-function generateForShell(shell) {
-    switch (shell) {
-        case "bash":
-            return generateBashCompletion();
-        case "zsh":
-            return generateZshCompletion();
-        case "fish":
-            return generateFishCompletion();
-        default:
-            throw new Error(`Unknown shell: ${shell}`);
-    }
-}
-/** Extract the version from a completion file's header lines.
- *  Scans the first few lines so the header can appear after
- *  shell-required directives like zsh's #compdef. */
-export function extractCompletionVersion(filePath) {
-    if (!existsSync(filePath))
-        return undefined;
-    try {
-        const content = readFileSync(filePath, "utf-8");
-        const lines = content.split("\n").slice(0, 5);
-        for (const line of lines) {
-            if (line.startsWith(VERSION_HEADER_PREFIX)) {
-                return line.slice(VERSION_HEADER_PREFIX.length).trim();
-            }
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Install shell completions: write script to data dir, wire into RC file.
- *
- * Supports --dry-run via the c8ctl runtime flag.
- */
-export function installCompletion(shellOverride) {
-    const logger = getLogger();
-    const shell = shellOverride?.toLowerCase() ?? detectShell();
-    if (!shell) {
-        throw new Error("Could not detect shell. Specify with: c8ctl completion install --shell <bash|zsh|fish>");
-    }
-    if (!["bash", "zsh", "fish"].includes(shell)) {
-        throw new Error(`Unsupported shell: ${shell}. Supported shells: bash, zsh, fish`);
-    }
-    const completionFile = getCompletionFilePath(shell);
-    const rcFile = getShellRcFile(shell);
-    const rcConfigured = rcFile
-        ? rcAlreadyConfigured(rcFile, completionFile)
-        : true;
-    // Dry-run support
-    if (c8ctl.dryRun) {
-        const result = {
-            dryRun: true,
-            detectedShell: shell,
-            completionFile,
-        };
-        if (rcFile) {
-            result.rcFile = rcFile;
-            result.sourceLine = buildSourceLine(completionFile);
-            result.rcAlreadyConfigured = rcConfigured;
-        }
-        if (shell === "fish") {
-            result.fishCompletionsDir = getFishCompletionsDir();
-        }
-        logger.json(result);
-        return;
-    }
-    // Write the completion file
-    try {
-        const completionDir = join(getUserDataDir(), COMPLETIONS_DIR);
-        mkdirSync(completionDir, { recursive: true });
-        const script = generateForShell(shell);
-        writeFileSync(completionFile, script, "utf-8");
-        logger.info(`Completion script written to ${completionFile}`);
-        // Fish: also copy to fish auto-load directory
-        if (shell === "fish") {
-            const fishDir = getFishCompletionsDir();
-            mkdirSync(fishDir, { recursive: true });
-            writeFileSync(join(fishDir, "c8ctl.fish"), script, "utf-8");
-            logger.info(`Fish completion installed to ${fishDir}/c8ctl.fish`);
-            logger.info("Completions will be loaded automatically on next shell start.");
-            return;
-        }
-        // Wire into RC file (bash/zsh)
-        if (rcFile) {
-            if (rcConfigured) {
-                logger.info(`RC file already configured: ${rcFile}`);
-            }
-            else {
-                const block = buildRcBlock(completionFile);
-                writeFileSync(rcFile, block, { encoding: "utf-8", flag: "a" });
-                logger.info(`Added source line to ${rcFile}`);
-            }
-        }
-        logger.info("Restart your shell or run:");
-        logger.info(`  ${buildSourceLine(completionFile)}`);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger.info(`Target path: ${completionFile}`);
-        if (rcFile) {
-            logger.info(`Add this line manually to your shell config:\n  ${buildSourceLine(completionFile)}`);
-        }
-        throw new Error(`Failed to install completions: ${msg}`);
-    }
-}
-/**
- * Refresh the installed completion file if the CLI version has changed.
- *
- * Called on every CLI invocation — no-op if completions are not installed
- * or if the embedded version matches the running CLI version.
- * Synchronous write (~1ms for a few KB).
- */
-export function refreshCompletionsIfStale() {
-    // Skip in dry-run mode — refresh is a side effect
-    if (c8ctl.dryRun)
-        return;
-    // Use the same source of truth as generateForShell() for version headers
-    const currentVersion = c8ctl.version;
-    // Check each shell — user may have installed for multiple shells
-    for (const shell of ["bash", "zsh", "fish"]) {
-        const filePath = getCompletionFilePath(shell);
-        const installed = extractCompletionVersion(filePath);
-        if (installed === undefined) {
-            // No version header — treat existing file as stale, regenerate
-            if (!existsSync(filePath))
-                continue; // not installed for this shell
-        }
-        else if (installed === currentVersion) {
-            continue; // up to date
-        }
-        // Stale — regenerate
-        try {
-            const script = generateForShell(shell);
-            writeFileSync(filePath, script, "utf-8");
-            // Fish: also update the auto-load copy
-            if (shell === "fish") {
-                const fishTarget = join(getFishCompletionsDir(), "c8ctl.fish");
-                if (existsSync(fishTarget)) {
-                    writeFileSync(fishTarget, script, "utf-8");
-                }
-            }
-        }
-        catch {
-            // Best-effort — don't crash if the write fails
-        }
-    }
-}
-// ─── defineCommand wrappers ──────────────────────────────────────────────────
+import { defineCommand } from "../command-framework.js";
+import { installCompletion, showCompletion } from "../completion.js";
 /**
  * `completion` verb dispatcher.
  *
@@ -697,19 +18,40 @@ export function refreshCompletionsIfStale() {
  * invocation to `completion:` because `requiresResource` is false. This
  * single handler branches on the incoming resource.
  *
+ * Registered against `"install"` (not `""`) so the typed `flags`
+ * parameter includes `shell` — the only resource-scoped flag, declared
+ * in `resourceFlags.install` per the verb/resource flag-bucket
+ * disjointness invariant (#256). The dispatch key is still `completion:`
+ * because dispatch is derived from `requiresResource`, not from the
+ * registration resource. The framework uses `ctx.resource` for error
+ * messages so failures on non-install branches are not mislabelled
+ * "Failed to completion install".
+ *
  * All validation errors are raised via `throw` so the framework wrapper
  * routes them through `handleCommandError`. The architectural guard in
  * `tests/unit/no-process-exit-in-handlers.test.ts` forbids `process.exit`
  * here.
  */
-export const completionCommand = defineCommand("completion", "", async (ctx, flags) => {
+export const completionCommand = defineCommand("completion", "install", async (ctx, flags) => {
     const resource = ctx.resource;
     if (resource === "install") {
         const shellFlag = flags.shell;
         installCompletion(typeof shellFlag === "string" ? shellFlag : undefined);
         return undefined;
     }
-    // Empty resource → show usage error consistent with prior behaviour.
+    // Non-install resource → render the requested shell's completion
+    // script when `resource` is one of bash/zsh/fish. When `resource`
+    // is empty (`c8ctl completion` with no positional), `showCompletion`
+    // throws a usage error listing the supported shells; the framework
+    // wrapper routes that through `handleCommandError`.
+    //
+    // Note: `flags.shell` may still be populated here because dispatch is
+    // `completion:` regardless of resource and the install schema is in
+    // effect — `parseArgs` will accept `--shell` and `deserializeFlags`
+    // will populate it. `detectUnknownFlags` (src/command-validation.ts)
+    // emits a warning that `--shell` is not valid for non-install
+    // resources, but the value is not stripped. This branch deliberately
+    // ignores `flags.shell`; the warning is the user-facing signal.
     showCompletion(resource || undefined);
     return undefined;
 });