zinkee 0.1.24 → 0.1.26

package/src/commands/displays.ts

@@ -3,7 +3,12 @@ import type { Writable } from "node:stream";
 
 import { Command, InvalidArgumentError } from "commander";
 
-import { DisplaysApi, type DisplayResource, type DisplaySummary } from "../api/displays.js";
+import {
+  DisplaysApi,
+  type ApiDisplayFolder,
+  type DisplayResource,
+  type DisplaySummary,
+} from "../api/displays.js";
 import { ApiClient } from "../client.js";
 import { defaultConfigPath, readRuntimeConfig } from "../config.js";
 import {
@@ -102,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;
 }
@@ -290,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,
@@ -308,6 +512,40 @@ function getDisplaySubresource(value: unknown): Record<string, unknown>[] {
   return value.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === "object");
 }
 
+function displayFolderRows(folders: readonly ApiDisplayFolder[]): Record<string, unknown>[] {
+  return folders.map((folder) => ({
+    id: folder.id ?? "",
+    name: folder.name ?? "",
+    isRoot: folder.isRoot ?? "",
+    displayCount: folder.displayCount ?? "",
+  }));
+}
+
+async function resolveDisplayFolderId(
+  api: DisplaysApi,
+  selector: NormalizedUuidOrSlug,
+): Promise<string> {
+  if (selector.kind === "uuid") {
+    return selector.value;
+  }
+
+  const folders = await api.listFolders();
+  const matches = folders.filter((folder) => folder.name === selector.value);
+
+  if (matches.length === 1 && typeof matches[0]?.id === "string" && matches[0].id.length > 0) {
+    return matches[0].id;
+  }
+
+  if (matches.length > 1) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Folder "${selector.value}" is ambiguous. Found ${matches.length} matches.`,
+    );
+  }
+
+  throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
+}
+
 function buildVariableBody(options: VariableMutationOptions): Record<string, unknown> {
   const body = {
     ...readRawObject(options.raw, options.rawFile),
@@ -396,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);
@@ -590,6 +853,109 @@ export function registerDisplaysCommands(
       writeLine(stdout, `Deleted display "${display.value}".`);
     });
 
+  const folders = displays
+    .command("folders")
+    .description("Manage display folders (flat: a folder only has a name, no order or properties)");
+
+  folders
+    .command("list")
+    .description("List display folders (non-root folders plus the root bucket, whose name is null)")
+    .action(async function action(this: Command) {
+      const { api, json } = createDisplaysApi(this, filePath);
+      const data = await api.listFolders();
+      if (json) {
+        emitJson(stdout, "displays folders list", data);
+        return;
+      }
+      printTable(displayFolderRows(data), ["id", "name", "isRoot", "displayCount"], stdout);
+    });
+
+  folders
+    .command("create")
+    .description("Create a display folder")
+    .requiredOption("--name <name>", "folder name")
+    .action(async function action(this: Command, commandOptions: { name?: string }) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders create", readOnly, "write");
+      if (commandOptions.name === undefined) {
+        throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+      }
+      const data = await api.createFolder({ name: commandOptions.name });
+      if (json) {
+        emitJson(stdout, "displays folders create", data);
+        return;
+      }
+      writeLine(stdout, `Created display folder "${String(data.name ?? commandOptions.name)}".`);
+    });
+
+  folders
+    .command("update")
+    .description("Rename a display folder")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .requiredOption("--name <name>", "folder name")
+    .action(async function action(
+      this: Command,
+      folder: NormalizedUuidOrSlug,
+      commandOptions: { name?: string },
+    ) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders update", readOnly, "write");
+      if (commandOptions.name === undefined) {
+        throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+      }
+      const folderId = await resolveDisplayFolderId(api, folder);
+      const data = await api.updateFolder({ kind: "uuid", value: folderId }, { name: commandOptions.name });
+      if (json) {
+        emitJson(stdout, "displays folders update", data);
+        return;
+      }
+      writeLine(stdout, `Updated display folder "${String(data.name ?? folder.value)}".`);
+    });
+
+  folders
+    .command("delete")
+    .description("Delete a display folder (its displays move back to the root folder)")
+    .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, folder: NormalizedUuidOrSlug) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders delete", readOnly, "destructive");
+      const folderId = await resolveDisplayFolderId(api, folder);
+      const data = await api.deleteFolder({ kind: "uuid", value: folderId });
+      if (json) {
+        emitJson(stdout, "displays folders delete", data);
+        return;
+      }
+      writeLine(stdout, `Deleted display folder "${folder.value}".`);
+    });
+
+  folders
+    .command("move")
+    .description("Move a display into a folder")
+    .argument("<display>", "display UUID", parseUuidOrSlugSelector)
+    .requiredOption(
+      "--to <folder>",
+      "target folder UUID or exact name (use the root folder to move it out of any folder)",
+      parseUuidOrSlugSelector,
+    )
+    .action(async function action(
+      this: Command,
+      display: NormalizedUuidOrSlug,
+      commandOptions: { to?: NormalizedUuidOrSlug },
+    ) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays folders move", readOnly, "write");
+      if (!commandOptions.to) {
+        throw new CliError("invalid_cli_usage", 'Provide target folder via "--to".');
+      }
+      const targetFolderId = await resolveDisplayFolderId(api, commandOptions.to);
+      const data = await api.moveDisplay({ displayId: display.value, targetFolderId });
+      if (json) {
+        emitJson(stdout, "displays folders move", data);
+        return;
+      }
+      writeLine(stdout, `Moved display "${display.value}" to folder "${targetFolderId}".`);
+    });
+
   const layout = displays.command("layout").description("Manage display layout");
   layout
     .command("get")
@@ -725,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));
@@ -743,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/commands/navigation.test.ts

@@ -157,7 +157,7 @@ describe("navigation commands", () => {
     ).rejects.toThrowError('Folder "Finance" is ambiguous. Found 2 matches.');
   });
 
-  it("shapes move payloads using the resource type and resolved folder id", async () => {
+  it("shapes move payloads using the resolved folder id (schemas only, no resource type)", async () => {
     const configPath = createApiConfig();
     const output = createStdoutBuffer();
     const fetchMock = createFetchMock();
@@ -171,7 +171,7 @@ describe("navigation commands", () => {
             {
               id: "resource-1",
               name: "Invoices",
-              type: "DISPLAY",
+              type: "SCHEMA",
               isInSpace: false,
             },
           ],
@@ -189,8 +189,6 @@ describe("navigation commands", () => {
       "resources",
       "move",
       "resource-1",
-      "--type",
-      "display",
       "--to",
       "Finance",
     ]);
@@ -207,7 +205,6 @@ describe("navigation commands", () => {
     expect(moveInit?.method).toBe("POST");
     expect(JSON.parse(String(moveInit?.body))).toEqual({
       resourceId: "resource-1",
-      resourceType: "DISPLAY",
       targetFolderId: "aaaabbbb-cccc-dddd-eeee-ffffffffffff",
     });
   });

package/src/commands/navigation.ts

@@ -251,9 +251,9 @@ export function registerNavigationCommands(
     .command("create")
     .description("Create a navigation folder")
     .requiredOption("--name <name>", "folder name")
-    .option("--order <n>", "folder order")
-    .option("--props <json>", "folder additionalProperties JSON")
-    .option("--props-file <path>", "folder additionalProperties JSON file")
+    .option("--order <n>", "display order (lower values appear first)")
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"color\":\"blue\",\"icon\":\"chart-line\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(this: Command, commandOptions: FolderMutationOptions) {
       const { api, json, readOnly } = createNavigationApi(this, filePath);
       ensureWritable("navigation folders create", readOnly, "write");
@@ -272,9 +272,9 @@ export function registerNavigationCommands(
     .description("Update a navigation folder")
     .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
     .option("--name <name>", "folder name")
-    .option("--order <n>", "folder order")
-    .option("--props <json>", "folder additionalProperties JSON")
-    .option("--props-file <path>", "folder additionalProperties JSON file")
+    .option("--order <n>", "display order (lower values appear first)")
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"color\":\"blue\",\"icon\":\"chart-line\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(this: Command, folder: NormalizedUuidOrSlug, commandOptions: FolderMutationOptions) {
       const { api, json, readOnly } = createNavigationApi(this, filePath);
       ensureWritable("navigation folders update", readOnly, "write");
@@ -319,14 +319,15 @@ export function registerNavigationCommands(
     .command("resources")
     .description("Manage navigation resources")
     .command("move")
-    .description("Move a resource into a folder")
-    .argument("<resource>", "resource UUID")
-    .requiredOption("--type <type>", "resource type")
+    .description(
+      "Move a schema into a navigation folder. Only schemas can be moved (the navigation menu holds databases); schedules and sub-schemas follow their parent schema. Use the root folder UUID 00000000-0000-0000-0000-000000000000 to move it back to the workspace root.",
+    )
+    .argument("<resource>", "schema UUID")
     .requiredOption("--to <folder>", "target folder UUID or exact name")
     .action(async function action(
       this: Command,
       resourceId: string,
-      commandOptions: { type: string; to: string },
+      commandOptions: { to: string },
     ) {
       const { api, json, readOnly } = createNavigationApi(this, filePath);
       ensureWritable("navigation resources move", readOnly, "write");
@@ -334,7 +335,6 @@ export function registerNavigationCommands(
       const resolved = resolveFolder(allFolders, parseUuidOrSlugSelector(commandOptions.to));
       const data = await api.moveResource({
         resourceId,
-        resourceType: commandOptions.type.toUpperCase(),
         targetFolderId: resolved.id,
       });
 

package/src/commands/teamspace.ts

@@ -385,7 +385,7 @@ export function registerTeamspaceCommands(
   folders
     .command("list")
     .description("List teamspace folders")
-    .option("--include-resources", "include nested resources")
+    .option("--include-resources", "include the published resources inside each folder")
     .action(async function action(this: Command, commandOptions: FolderListCommandOptions) {
       const { api, json } = createTeamspaceApi(this, filePath);
       const data = await api.listFolders(Boolean(commandOptions.includeResources));
@@ -402,7 +402,7 @@ export function registerTeamspaceCommands(
     .command("get")
     .description("Get a teamspace folder by exact name or UUID")
     .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
-    .option("--include-resources", "include nested resources")
+    .option("--include-resources", "include the published resources inside each folder")
     .action(async function action(
       this: Command,
       folder: NormalizedUuidOrSlug,
@@ -425,9 +425,9 @@ export function registerTeamspaceCommands(
     .command("create")
     .description("Create a teamspace folder")
     .requiredOption("--name <name>", "folder name")
-    .option("--order <n>", "folder order", parseNonNegativeInteger)
-    .option("--props <json>", "folder properties payload")
-    .option("--props-file <path>", "path to a folder properties JSON payload")
+    .option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger)
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"icon\":\"folder-users\",\"color\":\"gold\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(
       this: Command,
       commandOptions: FolderCreateCommandOptions,
@@ -450,9 +450,9 @@ export function registerTeamspaceCommands(
     .description("Update a teamspace folder")
     .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
     .option("--name <name>", "folder name")
-    .option("--order <n>", "folder order", parseNonNegativeInteger)
-    .option("--props <json>", "folder properties payload")
-    .option("--props-file <path>", "path to a folder properties JSON payload")
+    .option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger)
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"icon\":\"folder-users\",\"color\":\"gold\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(
       this: Command,
       folder: NormalizedUuidOrSlug,
@@ -495,9 +495,15 @@ export function registerTeamspaceCommands(
 
   resources
     .command("publish")
-    .description("Publish a resource to a teamspace folder")
-    .argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector)
-    .requiredOption("--to <folder>", "target folder", parseUuidOrSlugSelector)
+    .description(
+      "Publish a resource to a teamspace folder. Publishing an already-published resource moves it to the new folder.",
+    )
+    .argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector)
+    .requiredOption(
+      "--to <folder>",
+      "target folder UUID or exact name (root folder UUID is 00000000-0000-0000-0000-000000000000)",
+      parseUuidOrSlugSelector,
+    )
     .action(async function action(
       this: Command,
       resource: NormalizedUuidOrSlug,
@@ -522,8 +528,8 @@ export function registerTeamspaceCommands(
 
   resources
     .command("unpublish")
-    .description("Unpublish a resource from teamspace")
-    .argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector)
+    .description("Unpublish a resource from teamspace (removes it from its shared folder)")
+    .argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector)
     .action(async function action(this: Command, resource: NormalizedUuidOrSlug) {
       const { api, json, readOnly } = createTeamspaceApi(this, filePath);
       ensureWritable("teamspace resources unpublish", readOnly, "write");