zinkee 0.1.11 → 0.1.15

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

package/src/utils/examples.ts

@@ -411,11 +411,11 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     {
       description: "Patch formula field (formula text).",
       command:
-        `zinkee --json schemas fields update contacts formula-total --raw '{"type":"FormulaField","config":{"formulaText":"amount * 1.10","uiFormatKind":"number","status":"ACTIVE","numberFormatOptions":{"format":"number","decimals":2,"thousandsSeparator":true},"conditionalFormatting":[]}}'`,
+        `zinkee --json schemas fields update contacts formula-total --raw '{"type":"FormulaField","config":{"formulaText":"c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.10","uiFormatKind":"number","status":"ACTIVE","numberFormatOptions":{"format":"number","decimals":2,"thousandsSeparator":true},"conditionalFormatting":[]}}'`,
       raw: `{
   "type": "FormulaField",
   "config": {
-    "formulaText": "amount * 1.10",
+    "formulaText": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.10",
     "uiFormatKind": "number",
     "status": "ACTIVE",
     "numberFormatOptions": {
@@ -1398,9 +1398,9 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Create a bar CHART widget with a time-serie x-axis and two y-axis series.",
+      description: "Create a bars CHART widget with a time-serie x-axis and two y-axis series.",
       command:
-        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bar --x-axis-field due-date --x-axis-date-format MONTH --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"BAR"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"LINE"}' --legend '{"position":"bottom"}'`,
+        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
       raw: `{
   "type": "CHART",
   "source": {
@@ -1412,7 +1412,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   },
   "presentation": { "name": "Revenue by month" },
   "chart": {
-    "chartType": "bar",
+    "chartType": "bars",
     "xAxisFieldId": "due-date",
     "xAxisDateFormat": "MONTH",
     "xAxisAsTimeSerie": true,
@@ -1421,13 +1421,13 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#4B9CD3",
-        "axisType": "BAR"
+        "axisType": "PRIMARY"
       },
       {
         "typeCalc": "COUNT",
         "fieldCalc": "id",
         "color": "#E57373",
-        "axisType": "LINE"
+        "axisType": "SECONDARY"
       }
     ],
     "legend": { "position": "bottom" }
@@ -1582,12 +1582,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Replace the chart series with a weekly line.",
+      description: "Replace the chart series with weekly lines.",
       command:
-        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type line --x-axis-field due-date --x-axis-date-format WEEK --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"LINE"}'`,
+        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 22222222-2222-4222-a222-222222222222 --chart-type lines --x-axis-field due-date --x-axis-date-format WEEK --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#2E7D32","axisType":"PRIMARY"}'`,
       raw: `{
   "chart": {
-    "chartType": "line",
+    "chartType": "lines",
     "xAxisFieldId": "due-date",
     "xAxisDateFormat": "WEEK",
     "xAxisAsTimeSerie": true,
@@ -1596,7 +1596,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#2E7D32",
-        "axisType": "LINE"
+        "axisType": "PRIMARY"
       }
     ]
   }
@@ -1932,7 +1932,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "amount * 1.21",
+        "formulaText": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
         "uiFormatKind": "number",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -1947,12 +1947,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     {
       "id": "6d7e8f90-1234-5678-9abc-def012345678",
       "type": "FormulaField",
-      "slug": "formula-deadline",
-      "label": "Computed Deadline",
+      "slug": "formula-period",
+      "label": "Formula Period",
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "addDays(startDate, 7)",
+        "formulaText": "date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, \"AAAA-MM\")",
         "uiFormatKind": "date",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -2234,6 +2234,17 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       response: `{
   "recordId": "550e8400-e29b-41d4-a716-446655440000",
   "deleted": true
+}`,
+    },
+  ]),
+  "records clear": buildCommandExamples([
+    {
+      description:
+        "Delete every record from a schema's table. Heritage rules (CASCADE / SET NULL) propagate to child schemas asynchronously via the CDC pipeline.",
+      command: "zinkee --json records clear contacts",
+      response: `{
+  "schemaId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+  "cleared": true
 }`,
     },
   ]),
@@ -3353,7 +3364,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       description:
         "Add a search-records action whose condition pulls its value from the trigger payload using --condition-json.",
       command:
-        `zinkee --json automations actions add automation-1 --type search_records --name "Find duplicates" --target-schema followups --condition-json '{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'`,
+        `zinkee --json automations actions add automation-1 --type search_records --name "Find duplicates" --target-schema followups --condition-json '{"field":"email","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"f1e1d000-0000-0000-0000-000000000005"}}]}'`,
       raw: `{
   "type": "search_records",
   "name": "Find duplicates",
@@ -3368,7 +3379,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "f1e1d000-0000-0000-0000-000000000005"
             }
           }
         ]
