zinkee 0.1.10 → 0.1.12

package/dist/index.js

@@ -732,6 +732,197 @@ var commandRegistry = {
   }
 };
 
+// src/utils/argv-rewrite.ts
+var HOISTABLE_GLOBAL_FLAGS = {
+  "--profile": "value",
+  "--base-url": "value",
+  "--api-key": "value",
+  "--read-only": "boolean",
+  "--json": "boolean"
+};
+function isHoistableFlag(flagName) {
+  return Object.hasOwn(HOISTABLE_GLOBAL_FLAGS, flagName);
+}
+function getCommandPath(command) {
+  const parts = [];
+  let cursor = command;
+  while (cursor && cursor.parent) {
+    parts.unshift(cursor.name());
+    cursor = cursor.parent;
+  }
+  return parts.join(" ");
+}
+function buildOptionMetadata(program) {
+  const valueFlags = /* @__PURE__ */ new Set();
+  const booleanFlags = /* @__PURE__ */ new Set();
+  const localOptionsByCommand = /* @__PURE__ */ new Map();
+  function visit(command, isRoot) {
+    const localFlags = /* @__PURE__ */ new Set();
+    for (const option of command.options) {
+      if (!option.long) continue;
+      if (option.required || option.optional) {
+        valueFlags.add(option.long);
+      } else {
+        booleanFlags.add(option.long);
+      }
+      if (!isRoot) {
+        localFlags.add(option.long);
+      }
+    }
+    if (!isRoot) {
+      localOptionsByCommand.set(getCommandPath(command), localFlags);
+    }
+    for (const sub of command.commands) {
+      visit(sub, false);
+    }
+  }
+  visit(program, true);
+  return { valueFlags, booleanFlags, localOptionsByCommand };
+}
+function createDefaultOptionMetadata() {
+  return {
+    valueFlags: /* @__PURE__ */ new Set([
+      "--profile",
+      "--base-url",
+      "--api-key",
+      "--install-completion",
+      "--show-completion"
+    ]),
+    booleanFlags: /* @__PURE__ */ new Set([
+      "--read-only",
+      "--json",
+      "--example",
+      "--help"
+    ]),
+    localOptionsByCommand: /* @__PURE__ */ new Map()
+  };
+}
+function isFlagToken(token) {
+  return token.length > 1 && token.startsWith("-");
+}
+function splitFlagToken(token) {
+  if (token.startsWith("--") && token.includes("=")) {
+    const eqIdx = token.indexOf("=");
+    return {
+      flagName: token.slice(0, eqIdx),
+      inlineValue: token.slice(eqIdx + 1)
+    };
+  }
+  return { flagName: token, inlineValue: void 0 };
+}
+function flagConsumesValue(flagName, optionMeta) {
+  if (optionMeta.valueFlags.has(flagName)) {
+    return true;
+  }
+  if (optionMeta.booleanFlags.has(flagName)) {
+    return false;
+  }
+  return true;
+}
+function collectOperandTokens(userArgs, optionMeta, options = {}) {
+  const operands = [];
+  let i = 0;
+  while (i < userArgs.length) {
+    const token = userArgs[i];
+    if (token === "--") {
+      break;
+    }
+    if (isFlagToken(token)) {
+      const { flagName, inlineValue } = splitFlagToken(token);
+      if (options.skipFlag !== void 0 && flagName === options.skipFlag) {
+        i += 1;
+        continue;
+      }
+      if (inlineValue !== void 0) {
+        i += 1;
+        continue;
+      }
+      const consumes = flagConsumesValue(flagName, optionMeta);
+      const next = userArgs[i + 1];
+      if (consumes && next !== void 0 && !isFlagToken(next)) {
+        i += 2;
+      } else {
+        i += 1;
+      }
+      continue;
+    }
+    operands.push({ index: i, token });
+    i += 1;
+  }
+  return operands;
+}
+function findCommandPath(operands, registry) {
+  if (operands.length === 0) return null;
+  const commandsByLength = Object.keys(registry).sort(
+    (left, right) => right.split(" ").length - left.split(" ").length
+  );
+  for (let start = 0; start < operands.length; start += 1) {
+    for (const commandName of commandsByLength) {
+      const parts = commandName.split(" ");
+      if (start + parts.length > operands.length) continue;
+      let matches = true;
+      for (let j = 0; j < parts.length; j += 1) {
+        if (operands[start + j].token !== parts[j]) {
+          matches = false;
+          break;
+        }
+      }
+      if (matches) {
+        return {
+          commandName,
+          firstArgvIndex: operands[start].index,
+          lastArgvIndex: operands[start + parts.length - 1].index
+        };
+      }
+    }
+  }
+  return null;
+}
+function hoistGlobalOptions(argv, optionMeta, registry) {
+  if (argv.length < 3) return [...argv];
+  const userArgs = argv.slice(2);
+  const operands = collectOperandTokens(userArgs, optionMeta);
+  const cmdPath = findCommandPath(operands, registry);
+  if (!cmdPath) return [...argv];
+  const localOptions = optionMeta.localOptionsByCommand.get(cmdPath.commandName) ?? /* @__PURE__ */ new Set();
+  const hoisted = [];
+  const remaining = [];
+  let i = 0;
+  while (i < userArgs.length) {
+    const token = userArgs[i];
+    if (token === "--") {
+      remaining.push(...userArgs.slice(i));
+      break;
+    }
+    if (!isFlagToken(token)) {
+      remaining.push(token);
+      i += 1;
+      continue;
+    }
+    const { flagName, inlineValue } = splitFlagToken(token);
+    if (!isHoistableFlag(flagName)) {
+      remaining.push(token);
+      i += 1;
+      continue;
+    }
+    const isAfterCommandPath = i > cmdPath.lastArgvIndex;
+    const collidesWithLocal = localOptions.has(flagName);
+    const target = isAfterCommandPath && collidesWithLocal ? remaining : hoisted;
+    target.push(token);
+    const spec = HOISTABLE_GLOBAL_FLAGS[flagName];
+    if (spec === "value" && inlineValue === void 0) {
+      const next = userArgs[i + 1];
+      if (next !== void 0 && !isFlagToken(next)) {
+        target.push(next);
+        i += 2;
+        continue;
+      }
+    }
+    i += 1;
+  }
+  return [argv[0], argv[1], ...hoisted, ...remaining];
+}
+
 // src/client.ts
 var ApiClientError = class extends Error {
   name = "ApiClientError";
@@ -6392,26 +6583,6 @@ async function getResolvedCommandExamples(commandName, filters = {}, options = {
 function getStdout(stdout) {
   return stdout ?? process.stdout;
 }
-function resolveExampleCommand(tokens) {
-  const commands = Object.keys(commandRegistry).sort(
-    (left, right) => right.split(" ").length - left.split(" ").length
-  );
-  for (const commandName of commands) {
-    const commandTokens2 = commandName.split(" ");
-    const matches = commandTokens2.every((token, index) => tokens[index] === token);
-    if (matches) {
-      return {
-        commandName,
-        remainingTokens: tokens.slice(commandTokens2.length)
-      };
-    }
-  }
-  const commandTokens = tokens.filter((token) => !token.startsWith("-"));
-  return {
-    commandName: commandTokens.join(" "),
-    remainingTokens: []
-  };
-}
 function extractExampleFilters(tokens) {
   const filters = {};
   for (let index = 0; index < tokens.length; index += 1) {
@@ -6451,18 +6622,19 @@ function extractExampleOverrides(tokens) {
   }
   return overrides;
 }
-function extractExampleRequest(argv) {
-  const exampleIndex = argv.indexOf("--example");
-  if (exampleIndex === -1) {
+function extractExampleRequest(argv, optionMeta = createDefaultOptionMetadata()) {
+  if (!argv.includes("--example")) {
     return null;
   }
-  const requestTokens = argv.slice(exampleIndex + 1);
-  const { commandName, remainingTokens } = resolveExampleCommand(requestTokens);
-  if (commandName.length === 0) {
+  const userArgs = argv.slice(2);
+  const operands = collectOperandTokens(userArgs, optionMeta, { skipFlag: "--example" });
+  const cmdPath = findCommandPath(operands, commandRegistry);
+  if (!cmdPath) {
     throw new CliError("invalid_cli_usage", 'Provide a command after "--example".');
   }
+  const remainingTokens = userArgs.slice(cmdPath.lastArgvIndex + 1);
   return {
-    commandName,
+    commandName: cmdPath.commandName,
     filters: extractExampleFilters(remainingTokens),
     overrides: extractExampleOverrides(argv),
     json: argv.includes("--json")
@@ -10961,7 +11133,7 @@ var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 function buildProgram(options = {}) {
   const program = new Command10();
-  program.name("zinkee").description("CLI for Zinkee API v2").version(version).enablePositionalOptions().showHelpAfterError().option("--profile <name>", "select a profile from config").option("--base-url <url>", "override the configured base URL").option("--api-key <token>", "override the configured API key").option("--read-only", "run in read-only mode").option("--example", "show examples for a command").option("--json", "emit JSON output");
+  program.name("zinkee").description("CLI for Zinkee API v2").version(version).enablePositionalOptions().showHelpAfterError().option("--profile <name>", "select a profile from config").option("--base-url <url>", "override the configured base URL").option("--api-key <token>", "override the configured API key").option("--read-only", "run in read-only mode").option("--example", "show examples for a command").option("--json", "emit JSON output").option("--install-completion [shell]", "install shell completion (bash, zsh, fish, powershell)").option("--show-completion [shell]", "print shell completion script for the current shell");
   registerProfilesCommands(program, options);
   registerAutomationsCommands(program, options);
   registerConfigCommands(program, options);
@@ -10976,6 +11148,539 @@ function buildProgram(options = {}) {
   return program;
 }
 
+// src/completion/engine.ts
+function readProfileNamesFromConfig(configPath) {
+  try {
+    const config = readConfigIfExists(configPath);
+    if (!config) {
+      return [];
+    }
+    return Object.keys(config.profiles).sort();
+  } catch {
+    return [];
+  }
+}
+function findSubcommand(command, name) {
+  return command.commands.find((sub) => {
+    if (sub.name() === name) {
+      return true;
+    }
+    const aliases = sub.aliases();
+    return aliases.includes(name);
+  });
+}
+function collectFlagsThatTakeValues(root) {
+  const flags = /* @__PURE__ */ new Set();
+  const walk = (command) => {
+    for (const option of command.options) {
+      if (!option.required && !option.optional) {
+        continue;
+      }
+      if (option.long) {
+        flags.add(option.long);
+      }
+      if (option.short) {
+        flags.add(option.short);
+      }
+    }
+    for (const sub of command.commands) {
+      walk(sub);
+    }
+  };
+  walk(root);
+  return flags;
+}
+function descend(root, words) {
+  const flagsWithValues = collectFlagsThatTakeValues(root);
+  let current = root;
+  let index = 0;
+  while (index < words.length) {
+    const word = words[index];
+    if (word.startsWith("-")) {
+      const [flagPart] = word.split("=", 1);
+      if (flagPart && flagsWithValues.has(flagPart) && !word.includes("=")) {
+        index += 2;
+      } else {
+        index += 1;
+      }
+      continue;
+    }
+    const next = findSubcommand(current, word);
+    if (!next) {
+      break;
+    }
+    current = next;
+    index += 1;
+  }
+  return current;
+}
+function collectVisibleSubcommands(command) {
+  const names = [];
+  for (const sub of command.commands) {
+    if (sub.name().startsWith("__")) {
+      continue;
+    }
+    names.push(sub.name());
+  }
+  return names;
+}
+function collectVisibleLongFlags(command) {
+  const flags = [];
+  let current = command;
+  while (current) {
+    for (const option of current.options) {
+      if (option.hidden || !option.long) {
+        continue;
+      }
+      if (!flags.includes(option.long)) {
+        flags.push(option.long);
+      }
+    }
+    current = current.parent;
+  }
+  if (!flags.includes("--help")) {
+    flags.push("--help");
+  }
+  return flags;
+}
+function getCompletions(program, request, deps = {}) {
+  const { words, cwordIndex } = request;
+  const safeIndex = Math.max(0, Math.min(cwordIndex, words.length));
+  const current = words[safeIndex] ?? "";
+  const prevToken = safeIndex > 0 ? words[safeIndex - 1] : void 0;
+  const readProfiles = deps.readProfileNames ?? readProfileNamesFromConfig;
+  if (prevToken === "--profile" || prevToken === "-p") {
+    try {
+      return readProfiles(deps.configPath).filter((name) => name.startsWith(current)).slice().sort();
+    } catch {
+      return [];
+    }
+  }
+  const tokensBeforeCurrent = words.slice(1, safeIndex);
+  const command = descend(program, tokensBeforeCurrent);
+  const candidates = /* @__PURE__ */ new Set();
+  if (current.startsWith("-")) {
+    for (const flag of collectVisibleLongFlags(command)) {
+      if (flag.startsWith(current)) {
+        candidates.add(flag);
+      }
+    }
+    return [...candidates].sort();
+  }
+  for (const subcommand of collectVisibleSubcommands(command)) {
+    if (subcommand.startsWith(current)) {
+      candidates.add(subcommand);
+    }
+  }
+  for (const flag of collectVisibleLongFlags(command)) {
+    if (flag.startsWith(current)) {
+      candidates.add(flag);
+    }
+  }
+  return [...candidates].sort();
+}
+
+// src/completion/install.ts
+import { execFileSync } from "child_process";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync10, writeFileSync as writeFileSync3 } from "fs";
+import { homedir as homedir2, platform } from "os";
+import { basename as basename2, dirname as dirname2, join as join2 } from "path";
+
+// src/completion/scripts.ts
+var PROGRAM = "zinkee";
+var ENV_VAR = "_ZINKEE_COMPLETE";
+function renderBashScript() {
+  return `_zinkee_completion() {
+    local IFS=$'\\n'
+    local response
+
+    response=$(env COMP_WORDS="\${COMP_WORDS[*]}" COMP_CWORD=$COMP_CWORD ${ENV_VAR}=bash_complete ${PROGRAM} 2>/dev/null)
+
+    COMPREPLY=( \${response} )
+    return 0
+}
+
+complete -o default -F _zinkee_completion ${PROGRAM}
+`;
+}
+function renderZshScript() {
+  return `#compdef ${PROGRAM}
+
+_zinkee_completion() {
+    local -a response
+    (( ! $+commands[${PROGRAM}] )) && return 1
+
+    response=("\${(@f)$(env COMP_WORDS="\${words[*]}" COMP_CWORD=$((CURRENT - 1)) ${ENV_VAR}=zsh_complete ${PROGRAM} 2>/dev/null)}")
+
+    if [ -n "$response" ]; then
+        compadd -U -V unsorted -a response
+    fi
+}
+
+if [[ $zsh_eval_context[-1] == loadautofunc ]]; then
+    _zinkee_completion "$@"
+else
+    compdef _zinkee_completion ${PROGRAM}
+fi
+`;
+}
+function renderFishScript() {
+  return `function __zinkee_completion
+    set -l tokens (commandline -opc) (commandline -ct)
+    set -l cword (math (count $tokens) - 1)
+    set -l joined (string join " " -- $tokens)
+
+    env COMP_WORDS="$joined" COMP_CWORD=$cword ${ENV_VAR}=fish_complete ${PROGRAM} 2>/dev/null
+end
+
+complete --no-files --command ${PROGRAM} --arguments '(__zinkee_completion)'
+`;
+}
+function renderPowerShellScript() {
+  return `Register-ArgumentCompleter -Native -CommandName ${PROGRAM} -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+
+    $tokens = @($commandAst.CommandElements | ForEach-Object { $_.ToString() })
+    $cword = [Math]::Max(0, $tokens.Count - 1)
+
+    $env:COMP_WORDS = ($tokens -join ' ')
+    $env:COMP_CWORD = $cword
+    $env:${ENV_VAR} = 'powershell_complete'
+
+    try {
+        & ${PROGRAM} 2>$null | ForEach-Object {
+            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+        }
+    } finally {
+        Remove-Item Env:COMP_WORDS -ErrorAction SilentlyContinue
+        Remove-Item Env:COMP_CWORD -ErrorAction SilentlyContinue
+        Remove-Item Env:${ENV_VAR} -ErrorAction SilentlyContinue
+    }
+}
+`;
+}
+function renderScript(shell) {
+  switch (shell) {
+    case "bash":
+      return renderBashScript();
+    case "zsh":
+      return renderZshScript();
+    case "fish":
+      return renderFishScript();
+    case "powershell":
+      return renderPowerShellScript();
+  }
+}
+
+// src/completion/install.ts
+var SUPPORTED_SHELLS = [
+  "bash",
+  "zsh",
+  "fish",
+  "powershell"
+];
+var BLOCK_BEGIN = "# >>> zinkee completion >>>";
+var BLOCK_END = "# <<< zinkee completion <<<";
+var CompletionShellError = class extends Error {
+  name = "CompletionShellError";
+};
+function defaultPowerShellProfile(env) {
+  for (const exe of ["pwsh", "powershell.exe"]) {
+    try {
+      const out = execFileSync(exe, ["-NoProfile", "-Command", "$PROFILE"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      const path = out.trim();
+      if (path) {
+        return path;
+      }
+    } catch {
+    }
+  }
+  if (env.platform === "win32") {
+    return join2(env.home, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1");
+  }
+  return join2(env.home, ".config", "powershell", "Microsoft.PowerShell_profile.ps1");
+}
+function detectShell(env) {
+  const fromEnv = env.shellEnv;
+  if (fromEnv) {
+    const name = basename2(fromEnv).toLowerCase().replace(/\.exe$/, "");
+    if (name === "bash") {
+      return "bash";
+    }
+    if (name === "zsh") {
+      return "zsh";
+    }
+    if (name === "fish") {
+      return "fish";
+    }
+    if (name === "pwsh" || name === "powershell") {
+      return "powershell";
+    }
+  }
+  if (env.platform === "win32") {
+    return "powershell";
+  }
+  throw new CompletionShellError(
+    `Could not detect a supported shell from $SHELL=${fromEnv ?? ""}. Pass one of: ${SUPPORTED_SHELLS.join(", ")}.`
+  );
+}
+function parseShell(value) {
+  const normalized = value.toLowerCase();
+  if (normalized === "bash" || normalized === "zsh" || normalized === "fish" || normalized === "powershell") {
+    return normalized;
+  }
+  if (normalized === "pwsh") {
+    return "powershell";
+  }
+  throw new CompletionShellError(
+    `Unsupported shell "${value}". Supported: ${SUPPORTED_SHELLS.join(", ")}.`
+  );
+}
+function resolveTarget(shell, env) {
+  switch (shell) {
+    case "bash":
+      return {
+        shell,
+        scriptPath: join2(env.home, ".bash_completions", "zinkee.sh"),
+        rcPath: join2(env.home, ".bashrc")
+      };
+    case "zsh":
+      return {
+        shell,
+        scriptPath: join2(env.home, ".zfunc", "_zinkee"),
+        rcPath: join2(env.home, ".zshrc")
+      };
+    case "fish":
+      return {
+        shell,
+        scriptPath: join2(env.home, ".config", "fish", "completions", "zinkee.fish")
+      };
+    case "powershell": {
+      const resolver = env.resolvePowerShellProfile ?? (() => defaultPowerShellProfile(env));
+      const profilePath = resolver();
+      if (!profilePath) {
+        throw new CompletionShellError(
+          "Could not resolve PowerShell $PROFILE path. Install PowerShell or use --show-completion."
+        );
+      }
+      return {
+        shell,
+        scriptPath: profilePath,
+        rcPath: profilePath
+      };
+    }
+  }
+}
+function buildRcSnippet(shell, scriptPath) {
+  switch (shell) {
+    case "bash":
+      return `source "${scriptPath}"`;
+    case "zsh":
+      return [
+        `fpath=("${dirname2(scriptPath)}" $fpath)`,
+        "autoload -Uz compinit && compinit"
+      ].join("\n");
+    default:
+      return "";
+  }
+}
+function applyBlock(existing, block) {
+  const wrapped = `${BLOCK_BEGIN}
+${block.trimEnd()}
+${BLOCK_END}
+`;
+  const blockPattern = new RegExp(
+    `${BLOCK_BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`,
+    "m"
+  );
+  if (blockPattern.test(existing)) {
+    return existing.replace(blockPattern, wrapped);
+  }
+  const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  return `${existing}${separator}${wrapped}`;
+}
+function readFileOrEmpty(path) {
+  try {
+    return readFileSync10(path, "utf8");
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+function writeFileEnsuringDir(path, content) {
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync3(path, content, "utf8");
+}
+function installCompletion(shell, env) {
+  const target = resolveTarget(shell, env);
+  const script = renderScript(shell);
+  if (shell === "powershell") {
+    const existing = readFileOrEmpty(target.scriptPath);
+    const updated = applyBlock(existing, script);
+    writeFileEnsuringDir(target.scriptPath, updated);
+    return {
+      shell,
+      scriptPath: target.scriptPath,
+      rcPath: target.scriptPath,
+      rcUpdated: true
+    };
+  }
+  writeFileEnsuringDir(target.scriptPath, script);
+  if (!target.rcPath) {
+    return {
+      shell,
+      scriptPath: target.scriptPath,
+      rcUpdated: false
+    };
+  }
+  const snippet = buildRcSnippet(shell, target.scriptPath);
+  if (!snippet) {
+    return {
+      shell,
+      scriptPath: target.scriptPath,
+      rcPath: target.rcPath,
+      rcUpdated: false
+    };
+  }
+  const existingRc = readFileOrEmpty(target.rcPath);
+  const updatedRc = applyBlock(existingRc, snippet);
+  if (updatedRc !== existingRc) {
+    writeFileEnsuringDir(target.rcPath, updatedRc);
+    return {
+      shell,
+      scriptPath: target.scriptPath,
+      rcPath: target.rcPath,
+      rcUpdated: true
+    };
+  }
+  return {
+    shell,
+    scriptPath: target.scriptPath,
+    rcPath: target.rcPath,
+    rcUpdated: false
+  };
+}
+function currentEnvironment() {
+  return {
+    home: homedir2(),
+    platform: platform(),
+    shellEnv: process.env.SHELL
+  };
+}
+
+// src/completion/runtime.ts
+var COMPLETION_ENV_VAR = "_ZINKEE_COMPLETE";
+function getStream(stream, fallback) {
+  return stream ?? fallback;
+}
+function parseEnvWords(env) {
+  const raw = env.COMP_WORDS ?? "";
+  if (raw.trim().length === 0) {
+    return [];
+  }
+  return raw.split(/\s+/).filter((token) => token.length > 0);
+}
+function parseEnvCwordIndex(env) {
+  const raw = env.COMP_CWORD ?? "0";
+  const parsed = Number.parseInt(raw, 10);
+  if (Number.isNaN(parsed) || parsed < 0) {
+    return 0;
+  }
+  return parsed;
+}
+function isCompletionRequest(env = process.env) {
+  return typeof env[COMPLETION_ENV_VAR] === "string" && env[COMPLETION_ENV_VAR].length > 0;
+}
+function runCompletionRequest(env = process.env, stdout) {
+  const out = getStream(stdout, process.stdout);
+  try {
+    const program = buildProgram();
+    const candidates = getCompletions(program, {
+      words: parseEnvWords(env),
+      cwordIndex: parseEnvCwordIndex(env)
+    });
+    if (candidates.length > 0) {
+      out.write(`${candidates.join("\n")}
+`);
+    }
+  } catch {
+  }
+}
+function extractCompletionFlag(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token) {
+      continue;
+    }
+    if (token === "--install-completion" || token === "--show-completion") {
+      const mode = token === "--install-completion" ? "install" : "show";
+      const next = argv[index + 1];
+      const shellOverride = next && !next.startsWith("-") ? next : void 0;
+      return { mode, shellOverride };
+    }
+    if (token.startsWith("--install-completion=")) {
+      const value = token.slice("--install-completion=".length);
+      return { mode: "install", shellOverride: value || void 0 };
+    }
+    if (token.startsWith("--show-completion=")) {
+      const value = token.slice("--show-completion=".length);
+      return { mode: "show", shellOverride: value || void 0 };
+    }
+  }
+  return null;
+}
+function resolveShell(request, env) {
+  if (request.shellOverride) {
+    return parseShell(request.shellOverride);
+  }
+  return detectShell(env);
+}
+function handleCompletionFlag(request, deps = {}) {
+  const env = deps.environment ?? currentEnvironment();
+  const out = getStream(deps.stdout, process.stdout);
+  const err = getStream(deps.stderr, process.stderr);
+  let shell;
+  try {
+    shell = resolveShell(request, env);
+  } catch (error) {
+    const message = error instanceof CompletionShellError ? error.message : String(error);
+    err.write(`${message}
+`);
+    return 1;
+  }
+  if (request.mode === "show") {
+    out.write(renderScript(shell));
+    return 0;
+  }
+  try {
+    const result = installCompletion(shell, env);
+    err.write(`zinkee completion installed for ${shell}.
+`);
+    err.write(`  script: ${result.scriptPath}
+`);
+    if (result.rcPath && result.rcPath !== result.scriptPath) {
+      err.write(
+        result.rcUpdated ? `  updated: ${result.rcPath}
+` : `  unchanged: ${result.rcPath}
+`
+      );
+    }
+    err.write(`Restart your shell or open a new session to enable completion.
+`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    err.write(`Failed to install zinkee completion: ${message}
+`);
+    return 1;
+  }
+}
+
 // src/cli-runner.ts
 var ExampleDisplayed = class extends Error {
   name = "ExampleDisplayed";
@@ -10998,7 +11703,19 @@ function isExecutedAsEntry(argvEntry, moduleUrl) {
 }
 async function runCli(argv) {
   try {
-    const exampleRequest = extractExampleRequest(argv);
+    if (isCompletionRequest()) {
+      runCompletionRequest();
+      return;
+    }
+    const completionFlag = extractCompletionFlag(argv);
+    if (completionFlag) {
+      const exitCode = handleCompletionFlag(completionFlag);
+      process.exitCode = exitCode;
+      return;
+    }
+    const program = buildProgram();
+    const optionMeta = buildOptionMetadata(program);
+    const exampleRequest = extractExampleRequest(argv, optionMeta);
     if (exampleRequest) {
       await showExamples(
         exampleRequest.commandName,
@@ -11012,7 +11729,8 @@ async function runCli(argv) {
       );
       throw new ExampleDisplayed();
     }
-    await buildProgram().parseAsync(argv);
+    const rewrittenArgv = hoistGlobalOptions(argv, optionMeta, commandRegistry);
+    await program.parseAsync(rewrittenArgv);
   } catch (error) {
     if (error instanceof ExampleDisplayed) {
       process.exitCode = 0;