zinkee 0.1.25 → 0.1.26

package/package.json

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

package/src/commands/displays.test.ts

@@ -252,6 +252,243 @@ describe("displays commands", () => {
     });
   });
 
+  it("builds KANBAN viewState fieldMapping, cardConfig and aggregation from flags", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-k1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "kanban",
+      "--field",
+      "name-uuid",
+      "--column-field",
+      "status-uuid",
+      "--swimlane-field",
+      "owner-uuid",
+      "--card-title-field",
+      "name-uuid",
+      "--card-category3-field",
+      "amount-uuid",
+      "--aggregation-method",
+      "sum",
+      "--aggregation-field",
+      "amount-uuid",
+      "--view-state",
+      '{"showNoValueColumn":true,"hideEmptyColumns":false}',
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "KANBAN",
+      view: {
+        fields: ["name-uuid"],
+        viewAdditionalProperties: {
+          viewState: {
+            showNoValueColumn: true,
+            hideEmptyColumns: false,
+            fieldMapping: {
+              columnField: "status-uuid",
+              swimlaneField: "owner-uuid",
+              cardConfig: { titleField: "name-uuid", category3Field: "amount-uuid" },
+              aggregationConfig: { method: "sum", fieldId: "amount-uuid" },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it("builds TIMELINE viewState fieldMapping with category4 from flags", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-t1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "timeline",
+      "--start-date-field",
+      "start-uuid",
+      "--end-date-field",
+      "end-uuid",
+      "--label-field",
+      "name-uuid",
+      "--card-category4-field",
+      "amount-uuid",
+      "--view-state",
+      '{"granularity":"month","sidebarWidth":300}',
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "TIMELINE",
+      view: {
+        viewAdditionalProperties: {
+          viewState: {
+            granularity: "month",
+            sidebarWidth: 300,
+            fieldMapping: {
+              startDateField: "start-uuid",
+              endDateField: "end-uuid",
+              labelField: "name-uuid",
+              cardConfig: { category4Field: "amount-uuid" },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it("builds HIERARCHY hierarchyConfig from columns, root and child flags", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-h1" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "hierarchy",
+      "--hierarchy-label",
+      "Name",
+      "--hierarchy-info",
+      "col-info-status:Status",
+      "--hierarchy-number",
+      "col-num-amount:Total amount:sum",
+      "--hierarchy-root-name",
+      "Customers",
+      "--hierarchy-root-label-field",
+      "name-uuid",
+      "--hierarchy-root-info",
+      "col-info-status:status-uuid",
+      "--hierarchy-root-number",
+      "col-num-amount:amount-uuid",
+      "--hierarchy-child",
+      '{"name":"Projects","schemaId":"projects-uuid","childFieldId":"child-uuid","labelFieldId":"project-name-uuid","infoMappings":[],"numberMappings":[{"columnId":"col-num-amount","fieldId":"project-amount-uuid"}]}',
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "HIERARCHY",
+      view: {
+        hierarchyConfig: {
+          columns: {
+            label: "Name",
+            infos: [{ id: "col-info-status", name: "Status" }],
+            numbers: [{ id: "col-num-amount", name: "Total amount", aggregation: "SUM" }],
+          },
+          rootLevel: {
+            name: "Customers",
+            labelFieldId: "name-uuid",
+            infoMappings: [{ columnId: "col-info-status", fieldId: "status-uuid" }],
+            numberMappings: [{ columnId: "col-num-amount", fieldId: "amount-uuid" }],
+          },
+          childLevels: [
+            {
+              name: "Projects",
+              schemaId: "projects-uuid",
+              childFieldId: "child-uuid",
+              labelFieldId: "project-name-uuid",
+              infoMappings: [],
+              numberMappings: [{ columnId: "col-num-amount", fieldId: "project-amount-uuid" }],
+            },
+          ],
+        },
+      },
+    });
+  });
+
+  it("deep merges KANBAN flags over view state coming from --raw", async () => {
+    const configPath = createApiConfig();
+    const output = createStdoutBuffer();
+    const fetchMock = createFetchMock();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ displayId: "display-1", widgetId: "widget-k2" }));
+    const program = buildProgram({ configPath, stdout: output.stdout });
+
+    await program.parseAsync([
+      "node",
+      "zinkee",
+      "--json",
+      "displays",
+      "widgets",
+      "create",
+      "display-1",
+      "--type",
+      "kanban",
+      "--raw",
+      '{"view":{"viewAdditionalProperties":{"viewState":{"columnOrder":["a","b"],"fieldMapping":{"columnField":"old-uuid","cardConfig":{"titleField":"name-uuid"}}}}}}',
+      "--column-field",
+      "status-uuid",
+      "--card-category1-field",
+      "status-uuid",
+    ]);
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      type: "KANBAN",
+      view: {
+        viewAdditionalProperties: {
+          viewState: {
+            columnOrder: ["a", "b"],
+            fieldMapping: {
+              columnField: "status-uuid",
+              cardConfig: { titleField: "name-uuid", category1Field: "status-uuid" },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it("rejects --hierarchy-number with an invalid aggregation", 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",
+        "create",
+        "display-1",
+        "--type",
+        "hierarchy",
+        "--hierarchy-number",
+        "col-num-amount:Total:BOGUS",
+      ]),
+    ).rejects.toThrow(/aggregation/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

@@ -107,6 +107,36 @@ interface WidgetMutationOptions {
   xAxisTimeSeries?: boolean;
   yAxisSerie?: string[];
   legend?: string;
+  // KANBAN / TIMELINE viewState.fieldMapping (UUIDs only; slugs are not resolved here)
+  columnField?: string;
+  swimlaneField?: string;
+  startDateField?: string;
+  endDateField?: string;
+  labelField?: string;
+  groupField?: string;
+  subgroupField?: string;
+  progressField?: string;
+  cardTitleField?: string;
+  cardCategory1Field?: string;
+  cardCategory2Field?: string;
+  cardCategory3Field?: string;
+  cardCategory4Field?: string;
+  cardDescriptionField?: string;
+  aggregationMethod?: string;
+  aggregationField?: string;
+  viewState?: string;
+  viewStateFile?: string;
+  // HIERARCHY view.hierarchyConfig (UUIDs only; slugs are not resolved here)
+  hierarchyLabel?: string;
+  hierarchyInfo?: string[];
+  hierarchyNumber?: string[];
+  hierarchyRootName?: string;
+  hierarchyRootLabelField?: string;
+  hierarchyRootInfo?: string[];
+  hierarchyRootNumber?: string[];
+  hierarchyChild?: string[];
+  hierarchyConfig?: string;
+  hierarchyConfigFile?: string;
   raw?: string;
   rawFile?: string;
 }
@@ -295,6 +325,175 @@ function isEmptyObject(value: object): boolean {
   return Object.keys(value).length === 0;
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    const existing = out[key];
+    out[key] = isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value;
+  }
+  return out;
+}
+
+function assignDefined(target: Record<string, unknown>, key: string, value: unknown): void {
+  if (value !== undefined) target[key] = value;
+}
+
+function readNamedJsonObject(
+  raw: string | undefined,
+  rawFile: string | undefined,
+  inlineFlag: string,
+  fileFlag: string,
+): Record<string, unknown> | undefined {
+  const parsed = readNamedJsonOption(raw, rawFile, inlineFlag, fileFlag);
+  if (parsed === undefined) return undefined;
+  if (!isPlainObject(parsed)) {
+    throw new CliError("invalid_cli_usage", `${inlineFlag} payload must be a JSON object.`);
+  }
+  return parsed;
+}
+
+const HIERARCHY_AGGREGATIONS = new Set([
+  "SUM",
+  "AVERAGE",
+  "MINIMUM",
+  "MAXIMUM",
+  "COUNT",
+  "COUNT_DISTINCT",
+]);
+
+function parseHierarchyInfo(value: string): Record<string, unknown> {
+  const idx = value.indexOf(":");
+  if (idx <= 0 || idx === value.length - 1) {
+    throw new CliError("invalid_cli_usage", `--hierarchy-info "${value}" must use the format <id:name>.`);
+  }
+  return { id: value.slice(0, idx).trim(), name: value.slice(idx + 1).trim() };
+}
+
+function parseHierarchyNumber(value: string): Record<string, unknown> {
+  const parts = value.split(":");
+  if (parts.length < 3) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number "${value}" must use the format <id:name:aggregation>.`,
+    );
+  }
+  const id = parts[0]?.trim() ?? "";
+  const aggregation = (parts[parts.length - 1]?.trim() ?? "").toUpperCase();
+  const name = parts.slice(1, -1).join(":").trim();
+  if (!id || !name) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number "${value}" must use the format <id:name:aggregation>.`,
+    );
+  }
+  if (!HIERARCHY_AGGREGATIONS.has(aggregation)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number aggregation "${aggregation}" must be one of SUM, AVERAGE, MINIMUM, MAXIMUM, COUNT, COUNT_DISTINCT.`,
+    );
+  }
+  return { id, name, aggregation };
+}
+
+function parseHierarchyMapping(value: string, flag: string): Record<string, unknown> {
+  const idx = value.indexOf(":");
+  if (idx <= 0 || idx === value.length - 1) {
+    throw new CliError("invalid_cli_usage", `${flag} "${value}" must use the format <columnId:fieldId>.`);
+  }
+  return { columnId: value.slice(0, idx).trim(), fieldId: value.slice(idx + 1).trim() };
+}
+
+function buildWidgetFieldMapping(options: WidgetMutationOptions): Record<string, unknown> | undefined {
+  const mapping: Record<string, unknown> = {};
+  assignDefined(mapping, "columnField", options.columnField);
+  assignDefined(mapping, "swimlaneField", options.swimlaneField);
+  assignDefined(mapping, "startDateField", options.startDateField);
+  assignDefined(mapping, "endDateField", options.endDateField);
+  assignDefined(mapping, "labelField", options.labelField);
+  assignDefined(mapping, "groupField", options.groupField);
+  assignDefined(mapping, "subgroupField", options.subgroupField);
+  assignDefined(mapping, "progressField", options.progressField);
+
+  const cardConfig: Record<string, unknown> = {};
+  assignDefined(cardConfig, "titleField", options.cardTitleField);
+  assignDefined(cardConfig, "category1Field", options.cardCategory1Field);
+  assignDefined(cardConfig, "category2Field", options.cardCategory2Field);
+  assignDefined(cardConfig, "category3Field", options.cardCategory3Field);
+  assignDefined(cardConfig, "category4Field", options.cardCategory4Field);
+  assignDefined(cardConfig, "descriptionField", options.cardDescriptionField);
+  if (Object.keys(cardConfig).length > 0) mapping.cardConfig = cardConfig;
+
+  const aggregationConfig: Record<string, unknown> = {};
+  assignDefined(aggregationConfig, "method", options.aggregationMethod);
+  assignDefined(aggregationConfig, "fieldId", options.aggregationField);
+  if (Object.keys(aggregationConfig).length > 0) mapping.aggregationConfig = aggregationConfig;
+
+  return Object.keys(mapping).length > 0 ? mapping : undefined;
+}
+
+function buildHierarchyConfig(options: WidgetMutationOptions): Record<string, unknown> | undefined {
+  const base = readNamedJsonObject(
+    options.hierarchyConfig,
+    options.hierarchyConfigFile,
+    "--hierarchy-config",
+    "--hierarchy-config-file",
+  );
+  const patch: Record<string, unknown> = {};
+
+  const columns: Record<string, unknown> = {};
+  assignDefined(columns, "label", options.hierarchyLabel);
+  if (options.hierarchyInfo && options.hierarchyInfo.length > 0) {
+    columns.infos = options.hierarchyInfo.map(parseHierarchyInfo);
+  }
+  if (options.hierarchyNumber && options.hierarchyNumber.length > 0) {
+    columns.numbers = options.hierarchyNumber.map(parseHierarchyNumber);
+  }
+  if (Object.keys(columns).length > 0) patch.columns = columns;
+
+  const rootLevel: Record<string, unknown> = {};
+  assignDefined(rootLevel, "name", options.hierarchyRootName);
+  assignDefined(rootLevel, "labelFieldId", options.hierarchyRootLabelField);
+  if (options.hierarchyRootInfo && options.hierarchyRootInfo.length > 0) {
+    rootLevel.infoMappings = options.hierarchyRootInfo.map((entry) =>
+      parseHierarchyMapping(entry, "--hierarchy-root-info"),
+    );
+  }
+  if (options.hierarchyRootNumber && options.hierarchyRootNumber.length > 0) {
+    rootLevel.numberMappings = options.hierarchyRootNumber.map((entry) =>
+      parseHierarchyMapping(entry, "--hierarchy-root-number"),
+    );
+  }
+  if (Object.keys(rootLevel).length > 0) patch.rootLevel = rootLevel;
+
+  if (options.hierarchyChild && options.hierarchyChild.length > 0) {
+    patch.childLevels = options.hierarchyChild.map((entry, index) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(entry);
+      } catch {
+        throw new CliError("invalid_cli_usage", `--hierarchy-child payload #${index + 1} is invalid JSON.`);
+      }
+      if (!isPlainObject(parsed)) {
+        throw new CliError(
+          "invalid_cli_usage",
+          `--hierarchy-child payload #${index + 1} must be a JSON object.`,
+        );
+      }
+      return parsed;
+    });
+  }
+
+  if (base === undefined && Object.keys(patch).length === 0) return undefined;
+  return deepMerge(base ?? {}, patch);
+}
+
 function displayRows(displays: readonly DisplaySummary[]): Record<string, unknown>[] {
   return displays.map((display) => ({
     id: display.id,
@@ -435,12 +634,37 @@ function buildWidgetBody(options: WidgetMutationOptions): Record<string, unknown
     };
   }
 
+  const viewPatch: Record<string, unknown> = {};
   if (options.field && options.field.length > 0) {
-    body.view = {
-      ...(typeof body.view === "object" && body.view ? body.view as Record<string, unknown> : {}),
-      fields: options.field,
-    };
+    viewPatch.fields = options.field;
+  }
+
+  const fieldMapping = buildWidgetFieldMapping(options);
+  const viewStateBase = readNamedJsonObject(
+    options.viewState,
+    options.viewStateFile,
+    "--view-state",
+    "--view-state-file",
+  );
+  let viewState: Record<string, unknown> | undefined = viewStateBase ? { ...viewStateBase } : undefined;
+  if (fieldMapping) {
+    viewState = deepMerge(viewState ?? {}, { fieldMapping });
+  }
+  if (viewState !== undefined) {
+    viewPatch.viewAdditionalProperties = { viewState };
   }
+
+  const hierarchyConfig = buildHierarchyConfig(options);
+  if (hierarchyConfig !== undefined) {
+    viewPatch.hierarchyConfig = hierarchyConfig;
+  }
+
+  if (Object.keys(viewPatch).length > 0) {
+    const existingView =
+      typeof body.view === "object" && body.view ? (body.view as Record<string, unknown>) : {};
+    body.view = deepMerge(existingView, viewPatch);
+  }
+
   const queryMerge: Record<string, unknown> = {};
   if (options.sort && options.sort.length > 0) queryMerge.sorts = options.sort;
   if (options.filter && options.filter.length > 0) queryMerge.filters = options.filter.map(toDisplayFilter);
@@ -867,7 +1091,36 @@ export function registerDisplaysCommands(
     .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], [])
-    .option("--legend <json>").option("--raw <json>").option("--raw-file <path>")
+    .option("--legend <json>")
+    .option("--column-field <uuid>", "KANBAN column field (UUID, not slug)")
+    .option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)")
+    .option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)")
+    .option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)")
+    .option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)")
+    .option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)")
+    .option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)")
+    .option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)")
+    .option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)")
+    .option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)")
+    .option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)")
+    .option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)")
+    .option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)")
+    .option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)")
+    .option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)")
+    .option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)")
+    .option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)")
+    .option("--view-state-file <path>", "read --view-state JSON from a file")
+    .option("--hierarchy-label <name>", "HIERARCHY label column name")
+    .option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-root-name <name>", "HIERARCHY root level name")
+    .option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)")
+    .option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)")
+    .option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file")
+    .option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: WidgetMutationOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays widgets create", readOnly, "write");
       const data = await api.createWidget(display, buildWidgetBody(commandOptions));
