zinkee 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "CLI for Zinkee API v2",
   "type": "module",
   "bin": {

package/src/cli-examples.ts

@@ -1,4 +1,10 @@
 import { commandRegistry } from "./command-registry.js";
+import {
+  collectOperandTokens,
+  createDefaultOptionMetadata,
+  findCommandPath,
+  type OptionMetadata,
+} from "./utils/argv-rewrite.js";
 import { CliError } from "./utils/errors.js";
 import { getResolvedCommandExamples } from "./utils/examples.js";
 import { buildJsonSuccess } from "./utils/output.js";
@@ -24,34 +30,6 @@ function getStdout(stdout?: CommandIo): CommandIo {
   return stdout ?? process.stdout;
 }
 
-function resolveExampleCommand(tokens: readonly string[]): {
-  commandName: string;
-  remainingTokens: readonly string[];
-} {
-  const commands = Object.keys(commandRegistry).sort(
-    (left, right) => right.split(" ").length - left.split(" ").length,
-  );
-
-  for (const commandName of commands) {
-    const commandTokens = commandName.split(" ");
-    const matches = commandTokens.every((token, index) => tokens[index] === token);
-
-    if (matches) {
-      return {
-        commandName,
-        remainingTokens: tokens.slice(commandTokens.length),
-      };
-    }
-  }
-
-  const commandTokens = tokens.filter((token) => !token.startsWith("-"));
-
-  return {
-    commandName: commandTokens.join(" "),
-    remainingTokens: [],
-  };
-}
-
 function extractExampleFilters(tokens: readonly string[]): { type?: string } {
   const filters: { type?: string } = {};
 
@@ -110,22 +88,26 @@ function extractExampleOverrides(tokens: readonly string[]): {
   return overrides;
 }
 
-export function extractExampleRequest(argv: readonly string[]): ExampleRequest | null {
-  const exampleIndex = argv.indexOf("--example");
-
-  if (exampleIndex === -1) {
+export function extractExampleRequest(
+  argv: readonly string[],
+  optionMeta: OptionMetadata = createDefaultOptionMetadata(),
+): ExampleRequest | null {
+  if (!argv.includes("--example")) {
     return null;
   }
 
-  const requestTokens = argv.slice(exampleIndex + 1);
-  const { commandName, remainingTokens } = resolveExampleCommand(requestTokens);
+  const userArgs = argv.slice(2);
+  const operands = collectOperandTokens(userArgs, optionMeta, { skipFlag: "--example" });
+  const cmdPath = findCommandPath(operands, commandRegistry);
 
-  if (commandName.length === 0) {
+  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"),

package/src/cli-runner.ts

@@ -4,7 +4,18 @@ import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 
 import { extractExampleRequest, showExamples } from "./cli-examples.js";
+import { commandRegistry } from "./command-registry.js";
+import {
+  extractCompletionFlag,
+  handleCompletionFlag,
+  isCompletionRequest,
+  runCompletionRequest,
+} from "./completion/runtime.js";
 import { buildProgram } from "./program.js";
+import {
+  buildOptionMetadata,
+  hoistGlobalOptions,
+} from "./utils/argv-rewrite.js";
 import {
   formatCliErrorJson,
   formatCliErrorText,
@@ -37,7 +48,21 @@ export function isExecutedAsEntry(argvEntry: string | undefined, moduleUrl: stri
 
 export async function runCli(argv: string[]): Promise<void> {
   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(
@@ -53,7 +78,8 @@ export async function runCli(argv: string[]): Promise<void> {
       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;

package/src/completion/engine.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+
+import { buildProgram } from "../program.js";
+import { getCompletions } from "./engine.js";
+
+const NEVER_READ_PROFILES = (): readonly string[] => [];
+
+describe("completion engine", () => {
+  it("suggests top-level subcommands and inherited globals", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", ""], cwordIndex: 1 },
+      { readProfileNames: NEVER_READ_PROFILES },
+    );
+
+    expect(result).toContain("schemas");
+    expect(result).toContain("automations");
+    expect(result).toContain("--json");
+    expect(result).toContain("--profile");
+    expect(result).toContain("--help");
+  });
+
+  it("filters subcommands by prefix", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "sch"], cwordIndex: 1 },
+      { readProfileNames: NEVER_READ_PROFILES },
+    );
+
+    expect(result).toEqual(["schemas"]);
+  });
+
+  it("descends into subcommands", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "schemas", ""], cwordIndex: 2 },
+      { readProfileNames: NEVER_READ_PROFILES },
+    );
+
+    expect(result).toContain("list");
+    expect(result).toContain("get");
+    expect(result).toContain("create");
+    expect(result).toContain("fields");
+  });
+
+  it("descends into nested subcommands", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "schemas", "fields", ""], cwordIndex: 3 },
+      { readProfileNames: NEVER_READ_PROFILES },
+    );
+
+    expect(result).toContain("list");
+    expect(result).toContain("create");
+    expect(result).toContain("update");
+    expect(result).toContain("delete");
+  });
+
+  it("only suggests long flags when the current token starts with --", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "schemas", "list", "--"], cwordIndex: 3 },
+      { readProfileNames: NEVER_READ_PROFILES },
+    );
+
+    expect(result.every((candidate) => candidate.startsWith("--"))).toBe(true);
+    expect(result).toContain("--json");
+    expect(result).toContain("--profile");
+  });
+
+  it("skips flag tokens when descending into the command tree", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      {
+        words: ["zinkee", "--profile", "prod", "schemas", ""],
+        cwordIndex: 4,
+      },
+      { readProfileNames: NEVER_READ_PROFILES },
+    );
+
+    expect(result).toContain("list");
+    expect(result).toContain("fields");
+  });
+
+  it("returns profile names when the previous token is --profile", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "--profile", ""], cwordIndex: 2 },
+      { readProfileNames: () => ["alpha", "beta"] },
+    );
+
+    expect(result).toEqual(["alpha", "beta"]);
+  });
+
+  it("filters profile names by prefix", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "--profile", "be"], cwordIndex: 2 },
+      { readProfileNames: () => ["alpha", "beta"] },
+    );
+
+    expect(result).toEqual(["beta"]);
+  });
+
+  it("does not crash when profile reader throws", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "--profile", ""], cwordIndex: 2 },
+      {
+        readProfileNames: () => {
+          throw new Error("config unreadable");
+        },
+      },
+    );
+
+    expect(result).toEqual([]);
+  });
+
+  it("ignores hidden and unknown subcommands", () => {
+    const program = buildProgram();
+    const result = getCompletions(
+      program,
+      { words: ["zinkee", "no-such-thing", ""], cwordIndex: 2 },
+      { readProfileNames: NEVER_READ_PROFILES },
+    );
+
+    expect(result).toContain("schemas");
+  });
+});

