zinkee 0.1.38 → 0.1.39

package/package.json

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

package/src/commands/displays.test.ts

@@ -489,6 +489,147 @@ describe("displays commands", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it("translates --lock-* flags into behavior.lockedFields", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-l1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "table",
+      "--origin-resource",
+      "schema-1",
+      "--lock-field",
+      "contact-name",
+      "--lock-condition",
+      "status:invoice-number:is_empty",
+      "--lock-condition",
+      "status:amount:gte:500",
+      "--lock-message-before",
+      "status:Status locks until the invoice number is set.",
+      "--lock-message-after",
+      "status:Status is locked because the invoice number is missing.",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "TABLE_OR_SUBTABLE",
+      behavior: {
+        lockedFields: [
+          {
+            field: { fieldId: "contact-name" },
+            conditions: [],
+          },
+          {
+            field: { fieldId: "status" },
+            conditions: [
+              {
+                origin: { fieldId: "invoice-number" },
+                comparisonOperator: "IS_EMPTY",
+                values: [],
+              },
+              {
+                origin: { fieldId: "amount" },
+                comparisonOperator: "GREATER_OR_EQUAL",
+                values: ["500"],
+              },
+            ],
+            messageBeforeLock: "Status locks until the invoice number is set.",
+            messageAfterLock: "Status is locked because the invoice number is missing.",
+          },
+        ],
+      },
+    });
+  });
+
+  it("clears locked fields with --clear-locked-fields", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-l2" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "update",
+      "display-1",
+      "widget-l2",
+      "--clear-locked-fields",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.method).toBe("PATCH");
+    expect(JSON.parse(String(init?.body))).toEqual({
+      behavior: { lockedFields: [] },
+    });
+  });
+
+  it("rejects --clear-locked-fields combined with --lock-* flags", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "displays",
+        "widgets",
+        "update",
+        "display-1",
+        "widget-l3",
+        "--clear-locked-fields",
+        "--lock-field",
+        "status",
+      ]),
+    ).rejects.toThrow(/not both/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects a --lock-condition without an expression", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    const errorSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    // Option arg parser errors are handled by commander, which prints the
+    // InvalidArgumentError message to stderr and exits with code 1 (same
+    // behavior as an invalid --filter expression).
+    await expect(
+      program.parseAsync([
+        "node",
+        "zinkee",
+        "--json",
+        "displays",
+        "widgets",
+        "create",
+        "display-1",
+        "--type",
+        "table",
+        "--lock-condition",
+        "status",
+      ]),
+    ).rejects.toThrow(/process.exit/);
+    expect(errorSpy.mock.calls.flat().join("\n")).toMatch(/lockedField/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("translates --filter into the structured display filter contract", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();

package/src/commands/displays.ts

@@ -98,6 +98,11 @@ interface WidgetMutationOptions {
   hideSortButton?: boolean;
   hideFilterButton?: boolean;
   hideSeeButton?: boolean;
+  lockField?: string[];
+  lockCondition?: LockConditionOption[];
+  lockMessageBefore?: LockMessageOption[];
+  lockMessageAfter?: LockMessageOption[];
+  clearLockedFields?: boolean;
   calc?: string;
   calcField?: string;
   kpiConfig?: string;
@@ -141,6 +146,16 @@ interface WidgetMutationOptions {
   rawFile?: string;
 }
 
+interface LockConditionOption {
+  lockedField: string;
+  expression: ParsedExpression;
+}
+
+interface LockMessageOption {
+  lockedField: string;
+  message: string;
+}
+
 interface NavigationTargetMutationOptions {
   sourceWidget?: string;
   targetDisplay?: string;
@@ -275,6 +290,115 @@ function collectFilters(value: string, previous: ParsedExpression[] = []): Parse
   return [...previous, parseFilterExpression(value)];
 }
 
+function parseLockConditionOption(input: string): LockConditionOption {
+  const trimmed = input.trim();
+  let lockedField: string;
+  let expressionText: string;
+
+  if (trimmed.includes(":") && !trimmed.includes(" ")) {
+    const separatorIndex = trimmed.indexOf(":");
+    lockedField = trimmed.slice(0, separatorIndex).trim();
+    expressionText = trimmed.slice(separatorIndex + 1).trim();
+  } else {
+    const parts = trimmed.split(/\s+/);
+    lockedField = parts[0]?.trim() ?? "";
+    expressionText = parts.slice(1).join(" ").trim();
+  }
+
+  if (!lockedField || !expressionText) {
+    throw new InvalidArgumentError(
+      'Expected "<lockedField>:<field>:<comparator>[:<value>]" (or space-separated), e.g. "status:invoice-number:is_empty".',
+    );
+  }
+
+  return { lockedField, expression: parseFilterExpression(expressionText) };
+}
+
+function collectLockConditions(value: string, previous: LockConditionOption[] = []): LockConditionOption[] {
+  return [...previous, parseLockConditionOption(value)];
+}
+
+function parseLockMessageOption(input: string): LockMessageOption {
+  const separatorIndex = input.indexOf(":");
+  const lockedField = separatorIndex > 0 ? input.slice(0, separatorIndex).trim() : "";
+  const message = separatorIndex > 0 ? input.slice(separatorIndex + 1).trim() : "";
+
+  if (!lockedField || !message) {
+    throw new InvalidArgumentError('Expected "<lockedField>:<message>", e.g. "status:Locked once approved.".');
+  }
+
+  return { lockedField, message };
+}
+
+function collectLockMessages(value: string, previous: LockMessageOption[] = []): LockMessageOption[] {
+  return [...previous, parseLockMessageOption(value)];
+}
+
+/**
+ * Builds behavior.lockedFields from the --lock-* flags. Every flag names its
+ * locked field explicitly, so ordering between flags never matters. A field
+ * with no conditions is locked permanently; with conditions it locks when all
+ * of them match (AND). Returns [] for --clear-locked-fields and undefined when
+ * no lock flag was used.
+ */
+function buildLockedFields(options: WidgetMutationOptions): Array<Record<string, unknown>> | undefined {
+  const hasLockFlags =
+    (options.lockField?.length ?? 0) > 0 ||
+    (options.lockCondition?.length ?? 0) > 0 ||
+    (options.lockMessageBefore?.length ?? 0) > 0 ||
+    (options.lockMessageAfter?.length ?? 0) > 0;
+
+  if (options.clearLockedFields) {
+    if (hasLockFlags) {
+      throw new CliError(
+        "invalid_cli_usage",
+        'Use either "--clear-locked-fields" or the "--lock-*" flags, not both.',
+      );
+    }
+    return [];
+  }
+
+  if (!hasLockFlags) {
+    return undefined;
+  }
+
+  interface LockRule {
+    conditions: Array<Record<string, unknown>>;
+    messageBeforeLock?: string;
+    messageAfterLock?: string;
+  }
+
+  const rules = new Map<string, LockRule>();
+  const ensureRule = (lockedField: string): LockRule => {
+    let rule = rules.get(lockedField);
+    if (!rule) {
+      rule = { conditions: [] };
+      rules.set(lockedField, rule);
+    }
+    return rule;
+  };
+
+  for (const lockedField of options.lockField ?? []) {
+    ensureRule(lockedField);
+  }
+  for (const { lockedField, expression } of options.lockCondition ?? []) {
+    ensureRule(lockedField).conditions.push(toDisplayFilter(expression));
+  }
+  for (const { lockedField, message } of options.lockMessageBefore ?? []) {
+    ensureRule(lockedField).messageBeforeLock = message;
+  }
+  for (const { lockedField, message } of options.lockMessageAfter ?? []) {
+    ensureRule(lockedField).messageAfterLock = message;
+  }
+
+  return [...rules.entries()].map(([lockedField, rule]) => ({
+    field: { fieldId: lockedField },
+    conditions: rule.conditions,
+    ...(rule.messageBeforeLock !== undefined ? { messageBeforeLock: rule.messageBeforeLock } : {}),
+    ...(rule.messageAfterLock !== undefined ? { messageAfterLock: rule.messageAfterLock } : {}),
+  }));
+}
+
 function parseBooleanFlag(input: string): boolean {
   const normalized = input.trim().toLowerCase();
   if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
@@ -697,6 +821,14 @@ function buildWidgetBody(options: WidgetMutationOptions): Record<string, unknown
     };
   }
 
+  const lockedFields = buildLockedFields(options);
+  if (lockedFields !== undefined) {
+    body.behavior = {
+      ...(typeof body.behavior === "object" && body.behavior ? body.behavior as Record<string, unknown> : {}),
+      lockedFields,
+    };
+  }
+
   if (options.calc || options.calcField || options.kpiConfig) {
     body.kpi = {
       ...(typeof body.kpi === "object" && body.kpi ? body.kpi as Record<string, unknown> : {}),
@@ -1131,6 +1263,11 @@ export function registerDisplaysCommands(
     .option("--sort <sort>", "repeatable sort", (v, p: string[] = []) => [...p, v], [])
     .option("--filter <expr>", "repeatable filter", collectFilters, [])
     .option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button")
+    .option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p: string[] = []) => [...p, v], [])
+    .option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, [])
+    .option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, [])
+    .option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, [])
+    .option("--clear-locked-fields", "clear the widget locked-fields configuration")
     .option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
     .option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series")
     .option("--y-axis-serie <json>", "repeatable y axis serie", (v, p: string[] = []) => [...p, v], [])
@@ -1178,6 +1315,11 @@ export function registerDisplaysCommands(
     .option("--sort <sort>", "repeatable sort", (v, p: string[] = []) => [...p, v], [])
     .option("--filter <expr>", "repeatable filter", collectFilters, [])
     .option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button")
+    .option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p: string[] = []) => [...p, v], [])
+    .option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, [])
+    .option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, [])
+    .option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, [])
+    .option("--clear-locked-fields", "clear the widget locked-fields configuration")
     .option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
     .option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series")
     .option("--y-axis-serie <json>", "repeatable y axis serie", (v, p: string[] = []) => [...p, v], [])

