zinkee 0.1.10 → 0.1.11

package/.claude/settings.local.json

@@ -10,7 +10,35 @@
       "Read(//home/guillermo/dev/z2-backend/**)",
       "Bash(grep *)",
       "Bash(npx vitest *)",
-      "Bash(npx tsx *)"
+      "Bash(npx tsx *)",
+      "Bash(node dist/index.js --help)",
+      "Bash(gh repo *)",
+      "WebFetch(domain:github.com)",
+      "Bash(git config *)",
+      "Read(//home/guillermo/.config/**)",
+      "Read(//home/guillermo/**)",
+      "Bash(curl *)",
+      "Bash(node dist/index.js --show-completion zsh)",
+      "Bash(node *)",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee\" COMP_CWORD=1 node *)",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas\" COMP_CWORD=2 node *)",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas fields\" COMP_CWORD=3 node dist/index.js)",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas fields cr\" COMP_CWORD=3 node dist/index.js)",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas list --j\" COMP_CWORD=3 node dist/index.js)",
+      "Bash(rm -rf /tmp/zinkee-install)",
+      "Bash(mkdir -p /tmp/zinkee-install)",
+      "Bash(HOME=/tmp/zinkee-install SHELL=/bin/zsh node dist/index.js --install-completion)",
+      "Read(//tmp/**)",
+      "Read(//tmp/zinkee-install/**)",
+      "Bash(rm -rf /tmp/zinkee-install-bash)",
+      "Bash(mkdir -p /tmp/zinkee-install-bash)",
+      "Bash(HOME=/tmp/zinkee-install-bash SHELL=/bin/bash node dist/index.js --install-completion)",
+      "Bash(rm -rf /tmp/zinkee-install-fish)",
+      "Bash(mkdir -p /tmp/zinkee-install-fish)",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete node dist/index.js)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee schemas\" COMP_CWORD=abc node dist/index.js)",
+      "Bash(_ZINKEE_COMPLETE=zsh_complete COMP_WORDS=\"zinkee config show --foo --bar baz quux ?\" COMP_CWORD=10 node dist/index.js)"
     ]
   }
 }

package/AGENTS.md

@@ -45,6 +45,7 @@ Use this order when reasoning about behavior:
 - JSON/table output helpers live in `src/utils/output.ts`
 - shared CLI error handling lives in `src/utils/errors.ts`
 - parsers live in `src/parsers`
+- shell completion (engine, scripts, install, runtime) lives in `src/completion`
 
 ## Testing
 

package/README.md

@@ -68,6 +68,18 @@ base_url = "https://api.zinkee.com"
 | `--read-only` | Run in read-only mode |
 | `--example` | Show examples for a command |
 | `--json` | Emit JSON output |
+| `--install-completion [shell]` | Install shell completion (bash, zsh, fish, powershell) |
+| `--show-completion [shell]` | Print the completion script to stdout |
+
+## Shell completion
+
+```bash
+zinkee --install-completion          # auto-detects $SHELL and installs
+zinkee --install-completion zsh      # force a specific shell
+zinkee --show-completion zsh         # print the script (for inspection)
+```
+
+After installing, restart your shell.
 
 ## Runtime Resolution
 

package/dist/index.js

@@ -10961,7 +10961,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 +10976,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,6 +11531,16 @@ function isExecutedAsEntry(argvEntry, moduleUrl) {
 }
 async function runCli(argv) {
   try {
+    if (isCompletionRequest()) {
+      runCompletionRequest();
+      return;
+    }
+    const completionFlag = extractCompletionFlag(argv);
+    if (completionFlag) {
+      const exitCode = handleCompletionFlag(completionFlag);
+      process.exitCode = exitCode;
+      return;
+    }
     const exampleRequest = extractExampleRequest(argv);
     if (exampleRequest) {
       await showExamples(