zinkee 0.1.11 → 0.1.15

package/package.json

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

package/src/api/records.ts

@@ -133,6 +133,13 @@ export class RecordsApi {
     );
   }
 
+  clearRecords(schema: NormalizedUuidOrSlug): Promise<Record<string, unknown>> {
+    return this.client.requestJson<Record<string, unknown>>(
+      `/api/v2/schemas/${selectorValue(schema)}/records:clear`,
+      { method: "DELETE" },
+    );
+  }
+
   private normalizeQueryInput(query: RecordQueryInput): Record<string, unknown> {
     const where = query.where?.map((expression) => ({
       field: expression.field,

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/command-registry.ts

@@ -665,6 +665,13 @@ export const commandRegistry = {
     supportsRaw: false,
     output: writeOutput,
   },
+  "records clear": {
+    command: "records clear",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput,
+  },
   "comments list": {
     command: "comments list",
     accessLevel: "read",

package/src/commands/automations.test.ts

@@ -335,7 +335,7 @@ describe("automations commands", () => {
       "--target-schema",
       "schema-1",
       "--map-json",
-      'owner={"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}',
+      'owner={"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}',
     ]);
 
     expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
@@ -348,7 +348,7 @@ describe("automations commands", () => {
             rawValue: null,
             source: {
               type: "TRIGGER",
-              id: "payload_value",
+              id: "f1e1d000-0000-0000-0000-000000000005",
             },
           },
         },
@@ -378,7 +378,7 @@ describe("automations commands", () => {
       "--target-schema",
       "schema-1",
       "--condition-json",
-      '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}',
+      '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}]}',
     ]);
 
     expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toEqual({
@@ -395,7 +395,7 @@ describe("automations commands", () => {
                 rawValue: null,
                 source: {
                   type: "TRIGGER",
-                  id: "payload_value",
+                  id: "f1e1d000-0000-0000-0000-000000000005",
                 },
               },
             ],
@@ -471,7 +471,7 @@ describe("automations commands", () => {
         "--trigger-field",
         "field-1",
         "--condition-json",
-        '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}',
+        '{"field":"status","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}]}',
       ]),
     ).rejects.toThrowError('Expected trigger condition 1 value 1 to use only literal "rawValue" values.');
 

package/src/commands/displays.test.ts

@@ -151,7 +151,7 @@ describe("displays commands", () => {
       "--name",
       "Revenue",
       "--chart-type",
-      "bar",
+      "bars",
     ]);
 
     const init = fetchMock.mock.calls[0]?.[1];
@@ -159,7 +159,7 @@ describe("displays commands", () => {
     expect(JSON.parse(String(init?.body))).toMatchObject({
       type: "CHART",
       presentation: { name: "Revenue" },
-      chart: { chartType: "bar" },
+      chart: { chartType: "bars" },
     });
     expect(JSON.parse(output.read())).toEqual({
       data: { displayId: "display-1", widgetId: "widget-1" },

package/src/commands/records.test.ts

@@ -364,4 +364,62 @@ describe("records commands", () => {
 
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  it("clears all records in a schema", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    mockSchemaLookup(fetchMock);
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        schemaId: "schema-1",
+        cleared: true,
+      }),
+    );
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "records",
+      "clear",
+      "contacts",
+    ]);
+
+    const init = fetchMock.mock.calls[1]?.[1];
+
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://api.zinkee.test/api/v2/schemas/schema-1/records:clear",
+    );
+    expect(init?.method).toBe("DELETE");
+    expect(init?.body).toBeUndefined();
+
+    const payload = JSON.parse(output.read());
+
+    expect(payload.data).toEqual({
+      schemaId: "schema-1",
+      cleared: true,
+    });
+  });
+
+  it("blocks records clear in read-only mode", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--read-only",
+        "records",
+        "clear",
+        "contacts",
+      ]),
+    ).rejects.toThrowError('Command "records clear" is not allowed in read-only mode.');
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
 });

package/src/commands/records.ts

@@ -723,4 +723,23 @@ export function registerRecordsCommands(
 
       writeLine(stdout, `Deleted record "${record.value}" from schema "${schema.value}".`);
     });
+
+  records
+    .command("clear")
+    .description("Delete all records from a schema's table")
+    .argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, schema: NormalizedUuidOrSlug) {
+      const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
+      ensureWritable("records clear", readOnly, "destructive");
+      const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+
+      const data = await api.clearRecords(resolvedSchema);
+
+      if (json) {
+        emitJson(stdout, "records clear", data, filePath);
+        return;
+      }
+
+      writeLine(stdout, `Cleared all records from schema "${schema.value}".`);
+    });
 }

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);
+  });
+});