zinkee 0.1.0

package/src/commands/displays.ts

@@ -0,0 +1,755 @@
+import { readFileSync } from "node:fs";
+import type { Writable } from "node:stream";
+
+import { Command, InvalidArgumentError } from "commander";
+
+import { DisplaysApi, type DisplayResource, type DisplaySummary } from "../api/displays.js";
+import { ApiClient } from "../client.js";
+import { defaultConfigPath, readConfig } from "../config.js";
+import { normalizeUuidOrSlug, type NormalizedUuidOrSlug } from "../parsers/selectors.js";
+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";
+
+interface CommandIo {
+  write(chunk: string): unknown;
+}
+
+export interface RegisterDisplaysCommandsOptions {
+  configPath?: string;
+  stdout?: CommandIo;
+}
+
+interface GlobalOptions extends RuntimeOverrides {}
+
+interface DisplayCreateOptions {
+  name: string;
+  template: string;
+  freeformLayouts?: string;
+  freeformLayoutsFile?: string;
+}
+
+interface DisplayUpdateOptions {
+  name?: string;
+}
+
+interface LayoutUpdateOptions {
+  template: string;
+  freeformLayouts?: string;
+  freeformLayoutsFile?: string;
+}
+
+interface TabMutationOptions {
+  name?: string;
+  orientation?: string;
+}
+
+interface VariableMutationOptions {
+  type?: string;
+  name?: string;
+  allowMultiple?: boolean;
+  static?: boolean;
+  default?: string;
+  defaultValue?: string[];
+  sourceSchema?: string;
+  sourceField?: string;
+  filter?: string[];
+  dateMode?: string;
+  dateDynamicOption?: string;
+  dateSpecific?: string;
+  dateRangeStart?: string;
+  dateRangeEnd?: string;
+  raw?: string;
+  rawFile?: string;
+}
+
+interface WidgetMutationOptions {
+  type?: string;
+  name?: string;
+  description?: string;
+  icon?: string;
+  color?: string;
+  originResource?: string;
+  originSubschema?: boolean;
+  tab?: string;
+  slot?: string;
+  layout?: string;
+  layoutFile?: string;
+  field?: string[];
+  sort?: string[];
+  filter?: string[];
+  widgetReadOnly?: boolean;
+  hideAddButton?: boolean;
+  hideDeleteButton?: boolean;
+  hideSortButton?: boolean;
+  hideFilterButton?: boolean;
+  hideSeeButton?: boolean;
+  calc?: string;
+  calcField?: string;
+  kpiConfig?: string;
+  chartType?: string;
+  xAxisField?: string;
+  xAxisDateFormat?: string;
+  xAxisTimeSeries?: boolean;
+  yAxisSerie?: string[];
+  legend?: string;
+  raw?: string;
+  rawFile?: string;
+}
+
+interface NavigationTargetMutationOptions {
+  sourceWidget?: string;
+  targetDisplay?: string;
+  targetVariable?: string;
+  label?: string;
+}
+
+interface CrossWidgetFilterSetOptions {
+  sourceWidget: string;
+  sourceField: string;
+  target: string[];
+}
+
+function getCommandIo(stdout: CommandIo | undefined): CommandIo {
+  return stdout ?? (process.stdout as Writable);
+}
+
+function writeLine(stdout: CommandIo, value: string): void {
+  stdout.write(`${value}\n`);
+}
+
+function getGlobalOptions(command: Command): GlobalOptions {
+  return command.optsWithGlobals<GlobalOptions>();
+}
+
+function emitJson(stdout: CommandIo, commandName: string, data: unknown): void {
+  writeLine(stdout, JSON.stringify(buildJsonSuccess(data, { command: commandName })));
+}
+
+function toConfigurationError(filePath: string, error: unknown): never {
+  if (error instanceof CliError) {
+    throw error;
+  }
+
+  if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+    throw new CliError("configuration_error", `Config file not found at ${filePath}.`);
+  }
+
+  if (error instanceof Error) {
+    throw new CliError("configuration_error", error.message);
+  }
+
+  throw error;
+}
+
+function createDisplaysApi(
+  command: Command,
+  filePath: string,
+): { api: DisplaysApi; json: boolean; readOnly: boolean } {
+  try {
+    const config = readConfig(filePath);
+    const runtime = resolveRuntimeContext(config, getGlobalOptions(command));
+
+    if (!runtime.baseUrl) {
+      throw new CliError("configuration_error", `Resolved profile "${runtime.profile}" is missing a base URL.`);
+    }
+
+    return {
+      api: new DisplaysApi(
+        new ApiClient({
+          baseUrl: runtime.baseUrl,
+          apiKey: runtime.apiKey,
+        }),
+      ),
+      json: runtime.json,
+      readOnly: runtime.readOnly,
+    };
+  } catch (error) {
+    toConfigurationError(filePath, error);
+  }
+}
+
+function ensureWritable(commandName: string, readOnly: boolean, mode: "write" | "destructive"): void {
+  if (readOnly) {
+    throw new CliError(
+      "command_not_allowed_in_read_only_mode",
+      `Command "${commandName}" is not allowed in read-only mode.`,
+      { commandMode: mode, executionMode: "read-only" },
+    );
+  }
+}
+
+function parseUuidOrSlugSelector(input: string): NormalizedUuidOrSlug {
+  try {
+    return normalizeUuidOrSlug(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid selector.";
+    throw new InvalidArgumentError(message);
+  }
+}
+
+function parseBooleanFlag(input: string): boolean {
+  const normalized = input.trim().toLowerCase();
+  if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
+  if (["false", "0", "no", "n", "off"].includes(normalized)) return false;
+  throw new InvalidArgumentError(`Expected a boolean value, received "${input}".`);
+}
+
+function parseNonNegativeInteger(input: string): number {
+  if (!/^\d+$/.test(input.trim())) {
+    throw new InvalidArgumentError(`Expected a non-negative integer, received "${input}".`);
+  }
+  return Number(input);
+}
+
+function readRawObject(raw?: string, rawFile?: string): Record<string, unknown> {
+  if (raw && rawFile) {
+    throw new CliError("invalid_cli_usage", 'Use either "--raw" or "--raw-file", not both.');
+  }
+
+  const source = rawFile ? readFileSync(rawFile, "utf8") : raw;
+  if (!source) {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(source) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new CliError("invalid_cli_usage", "Raw JSON payload must be a JSON object.");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError("invalid_cli_usage", "Raw JSON payload is invalid.");
+  }
+}
+
+function readNamedJsonOption(raw?: string, rawFile?: string, inlineFlag = "--option", fileFlag = "--option-file"): unknown {
+  if (raw && rawFile) {
+    throw new CliError("invalid_cli_usage", `Use either "${inlineFlag}" or "${fileFlag}", not both.`);
+  }
+  const source = rawFile ? readFileSync(rawFile, "utf8") : raw;
+  if (!source) return undefined;
+  try {
+    return JSON.parse(source) as unknown;
+  } catch {
+    throw new CliError("invalid_cli_usage", `${inlineFlag} payload is invalid JSON.`);
+  }
+}
+
+function isEmptyObject(value: object): boolean {
+  return Object.keys(value).length === 0;
+}
+
+function displayRows(displays: readonly DisplaySummary[]): Record<string, unknown>[] {
+  return displays.map((display) => ({
+    id: display.id,
+    name: display.name ?? "",
+    layoutTemplate: display.layoutTemplate ?? "",
+    variableCount: display.variableCount ?? "",
+    widgetCount: display.widgetCount ?? "",
+  }));
+}
+
+function getDisplaySubresource(value: unknown): Record<string, unknown>[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === "object");
+}
+
+function buildVariableBody(options: VariableMutationOptions): Record<string, unknown> {
+  const body = {
+    ...readRawObject(options.raw, options.rawFile),
+  };
+
+  if (options.type !== undefined) body.type = options.type;
+  if (options.name !== undefined) body.name = options.name;
+  if (options.allowMultiple !== undefined) body.allowMultiple = options.allowMultiple;
+  if (options.static !== undefined) body.staticVariable = options.static;
+  if (options.default !== undefined) body.defaultValue = options.default;
+  if (options.defaultValue && options.defaultValue.length > 0) body.defaultValues = options.defaultValue;
+  if (options.sourceSchema || options.sourceField) {
+    body.source = {
+      schemaId: options.sourceSchema,
+      fieldId: options.sourceField,
+    };
+  }
+  if (options.filter && options.filter.length > 0) {
+    body.filters = options.filter.map((entry) => ({ raw: entry }));
+  }
+  if (
+    options.dateMode ||
+    options.dateDynamicOption ||
+    options.dateSpecific ||
+    options.dateRangeStart ||
+    options.dateRangeEnd
+  ) {
+    body.date = {
+      mode: options.dateMode,
+      dynamicOption: options.dateDynamicOption,
+      specificDate: options.dateSpecific,
+      rangeStart: options.dateRangeStart,
+      rangeEnd: options.dateRangeEnd,
+    };
+  }
+
+  if (isEmptyObject(body)) {
+    throw new CliError("invalid_cli_usage", "Nothing to send for variable mutation.");
+  }
+
+  return body;
+}
+
+function buildWidgetBody(options: WidgetMutationOptions): Record<string, unknown> {
+  const body = {
+    ...readRawObject(options.raw, options.rawFile),
+  };
+
+  if (options.type !== undefined) {
+    const normalizedType = options.type.toLowerCase() === "table"
+      ? "TABLE_OR_SUBTABLE"
+      : options.type.toUpperCase();
+    body.type = normalizedType;
+  }
+
+  if (
+    options.name !== undefined ||
+    options.description !== undefined ||
+    options.icon !== undefined ||
+    options.color !== undefined
+  ) {
+    body.presentation = {
+      ...(typeof body.presentation === "object" && body.presentation ? body.presentation as Record<string, unknown> : {}),
+      name: options.name,
+      description: options.description,
+      icon: options.icon,
+      color: options.color,
+    };
+  }
+
+  if (options.originResource !== undefined || options.originSubschema !== undefined) {
+    body.source = {
+      ...(typeof body.source === "object" && body.source ? body.source as Record<string, unknown> : {}),
+      originResourceId: options.originResource,
+      isOriginSubSchema: options.originSubschema,
+    };
+  }
+
+  const layout = readNamedJsonOption(options.layout, options.layoutFile, "--layout", "--layout-file");
+  if (options.tab || options.slot || layout !== undefined) {
+    body.placement = {
+      ...(typeof body.placement === "object" && body.placement ? body.placement as Record<string, unknown> : {}),
+      tabId: options.tab,
+      slotId: options.slot,
+      layout,
+    };
+  }
+
+  if (options.field?.length || options.sort?.length || options.filter?.length) {
+    body.view = {
+      ...(typeof body.view === "object" && body.view ? body.view as Record<string, unknown> : {}),
+      fields: options.field,
+    };
+    body.query = {
+      ...(typeof body.query === "object" && body.query ? body.query as Record<string, unknown> : {}),
+      sorts: options.sort,
+      filters: options.filter?.map((entry) => ({ raw: entry })),
+    };
+  }
+
+  if (
+    options.widgetReadOnly !== undefined ||
+    options.hideAddButton !== undefined ||
+    options.hideDeleteButton !== undefined ||
+    options.hideSortButton !== undefined ||
+    options.hideFilterButton !== undefined ||
+    options.hideSeeButton !== undefined
+  ) {
+    body.behavior = {
+      ...(typeof body.behavior === "object" && body.behavior ? body.behavior as Record<string, unknown> : {}),
+      readOnly: options.widgetReadOnly,
+      hideAddButton: options.hideAddButton,
+      hideDeleteButton: options.hideDeleteButton,
+      hideSortButton: options.hideSortButton,
+      hideFilterButton: options.hideFilterButton,
+      hideSeeButton: options.hideSeeButton,
+    };
+  }
+
+  if (options.calc || options.calcField || options.kpiConfig) {
+    body.kpi = {
+      ...(typeof body.kpi === "object" && body.kpi ? body.kpi as Record<string, unknown> : {}),
+      typeCalc: options.calc,
+      fieldCalc: options.calcField,
+      config: readNamedJsonOption(options.kpiConfig, undefined, "--kpi-config"),
+    };
+  }
+
+  const hasChartFlags =
+    options.chartType !== undefined ||
+    options.xAxisField !== undefined ||
+    options.xAxisDateFormat !== undefined ||
+    options.xAxisTimeSeries !== undefined ||
+    (options.yAxisSerie?.length ?? 0) > 0 ||
+    options.legend !== undefined;
+  if (hasChartFlags) {
+    const legend = readNamedJsonOption(options.legend, undefined, "--legend");
+    body.chart = {
+      ...(typeof body.chart === "object" && body.chart ? body.chart as Record<string, unknown> : {}),
+      ...(options.chartType !== undefined ? { chartType: options.chartType } : {}),
+      ...(options.xAxisField !== undefined ? { xAxisFieldId: options.xAxisField } : {}),
+      ...(options.xAxisDateFormat !== undefined ? { xAxisDateFormat: options.xAxisDateFormat } : {}),
+      ...(options.xAxisTimeSeries !== undefined ? { xAxisAsTimeSerie: options.xAxisTimeSeries } : {}),
+      ...(options.yAxisSerie && options.yAxisSerie.length > 0
+        ? { yAxisSeries: options.yAxisSerie.map((entry) => JSON.parse(entry)) }
+        : {}),
+      ...(legend !== undefined ? { legend } : {}),
+    };
+  }
+
+  if (isEmptyObject(body)) {
+    throw new CliError("invalid_cli_usage", "Nothing to send for widget mutation.");
+  }
+
+  return body;
+}
+
+function buildNavigationTargetBody(options: NavigationTargetMutationOptions): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  if (options.sourceWidget !== undefined) body.sourceWidgetId = options.sourceWidget;
+  if (options.targetDisplay !== undefined) body.targetDisplayId = options.targetDisplay;
+  if (options.targetVariable !== undefined) body.targetVariableId = options.targetVariable;
+  if (options.label !== undefined) body.label = options.label;
+  if (isEmptyObject(body)) {
+    throw new CliError("invalid_cli_usage", "Nothing to send for navigation target mutation.");
+  }
+  return body;
+}
+
+function buildCrossWidgetFilterBody(options: CrossWidgetFilterSetOptions): Record<string, unknown> {
+  return {
+    source: {
+      widgetId: options.sourceWidget,
+      fieldId: options.sourceField,
+    },
+    targets: options.target.map((entry) => {
+      const [widgetId, fieldId] = entry.split(":");
+      if (!widgetId || !fieldId) {
+        throw new CliError("invalid_cli_usage", `Invalid --target entry "${entry}". Use <widgetId:fieldId>.`);
+      }
+      return { widgetId, fieldId };
+    }),
+  };
+}
+
+export function registerDisplaysCommands(
+  program: Command,
+  options: RegisterDisplaysCommandsOptions = {},
+): void {
+  const filePath = options.configPath ?? defaultConfigPath;
+  const stdout = getCommandIo(options.stdout);
+  const displays = program.command("displays").description("Manage displays");
+
+  displays
+    .command("list")
+    .description("List displays")
+    .action(async function action(this: Command) {
+      const { api, json } = createDisplaysApi(this, filePath);
+      const data = await api.listDisplays();
+      if (json) {
+        emitJson(stdout, "displays list", data);
+        return;
+      }
+      printTable(displayRows(data), ["id", "name", "layoutTemplate", "variableCount", "widgetCount"], stdout);
+    });
+
+  displays
+    .command("get")
+    .description("Get a display")
+    .argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+      const { api, json } = createDisplaysApi(this, filePath);
+      const data = await api.getDisplay(display);
+      if (json) {
+        emitJson(stdout, "displays get", data);
+        return;
+      }
+      printTable([{ id: data.id, name: data.name ?? "", layoutTemplate: data.layout?.template ?? "" }], ["id", "name", "layoutTemplate"], stdout);
+    });
+
+  displays
+    .command("create")
+    .description("Create a display")
+    .requiredOption("--name <name>", "display name")
+    .requiredOption("--template <template>", "layout template")
+    .option("--freeform-layouts <json>", "freeform layouts JSON")
+    .option("--freeform-layouts-file <path>", "freeform layouts JSON file")
+    .action(async function action(this: Command, commandOptions: DisplayCreateOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays create", readOnly, "write");
+      const layout: Record<string, unknown> = { template: commandOptions.template };
+      const freeformLayouts = readNamedJsonOption(
+        commandOptions.freeformLayouts,
+        commandOptions.freeformLayoutsFile,
+        "--freeform-layouts",
+        "--freeform-layouts-file",
+      );
+      if (freeformLayouts !== undefined) layout.freeformLayouts = freeformLayouts;
+      const data = await api.createDisplay({ name: commandOptions.name, layout });
+      if (json) {
+        emitJson(stdout, "displays create", data);
+        return;
+      }
+      writeLine(stdout, `Created display "${commandOptions.name}".`);
+    });
+
+  displays
+    .command("update")
+    .description("Update a display")
+    .argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .option("--name <name>", "display name")
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: DisplayUpdateOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays update", readOnly, "write");
+      if (!commandOptions.name) throw new CliError("invalid_cli_usage", "Nothing to update.");
+      const data = await api.updateDisplay(display, { name: commandOptions.name });
+      if (json) {
+        emitJson(stdout, "displays update", data);
+        return;
+      }
+      writeLine(stdout, `Updated display "${display.value}".`);
+    });
+
+  displays
+    .command("delete")
+    .description("Delete a display")
+    .argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays delete", readOnly, "destructive");
+      const data = await api.deleteDisplay(display);
+      if (json) {
+        emitJson(stdout, "displays delete", data);
+        return;
+      }
+      writeLine(stdout, `Deleted display "${display.value}".`);
+    });
+
+  const layout = displays.command("layout").description("Manage display layout");
+  layout
+    .command("get")
+    .description("Get display layout")
+    .argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+      const { api, json } = createDisplaysApi(this, filePath);
+      const data = await api.getDisplay(display);
+      const layoutData = data.layout ?? null;
+      if (json) {
+        emitJson(stdout, "displays layout get", layoutData);
+        return;
+      }
+      printTable(layoutData ? [{ template: layoutData.template ?? "", freeformLayouts: layoutData.freeformLayouts ?? "" }] : [], ["template", "freeformLayouts"], stdout);
+    });
+  layout
+    .command("update")
+    .description("Update display layout")
+    .argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .requiredOption("--template <template>", "layout template")
+    .option("--freeform-layouts <json>", "freeform layouts JSON")
+    .option("--freeform-layouts-file <path>", "freeform layouts JSON file")
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: LayoutUpdateOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath);
+      ensureWritable("displays layout update", readOnly, "write");
+      const body: Record<string, unknown> = { template: commandOptions.template };
+      const freeformLayouts = readNamedJsonOption(commandOptions.freeformLayouts, commandOptions.freeformLayoutsFile, "--freeform-layouts", "--freeform-layouts-file");
+      if (freeformLayouts !== undefined) body.freeformLayouts = freeformLayouts;
+      const data = await api.patchLayout(display, body);
+      if (json) {
+        emitJson(stdout, "displays layout update", data);
+        return;
+      }
+      writeLine(stdout, `Updated layout for display "${display.value}".`);
+    });
+
+  const tabs = displays.command("tabs").description("Manage display tabs");
+  tabs.command("list").description("List tabs").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+    const { api, json } = createDisplaysApi(this, filePath);
+    const data = await api.getDisplay(display);
+    const tabsData = getDisplaySubresource(data.layout?.tabs);
+    if (json) { emitJson(stdout, "displays tabs list", tabsData); return; }
+    printTable(tabsData, undefined, stdout);
+  });
+  tabs.command("create").description("Create a tab").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).option("--name <name>").option("--orientation <orientation>").action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: TabMutationOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable("displays tabs create", readOnly, "write");
+    const data = await api.createTab(display, { name: commandOptions.name, orientation: commandOptions.orientation });
+    if (json) { emitJson(stdout, "displays tabs create", data); return; }
+    writeLine(stdout, `Created tab on display "${display.value}".`);
+  });
+  tabs.command("update").description("Update a tab").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<tab>", "tab id").option("--name <name>").option("--orientation <orientation>").action(async function action(this: Command, display: NormalizedUuidOrSlug, tabId: string, commandOptions: TabMutationOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable("displays tabs update", readOnly, "write");
+    const data = await api.updateTab(display, tabId, { name: commandOptions.name, orientation: commandOptions.orientation });
+    if (json) { emitJson(stdout, "displays tabs update", data); return; }
+    writeLine(stdout, `Updated tab "${tabId}".`);
+  });
+  tabs.command("delete").description("Delete a tab").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<tab>", "tab id").action(async function action(this: Command, display: NormalizedUuidOrSlug, tabId: string) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable("displays tabs delete", readOnly, "destructive");
+    const data = await api.deleteTab(display, tabId);
+    if (json) { emitJson(stdout, "displays tabs delete", data); return; }
+    writeLine(stdout, `Deleted tab "${tabId}".`);
+  });
+
+  const variables = displays.command("variables").description("Manage display variables");
+  variables.command("list").description("List variables").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+    const { api, json } = createDisplaysApi(this, filePath);
+    const data = await api.getDisplay(display);
+    const items = getDisplaySubresource(data.variables);
+    if (json) { emitJson(stdout, "displays variables list", items); return; }
+    printTable(items, undefined, stdout);
+  });
+  variables.command("get").description("Get variable").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<variable>", "variable id").action(async function action(this: Command, display: NormalizedUuidOrSlug, variableId: string) {
+    const { api, json } = createDisplaysApi(this, filePath);
+    const data = await api.getDisplay(display);
+    const items = getDisplaySubresource(data.variables);
+    const match = items.find((item) => item && typeof item === "object" && "id" in item && String(item.id) === variableId);
+    if (!match) throw new CliError("invalid_cli_usage", `Variable "${variableId}" not found.`);
+    if (json) { emitJson(stdout, "displays variables get", match); return; }
+    printTable([match], undefined, stdout);
+  });
+  variables.command("create").description("Create variable").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .option("--type <type>").option("--name <name>").option("--allow-multiple").option("--static")
+    .option("--default <value>").option("--default-value <value>", "repeatable default value", (v, p: string[] = []) => [...p, v], [])
+    .option("--source-schema <id>").option("--source-field <id>").option("--filter <expr>", "repeatable filter", (v, p: string[] = []) => [...p, v], [])
+    .option("--date-mode <mode>").option("--date-dynamic-option <option>").option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
+    .option("--raw <json>").option("--raw-file <path>")
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: VariableMutationOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays variables create", readOnly, "write");
+      const data = await api.createVariable(display, buildVariableBody(commandOptions));
+      if (json) { emitJson(stdout, "displays variables create", data); return; }
+      writeLine(stdout, `Created variable on display "${display.value}".`);
+    });
+  variables.command("update").description("Update variable").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<variable>", "variable id")
+    .option("--type <type>").option("--name <name>").option("--allow-multiple").option("--static")
+    .option("--default <value>").option("--default-value <value>", "repeatable default value", (v, p: string[] = []) => [...p, v], [])
+    .option("--source-schema <id>").option("--source-field <id>").option("--filter <expr>", "repeatable filter", (v, p: string[] = []) => [...p, v], [])
+    .option("--date-mode <mode>").option("--date-dynamic-option <option>").option("--date-specific <iso>").option("--date-range-start <iso>").option("--date-range-end <iso>")
+    .option("--raw <json>").option("--raw-file <path>")
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug, variableId: string, commandOptions: VariableMutationOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays variables update", readOnly, "write");
+      const data = await api.updateVariable(display, variableId, buildVariableBody(commandOptions));
+      if (json) { emitJson(stdout, "displays variables update", data); return; }
+      writeLine(stdout, `Updated variable "${variableId}".`);
+    });
+  variables.command("delete").description("Delete variable").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<variable>", "variable id").action(async function action(this: Command, display: NormalizedUuidOrSlug, variableId: string) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays variables delete", readOnly, "destructive");
+    const data = await api.deleteVariable(display, variableId);
+    if (json) { emitJson(stdout, "displays variables delete", data); return; }
+    writeLine(stdout, `Deleted variable "${variableId}".`);
+  });
+
+  const widgets = displays.command("widgets").description("Manage display widgets");
+  widgets.command("list").description("List widgets").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+    const { api, json } = createDisplaysApi(this, filePath); const data = await api.getDisplay(display); const items = getDisplaySubresource(data.widgets);
+    if (json) { emitJson(stdout, "displays widgets list", items); return; } printTable(items, undefined, stdout);
+  });
+  widgets.command("get").description("Get widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<widget>", "widget id").action(async function action(this: Command, display: NormalizedUuidOrSlug, widgetId: string) {
+    const { api, json } = createDisplaysApi(this, filePath); const data = await api.getWidget(display, widgetId);
+    if (json) { emitJson(stdout, "displays widgets get", data); return; } printTable([data], undefined, stdout);
+  });
+  widgets.command("create").description("Create widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .requiredOption("--type <type>", "widget type")
+    .option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>")
+    .option("--origin-resource <uuid>").option("--origin-subschema")
+    .option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>")
+    .option("--field <field>", "repeatable field", (v, p: string[] = []) => [...p, v], [])
+    .option("--sort <sort>", "repeatable sort", (v, p: string[] = []) => [...p, v], [])
+    .option("--filter <expr>", "repeatable filter", (v, p: string[] = []) => [...p, v], [])
+    .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("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
+    .option("--chart-type <type>").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>").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>")
+    .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));
+      if (json) { emitJson(stdout, "displays widgets create", data); return; }
+      writeLine(stdout, `Created widget on display "${display.value}".`);
+    });
+  widgets.command("update").description("Update widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<widget>", "widget id")
+    .option("--type <type>").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>")
+    .option("--origin-resource <uuid>").option("--origin-subschema")
+    .option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>")
+    .option("--field <field>", "repeatable field", (v, p: string[] = []) => [...p, v], [])
+    .option("--sort <sort>", "repeatable sort", (v, p: string[] = []) => [...p, v], [])
+    .option("--filter <expr>", "repeatable filter", (v, p: string[] = []) => [...p, v], [])
+    .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("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
+    .option("--chart-type <type>").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>").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>")
+    .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));
+      if (json) { emitJson(stdout, "displays widgets update", data); return; }
+      writeLine(stdout, `Updated widget "${widgetId}".`);
+    });
+  widgets.command("delete").description("Delete widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<widget>", "widget id").action(async function action(this: Command, display: NormalizedUuidOrSlug, widgetId: string) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays widgets delete", readOnly, "destructive");
+    const data = await api.deleteWidget(display, widgetId);
+    if (json) { emitJson(stdout, "displays widgets delete", data); return; }
+    writeLine(stdout, `Deleted widget "${widgetId}".`);
+  });
+
+  const targets = displays.command("navigation-targets").description("Manage navigation targets");
+  targets.command("list").description("List navigation targets").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+    const { api, json } = createDisplaysApi(this, filePath); const data = await api.getDisplay(display); const items = getDisplaySubresource(data.navigationTargets);
+    if (json) { emitJson(stdout, "displays navigation-targets list", items); return; } printTable(items, undefined, stdout);
+  });
+  targets.command("create").description("Create navigation target").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .requiredOption("--source-widget <id>").requiredOption("--target-display <id>").requiredOption("--target-variable <id>").option("--label <label>")
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: NavigationTargetMutationOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays navigation-targets create", readOnly, "write");
+      const data = await api.createNavigationTarget(display, buildNavigationTargetBody(commandOptions));
+      if (json) { emitJson(stdout, "displays navigation-targets create", data); return; }
+      writeLine(stdout, `Created navigation target on display "${display.value}".`);
+    });
+  targets.command("update").description("Update navigation target").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<target>", "target id")
+    .option("--source-widget <id>").option("--target-display <id>").option("--target-variable <id>").option("--label <label>")
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug, targetId: string, commandOptions: NavigationTargetMutationOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays navigation-targets update", readOnly, "write");
+      const data = await api.updateNavigationTarget(display, targetId, buildNavigationTargetBody(commandOptions));
+      if (json) { emitJson(stdout, "displays navigation-targets update", data); return; }
+      writeLine(stdout, `Updated navigation target "${targetId}".`);
+    });
+  targets.command("delete").description("Delete navigation target").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).argument("<target>", "target id").action(async function action(this: Command, display: NormalizedUuidOrSlug, targetId: string) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays navigation-targets delete", readOnly, "destructive");
+    const data = await api.deleteNavigationTarget(display, targetId);
+    if (json) { emitJson(stdout, "displays navigation-targets delete", data); return; }
+    writeLine(stdout, `Deleted navigation target "${targetId}".`);
+  });
+
+  const cross = displays.command("cross-widget-filter").description("Manage cross widget filter");
+  cross.command("get").description("Get cross widget filter").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+    const { api, json } = createDisplaysApi(this, filePath); const data = await api.getDisplay(display); const item = data.crossWidgetFilter ?? null;
+    if (json) { emitJson(stdout, "displays cross-widget-filter get", item); return; } printTable(item ? [item] : [], undefined, stdout);
+  });
+  cross.command("set").description("Set cross widget filter").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
+    .requiredOption("--source-widget <id>").requiredOption("--source-field <id>").requiredOption("--target <widget:field>", "repeatable target", (v, p: string[] = []) => [...p, v], [])
+    .action(async function action(this: Command, display: NormalizedUuidOrSlug, commandOptions: CrossWidgetFilterSetOptions) {
+      const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays cross-widget-filter set", readOnly, "write");
+      const data = await api.setCrossWidgetFilter(display, buildCrossWidgetFilterBody(commandOptions));
+      if (json) { emitJson(stdout, "displays cross-widget-filter set", data); return; }
+      writeLine(stdout, `Updated cross widget filter for display "${display.value}".`);
+    });
+  cross.command("delete").description("Delete cross widget filter").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector).action(async function action(this: Command, display: NormalizedUuidOrSlug) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath); ensureWritable("displays cross-widget-filter delete", readOnly, "destructive");
+    const data = await api.deleteCrossWidgetFilter(display);
+    if (json) { emitJson(stdout, "displays cross-widget-filter delete", data); return; }
+    writeLine(stdout, `Deleted cross widget filter for display "${display.value}".`);
+  });
+}