zinkee 0.1.58 → 0.1.60

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -252,7 +252,7 @@ ${list}`
252
252
  };
253
253
  }
254
254
  async function showExamples(commandName, json, stdout, filters = {}) {
255
- const { getCommandExamples } = await import("./examples-RPCREBTK.js");
255
+ const { getCommandExamples } = await import("./examples-ELI5SKQH.js");
256
256
  const examples = getCommandExamples(commandName, filters);
257
257
  if (examples.length === 0) {
258
258
  throw new CliError("invalid_cli_usage", `No examples registered for "${commandName}".`);
@@ -2721,7 +2721,9 @@ var supportedComparators = /* @__PURE__ */ new Set([
2721
2721
  "lt",
2722
2722
  "lte",
2723
2723
  "contains",
2724
+ "not_contains",
2724
2725
  "in",
2726
+ "between",
2725
2727
  "is_empty",
2726
2728
  "is_not_empty"
2727
2729
  ]);
@@ -2763,8 +2765,13 @@ function normalizeValue(comparator, rawValue) {
2763
2765
  }
2764
2766
  return null;
2765
2767
  }
2766
- if (comparator === "in") {
2768
+ if (comparator === "in" || comparator === "between") {
2767
2769
  const values = rawValue.split(",").map((value) => value.trim()).filter(Boolean);
2770
+ if (comparator === "between" && values.length !== 2) {
2771
+ throw new Error(
2772
+ `Comparator "between" requires exactly two comma-separated values (from,to), got "${rawValue}".`
2773
+ );
2774
+ }
2768
2775
  if (values.length === 0) {
2769
2776
  throw new Error(`Comparator "${comparator}" requires at least one value.`);
2770
2777
  }
@@ -2775,10 +2782,10 @@ function normalizeValue(comparator, rawValue) {
2775
2782
  }
2776
2783
  return rawValue;
2777
2784
  }
2778
- function parseExpression(input) {
2785
+ function parseExpression(input, comparators = supportedComparators) {
2779
2786
  const trimmed = input.trim();
2780
2787
  const [field, comparatorCandidate, rawValue] = trimmed.includes(":") && !trimmed.includes(" ") ? parseColonExpression(trimmed) : parseSpaceExpression(trimmed);
2781
- if (!supportedComparators.has(comparatorCandidate)) {
2788
+ if (!comparators.has(comparatorCandidate)) {
2782
2789
  throw new Error(
2783
2790
  `Unsupported comparator "${comparatorCandidate}" in expression "${input}".`
2784
2791
  );
@@ -2813,6 +2820,9 @@ var COMPARATOR_TO_DISPLAY_OPERATOR = {
2813
2820
  is_empty: "IS_EMPTY",
2814
2821
  is_not_empty: "IS_NOT_EMPTY"
2815
2822
  };
2823
+ var DISPLAY_FILTER_COMPARATORS = new Set(
2824
+ Object.keys(COMPARATOR_TO_DISPLAY_OPERATOR)
2825
+ );
2816
2826
  function toDisplayFilter(parsed) {
2817
2827
  const values = parsed.value === null ? [] : Array.isArray(parsed.value) ? [...parsed.value] : [parsed.value];
2818
2828
  return {
@@ -2823,7 +2833,7 @@ function toDisplayFilter(parsed) {
2823
2833
  }
2824
2834
  function parseFilterExpression(input) {
2825
2835
  try {
2826
- return parseExpression(input);
2836
+ return parseExpression(input, DISPLAY_FILTER_COMPARATORS);
2827
2837
  } catch (error) {
2828
2838
  const message = error instanceof Error ? error.message : "Invalid filter expression.";
2829
2839
  throw new InvalidArgumentError2(message);
@@ -2867,8 +2877,20 @@ function parseLockMessageOption(input) {
2867
2877
  function collectLockMessages(value, previous = []) {
2868
2878
  return [...previous, parseLockMessageOption(value)];
2869
2879
  }
2880
+ function parseLockMatchOption(input) {
2881
+ const separatorIndex = input.indexOf(":");
2882
+ const lockedField = separatorIndex > 0 ? input.slice(0, separatorIndex).trim() : "";
2883
+ const match = separatorIndex > 0 ? input.slice(separatorIndex + 1).trim().toUpperCase() : "";
2884
+ if (!lockedField || match !== "ALL" && match !== "ANY") {
2885
+ throw new InvalidArgumentError2('Expected "<lockedField>:all|any", e.g. "status:any".');
2886
+ }
2887
+ return { lockedField, conditionMatch: match };
2888
+ }
2889
+ function collectLockMatches(value, previous = []) {
2890
+ return [...previous, parseLockMatchOption(value)];
2891
+ }
2870
2892
  function buildLockedFields(options) {
2871
- const hasLockFlags = (options.lockField?.length ?? 0) > 0 || (options.lockCondition?.length ?? 0) > 0 || (options.lockMessageBefore?.length ?? 0) > 0 || (options.lockMessageAfter?.length ?? 0) > 0;
2893
+ const hasLockFlags = (options.lockField?.length ?? 0) > 0 || (options.lockCondition?.length ?? 0) > 0 || (options.lockMessageBefore?.length ?? 0) > 0 || (options.lockMessageAfter?.length ?? 0) > 0 || (options.lockMatch?.length ?? 0) > 0;
2872
2894
  if (options.clearLockedFields) {
2873
2895
  if (hasLockFlags) {
2874
2896
  throw new CliError(
@@ -2902,9 +2924,21 @@ function buildLockedFields(options) {
2902
2924
  for (const { lockedField, message } of options.lockMessageAfter ?? []) {
2903
2925
  ensureRule(lockedField).messageAfterLock = message;
2904
2926
  }
2927
+ for (const { lockedField, conditionMatch } of options.lockMatch ?? []) {
2928
+ ensureRule(lockedField).conditionMatch = conditionMatch;
2929
+ }
2930
+ for (const [lockedField, rule] of rules) {
2931
+ if (rule.conditionMatch !== void 0 && rule.conditions.length === 0) {
2932
+ throw new CliError(
2933
+ "invalid_cli_usage",
2934
+ `"--lock-match ${lockedField}:..." needs at least one "--lock-condition" for "${lockedField}"; a lock without conditions always applies.`
2935
+ );
2936
+ }
2937
+ }
2905
2938
  return [...rules.entries()].map(([lockedField, rule]) => ({
2906
2939
  field: { fieldId: lockedField },
2907
2940
  conditions: rule.conditions,
2941
+ ...rule.conditionMatch !== void 0 ? { conditionMatch: rule.conditionMatch } : {},
2908
2942
  ...rule.messageBeforeLock !== void 0 ? { messageBeforeLock: rule.messageBeforeLock } : {},
2909
2943
  ...rule.messageAfterLock !== void 0 ? { messageAfterLock: rule.messageAfterLock } : {}
2910
2944
  }));
@@ -3611,7 +3645,7 @@ function registerDisplaysCommands(program, options = {}) {
3611
3645
  }
3612
3646
  printTable([data], void 0, stdout);
3613
3647
  });
3614
- 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 = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...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 = []) => [...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 = []) => [...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 = []) => [...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 = []) => [...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 = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...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(display, commandOptions) {
3648
+ 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 = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...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 = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match, or any with --lock-match (repeatable)', collectLockConditions, []).option("--lock-match <field:all|any>", "how the conditions of a lock combine: all (default) or any (repeatable)", collectLockMatches, []).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 = []) => [...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 = []) => [...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 = []) => [...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 = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...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(display, commandOptions) {
3615
3649
  const { api, json, readOnly } = createDisplaysApi(this, filePath);
3616
3650
  ensureWritable("displays widgets create", readOnly, "write");
3617
3651
  const data = await api.createWidget(display, buildWidgetBody(commandOptions));
@@ -3621,7 +3655,7 @@ function registerDisplaysCommands(program, options = {}) {
3621
3655
  }
3622
3656
  writeLine(stdout, `Created widget on display "${display.value}".`);
3623
3657
  });
3624
- 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>", "visible field (repeatable); merged into the saved view: visible columns keep position/width, hidden or new ones go to the end, omitted ones are hidden", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...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 = []) => [...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 = []) => [...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* ...); merged key by key into the saved viewState").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 = []) => [...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 = []) => [...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 = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...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(display, widgetId, commandOptions) {
3658
+ 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>", "visible field (repeatable); merged into the saved view: visible columns keep position/width, hidden or new ones go to the end, omitted ones are hidden", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...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 = []) => [...p, v], []).option("--lock-condition <expr>", 'conditional lock "<lockedField>:<field>:<comparator>[:<value>]"; locks <lockedField> when all its conditions match, or any with --lock-match (repeatable)', collectLockConditions, []).option("--lock-match <field:all|any>", "how the conditions of a lock combine: all (default) or any (repeatable)", collectLockMatches, []).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 = []) => [...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* ...); merged key by key into the saved viewState").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 = []) => [...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 = []) => [...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 = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...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(display, widgetId, commandOptions) {
3625
3659
  const { api, json, readOnly } = createDisplaysApi(this, filePath);
3626
3660
  ensureWritable("displays widgets update", readOnly, "write");
3627
3661
  const data = await api.updateWidget(display, widgetId, buildWidgetBody(commandOptions));
@@ -4720,6 +4754,29 @@ import { readFileSync as readFileSync5 } from "fs";
4720
4754
  import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
4721
4755
 
4722
4756
  // src/api/records.ts
4757
+ function isQueryExpression(entry) {
4758
+ return typeof entry === "object" && entry !== null && "comparator" in entry && !("op" in entry);
4759
+ }
4760
+ function toWhereNode(entry) {
4761
+ if (!isQueryExpression(entry)) {
4762
+ return entry;
4763
+ }
4764
+ return {
4765
+ field: entry.field,
4766
+ op: entry.comparator,
4767
+ value: entry.value
4768
+ };
4769
+ }
4770
+ function toSort(entry) {
4771
+ if (typeof entry !== "string") {
4772
+ return entry;
4773
+ }
4774
+ const [field = "", direction = "asc"] = entry.split(":");
4775
+ return {
4776
+ field,
4777
+ direction: direction.toUpperCase()
4778
+ };
4779
+ }
4723
4780
  function jsonOptions6(body, method) {
4724
4781
  return {
4725
4782
  method,
@@ -4783,19 +4840,11 @@ var RecordsApi = class {
4783
4840
  { method: "DELETE" }
4784
4841
  );
4785
4842
  }
4843
+ // Only the CLI forms (comparator expressions, "field:dir" sort strings, limit/offset)
4844
+ // are converted; native payloads from --raw/--where-json reach the API untouched.
4786
4845
  normalizeQueryInput(query) {
4787
- const where = query.where?.map((expression) => ({
4788
- field: expression.field,
4789
- op: expression.comparator,
4790
- value: expression.value
4791
- }));
4792
- const sort = query.sort?.map((entry) => {
4793
- const [field, direction = "asc"] = entry.split(":");
4794
- return {
4795
- field,
4796
- direction: direction.toUpperCase()
4797
- };
4798
- });
4846
+ const where = Array.isArray(query.where) ? query.where.map(toWhereNode) : query.where;
4847
+ const sort = Array.isArray(query.sort) ? query.sort.map(toSort) : query.sort;
4799
4848
  return {
4800
4849
  ...query,
4801
4850
  select: query.select,
@@ -4804,7 +4853,7 @@ var RecordsApi = class {
4804
4853
  page: query.limit !== void 0 || query.offset !== void 0 ? {
4805
4854
  offset: query.offset,
4806
4855
  limit: query.limit
4807
- } : void 0,
4856
+ } : query.page,
4808
4857
  limit: void 0,
4809
4858
  offset: void 0
4810
4859
  };
@@ -5017,13 +5066,45 @@ function toQueryExpressions(expressions) {
5017
5066
  value: expression.value
5018
5067
  }));
5019
5068
  }
5069
+ function parseWhereJson(input) {
5070
+ let parsed;
5071
+ try {
5072
+ parsed = JSON.parse(input);
5073
+ } catch (error) {
5074
+ const message = error instanceof Error ? error.message : "Invalid JSON.";
5075
+ throw new CliError(
5076
+ "invalid_cli_usage",
5077
+ `Failed to parse JSON from --where-json: ${message}`
5078
+ );
5079
+ }
5080
+ if (!Array.isArray(parsed) && !isJsonObject(parsed)) {
5081
+ throw new CliError(
5082
+ "invalid_cli_usage",
5083
+ 'Expected --where-json to contain a JSON array of conditions or a JSON object (a condition or an {"and"|"or": [...]} group).'
5084
+ );
5085
+ }
5086
+ return parsed;
5087
+ }
5088
+ function resolveWhere(options) {
5089
+ const where = toQueryExpressions(options.where);
5090
+ if (options.whereJson !== void 0) {
5091
+ if (where) {
5092
+ throw new CliError(
5093
+ "invalid_cli_usage",
5094
+ 'Provide either "--where" or "--where-json", not both.'
5095
+ );
5096
+ }
5097
+ return parseWhereJson(options.whereJson);
5098
+ }
5099
+ return where;
5100
+ }
5020
5101
  function buildRecordQueryInput(options, allowRaw) {
5021
5102
  const input = allowRaw ? readRawObject(options.raw, options.rawFile) : {};
5022
5103
  if (options.select && options.select.length > 0) {
5023
5104
  input.select = [...options.select];
5024
5105
  }
5025
- const where = toQueryExpressions(options.where);
5026
- if (where && where.length > 0) {
5106
+ const where = resolveWhere(options);
5107
+ if (where !== void 0) {
5027
5108
  input.where = where;
5028
5109
  }
5029
5110
  if (options.search !== void 0) {
@@ -5182,16 +5263,22 @@ function registerRecordsCommands(program, options = {}) {
5182
5263
  }
5183
5264
  emitTable(stdout, recordsData);
5184
5265
  });
5185
- records.command("query").description("Query records for a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--select <fields>", "field selection (comma-separated, repeatable)", collectSelectValues, []).option("--where <expression>", "where expression", collectWhereExpressions, []).option(
5266
+ records.command("query").description("Query records for a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--select <fields>", "field selection (comma-separated, repeatable)", collectSelectValues, []).option(
5267
+ "--where <expression>",
5268
+ 'condition "<field> <op> [value]" (repeatable, combined with AND)',
5269
+ collectWhereExpressions,
5270
+ []
5271
+ ).option(
5272
+ "--where-json <json>",
5273
+ 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
5274
+ ).option(
5186
5275
  "--search <term>",
5187
5276
  "free-text search term (matched across the schema's searchable fields)"
5188
5277
  ).option("--sort <field:direction>", "sort field(s)", collectSortValues, []).option("--limit <number>", "limit results", parseNonNegativeInteger).option("--offset <number>", "offset results", parseNonNegativeInteger).option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, commandOptions) {
5189
5278
  const { api, schemasApi, json } = createRecordsApi(this, filePath);
5279
+ const query = buildRecordQueryInput(commandOptions, true);
5190
5280
  const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5191
- const data = await api.queryRecords(
5192
- resolvedSchema,
5193
- buildRecordQueryInput(commandOptions, true)
5194
- );
5281
+ const data = await api.queryRecords(resolvedSchema, query);
5195
5282
  const recordsData = getQueryRecords(data);
5196
5283
  if (json) {
5197
5284
  emitJson(