package/src/utils/examples.ts

@@ -1458,6 +1458,50 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       response: `{
   "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
   "widgetId": "11111111-1111-4111-a111-111111111111"
+}`,
+    },
+    {
+      description:
+        "Create a TABLE widget with locked fields: contact-name locked permanently (no conditions) and status locked while invoice-number is empty, with before/after lock messages.",
+      command:
+        `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Invoices --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field contact-name --field invoice-number --field status --field amount --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-message-before "status:Status locks until the invoice number is set." --lock-message-after "status:Status is locked because the invoice number is missing."`,
+      raw: `{
+  "type": "TABLE_OR_SUBTABLE",
+  "source": {
+    "originResourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+    "isOriginSubSchema": false
+  },
+  "placement": {
+    "layout": { "x": 0, "y": 0, "w": 12, "h": 8 }
+  },
+  "presentation": { "name": "Invoices" },
+  "view": {
+    "fields": ["contact-name", "invoice-number", "status", "amount"]
+  },
+  "behavior": {
+    "lockedFields": [
+      {
+        "field": { "fieldId": "contact-name" },
+        "conditions": []
+      },
+      {
+        "field": { "fieldId": "status" },
+        "conditions": [
+          {
+            "origin": { "fieldId": "invoice-number" },
+            "comparisonOperator": "IS_EMPTY",
+            "values": []
+          }
+        ],
+        "messageBeforeLock": "Status locks until the invoice number is set.",
+        "messageAfterLock": "Status is locked because the invoice number is missing."
+      }
+    ]
+  }
+}`,
+      response: `{
+  "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
+  "widgetId": "11111111-1111-4111-a111-111111111111"
 }`,
     },
     {
@@ -1858,6 +1902,46 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     "hideDeleteButton": true,
     "hideFilterButton": true
   }