package/src/completion/engine.ts

@@ -0,0 +1,168 @@
+import type { Command } from "commander";
+
+import { readConfigIfExists } from "../config.js";
+
+export interface CompletionRequest {
+  words: readonly string[];
+  cwordIndex: number;
+}
+
+export interface CompletionDeps {
+  configPath?: string;
+  readProfileNames?: (configPath: string | undefined) => readonly string[];
+}
+
+function readProfileNamesFromConfig(configPath: string | undefined): readonly string[] {
+  try {
+    const config = readConfigIfExists(configPath);
+    if (!config) {
+      return [];
+    }
+    return Object.keys(config.profiles).sort();
+  } catch {
+    return [];
+  }
+}
+
+function findSubcommand(command: Command, name: string): Command | undefined {
+  return command.commands.find((sub) => {
+    if (sub.name() === name) {
+      return true;
+    }
+    const aliases = sub.aliases();
+    return aliases.includes(name);
+  });
+}
+
+function collectFlagsThatTakeValues(root: Command): Set<string> {
+  const flags = new Set<string>();
+  const walk = (command: Command): void => {
+    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: Command, words: readonly string[]): Command {
+  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: Command): readonly string[] {
+  const names: string[] = [];
+  for (const sub of command.commands) {
+    if (sub.name().startsWith("__")) {
+      continue;
+    }
+    names.push(sub.name());
+  }
+  return names;
+}
+
+function collectVisibleLongFlags(command: Command): readonly string[] {
+  const flags: string[] = [];
+  let current: Command | null = 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;
+}
+
+export function getCompletions(
+  program: Command,
+  request: CompletionRequest,
+  deps: CompletionDeps = {},
+): string[] {
+  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] : undefined;
+  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 = new Set<string>();
+
+  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();
+}

package/src/completion/install.test.ts

