zinkee 0.1.70 → 0.1.72

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
@@ -253,7 +253,7 @@ ${list}`
253
253
  };
254
254
  }
255
255
  async function showExamples(commandName, json, stdout, filters = {}) {
256
- const { getCommandExamples } = await import("./examples-MT6FVPAD.js");
256
+ const { getCommandExamples } = await import("./examples-FIA4FRWM.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}".`);
@@ -290,7 +290,7 @@ ${index + 1}. ${example.description}
290
290
 
291
291
  // src/program.ts
292
292
  import { createRequire } from "module";
293
- import { Command as Command4 } from "commander";
293
+ import { Command as Command5 } from "commander";
294
294
 
295
295
  // src/config.ts
296
296
  import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -4678,1371 +4678,1995 @@ function registerFilesCommands(program, options = {}) {
4678
4678
  });
4679
4679
  }
4680
4680
 
4681
- // src/api/formulas.ts
4682
- function toRequestBody(input) {
4683
- if (input.scope === "FIELD") {
4684
- return {
4685
- scope: input.scope,
4686
- schema: input.schema.value,
4687
- field: input.field.value
4688
- };
4689
- }
4690
- if (input.scope === "SCHEMA") {
4691
- return {
4692
- scope: input.scope,
4693
- schema: input.schema.value
4694
- };
4695
- }
4696
- return { scope: input.scope };
4681
+ // src/commands/forms.ts
4682
+ import { InvalidArgumentError as InvalidArgumentError4 } from "commander";
4683
+
4684
+ // src/api/forms.ts
4685
+ function jsonOptions7(body, method) {
4686
+ return {
4687
+ method,
4688
+ headers: { "content-type": "application/json" },
4689
+ body: JSON.stringify(body)
4690
+ };
4697
4691
  }
4698
- var FormulasApi = class {
4692
+ function formsPath(schemaId, formId, suffix = "") {
4693
+ const base = `/api/v2/schemas/${encodeURIComponent(schemaId)}/forms`;
4694
+ return formId === void 0 ? base : `${base}/${encodeURIComponent(formId)}${suffix}`;
4695
+ }
4696
+ var FormsApi = class {
4699
4697
  constructor(client) {
4700
4698
  this.client = client;
4701
4699
  }
4702
- recompute(input) {
4700
+ listForms(schemaId) {
4701
+ return this.client.getJson(formsPath(schemaId));
4702
+ }
4703
+ getForm(schemaId, formId) {
4704
+ return this.client.getJson(formsPath(schemaId, formId));
4705
+ }
4706
+ createForm(schemaId, input) {
4707
+ return this.client.requestJson(formsPath(schemaId), jsonOptions7(input, "POST"));
4708
+ }
4709
+ updateForm(schemaId, formId, input) {
4710
+ return this.client.requestJson(formsPath(schemaId, formId), jsonOptions7(input, "PATCH"));
4711
+ }
4712
+ deleteForm(schemaId, formId) {
4713
+ return this.client.requestJson(formsPath(schemaId, formId), {
4714
+ method: "DELETE"
4715
+ });
4716
+ }
4717
+ getLink(schemaId, formId) {
4718
+ return this.client.getJson(formsPath(schemaId, formId, "/link"));
4719
+ }
4720
+ setLink(schemaId, formId, input) {
4703
4721
  return this.client.requestJson(
4704
- "/api/v2/formulas:recompute",
4705
- {
4706
- method: "POST",
4707
- headers: {
4708
- "content-type": "application/json"
4709
- },
4710
- body: JSON.stringify(toRequestBody(input))
4711
- }
4722
+ formsPath(schemaId, formId, "/link"),
4723
+ jsonOptions7(input, "PUT")
4712
4724
  );
4713
4725
  }
4714
4726
  };
4715
4727
 
4716
- // src/commands/formulas.ts
4717
- function createFormulasApi(command, filePath) {
4728
+ // src/commands/schemas.ts
4729
+ import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
4730
+ var HIGHLIGHTED_FIELD_HELP = `
4731
+ Highlighted field:
4732
+ The schema's "main" field. The frontend uses its value as each record's
4733
+ display name, in two places:
4734
+ - Activity panel: the record's title in the activity side panel
4735
+ (the panel with the record's logs and comments).
4736
+ - Detail view: the record's name in the left-hand record list you
4737
+ browse to open each record's form.
4738
+ `;
4739
+ function createSchemasApi(command, filePath) {
4718
4740
  const { client, ...runtime } = createCommandContext(command, filePath);
4719
4741
  return {
4720
- api: new FormulasApi(client),
4742
+ api: new SchemasApi(client),
4721
4743
  ...runtime
4722
4744
  };
4723
4745
  }
4724
- function ensureConfirmed(commandName, confirmed) {
4725
- if (!confirmed) {
4726
- throw new CliError(
4727
- "invalid_cli_usage",
4728
- `Command "${commandName}" requires --yes because it may enqueue a large recalculation.`
4729
- );
4730
- }
4746
+ function collectFieldSelectors(value, previous = []) {
4747
+ return [...previous, parseUuidOrSlugSelector(value)];
4731
4748
  }
4732
- function emitResult(stdout, commandName, result, configPath, json) {
4733
- if (json) {
4734
- emitJson(stdout, commandName, result, configPath);
4735
- return;
4749
+ function parseBooleanFlag(input) {
4750
+ const normalized = input.trim().toLowerCase();
4751
+ if (["true", "1", "yes", "y", "on"].includes(normalized)) {
4752
+ return true;
4736
4753
  }
4737
- writeLine(
4738
- stdout,
4739
- `Queued ${result.eventsQueued} formula recalculation event(s) for ${result.scope.toLowerCase()} scope (request ${result.requestId}).`
4740
- );
4741
- }
4742
- async function recompute(command, commandName, input, options, requireConfirmation, confirmed) {
4743
- const configPath = options.configPath ?? defaultConfigPath;
4744
- const stdout = options.stdout ?? process.stdout;
4745
- const { api, json, readOnly } = createFormulasApi(command, configPath);
4746
- ensureWritable(commandName, readOnly, "write");
4747
- if (requireConfirmation) {
4748
- ensureConfirmed(commandName, confirmed);
4754
+ if (["false", "0", "no", "n", "off"].includes(normalized)) {
4755
+ return false;
4749
4756
  }
4750
- const result = await api.recompute(input);
4751
- emitResult(stdout, commandName, result, configPath, json);
4757
+ throw new InvalidArgumentError3(`Expected a boolean value, received "${input}".`);
4752
4758
  }
4753
- function registerFormulasCommands(program, options = {}) {
4754
- const formulas = program.command("formulas").description("Recalculate formula values");
4755
- const recomputeCommand = formulas.command("recompute").description("Queue a full formula recalculation");
4756
- recomputeCommand.command("field").description("Queue recalculation of one formula column").argument("<schema>", "schema UUID or slug", parseUuidOrSlugSelector).argument("<field>", "formula field UUID or slug", parseUuidOrSlugSelector).action(
4757
- async function action(schema, field) {
4758
- await recompute(
4759
- this,
4760
- "formulas recompute field",
4761
- { scope: "FIELD", schema, field },
4762
- options,
4763
- false
4764
- );
4765
- }
4759
+ function emitSchemasTable(stdout, schemas) {
4760
+ printTable(
4761
+ schemas.map((schema) => ({
4762
+ id: schema.id ?? "",
4763
+ name: schema.name ?? "",
4764
+ slug: schema.slug ?? "",
4765
+ auditable: schema.auditable ?? "",
4766
+ commentable: schema.commentable ?? "",
4767
+ ...folderColumns(schema.folder)
4768
+ })),
4769
+ ["id", "name", "slug", "auditable", "commentable", ...FOLDER_TABLE_KEYS],
4770
+ stdout
4766
4771
  );
4767
- recomputeCommand.command("schema").description("Queue recalculation of all active formulas in one schema").argument("<schema>", "schema UUID or slug", parseUuidOrSlugSelector).option("--yes", "confirm the potentially expensive recalculation").action(
4768
- async function action(schema, commandOptions) {
4769
- await recompute(
4770
- this,
4771
- "formulas recompute schema",
4772
- { scope: "SCHEMA", schema },
4773
- options,
4774
- true,
4775
- commandOptions.yes
4776
- );
4777
- }
4772
+ }
4773
+ function emitFieldsTable(stdout, fields) {
4774
+ printTable(
4775
+ fields.map((field) => ({
4776
+ id: field.id ?? "",
4777
+ type: field.type ?? "",
4778
+ slug: field.slug ?? "",
4779
+ label: field.label ?? "",
4780
+ required: field.required ?? ""
4781
+ })),
4782
+ ["id", "type", "slug", "label", "required"],
4783
+ stdout
4778
4784
  );
4779
- recomputeCommand.command("workspace").description("Queue recalculation of all active formulas in the workspace").option("--yes", "confirm the potentially expensive recalculation").action(async function action(commandOptions) {
4780
- await recompute(
4781
- this,
4782
- "formulas recompute workspace",
4783
- { scope: "WORKSPACE" },
4784
- options,
4785
- true,
4786
- commandOptions.yes
4787
- );
4788
- });
4789
4785
  }
4790
-
4791
- // src/api/logs.ts
4792
- var LogsApi = class {
4793
- constructor(client) {
4794
- this.client = client;
4786
+ function buildSchemaUpdateInput(options) {
4787
+ const input = {};
4788
+ if (options.name !== void 0) {
4789
+ input.name = options.name;
4795
4790
  }
4796
- listLogs(schema, recordId) {
4797
- return this.client.getJson(
4798
- `/api/v2/schemas/${schema.value}/records/${recordId}/logs`
4791
+ if (options.slug !== void 0) {
4792
+ input.slug = options.slug;
4793
+ }
4794
+ if (options.auditable !== void 0) {
4795
+ input.auditable = options.auditable;
4796
+ }
4797
+ if (options.commentable !== void 0) {
4798
+ input.commentable = options.commentable;
4799
+ }
4800
+ return input;
4801
+ }
4802
+ function applyFieldDefaultValue(input, defaultValue) {
4803
+ if (defaultValue === void 0) {
4804
+ return;
4805
+ }
4806
+ const config = input.config;
4807
+ if (config !== void 0 && !isJsonObject(config)) {
4808
+ throw new CliError(
4809
+ "invalid_cli_usage",
4810
+ 'Expected field "config" to be a JSON object when using "--default".'
4799
4811
  );
4800
4812
  }
4801
- };
4802
-
4803
- // src/commands/logs.ts
4804
- function createLogsApi(command, filePath) {
4805
- const { client, ...runtime } = createCommandContext(command, filePath);
4806
- return {
4807
- api: new LogsApi(client),
4808
- ...runtime
4813
+ input.config = {
4814
+ ...config ?? {},
4815
+ defaultValue
4809
4816
  };
4810
4817
  }
4811
- function registerLogsCommands(program, options = {}) {
4812
- const filePath = options.configPath ?? defaultConfigPath;
4813
- const stdout = options.stdout ?? process.stdout;
4814
- const logs = program.command("logs").description("Inspect record change logs");
4815
- logs.command("list").description("List change logs for a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, record) {
4816
- const { api, json } = createLogsApi(this, filePath);
4817
- const data = await api.listLogs(schema, record.value);
4818
- if (json) {
4819
- emitJson(stdout, "logs list", data);
4820
- return;
4821
- }
4822
- emitTable(stdout, data);
4823
- });
4824
- }
4825
-
4826
- // src/api/members.ts
4827
- var MembersApi = class {
4828
- constructor(client) {
4829
- this.client = client;
4818
+ function buildFieldCreateInput(options) {
4819
+ const raw = normalizeSchemaFieldCreatePayload(readRawObject(options.raw, options.rawFile));
4820
+ const rawType = typeof raw.type === "string" ? raw.type : void 0;
4821
+ const rawSlug = typeof raw.slug === "string" ? raw.slug : void 0;
4822
+ const rawLabel = typeof raw.label === "string" ? raw.label : void 0;
4823
+ const type = options.type ?? rawType;
4824
+ const slug = options.slug ?? rawSlug;
4825
+ const label = options.label ?? rawLabel;
4826
+ if (!type) {
4827
+ throw new CliError("invalid_cli_usage", 'Provide field type via "--type" or "--raw".');
4830
4828
  }
4831
- listMembers() {
4832
- return this.client.getJson("/api/v2/members");
4829
+ if (!slug) {
4830
+ throw new CliError("invalid_cli_usage", 'Provide field slug via "--slug" or "--raw".');
4833
4831
  }
4834
- };
4835
-
4836
- // src/commands/members.ts
4837
- function createMembersApi(command, filePath) {
4838
- const { client, ...runtime } = createCommandContext(command, filePath);
4839
- return {
4840
- api: new MembersApi(client),
4841
- ...runtime
4832
+ if (!label) {
4833
+ throw new CliError("invalid_cli_usage", 'Provide field label via "--label" or "--raw".');
4834
+ }
4835
+ const normalizedType = normalizeSchemaFieldType(type);
4836
+ assertSupportedSchemaFieldType(normalizedType);
4837
+ const input = {
4838
+ ...raw,
4839
+ type: normalizedType,
4840
+ slug,
4841
+ label
4842
4842
  };
4843
+ if (options.required !== void 0) {
4844
+ input.required = options.required;
4845
+ }
4846
+ if (options.description !== void 0) {
4847
+ input.description = options.description;
4848
+ }
4849
+ applyFieldDefaultValue(input, options.default);
4850
+ if ("config" in input && isJsonObject(input.config) && isEmptyObject(input.config)) {
4851
+ delete input.config;
4852
+ }
4853
+ return input;
4843
4854
  }
4844
- function registerMembersCommands(program, options = {}) {
4845
- const filePath = options.configPath ?? defaultConfigPath;
4846
- const stdout = options.stdout ?? process.stdout;
4847
- const members = program.command("members").description("Inspect workspace members");
4848
- members.command("list").description(
4849
- "List the active members of the workspace (email to write in member fields, alias, currentUser)"
4850
- ).action(async function action() {
4851
- const { api, json } = createMembersApi(this, filePath);
4852
- const data = await api.listMembers();
4853
- if (json) {
4854
- emitJson(stdout, "members list", data);
4855
- return;
4856
- }
4857
- emitTable(stdout, data);
4858
- });
4859
- }
4860
-
4861
- // src/commands/navigation.ts
4862
- import { readFileSync as readFileSync4 } from "fs";
4863
-
4864
- // src/api/navigation.ts
4865
- function jsonOptions7(body, method) {
4866
- return {
4867
- method,
4868
- headers: {
4869
- "content-type": "application/json"
4870
- },
4871
- body: JSON.stringify(body)
4872
- };
4873
- }
4874
- var NavigationApi = class {
4875
- constructor(client) {
4876
- this.client = client;
4877
- }
4878
- listFolders() {
4879
- return this.client.getJson("/api/v2/navigation/folders");
4880
- }
4881
- createFolder(body) {
4882
- return this.client.requestJson(
4883
- "/api/v2/navigation/folders",
4884
- jsonOptions7(body, "POST")
4885
- );
4886
- }
4887
- updateFolder(folder, body) {
4888
- return this.client.requestJson(
4889
- `/api/v2/navigation/folders/${folder.value}`,
4890
- jsonOptions7(body, "PATCH")
4891
- );
4892
- }
4893
- deleteFolder(folder) {
4894
- return this.client.requestJson(
4895
- `/api/v2/navigation/folders/${folder.value}`,
4896
- { method: "DELETE" }
4897
- );
4898
- }
4899
- moveResource(body) {
4900
- return this.client.requestJson(
4901
- "/api/v2/navigation/resources:move",
4902
- jsonOptions7(body, "POST")
4903
- );
4904
- }
4905
- };
4906
-
4907
- // src/commands/navigation.ts
4908
- function createNavigationApi(command, filePath) {
4909
- const { client, ...runtime } = createCommandContext(command, filePath);
4910
- return {
4911
- api: new NavigationApi(client),
4912
- ...runtime
4913
- };
4855
+ function readBackendErrorMessage(error) {
4856
+ const responseBody = typeof error.responseBody === "object" && error.responseBody !== null ? error.responseBody : void 0;
4857
+ const envelopeError = responseBody && "error" in responseBody && typeof responseBody.error === "object" && responseBody.error !== null ? responseBody.error : responseBody;
4858
+ return (envelopeError && "message" in envelopeError && typeof envelopeError.message === "string" ? envelopeError.message : void 0) ?? (typeof error.responseText === "string" && error.responseText.length > 0 ? error.responseText : void 0);
4914
4859
  }
4915
- function parseInteger(value, flagName) {
4916
- if (value === void 0) {
4917
- return void 0;
4860
+ function toFieldCreateError(error, input) {
4861
+ if (!(error instanceof ApiClientError)) {
4862
+ throw error;
4918
4863
  }
4919
- const parsed = Number.parseInt(value, 10);
4920
- if (Number.isNaN(parsed)) {
4921
- throw new CliError("invalid_cli_usage", `${flagName} must be an integer.`);
4864
+ const backendMessage = readBackendErrorMessage(error);
4865
+ const isGenericValidationMessage = backendMessage === "Schema payload is invalid. One or more fields are invalid." || backendMessage === "Create field payload is invalid.";
4866
+ if (!isGenericValidationMessage) {
4867
+ throw error;
4922
4868
  }
4923
- return parsed;
4869
+ throw new CliError(
4870
+ "invalid_cli_usage",
4871
+ buildSchemaFieldCreateValidationMessage(input.type),
4872
+ {
4873
+ fieldType: input.type,
4874
+ status: error.status
4875
+ }
4876
+ );
4924
4877
  }
4925
- function readJsonObject(raw, rawFile) {
4926
- if (raw && rawFile) {
4927
- throw new CliError("invalid_cli_usage", 'Use either "--props" or "--props-file", not both.');
4878
+ function buildFieldUpdateInput(currentType, options) {
4879
+ const input = {
4880
+ ...normalizeSchemaFieldUpdatePayload(
4881
+ currentType,
4882
+ readRawObject(options.raw, options.rawFile)
4883
+ ),
4884
+ type: currentType
4885
+ };
4886
+ if (options.label !== void 0) {
4887
+ input.label = options.label;
4928
4888
  }
4929
- const source = rawFile ? readFileSync4(rawFile, "utf8") : raw;
4930
- if (!source) {
4931
- return {};
4889
+ if (options.required !== void 0) {
4890
+ input.required = options.required;
4932
4891
  }
4933
- try {
4934
- const parsed = JSON.parse(source);
4935
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
4936
- throw new CliError("invalid_cli_usage", "Props payload must be a JSON object.");
4937
- }
4938
- return parsed;
4939
- } catch (error) {
4940
- if (error instanceof CliError) {
4941
- throw error;
4942
- }
4943
- throw new CliError("invalid_cli_usage", "Props payload is invalid JSON.");
4892
+ if (options.description !== void 0) {
4893
+ input.description = options.description;
4944
4894
  }
4895
+ applyFieldDefaultValue(input, options.default);
4896
+ return input;
4945
4897
  }
4946
- function buildFolderBody(options) {
4947
- const body = {};
4948
- if (options.name !== void 0) {
4949
- body.name = options.name;
4950
- }
4951
- const order = parseInteger(options.order, "--order");
4952
- if (order !== void 0) {
4953
- body.order = order;
4898
+ async function resolveSchemaSelector(api, selector) {
4899
+ if (selector.kind === "uuid") {
4900
+ return selector;
4954
4901
  }
4955
- const props = readJsonObject(options.props, options.propsFile);
4956
- if (Object.keys(props).length > 0) {
4957
- body.additionalProperties = props;
4902
+ const schemas = await api.listSchemas();
4903
+ const match = schemas.find((schema) => schema.slug === selector.value);
4904
+ if (!match || typeof match.id !== "string") {
4905
+ throw new CliError("invalid_cli_usage", `Schema "${selector.value}" not found.`);
4958
4906
  }
4959
- return body;
4907
+ return {
4908
+ kind: "uuid",
4909
+ value: match.id
4910
+ };
4960
4911
  }
4961
- function resolveFolder2(folders, selector) {
4912
+ async function resolveFieldSelector(api, schema, selector) {
4962
4913
  if (selector.kind === "uuid") {
4963
- const match = folders.find((folder) => folder.id === selector.value);
4964
- if (!match) {
4965
- throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
4966
- }
4967
- return match;
4968
- }
4969
- const matches = folders.filter((folder) => folder.name === selector.value);
4970
- if (matches.length === 1) {
4971
- return matches[0];
4914
+ return selector;
4972
4915
  }
4973
- if (matches.length > 1) {
4974
- throw new CliError(
4975
- "invalid_cli_usage",
4976
- `Folder "${selector.value}" is ambiguous. Found ${matches.length} matches.`
4977
- );
4916
+ const fields = await api.listFields(schema);
4917
+ const match = fields.find((field) => field.slug === selector.value);
4918
+ if (!match || typeof match.id !== "string") {
4919
+ throw new CliError("invalid_cli_usage", `Field "${selector.value}" not found.`);
4978
4920
  }
4979
- throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
4980
- }
4981
- function folderRows2(folders) {
4982
- return folders.map((folder) => ({
4983
- id: folder.id,
4984
- order: folder.order ?? "",
4985
- name: folder.name ?? "",
4986
- resourceCount: Array.isArray(folder.resources) ? folder.resources.length : ""
4987
- }));
4921
+ return {
4922
+ kind: "uuid",
4923
+ value: match.id
4924
+ };
4988
4925
  }
4989
- function registerNavigationCommands(program, options = {}) {
4926
+ function registerSchemasCommands(program, options = {}) {
4990
4927
  const filePath = options.configPath ?? defaultConfigPath;
4991
4928
  const stdout = options.stdout ?? process.stdout;
4992
- const navigation = program.command("navigation").description("Manage workspace navigation");
4993
- const folders = navigation.command("folders").description("Manage navigation folders");
4994
- folders.command("list").description("List navigation folders").action(async function action() {
4995
- const { api, json } = createNavigationApi(this, filePath);
4996
- const data = await api.listFolders();
4929
+ const schemas = program.command("schemas").description("Manage schemas and schema fields");
4930
+ schemas.command("list").description("List schemas").action(async function action() {
4931
+ const { api, json } = createSchemasApi(this, filePath);
4932
+ const data = await api.listSchemas();
4997
4933
  if (json) {
4998
- emitJson(stdout, "navigation folders list", data, filePath);
4934
+ emitJson(stdout, "schemas list", data, filePath);
4999
4935
  return;
5000
4936
  }
5001
- printTable(folderRows2(data), ["id", "order", "name", "resourceCount"], stdout);
4937
+ emitSchemasTable(stdout, data);
5002
4938
  });
5003
- folders.command("get").description("Get a navigation folder by UUID or exact name").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector).action(async function action(folder) {
5004
- const { api, json } = createNavigationApi(this, filePath);
5005
- const data = await api.listFolders();
5006
- const resolved = resolveFolder2(data, folder);
4939
+ schemas.command("get").description("Get a schema by UUID or slug").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
4940
+ const { api, json } = createSchemasApi(this, filePath);
4941
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
4942
+ const data = await api.getSchema(resolvedSchema);
5007
4943
  if (json) {
5008
- emitJson(stdout, "navigation folders get", resolved, filePath);
4944
+ emitJson(stdout, "schemas get", data, filePath);
5009
4945
  return;
5010
4946
  }
5011
- printTable(folderRows2([resolved]), ["id", "order", "name", "resourceCount"], stdout);
4947
+ emitSchemasTable(stdout, [data]);
5012
4948
  });
5013
- folders.command("create").description("Create a navigation folder").requiredOption("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(commandOptions) {
5014
- const { api, json, readOnly } = createNavigationApi(this, filePath);
5015
- ensureWritable("navigation folders create", readOnly, "write");
5016
- const data = await api.createFolder(buildFolderBody(commandOptions));
4949
+ schemas.command("create").description("Create a schema").requiredOption("--name <name>", "schema name").requiredOption("--slug <slug>", "schema slug").option("--auditable", "mark schema as auditable").option("--commentable", "mark schema as commentable").action(async function action(commandOptions) {
4950
+ const { api, json, readOnly } = createSchemasApi(this, filePath);
4951
+ ensureWritable("schemas create", readOnly, "write");
4952
+ const input = {
4953
+ name: commandOptions.name,
4954
+ slug: commandOptions.slug,
4955
+ auditable: Boolean(commandOptions.auditable),
4956
+ commentable: Boolean(commandOptions.commentable)
4957
+ };
4958
+ const data = await api.createSchema(input);
5017
4959
  if (json) {
5018
- emitJson(stdout, "navigation folders create", data, filePath);
4960
+ emitJson(stdout, "schemas create", data, filePath);
5019
4961
  return;
5020
4962
  }
5021
- writeLine(stdout, `Created navigation folder "${String(data.name ?? commandOptions.name)}".`);
4963
+ writeLine(stdout, `Created schema "${data.slug ?? commandOptions.slug}".`);
5022
4964
  });
5023
- folders.command("update").description("Update a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector).option("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(folder, commandOptions) {
5024
- const { api, json, readOnly } = createNavigationApi(this, filePath);
5025
- ensureWritable("navigation folders update", readOnly, "write");
5026
- const allFolders = await api.listFolders();
5027
- const resolved = resolveFolder2(allFolders, folder);
5028
- const body = buildFolderBody(commandOptions);
5029
- if (Object.keys(body).length === 0) {
5030
- throw new CliError("invalid_cli_usage", "Nothing to update.");
4965
+ schemas.command("update").description("Update a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--name <name>", "schema name").option("--slug <slug>", "schema slug").option("--auditable <bool>", "auditable flag", parseBooleanFlag).option("--commentable <bool>", "commentable flag", parseBooleanFlag).option(
4966
+ "--highlighted-field <field>",
4967
+ "its value is used as each record's display name in the UI (field uuid or slug)",
4968
+ parseUuidOrSlugSelector
4969
+ ).action(async function action(schema, commandOptions) {
4970
+ const { api, json, readOnly } = createSchemasApi(this, filePath);
4971
+ ensureWritable("schemas update", readOnly, "write");
4972
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
4973
+ const input = buildSchemaUpdateInput(commandOptions);
4974
+ if (commandOptions.highlightedField !== void 0) {
4975
+ const resolvedField = await resolveFieldSelector(
4976
+ api,
4977
+ resolvedSchema,
4978
+ commandOptions.highlightedField
4979
+ );
4980
+ input.highlightedField = resolvedField.value;
5031
4981
  }
5032
- const data = await api.updateFolder({ kind: "uuid", value: resolved.id }, body);
5033
- if (json) {
5034
- emitJson(stdout, "navigation folders update", data, filePath);
5035
- return;
4982
+ if (isEmptyObject(input)) {
4983
+ throw new CliError(
4984
+ "invalid_cli_usage",
4985
+ 'Provide at least one schema field to update via "--name", "--slug", "--auditable", "--commentable", or "--highlighted-field".'
4986
+ );
5036
4987
  }
5037
- writeLine(stdout, `Updated navigation folder "${String(data.name ?? resolved.name ?? resolved.id)}".`);
5038
- });
5039
- folders.command("delete").description("Delete a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector).action(async function action(folder) {
5040
- const { api, json, readOnly } = createNavigationApi(this, filePath);
5041
- ensureWritable("navigation folders delete", readOnly, "destructive");
5042
- const allFolders = await api.listFolders();
5043
- const resolved = resolveFolder2(allFolders, folder);
5044
- const data = await api.deleteFolder({ kind: "uuid", value: resolved.id });
4988
+ const data = await api.updateSchema(resolvedSchema, input);
5045
4989
  if (json) {
5046
- emitJson(stdout, "navigation folders delete", data, filePath);
4990
+ emitJson(stdout, "schemas update", data, filePath);
5047
4991
  return;
5048
4992
  }
5049
- writeLine(stdout, `Deleted navigation folder "${resolved.name ?? resolved.id}".`);
5050
- });
5051
- navigation.command("resources").description("Manage navigation resources").command("move").description(
5052
- "Move a schema into a navigation folder. Only schemas can be moved (the navigation menu holds databases); schedules and sub-schemas follow their parent schema. Use `--to root` to move it back to the workspace root: the root folder is named `root`, and its UUID differs per workspace."
5053
- ).argument("<resource>", "schema UUID").requiredOption("--to <folder>", "target folder UUID or exact name").action(async function action(resourceId, commandOptions) {
5054
- const { api, json, readOnly } = createNavigationApi(this, filePath);
5055
- ensureWritable("navigation resources move", readOnly, "write");
5056
- const allFolders = await api.listFolders();
5057
- const resolved = resolveFolder2(allFolders, parseUuidOrSlugSelector(commandOptions.to));
5058
- const data = await api.moveResource({
5059
- resourceId,
5060
- targetFolderId: resolved.id
5061
- });
4993
+ writeLine(stdout, `Updated schema "${data.slug ?? schema.value}".`);
4994
+ }).addHelpText("after", HIGHLIGHTED_FIELD_HELP);
4995
+ schemas.command("set-unique-fields").description("Set or clear the composite unique-field constraint on a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
4996
+ "--field <field>",
4997
+ "field uuid or slug to include in the unique constraint (repeatable)",
4998
+ collectFieldSelectors,
4999
+ []
5000
+ ).option("--clear", "clear the unique constraint (sends an empty field list)").action(async function action(schema, commandOptions) {
5001
+ const { api, json, readOnly } = createSchemasApi(this, filePath);
5002
+ ensureWritable("schemas set-unique-fields", readOnly, "write");
5003
+ const selectors = commandOptions.field ?? [];
5004
+ if (commandOptions.clear && selectors.length > 0) {
5005
+ throw new CliError(
5006
+ "invalid_cli_usage",
5007
+ 'Use either "--field" or "--clear", not both.'
5008
+ );
5009
+ }
5010
+ if (!commandOptions.clear && selectors.length === 0) {
5011
+ throw new CliError(
5012
+ "invalid_cli_usage",
5013
+ 'Provide at least one field via "--field", or pass "--clear" to remove the unique constraint.'
5014
+ );
5015
+ }
5016
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
5017
+ const fields2 = selectors.some((selector) => selector.kind === "slug") ? await api.listFields(resolvedSchema) : [];
5018
+ const input = {
5019
+ fieldIds: selectors.map((selector) => {
5020
+ if (selector.kind === "uuid") {
5021
+ return selector.value;
5022
+ }
5023
+ const match = fields2.find((field) => field.slug === selector.value);
5024
+ if (!match || typeof match.id !== "string") {
5025
+ throw new CliError("invalid_cli_usage", `Field "${selector.value}" not found.`);
5026
+ }
5027
+ return match.id;
5028
+ })
5029
+ };
5030
+ const data = await api.setUniqueFields(resolvedSchema, input);
5062
5031
  if (json) {
5063
- emitJson(stdout, "navigation resources move", data, filePath);
5032
+ emitJson(stdout, "schemas set-unique-fields", data, filePath);
5064
5033
  return;
5065
5034
  }
5066
- writeLine(stdout, `Moved resource "${resourceId}" to "${resolved.name ?? resolved.id}".`);
5067
- });
5068
- }
5069
-
5070
- // src/commands/profiles.ts
5071
- function readRequiredConfig(filePath) {
5072
- const config = readConfigIfExists(filePath);
5073
- if (config) {
5074
- return config;
5075
- }
5076
- throw new CliError("configuration_error", `Config file not found at ${filePath}.`);
5077
- }
5078
- function getRequiredProfile(config, profileName) {
5079
- const profile = config.profiles[profileName];
5080
- if (profile) {
5081
- return profile;
5082
- }
5083
- throw new CliError("configuration_error", `Profile "${profileName}" not found in config.`);
5084
- }
5085
- function toDisplayProfile(profileName, profile, defaultProfile) {
5086
- return {
5087
- name: profileName,
5088
- isDefault: defaultProfile === profileName,
5089
- ...redactProfile(profile)
5090
- };
5091
- }
5092
- function loadConfigForAdd(filePath) {
5093
- return readConfigIfExists(filePath) ?? { profiles: {} };
5094
- }
5095
- function normalizeProfileBaseUrl(baseUrl) {
5096
- if (baseUrl === void 0) {
5097
- return void 0;
5098
- }
5099
- try {
5100
- return validateBaseUrl(baseUrl, '"--base-url"');
5101
- } catch (error) {
5102
- if (error instanceof ProfileResolutionError) {
5103
- throw new CliError("configuration_error", error.message);
5035
+ if (input.fieldIds.length === 0) {
5036
+ writeLine(stdout, `Cleared unique fields on schema "${schema.value}".`);
5037
+ return;
5104
5038
  }
5105
- throw error;
5106
- }
5107
- }
5108
- function emitProfilesTable(stdout, data) {
5109
- printTable(
5110
- data.map((profile) => ({
5111
- name: profile.name,
5112
- default: profile.isDefault ? "yes" : "",
5113
- baseUrl: profile.baseUrl ?? "",
5114
- credential: describeProfileCredential(profile)
5115
- })),
5116
- ["name", "default", "baseUrl", "credential"],
5117
- stdout
5118
- );
5119
- }
5120
- function registerProfilesCommands(program, options = {}) {
5121
- const filePath = options.configPath ?? defaultConfigPath;
5122
- const stdout = options.stdout ?? process.stdout;
5123
- const profiles = program.command("profiles").description("Manage local CLI profiles");
5124
- profiles.command("list").description("List configured profiles").action(function action() {
5125
- const config = readRequiredConfig(filePath);
5126
- const data = Object.entries(config.profiles).map(
5127
- ([name, profile]) => toDisplayProfile(name, profile, config.defaultProfile)
5039
+ const count = input.fieldIds.length;
5040
+ writeLine(
5041
+ stdout,
5042
+ `Set unique fields on schema "${schema.value}" (${count} field${count === 1 ? "" : "s"}).`
5128
5043
  );
5129
- if (this.optsWithGlobals().json) {
5130
- emitJson(stdout, "profiles list", data, filePath);
5044
+ });
5045
+ schemas.command("delete").description("Delete a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
5046
+ const { api, json, readOnly } = createSchemasApi(this, filePath);
5047
+ ensureWritable("schemas delete", readOnly, "destructive");
5048
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
5049
+ await api.deleteSchema(resolvedSchema);
5050
+ const data = {
5051
+ schema: resolvedSchema.value,
5052
+ deleted: true
5053
+ };
5054
+ if (json) {
5055
+ emitJson(stdout, "schemas delete", data, filePath);
5131
5056
  return;
5132
5057
  }
5133
- emitProfilesTable(stdout, data);
5058
+ writeLine(stdout, `Deleted schema "${schema.value}".`);
5134
5059
  });
5135
- profiles.command("get").description("Show a single configured profile").argument("<profile>", "profile name").action(function action(profileName) {
5136
- const config = readRequiredConfig(filePath);
5137
- const profile = getRequiredProfile(config, profileName);
5138
- const data = toDisplayProfile(profileName, profile, config.defaultProfile);
5139
- if (this.optsWithGlobals().json) {
5140
- emitJson(stdout, "profiles get", data, filePath);
5060
+ const fields = schemas.command("fields").description("Manage schema fields");
5061
+ fields.command("list").description("List fields for a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
5062
+ const { api, json } = createSchemasApi(this, filePath);
5063
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
5064
+ const data = await api.listFields(resolvedSchema);
5065
+ if (json) {
5066
+ emitJson(stdout, "schemas fields list", data, filePath);
5141
5067
  return;
5142
5068
  }
5143
- emitProfilesTable(stdout, [data]);
5069
+ emitFieldsTable(stdout, data);
5144
5070
  });
5145
- profiles.command("use").description("Set the default profile").argument("<profile>", "profile name").action(function action(profileName) {
5146
- const config = readRequiredConfig(filePath);
5147
- getRequiredProfile(config, profileName);
5148
- const nextConfig = setDefaultProfile(config, profileName);
5149
- writeConfig(nextConfig, filePath);
5150
- const data = {
5151
- profile: profileName,
5152
- defaultProfile: nextConfig.defaultProfile
5153
- };
5154
- if (this.optsWithGlobals().json) {
5155
- emitJson(stdout, "profiles use", data, filePath);
5071
+ fields.command("get").description("Get a field by UUID or slug").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, field) {
5072
+ const { api, json } = createSchemasApi(this, filePath);
5073
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
5074
+ const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
5075
+ const data = await api.getField(resolvedSchema, resolvedField);
5076
+ if (json) {
5077
+ emitJson(stdout, "schemas fields get", data, filePath);
5156
5078
  return;
5157
5079
  }
5158
- writeLine(stdout, `Using profile "${profileName}".`);
5080
+ emitFieldsTable(stdout, [data]);
5159
5081
  });
5160
- profiles.command("add").description("Add a profile to the local config").argument("<profile>", "profile name").requiredOption("--api-key <token>", "API key").option("--base-url <url>", "base URL").action(function action(profileName, commandOptions) {
5161
- const config = loadConfigForAdd(filePath);
5162
- if (config.profiles[profileName]) {
5163
- throw new CliError(
5164
- "configuration_error",
5165
- `Profile "${profileName}" already exists in config.`
5166
- );
5167
- }
5168
- const baseUrl = normalizeProfileBaseUrl(commandOptions.baseUrl);
5169
- let nextConfig = setProfileConfig(config, profileName, {
5170
- apiKey: commandOptions.apiKey,
5171
- baseUrl
5172
- });
5173
- if (!nextConfig.defaultProfile) {
5174
- nextConfig = setDefaultProfile(nextConfig, profileName);
5082
+ fields.command("create").description(`Create a field in a schema.${buildSchemaFieldCreateHelpText()}`).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--type <type>", `field type (${formatSchemaFieldTypes()})`).option("--slug <slug>", "field slug").option("--label <label>", "field label").option("--description <text>", "field description").option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload (see type-specific shapes in --help)").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, commandOptions) {
5083
+ const { api, json, readOnly } = createSchemasApi(this, filePath);
5084
+ ensureWritable("schemas fields create", readOnly, "write");
5085
+ const input = buildFieldCreateInput(commandOptions);
5086
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
5087
+ let data;
5088
+ try {
5089
+ data = await api.createField(resolvedSchema, input);
5090
+ } catch (error) {
5091
+ toFieldCreateError(error, input);
5175
5092
  }
5176
- writeConfig(nextConfig, filePath);
5177
- const data = toDisplayProfile(
5178
- profileName,
5179
- nextConfig.profiles[profileName] ?? {},
5180
- nextConfig.defaultProfile
5181
- );
5182
- if (this.optsWithGlobals().json) {
5183
- emitJson(stdout, "profiles add", data, filePath);
5093
+ if (json) {
5094
+ emitJson(stdout, "schemas fields create", data, filePath);
5184
5095
  return;
5185
5096
  }
5186
- writeLine(stdout, `Added profile "${profileName}".`);
5097
+ writeLine(stdout, `Created field "${data.slug ?? commandOptions.slug}".`);
5187
5098
  });
5188
- profiles.command("update").description("Update an existing profile").argument("<profile>", "profile name").option("--api-key <token>", "API key").option("--base-url <url>", "base URL").action(function action(profileName, commandOptions) {
5189
- if (commandOptions.apiKey === void 0 && commandOptions.baseUrl === void 0) {
5190
- throw new CliError(
5191
- "configuration_error",
5192
- 'Provide at least one of "--api-key" or "--base-url".'
5193
- );
5099
+ fields.command("update").description("Update a field in a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector).option("--label <label>", "field label").option("--description <text>", 'field description (use "" to clear)').option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, field, commandOptions) {
5100
+ const { api, json, readOnly } = createSchemasApi(this, filePath);
5101
+ ensureWritable("schemas fields update", readOnly, "write");
5102
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
5103
+ const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
5104
+ const currentField = await api.getField(resolvedSchema, resolvedField);
5105
+ const currentType = typeof currentField.type === "string" && currentField.type.length > 0 ? currentField.type : void 0;
5106
+ if (!currentType) {
5107
+ throw new CliError("invalid_cli_usage", `Field "${field.value}" is missing type metadata.`);
5194
5108
  }
5195
- const config = readRequiredConfig(filePath);
5196
- const profile = getRequiredProfile(config, profileName);
5197
- if (isSessionProfile(profile)) {
5109
+ const input = buildFieldUpdateInput(currentType, commandOptions);
5110
+ if (isEmptyObject(input)) {
5198
5111
  throw new CliError(
5199
- "configuration_error",
5200
- `Profile "${profileName}" is a session profile. Run \`zinkee login --profile ${profileName}\` to renew its session, adding --backend-url and --base-url to change its environment.`
5112
+ "invalid_cli_usage",
5113
+ 'Provide at least one field update via "--label", "--description", "--required", "--default", "--raw", or "--raw-file".'
5201
5114
  );
5202
5115
  }
5203
- const baseUrl = normalizeProfileBaseUrl(commandOptions.baseUrl);
5204
- const nextConfig = setProfileConfig(config, profileName, {
5205
- apiKey: commandOptions.apiKey,
5206
- baseUrl
5207
- });
5208
- writeConfig(nextConfig, filePath);
5209
- const data = toDisplayProfile(
5210
- profileName,
5211
- nextConfig.profiles[profileName] ?? {},
5212
- nextConfig.defaultProfile
5213
- );
5214
- if (this.optsWithGlobals().json) {
5215
- emitJson(stdout, "profiles update", data, filePath);
5116
+ const data = await api.updateField(resolvedSchema, resolvedField, input);
5117
+ if (json) {
5118
+ emitJson(stdout, "schemas fields update", data, filePath);
5216
5119
  return;
5217
5120
  }
5218
- writeLine(stdout, `Updated profile "${profileName}".`);
5121
+ writeLine(stdout, `Updated field "${data.slug ?? field.value}".`);
5219
5122
  });
5220
- profiles.command("remove").description("Remove a profile from the local config").argument("<profile>", "profile name").action(function action(profileName) {
5221
- const config = readRequiredConfig(filePath);
5222
- getRequiredProfile(config, profileName);
5223
- const nextConfig = removeProfileConfig(config, profileName);
5224
- writeConfig(nextConfig, filePath);
5123
+ fields.command("delete").description("Delete a field from a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, field) {
5124
+ const { api, json, readOnly } = createSchemasApi(this, filePath);
5125
+ ensureWritable("schemas fields delete", readOnly, "destructive");
5126
+ const resolvedSchema = await resolveSchemaSelector(api, schema);
5127
+ const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
5128
+ await api.deleteField(resolvedSchema, resolvedField);
5225
5129
  const data = {
5226
- profile: profileName,
5227
- defaultProfile: nextConfig.defaultProfile
5130
+ schema: resolvedSchema.value,
5131
+ field: resolvedField.value,
5132
+ deleted: true
5228
5133
  };
5229
- if (this.optsWithGlobals().json) {
5230
- emitJson(stdout, "profiles remove", data, filePath);
5134
+ if (json) {
5135
+ emitJson(stdout, "schemas fields delete", data, filePath);
5231
5136
  return;
5232
5137
  }
5233
- writeLine(stdout, `Removed profile "${profileName}".`);
5138
+ writeLine(stdout, `Deleted field "${field.value}" from schema "${schema.value}".`);
5234
5139
  });
5235
5140
  }
5236
5141
 
5237
- // src/commands/records.ts
5238
- import { readFileSync as readFileSync5 } from "fs";
5239
- import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
5240
- var AGGREGATE_BUCKETS = ["day", "week", "month", "quarter", "year"];
5241
- var AGGREGATE_HELP = `
5242
- Group by (--group-by <field>[:<bucket>], up to 3):
5243
- A field slug; date fields take a bucket: day, week, month, quarter or year
5244
- (a date field without bucket groups by day). Each group key comes back as
5245
- {value, label}; records with an empty value fall into one group with
5246
- value/label null. A reference key's value is the target record id: reuse
5247
- it in --where "<field> eq <value>" to list the records of that group.
5248
-
5249
- Metrics (--metric [<alias>=]<op>[:<field>], up to 10, default "count"):
5250
- count number of records
5251
- count:<field> records where <field> is not null (same rule as a
5252
- panel COUNT; options skip -1)
5253
- count_distinct:<field>, sum:<field>, avg:<field>, min:<field>, max:<field>
5254
- The alias defaults to "count" for a bare count and to <op>_<field>
5255
- otherwise (e.g. sum_amount). avg/min/max are null when no record has a
5256
- value; min/max on dates return an ISO-8601 UTC instant.
5257
-
5258
- Sort (--sort <alias|field>[:asc|desc], up to 4):
5259
- By a metric alias or a group-by field. Default: group keys ascending.
5142
+ // src/commands/forms.ts
5143
+ var LOCATION_MODES = ["off", "optional", "required"];
5144
+ var MODES = ["create", "update"];
5145
+ var WHEN_MULTIPLE = ["latest", "error"];
5146
+ var WHEN_NONE = ["error", "create"];
5147
+ var FIELD_OPTION_KEYS = [
5148
+ "field",
5149
+ "addField",
5150
+ "removeField",
5151
+ "required",
5152
+ "notRequired",
5153
+ "hidden",
5154
+ "visible",
5155
+ "label",
5156
+ "hint",
5157
+ "default",
5158
+ "defaultToday",
5159
+ "defaultSubmittedAt",
5160
+ "defaultCurrentMember",
5161
+ "clearDefault",
5162
+ "remember",
5163
+ "forget",
5164
+ "urlParam",
5165
+ "clearUrlParam"
5166
+ ];
5167
+ var FIELD_MODIFIER_KEYS = FIELD_OPTION_KEYS.filter(
5168
+ (key) => key !== "field" && key !== "addField" && key !== "removeField"
5169
+ );
5170
+ var UPDATE_OPTION_KEYS = ["match", "whenMultiple", "whenNone", "notFoundMessage"];
5171
+ var FORMS_HELP = `
5172
+ A form is a view of a table through which people add records (or update one, in
5173
+ mode "update"), from Zinkee or, without an account, from its public link.
5174
+ Address the table by slug or UUID, the form by id or exact name, and fields by
5175
+ slug or UUID.
5260
5176
 
5261
- --limit caps the groups returned (default 100, max 1000); meta.aggregate
5262
- reports count, total and truncated. Date buckets use --timezone, or the
5263
- workspace timezone when omitted. --where/--where-json/--search filter the
5264
- records first, exactly as in "records query".
5177
+ Fields (in order) and their settings:
5178
+ --field <slug> the fields of the form, in order (repeat); on update
5179
+ it reorders and keeps the settings of each field
5180
+ --add-field / --remove-field add one at the end / take one out (update)
5181
+ --required / --not-required <slug>
5182
+ --hidden / --visible <slug> a hidden field needs a default value or a URL value
5183
+ --label <slug=text>, --hint <slug=text> label and help text ("slug=" clears it)
5184
+ --default <slug=value> fixed value, as records take it (an option by name)
5185
+ --default-today <slug[=days]> a date: the day it is opened or received, plus days
5186
+ --default-submitted-at <slug> a hidden date with the instant it is received
5187
+ --default-current-member <slug> a hidden member field with who sends it
5188
+ --clear-default <slug>
5189
+ --remember / --forget <slug> the device offers the last answer next time
5190
+ --url-param <slug[=name]> the value can come in the link (?name=value)
5191
+ --clear-url-param <slug>
5192
+ Location:
5193
+ --location off|optional|required --location-field <text field slug>
5194
+ Update an existing record instead of creating one:
5195
+ --mode update --match <spec> (repeat; replaces the conditions)
5196
+ <slug> the field holds what this submission gives to that field
5197
+ <slug>=<value> the field holds that value
5198
+ <slug>:empty the field is empty <slug>:not-empty it is not
5199
+ --when-multiple latest|error --when-none error|create --not-found-message <text>
5200
+ --mode create switches back; --clear-update removes the conditions.
5265
5201
  `;
5266
- function createRecordsApi(command, filePath) {
5267
- const { client, ...runtime } = createCommandContext(command, filePath);
5268
- return {
5269
- api: new RecordsApi(client),
5270
- schemasApi: new SchemasApi(client),
5271
- ...runtime
5202
+ function collect(value, previous = []) {
5203
+ return [...previous, value];
5204
+ }
5205
+ function choice(allowed, label) {
5206
+ return (input) => {
5207
+ const value = input.trim();
5208
+ if (!allowed.includes(value)) {
5209
+ throw new InvalidArgumentError4(`${label} must be ${allowed.join(", ")}; received "${input}".`);
5210
+ }
5211
+ return value;
5272
5212
  };
5273
5213
  }
5274
- function parseCommaSeparatedValues(input, label) {
5275
- const values = input.split(",").map((value) => value.trim()).filter(Boolean);
5276
- if (values.length === 0) {
5277
- throw new InvalidArgumentError3(`Expected ${label} to contain at least one value.`);
5278
- }
5279
- return values;
5214
+ function usage(message) {
5215
+ return new CliError("invalid_cli_usage", message);
5280
5216
  }
5281
- function parseExpressionValue(input) {
5282
- try {
5283
- return parseExpression(input);
5284
- } catch (error) {
5285
- const message = error instanceof Error ? error.message : "Invalid expression.";
5286
- throw new InvalidArgumentError3(message);
5287
- }
5217
+ function createFormsApi(command, filePath) {
5218
+ const { client, ...runtime } = createCommandContext(command, filePath);
5219
+ return { forms: new FormsApi(client), schemas: new SchemasApi(client), ...runtime };
5288
5220
  }
5289
- function parseKeyValueAssignment(input) {
5290
- try {
5291
- return parseKeyValue(input);
5292
- } catch (error) {
5293
- const message = error instanceof Error ? error.message : "Invalid assignment.";
5294
- throw new InvalidArgumentError3(message);
5295
- }
5221
+ async function resolveSchemaId(schemas, selector) {
5222
+ return (await resolveSchemaSelector(schemas, selector)).value;
5296
5223
  }
5297
- function parseJsonKeyValueAssignment(input) {
5298
- try {
5299
- return parseJsonAssignment(input);
5300
- } catch (error) {
5301
- const message = error instanceof Error ? error.message : "Invalid JSON assignment.";
5302
- throw new InvalidArgumentError3(message);
5224
+ function findForm(forms, selector, schema) {
5225
+ const byId = forms.find((form) => form.id === selector);
5226
+ if (byId) {
5227
+ return byId;
5303
5228
  }
5304
- }
5305
- function dedupeStrings(values) {
5306
- return [...new Set(values)];
5307
- }
5308
- function toRecordUuid(value) {
5309
- try {
5310
- const normalized = normalizeUuidOrSlug(value);
5311
- return normalized.kind === "uuid" ? normalized.value : null;
5312
- } catch {
5313
- return null;
5229
+ const byName = forms.filter((form) => form.name === selector);
5230
+ if (byName.length === 1) {
5231
+ return byName[0];
5314
5232
  }
5315
- }
5316
- function collectRecordIds(value, previous = []) {
5317
- const uuid = toRecordUuid(value.trim());
5318
- if (!uuid) {
5319
- throw new InvalidArgumentError3(`Expected a record UUID, received "${value}".`);
5233
+ if (byName.length > 1) {
5234
+ throw usage(`Form name "${selector}" is ambiguous in "${schema}": use its id (zinkee forms list ${schema}).`);
5320
5235
  }
5321
- return [...previous, uuid];
5236
+ throw usage(`Form "${selector}" was not found in "${schema}". List them with: zinkee forms list ${schema}`);
5322
5237
  }
5323
- function readRecordIdsFromFile(path) {
5324
- let contents;
5325
- try {
5326
- contents = readFileSync5(path, "utf8");
5327
- } catch (error) {
5328
- const message = error instanceof Error ? error.message : "Unable to read file.";
5329
- throw new CliError(
5330
- "invalid_cli_usage",
5331
- `Failed to read record ids from ${path}: ${message}`
5332
- );
5333
- }
5334
- const ids = [];
5335
- contents.split(/\r?\n/).forEach((line, index) => {
5336
- const value = line.trim();
5337
- if (!value) {
5338
- return;
5339
- }
5340
- const uuid = toRecordUuid(value);
5341
- if (!uuid) {
5342
- throw new CliError(
5343
- "invalid_cli_usage",
5344
- `Invalid record UUID "${value}" at ${path}:${index + 1}.`
5345
- );
5346
- }
5347
- ids.push(uuid);
5348
- });
5349
- return ids;
5238
+ async function resolveForm(forms, schemaId, selector, schema) {
5239
+ return findForm(await forms.listForms(schemaId), selector, schema);
5350
5240
  }
5351
- function resolveDeleteRecordIds(options) {
5352
- const flagIds = options.record ?? [];
5353
- const fileIds = options.recordsFile ? readRecordIdsFromFile(options.recordsFile) : [];
5354
- const recordIds = dedupeStrings([...flagIds, ...fileIds]);
5355
- if (recordIds.length === 0) {
5356
- throw new CliError(
5357
- "invalid_cli_usage",
5358
- 'Provide at least one record id via "--record <uuid>" (repeatable) or "--records-file <path>".'
5359
- );
5241
+ function splitAssignment2(input, option, valueRequired) {
5242
+ const index = input.indexOf("=");
5243
+ if (index < 0) {
5244
+ if (valueRequired) {
5245
+ throw usage(`Expected "${option} <field>=<value>", received "${input}".`);
5246
+ }
5247
+ return [input.trim(), void 0];
5360
5248
  }
5361
- return recordIds;
5249
+ const field = input.slice(0, index).trim();
5250
+ if (!field) {
5251
+ throw usage(`Expected "${option} <field>=<value>", received "${input}".`);
5252
+ }
5253
+ return [field, input.slice(index + 1)];
5362
5254
  }
5363
- function collectStringValues(value, previous = []) {
5364
- return [...previous, value];
5255
+ function sameField(config, selector) {
5256
+ return config.field === selector || config.fieldId === selector;
5365
5257
  }
5366
- function collectSelectValues(value, previous = []) {
5367
- return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--select")]);
5258
+ function toInputField(config) {
5259
+ const { fieldId: _fieldId, ...rest } = config;
5260
+ return { ...rest };
5368
5261
  }
5369
- function collectSortValues(value, previous = []) {
5370
- return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--sort")]);
5262
+ function fieldOf(fields, selector) {
5263
+ const existing = fields.find((config) => sameField(config, selector));
5264
+ if (existing) {
5265
+ return existing;
5266
+ }
5267
+ const added = { field: selector };
5268
+ fields.push(added);
5269
+ return added;
5371
5270
  }
5372
- function collectWhereExpressions(value, previous = []) {
5373
- return [...previous, parseExpressionValue(value)];
5271
+ function hasAny(options, keys) {
5272
+ return keys.some((key) => {
5273
+ const value = options[key];
5274
+ return Array.isArray(value) ? value.length > 0 : value !== void 0;
5275
+ });
5374
5276
  }
5375
- function splitKnownSuffix(input, suffixes) {
5376
- const index = input.lastIndexOf(":");
5377
- if (index !== -1) {
5378
- const suffix = input.slice(index + 1).trim().toLowerCase();
5379
- if (suffixes.includes(suffix)) {
5380
- return { head: input.slice(0, index).trim(), suffix };
5277
+ function applyFieldModifiers(fields, options) {
5278
+ const each = (values, apply) => {
5279
+ for (const value of values ?? []) {
5280
+ apply(value);
5381
5281
  }
5282
+ };
5283
+ each(options.required, (slug) => fieldOf(fields, slug).required = true);
5284
+ each(options.notRequired, (slug) => fieldOf(fields, slug).required = false);
5285
+ each(options.hidden, (slug) => fieldOf(fields, slug).hidden = true);
5286
+ each(options.visible, (slug) => fieldOf(fields, slug).hidden = false);
5287
+ each(options.label, (input) => {
5288
+ const [slug, text] = splitAssignment2(input, "--label", true);
5289
+ fieldOf(fields, slug).label = text ? text : null;
5290
+ });
5291
+ each(options.hint, (input) => {
5292
+ const [slug, text] = splitAssignment2(input, "--hint", true);
5293
+ fieldOf(fields, slug).help = text ? text : null;
5294
+ });
5295
+ each(options.default, (input) => {
5296
+ const [slug, value] = splitAssignment2(input, "--default", true);
5297
+ fieldOf(fields, slug).defaultValue = { kind: "value", value };
5298
+ });
5299
+ each(options.defaultToday, (input) => {
5300
+ const [slug, days] = splitAssignment2(input, "--default-today", false);
5301
+ const offsetDays = days === void 0 || days.trim() === "" ? 0 : Number(days);
5302
+ if (!Number.isInteger(offsetDays)) {
5303
+ throw usage(`Expected "--default-today <field>[=<whole days>]", received "${input}".`);
5304
+ }
5305
+ fieldOf(fields, slug).defaultValue = { kind: "today", offsetDays };
5306
+ });
5307
+ each(options.defaultSubmittedAt, (slug) => {
5308
+ const config = fieldOf(fields, slug);
5309
+ config.hidden = true;
5310
+ config.defaultValue = { kind: "submittedAt" };
5311
+ });
5312
+ each(options.defaultCurrentMember, (slug) => {
5313
+ const config = fieldOf(fields, slug);
5314
+ config.hidden = true;
5315
+ config.defaultValue = { kind: "currentMember" };
5316
+ });
5317
+ each(options.clearDefault, (slug) => fieldOf(fields, slug).defaultValue = null);
5318
+ each(options.remember, (slug) => fieldOf(fields, slug).rememberOnDevice = true);
5319
+ each(options.forget, (slug) => fieldOf(fields, slug).rememberOnDevice = false);
5320
+ each(options.urlParam, (input) => {
5321
+ const [slug, name] = splitAssignment2(input, "--url-param", false);
5322
+ const config = fieldOf(fields, slug);
5323
+ config.allowUrlPrefill = true;
5324
+ config.urlParam = name && name.trim() ? name.trim() : null;
5325
+ });
5326
+ each(options.clearUrlParam, (slug) => {
5327
+ const config = fieldOf(fields, slug);
5328
+ config.allowUrlPrefill = false;
5329
+ config.urlParam = null;
5330
+ });
5331
+ }
5332
+ function parseMatch(input) {
5333
+ const emptiness = /^([^=:]+):(empty|not-empty)$/.exec(input.trim());
5334
+ if (emptiness) {
5335
+ return {
5336
+ field: emptiness[1].trim(),
5337
+ op: emptiness[2] === "empty" ? "isEmpty" : "isNotEmpty"
5338
+ };
5382
5339
  }
5383
- return { head: input.trim() };
5384
- }
5385
- function parseGroupBy(input) {
5386
- const { head, suffix } = splitKnownSuffix(input, AGGREGATE_BUCKETS);
5387
- if (!head) {
5388
- throw new CliError(
5389
- "invalid_cli_usage",
5390
- `Invalid --group-by "${input}": expected <field>[:<bucket>] with bucket one of ${AGGREGATE_BUCKETS.join(", ")}.`
5391
- );
5340
+ const index = input.indexOf("=");
5341
+ if (index >= 0) {
5342
+ const field = input.slice(0, index).trim();
5343
+ if (!field) {
5344
+ throw usage(`Expected "--match <field>=<value>", received "${input}".`);
5345
+ }
5346
+ return { field, op: "equalsValue", value: input.slice(index + 1) };
5347
+ }
5348
+ if (!input.trim()) {
5349
+ throw usage('Expected "--match <field>", "<field>=<value>", "<field>:empty" or "<field>:not-empty".');
5350
+ }
5351
+ return { field: input.trim(), op: "equalsSubmitted" };
5352
+ }
5353
+ function toInputCondition(condition) {
5354
+ const { fieldId: _fieldId, ...rest } = condition;
5355
+ return { ...rest };
5356
+ }
5357
+ function setText(input, key, value, clear, option) {
5358
+ if (value !== void 0 && clear) {
5359
+ throw usage(`Use either "--${option}" or "--clear-${option}", not both.`);
5360
+ }
5361
+ if (value !== void 0) {
5362
+ input[key] = value;
5363
+ } else if (clear) {
5364
+ input[key] = null;
5365
+ }
5366
+ }
5367
+ function buildFormInput(options, current) {
5368
+ const input = { ...readRawObject(options.raw, options.rawFile) };
5369
+ if (options.name !== void 0) input.name = options.name;
5370
+ if (options.title !== void 0) input.title = options.title;
5371
+ setText(input, "description", options.description, options.clearDescription, "description");
5372
+ setText(input, "submitLabel", options.submitLabel, options.clearSubmitLabel, "submit-label");
5373
+ setText(input, "successMessage", options.successMessage, options.clearSuccessMessage, "success-message");
5374
+ if (hasAny(options, FIELD_OPTION_KEYS)) {
5375
+ input.fields = buildFields(options, current, input.fields);
5376
+ }
5377
+ if (options.location !== void 0 || options.locationField !== void 0) {
5378
+ const mode = options.location ?? current?.location.mode;
5379
+ if (mode === void 0) {
5380
+ throw usage('Give the mode with "--location optional|required" along with "--location-field".');
5381
+ }
5382
+ const field = options.locationField ?? current?.location.field ?? void 0;
5383
+ const location = { mode };
5384
+ if (mode !== "off") {
5385
+ if (!field) {
5386
+ throw usage('A form that asks for the location needs "--location-field <text field>".');
5387
+ }
5388
+ location.field = field;
5389
+ }
5390
+ input.location = location;
5392
5391
  }
5393
- return suffix ? { field: head, bucket: suffix } : { field: head };
5394
- }
5395
- function parseMetric(input) {
5396
- const usage = `Invalid --metric "${input}": expected [<alias>=]<op>[:<field>], e.g. "count", "total=sum:amount" or "count_distinct:customer".`;
5397
- const aliasIndex = input.lastIndexOf("=");
5398
- const alias = aliasIndex === -1 ? void 0 : input.slice(0, aliasIndex).trim();
5399
- const expression = input.slice(aliasIndex + 1);
5400
- const fieldIndex = expression.indexOf(":");
5401
- const op = (fieldIndex === -1 ? expression : expression.slice(0, fieldIndex)).trim();
5402
- const field = fieldIndex === -1 ? void 0 : expression.slice(fieldIndex + 1).trim();
5403
- if (alias === "" || !/^[A-Za-z_]+$/.test(op) || field === "") {
5404
- throw new CliError("invalid_cli_usage", usage);
5392
+ if (options.mode !== void 0) input.mode = options.mode;
5393
+ if (options.clearUpdate && hasAny(options, UPDATE_OPTION_KEYS)) {
5394
+ throw usage('Use either "--clear-update" or the options of the update mode, not both.');
5405
5395
  }
5406
- return {
5407
- op,
5408
- ...field !== void 0 ? { field } : {},
5409
- ...alias !== void 0 ? { as: alias } : {}
5410
- };
5411
- }
5412
- function parseAggregateSort(input) {
5413
- const { head, suffix } = splitKnownSuffix(input, ["asc", "desc"]);
5414
- if (!head) {
5415
- throw new CliError(
5416
- "invalid_cli_usage",
5417
- `Invalid --sort "${input}": expected <alias|field>[:asc|desc].`
5418
- );
5396
+ if (options.clearUpdate) {
5397
+ input.update = null;
5398
+ } else if (hasAny(options, UPDATE_OPTION_KEYS)) {
5399
+ input.update = buildUpdate(options, current?.update ?? input.update);
5419
5400
  }
5420
- return { by: head, direction: (suffix ?? "asc").toUpperCase() };
5401
+ return input;
5421
5402
  }
5422
- function parseGroupLimit(input) {
5423
- const limit = /^\d+$/.test(input.trim()) ? Number(input) : Number.NaN;
5424
- if (!(limit >= 1 && limit <= 1e3)) {
5425
- throw new CliError(
5426
- "invalid_cli_usage",
5427
- `Invalid --limit "${input}": expected a number of groups from 1 to 1000.`
5428
- );
5403
+ function buildFields(options, current, rawFields) {
5404
+ const saved = (current?.fields ?? []).map(toInputField);
5405
+ let fields;
5406
+ if (Array.isArray(rawFields)) {
5407
+ fields = rawFields.map((config) => ({ ...config }));
5408
+ } else if (options.field && options.field.length > 0) {
5409
+ fields = options.field.map((slug) => {
5410
+ const existing = saved.find((config) => sameField(config, slug));
5411
+ return existing ? { ...existing } : { field: slug };
5412
+ });
5413
+ } else if (current) {
5414
+ fields = saved;
5415
+ } else {
5416
+ if (hasAny(options, FIELD_MODIFIER_KEYS)) {
5417
+ throw usage(
5418
+ 'List the fields of the form, in order, with "--field" to set their options on create; without "--field" the form gets every field with the default settings, which "forms update" can change afterwards.'
5419
+ );
5420
+ }
5421
+ fields = [];
5429
5422
  }
5430
- return limit;
5431
- }
5432
- function collectGroupBy(value, previous = []) {
5433
- return [...previous, parseGroupBy(value)];
5434
- }
5435
- function collectMetrics(value, previous = []) {
5436
- return [...previous, parseMetric(value)];
5423
+ for (const slug of options.addField ?? []) {
5424
+ if (!fields.some((config) => sameField(config, slug))) {
5425
+ fields.push({ field: slug });
5426
+ }
5427
+ }
5428
+ for (const slug of options.removeField ?? []) {
5429
+ const before = fields.length;
5430
+ fields = fields.filter((config) => !sameField(config, slug));
5431
+ if (fields.length === before) {
5432
+ throw usage(`Field "${slug}" is not in the form.`);
5433
+ }
5434
+ }
5435
+ applyFieldModifiers(fields, options);
5436
+ return fields;
5437
5437
  }
5438
- function collectAggregateSort(value, previous = []) {
5439
- return [...previous, parseAggregateSort(value)];
5438
+ function buildUpdate(options, saved) {
5439
+ const update = {
5440
+ conditions: (saved?.conditions ?? []).map(toInputCondition),
5441
+ ...saved?.whenMultiple ? { whenMultiple: saved.whenMultiple } : {},
5442
+ ...saved?.whenNone ? { whenNone: saved.whenNone } : {},
5443
+ ...saved?.noMatchMessage ? { noMatchMessage: saved.noMatchMessage } : {}
5444
+ };
5445
+ if (options.match && options.match.length > 0) {
5446
+ update.conditions = options.match.map(parseMatch);
5447
+ }
5448
+ if (options.whenMultiple !== void 0) update.whenMultiple = options.whenMultiple;
5449
+ if (options.whenNone !== void 0) update.whenNone = options.whenNone;
5450
+ if (options.notFoundMessage !== void 0) update.noMatchMessage = options.notFoundMessage;
5451
+ return update;
5440
5452
  }
5441
- function collectKeyValueAssignments(value, previous = []) {
5442
- return [...previous, parseKeyValueAssignment(value)];
5453
+ function linkSummary(link) {
5454
+ if (!link) return "";
5455
+ if (!link.exists) return "none";
5456
+ if (!link.active) return "off";
5457
+ return `${link.url ?? link.token ?? "on"}${link.hasPassword ? " (password)" : ""}`;
5443
5458
  }
5444
- function collectJsonAssignments(value, previous = []) {
5445
- return [...previous, parseJsonKeyValueAssignment(value)];
5459
+ function emitFormsTable(stdout, forms) {
5460
+ printTable(
5461
+ forms.map((form) => ({
5462
+ id: form.id,
5463
+ name: form.name ?? "",
5464
+ mode: form.mode,
5465
+ fields: Array.isArray(form.fields) ? form.fields.length : 0,
5466
+ link: linkSummary(form.link)
5467
+ })),
5468
+ ["id", "name", "mode", "fields", "link"],
5469
+ stdout
5470
+ );
5446
5471
  }
5447
- function buildAssignmentObject(assignments = [], jsonAssignments = []) {
5448
- const output = {};
5449
- for (const assignment of assignments) {
5450
- output[assignment.key] = assignment.value;
5451
- }
5452
- for (const assignment of jsonAssignments) {
5453
- output[assignment.key] = assignment.value;
5472
+ function describeDefault(value) {
5473
+ if (!value) return "";
5474
+ switch (value.kind) {
5475
+ case "value":
5476
+ return `= ${JSON.stringify(value.value)}`;
5477
+ case "today":
5478
+ return value.offsetDays ? `today ${value.offsetDays > 0 ? "+" : ""}${value.offsetDays}d` : "today";
5479
+ case "submittedAt":
5480
+ return "submission time";
5481
+ case "currentMember":
5482
+ return "current member";
5483
+ default:
5484
+ return "";
5454
5485
  }
5455
- return output;
5456
5486
  }
5457
- function toQueryExpressions(expressions) {
5458
- if (!expressions || expressions.length === 0) {
5459
- return void 0;
5487
+ function emitForm(stdout, form) {
5488
+ writeLine(stdout, `${form.name ?? form.id} (${form.id}) \u2014 mode ${form.mode}`);
5489
+ writeLine(stdout, `Title: ${form.title ?? ""}`);
5490
+ if (form.description) writeLine(stdout, `Description: ${form.description}`);
5491
+ if (form.submitLabel) writeLine(stdout, `Button: ${form.submitLabel}`);
5492
+ if (form.successMessage) writeLine(stdout, `Confirmation: ${form.successMessage}`);
5493
+ writeLine(
5494
+ stdout,
5495
+ `Location: ${form.location.mode}${form.location.mode !== "off" && form.location.field ? ` \u2192 ${form.location.field}` : ""}`
5496
+ );
5497
+ if (form.mode === "update" && form.update) {
5498
+ const conditions = form.update.conditions.map((condition) => `${condition.field} ${condition.op}${condition.value !== void 0 ? ` ${JSON.stringify(condition.value)}` : ""}`).join("; ");
5499
+ writeLine(
5500
+ stdout,
5501
+ `Updates the record where: ${conditions} (several: ${form.update.whenMultiple ?? "latest"}, none: ${form.update.whenNone ?? "error"})`
5502
+ );
5460
5503
  }
5461
- return expressions.map((expression) => ({
5462
- field: expression.field,
5463
- comparator: expression.comparator,
5464
- value: expression.value
5465
- }));
5504
+ if (form.link) writeLine(stdout, `Link: ${linkSummary(form.link)}`);
5505
+ printTable(
5506
+ form.fields.map((config) => ({
5507
+ field: config.field,
5508
+ label: config.label ?? "",
5509
+ required: config.required ? "yes" : "",
5510
+ hidden: config.hidden ? "yes" : "",
5511
+ default: describeDefault(config.defaultValue),
5512
+ remember: config.rememberOnDevice ? "yes" : "",
5513
+ url: config.allowUrlPrefill ? config.urlParam ?? config.fieldId ?? "" : ""
5514
+ })),
5515
+ ["field", "label", "required", "hidden", "default", "remember", "url"],
5516
+ stdout
5517
+ );
5466
5518
  }
5467
- function parseWhereJson(input) {
5468
- let parsed;
5469
- try {
5470
- parsed = JSON.parse(input);
5471
- } catch (error) {
5472
- const message = error instanceof Error ? error.message : "Invalid JSON.";
5473
- throw new CliError(
5474
- "invalid_cli_usage",
5475
- `Failed to parse JSON from --where-json: ${message}`
5476
- );
5519
+ function emitLink(stdout, link) {
5520
+ if (!link.exists) {
5521
+ writeLine(stdout, 'The form has no public link yet: create it with "zinkee forms link set <schema> <form> --active".');
5522
+ return;
5477
5523
  }
5478
- if (!Array.isArray(parsed) && !isJsonObject(parsed)) {
5479
- throw new CliError(
5480
- "invalid_cli_usage",
5481
- 'Expected --where-json to contain a JSON array of conditions or a JSON object (a condition or an {"and"|"or": [...]} group).'
5482
- );
5524
+ if (!link.active) {
5525
+ writeLine(stdout, `The public link is off${link.hasPassword ? " (it keeps its password)" : ""}.`);
5526
+ return;
5483
5527
  }
5484
- return parsed;
5485
- }
5486
- function resolveWhere(options) {
5487
- const where = toQueryExpressions(options.where);
5488
- if (options.whereJson !== void 0) {
5489
- if (where) {
5490
- throw new CliError(
5491
- "invalid_cli_usage",
5492
- 'Provide either "--where" or "--where-json", not both.'
5493
- );
5528
+ writeLine(stdout, `Public link: ${link.url ?? link.token}`);
5529
+ writeLine(stdout, `Password: ${link.hasPassword ? "yes" : "no"}`);
5530
+ }
5531
+ function addEditOptions(command, update) {
5532
+ command.option("--name <name>", update ? "new name of the form" : "name of the form among the views of the table").option("--title <text>", "title shown at the top of the form" + (update ? "" : " (the name by default)")).option("--description <text>", "text under the title").option("--submit-label <text>", "label of the send button").option("--success-message <text>", "message shown after sending");
5533
+ if (update) {
5534
+ command.option("--clear-description", "remove the description").option("--clear-submit-label", "remove the button label (back to the default)").option("--clear-success-message", "remove the confirmation message").option("--clear-update", "remove the conditions of the update mode");
5535
+ }
5536
+ command.option("--field <slug>", "a field of the form, in order (repeat)", collect);
5537
+ if (update) {
5538
+ command.option("--add-field <slug>", "add a field at the end (repeat)", collect).option("--remove-field <slug>", "take a field out of the form (repeat)", collect);
5539
+ }
5540
+ return command.option("--required <slug>", "make a field required (repeat)", collect).option("--not-required <slug>", "make a field optional (repeat)", collect).option("--hidden <slug>", "hide a field: it takes its default or URL value (repeat)", collect).option("--visible <slug>", "show a hidden field (repeat)", collect).option("--label <slug=text>", "label of a field in the form (repeat)", collect).option("--hint <slug=text>", "help text under a field (repeat)", collect).option("--default <slug=value>", "fixed default value (repeat)", collect).option("--default-today <slug[=days]>", "a date defaults to today plus days (repeat)", collect).option("--default-submitted-at <slug>", "hidden date with the instant it is received (repeat)", collect).option("--default-current-member <slug>", "hidden member field with who sends it (repeat)", collect).option("--clear-default <slug>", "remove the default value of a field (repeat)", collect).option("--remember <slug>", "the device offers the last answer next time (repeat)", collect).option("--forget <slug>", "stop remembering a field on the device (repeat)", collect).option("--url-param <slug[=name]>", "the field can come in the link as ?name=value (repeat)", collect).option("--clear-url-param <slug>", "the field no longer comes from the link (repeat)", collect).option(
5541
+ "--location <mode>",
5542
+ "ask for the device's location: off, optional or required",
5543
+ choice(LOCATION_MODES, "--location")
5544
+ ).option("--location-field <slug>", "text field the location is written to").option("--mode <mode>", "create (a record per submission) or update (an existing one)", choice(MODES, "--mode")).option("--match <spec>", "a condition to find the record to update (repeat; replaces them)", collect).option(
5545
+ "--when-multiple <choice>",
5546
+ "several records match: latest or error",
5547
+ choice(WHEN_MULTIPLE, "--when-multiple")
5548
+ ).option("--when-none <choice>", "no record matches: error or create", choice(WHEN_NONE, "--when-none")).option("--not-found-message <text>", "what people read when no record matches").option("--raw <json>", "full form JSON (the API body); the options above override its keys").option("--raw-file <path>", "path to the full form JSON").addHelpText("after", FORMS_HELP);
5549
+ }
5550
+ function registerFormsCommands(program, options = {}) {
5551
+ const filePath = options.configPath ?? defaultConfigPath;
5552
+ const stdout = options.stdout ?? process.stdout;
5553
+ const forms = program.command("forms").description("Manage the forms of a table and their public links");
5554
+ forms.command("list").description("List the forms of a table").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
5555
+ const { forms: api, schemas, json } = createFormsApi(this, filePath);
5556
+ const data = await api.listForms(await resolveSchemaId(schemas, schema));
5557
+ if (json) {
5558
+ emitJson(stdout, "forms list", data, filePath);
5559
+ return;
5494
5560
  }
5495
- return parseWhereJson(options.whereJson);
5496
- }
5497
- return where;
5498
- }
5499
- function buildRecordQueryInput(options, allowRaw) {
5500
- const input = allowRaw ? readRawObject(options.raw, options.rawFile) : {};
5501
- if (options.select && options.select.length > 0) {
5502
- input.select = [...options.select];
5503
- }
5504
- const where = resolveWhere(options);
5505
- if (where !== void 0) {
5506
- input.where = where;
5507
- }
5508
- if (options.search !== void 0) {
5509
- input.search = { term: options.search };
5510
- }
5511
- if (options.sort && options.sort.length > 0) {
5512
- input.sort = [...options.sort];
5513
- }
5514
- if (options.limit !== void 0) {
5515
- input.limit = options.limit;
5516
- }
5517
- if (options.offset !== void 0) {
5518
- input.offset = options.offset;
5519
- }
5520
- return input;
5521
- }
5522
- function buildRecordAggregateInput(options) {
5523
- const input = readRawObject(options.raw, options.rawFile);
5524
- const where = resolveWhere(options);
5525
- if (where !== void 0) {
5526
- input.where = where;
5527
- }
5528
- if (options.search !== void 0) {
5529
- input.search = { term: options.search };
5530
- }
5531
- if (options.groupBy && options.groupBy.length > 0) {
5532
- input.groupBy = [...options.groupBy];
5533
- }
5534
- if (options.metric && options.metric.length > 0) {
5535
- input.metrics = [...options.metric];
5536
- }
5537
- if (options.sort && options.sort.length > 0) {
5538
- input.sort = [...options.sort];
5539
- }
5540
- if (options.limit !== void 0) {
5541
- input.limit = options.limit;
5542
- }
5543
- if (options.timezone !== void 0) {
5544
- input.timezone = options.timezone;
5545
- }
5546
- return input;
5547
- }
5548
- function toAggregateTableRows(groups) {
5549
- return groups.map((group) => {
5550
- const row = {};
5551
- for (const [slug, key] of Object.entries(group.key ?? {})) {
5552
- row[slug] = key?.label ? key.label : key?.value ?? "(empty)";
5561
+ emitFormsTable(stdout, data);
5562
+ });
5563
+ forms.command("get").description("Get a form with its fields, settings and public link").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<form>", "form id or exact name").action(async function action(schema, form) {
5564
+ const { forms: api, schemas, json } = createFormsApi(this, filePath);
5565
+ const data = await resolveForm(api, await resolveSchemaId(schemas, schema), form, schema.value);
5566
+ if (json) {
5567
+ emitJson(stdout, "forms get", data, filePath);
5568
+ return;
5553
5569
  }
5554
- for (const [alias, value] of Object.entries(group.metrics ?? {})) {
5555
- row[alias in row ? `${alias} (metric)` : alias] = value;
5570
+ emitForm(stdout, data);
5571
+ });
5572
+ addEditOptions(
5573
+ forms.command("create").description("Create a form on a table").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector),
5574
+ false
5575
+ ).action(async function action(schema, commandOptions) {
5576
+ const { forms: api, schemas, json, readOnly } = createFormsApi(this, filePath);
5577
+ ensureWritable("forms create", readOnly, "write");
5578
+ const input = buildFormInput(commandOptions, void 0);
5579
+ if (typeof input.name !== "string" || input.name.trim().length === 0) {
5580
+ throw usage('Provide the name of the form with "--name".');
5581
+ }
5582
+ const schemaId = await resolveSchemaId(schemas, schema);
5583
+ const data = await api.createForm(schemaId, input);
5584
+ if (json) {
5585
+ emitJson(stdout, "forms create", data, filePath);
5586
+ return;
5556
5587
  }
5557
- return row;
5588
+ writeLine(stdout, `Created form "${data.name ?? input.name}" (${data.id}) on "${schema.value}".`);
5589
+ writeLine(stdout, `Share it with: zinkee forms link set ${schema.value} ${data.id} --active`);
5590
+ });
5591
+ addEditOptions(
5592
+ forms.command("update").description("Change a form: its settings, fields, location or update mode").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<form>", "form id or exact name"),
5593
+ true
5594
+ ).action(async function action(schema, form, commandOptions) {
5595
+ const { forms: api, schemas, json, readOnly } = createFormsApi(this, filePath);
5596
+ ensureWritable("forms update", readOnly, "write");
5597
+ const schemaId = await resolveSchemaId(schemas, schema);
5598
+ const current = await resolveForm(api, schemaId, form, schema.value);
5599
+ const input = buildFormInput(commandOptions, current);
5600
+ if (isEmptyObject(input)) {
5601
+ throw usage('Nothing to change: see "zinkee forms update --help".');
5602
+ }
5603
+ const data = await api.updateForm(schemaId, current.id, input);
5604
+ if (json) {
5605
+ emitJson(stdout, "forms update", data, filePath);
5606
+ return;
5607
+ }
5608
+ writeLine(stdout, `Updated form "${data.name ?? form}" (${data.id}).`);
5558
5609
  });
5559
- }
5560
- function readRecordsFromFile(path) {
5561
- let contents;
5562
- try {
5563
- contents = readFileSync5(path, "utf8");
5564
- } catch (error) {
5565
- const message = error instanceof Error ? error.message : "Unable to read file.";
5566
- throw new CliError(
5567
- "invalid_cli_usage",
5568
- `Failed to read records from ${path}: ${message}`
5569
- );
5570
- }
5571
- let parsed;
5572
- try {
5573
- parsed = JSON.parse(contents);
5574
- } catch (error) {
5575
- const message = error instanceof Error ? error.message : "Invalid JSON.";
5576
- throw new CliError(
5577
- "invalid_cli_usage",
5578
- `Failed to parse JSON from --records-file ${path}: ${message}`
5579
- );
5580
- }
5581
- if (!Array.isArray(parsed)) {
5582
- throw new CliError(
5583
- "invalid_cli_usage",
5584
- `Expected --records-file ${path} to contain a JSON array of record objects.`
5585
- );
5586
- }
5587
- if (parsed.length === 0) {
5588
- throw new CliError(
5589
- "invalid_cli_usage",
5590
- `--records-file ${path} must contain at least one record.`
5591
- );
5592
- }
5593
- return parsed.map((record, index) => {
5594
- if (!isJsonObject(record)) {
5595
- throw new CliError(
5596
- "invalid_cli_usage",
5597
- `Record at index ${index} in --records-file ${path} must be a JSON object.`
5598
- );
5610
+ forms.command("delete").description("Delete a form; its public link stops working and its records stay").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<form>", "form id or exact name").action(async function action(schema, form) {
5611
+ const { forms: api, schemas, json, readOnly } = createFormsApi(this, filePath);
5612
+ ensureWritable("forms delete", readOnly, "destructive");
5613
+ const schemaId = await resolveSchemaId(schemas, schema);
5614
+ const current = await resolveForm(api, schemaId, form, schema.value);
5615
+ const data = await api.deleteForm(schemaId, current.id);
5616
+ if (json) {
5617
+ emitJson(stdout, "forms delete", data, filePath);
5618
+ return;
5599
5619
  }
5600
- return record;
5620
+ writeLine(stdout, `Deleted form "${current.name ?? current.id}".`);
5601
5621
  });
5602
- }
5603
- function buildCreateRecords(options) {
5604
- const hasSingleRecordFlags = (options.set?.length ?? 0) > 0 || (options.setJson?.length ?? 0) > 0 || options.raw !== void 0 || options.rawFile !== void 0;
5605
- if (options.recordsFile !== void 0) {
5606
- if (hasSingleRecordFlags) {
5607
- throw new CliError(
5608
- "invalid_cli_usage",
5609
- 'Provide either "--records-file" or the single-record flags (--set/--set-json/--raw/--raw-file), not both.'
5610
- );
5622
+ const link = forms.command("link").description("Manage the public link of a form");
5623
+ link.command("get").description("Show the public link of a form: whether it is on, its URL and whether it has a password").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<form>", "form id or exact name").action(async function action(schema, form) {
5624
+ const { forms: api, schemas, json } = createFormsApi(this, filePath);
5625
+ const schemaId = await resolveSchemaId(schemas, schema);
5626
+ const current = await resolveForm(api, schemaId, form, schema.value);
5627
+ const data = await api.getLink(schemaId, current.id);
5628
+ if (json) {
5629
+ emitJson(stdout, "forms link get", data, filePath);
5630
+ return;
5611
5631
  }
5612
- return readRecordsFromFile(options.recordsFile);
5632
+ emitLink(stdout, data);
5633
+ });
5634
+ link.command("set").description("Switch the public link on or off, set or remove its password, or give it a new URL").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<form>", "form id or exact name").option("--active", "switch the link on (the first time, it creates it)").option("--inactive", "switch the link off").option("--password <password>", "ask for this password (1 to 128 characters)").option("--clear-password", "stop asking for a password").option("--regenerate", "give the link a new URL: the old one stops working").addHelpText(
5635
+ "after",
5636
+ "\nWithout --active or --inactive the link keeps its state (a new link starts on).\nThe password is never shown again: share it apart from the link.\n"
5637
+ ).action(async function action(schema, form, commandOptions) {
5638
+ const { forms: api, schemas, json, readOnly } = createFormsApi(this, filePath);
5639
+ ensureWritable("forms link set", readOnly, "write");
5640
+ if (commandOptions.active && commandOptions.inactive) {
5641
+ throw usage('Use either "--active" or "--inactive", not both.');
5642
+ }
5643
+ if (commandOptions.password !== void 0 && commandOptions.clearPassword) {
5644
+ throw usage('Use either "--password" or "--clear-password", not both.');
5645
+ }
5646
+ if (!commandOptions.active && !commandOptions.inactive && commandOptions.password === void 0 && !commandOptions.clearPassword && !commandOptions.regenerate) {
5647
+ throw usage("Nothing to change: use --active, --inactive, --password, --clear-password or --regenerate.");
5648
+ }
5649
+ const schemaId = await resolveSchemaId(schemas, schema);
5650
+ const current = await resolveForm(api, schemaId, form, schema.value);
5651
+ let active;
5652
+ if (commandOptions.active || commandOptions.inactive) {
5653
+ active = commandOptions.active === true;
5654
+ } else {
5655
+ const saved = current.link ?? await api.getLink(schemaId, current.id);
5656
+ active = saved.exists ? saved.active : true;
5657
+ }
5658
+ const input = { active };
5659
+ if (commandOptions.password !== void 0) input.password = commandOptions.password;
5660
+ if (commandOptions.clearPassword) input.password = null;
5661
+ if (commandOptions.regenerate) input.regenerate = true;
5662
+ const data = await api.setLink(schemaId, current.id, input);
5663
+ if (json) {
5664
+ emitJson(stdout, "forms link set", data, filePath);
5665
+ return;
5666
+ }
5667
+ emitLink(stdout, data);
5668
+ });
5669
+ }
5670
+
5671
+ // src/api/formulas.ts
5672
+ function toRequestBody(input) {
5673
+ if (input.scope === "FIELD") {
5674
+ return {
5675
+ scope: input.scope,
5676
+ schema: input.schema.value,
5677
+ field: input.field.value
5678
+ };
5613
5679
  }
5614
- const values = {
5615
- ...readRawObject(options.raw, options.rawFile),
5616
- ...buildAssignmentObject(options.set, options.setJson)
5617
- };
5618
- if (isEmptyObject(values)) {
5619
- throw new CliError(
5620
- "invalid_cli_usage",
5621
- 'Provide record fields via "--set", "--set-json", "--raw", "--raw-file", or load multiple records with "--records-file".'
5622
- );
5680
+ if (input.scope === "SCHEMA") {
5681
+ return {
5682
+ scope: input.scope,
5683
+ schema: input.schema.value
5684
+ };
5623
5685
  }
5624
- return [values];
5686
+ return { scope: input.scope };
5625
5687
  }
5626
- function buildRecordUpdateInput(options) {
5627
- const raw = readRawObject(options.raw, options.rawFile);
5628
- const input = {};
5629
- const setPayload = {
5630
- ...raw,
5631
- ...buildAssignmentObject(options.set, options.setJson)
5632
- };
5633
- const unsetPayload = [...options.unset ?? []];
5634
- for (const key of Object.keys(setPayload)) {
5635
- const unsetIndex = unsetPayload.indexOf(key);
5636
- if (unsetIndex !== -1) {
5637
- unsetPayload.splice(unsetIndex, 1);
5638
- }
5639
- }
5640
- if (Object.keys(setPayload).length > 0) {
5641
- input.set = setPayload;
5642
- } else {
5643
- delete input.set;
5688
+ var FormulasApi = class {
5689
+ constructor(client) {
5690
+ this.client = client;
5644
5691
  }
5645
- if (unsetPayload.length > 0) {
5646
- input.unset = [...new Set(unsetPayload)];
5647
- } else {
5648
- delete input.unset;
5692
+ recompute(input) {
5693
+ return this.client.requestJson(
5694
+ "/api/v2/formulas:recompute",
5695
+ {
5696
+ method: "POST",
5697
+ headers: {
5698
+ "content-type": "application/json"
5699
+ },
5700
+ body: JSON.stringify(toRequestBody(input))
5701
+ }
5702
+ );
5649
5703
  }
5650
- if (isEmptyObject(input)) {
5704
+ };
5705
+
5706
+ // src/commands/formulas.ts
5707
+ function createFormulasApi(command, filePath) {
5708
+ const { client, ...runtime } = createCommandContext(command, filePath);
5709
+ return {
5710
+ api: new FormulasApi(client),
5711
+ ...runtime
5712
+ };
5713
+ }
5714
+ function ensureConfirmed(commandName, confirmed) {
5715
+ if (!confirmed) {
5651
5716
  throw new CliError(
5652
5717
  "invalid_cli_usage",
5653
- 'Provide record updates via "--set", "--set-json", "--unset", "--raw", or "--raw-file".'
5718
+ `Command "${commandName}" requires --yes because it may enqueue a large recalculation.`
5654
5719
  );
5655
5720
  }
5656
- return input;
5657
- }
5658
- function getQueryRecords(result) {
5659
- return Array.isArray(result.records) ? result.records : [];
5660
- }
5661
- function getRecordIdentifier(record) {
5662
- return typeof record.recordId === "string" ? record.recordId : "unknown";
5663
5721
  }
5664
- async function resolveSchemaSelector(api, selector) {
5665
- if (selector.kind === "uuid") {
5666
- return selector;
5722
+ function emitResult(stdout, commandName, result, configPath, json) {
5723
+ if (json) {
5724
+ emitJson(stdout, commandName, result, configPath);
5725
+ return;
5667
5726
  }
5668
- const schemas = await api.listSchemas();
5669
- const match = schemas.find((entry) => entry.slug === selector.value);
5670
- if (!match || typeof match.id !== "string") {
5671
- throw new CliError("invalid_cli_usage", `Schema "${selector.value}" not found.`);
5672
- }
5673
- return {
5674
- kind: "uuid",
5675
- value: match.id
5676
- };
5727
+ writeLine(
5728
+ stdout,
5729
+ `Queued ${result.eventsQueued} formula recalculation event(s) for ${result.scope.toLowerCase()} scope (request ${result.requestId}).`
5730
+ );
5677
5731
  }
5678
- function registerRecordsCommands(program, options = {}) {
5679
- const filePath = options.configPath ?? defaultConfigPath;
5732
+ async function recompute(command, commandName, input, options, requireConfirmation, confirmed) {
5733
+ const configPath = options.configPath ?? defaultConfigPath;
5680
5734
  const stdout = options.stdout ?? process.stdout;
5681
- const records = program.command("records").description("Manage schema records");
5682
- records.command("list").description("List records for a schema with simple pagination").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--limit <number>", "limit results", parseNonNegativeInteger).option("--offset <number>", "offset results", parseNonNegativeInteger).action(async function action(schema, commandOptions) {
5683
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5684
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5685
- const data = await api.listRecords(
5686
- resolvedSchema,
5687
- buildRecordQueryInput(commandOptions, false)
5688
- );
5689
- const recordsData = getQueryRecords(data);
5690
- if (json) {
5691
- emitJson(
5692
- stdout,
5693
- "records list",
5694
- recordsData,
5695
- filePath,
5696
- data.page ? { page: data.page } : {}
5697
- );
5698
- return;
5699
- }
5700
- emitTable(stdout, recordsData);
5701
- });
5702
- 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(
5703
- "--where <expression>",
5704
- 'condition "<field> <op> [value]" (repeatable, combined with AND)',
5705
- collectWhereExpressions,
5706
- []
5707
- ).option(
5708
- "--where-json <json>",
5709
- 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
5710
- ).option(
5711
- "--search <term>",
5712
- "free-text search term (matched across the schema's searchable fields)"
5713
- ).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) {
5714
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5715
- const query = buildRecordQueryInput(commandOptions, true);
5716
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5717
- const data = await api.queryRecords(resolvedSchema, query);
5718
- const recordsData = getQueryRecords(data);
5719
- if (json) {
5720
- emitJson(
5721
- stdout,
5722
- "records query",
5723
- recordsData,
5724
- filePath,
5725
- data.page ? { page: data.page } : {}
5726
- );
5727
- return;
5728
- }
5729
- emitTable(stdout, recordsData);
5730
- });
5731
- records.command("aggregate").description(
5732
- "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"
5733
- ).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
5734
- "--group-by <field[:bucket]>",
5735
- "group by a field slug; date fields take a bucket day|week|month|quarter|year (repeatable, up to 3)",
5736
- collectGroupBy,
5737
- []
5738
- ).option(
5739
- "--metric <[alias=]op[:field]>",
5740
- "metric count|count_distinct|sum|avg|min|max, e.g. count, total=sum:amount (repeatable, up to 10; default count)",
5741
- collectMetrics,
5742
- []
5743
- ).option(
5744
- "--where <expression>",
5745
- 'condition "<field> <op> [value]" (repeatable, combined with AND)',
5746
- collectWhereExpressions,
5747
- []
5748
- ).option(
5749
- "--where-json <json>",
5750
- 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
5751
- ).option(
5752
- "--search <term>",
5753
- "free-text search term (matched across the schema's searchable fields)"
5754
- ).option(
5755
- "--sort <alias|field[:direction]>",
5756
- "sort groups by a metric alias or group-by field, asc|desc (repeatable, up to 4)",
5757
- collectAggregateSort,
5758
- []
5759
- ).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) {
5760
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5761
- const input = buildRecordAggregateInput(commandOptions);
5762
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5763
- const data = await api.aggregateRecords(resolvedSchema, input);
5764
- const groups = Array.isArray(data.groups) ? data.groups : [];
5765
- if (json) {
5766
- emitJson(
5767
- stdout,
5768
- "records aggregate",
5769
- groups,
5770
- filePath,
5771
- data.meta ? { aggregate: data.meta } : {}
5735
+ const { api, json, readOnly } = createFormulasApi(command, configPath);
5736
+ ensureWritable(commandName, readOnly, "write");
5737
+ if (requireConfirmation) {
5738
+ ensureConfirmed(commandName, confirmed);
5739
+ }
5740
+ const result = await api.recompute(input);
5741
+ emitResult(stdout, commandName, result, configPath, json);
5742
+ }
5743
+ function registerFormulasCommands(program, options = {}) {
5744
+ const formulas = program.command("formulas").description("Recalculate formula values");
5745
+ const recomputeCommand = formulas.command("recompute").description("Queue a full formula recalculation");
5746
+ recomputeCommand.command("field").description("Queue recalculation of one formula column").argument("<schema>", "schema UUID or slug", parseUuidOrSlugSelector).argument("<field>", "formula field UUID or slug", parseUuidOrSlugSelector).action(
5747
+ async function action(schema, field) {
5748
+ await recompute(
5749
+ this,
5750
+ "formulas recompute field",
5751
+ { scope: "FIELD", schema, field },
5752
+ options,
5753
+ false
5772
5754
  );
5773
- return;
5774
5755
  }
5775
- emitTable(stdout, toAggregateTableRows(groups));
5776
- if (data.meta?.truncated) {
5777
- writeLine(
5778
- stdout,
5779
- `Showing ${data.meta.count} of ${data.meta.total} groups; raise --limit (max 1000) or narrow the filters to see the rest.`
5756
+ );
5757
+ recomputeCommand.command("schema").description("Queue recalculation of all active formulas in one schema").argument("<schema>", "schema UUID or slug", parseUuidOrSlugSelector).option("--yes", "confirm the potentially expensive recalculation").action(
5758
+ async function action(schema, commandOptions) {
5759
+ await recompute(
5760
+ this,
5761
+ "formulas recompute schema",
5762
+ { scope: "SCHEMA", schema },
5763
+ options,
5764
+ true,
5765
+ commandOptions.yes
5780
5766
  );
5781
5767
  }
5768
+ );
5769
+ recomputeCommand.command("workspace").description("Queue recalculation of all active formulas in the workspace").option("--yes", "confirm the potentially expensive recalculation").action(async function action(commandOptions) {
5770
+ await recompute(
5771
+ this,
5772
+ "formulas recompute workspace",
5773
+ { scope: "WORKSPACE" },
5774
+ options,
5775
+ true,
5776
+ commandOptions.yes
5777
+ );
5782
5778
  });
5783
- 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) {
5784
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5785
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5786
- const data = await api.getRecord(resolvedSchema, record);
5779
+ }
5780
+
5781
+ // src/api/logs.ts
5782
+ var LogsApi = class {
5783
+ constructor(client) {
5784
+ this.client = client;
5785
+ }
5786
+ listLogs(schema, recordId) {
5787
+ return this.client.getJson(
5788
+ `/api/v2/schemas/${schema.value}/records/${recordId}/logs`
5789
+ );
5790
+ }
5791
+ };
5792
+
5793
+ // src/commands/logs.ts
5794
+ function createLogsApi(command, filePath) {
5795
+ const { client, ...runtime } = createCommandContext(command, filePath);
5796
+ return {
5797
+ api: new LogsApi(client),
5798
+ ...runtime
5799
+ };
5800
+ }
5801
+ function registerLogsCommands(program, options = {}) {
5802
+ const filePath = options.configPath ?? defaultConfigPath;
5803
+ const stdout = options.stdout ?? process.stdout;
5804
+ const logs = program.command("logs").description("Inspect record change logs");
5805
+ logs.command("list").description("List change logs for a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, record) {
5806
+ const { api, json } = createLogsApi(this, filePath);
5807
+ const data = await api.listLogs(schema, record.value);
5787
5808
  if (json) {
5788
- emitJson(stdout, "records get", data, filePath);
5809
+ emitJson(stdout, "logs list", data);
5789
5810
  return;
5790
5811
  }
5791
5812
  emitTable(stdout, data);
5792
5813
  });
5793
- records.command("create").description("Create one or more records").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
5794
- "--set <field=value>",
5795
- "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
5796
- collectKeyValueAssignments,
5797
- []
5798
- ).option("--set-json <field=json>", "set a structured field", collectJsonAssignments, []).option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").option(
5799
- "--records-file <path>",
5800
- "path to a JSON array of record objects (mutually exclusive with --set/--set-json/--raw/--raw-file)"
5801
- ).action(async function action(schema, commandOptions) {
5802
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5803
- ensureWritable("records create", readOnly, "write");
5804
- const records2 = buildCreateRecords(commandOptions);
5805
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5806
- const data = await api.createRecords(resolvedSchema, records2);
5807
- if (json) {
5808
- emitJson(stdout, "records create", data, filePath);
5809
- return;
5810
- }
5811
- writeLine(stdout, `Created ${data.created.length} record(s) in schema "${schema.value}".`);
5812
- if (data.errors.length > 0) {
5813
- writeLine(stdout, `${data.errors.length} record(s) rejected:`);
5814
- for (const error of data.errors) {
5815
- writeLine(stdout, ` - index ${error.index}: ${error.message}`);
5816
- }
5817
- }
5818
- });
5819
- records.command("update").description("Update a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector).option(
5820
- "--set <field=value>",
5821
- "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
5822
- collectKeyValueAssignments,
5823
- []
5824
- ).option("--set-json <field=json>", "set a structured field", collectJsonAssignments, []).option("--unset <field>", "unset a field", collectStringValues, []).option("--raw <json>", "raw JSON object of fields to set").option("--raw-file <path>", "path to a JSON object of fields to set").action(async function action(schema, record, commandOptions) {
5825
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5826
- ensureWritable("records update", readOnly, "write");
5827
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5828
- const data = await api.updateRecord(
5829
- resolvedSchema,
5830
- record,
5831
- buildRecordUpdateInput(commandOptions)
5832
- );
5814
+ }
5815
+
5816
+ // src/api/members.ts
5817
+ var MembersApi = class {
5818
+ constructor(client) {
5819
+ this.client = client;
5820
+ }
5821
+ listMembers() {
5822
+ return this.client.getJson("/api/v2/members");
5823
+ }
5824
+ };
5825
+
5826
+ // src/commands/members.ts
5827
+ function createMembersApi(command, filePath) {
5828
+ const { client, ...runtime } = createCommandContext(command, filePath);
5829
+ return {
5830
+ api: new MembersApi(client),
5831
+ ...runtime
5832
+ };
5833
+ }
5834
+ function registerMembersCommands(program, options = {}) {
5835
+ const filePath = options.configPath ?? defaultConfigPath;
5836
+ const stdout = options.stdout ?? process.stdout;
5837
+ const members = program.command("members").description("Inspect workspace members");
5838
+ members.command("list").description(
5839
+ "List the active members of the workspace (email to write in member fields, alias, currentUser)"
5840
+ ).action(async function action() {
5841
+ const { api, json } = createMembersApi(this, filePath);
5842
+ const data = await api.listMembers();
5833
5843
  if (json) {
5834
- emitJson(stdout, "records update", data, filePath);
5844
+ emitJson(stdout, "members list", data);
5835
5845
  return;
5836
5846
  }
5837
- writeLine(stdout, `Updated record "${getRecordIdentifier(data)}".`);
5847
+ emitTable(stdout, data);
5838
5848
  });
5839
- records.command("delete").description("Delete one or more records").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--record <uuid>", "record uuid to delete (repeatable)", collectRecordIds, []).option(
5840
- "--records-file <path>",
5841
- "path to a file with one record uuid per line (merged with --record)"
5842
- ).action(async function action(schema, commandOptions) {
5843
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5844
- ensureWritable("records delete", readOnly, "destructive");
5845
- const recordIds = resolveDeleteRecordIds(commandOptions);
5846
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5847
- const data = await api.deleteRecords(resolvedSchema, recordIds);
5849
+ }
5850
+
5851
+ // src/commands/navigation.ts
5852
+ import { readFileSync as readFileSync4 } from "fs";
5853
+
5854
+ // src/api/navigation.ts
5855
+ function jsonOptions8(body, method) {
5856
+ return {
5857
+ method,
5858
+ headers: {
5859
+ "content-type": "application/json"
5860
+ },
5861
+ body: JSON.stringify(body)
5862
+ };
5863
+ }
5864
+ var NavigationApi = class {
5865
+ constructor(client) {
5866
+ this.client = client;
5867
+ }
5868
+ listFolders() {
5869
+ return this.client.getJson("/api/v2/navigation/folders");
5870
+ }
5871
+ createFolder(body) {
5872
+ return this.client.requestJson(
5873
+ "/api/v2/navigation/folders",
5874
+ jsonOptions8(body, "POST")
5875
+ );
5876
+ }
5877
+ updateFolder(folder, body) {
5878
+ return this.client.requestJson(
5879
+ `/api/v2/navigation/folders/${folder.value}`,
5880
+ jsonOptions8(body, "PATCH")
5881
+ );
5882
+ }
5883
+ deleteFolder(folder) {
5884
+ return this.client.requestJson(
5885
+ `/api/v2/navigation/folders/${folder.value}`,
5886
+ { method: "DELETE" }
5887
+ );
5888
+ }
5889
+ moveResource(body) {
5890
+ return this.client.requestJson(
5891
+ "/api/v2/navigation/resources:move",
5892
+ jsonOptions8(body, "POST")
5893
+ );
5894
+ }
5895
+ };
5896
+
5897
+ // src/commands/navigation.ts
5898
+ function createNavigationApi(command, filePath) {
5899
+ const { client, ...runtime } = createCommandContext(command, filePath);
5900
+ return {
5901
+ api: new NavigationApi(client),
5902
+ ...runtime
5903
+ };
5904
+ }
5905
+ function parseInteger(value, flagName) {
5906
+ if (value === void 0) {
5907
+ return void 0;
5908
+ }
5909
+ const parsed = Number.parseInt(value, 10);
5910
+ if (Number.isNaN(parsed)) {
5911
+ throw new CliError("invalid_cli_usage", `${flagName} must be an integer.`);
5912
+ }
5913
+ return parsed;
5914
+ }
5915
+ function readJsonObject(raw, rawFile) {
5916
+ if (raw && rawFile) {
5917
+ throw new CliError("invalid_cli_usage", 'Use either "--props" or "--props-file", not both.');
5918
+ }
5919
+ const source = rawFile ? readFileSync4(rawFile, "utf8") : raw;
5920
+ if (!source) {
5921
+ return {};
5922
+ }
5923
+ try {
5924
+ const parsed = JSON.parse(source);
5925
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
5926
+ throw new CliError("invalid_cli_usage", "Props payload must be a JSON object.");
5927
+ }
5928
+ return parsed;
5929
+ } catch (error) {
5930
+ if (error instanceof CliError) {
5931
+ throw error;
5932
+ }
5933
+ throw new CliError("invalid_cli_usage", "Props payload is invalid JSON.");
5934
+ }
5935
+ }
5936
+ function buildFolderBody(options) {
5937
+ const body = {};
5938
+ if (options.name !== void 0) {
5939
+ body.name = options.name;
5940
+ }
5941
+ const order = parseInteger(options.order, "--order");
5942
+ if (order !== void 0) {
5943
+ body.order = order;
5944
+ }
5945
+ const props = readJsonObject(options.props, options.propsFile);
5946
+ if (Object.keys(props).length > 0) {
5947
+ body.additionalProperties = props;
5948
+ }
5949
+ return body;
5950
+ }
5951
+ function resolveFolder2(folders, selector) {
5952
+ if (selector.kind === "uuid") {
5953
+ const match = folders.find((folder) => folder.id === selector.value);
5954
+ if (!match) {
5955
+ throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
5956
+ }
5957
+ return match;
5958
+ }
5959
+ const matches = folders.filter((folder) => folder.name === selector.value);
5960
+ if (matches.length === 1) {
5961
+ return matches[0];
5962
+ }
5963
+ if (matches.length > 1) {
5964
+ throw new CliError(
5965
+ "invalid_cli_usage",
5966
+ `Folder "${selector.value}" is ambiguous. Found ${matches.length} matches.`
5967
+ );
5968
+ }
5969
+ throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
5970
+ }
5971
+ function folderRows2(folders) {
5972
+ return folders.map((folder) => ({
5973
+ id: folder.id,
5974
+ order: folder.order ?? "",
5975
+ name: folder.name ?? "",
5976
+ resourceCount: Array.isArray(folder.resources) ? folder.resources.length : ""
5977
+ }));
5978
+ }
5979
+ function registerNavigationCommands(program, options = {}) {
5980
+ const filePath = options.configPath ?? defaultConfigPath;
5981
+ const stdout = options.stdout ?? process.stdout;
5982
+ const navigation = program.command("navigation").description("Manage workspace navigation");
5983
+ const folders = navigation.command("folders").description("Manage navigation folders");
5984
+ folders.command("list").description("List navigation folders").action(async function action() {
5985
+ const { api, json } = createNavigationApi(this, filePath);
5986
+ const data = await api.listFolders();
5848
5987
  if (json) {
5849
- emitJson(stdout, "records delete", data, filePath);
5988
+ emitJson(stdout, "navigation folders list", data, filePath);
5850
5989
  return;
5851
5990
  }
5852
- writeLine(
5853
- stdout,
5854
- `Deleted ${recordIds.length} record(s) from schema "${schema.value}".`
5855
- );
5991
+ printTable(folderRows2(data), ["id", "order", "name", "resourceCount"], stdout);
5856
5992
  });
5857
- records.command("clear").description("Delete all records from a schema's table").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
5858
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5859
- ensureWritable("records clear", readOnly, "destructive");
5860
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5861
- const data = await api.clearRecords(resolvedSchema);
5993
+ folders.command("get").description("Get a navigation folder by UUID or exact name").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector).action(async function action(folder) {
5994
+ const { api, json } = createNavigationApi(this, filePath);
5995
+ const data = await api.listFolders();
5996
+ const resolved = resolveFolder2(data, folder);
5862
5997
  if (json) {
5863
- emitJson(stdout, "records clear", data, filePath);
5998
+ emitJson(stdout, "navigation folders get", resolved, filePath);
5864
5999
  return;
5865
6000
  }
5866
- writeLine(stdout, `Cleared all records from schema "${schema.value}".`);
6001
+ printTable(folderRows2([resolved]), ["id", "order", "name", "resourceCount"], stdout);
6002
+ });
6003
+ folders.command("create").description("Create a navigation folder").requiredOption("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(commandOptions) {
6004
+ const { api, json, readOnly } = createNavigationApi(this, filePath);
6005
+ ensureWritable("navigation folders create", readOnly, "write");
6006
+ const data = await api.createFolder(buildFolderBody(commandOptions));
6007
+ if (json) {
6008
+ emitJson(stdout, "navigation folders create", data, filePath);
6009
+ return;
6010
+ }
6011
+ writeLine(stdout, `Created navigation folder "${String(data.name ?? commandOptions.name)}".`);
6012
+ });
6013
+ folders.command("update").description("Update a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector).option("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(folder, commandOptions) {
6014
+ const { api, json, readOnly } = createNavigationApi(this, filePath);
6015
+ ensureWritable("navigation folders update", readOnly, "write");
6016
+ const allFolders = await api.listFolders();
6017
+ const resolved = resolveFolder2(allFolders, folder);
6018
+ const body = buildFolderBody(commandOptions);
6019
+ if (Object.keys(body).length === 0) {
6020
+ throw new CliError("invalid_cli_usage", "Nothing to update.");
6021
+ }
6022
+ const data = await api.updateFolder({ kind: "uuid", value: resolved.id }, body);
6023
+ if (json) {
6024
+ emitJson(stdout, "navigation folders update", data, filePath);
6025
+ return;
6026
+ }
6027
+ writeLine(stdout, `Updated navigation folder "${String(data.name ?? resolved.name ?? resolved.id)}".`);
6028
+ });
6029
+ folders.command("delete").description("Delete a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector).action(async function action(folder) {
6030
+ const { api, json, readOnly } = createNavigationApi(this, filePath);
6031
+ ensureWritable("navigation folders delete", readOnly, "destructive");
6032
+ const allFolders = await api.listFolders();
6033
+ const resolved = resolveFolder2(allFolders, folder);
6034
+ const data = await api.deleteFolder({ kind: "uuid", value: resolved.id });
6035
+ if (json) {
6036
+ emitJson(stdout, "navigation folders delete", data, filePath);
6037
+ return;
6038
+ }
6039
+ writeLine(stdout, `Deleted navigation folder "${resolved.name ?? resolved.id}".`);
6040
+ });
6041
+ navigation.command("resources").description("Manage navigation resources").command("move").description(
6042
+ "Move a schema into a navigation folder. Only schemas can be moved (the navigation menu holds databases); schedules and sub-schemas follow their parent schema. Use `--to root` to move it back to the workspace root: the root folder is named `root`, and its UUID differs per workspace."
6043
+ ).argument("<resource>", "schema UUID").requiredOption("--to <folder>", "target folder UUID or exact name").action(async function action(resourceId, commandOptions) {
6044
+ const { api, json, readOnly } = createNavigationApi(this, filePath);
6045
+ ensureWritable("navigation resources move", readOnly, "write");
6046
+ const allFolders = await api.listFolders();
6047
+ const resolved = resolveFolder2(allFolders, parseUuidOrSlugSelector(commandOptions.to));
6048
+ const data = await api.moveResource({
6049
+ resourceId,
6050
+ targetFolderId: resolved.id
6051
+ });
6052
+ if (json) {
6053
+ emitJson(stdout, "navigation resources move", data, filePath);
6054
+ return;
6055
+ }
6056
+ writeLine(stdout, `Moved resource "${resourceId}" to "${resolved.name ?? resolved.id}".`);
5867
6057
  });
5868
6058
  }
5869
6059
 
5870
- // src/commands/schemas.ts
5871
- import { InvalidArgumentError as InvalidArgumentError4 } from "commander";
5872
- var HIGHLIGHTED_FIELD_HELP = `
5873
- Highlighted field:
5874
- The schema's "main" field. The frontend uses its value as each record's
5875
- display name, in two places:
5876
- - Activity panel: the record's title in the activity side panel
5877
- (the panel with the record's logs and comments).
5878
- - Detail view: the record's name in the left-hand record list you
5879
- browse to open each record's form.
5880
- `;
5881
- function createSchemasApi(command, filePath) {
5882
- const { client, ...runtime } = createCommandContext(command, filePath);
6060
+ // src/commands/profiles.ts
6061
+ function readRequiredConfig(filePath) {
6062
+ const config = readConfigIfExists(filePath);
6063
+ if (config) {
6064
+ return config;
6065
+ }
6066
+ throw new CliError("configuration_error", `Config file not found at ${filePath}.`);
6067
+ }
6068
+ function getRequiredProfile(config, profileName) {
6069
+ const profile = config.profiles[profileName];
6070
+ if (profile) {
6071
+ return profile;
6072
+ }
6073
+ throw new CliError("configuration_error", `Profile "${profileName}" not found in config.`);
6074
+ }
6075
+ function toDisplayProfile(profileName, profile, defaultProfile) {
5883
6076
  return {
5884
- api: new SchemasApi(client),
5885
- ...runtime
6077
+ name: profileName,
6078
+ isDefault: defaultProfile === profileName,
6079
+ ...redactProfile(profile)
5886
6080
  };
5887
6081
  }
5888
- function collectFieldSelectors(value, previous = []) {
5889
- return [...previous, parseUuidOrSlugSelector(value)];
6082
+ function loadConfigForAdd(filePath) {
6083
+ return readConfigIfExists(filePath) ?? { profiles: {} };
5890
6084
  }
5891
- function parseBooleanFlag(input) {
5892
- const normalized = input.trim().toLowerCase();
5893
- if (["true", "1", "yes", "y", "on"].includes(normalized)) {
5894
- return true;
5895
- }
5896
- if (["false", "0", "no", "n", "off"].includes(normalized)) {
5897
- return false;
6085
+ function normalizeProfileBaseUrl(baseUrl) {
6086
+ if (baseUrl === void 0) {
6087
+ return void 0;
6088
+ }
6089
+ try {
6090
+ return validateBaseUrl(baseUrl, '"--base-url"');
6091
+ } catch (error) {
6092
+ if (error instanceof ProfileResolutionError) {
6093
+ throw new CliError("configuration_error", error.message);
6094
+ }
6095
+ throw error;
5898
6096
  }
5899
- throw new InvalidArgumentError4(`Expected a boolean value, received "${input}".`);
5900
6097
  }
5901
- function emitSchemasTable(stdout, schemas) {
6098
+ function emitProfilesTable(stdout, data) {
5902
6099
  printTable(
5903
- schemas.map((schema) => ({
5904
- id: schema.id ?? "",
5905
- name: schema.name ?? "",
5906
- slug: schema.slug ?? "",
5907
- auditable: schema.auditable ?? "",
5908
- commentable: schema.commentable ?? "",
5909
- ...folderColumns(schema.folder)
6100
+ data.map((profile) => ({
6101
+ name: profile.name,
6102
+ default: profile.isDefault ? "yes" : "",
6103
+ baseUrl: profile.baseUrl ?? "",
6104
+ credential: describeProfileCredential(profile)
5910
6105
  })),
5911
- ["id", "name", "slug", "auditable", "commentable", ...FOLDER_TABLE_KEYS],
6106
+ ["name", "default", "baseUrl", "credential"],
5912
6107
  stdout
5913
6108
  );
5914
6109
  }
5915
- function emitFieldsTable(stdout, fields) {
5916
- printTable(
5917
- fields.map((field) => ({
5918
- id: field.id ?? "",
5919
- type: field.type ?? "",
5920
- slug: field.slug ?? "",
5921
- label: field.label ?? "",
5922
- required: field.required ?? ""
5923
- })),
5924
- ["id", "type", "slug", "label", "required"],
5925
- stdout
5926
- );
6110
+ function registerProfilesCommands(program, options = {}) {
6111
+ const filePath = options.configPath ?? defaultConfigPath;
6112
+ const stdout = options.stdout ?? process.stdout;
6113
+ const profiles = program.command("profiles").description("Manage local CLI profiles");
6114
+ profiles.command("list").description("List configured profiles").action(function action() {
6115
+ const config = readRequiredConfig(filePath);
6116
+ const data = Object.entries(config.profiles).map(
6117
+ ([name, profile]) => toDisplayProfile(name, profile, config.defaultProfile)
6118
+ );
6119
+ if (this.optsWithGlobals().json) {
6120
+ emitJson(stdout, "profiles list", data, filePath);
6121
+ return;
6122
+ }
6123
+ emitProfilesTable(stdout, data);
6124
+ });
6125
+ profiles.command("get").description("Show a single configured profile").argument("<profile>", "profile name").action(function action(profileName) {
6126
+ const config = readRequiredConfig(filePath);
6127
+ const profile = getRequiredProfile(config, profileName);
6128
+ const data = toDisplayProfile(profileName, profile, config.defaultProfile);
6129
+ if (this.optsWithGlobals().json) {
6130
+ emitJson(stdout, "profiles get", data, filePath);
6131
+ return;
6132
+ }
6133
+ emitProfilesTable(stdout, [data]);
6134
+ });
6135
+ profiles.command("use").description("Set the default profile").argument("<profile>", "profile name").action(function action(profileName) {
6136
+ const config = readRequiredConfig(filePath);
6137
+ getRequiredProfile(config, profileName);
6138
+ const nextConfig = setDefaultProfile(config, profileName);
6139
+ writeConfig(nextConfig, filePath);
6140
+ const data = {
6141
+ profile: profileName,
6142
+ defaultProfile: nextConfig.defaultProfile
6143
+ };
6144
+ if (this.optsWithGlobals().json) {
6145
+ emitJson(stdout, "profiles use", data, filePath);
6146
+ return;
6147
+ }
6148
+ writeLine(stdout, `Using profile "${profileName}".`);
6149
+ });
6150
+ profiles.command("add").description("Add a profile to the local config").argument("<profile>", "profile name").requiredOption("--api-key <token>", "API key").option("--base-url <url>", "base URL").action(function action(profileName, commandOptions) {
6151
+ const config = loadConfigForAdd(filePath);
6152
+ if (config.profiles[profileName]) {
6153
+ throw new CliError(
6154
+ "configuration_error",
6155
+ `Profile "${profileName}" already exists in config.`
6156
+ );
6157
+ }
6158
+ const baseUrl = normalizeProfileBaseUrl(commandOptions.baseUrl);
6159
+ let nextConfig = setProfileConfig(config, profileName, {
6160
+ apiKey: commandOptions.apiKey,
6161
+ baseUrl
6162
+ });
6163
+ if (!nextConfig.defaultProfile) {
6164
+ nextConfig = setDefaultProfile(nextConfig, profileName);
6165
+ }
6166
+ writeConfig(nextConfig, filePath);
6167
+ const data = toDisplayProfile(
6168
+ profileName,
6169
+ nextConfig.profiles[profileName] ?? {},
6170
+ nextConfig.defaultProfile
6171
+ );
6172
+ if (this.optsWithGlobals().json) {
6173
+ emitJson(stdout, "profiles add", data, filePath);
6174
+ return;
6175
+ }
6176
+ writeLine(stdout, `Added profile "${profileName}".`);
6177
+ });
6178
+ profiles.command("update").description("Update an existing profile").argument("<profile>", "profile name").option("--api-key <token>", "API key").option("--base-url <url>", "base URL").action(function action(profileName, commandOptions) {
6179
+ if (commandOptions.apiKey === void 0 && commandOptions.baseUrl === void 0) {
6180
+ throw new CliError(
6181
+ "configuration_error",
6182
+ 'Provide at least one of "--api-key" or "--base-url".'
6183
+ );
6184
+ }
6185
+ const config = readRequiredConfig(filePath);
6186
+ const profile = getRequiredProfile(config, profileName);
6187
+ if (isSessionProfile(profile)) {
6188
+ throw new CliError(
6189
+ "configuration_error",
6190
+ `Profile "${profileName}" is a session profile. Run \`zinkee login --profile ${profileName}\` to renew its session, adding --backend-url and --base-url to change its environment.`
6191
+ );
6192
+ }
6193
+ const baseUrl = normalizeProfileBaseUrl(commandOptions.baseUrl);
6194
+ const nextConfig = setProfileConfig(config, profileName, {
6195
+ apiKey: commandOptions.apiKey,
6196
+ baseUrl
6197
+ });
6198
+ writeConfig(nextConfig, filePath);
6199
+ const data = toDisplayProfile(
6200
+ profileName,
6201
+ nextConfig.profiles[profileName] ?? {},
6202
+ nextConfig.defaultProfile
6203
+ );
6204
+ if (this.optsWithGlobals().json) {
6205
+ emitJson(stdout, "profiles update", data, filePath);
6206
+ return;
6207
+ }
6208
+ writeLine(stdout, `Updated profile "${profileName}".`);
6209
+ });
6210
+ profiles.command("remove").description("Remove a profile from the local config").argument("<profile>", "profile name").action(function action(profileName) {
6211
+ const config = readRequiredConfig(filePath);
6212
+ getRequiredProfile(config, profileName);
6213
+ const nextConfig = removeProfileConfig(config, profileName);
6214
+ writeConfig(nextConfig, filePath);
6215
+ const data = {
6216
+ profile: profileName,
6217
+ defaultProfile: nextConfig.defaultProfile
6218
+ };
6219
+ if (this.optsWithGlobals().json) {
6220
+ emitJson(stdout, "profiles remove", data, filePath);
6221
+ return;
6222
+ }
6223
+ writeLine(stdout, `Removed profile "${profileName}".`);
6224
+ });
5927
6225
  }
5928
- function buildSchemaUpdateInput(options) {
5929
- const input = {};
5930
- if (options.name !== void 0) {
5931
- input.name = options.name;
6226
+
6227
+ // src/commands/records.ts
6228
+ import { readFileSync as readFileSync5 } from "fs";
6229
+ import { InvalidArgumentError as InvalidArgumentError5 } from "commander";
6230
+ var AGGREGATE_BUCKETS = ["day", "week", "month", "quarter", "year"];
6231
+ var AGGREGATE_HELP = `
6232
+ Group by (--group-by <field>[:<bucket>], up to 3):
6233
+ A field slug; date fields take a bucket: day, week, month, quarter or year
6234
+ (a date field without bucket groups by day). Each group key comes back as
6235
+ {value, label}; records with an empty value fall into one group with
6236
+ value/label null. A reference key's value is the target record id: reuse
6237
+ it in --where "<field> eq <value>" to list the records of that group.
6238
+
6239
+ Metrics (--metric [<alias>=]<op>[:<field>], up to 10, default "count"):
6240
+ count number of records
6241
+ count:<field> records where <field> is not null (same rule as a
6242
+ panel COUNT; options skip -1)
6243
+ count_distinct:<field>, sum:<field>, avg:<field>, min:<field>, max:<field>
6244
+ The alias defaults to "count" for a bare count and to <op>_<field>
6245
+ otherwise (e.g. sum_amount). avg/min/max are null when no record has a
6246
+ value; min/max on dates return an ISO-8601 UTC instant.
6247
+
6248
+ Sort (--sort <alias|field>[:asc|desc], up to 4):
6249
+ By a metric alias or a group-by field. Default: group keys ascending.
6250
+
6251
+ --limit caps the groups returned (default 100, max 1000); meta.aggregate
6252
+ reports count, total and truncated. Date buckets use --timezone, or the
6253
+ workspace timezone when omitted. --where/--where-json/--search filter the
6254
+ records first, exactly as in "records query".
6255
+ `;
6256
+ function createRecordsApi(command, filePath) {
6257
+ const { client, ...runtime } = createCommandContext(command, filePath);
6258
+ return {
6259
+ api: new RecordsApi(client),
6260
+ schemasApi: new SchemasApi(client),
6261
+ ...runtime
6262
+ };
6263
+ }
6264
+ function parseCommaSeparatedValues(input, label) {
6265
+ const values = input.split(",").map((value) => value.trim()).filter(Boolean);
6266
+ if (values.length === 0) {
6267
+ throw new InvalidArgumentError5(`Expected ${label} to contain at least one value.`);
6268
+ }
6269
+ return values;
6270
+ }
6271
+ function parseExpressionValue(input) {
6272
+ try {
6273
+ return parseExpression(input);
6274
+ } catch (error) {
6275
+ const message = error instanceof Error ? error.message : "Invalid expression.";
6276
+ throw new InvalidArgumentError5(message);
6277
+ }
6278
+ }
6279
+ function parseKeyValueAssignment(input) {
6280
+ try {
6281
+ return parseKeyValue(input);
6282
+ } catch (error) {
6283
+ const message = error instanceof Error ? error.message : "Invalid assignment.";
6284
+ throw new InvalidArgumentError5(message);
6285
+ }
6286
+ }
6287
+ function parseJsonKeyValueAssignment(input) {
6288
+ try {
6289
+ return parseJsonAssignment(input);
6290
+ } catch (error) {
6291
+ const message = error instanceof Error ? error.message : "Invalid JSON assignment.";
6292
+ throw new InvalidArgumentError5(message);
6293
+ }
6294
+ }
6295
+ function dedupeStrings(values) {
6296
+ return [...new Set(values)];
6297
+ }
6298
+ function toRecordUuid(value) {
6299
+ try {
6300
+ const normalized = normalizeUuidOrSlug(value);
6301
+ return normalized.kind === "uuid" ? normalized.value : null;
6302
+ } catch {
6303
+ return null;
6304
+ }
6305
+ }
6306
+ function collectRecordIds(value, previous = []) {
6307
+ const uuid = toRecordUuid(value.trim());
6308
+ if (!uuid) {
6309
+ throw new InvalidArgumentError5(`Expected a record UUID, received "${value}".`);
6310
+ }
6311
+ return [...previous, uuid];
6312
+ }
6313
+ function readRecordIdsFromFile(path) {
6314
+ let contents;
6315
+ try {
6316
+ contents = readFileSync5(path, "utf8");
6317
+ } catch (error) {
6318
+ const message = error instanceof Error ? error.message : "Unable to read file.";
6319
+ throw new CliError(
6320
+ "invalid_cli_usage",
6321
+ `Failed to read record ids from ${path}: ${message}`
6322
+ );
6323
+ }
6324
+ const ids = [];
6325
+ contents.split(/\r?\n/).forEach((line, index) => {
6326
+ const value = line.trim();
6327
+ if (!value) {
6328
+ return;
6329
+ }
6330
+ const uuid = toRecordUuid(value);
6331
+ if (!uuid) {
6332
+ throw new CliError(
6333
+ "invalid_cli_usage",
6334
+ `Invalid record UUID "${value}" at ${path}:${index + 1}.`
6335
+ );
6336
+ }
6337
+ ids.push(uuid);
6338
+ });
6339
+ return ids;
6340
+ }
6341
+ function resolveDeleteRecordIds(options) {
6342
+ const flagIds = options.record ?? [];
6343
+ const fileIds = options.recordsFile ? readRecordIdsFromFile(options.recordsFile) : [];
6344
+ const recordIds = dedupeStrings([...flagIds, ...fileIds]);
6345
+ if (recordIds.length === 0) {
6346
+ throw new CliError(
6347
+ "invalid_cli_usage",
6348
+ 'Provide at least one record id via "--record <uuid>" (repeatable) or "--records-file <path>".'
6349
+ );
6350
+ }
6351
+ return recordIds;
6352
+ }
6353
+ function collectStringValues(value, previous = []) {
6354
+ return [...previous, value];
6355
+ }
6356
+ function buildSearch(options) {
6357
+ const search = { term: options.search ?? "" };
6358
+ if (options.searchFields && options.searchFields.length > 0) {
6359
+ search.fields = [...options.searchFields];
6360
+ }
6361
+ if (options.searchTimezone !== void 0) {
6362
+ search.timezone = options.searchTimezone;
6363
+ }
6364
+ return search;
6365
+ }
6366
+ function collectSelectValues(value, previous = []) {
6367
+ return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--select")]);
6368
+ }
6369
+ function collectSortValues(value, previous = []) {
6370
+ return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--sort")]);
6371
+ }
6372
+ function collectWhereExpressions(value, previous = []) {
6373
+ return [...previous, parseExpressionValue(value)];
6374
+ }
6375
+ function splitKnownSuffix(input, suffixes) {
6376
+ const index = input.lastIndexOf(":");
6377
+ if (index !== -1) {
6378
+ const suffix = input.slice(index + 1).trim().toLowerCase();
6379
+ if (suffixes.includes(suffix)) {
6380
+ return { head: input.slice(0, index).trim(), suffix };
6381
+ }
6382
+ }
6383
+ return { head: input.trim() };
6384
+ }
6385
+ function parseGroupBy(input) {
6386
+ const { head, suffix } = splitKnownSuffix(input, AGGREGATE_BUCKETS);
6387
+ if (!head) {
6388
+ throw new CliError(
6389
+ "invalid_cli_usage",
6390
+ `Invalid --group-by "${input}": expected <field>[:<bucket>] with bucket one of ${AGGREGATE_BUCKETS.join(", ")}.`
6391
+ );
6392
+ }
6393
+ return suffix ? { field: head, bucket: suffix } : { field: head };
6394
+ }
6395
+ function parseMetric(input) {
6396
+ const usage2 = `Invalid --metric "${input}": expected [<alias>=]<op>[:<field>], e.g. "count", "total=sum:amount" or "count_distinct:customer".`;
6397
+ const aliasIndex = input.lastIndexOf("=");
6398
+ const alias = aliasIndex === -1 ? void 0 : input.slice(0, aliasIndex).trim();
6399
+ const expression = input.slice(aliasIndex + 1);
6400
+ const fieldIndex = expression.indexOf(":");
6401
+ const op = (fieldIndex === -1 ? expression : expression.slice(0, fieldIndex)).trim();
6402
+ const field = fieldIndex === -1 ? void 0 : expression.slice(fieldIndex + 1).trim();
6403
+ if (alias === "" || !/^[A-Za-z_]+$/.test(op) || field === "") {
6404
+ throw new CliError("invalid_cli_usage", usage2);
6405
+ }
6406
+ return {
6407
+ op,
6408
+ ...field !== void 0 ? { field } : {},
6409
+ ...alias !== void 0 ? { as: alias } : {}
6410
+ };
6411
+ }
6412
+ function parseAggregateSort(input) {
6413
+ const { head, suffix } = splitKnownSuffix(input, ["asc", "desc"]);
6414
+ if (!head) {
6415
+ throw new CliError(
6416
+ "invalid_cli_usage",
6417
+ `Invalid --sort "${input}": expected <alias|field>[:asc|desc].`
6418
+ );
6419
+ }
6420
+ return { by: head, direction: (suffix ?? "asc").toUpperCase() };
6421
+ }
6422
+ function parseGroupLimit(input) {
6423
+ const limit = /^\d+$/.test(input.trim()) ? Number(input) : Number.NaN;
6424
+ if (!(limit >= 1 && limit <= 1e3)) {
6425
+ throw new CliError(
6426
+ "invalid_cli_usage",
6427
+ `Invalid --limit "${input}": expected a number of groups from 1 to 1000.`
6428
+ );
6429
+ }
6430
+ return limit;
6431
+ }
6432
+ function collectGroupBy(value, previous = []) {
6433
+ return [...previous, parseGroupBy(value)];
6434
+ }
6435
+ function collectMetrics(value, previous = []) {
6436
+ return [...previous, parseMetric(value)];
6437
+ }
6438
+ function collectAggregateSort(value, previous = []) {
6439
+ return [...previous, parseAggregateSort(value)];
6440
+ }
6441
+ function collectKeyValueAssignments(value, previous = []) {
6442
+ return [...previous, parseKeyValueAssignment(value)];
6443
+ }
6444
+ function collectJsonAssignments(value, previous = []) {
6445
+ return [...previous, parseJsonKeyValueAssignment(value)];
6446
+ }
6447
+ function buildAssignmentObject(assignments = [], jsonAssignments = []) {
6448
+ const output = {};
6449
+ for (const assignment of assignments) {
6450
+ output[assignment.key] = assignment.value;
6451
+ }
6452
+ for (const assignment of jsonAssignments) {
6453
+ output[assignment.key] = assignment.value;
6454
+ }
6455
+ return output;
6456
+ }
6457
+ function toQueryExpressions(expressions) {
6458
+ if (!expressions || expressions.length === 0) {
6459
+ return void 0;
6460
+ }
6461
+ return expressions.map((expression) => ({
6462
+ field: expression.field,
6463
+ comparator: expression.comparator,
6464
+ value: expression.value
6465
+ }));
6466
+ }
6467
+ function parseWhereJson(input) {
6468
+ let parsed;
6469
+ try {
6470
+ parsed = JSON.parse(input);
6471
+ } catch (error) {
6472
+ const message = error instanceof Error ? error.message : "Invalid JSON.";
6473
+ throw new CliError(
6474
+ "invalid_cli_usage",
6475
+ `Failed to parse JSON from --where-json: ${message}`
6476
+ );
6477
+ }
6478
+ if (!Array.isArray(parsed) && !isJsonObject(parsed)) {
6479
+ throw new CliError(
6480
+ "invalid_cli_usage",
6481
+ 'Expected --where-json to contain a JSON array of conditions or a JSON object (a condition or an {"and"|"or": [...]} group).'
6482
+ );
6483
+ }
6484
+ return parsed;
6485
+ }
6486
+ function resolveWhere(options) {
6487
+ const where = toQueryExpressions(options.where);
6488
+ if (options.whereJson !== void 0) {
6489
+ if (where) {
6490
+ throw new CliError(
6491
+ "invalid_cli_usage",
6492
+ 'Provide either "--where" or "--where-json", not both.'
6493
+ );
6494
+ }
6495
+ return parseWhereJson(options.whereJson);
6496
+ }
6497
+ return where;
6498
+ }
6499
+ function buildRecordQueryInput(options, allowRaw) {
6500
+ const input = allowRaw ? readRawObject(options.raw, options.rawFile) : {};
6501
+ if (options.select && options.select.length > 0) {
6502
+ input.select = [...options.select];
6503
+ }
6504
+ const where = resolveWhere(options);
6505
+ if (where !== void 0) {
6506
+ input.where = where;
6507
+ }
6508
+ if (options.search !== void 0) {
6509
+ input.search = buildSearch(options);
6510
+ }
6511
+ if (options.sort && options.sort.length > 0) {
6512
+ input.sort = [...options.sort];
6513
+ }
6514
+ if (options.limit !== void 0) {
6515
+ input.limit = options.limit;
6516
+ }
6517
+ if (options.offset !== void 0) {
6518
+ input.offset = options.offset;
6519
+ }
6520
+ return input;
6521
+ }
6522
+ function buildRecordAggregateInput(options) {
6523
+ const input = readRawObject(options.raw, options.rawFile);
6524
+ const where = resolveWhere(options);
6525
+ if (where !== void 0) {
6526
+ input.where = where;
6527
+ }
6528
+ if (options.search !== void 0) {
6529
+ input.search = buildSearch(options);
6530
+ }
6531
+ if (options.groupBy && options.groupBy.length > 0) {
6532
+ input.groupBy = [...options.groupBy];
6533
+ }
6534
+ if (options.metric && options.metric.length > 0) {
6535
+ input.metrics = [...options.metric];
6536
+ }
6537
+ if (options.sort && options.sort.length > 0) {
6538
+ input.sort = [...options.sort];
6539
+ }
6540
+ if (options.limit !== void 0) {
6541
+ input.limit = options.limit;
6542
+ }
6543
+ if (options.timezone !== void 0) {
6544
+ input.timezone = options.timezone;
6545
+ }
6546
+ return input;
6547
+ }
6548
+ function toAggregateTableRows(groups) {
6549
+ return groups.map((group) => {
6550
+ const row = {};
6551
+ for (const [slug, key] of Object.entries(group.key ?? {})) {
6552
+ row[slug] = key?.label ? key.label : key?.value ?? "(empty)";
6553
+ }
6554
+ for (const [alias, value] of Object.entries(group.metrics ?? {})) {
6555
+ row[alias in row ? `${alias} (metric)` : alias] = value;
6556
+ }
6557
+ return row;
6558
+ });
6559
+ }
6560
+ function readRecordsFromFile(path) {
6561
+ let contents;
6562
+ try {
6563
+ contents = readFileSync5(path, "utf8");
6564
+ } catch (error) {
6565
+ const message = error instanceof Error ? error.message : "Unable to read file.";
6566
+ throw new CliError(
6567
+ "invalid_cli_usage",
6568
+ `Failed to read records from ${path}: ${message}`
6569
+ );
5932
6570
  }
5933
- if (options.slug !== void 0) {
5934
- input.slug = options.slug;
6571
+ let parsed;
6572
+ try {
6573
+ parsed = JSON.parse(contents);
6574
+ } catch (error) {
6575
+ const message = error instanceof Error ? error.message : "Invalid JSON.";
6576
+ throw new CliError(
6577
+ "invalid_cli_usage",
6578
+ `Failed to parse JSON from --records-file ${path}: ${message}`
6579
+ );
5935
6580
  }
5936
- if (options.auditable !== void 0) {
5937
- input.auditable = options.auditable;
6581
+ if (!Array.isArray(parsed)) {
6582
+ throw new CliError(
6583
+ "invalid_cli_usage",
6584
+ `Expected --records-file ${path} to contain a JSON array of record objects.`
6585
+ );
5938
6586
  }
5939
- if (options.commentable !== void 0) {
5940
- input.commentable = options.commentable;
6587
+ if (parsed.length === 0) {
6588
+ throw new CliError(
6589
+ "invalid_cli_usage",
6590
+ `--records-file ${path} must contain at least one record.`
6591
+ );
5941
6592
  }
5942
- return input;
6593
+ return parsed.map((record, index) => {
6594
+ if (!isJsonObject(record)) {
6595
+ throw new CliError(
6596
+ "invalid_cli_usage",
6597
+ `Record at index ${index} in --records-file ${path} must be a JSON object.`
6598
+ );
6599
+ }
6600
+ return record;
6601
+ });
5943
6602
  }
5944
- function applyFieldDefaultValue(input, defaultValue) {
5945
- if (defaultValue === void 0) {
5946
- return;
6603
+ function buildCreateRecords(options) {
6604
+ const hasSingleRecordFlags = (options.set?.length ?? 0) > 0 || (options.setJson?.length ?? 0) > 0 || options.raw !== void 0 || options.rawFile !== void 0;
6605
+ if (options.recordsFile !== void 0) {
6606
+ if (hasSingleRecordFlags) {
6607
+ throw new CliError(
6608
+ "invalid_cli_usage",
6609
+ 'Provide either "--records-file" or the single-record flags (--set/--set-json/--raw/--raw-file), not both.'
6610
+ );
6611
+ }
6612
+ return readRecordsFromFile(options.recordsFile);
5947
6613
  }
5948
- const config = input.config;
5949
- if (config !== void 0 && !isJsonObject(config)) {
6614
+ const values = {
6615
+ ...readRawObject(options.raw, options.rawFile),
6616
+ ...buildAssignmentObject(options.set, options.setJson)
6617
+ };
6618
+ if (isEmptyObject(values)) {
5950
6619
  throw new CliError(
5951
6620
  "invalid_cli_usage",
5952
- 'Expected field "config" to be a JSON object when using "--default".'
6621
+ 'Provide record fields via "--set", "--set-json", "--raw", "--raw-file", or load multiple records with "--records-file".'
5953
6622
  );
5954
6623
  }
5955
- input.config = {
5956
- ...config ?? {},
5957
- defaultValue
5958
- };
6624
+ return [values];
5959
6625
  }
5960
- function buildFieldCreateInput(options) {
5961
- const raw = normalizeSchemaFieldCreatePayload(readRawObject(options.raw, options.rawFile));
5962
- const rawType = typeof raw.type === "string" ? raw.type : void 0;
5963
- const rawSlug = typeof raw.slug === "string" ? raw.slug : void 0;
5964
- const rawLabel = typeof raw.label === "string" ? raw.label : void 0;
5965
- const type = options.type ?? rawType;
5966
- const slug = options.slug ?? rawSlug;
5967
- const label = options.label ?? rawLabel;
5968
- if (!type) {
5969
- throw new CliError("invalid_cli_usage", 'Provide field type via "--type" or "--raw".');
5970
- }
5971
- if (!slug) {
5972
- throw new CliError("invalid_cli_usage", 'Provide field slug via "--slug" or "--raw".');
5973
- }
5974
- if (!label) {
5975
- throw new CliError("invalid_cli_usage", 'Provide field label via "--label" or "--raw".');
5976
- }
5977
- const normalizedType = normalizeSchemaFieldType(type);
5978
- assertSupportedSchemaFieldType(normalizedType);
5979
- const input = {
6626
+ function buildRecordUpdateInput(options) {
6627
+ const raw = readRawObject(options.raw, options.rawFile);
6628
+ const input = {};
6629
+ const setPayload = {
5980
6630
  ...raw,
5981
- type: normalizedType,
5982
- slug,
5983
- label
6631
+ ...buildAssignmentObject(options.set, options.setJson)
5984
6632
  };
5985
- if (options.required !== void 0) {
5986
- input.required = options.required;
6633
+ const unsetPayload = [...options.unset ?? []];
6634
+ for (const key of Object.keys(setPayload)) {
6635
+ const unsetIndex = unsetPayload.indexOf(key);
6636
+ if (unsetIndex !== -1) {
6637
+ unsetPayload.splice(unsetIndex, 1);
6638
+ }
5987
6639
  }
5988
- if (options.description !== void 0) {
5989
- input.description = options.description;
6640
+ if (Object.keys(setPayload).length > 0) {
6641
+ input.set = setPayload;
6642
+ } else {
6643
+ delete input.set;
5990
6644
  }
5991
- applyFieldDefaultValue(input, options.default);
5992
- if ("config" in input && isJsonObject(input.config) && isEmptyObject(input.config)) {
5993
- delete input.config;
6645
+ if (unsetPayload.length > 0) {
6646
+ input.unset = [...new Set(unsetPayload)];
6647
+ } else {
6648
+ delete input.unset;
6649
+ }
6650
+ if (isEmptyObject(input)) {
6651
+ throw new CliError(
6652
+ "invalid_cli_usage",
6653
+ 'Provide record updates via "--set", "--set-json", "--unset", "--raw", or "--raw-file".'
6654
+ );
5994
6655
  }
5995
6656
  return input;
5996
6657
  }
5997
- function readBackendErrorMessage(error) {
5998
- const responseBody = typeof error.responseBody === "object" && error.responseBody !== null ? error.responseBody : void 0;
5999
- const envelopeError = responseBody && "error" in responseBody && typeof responseBody.error === "object" && responseBody.error !== null ? responseBody.error : responseBody;
6000
- return (envelopeError && "message" in envelopeError && typeof envelopeError.message === "string" ? envelopeError.message : void 0) ?? (typeof error.responseText === "string" && error.responseText.length > 0 ? error.responseText : void 0);
6001
- }
6002
- function toFieldCreateError(error, input) {
6003
- if (!(error instanceof ApiClientError)) {
6004
- throw error;
6005
- }
6006
- const backendMessage = readBackendErrorMessage(error);
6007
- const isGenericValidationMessage = backendMessage === "Schema payload is invalid. One or more fields are invalid." || backendMessage === "Create field payload is invalid.";
6008
- if (!isGenericValidationMessage) {
6009
- throw error;
6010
- }
6011
- throw new CliError(
6012
- "invalid_cli_usage",
6013
- buildSchemaFieldCreateValidationMessage(input.type),
6014
- {
6015
- fieldType: input.type,
6016
- status: error.status
6017
- }
6018
- );
6658
+ function getQueryRecords(result) {
6659
+ return Array.isArray(result.records) ? result.records : [];
6019
6660
  }
6020
- function buildFieldUpdateInput(currentType, options) {
6021
- const input = {
6022
- ...normalizeSchemaFieldUpdatePayload(
6023
- currentType,
6024
- readRawObject(options.raw, options.rawFile)
6025
- ),
6026
- type: currentType
6027
- };
6028
- if (options.label !== void 0) {
6029
- input.label = options.label;
6030
- }
6031
- if (options.required !== void 0) {
6032
- input.required = options.required;
6033
- }
6034
- if (options.description !== void 0) {
6035
- input.description = options.description;
6036
- }
6037
- applyFieldDefaultValue(input, options.default);
6038
- return input;
6661
+ function getRecordIdentifier(record) {
6662
+ return typeof record.recordId === "string" ? record.recordId : "unknown";
6039
6663
  }
6040
6664
  async function resolveSchemaSelector2(api, selector) {
6041
6665
  if (selector.kind === "uuid") {
6042
6666
  return selector;
6043
6667
  }
6044
6668
  const schemas = await api.listSchemas();
6045
- const match = schemas.find((schema) => schema.slug === selector.value);
6669
+ const match = schemas.find((entry) => entry.slug === selector.value);
6046
6670
  if (!match || typeof match.id !== "string") {
6047
6671
  throw new CliError("invalid_cli_usage", `Schema "${selector.value}" not found.`);
6048
6672
  }
@@ -6051,233 +6675,211 @@ async function resolveSchemaSelector2(api, selector) {
6051
6675
  value: match.id
6052
6676
  };
6053
6677
  }
6054
- async function resolveFieldSelector(api, schema, selector) {
6055
- if (selector.kind === "uuid") {
6056
- return selector;
6057
- }
6058
- const fields = await api.listFields(schema);
6059
- const match = fields.find((field) => field.slug === selector.value);
6060
- if (!match || typeof match.id !== "string") {
6061
- throw new CliError("invalid_cli_usage", `Field "${selector.value}" not found.`);
6062
- }
6063
- return {
6064
- kind: "uuid",
6065
- value: match.id
6066
- };
6067
- }
6068
- function registerSchemasCommands(program, options = {}) {
6678
+ function registerRecordsCommands(program, options = {}) {
6069
6679
  const filePath = options.configPath ?? defaultConfigPath;
6070
6680
  const stdout = options.stdout ?? process.stdout;
6071
- const schemas = program.command("schemas").description("Manage schemas and schema fields");
6072
- schemas.command("list").description("List schemas").action(async function action() {
6073
- const { api, json } = createSchemasApi(this, filePath);
6074
- const data = await api.listSchemas();
6075
- if (json) {
6076
- emitJson(stdout, "schemas list", data, filePath);
6077
- return;
6078
- }
6079
- emitSchemasTable(stdout, data);
6080
- });
6081
- schemas.command("get").description("Get a schema by UUID or slug").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
6082
- const { api, json } = createSchemasApi(this, filePath);
6083
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6084
- const data = await api.getSchema(resolvedSchema);
6085
- if (json) {
6086
- emitJson(stdout, "schemas get", data, filePath);
6087
- return;
6088
- }
6089
- emitSchemasTable(stdout, [data]);
6090
- });
6091
- schemas.command("create").description("Create a schema").requiredOption("--name <name>", "schema name").requiredOption("--slug <slug>", "schema slug").option("--auditable", "mark schema as auditable").option("--commentable", "mark schema as commentable").action(async function action(commandOptions) {
6092
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6093
- ensureWritable("schemas create", readOnly, "write");
6094
- const input = {
6095
- name: commandOptions.name,
6096
- slug: commandOptions.slug,
6097
- auditable: Boolean(commandOptions.auditable),
6098
- commentable: Boolean(commandOptions.commentable)
6099
- };
6100
- const data = await api.createSchema(input);
6101
- if (json) {
6102
- emitJson(stdout, "schemas create", data, filePath);
6103
- return;
6104
- }
6105
- writeLine(stdout, `Created schema "${data.slug ?? commandOptions.slug}".`);
6106
- });
6107
- schemas.command("update").description("Update a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--name <name>", "schema name").option("--slug <slug>", "schema slug").option("--auditable <bool>", "auditable flag", parseBooleanFlag).option("--commentable <bool>", "commentable flag", parseBooleanFlag).option(
6108
- "--highlighted-field <field>",
6109
- "its value is used as each record's display name in the UI (field uuid or slug)",
6110
- parseUuidOrSlugSelector
6111
- ).action(async function action(schema, commandOptions) {
6112
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6113
- ensureWritable("schemas update", readOnly, "write");
6114
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6115
- const input = buildSchemaUpdateInput(commandOptions);
6116
- if (commandOptions.highlightedField !== void 0) {
6117
- const resolvedField = await resolveFieldSelector(
6118
- api,
6119
- resolvedSchema,
6120
- commandOptions.highlightedField
6121
- );
6122
- input.highlightedField = resolvedField.value;
6123
- }
6124
- if (isEmptyObject(input)) {
6125
- throw new CliError(
6126
- "invalid_cli_usage",
6127
- 'Provide at least one schema field to update via "--name", "--slug", "--auditable", "--commentable", or "--highlighted-field".'
6128
- );
6129
- }
6130
- const data = await api.updateSchema(resolvedSchema, input);
6681
+ const records = program.command("records").description("Manage schema records");
6682
+ records.command("list").description("List records for a schema with simple pagination").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--limit <number>", "limit results", parseNonNegativeInteger).option("--offset <number>", "offset results", parseNonNegativeInteger).action(async function action(schema, commandOptions) {
6683
+ const { api, schemasApi, json } = createRecordsApi(this, filePath);
6684
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6685
+ const data = await api.listRecords(
6686
+ resolvedSchema,
6687
+ buildRecordQueryInput(commandOptions, false)
6688
+ );
6689
+ const recordsData = getQueryRecords(data);
6131
6690
  if (json) {
6132
- emitJson(stdout, "schemas update", data, filePath);
6691
+ emitJson(
6692
+ stdout,
6693
+ "records list",
6694
+ recordsData,
6695
+ filePath,
6696
+ data.page ? { page: data.page } : {}
6697
+ );
6133
6698
  return;
6134
6699
  }
6135
- writeLine(stdout, `Updated schema "${data.slug ?? schema.value}".`);
6136
- }).addHelpText("after", HIGHLIGHTED_FIELD_HELP);
6137
- schemas.command("set-unique-fields").description("Set or clear the composite unique-field constraint on a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
6138
- "--field <field>",
6139
- "field uuid or slug to include in the unique constraint (repeatable)",
6140
- collectFieldSelectors,
6700
+ emitTable(stdout, recordsData);
6701
+ });
6702
+ 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(
6703
+ "--where <expression>",
6704
+ 'condition "<field> <op> [value]" (repeatable, combined with AND)',
6705
+ collectWhereExpressions,
6141
6706
  []
6142
- ).option("--clear", "clear the unique constraint (sends an empty field list)").action(async function action(schema, commandOptions) {
6143
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6144
- ensureWritable("schemas set-unique-fields", readOnly, "write");
6145
- const selectors = commandOptions.field ?? [];
6146
- if (commandOptions.clear && selectors.length > 0) {
6147
- throw new CliError(
6148
- "invalid_cli_usage",
6149
- 'Use either "--field" or "--clear", not both.'
6150
- );
6151
- }
6152
- if (!commandOptions.clear && selectors.length === 0) {
6153
- throw new CliError(
6154
- "invalid_cli_usage",
6155
- 'Provide at least one field via "--field", or pass "--clear" to remove the unique constraint.'
6156
- );
6157
- }
6158
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6159
- const fields2 = selectors.some((selector) => selector.kind === "slug") ? await api.listFields(resolvedSchema) : [];
6160
- const input = {
6161
- fieldIds: selectors.map((selector) => {
6162
- if (selector.kind === "uuid") {
6163
- return selector.value;
6164
- }
6165
- const match = fields2.find((field) => field.slug === selector.value);
6166
- if (!match || typeof match.id !== "string") {
6167
- throw new CliError("invalid_cli_usage", `Field "${selector.value}" not found.`);
6168
- }
6169
- return match.id;
6170
- })
6171
- };
6172
- const data = await api.setUniqueFields(resolvedSchema, input);
6707
+ ).option(
6708
+ "--where-json <json>",
6709
+ 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
6710
+ ).option(
6711
+ "--search <term>",
6712
+ 'free-text search: every word must appear in some field, as the field shows it (formatted numbers, dates as dd/mm/yyyy or yyyy-mm-dd, members by alias or email, files by name); "quoted text" is one phrase'
6713
+ ).option(
6714
+ "--search-fields <fields>",
6715
+ "field slugs the search looks in (comma-separated, repeatable; default: every searchable field)",
6716
+ collectSelectValues,
6717
+ []
6718
+ ).option(
6719
+ "--search-timezone <iana>",
6720
+ "timezone dates are searched in, e.g. Europe/Madrid (default: workspace timezone)"
6721
+ ).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) {
6722
+ const { api, schemasApi, json } = createRecordsApi(this, filePath);
6723
+ const query = buildRecordQueryInput(commandOptions, true);
6724
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6725
+ const data = await api.queryRecords(resolvedSchema, query);
6726
+ const recordsData = getQueryRecords(data);
6173
6727
  if (json) {
6174
- emitJson(stdout, "schemas set-unique-fields", data, filePath);
6175
- return;
6176
- }
6177
- if (input.fieldIds.length === 0) {
6178
- writeLine(stdout, `Cleared unique fields on schema "${schema.value}".`);
6728
+ emitJson(
6729
+ stdout,
6730
+ "records query",
6731
+ recordsData,
6732
+ filePath,
6733
+ data.page ? { page: data.page } : {}
6734
+ );
6179
6735
  return;
6180
6736
  }
6181
- const count = input.fieldIds.length;
6182
- writeLine(
6183
- stdout,
6184
- `Set unique fields on schema "${schema.value}" (${count} field${count === 1 ? "" : "s"}).`
6185
- );
6737
+ emitTable(stdout, recordsData);
6186
6738
  });
6187
- schemas.command("delete").description("Delete a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
6188
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6189
- ensureWritable("schemas delete", readOnly, "destructive");
6190
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6191
- await api.deleteSchema(resolvedSchema);
6192
- const data = {
6193
- schema: resolvedSchema.value,
6194
- deleted: true
6195
- };
6739
+ records.command("aggregate").description(
6740
+ "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"
6741
+ ).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
6742
+ "--group-by <field[:bucket]>",
6743
+ "group by a field slug; date fields take a bucket day|week|month|quarter|year (repeatable, up to 3)",
6744
+ collectGroupBy,
6745
+ []
6746
+ ).option(
6747
+ "--metric <[alias=]op[:field]>",
6748
+ "metric count|count_distinct|sum|avg|min|max, e.g. count, total=sum:amount (repeatable, up to 10; default count)",
6749
+ collectMetrics,
6750
+ []
6751
+ ).option(
6752
+ "--where <expression>",
6753
+ 'condition "<field> <op> [value]" (repeatable, combined with AND)',
6754
+ collectWhereExpressions,
6755
+ []
6756
+ ).option(
6757
+ "--where-json <json>",
6758
+ 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
6759
+ ).option(
6760
+ "--search <term>",
6761
+ 'free-text search: every word must appear in some field, as the field shows it (formatted numbers, dates as dd/mm/yyyy or yyyy-mm-dd, members by alias or email, files by name); "quoted text" is one phrase'
6762
+ ).option(
6763
+ "--search-fields <fields>",
6764
+ "field slugs the search looks in (comma-separated, repeatable; default: every searchable field)",
6765
+ collectSelectValues,
6766
+ []
6767
+ ).option(
6768
+ "--search-timezone <iana>",
6769
+ "timezone dates are searched in, e.g. Europe/Madrid (default: workspace timezone)"
6770
+ ).option(
6771
+ "--sort <alias|field[:direction]>",
6772
+ "sort groups by a metric alias or group-by field, asc|desc (repeatable, up to 4)",
6773
+ collectAggregateSort,
6774
+ []
6775
+ ).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) {
6776
+ const { api, schemasApi, json } = createRecordsApi(this, filePath);
6777
+ const input = buildRecordAggregateInput(commandOptions);
6778
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6779
+ const data = await api.aggregateRecords(resolvedSchema, input);
6780
+ const groups = Array.isArray(data.groups) ? data.groups : [];
6196
6781
  if (json) {
6197
- emitJson(stdout, "schemas delete", data, filePath);
6782
+ emitJson(
6783
+ stdout,
6784
+ "records aggregate",
6785
+ groups,
6786
+ filePath,
6787
+ data.meta ? { aggregate: data.meta } : {}
6788
+ );
6198
6789
  return;
6199
6790
  }
6200
- writeLine(stdout, `Deleted schema "${schema.value}".`);
6791
+ emitTable(stdout, toAggregateTableRows(groups));
6792
+ if (data.meta?.truncated) {
6793
+ writeLine(
6794
+ stdout,
6795
+ `Showing ${data.meta.count} of ${data.meta.total} groups; raise --limit (max 1000) or narrow the filters to see the rest.`
6796
+ );
6797
+ }
6201
6798
  });
6202
- const fields = schemas.command("fields").description("Manage schema fields");
6203
- fields.command("list").description("List fields for a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
6204
- const { api, json } = createSchemasApi(this, filePath);
6205
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6206
- const data = await api.listFields(resolvedSchema);
6799
+ 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) {
6800
+ const { api, schemasApi, json } = createRecordsApi(this, filePath);
6801
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6802
+ const data = await api.getRecord(resolvedSchema, record);
6207
6803
  if (json) {
6208
- emitJson(stdout, "schemas fields list", data, filePath);
6804
+ emitJson(stdout, "records get", data, filePath);
6209
6805
  return;
6210
6806
  }
6211
- emitFieldsTable(stdout, data);
6807
+ emitTable(stdout, data);
6212
6808
  });
6213
- fields.command("get").description("Get a field by UUID or slug").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, field) {
6214
- const { api, json } = createSchemasApi(this, filePath);
6215
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6216
- const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
6217
- const data = await api.getField(resolvedSchema, resolvedField);
6809
+ records.command("create").description("Create one or more records").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
6810
+ "--set <field=value>",
6811
+ "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
6812
+ collectKeyValueAssignments,
6813
+ []
6814
+ ).option("--set-json <field=json>", "set a structured field", collectJsonAssignments, []).option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").option(
6815
+ "--records-file <path>",
6816
+ "path to a JSON array of record objects (mutually exclusive with --set/--set-json/--raw/--raw-file)"
6817
+ ).action(async function action(schema, commandOptions) {
6818
+ const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
6819
+ ensureWritable("records create", readOnly, "write");
6820
+ const records2 = buildCreateRecords(commandOptions);
6821
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6822
+ const data = await api.createRecords(resolvedSchema, records2);
6218
6823
  if (json) {
6219
- emitJson(stdout, "schemas fields get", data, filePath);
6824
+ emitJson(stdout, "records create", data, filePath);
6220
6825
  return;
6221
6826
  }
6222
- emitFieldsTable(stdout, [data]);
6223
- });
6224
- fields.command("create").description(`Create a field in a schema.${buildSchemaFieldCreateHelpText()}`).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--type <type>", `field type (${formatSchemaFieldTypes()})`).option("--slug <slug>", "field slug").option("--label <label>", "field label").option("--description <text>", "field description").option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload (see type-specific shapes in --help)").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, commandOptions) {
6225
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6226
- ensureWritable("schemas fields create", readOnly, "write");
6227
- const input = buildFieldCreateInput(commandOptions);
6228
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6229
- let data;
6230
- try {
6231
- data = await api.createField(resolvedSchema, input);
6232
- } catch (error) {
6233
- toFieldCreateError(error, input);
6827
+ writeLine(stdout, `Created ${data.created.length} record(s) in schema "${schema.value}".`);
6828
+ if (data.errors.length > 0) {
6829
+ writeLine(stdout, `${data.errors.length} record(s) rejected:`);
6830
+ for (const error of data.errors) {
6831
+ writeLine(stdout, ` - index ${error.index}: ${error.message}`);
6832
+ }
6234
6833
  }
6834
+ });
6835
+ records.command("update").description("Update a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector).option(
6836
+ "--set <field=value>",
6837
+ "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
6838
+ collectKeyValueAssignments,
6839
+ []
6840
+ ).option("--set-json <field=json>", "set a structured field", collectJsonAssignments, []).option("--unset <field>", "unset a field", collectStringValues, []).option("--raw <json>", "raw JSON object of fields to set").option("--raw-file <path>", "path to a JSON object of fields to set").action(async function action(schema, record, commandOptions) {
6841
+ const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
6842
+ ensureWritable("records update", readOnly, "write");
6843
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6844
+ const data = await api.updateRecord(
6845
+ resolvedSchema,
6846
+ record,
6847
+ buildRecordUpdateInput(commandOptions)
6848
+ );
6235
6849
  if (json) {
6236
- emitJson(stdout, "schemas fields create", data, filePath);
6850
+ emitJson(stdout, "records update", data, filePath);
6237
6851
  return;
6238
6852
  }
6239
- writeLine(stdout, `Created field "${data.slug ?? commandOptions.slug}".`);
6853
+ writeLine(stdout, `Updated record "${getRecordIdentifier(data)}".`);
6240
6854
  });
6241
- fields.command("update").description("Update a field in a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector).option("--label <label>", "field label").option("--description <text>", 'field description (use "" to clear)').option("--required <bool>", "required flag", parseBooleanFlag).option("--default <value>", "default field value").option("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").action(async function action(schema, field, commandOptions) {
6242
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6243
- ensureWritable("schemas fields update", readOnly, "write");
6244
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6245
- const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
6246
- const currentField = await api.getField(resolvedSchema, resolvedField);
6247
- const currentType = typeof currentField.type === "string" && currentField.type.length > 0 ? currentField.type : void 0;
6248
- if (!currentType) {
6249
- throw new CliError("invalid_cli_usage", `Field "${field.value}" is missing type metadata.`);
6250
- }
6251
- const input = buildFieldUpdateInput(currentType, commandOptions);
6252
- if (isEmptyObject(input)) {
6253
- throw new CliError(
6254
- "invalid_cli_usage",
6255
- 'Provide at least one field update via "--label", "--description", "--required", "--default", "--raw", or "--raw-file".'
6256
- );
6257
- }
6258
- const data = await api.updateField(resolvedSchema, resolvedField, input);
6855
+ records.command("delete").description("Delete one or more records").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option("--record <uuid>", "record uuid to delete (repeatable)", collectRecordIds, []).option(
6856
+ "--records-file <path>",
6857
+ "path to a file with one record uuid per line (merged with --record)"
6858
+ ).action(async function action(schema, commandOptions) {
6859
+ const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
6860
+ ensureWritable("records delete", readOnly, "destructive");
6861
+ const recordIds = resolveDeleteRecordIds(commandOptions);
6862
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6863
+ const data = await api.deleteRecords(resolvedSchema, recordIds);
6259
6864
  if (json) {
6260
- emitJson(stdout, "schemas fields update", data, filePath);
6865
+ emitJson(stdout, "records delete", data, filePath);
6261
6866
  return;
6262
6867
  }
6263
- writeLine(stdout, `Updated field "${data.slug ?? field.value}".`);
6868
+ writeLine(
6869
+ stdout,
6870
+ `Deleted ${recordIds.length} record(s) from schema "${schema.value}".`
6871
+ );
6264
6872
  });
6265
- fields.command("delete").description("Delete a field from a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<field>", "field uuid or slug", parseUuidOrSlugSelector).action(async function action(schema, field) {
6266
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6267
- ensureWritable("schemas fields delete", readOnly, "destructive");
6268
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6269
- const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
6270
- await api.deleteField(resolvedSchema, resolvedField);
6271
- const data = {
6272
- schema: resolvedSchema.value,
6273
- field: resolvedField.value,
6274
- deleted: true
6275
- };
6873
+ records.command("clear").description("Delete all records from a schema's table").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
6874
+ const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
6875
+ ensureWritable("records clear", readOnly, "destructive");
6876
+ const resolvedSchema = await resolveSchemaSelector2(schemasApi, schema);
6877
+ const data = await api.clearRecords(resolvedSchema);
6276
6878
  if (json) {
6277
- emitJson(stdout, "schemas fields delete", data, filePath);
6879
+ emitJson(stdout, "records clear", data, filePath);
6278
6880
  return;
6279
6881
  }
6280
- writeLine(stdout, `Deleted field "${field.value}" from schema "${schema.value}".`);
6882
+ writeLine(stdout, `Cleared all records from schema "${schema.value}".`);
6281
6883
  });
6282
6884
  }
6283
6885
 
@@ -6492,7 +7094,7 @@ function registerSessionCommands(program, options = {}) {
6492
7094
  import { readFileSync as readFileSync6 } from "fs";
6493
7095
 
6494
7096
  // src/api/teamspace.ts
6495
- function jsonOptions8(body, method) {
7097
+ function jsonOptions9(body, method) {
6496
7098
  return {
6497
7099
  method,
6498
7100
  headers: {
@@ -6519,13 +7121,13 @@ var TeamspaceApi = class {
6519
7121
  createFolder(input) {
6520
7122
  return this.client.requestJson(
6521
7123
  "/api/v2/teamspaces/folders",
6522
- jsonOptions8(input, "POST")
7124
+ jsonOptions9(input, "POST")
6523
7125
  );
6524
7126
  }
6525
7127
  updateFolder(folder, input) {
6526
7128
  return this.client.requestJson(
6527
7129
  `/api/v2/teamspaces/folders/${folder.value}`,
6528
- jsonOptions8(input, "PATCH")
7130
+ jsonOptions9(input, "PATCH")
6529
7131
  );
6530
7132
  }
6531
7133
  deleteFolder(folder) {
@@ -6537,13 +7139,13 @@ var TeamspaceApi = class {
6537
7139
  publishResource(input) {
6538
7140
  return this.client.requestJson(
6539
7141
  "/api/v2/teamspaces/resources:publish",
6540
- jsonOptions8(input, "POST")
7142
+ jsonOptions9(input, "POST")
6541
7143
  );
6542
7144
  }
6543
7145
  unpublishResource(resourceId) {
6544
7146
  return this.client.requestJson(
6545
7147
  "/api/v2/teamspaces/resources:unpublish",
6546
- jsonOptions8({ resourceId }, "POST")
7148
+ jsonOptions9({ resourceId }, "POST")
6547
7149
  );
6548
7150
  }
6549
7151
  };
@@ -6763,7 +7365,7 @@ function registerTeamspaceCommands(program, options = {}) {
6763
7365
  var require2 = createRequire(import.meta.url);
6764
7366
  var { version } = require2("../package.json");
6765
7367
  function buildProgram(options = {}) {
6766
- const program = new Command4();
7368
+ const program = new Command5();
6767
7369
  program.name("zinkee").description("CLI for Zinkee API v2").version(version).enablePositionalOptions().showHelpAfterError().option("--profile <name>", "select a profile from config").option("--base-url <url>", "override the configured base URL").option("--api-key <token>", "override the configured API key").option("--workspace <workspace>", "workspace name or id for a session profile (or ZINKEE_WORKSPACE)").option("--read-only", "run in read-only mode").option("--idempotency-key <key>", "send this Idempotency-Key on the write request so a retry does not repeat it").option("--example", "show examples for a command").option("--json", "emit JSON output").option("--install-completion [shell]", "install shell completion (bash, zsh, fish, powershell)").option("--show-completion [shell]", "print shell completion script for the current shell");
6768
7370
  registerProfilesCommands(program, options);
6769
7371
  registerSessionCommands(program, options);
@@ -6772,6 +7374,7 @@ function buildProgram(options = {}) {
6772
7374
  registerDisplaysCommands(program, options);
6773
7375
  registerDocumentTemplatesCommands(program, options);
6774
7376
  registerFilesCommands(program, options);
7377
+ registerFormsCommands(program, options);
6775
7378
  registerFormulasCommands(program, options);
6776
7379
  registerNavigationCommands(program, options);
6777
7380
  registerSchemasCommands(program, options);