@@ -3965,7 +3976,7 @@ async function buildDynamicAutomationExamples(
         {
           description:
             `Add a create-record action with literal and trigger-based mappings targeting ${schemaField.schemaRef}.`,
-          command: `zinkee --json automations actions add ${automationId} --type create_record --name "Create follow-up order" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=pending --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}'`,
+          command: `zinkee --json automations actions add ${automationId} --type create_record --name "Create follow-up order" --target-schema ${schemaField.schemaRef} --map ${schemaField.fieldRef}=pending --map-json owner='{"rawValue":null,"source":{"type":"TRIGGER","id":"${schemaField.fieldId}"}}'`,
           raw: `{
   "type": "create_record",
   "name": "Create follow-up order",
@@ -3980,7 +3991,7 @@ async function buildDynamicAutomationExamples(
         "rawValue": null,
         "source": {
           "type": "TRIGGER",
-          "id": "payload_value"
+          "id": "${schemaField.fieldId}"
         }
       }
     }
@@ -4008,7 +4019,7 @@ async function buildDynamicAutomationExamples(
         },
         {
           description: `Add a search-records action with a trigger-based condition on ${schemaField.schemaRef}.`,
-          command: `zinkee --json automations actions add ${automationId} --type search_records --name "Find duplicates" --target-schema ${schemaField.schemaRef} --condition-json '{"field":"${schemaField.fieldRef}","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"payload_value"}}]}'`,
+          command: `zinkee --json automations actions add ${automationId} --type search_records --name "Find duplicates" --target-schema ${schemaField.schemaRef} --condition-json '{"field":"${schemaField.fieldRef}","comparator":"eq","values":[{"rawValue":null,"source":{"type":"TRIGGER","id":"${schemaField.fieldId}"}}]}'`,
           raw: `{
   "type": "search_records",
   "name": "Find duplicates",
@@ -4023,7 +4034,7 @@ async function buildDynamicAutomationExamples(
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "${schemaField.fieldId}"
             }
           }
         ]

package/src/utils/schema-fields.ts

@@ -450,17 +450,18 @@ const fieldTypeDefinitions = [
     aliases: ["formula", "FormulaField"],
     description: "Calculated field from a formula.",
     rawShape:
-      '{"type":"FormulaField","slug":"formula-summary","label":"Formula Summary","config":{"formulaText":"concat(firstName, \' \', lastName)","uiFormatKind":"none"}}',
+      '{"type":"FormulaField","slug":"formula-code","label":"Formula Code","config":{"formulaText":"concat(\\"CUST-\\", f1e1d000-0000-0000-0000-000000000005)","uiFormatKind":"none"}}',
     examplePayloads: [
       {
         name: "Formula field (none)",
         payload: {
           type: "FormulaField",
-          slug: "formula-summary",
-          label: "Formula Summary",
+          slug: "formula-code",
+          label: "Formula Code",
           required: false,
           config: {
-            formulaText: "concat(firstName, ' ', lastName)",
+            formulaText:
+              'concat("CUST-", f1e1d000-0000-0000-0000-000000000005)',
             uiFormatKind: "none",
             status: "ACTIVE",
             conditionalFormatting: [],
@@ -475,7 +476,7 @@ const fieldTypeDefinitions = [
           label: "Formula Total",
           required: false,
           config: {
-            formulaText: "amount * 1.21",
+            formulaText: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
             uiFormatKind: "number",
             status: "ACTIVE",
             numberFormatOptions: {
@@ -491,11 +492,12 @@ const fieldTypeDefinitions = [
         name: "Formula field (date)",
         payload: {
           type: "FormulaField",
-          slug: "formula-deadline",
-          label: "Computed Deadline",
+          slug: "formula-period",
+          label: "Formula Period",
           required: false,
           config: {
-            formulaText: "addDays(startDate, 7)",
+            formulaText:
+              'date_format(d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90, "AAAA-MM")',
             uiFormatKind: "date",
             status: "ACTIVE",
             dateFormatOptions: {
@@ -515,7 +517,7 @@ const fieldTypeDefinitions = [
           label: "Computed Assignee",
           required: false,
           config: {
-            formulaText: "manager",
+            formulaText: "a7b8c9d0-e1f2-3a4b-5c6d-7e8f90123456",
             uiFormatKind: "member",
             status: "ACTIVE",
             conditionalFormatting: [],