zinkee 0.1.11 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zinkee",
-  "version": "0.1.11",
+  "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,6 +4,7 @@ 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,
@@ -11,6 +12,10 @@ import {
   runCompletionRequest,
 } from "./completion/runtime.js";
 import { buildProgram } from "./program.js";
+import {
+  buildOptionMetadata,
+  hoistGlobalOptions,
+} from "./utils/argv-rewrite.js";
 import {
   formatCliErrorJson,
   formatCliErrorText,
@@ -55,7 +60,9 @@ export async function runCli(argv: string[]): Promise<void> {
       return;
     }
 
-    const exampleRequest = extractExampleRequest(argv);
+    const program = buildProgram();
+    const optionMeta = buildOptionMetadata(program);
+    const exampleRequest = extractExampleRequest(argv, optionMeta);
 
     if (exampleRequest) {
       await showExamples(
@@ -71,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/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/utils/argv-rewrite.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+
+import { commandRegistry } from "../command-registry.js";
+import { buildProgram } from "../program.js";
+import {
+  buildOptionMetadata,
+  hoistGlobalOptions,
+} from "./argv-rewrite.js";
+
+function rewrite(userArgs: readonly string[]): string[] {
+  const optionMeta = buildOptionMetadata(buildProgram());
+  return hoistGlobalOptions(["node", "zinkee", ...userArgs], optionMeta, commandRegistry);
+}
+
+describe("hoistGlobalOptions", () => {
+  it("moves boolean global flags before the subcommand path", () => {
+    expect(rewrite(["schemas", "list", "--json"])).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("moves global value flags together with their value", () => {
+    expect(rewrite(["schemas", "list", "--profile", "staging"])).toEqual([
+      "node",
+      "zinkee",
+      "--profile",
+      "staging",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("moves multiple globals preserving their relative order", () => {
+    expect(
+      rewrite(["schemas", "list", "--json", "--profile", "staging", "--read-only"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "--profile",
+      "staging",
+      "--read-only",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("hoists globals that are interleaved between subcommand path tokens", () => {
+    expect(rewrite(["schemas", "--json", "fields", "create"])).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "fields",
+      "create",
+    ]);
+  });
+
+  it("does not touch global flags that already appear before the subcommand path", () => {
+    expect(rewrite(["--json", "schemas", "list"])).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("preserves --api-key when it appears after profiles add (subcommand-local option)", () => {
+    expect(
+      rewrite(["profiles", "add", "myProfile", "--api-key", "abc", "--base-url", "https://x"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "profiles",
+      "add",
+      "myProfile",
+      "--api-key",
+      "abc",
+      "--base-url",
+      "https://x",
+    ]);
+  });
+
+  it("preserves --api-key/--base-url for profiles update while still hoisting other globals", () => {
+    expect(
+      rewrite(["profiles", "update", "myProfile", "--api-key", "abc", "--json"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "--json",
+      "profiles",
+      "update",
+      "myProfile",
+      "--api-key",
+      "abc",
+    ]);
+  });
+
+  it("supports the --foo=bar syntax for global value flags", () => {
+    expect(rewrite(["schemas", "list", "--profile=staging"])).toEqual([
+      "node",
+      "zinkee",
+      "--profile=staging",
+      "schemas",
+      "list",
+    ]);
+  });
+
+  it("returns argv unchanged when no subcommand path is found", () => {
+    expect(rewrite(["--json"])).toEqual(["node", "zinkee", "--json"]);
+  });
+
+  it("respects -- and stops hoisting after it", () => {
+    expect(
+      rewrite(["schemas", "list", "--", "--json", "trailing"]),
+    ).toEqual([
+      "node",
+      "zinkee",
+      "schemas",
+      "list",
+      "--",
+      "--json",
+      "trailing",
+    ]);
+  });
+});
+
+describe("buildOptionMetadata", () => {
+  it("registers local options for leaf subcommands", () => {
+    const optionMeta = buildOptionMetadata(buildProgram());
+    const profilesAdd = optionMeta.localOptionsByCommand.get("profiles add");
+
+    expect(profilesAdd?.has("--api-key")).toBe(true);
+    expect(profilesAdd?.has("--base-url")).toBe(true);
+  });
+
+  it("recognises global value vs boolean flags", () => {
+    const optionMeta = buildOptionMetadata(buildProgram());
+
+    expect(optionMeta.valueFlags.has("--profile")).toBe(true);
+    expect(optionMeta.booleanFlags.has("--json")).toBe(true);
+    expect(optionMeta.booleanFlags.has("--read-only")).toBe(true);
+  });
+});

package/src/utils/argv-rewrite.ts

@@ -0,0 +1,269 @@
+import type { Command } from "commander";
+
+export const HOISTABLE_GLOBAL_FLAGS = {
+  "--profile": "value",
+  "--base-url": "value",
+  "--api-key": "value",
+  "--read-only": "boolean",
+  "--json": "boolean",
+} as const satisfies Record<string, "value" | "boolean">;
+
+type HoistableFlagName = keyof typeof HOISTABLE_GLOBAL_FLAGS;
+
+function isHoistableFlag(flagName: string): flagName is HoistableFlagName {
+  return Object.hasOwn(HOISTABLE_GLOBAL_FLAGS, flagName);
+}
+
+export interface OptionMetadata {
+  valueFlags: Set<string>;
+  booleanFlags: Set<string>;
+  localOptionsByCommand: Map<string, Set<string>>;
+}
+
+function getCommandPath(command: Command): string {
+  const parts: string[] = [];
+  let cursor: Command | null = command;
+  while (cursor && cursor.parent) {
+    parts.unshift(cursor.name());
+    cursor = cursor.parent;
+  }
+  return parts.join(" ");
+}
+
+export function buildOptionMetadata(program: Command): OptionMetadata {
+  const valueFlags = new Set<string>();
+  const booleanFlags = new Set<string>();
+  const localOptionsByCommand = new Map<string, Set<string>>();
+
+  function visit(command: Command, isRoot: boolean): void {
+    const localFlags = new Set<string>();
+
+    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 };
+}
+
+export function createDefaultOptionMetadata(): OptionMetadata {
+  return {
+    valueFlags: new Set([
+      "--profile",
+      "--base-url",
+      "--api-key",
+      "--install-completion",
+      "--show-completion",
+    ]),
+    booleanFlags: new Set([
+      "--read-only",
+      "--json",
+      "--example",
+      "--help",
+    ]),
+    localOptionsByCommand: new Map(),
+  };
+}
+
+interface FlagSplit {
+  flagName: string;
+  inlineValue: string | undefined;
+}
+
+function isFlagToken(token: string): boolean {
+  return token.length > 1 && token.startsWith("-");
+}
+
+function splitFlagToken(token: string): FlagSplit {
+  if (token.startsWith("--") && token.includes("=")) {
+    const eqIdx = token.indexOf("=");
+    return {
+      flagName: token.slice(0, eqIdx),
+      inlineValue: token.slice(eqIdx + 1),
+    };
+  }
+  return { flagName: token, inlineValue: undefined };
+}
+
+function flagConsumesValue(flagName: string, optionMeta: OptionMetadata): boolean {
+  if (optionMeta.valueFlags.has(flagName)) {
+    return true;
+  }
+  if (optionMeta.booleanFlags.has(flagName)) {
+    return false;
+  }
+  return true;
+}
+
+interface OperandPosition {
+  index: number;
+  token: string;
+}
+
+export function collectOperandTokens(
+  userArgs: readonly string[],
+  optionMeta: OptionMetadata,
+  options: { skipFlag?: string } = {},
+): OperandPosition[] {
+  const operands: OperandPosition[] = [];
+  let i = 0;
+  while (i < userArgs.length) {
+    const token = userArgs[i] as string;
+
+    if (token === "--") {
+      break;
+    }
+
+    if (isFlagToken(token)) {
+      const { flagName, inlineValue } = splitFlagToken(token);
+
+      if (options.skipFlag !== undefined && flagName === options.skipFlag) {
+        i += 1;
+        continue;
+      }
+
+      if (inlineValue !== undefined) {
+        i += 1;
+        continue;
+      }
+
+      const consumes = flagConsumesValue(flagName, optionMeta);
+      const next = userArgs[i + 1];
+      if (consumes && next !== undefined && !isFlagToken(next)) {
+        i += 2;
+      } else {
+        i += 1;
+      }
+      continue;
+    }
+
+    operands.push({ index: i, token });
+    i += 1;
+  }
+  return operands;
+}
+
+export interface CommandPathMatch {
+  commandName: string;
+  firstArgvIndex: number;
+  lastArgvIndex: number;
+}
+
+export function findCommandPath(
+  operands: readonly OperandPosition[],
+  registry: Record<string, unknown>,
+): CommandPathMatch | null {
+  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;
+}
+
+export function hoistGlobalOptions(
+  argv: readonly string[],
+  optionMeta: OptionMetadata,
+  registry: Record<string, unknown>,
+): string[] {
+  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) ?? new Set<string>();
+
+  const hoisted: string[] = [];
+  const remaining: string[] = [];
+  let i = 0;
+
+  while (i < userArgs.length) {
+    const token = userArgs[i] as string;
+
+    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 === undefined) {
+      const next = userArgs[i + 1];
+      if (next !== undefined && !isFlagToken(next)) {
+        target.push(next);
+        i += 2;
+        continue;
+      }
+    }
+
+    i += 1;
+  }
+
+  return [argv[0] as string, argv[1] as string, ...hoisted, ...remaining];
+}