zinkee 0.1.10 → 0.1.12

package/src/completion/install.ts

@@ -0,0 +1,260 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+import { renderScript, type SupportedShell } from "./scripts.js";
+
+export const SUPPORTED_SHELLS: readonly SupportedShell[] = [
+  "bash",
+  "zsh",
+  "fish",
+  "powershell",
+];
+
+const BLOCK_BEGIN = "# >>> zinkee completion >>>";
+const BLOCK_END = "# <<< zinkee completion <<<";
+
+export interface InstallEnvironment {
+  home: string;
+  platform: NodeJS.Platform;
+  shellEnv: string | undefined;
+  resolvePowerShellProfile?: () => string | undefined;
+}
+
+export interface InstallTarget {
+  shell: SupportedShell;
+  scriptPath: string;
+  rcPath?: string;
+}
+
+export interface InstallResult {
+  shell: SupportedShell;
+  scriptPath: string;
+  rcPath?: string;
+  rcUpdated: boolean;
+}
+
+export class CompletionShellError extends Error {
+  override name = "CompletionShellError";
+}
+
+function defaultPowerShellProfile(env: InstallEnvironment): string | undefined {
+  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 {
+      // try the next executable
+    }
+  }
+
+  if (env.platform === "win32") {
+    return join(env.home, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1");
+  }
+  return join(env.home, ".config", "powershell", "Microsoft.PowerShell_profile.ps1");
+}
+
+export function detectShell(env: InstallEnvironment): SupportedShell {
+  const fromEnv = env.shellEnv;
+  if (fromEnv) {
+    const name = basename(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(", ")}.`,
+  );
+}
+
+export function parseShell(value: string): SupportedShell {
+  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(", ")}.`,
+  );
+}
+
+export function resolveTarget(
+  shell: SupportedShell,
+  env: InstallEnvironment,
+): InstallTarget {
+  switch (shell) {
+    case "bash":
+      return {
+        shell,
+        scriptPath: join(env.home, ".bash_completions", "zinkee.sh"),
+        rcPath: join(env.home, ".bashrc"),
+      };
+    case "zsh":
+      return {
+        shell,
+        scriptPath: join(env.home, ".zfunc", "_zinkee"),
+        rcPath: join(env.home, ".zshrc"),
+      };
+    case "fish":
+      return {
+        shell,
+        scriptPath: join(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: SupportedShell, scriptPath: string): string {
+  switch (shell) {
+    case "bash":
+      return `source "${scriptPath}"`;
+    case "zsh":
+      return [
+        `fpath=("${dirname(scriptPath)}" $fpath)`,
+        "autoload -Uz compinit && compinit",
+      ].join("\n");
+    default:
+      return "";
+  }
+}
+
+function applyBlock(existing: string, block: string): string {
+  const wrapped = `${BLOCK_BEGIN}\n${block.trimEnd()}\n${BLOCK_END}\n`;
+  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: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+function writeFileEnsuringDir(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}
+
+export function installCompletion(
+  shell: SupportedShell,
+  env: InstallEnvironment,
+): InstallResult {
+  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,
+  };
+}
+
+export function currentEnvironment(): InstallEnvironment {
+  return {
+    home: homedir(),
+    platform: platform(),
+    shellEnv: process.env.SHELL,
+  };
+}

package/src/completion/runtime.ts

@@ -0,0 +1,150 @@
+import type { Writable } from "node:stream";
+
+import { buildProgram } from "../program.js";
+import { getCompletions } from "./engine.js";
+import {
+  CompletionShellError,
+  currentEnvironment,
+  detectShell,
+  installCompletion,
+  parseShell,
+  type InstallEnvironment,
+} from "./install.js";
+import { renderScript, type SupportedShell } from "./scripts.js";
+
+export const COMPLETION_ENV_VAR = "_ZINKEE_COMPLETE";
+
+interface Stream {
+  write(chunk: string): unknown;
+}
+
+function getStream(stream: Stream | undefined, fallback: NodeJS.WriteStream): Stream {
+  return stream ?? (fallback as unknown as Writable);
+}
+
+function parseEnvWords(env: NodeJS.ProcessEnv): string[] {
+  const raw = env.COMP_WORDS ?? "";
+  if (raw.trim().length === 0) {
+    return [];
+  }
+  return raw.split(/\s+/).filter((token) => token.length > 0);
+}
+
+function parseEnvCwordIndex(env: NodeJS.ProcessEnv): number {
+  const raw = env.COMP_CWORD ?? "0";
+  const parsed = Number.parseInt(raw, 10);
+  if (Number.isNaN(parsed) || parsed < 0) {
+    return 0;
+  }
+  return parsed;
+}
+
+export function isCompletionRequest(env: NodeJS.ProcessEnv = process.env): boolean {
+  return typeof env[COMPLETION_ENV_VAR] === "string" && env[COMPLETION_ENV_VAR]!.length > 0;
+}
+
+export function runCompletionRequest(
+  env: NodeJS.ProcessEnv = process.env,
+  stdout?: Stream,
+): void {
+  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")}\n`);
+    }
+  } catch {
+    // Completion must never crash the user's shell. Swallow.
+  }
+}
+
+export interface CompletionFlagRequest {
+  mode: "install" | "show";
+  shellOverride?: string;
+}
+
+export function extractCompletionFlag(argv: readonly string[]): CompletionFlagRequest | null {
+  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 : undefined;
+      return { mode, shellOverride };
+    }
+    if (token.startsWith("--install-completion=")) {
+      const value = token.slice("--install-completion=".length);
+      return { mode: "install", shellOverride: value || undefined };
+    }
+    if (token.startsWith("--show-completion=")) {
+      const value = token.slice("--show-completion=".length);
+      return { mode: "show", shellOverride: value || undefined };
+    }
+  }
+  return null;
+}
+
+function resolveShell(
+  request: CompletionFlagRequest,
+  env: InstallEnvironment,
+): SupportedShell {
+  if (request.shellOverride) {
+    return parseShell(request.shellOverride);
+  }
+  return detectShell(env);
+}
+
+export interface CompletionFlagDeps {
+  environment?: InstallEnvironment;
+  stdout?: Stream;
+  stderr?: Stream;
+}
+
+export function handleCompletionFlag(
+  request: CompletionFlagRequest,
+  deps: CompletionFlagDeps = {},
+): number {
+  const env = deps.environment ?? currentEnvironment();
+  const out = getStream(deps.stdout, process.stdout);
+  const err = getStream(deps.stderr, process.stderr);
+
+  let shell: SupportedShell;
+  try {
+    shell = resolveShell(request, env);
+  } catch (error) {
+    const message = error instanceof CompletionShellError ? error.message : String(error);
+    err.write(`${message}\n`);
+    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}.\n`);
+    err.write(`  script: ${result.scriptPath}\n`);
+    if (result.rcPath && result.rcPath !== result.scriptPath) {
+      err.write(
+        result.rcUpdated
+          ? `  updated: ${result.rcPath}\n`
+          : `  unchanged: ${result.rcPath}\n`,
+      );
+    }
+    err.write(`Restart your shell or open a new session to enable completion.\n`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    err.write(`Failed to install zinkee completion: ${message}\n`);
+    return 1;
+  }
+}

package/src/completion/scripts.ts

@@ -0,0 +1,91 @@
+export type SupportedShell = "bash" | "zsh" | "fish" | "powershell";
+
+const PROGRAM = "zinkee";
+const ENV_VAR = "_ZINKEE_COMPLETE";
+
+export function renderBashScript(): string {
+  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}
+`;
+}
+
+export function renderZshScript(): string {
+  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
+`;
+}
+
+export function renderFishScript(): string {
+  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)'
+`;
+}
+
+export function renderPowerShellScript(): string {
+  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
+    }
+}
+`;
+}
+
+export function renderScript(shell: SupportedShell): string {
+  switch (shell) {
+    case "bash":
+      return renderBashScript();
+    case "zsh":
+      return renderZshScript();
+    case "fish":
+      return renderFishScript();
+    case "powershell":
+      return renderPowerShellScript();
+  }
+}

package/src/index.test.ts

@@ -69,6 +69,58 @@ describe("project bootstrap", () => {
     });
   });
 
+  it("extracts example requests when --example appears at the end of argv", () => {
+    expect(
+      extractExampleRequest(["node", "zinkee", "schemas", "list", "--example"]),
+    ).toEqual({
+      commandName: "schemas list",
+      filters: {},
+      overrides: {},
+      json: false,
+    });
+  });
+
+  it("extracts example filters when --example appears after the filter flags", () => {
+    expect(
+      extractExampleRequest([
+        "node",
+        "zinkee",
+        "schemas",
+        "fields",
+        "create",
+        "contacts",
+        "--type",
+        "option",
+        "--example",
+      ]),
+    ).toEqual({
+      commandName: "schemas fields create",
+      filters: { type: "option" },
+      overrides: {},
+      json: false,
+    });
+  });
+
+  it("extracts example overrides regardless of --example position", () => {
+    expect(
+      extractExampleRequest([
+        "node",
+        "zinkee",
+        "schemas",
+        "list",
+        "--profile",
+        "staging",
+        "--example",
+        "--json",
+      ]),
+    ).toEqual({
+      commandName: "schemas list",
+      filters: {},
+      overrides: { profile: "staging" },
+      json: true,
+    });
+  });
+
   it("shows field examples filtered by type", async () => {
     let output = "";
 

package/src/program.ts

@@ -40,7 +40,9 @@ export function buildProgram(options: BuildProgramOptions = {}): Command {
     .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("--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);