zinkee 0.1.38 → 0.1.40

package/package.json

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

package/src/api/automations.ts

@@ -16,6 +16,7 @@ export interface ApiAutomation {
   description?: string;
   status?: string;
   folderId?: string;
+  folder?: { id?: string; name?: string | null; isRoot?: boolean };
   trigger?: ApiAutomationTrigger;
   actions?: ApiAutomationAction[];
 }

package/src/api/displays.ts

@@ -16,6 +16,7 @@ export interface ApiDisplay {
   widgets?: Array<Record<string, unknown>>;
   navigationTargets?: Array<Record<string, unknown>>;
   crossWidgetFilter?: Array<Record<string, unknown>> | null;
+  folder?: { id?: string; name?: string | null; isRoot?: boolean };
 }
 
 export interface ApiDisplayTab {

package/src/api/schemas.ts

@@ -20,6 +20,7 @@ export interface ApiSchema {
   highlightedField?: string;
   fields?: ApiSchemaField[];
   uniqueFields?: string[];
+  folder?: { id?: string; name?: string | null; isRoot?: boolean };
 }
 
 export interface CreateSchemaInput {

package/src/commands/automations.ts

@@ -29,7 +29,7 @@ import {
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { JsonObject, JsonValue, RuntimeOverrides } from "../types.js";
 import { CliError } from "../utils/errors.js";
-import { buildJsonSuccess, printTable } from "../utils/output.js";
+import { buildJsonSuccess, folderColumns, FOLDER_TABLE_KEYS, printTable } from "../utils/output.js";
 
 interface CommandIo {
   write(chunk: string): unknown;
@@ -800,12 +800,12 @@ function automationRows(automations: readonly ApiAutomation[]): Record<string, u
     id: automation.id ?? "",
     name: automation.name ?? "",
     status: automation.status ?? "",
-    folderId: automation.folderId ?? "",
     triggerType:
       isJsonObject(automation.trigger) && typeof automation.trigger.type === "string"
         ? automation.trigger.type
         : "",
     actionCount: Array.isArray(automation.actions) ? automation.actions.length : "",
+    ...folderColumns(automation.folder),
   }));
 }
 
@@ -1569,7 +1569,7 @@ export function registerAutomationsCommands(
 
       printTable(
         automationRows(data),
-        ["id", "name", "status", "folderId", "triggerType", "actionCount"],
+        ["id", "name", "status", "triggerType", "actionCount", ...FOLDER_TABLE_KEYS],
         stdout,
       );
     });

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

@@ -20,7 +20,7 @@ import { normalizeUuidOrSlug, type NormalizedUuidOrSlug } from "../parsers/selec
 import { resolveRuntimeContext } from "../runtime-context.js";
 import type { RuntimeOverrides } from "../types.js";
 import { CliError } from "../utils/errors.js";
-import { buildJsonSuccess, printTable } from "../utils/output.js";
+import { buildJsonSuccess, folderColumns, FOLDER_TABLE_KEYS, printTable } from "../utils/output.js";
 
 const DATE_DYNAMIC_OPTIONS =
   "today, thisWeek, thisMonth, thisQuarter, thisSemester, thisYear, next7Days, next30Days, next6Months, next12Months, last12Months";
@@ -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;
@@ -504,6 +628,7 @@ function displayRows(displays: readonly DisplaySummary[]): Record<string, unknow
     layoutTemplate: display.layoutTemplate ?? "",
     variableCount: display.variableCount ?? "",
     widgetCount: display.widgetCount ?? "",
+    ...folderColumns(display.folder),
   }));
 }
 
@@ -697,6 +822,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> : {}),
@@ -821,7 +954,11 @@ export function registerDisplaysCommands(
         emitJson(stdout, "displays list", data);
         return;
       }
-      printTable(displayRows(data), ["id", "name", "layoutTemplate", "variableCount", "widgetCount"], stdout);
+      printTable(
+        displayRows(data),
+        ["id", "name", "layoutTemplate", "variableCount", "widgetCount", ...FOLDER_TABLE_KEYS],
+        stdout,
+      );
     });
 
   displays
@@ -1131,6 +1268,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 +1320,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/commands/schemas.ts