@@ -0,0 +1,179 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  CompletionShellError,
+  detectShell,
+  installCompletion,
+  parseShell,
+  resolveTarget,
+  type InstallEnvironment,
+} from "./install.js";
+
+const tempDirs: string[] = [];
+
+function createTempHome(): string {
+  const dir = mkdtempSync(join(tmpdir(), "zinkee-install-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function envFor(home: string, overrides: Partial<InstallEnvironment> = {}): InstallEnvironment {
+  return {
+    home,
+    platform: "linux",
+    shellEnv: "/bin/zsh",
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    rmSync(tempDirs.pop()!, { force: true, recursive: true });
+  }
+});
+
+describe("detectShell", () => {
+  it("detects zsh from $SHELL", () => {
+    expect(detectShell({ home: "", platform: "linux", shellEnv: "/usr/bin/zsh" })).toBe("zsh");
+  });
+
+  it("detects bash from $SHELL", () => {
+    expect(detectShell({ home: "", platform: "linux", shellEnv: "/bin/bash" })).toBe("bash");
+  });
+
+  it("detects fish from $SHELL", () => {
+    expect(detectShell({ home: "", platform: "linux", shellEnv: "/usr/local/bin/fish" })).toBe(
+      "fish",
+    );
+  });
+
+  it("detects powershell from pwsh", () => {
+    expect(detectShell({ home: "", platform: "linux", shellEnv: "/usr/bin/pwsh" })).toBe(
+      "powershell",
+    );
+  });
+
+  it("falls back to powershell on win32 when $SHELL is unknown", () => {
+    expect(detectShell({ home: "", platform: "win32", shellEnv: undefined })).toBe("powershell");
+  });
+
+  it("throws when shell cannot be inferred", () => {
+    expect(() =>
+      detectShell({ home: "", platform: "linux", shellEnv: "/bin/csh" }),
+    ).toThrow(CompletionShellError);
+  });
+});
+
+describe("parseShell", () => {
+  it("normalizes pwsh to powershell", () => {
+    expect(parseShell("pwsh")).toBe("powershell");
+  });
+
+  it("rejects unsupported names", () => {
+    expect(() => parseShell("nu")).toThrow(CompletionShellError);
+  });
+});
+
+describe("resolveTarget", () => {
+  it("uses $PROFILE resolver for powershell", () => {
+    const home = createTempHome();
+    const target = resolveTarget(
+      "powershell",
+      envFor(home, {
+        platform: "win32",
+        resolvePowerShellProfile: () => join(home, "Documents", "PowerShell", "profile.ps1"),
+      }),
+    );
+    expect(target.scriptPath).toBe(join(home, "Documents", "PowerShell", "profile.ps1"));
+  });
+});
+
+describe("installCompletion", () => {
+  it("installs zsh completion and updates rc with idempotent block", () => {
+    const home = createTempHome();
+    writeFileSync(join(home, ".zshrc"), "# user content\n", "utf8");
+
+    const first = installCompletion("zsh", envFor(home));
+    expect(first.rcUpdated).toBe(true);
+    const rcAfter = readFileSync(join(home, ".zshrc"), "utf8");
+    expect(rcAfter).toContain("# >>> zinkee completion >>>");
+    expect(rcAfter).toContain(`fpath=("${join(home, ".zfunc")}" $fpath)`);
+    expect(rcAfter).toContain("autoload -Uz compinit && compinit");
+    expect(rcAfter).toContain("# user content");
+
+    const second = installCompletion("zsh", envFor(home));
+    expect(second.rcUpdated).toBe(false);
+    const rcSecond = readFileSync(join(home, ".zshrc"), "utf8");
+    const beginCount = (rcSecond.match(/# >>> zinkee completion >>>/g) ?? []).length;
+    expect(beginCount).toBe(1);
+  });
+
+  it("installs bash completion to ~/.bash_completions and sources it from .bashrc", () => {
+    const home = createTempHome();
+    const result = installCompletion("bash", envFor(home, { shellEnv: "/bin/bash" }));
+    expect(result.scriptPath).toBe(join(home, ".bash_completions", "zinkee.sh"));
+    expect(result.rcPath).toBe(join(home, ".bashrc"));
+
+    const rc = readFileSync(join(home, ".bashrc"), "utf8");
+    expect(rc).toContain(`source "${join(home, ".bash_completions", "zinkee.sh")}"`);
+
+    const script = readFileSync(result.scriptPath, "utf8");
+    expect(script).toContain("complete -o default -F _zinkee_completion zinkee");
+  });
+
+  it("installs fish completion without touching any rc file", () => {
+    const home = createTempHome();
+    const result = installCompletion("fish", envFor(home, { shellEnv: "/usr/bin/fish" }));
+    expect(result.scriptPath).toBe(
+      join(home, ".config", "fish", "completions", "zinkee.fish"),
+    );
+    expect(result.rcUpdated).toBe(false);
+
+    const script = readFileSync(result.scriptPath, "utf8");
+    expect(script).toContain("complete --no-files --command zinkee");
+  });
+
+  it("inlines powershell completion inside the resolved $PROFILE", () => {
+    const home = createTempHome();
+    const profilePath = join(home, "Documents", "PowerShell", "profile.ps1");
+    const result = installCompletion(
+      "powershell",
+      envFor(home, {
+        platform: "win32",
+        shellEnv: undefined,
+        resolvePowerShellProfile: () => profilePath,
+      }),
+    );
+
+    expect(result.scriptPath).toBe(profilePath);
+    const content = readFileSync(profilePath, "utf8");
+    expect(content).toContain("# >>> zinkee completion >>>");
+    expect(content).toContain("Register-ArgumentCompleter -Native -CommandName zinkee");
+  });
+
+  it("replaces an existing block instead of appending a new one", () => {
+    const home = createTempHome();
+    writeFileSync(
+      join(home, ".zshrc"),
+      [
+        "# top",
+        "# >>> zinkee completion >>>",
+        "stale-content",
+        "# <<< zinkee completion <<<",
+        "# bottom",
+      ].join("\n") + "\n",
+      "utf8",
+    );
+
+    installCompletion("zsh", envFor(home));
+    const rc = readFileSync(join(home, ".zshrc"), "utf8");
+    expect(rc).not.toContain("stale-content");
+    expect(rc).toContain("# top");
+    expect(rc).toContain("# bottom");
+    expect((rc.match(/# >>> zinkee completion >>>/g) ?? []).length).toBe(1);
+  });
+});