zinkee 0.1.44 → 0.1.45

package/src/commands/displays.ts

@@ -1,1442 +0,0 @@
-import { readFileSync } from "node:fs";
-import type { Writable } from "node:stream";
-
-import { Command, InvalidArgumentError } from "commander";
-
-import {
-  DisplaysApi,
-  type ApiDisplayFolder,
-  type DisplayResource,
-  type DisplaySummary,
-} from "../api/displays.js";
-import { ApiClient } from "../client.js";
-import { defaultConfigPath, readRuntimeConfig } from "../config.js";
-import {
-  parseExpression,
-  type ExpressionComparator,
-  type ParsedExpression,
-} from "../parsers/expressions.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, folderColumns, FOLDER_TABLE_KEYS, printTable } from "../utils/output.js";
-
-const DATE_DYNAMIC_OPTIONS =
-  "today, thisWeek, thisMonth, thisQuarter, thisSemester, thisYear, next7Days, next30Days, next6Months, next12Months, last12Months";
-
-interface CommandIo {
-  write(chunk: string): unknown;
-}
-
-export interface RegisterDisplaysCommandsOptions {
-  configPath?: string;
-  stdout?: CommandIo;
-}
-
-interface GlobalOptions extends RuntimeOverrides {}
-
-interface DisplayCreateOptions {
-  name: string;
-  description?: string;
-  template: string;
-  freeformLayouts?: string;
-  freeformLayoutsFile?: string;
-}
-
-interface DisplayUpdateOptions {
-  name?: string;
-  description?: 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?: ParsedExpression[];
-  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?: ParsedExpression[];
-  widgetReadOnly?: boolean;
-  hideAddButton?: boolean;
-  hideDeleteButton?: boolean;
-  hideSortButton?: boolean;
-  hideFilterButton?: boolean;
-  hideSeeButton?: boolean;
-  lockField?: string[];
-  lockCondition?: LockConditionOption[];
-  lockMessageBefore?: LockMessageOption[];
-  lockMessageAfter?: LockMessageOption[];
-  clearLockedFields?: boolean;
-  calc?: string;
-  calcField?: string;
-  kpiConfig?: string;
-  chartType?: string;
-  xAxisField?: string;
-  xAxisDateFormat?: string;
-  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;
-}
-
-interface LockConditionOption {
-  lockedField: string;
-  expression: ParsedExpression;
-}
-
-interface LockMessageOption {
-  lockedField: string;
-  message: string;
-}
-
-interface NavigationTargetMutationOptions {
-  sourceWidget?: string;
-  targetDisplay?: string;
-  targetVariable?: string;
-  label?: string;
-}
-
-interface CrossWidgetFilterSetOptions {
-  sourceWidget?: string;
-  sourceField?: string;
-  sourceSchema?: string;
-  target?: string[];
-  raw?: string;
-  rawFile?: 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 = readRuntimeConfig(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);
-  }
-}
-
-const COMPARATOR_TO_DISPLAY_OPERATOR: Record<ExpressionComparator, string> = {
-  eq: "EQUAL",
-  neq: "NOT_EQUAL",
-  gt: "GREATER",
-  gte: "GREATER_OR_EQUAL",
-  lt: "LESS",
-  lte: "LESS_OR_EQUAL",
-  contains: "CONTAINS",
-  in: "ANY_OF",
-  is_empty: "IS_EMPTY",
-  is_not_empty: "IS_NOT_EMPTY",
-};
-
-function toDisplayFilter(parsed: ParsedExpression): Record<string, unknown> {
-  const values =
-    parsed.value === null
-      ? []
-      : Array.isArray(parsed.value)
-        ? [...parsed.value]
-        : [parsed.value];
-  return {
-    origin: { fieldId: parsed.field },
-    comparisonOperator: COMPARATOR_TO_DISPLAY_OPERATOR[parsed.comparator],
-    values,
-  };
-}
-
-function parseFilterExpression(input: string): ParsedExpression {
-  try {
-    return parseExpression(input);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Invalid filter expression.";
-    throw new InvalidArgumentError(message);
-  }
-}
-
-function collectFilters(value: string, previous: ParsedExpression[] = []): ParsedExpression[] {
-  return [...previous, parseFilterExpression(value)];
-}
-
-function parseLockConditionOption(input: string): LockConditionOption {
-  const trimmed = input.trim();
-  let lockedField: string;
-  let expressionText: string;
-
-  if (trimmed.includes(":") && !trimmed.includes(" ")) {
-    const separatorIndex = trimmed.indexOf(":");
-    lockedField = trimmed.slice(0, separatorIndex).trim();
-    expressionText = trimmed.slice(separatorIndex + 1).trim();
-  } else {
-    const parts = trimmed.split(/\s+/);
-    lockedField = parts[0]?.trim() ?? "";
-    expressionText = parts.slice(1).join(" ").trim();
-  }
-
-  if (!lockedField || !expressionText) {
-    throw new InvalidArgumentError(
-      'Expected "<lockedField>:<field>:<comparator>[:<value>]" (or space-separated), e.g. "status:invoice-number:is_empty".',
-    );
-  }
-
-  return { lockedField, expression: parseFilterExpression(expressionText) };
-}
-
-function collectLockConditions(value: string, previous: LockConditionOption[] = []): LockConditionOption[] {
-  return [...previous, parseLockConditionOption(value)];
-}
-
-function parseLockMessageOption(input: string): LockMessageOption {
-  const separatorIndex = input.indexOf(":");
-  const lockedField = separatorIndex > 0 ? input.slice(0, separatorIndex).trim() : "";
-  const message = separatorIndex > 0 ? input.slice(separatorIndex + 1).trim() : "";
-
-  if (!lockedField || !message) {
-    throw new InvalidArgumentError('Expected "<lockedField>:<message>", e.g. "status:Locked once approved.".');
-  }
-
-  return { lockedField, message };
-}
-
-function collectLockMessages(value: string, previous: LockMessageOption[] = []): LockMessageOption[] {
-  return [...previous, parseLockMessageOption(value)];
-}
-
-/**
- * Builds behavior.lockedFields from the --lock-* flags. Every flag names its
- * locked field explicitly, so ordering between flags never matters. A field
- * with no conditions is locked permanently; with conditions it locks when all
- * of them match (AND). Returns [] for --clear-locked-fields and undefined when
- * no lock flag was used.
- */
-function buildLockedFields(options: WidgetMutationOptions): Array<Record<string, unknown>> | undefined {
-  const hasLockFlags =
-    (options.lockField?.length ?? 0) > 0 ||
-    (options.lockCondition?.length ?? 0) > 0 ||
-    (options.lockMessageBefore?.length ?? 0) > 0 ||
-    (options.lockMessageAfter?.length ?? 0) > 0;
-
-  if (options.clearLockedFields) {
-    if (hasLockFlags) {
-      throw new CliError(
-        "invalid_cli_usage",
-        'Use either "--clear-locked-fields" or the "--lock-*" flags, not both.',
-      );
-    }
-    return [];
-  }
-
-  if (!hasLockFlags) {
-    return undefined;
-  }
-
-  interface LockRule {
-    conditions: Array<Record<string, unknown>>;
-    messageBeforeLock?: string;
-    messageAfterLock?: string;
-  }
-
-  const rules = new Map<string, LockRule>();
-  const ensureRule = (lockedField: string): LockRule => {
-    let rule = rules.get(lockedField);
-    if (!rule) {
-      rule = { conditions: [] };
-      rules.set(lockedField, rule);
-    }
-    return rule;
-  };
-
-  for (const lockedField of options.lockField ?? []) {
-    ensureRule(lockedField);
-  }
-  for (const { lockedField, expression } of options.lockCondition ?? []) {
-    ensureRule(lockedField).conditions.push(toDisplayFilter(expression));
-  }
-  for (const { lockedField, message } of options.lockMessageBefore ?? []) {
-    ensureRule(lockedField).messageBeforeLock = message;
-  }
-  for (const { lockedField, message } of options.lockMessageAfter ?? []) {
-    ensureRule(lockedField).messageAfterLock = message;
-  }
-
-  return [...rules.entries()].map(([lockedField, rule]) => ({
-    field: { fieldId: lockedField },
-    conditions: rule.conditions,
-    ...(rule.messageBeforeLock !== undefined ? { messageBeforeLock: rule.messageBeforeLock } : {}),
-    ...(rule.messageAfterLock !== undefined ? { messageAfterLock: rule.messageAfterLock } : {}),
-  }));
-}
-
-function parseBooleanFlag(input: string): boolean {
-  const normalized = input.trim().toLowerCase();
-  if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
-  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 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,
-    name: display.name ?? "",
-    layoutTemplate: display.layoutTemplate ?? "",
-    variableCount: display.variableCount ?? "",
-    widgetCount: display.widgetCount ?? "",
-    ...folderColumns(display.folder),
-  }));
-}
-
-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 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),
-  };
-
-  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(toDisplayFilter);
-  }
-  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,
-    };
-  }
-
-  const viewPatch: Record<string, unknown> = {};
-  if (options.field && options.field.length > 0) {
-    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);
-  if (Object.keys(queryMerge).length > 0) {
-    body.query = {
-      ...(typeof body.query === "object" && body.query ? body.query as Record<string, unknown> : {}),
-      ...queryMerge,
-    };
-  }
-
-  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,
-    };
-  }
-
-  const lockedFields = buildLockedFields(options);
-  if (lockedFields !== undefined) {
-    body.behavior = {
-      ...(typeof body.behavior === "object" && body.behavior ? body.behavior as Record<string, unknown> : {}),
-      lockedFields,
-    };
-  }
-
-  if (options.calc || options.calcField || options.kpiConfig) {
-    body.kpi = {
-      ...(typeof body.kpi === "object" && body.kpi ? body.kpi as Record<string, unknown> : {}),
-      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 readRawArray(raw?: string, rawFile?: 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 (!Array.isArray(parsed)) {
-      throw new CliError("invalid_cli_usage", "Raw cross widget filter payload must be a JSON array of configurations.");
-    }
-    return parsed;
-  } catch (error) {
-    if (error instanceof CliError) throw error;
-    throw new CliError("invalid_cli_usage", "Raw JSON payload is invalid.");
-  }
-}
-
-// The endpoint replaces the whole array of configurations. With flags a single configuration is
-// built and wrapped in an array; use --raw/--raw-file to send several configurations at once.
-function buildCrossWidgetFilterBody(options: CrossWidgetFilterSetOptions): unknown[] {
-  if (options.raw !== undefined || options.rawFile !== undefined) {
-    return readRawArray(options.raw, options.rawFile);
-  }
-
-  if (!options.sourceWidget || !options.sourceField) {
-    throw new CliError(
-      "invalid_cli_usage",
-      "Provide --source-widget and --source-field, or --raw/--raw-file with the full configuration array.",
-    );
-  }
-
-  const source: Record<string, unknown> = {
-    widgetId: options.sourceWidget,
-    fieldId: options.sourceField,
-  };
-  if (options.sourceSchema) {
-    source.schemaId = options.sourceSchema;
-  }
-
-  return [
-    {
-      source,
-      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", ...FOLDER_TABLE_KEYS],
-        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")
-    .option("--description <text>", "display description")
-    .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,
-        description: commandOptions.description,
-        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")
-    .option("--description <text>", 'display description (use "" to clear)')
-    .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 === undefined && commandOptions.description === undefined) {
-        throw new CliError("invalid_cli_usage", "Nothing to update.");
-      }
-      if (commandOptions.name !== undefined && commandOptions.name.trim().length === 0) {
-        throw new CliError("invalid_cli_usage", "Display name cannot be empty.");
-      }
-      const data = await api.updateDisplay(display, {
-        name: commandOptions.name,
-        description: commandOptions.description,
-      });
-      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 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")
-    .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", collectFilters, [])
-    .option("--date-mode <mode>").option("--date-dynamic-option <option>", `dynamic date period (${DATE_DYNAMIC_OPTIONS})`).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", collectFilters, [])
-    .option("--date-mode <mode>").option("--date-dynamic-option <option>", `dynamic date period (${DATE_DYNAMIC_OPTIONS})`).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", collectFilters, [])
-    .option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button")
-    .option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p: string[] = []) => [...p, v], [])
-    .option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, [])
-    .option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, [])
-    .option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, [])
-    .option("--clear-locked-fields", "clear the widget locked-fields configuration")
-    .option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
-    .option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series")
-    .option("--y-axis-serie <json>", "repeatable y axis serie", (v, p: string[] = []) => [...p, v], [])
-    .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));
-      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", collectFilters, [])
-    .option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button")
-    .option("--lock-field <field>", "lock a field permanently in this widget (repeatable; field UUID or slug)", (v, p: string[] = []) => [...p, v], [])
-    .option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match (AND, repeatable)', collectLockConditions, [])
-    .option("--lock-message-before <field:text>", "message shown while a conditional lock is not met yet (repeatable)", collectLockMessages, [])
-    .option("--lock-message-after <field:text>", "message shown once the field is locked (repeatable)", collectLockMessages, [])
-    .option("--clear-locked-fields", "clear the widget locked-fields configuration")
-    .option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>")
-    .option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series")
-    .option("--y-axis-serie <json>", "repeatable y axis serie", (v, p: string[] = []) => [...p, v], [])
-    .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));
-      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 ?? [], undefined, stdout);
-  });
-  cross.command("set").description("Set cross widget filter (replaces the whole array of configurations)").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector)
-    .option("--source-widget <id>", "source widget id (single-configuration mode)")
-    .option("--source-field <id>", "source field id (single-configuration mode)")
-    .option("--source-schema <id>", "source schema id, only for HIERARCHY source widgets")
-    .option("--target <widget:field>", "repeatable target (single-configuration mode)", (v, p: string[] = []) => [...p, v], [])
-    .option("--raw <json>", "full array of configurations as JSON (for several configurations)")
-    .option("--raw-file <path>", "path to a JSON file with the full array of configurations")
-    .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}".`);
-  });
-}