+}`,
+    },
+    {
+      description:
+        "Configure locked fields (replaces the stored configuration): contact-name locked permanently, status locked while invoice-number is empty. Empty conditions = always locked; conditions combine with AND. Enforcement happens in display widgets only, never in the database view.",
+      command:
+        `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --lock-field contact-name --lock-condition "status:invoice-number:is_empty" --lock-message-before "status:Status locks until the invoice number is set." --lock-message-after "status:Status is locked because the invoice number is missing."`,
+      raw: `{
+  "behavior": {
+    "lockedFields": [
+      {
+        "field": { "fieldId": "contact-name" },
+        "conditions": []
+      },
+      {
+        "field": { "fieldId": "status" },
+        "conditions": [
+          {
+            "origin": { "fieldId": "invoice-number" },
+            "comparisonOperator": "IS_EMPTY",
+            "values": []
+          }
+        ],
+        "messageBeforeLock": "Status locks until the invoice number is set.",
+        "messageAfterLock": "Status is locked because the invoice number is missing."
+      }
+    ]
+  }
+}`,
+      response: `{
+  "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
+  "widgetId": "11111111-1111-4111-a111-111111111111"
+}`,
+    },
+    {
+      description: "Clear the locked-fields configuration.",
+      command:
+        'zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --clear-locked-fields',
+      raw: `{
+  "behavior": { "lockedFields": [] }
 }`,
     },
     {