@@ -885,7 +1138,36 @@ export function registerDisplaysCommands(
     .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], [])
-    .option("--legend <json>").option("--raw <json>").option("--raw-file <path>")
+    .option("--legend <json>")
+    .option("--column-field <uuid>", "KANBAN column field (UUID, not slug)")
+    .option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)")
+    .option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)")
+    .option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)")
+    .option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)")
+    .option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)")
+    .option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)")
+    .option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)")
+    .option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)")
+    .option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)")
+    .option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)")
+    .option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)")
+    .option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)")
+    .option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)")
+    .option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)")
+    .option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)")
+    .option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)")
+    .option("--view-state-file <path>", "read --view-state JSON from a file")
+    .option("--hierarchy-label <name>", "HIERARCHY label column name")
+    .option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-root-name <name>", "HIERARCHY root level name")
+    .option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)")
+    .option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p: string[] = []) => [...p, v], [])
+    .option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)")
+    .option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file")
+    .option("--raw <json>").option("--raw-file <path>")
     .action(async function action(this: Command, display: NormalizedUuidOrSlug, widgetId: string, commandOptions: WidgetMutationOptions) {
       const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays widgets update", readOnly, "write");
       const data = await api.updateWidget(display, widgetId, buildWidgetBody(commandOptions));

package/src/utils/examples.test.ts

@@ -200,6 +200,25 @@ describe("getCommandExamples", () => {
     }
   });
 
+  it("does not teach legacy system columns in display widget examples", () => {
+    const legacyColumns = ["id", "createdat", "updatedat", "createdby", "updatedby"];
+    const commands = ["displays widgets create", "displays widgets update", "displays list", "displays get"];
+
+    for (const command of commands) {
+      for (const example of getCommandExamples(command)) {
+        for (const column of legacyColumns) {
+          expect(example.command).not.toContain(`--field ${column}`);
+        }
+
+        const examplePayloads = [example.raw, example.response].filter(Boolean);
+        for (const payload of examplePayloads) {
+          expect(payload).not.toMatch(/"fields"\s*:\s*\[[^\]]*"(id|createdat|updatedat|createdby|updatedby)"/);
+          expect(payload).not.toMatch(/"fieldCalc"\s*:\s*"(id|createdat|updatedat|createdby|updatedby)"/);
+        }
+      }
+    }
+  });
+
   it("covers REFERENCE, MEMBER and DATE variants in displays variables create", () => {
     const examples = getCommandExamples("displays variables create");
     const rawPayloads = examples.map((example) => example.raw ?? "");