zinkee 0.1.12 → 0.1.15

package/AGENTS.md

@@ -50,3 +50,45 @@ Use this order when reasoning about behavior:
 ## Testing
 
 Prefer focused command tests and parser/client unit tests.
+
+> **Unit tests use `fetchMock` and never hit the real API.** When changing the
+> shape of a payload (enum values, property names, structure), unit tests will
+> still pass even if the real API would reject the request with `400`. For
+> shape-sensitive changes — especially edits to strings in `src/utils/examples.ts`
+> — also run the resulting command against a real workspace and confirm the API
+> accepts it.
+
+## Contributing
+
+### Branches
+
+- `feature/eng-<ticket>-<slug>` for Linear-tracked work
+- `fix/<slug>` / `chore/<slug>` / `docs/<slug>` for untracked work
+- Never push to `main` directly; always open a PR
+
+### Commits
+
+- Conventional Commits format: `<type>(<scope>): <subject>` (e.g.
+  `fix(displays): correct chart-type values in widget examples`)
+- Subject in imperative mood, under ~72 chars, no trailing period
+- Body explains the *why*, not the *what* — the diff already shows what changed
+- Stage files explicitly (`git add <path>`); never `git add -A`
+- Don't add `Co-Authored-By:` trailers; existing history doesn't use them
+
+### Before committing
+
+1. `npm run typecheck` — must pass
+2. `npm test` — must pass
+3. For changes that affect runtime behaviour or `--example` output, also
+   exercise the affected commands against a live workspace (see Testing note
+   above).
+
+### Versioning
+
+- Versioning is patch-only today (`0.1.x`). Bump the patch number unless the
+  team decides to move to a different scheme.
+- Every PR that ships user-visible changes (new commands, fixed examples,
+  behaviour changes) bumps `package.json` version in the same PR — not in a
+  separate "release" PR.
+- Before bumping, fetch `origin/main` to make sure the version you pick isn't
+  already taken by another PR that merged ahead of yours.

package/README.md

@@ -273,10 +273,17 @@ zinkee records update projects <record-uuid> --set status=2
 
 # Delete
 zinkee records delete projects <record-uuid>
+
+# Clear all records from a schema (destructive — irreversible)
+zinkee records clear projects
 ```
 
 Option values are written as numbers (`--set status=1`) but returned as strings (`"1"`). Number values are stored and returned as strings.
 
+`records clear` removes every record from the schema's table. Heritage rules
+(`CASCADE` / `SET NULL`) propagate to child schemas asynchronously through the
+CDC pipeline, so related tables converge eventually. Blocked by `--read-only`.
+
 ---
 
 ## Files

package/dist/index.js

@@ -660,6 +660,13 @@ var 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",
@@ -2189,17 +2196,17 @@ var fieldTypeDefinitions = [
     className: "FormulaField",
     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"}}`,
+    rawShape: '{"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: []
@@ -2214,7 +2221,7 @@ var fieldTypeDefinitions = [
           label: "Formula Total",
           required: false,
           config: {
-            formulaText: "amount * 1.21",
+            formulaText: "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
             uiFormatKind: "number",
             status: "ACTIVE",
             numberFormatOptions: {
@@ -2230,11 +2237,11 @@ var 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: {
@@ -2254,7 +2261,7 @@ var fieldTypeDefinitions = [
           label: "Computed Assignee",
           required: false,
           config: {
-            formulaText: "manager",
+            formulaText: "a7b8c9d0-e1f2-3a4b-5c6d-7e8f90123456",
             uiFormatKind: "member",
             status: "ACTIVE",
             conditionalFormatting: []
@@ -2991,11 +2998,11 @@ var specificExamples = {
     },
     {
       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":[]}}'`,
+      command: `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": {
@@ -3906,8 +3913,8 @@ var specificExamples = {
 }`
     },
     {
-      description: "Create a bar 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"}'`,
+      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 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": {
@@ -3919,7 +3926,7 @@ var specificExamples = {
   },
   "presentation": { "name": "Revenue by month" },
   "chart": {
-    "chartType": "bar",
+    "chartType": "bars",
     "xAxisFieldId": "due-date",
     "xAxisDateFormat": "MONTH",
     "xAxisAsTimeSerie": true,
@@ -3928,13 +3935,13 @@ var specificExamples = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#4B9CD3",
-        "axisType": "BAR"
+        "axisType": "PRIMARY"
       },
       {
         "typeCalc": "COUNT",
         "fieldCalc": "id",
         "color": "#E57373",
-        "axisType": "LINE"
+        "axisType": "SECONDARY"
       }
     ],
     "legend": { "position": "bottom" }
@@ -4080,11 +4087,11 @@ var specificExamples = {
 }`
     },
     {
-      description: "Replace the chart series with a weekly line.",
-      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"}'`,
+      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 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,
@@ -4093,7 +4100,7 @@ var specificExamples = {
         "typeCalc": "SUM",
         "fieldCalc": "amount",
         "color": "#2E7D32",
-        "axisType": "LINE"
+        "axisType": "PRIMARY"
       }
     ]
   }
@@ -4421,7 +4428,7 @@ var specificExamples = {
       "required": false,
       "system": false,
       "config": {
-        "formulaText": "amount * 1.21",
+        "formulaText": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043 * 1.21",
         "uiFormatKind": "number",
         "status": "ACTIVE",
         "defaultValue": null,
@@ -4436,12 +4443,12 @@ var specificExamples = {
     {
       "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,
@@ -4723,6 +4730,16 @@ var specificExamples = {
       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
 }`
     }
   ]),
@@ -5804,7 +5821,7 @@ var specificExamples = {
     },
     {
       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"}}]}'`,
+      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":"f1e1d000-0000-0000-0000-000000000005"}}]}'`,
       raw: `{
   "type": "search_records",
   "name": "Find duplicates",
@@ -5819,7 +5836,7 @@ var specificExamples = {
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "f1e1d000-0000-0000-0000-000000000005"
             }
           }
         ]
@@ -6328,7 +6345,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
       return buildCommandExamples([
         {
           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",
@@ -6343,7 +6360,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
         "rawValue": null,
         "source": {
           "type": "TRIGGER",
-          "id": "payload_value"
+          "id": "${schemaField.fieldId}"
         }
       }
     }
@@ -6370,7 +6387,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
         },
         {
           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",
@@ -6385,7 +6402,7 @@ async function buildDynamicAutomationExamples(commandName, options = {}) {
             "rawValue": null,
             "source": {
               "type": "TRIGGER",
-              "id": "payload_value"
+              "id": "${schemaField.fieldId}"
             }
           }
         ]
@@ -9773,6 +9790,12 @@ var RecordsApi = class {
       { method: "DELETE" }
     );
   }
+  clearRecords(schema) {
+    return this.client.requestJson(
+      `/api/v2/schemas/${selectorValue8(schema)}/records:clear`,
+      { method: "DELETE" }
+    );
+  }
   normalizeQueryInput(query) {
     const where = query.where?.map((expression) => ({
       field: expression.field,
@@ -10299,6 +10322,17 @@ function registerRecordsCommands(program, options = {}) {
     }
     writeLine9(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", parseUuidOrSlugSelector7).action(async function action(schema) {
+    const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
+    ensureWritable6("records clear", readOnly, "destructive");
+    const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
+    const data = await api.clearRecords(resolvedSchema);
+    if (json) {
+      emitJson9(stdout, "records clear", data, filePath);
+      return;
+    }
+    writeLine9(stdout, `Cleared all records from schema "${schema.value}".`);
+  });
 }
 
 // src/commands/schemas.ts