@@ -31,7 +31,7 @@ import {
   normalizeSchemaFieldUpdatePayload,
   normalizeSchemaFieldType,
 } from "../utils/schema-fields.js";
-import { buildJsonSuccess, printTable } from "../utils/output.js";
+import { buildJsonSuccess, folderColumns, FOLDER_TABLE_KEYS, printTable } from "../utils/output.js";
 
 interface CommandIo {
   write(chunk: string): unknown;
@@ -284,8 +284,9 @@ function emitSchemasTable(stdout: CommandIo, schemas: readonly ApiSchema[]): voi
       slug: schema.slug ?? "",
       auditable: schema.auditable ?? "",
       commentable: schema.commentable ?? "",
+      ...folderColumns(schema.folder),
     })),
-    ["id", "name", "slug", "auditable", "commentable"],
+    ["id", "name", "slug", "auditable", "commentable", ...FOLDER_TABLE_KEYS],
     stdout,
   );
 }

package/src/utils/examples.test.ts

@@ -274,6 +274,8 @@ describe("getCommandExamples", () => {
     expect(examples[0]?.response).toContain('"layoutTemplate": "widget_row_tabs"');
     expect(examples[0]?.response).toContain('"layoutTemplate": "freeform"');
     expect(examples[0]?.response).toContain('"layoutTemplate": "grid"');
+    expect(examples[0]?.response).toContain('"folder"');
+    expect(examples[0]?.response).toContain('"isRoot": true');
   });
 
   it("attaches a response body to schemas create and teamspace resources publish", () => {

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": [] }
 }`,
     },
     {
@@ -2825,21 +2909,36 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     "name": "Executive Revenue",
     "layoutTemplate": "widget_row_tabs",
     "variableCount": 3,
-    "widgetCount": 6
+    "widgetCount": 6,
+    "folder": {
+      "id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+      "name": "📊 Executive",
+      "isRoot": false
+    }
   },
   {
     "id": "6b7c8d9e-0f12-3456-789a-bcdef0123456",
     "name": "Sales Pipeline",
     "layoutTemplate": "freeform",
     "variableCount": 1,
-    "widgetCount": 3
+    "widgetCount": 3,
+    "folder": {
+      "id": "a0b1c2d3-e4f5-4061-8273-8495a6b7c8d9",
+      "name": null,
+      "isRoot": true
+    }
   },
   {
     "id": "ef012345-6789-4abc-8def-0123456789ab",
     "name": "Customer Detail",
     "layoutTemplate": "grid",
     "variableCount": 0,
-    "widgetCount": 2
+    "widgetCount": 2,
+    "folder": {
+      "id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+      "name": "📊 Executive",
+      "isRoot": false
+    }
   }
 ]`,
     },
@@ -2972,7 +3071,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       "targetVariableId": "aaaaaaaa-1111-4111-a111-111111111111",
       "label": "Open customer"
     }
-  ]
+  ],
+  "folder": {
+    "id": "b1a2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+    "name": "📊 Executive",
+    "isRoot": false
+  }
 }`,
     },
   ]),

package/src/utils/output.test.ts

@@ -2,7 +2,33 @@ import { describe, expect, it } from "vitest";
 
 import { getCommandMeta } from "../command-registry.js";
 
-import { buildJsonError, buildJsonSuccess } from "./output.js";
+import { buildJsonError, buildJsonSuccess, folderColumns } from "./output.js";
+
+describe("folderColumns", () => {
+  it("flattens a named folder into id/name/isRoot columns", () => {
+    expect(folderColumns({ id: "f1", name: "Finance", isRoot: false })).toEqual({
+      folderId: "f1",
+      folderName: "Finance",
+      folderIsRoot: "false",
+    });
+  });
+
+  it("renders the root folder (null name) as (root)", () => {
+    expect(folderColumns({ id: "root-1", name: null, isRoot: true })).toEqual({
+      folderId: "root-1",
+      folderName: "(root)",
+      folderIsRoot: "true",
+    });
+  });
+
+  it("leaves every column empty when there is no folder", () => {
+    expect(folderColumns(undefined)).toEqual({
+      folderId: "",
+      folderName: "",
+      folderIsRoot: "",
+    });
+  });
+});
 
 describe("buildJsonSuccess", () => {
   it("wraps data in the standard success envelope", () => {