zinkee 0.1.62 → 0.1.64

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
@@ -18,7 +18,7 @@ import {
18
18
  normalizeSchemaFieldUpdatePayload,
19
19
  printTable,
20
20
  toCliError
21
- } from "./chunk-JBTOZQSO.js";
21
+ } from "./chunk-UAL4VMAW.js";
22
22
 
23
23
  // src/cli-runner.ts
24
24
  import { realpathSync } from "fs";
@@ -253,7 +253,7 @@ ${list}`
253
253
  };
254
254
  }
255
255
  async function showExamples(commandName, json, stdout, filters = {}) {
256
- const { getCommandExamples } = await import("./examples-W3D7LVWT.js");
256
+ const { getCommandExamples } = await import("./examples-RRNLFYD4.js");
257
257
  const examples = getCommandExamples(commandName, filters);
258
258
  if (examples.length === 0) {
259
259
  throw new CliError("invalid_cli_usage", `No examples registered for "${commandName}".`);
@@ -2914,8 +2914,20 @@ function parseLockMatchOption(input) {
2914
2914
  function collectLockMatches(value, previous = []) {
2915
2915
  return [...previous, parseLockMatchOption(value)];
2916
2916
  }
2917
+ function parseLockOptionOption(input) {
2918
+ const separatorIndex = input.indexOf(":");
2919
+ const lockedField = separatorIndex > 0 ? input.slice(0, separatorIndex).trim() : "";
2920
+ const option = separatorIndex > 0 ? input.slice(separatorIndex + 1).trim() : "";
2921
+ if (!lockedField || !option) {
2922
+ throw new InvalidArgumentError2('Expected "<lockedField>:<option>", e.g. "status:Paid".');
2923
+ }
2924
+ return { lockedField, option };
2925
+ }
2926
+ function collectLockOptions(value, previous = []) {
2927
+ return [...previous, parseLockOptionOption(value)];
2928
+ }
2917
2929
  function buildLockedFields(options) {
2918
- 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;
2930
+ 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 || (options.lockOption?.length ?? 0) > 0;
2919
2931
  if (options.clearLockedFields) {
2920
2932
  if (hasLockFlags) {
2921
2933
  throw new CliError(
@@ -2932,7 +2944,7 @@ function buildLockedFields(options) {
2932
2944
  const ensureRule = (lockedField) => {
2933
2945
  let rule = rules.get(lockedField);
2934
2946
  if (!rule) {
2935
- rule = { conditions: [] };
2947
+ rule = { lockedOptions: [], conditions: [] };
2936
2948
  rules.set(lockedField, rule);
2937
2949
  }
2938
2950
  return rule;
@@ -2952,6 +2964,9 @@ function buildLockedFields(options) {
2952
2964
  for (const { lockedField, conditionMatch } of options.lockMatch ?? []) {
2953
2965
  ensureRule(lockedField).conditionMatch = conditionMatch;
2954
2966
  }
2967
+ for (const { lockedField, option } of options.lockOption ?? []) {
2968
+ ensureRule(lockedField).lockedOptions.push(option);
2969
+ }
2955
2970
  for (const [lockedField, rule] of rules) {
2956
2971
  if (rule.conditionMatch !== void 0 && rule.conditions.length === 0) {
2957
2972
  throw new CliError(
@@ -2962,6 +2977,7 @@ function buildLockedFields(options) {
2962
2977
  }
2963
2978
  return [...rules.entries()].map(([lockedField, rule]) => ({
2964
2979
  field: { fieldId: lockedField },
2980
+ ...rule.lockedOptions.length > 0 ? { lockedOptions: rule.lockedOptions } : {},
2965
2981
  conditions: rule.conditions,
2966
2982
  ...rule.conditionMatch !== void 0 ? { conditionMatch: rule.conditionMatch } : {},
2967
2983
  ...rule.messageBeforeLock !== void 0 ? { messageBeforeLock: rule.messageBeforeLock } : {},
@@ -3670,7 +3686,7 @@ function registerDisplaysCommands(program, options = {}) {
3670
3686
  }
3671
3687
  printTable([data], void 0, stdout);
3672
3688
  });
3673
- 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) {
3689
+ 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-option <field:option>", "lock only this option of an option field (repeatable; option name or id); its other options and leaving it empty stay allowed", collectLockOptions, []).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) {
3674
3690
  const { api, json, readOnly } = createDisplaysApi(this, filePath);
3675
3691
  ensureWritable("displays widgets create", readOnly, "write");
3676
3692
  const data = await api.createWidget(display, buildWidgetBody(commandOptions));
@@ -3680,7 +3696,7 @@ function registerDisplaysCommands(program, options = {}) {
3680
3696
  }
3681
3697
  writeLine(stdout, `Created widget on display "${display.value}".`);
3682
3698
  });
3683
- 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) {
3699
+ 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-option <field:option>", "lock only this option of an option field (repeatable; option name or id); its other options and leaving it empty stay allowed", collectLockOptions, []).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) {
3684
3700
  const { api, json, readOnly } = createDisplaysApi(this, filePath);
3685
3701
  ensureWritable("displays widgets update", readOnly, "write");
3686
3702
  const data = await api.updateWidget(display, widgetId, buildWidgetBody(commandOptions));
@@ -4836,6 +4852,13 @@ var RecordsApi = class {
4836
4852
  jsonOptions6(body, "POST")
4837
4853
  );
4838
4854
  }
4855
+ aggregateRecords(schema, input) {
4856
+ const body = Array.isArray(input.where) ? { ...input, where: input.where.map(toWhereNode) } : input;
4857
+ return this.client.requestJson(
4858
+ `/api/v2/schemas/${schema.value}/records:aggregate`,
4859
+ jsonOptions6(body, "POST")
4860
+ );
4861
+ }
4839
4862
  getRecord(schema, record) {
4840
4863
  return this.client.getJson(
4841
4864
  `/api/v2/schemas/${schema.value}/records/${record.value}`
@@ -4956,6 +4979,32 @@ var SchemasApi = class {
4956
4979
  };
4957
4980
 
4958
4981
  // src/commands/records.ts
4982
+ var AGGREGATE_BUCKETS = ["day", "week", "month", "quarter", "year"];
4983
+ var AGGREGATE_HELP = `
4984
+ Group by (--group-by <field>[:<bucket>], up to 3):
4985
+ A field slug; date fields take a bucket: day, week, month, quarter or year
4986
+ (a date field without bucket groups by day). Each group key comes back as
4987
+ {value, label}; records with an empty value fall into one group with
4988
+ value/label null. A reference key's value is the target record id: reuse
4989
+ it in --where "<field> eq <value>" to list the records of that group.
4990
+
4991
+ Metrics (--metric [<alias>=]<op>[:<field>], up to 10, default "count"):
4992
+ count number of records
4993
+ count:<field> records where <field> is not null (same rule as a
4994
+ panel COUNT; options skip -1)
4995
+ count_distinct:<field>, sum:<field>, avg:<field>, min:<field>, max:<field>
4996
+ The alias defaults to "count" for a bare count and to <op>_<field>
4997
+ otherwise (e.g. sum_amount). avg/min/max are null when no record has a
4998
+ value; min/max on dates return an ISO-8601 UTC instant.
4999
+
5000
+ Sort (--sort <alias|field>[:asc|desc], up to 4):
5001
+ By a metric alias or a group-by field. Default: group keys ascending.
5002
+
5003
+ --limit caps the groups returned (default 100, max 1000); meta.aggregate
5004
+ reports count, total and truncated. Date buckets use --timezone, or the
5005
+ workspace timezone when omitted. --where/--where-json/--search filter the
5006
+ records first, exactly as in "records query".
5007
+ `;
4959
5008
  function createRecordsApi(command, filePath) {
4960
5009
  const { client, ...runtime } = createCommandContext(command, filePath);
4961
5010
  return {
@@ -5065,6 +5114,72 @@ function collectSortValues(value, previous = []) {
5065
5114
  function collectWhereExpressions(value, previous = []) {
5066
5115
  return [...previous, parseExpressionValue(value)];
5067
5116
  }
5117
+ function splitKnownSuffix(input, suffixes) {
5118
+ const index = input.lastIndexOf(":");
5119
+ if (index !== -1) {
5120
+ const suffix = input.slice(index + 1).trim().toLowerCase();
5121
+ if (suffixes.includes(suffix)) {
5122
+ return { head: input.slice(0, index).trim(), suffix };
5123
+ }
5124
+ }
5125
+ return { head: input.trim() };
5126
+ }
5127
+ function parseGroupBy(input) {
5128
+ const { head, suffix } = splitKnownSuffix(input, AGGREGATE_BUCKETS);
5129
+ if (!head) {
5130
+ throw new CliError(
5131
+ "invalid_cli_usage",
5132
+ `Invalid --group-by "${input}": expected <field>[:<bucket>] with bucket one of ${AGGREGATE_BUCKETS.join(", ")}.`
5133
+ );
5134
+ }
5135
+ return suffix ? { field: head, bucket: suffix } : { field: head };
5136
+ }
5137
+ function parseMetric(input) {
5138
+ const usage = `Invalid --metric "${input}": expected [<alias>=]<op>[:<field>], e.g. "count", "total=sum:amount" or "count_distinct:customer".`;
5139
+ const aliasIndex = input.lastIndexOf("=");
5140
+ const alias = aliasIndex === -1 ? void 0 : input.slice(0, aliasIndex).trim();
5141
+ const expression = input.slice(aliasIndex + 1);
5142
+ const fieldIndex = expression.indexOf(":");
5143
+ const op = (fieldIndex === -1 ? expression : expression.slice(0, fieldIndex)).trim();
5144
+ const field = fieldIndex === -1 ? void 0 : expression.slice(fieldIndex + 1).trim();
5145
+ if (alias === "" || !/^[A-Za-z_]+$/.test(op) || field === "") {
5146
+ throw new CliError("invalid_cli_usage", usage);
5147
+ }
5148
+ return {
5149
+ op,
5150
+ ...field !== void 0 ? { field } : {},
5151
+ ...alias !== void 0 ? { as: alias } : {}
5152
+ };
5153
+ }
5154
+ function parseAggregateSort(input) {
5155
+ const { head, suffix } = splitKnownSuffix(input, ["asc", "desc"]);
5156
+ if (!head) {
5157
+ throw new CliError(
5158
+ "invalid_cli_usage",
5159
+ `Invalid --sort "${input}": expected <alias|field>[:asc|desc].`
5160
+ );
5161
+ }
5162
+ return { by: head, direction: (suffix ?? "asc").toUpperCase() };
5163
+ }
5164
+ function parseGroupLimit(input) {
5165
+ const limit = /^\d+$/.test(input.trim()) ? Number(input) : Number.NaN;
5166
+ if (!(limit >= 1 && limit <= 1e3)) {
5167
+ throw new CliError(
5168
+ "invalid_cli_usage",
5169
+ `Invalid --limit "${input}": expected a number of groups from 1 to 1000.`
5170
+ );
5171
+ }
5172
+ return limit;
5173
+ }
5174
+ function collectGroupBy(value, previous = []) {
5175
+ return [...previous, parseGroupBy(value)];
5176
+ }
5177
+ function collectMetrics(value, previous = []) {
5178
+ return [...previous, parseMetric(value)];
5179
+ }
5180
+ function collectAggregateSort(value, previous = []) {
5181
+ return [...previous, parseAggregateSort(value)];
5182
+ }
5068
5183
  function collectKeyValueAssignments(value, previous = []) {
5069
5184
  return [...previous, parseKeyValueAssignment(value)];
5070
5185
  }
@@ -5146,6 +5261,44 @@ function buildRecordQueryInput(options, allowRaw) {
5146
5261
  }
5147
5262
  return input;
5148
5263
  }
5264
+ function buildRecordAggregateInput(options) {
5265
+ const input = readRawObject(options.raw, options.rawFile);
5266
+ const where = resolveWhere(options);
5267
+ if (where !== void 0) {
5268
+ input.where = where;
5269
+ }
5270
+ if (options.search !== void 0) {
5271
+ input.search = { term: options.search };
5272
+ }
5273
+ if (options.groupBy && options.groupBy.length > 0) {
5274
+ input.groupBy = [...options.groupBy];
5275
+ }
5276
+ if (options.metric && options.metric.length > 0) {
5277
+ input.metrics = [...options.metric];
5278
+ }
5279
+ if (options.sort && options.sort.length > 0) {
5280
+ input.sort = [...options.sort];
5281
+ }
5282
+ if (options.limit !== void 0) {
5283
+ input.limit = options.limit;
5284
+ }
5285
+ if (options.timezone !== void 0) {
5286
+ input.timezone = options.timezone;
5287
+ }
5288
+ return input;
5289
+ }
5290
+ function toAggregateTableRows(groups) {
5291
+ return groups.map((group) => {
5292
+ const row = {};
5293
+ for (const [slug, key] of Object.entries(group.key ?? {})) {
5294
+ row[slug] = key?.label ? key.label : key?.value ?? "(empty)";
5295
+ }
5296
+ for (const [alias, value] of Object.entries(group.metrics ?? {})) {
5297
+ row[alias in row ? `${alias} (metric)` : alias] = value;
5298
+ }
5299
+ return row;
5300
+ });
5301
+ }
5149
5302
  function readRecordsFromFile(path) {
5150
5303
  let contents;
5151
5304
  try {
@@ -5317,6 +5470,58 @@ function registerRecordsCommands(program, options = {}) {
5317
5470
  }
5318
5471
  emitTable(stdout, recordsData);
5319
5472
  });
5473
+ records.command("aggregate").description(
5474
+ "Compute counts, sums, averages and min/max over a schema's records, optionally grouped by up to 3 fields (dates by day/week/month/quarter/year). Use it for totals and breakdowns instead of paginating records query and summing"
5475
+ ).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
5476
+ "--group-by <field[:bucket]>",
5477
+ "group by a field slug; date fields take a bucket day|week|month|quarter|year (repeatable, up to 3)",
5478
+ collectGroupBy,
5479
+ []
5480
+ ).option(
5481
+ "--metric <[alias=]op[:field]>",
5482
+ "metric count|count_distinct|sum|avg|min|max, e.g. count, total=sum:amount (repeatable, up to 10; default count)",
5483
+ collectMetrics,
5484
+ []
5485
+ ).option(
5486
+ "--where <expression>",
5487
+ 'condition "<field> <op> [value]" (repeatable, combined with AND)',
5488
+ collectWhereExpressions,
5489
+ []
5490
+ ).option(
5491
+ "--where-json <json>",
5492
+ 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
5493
+ ).option(
5494
+ "--search <term>",
5495
+ "free-text search term (matched across the schema's searchable fields)"
5496
+ ).option(
5497
+ "--sort <alias|field[:direction]>",
5498
+ "sort groups by a metric alias or group-by field, asc|desc (repeatable, up to 4)",
5499
+ collectAggregateSort,
5500
+ []
5501
+ ).option("--limit <number>", "maximum groups returned (default 100, max 1000)", parseGroupLimit).option("--timezone <iana>", "timezone for date buckets, e.g. Europe/Madrid (default: workspace timezone)").option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").addHelpText("after", AGGREGATE_HELP).action(async function action(schema, commandOptions) {
5502
+ const { api, schemasApi, json } = createRecordsApi(this, filePath);
5503
+ const input = buildRecordAggregateInput(commandOptions);
5504
+ const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5505
+ const data = await api.aggregateRecords(resolvedSchema, input);
5506
+ const groups = Array.isArray(data.groups) ? data.groups : [];
5507
+ if (json) {
5508
+ emitJson(
5509
+ stdout,
5510
+ "records aggregate",
5511
+ groups,
5512
+ filePath,
5513
+ data.meta ? { aggregate: data.meta } : {}
5514
+ );
5515
+ return;
5516
+ }
5517
+ emitTable(stdout, toAggregateTableRows(groups));
5518
+ if (data.meta?.truncated) {
5519
+ writeLine(
5520
+ stdout,
5521
+ `Showing ${data.meta.count} of ${data.meta.total} groups; raise --limit (max 1000) or narrow the filters to see the rest.`
5522
+ );
5523
+ }
5524
+ });
5320
5525
  records.command("get").description("Get a record by UUID or slug").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, record) {
5321
5526
  const { api, schemasApi, json } = createRecordsApi(this, filePath);
5322
5527
  const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);