zinkee 0.1.71 → 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,1632 +4678,2208 @@ 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
5272
- };
5273
- }
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;
5280
- }
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
- }
5202
+ function collect(value, previous = []) {
5203
+ return [...previous, value];
5288
5204
  }
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
- }
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;
5212
+ };
5296
5213
  }
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);
5303
- }
5214
+ function usage(message) {
5215
+ return new CliError("invalid_cli_usage", message);
5304
5216
  }
5305
- function dedupeStrings(values) {
5306
- return [...new Set(values)];
5217
+ function createFormsApi(command, filePath) {
5218
+ const { client, ...runtime } = createCommandContext(command, filePath);
5219
+ return { forms: new FormsApi(client), schemas: new SchemasApi(client), ...runtime };
5307
5220
  }
5308
- function toRecordUuid(value) {
5309
- try {
5310
- const normalized = normalizeUuidOrSlug(value);
5311
- return normalized.kind === "uuid" ? normalized.value : null;
5312
- } catch {
5313
- return null;
5314
- }
5221
+ async function resolveSchemaId(schemas, selector) {
5222
+ return (await resolveSchemaSelector(schemas, selector)).value;
5315
5223
  }
5316
- function collectRecordIds(value, previous = []) {
5317
- const uuid = toRecordUuid(value.trim());
5318
- if (!uuid) {
5319
- throw new InvalidArgumentError3(`Expected a record UUID, received "${value}".`);
5224
+ function findForm(forms, selector, schema) {
5225
+ const byId = forms.find((form) => form.id === selector);
5226
+ if (byId) {
5227
+ return byId;
5320
5228
  }
5321
- return [...previous, uuid];
5322
- }
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
- );
5229
+ const byName = forms.filter((form) => form.name === selector);
5230
+ if (byName.length === 1) {
5231
+ return byName[0];
5333
5232
  }
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;
5350
- }
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
- );
5233
+ if (byName.length > 1) {
5234
+ throw usage(`Form name "${selector}" is ambiguous in "${schema}": use its id (zinkee forms list ${schema}).`);
5360
5235
  }
5361
- return recordIds;
5236
+ throw usage(`Form "${selector}" was not found in "${schema}". List them with: zinkee forms list ${schema}`);
5362
5237
  }
5363
- function collectStringValues(value, previous = []) {
5364
- return [...previous, value];
5238
+ async function resolveForm(forms, schemaId, selector, schema) {
5239
+ return findForm(await forms.listForms(schemaId), selector, schema);
5365
5240
  }
5366
- function buildSearch(options) {
5367
- const search = { term: options.search ?? "" };
5368
- if (options.searchFields && options.searchFields.length > 0) {
5369
- search.fields = [...options.searchFields];
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];
5370
5248
  }
5371
- if (options.searchTimezone !== void 0) {
5372
- search.timezone = options.searchTimezone;
5249
+ const field = input.slice(0, index).trim();
5250
+ if (!field) {
5251
+ throw usage(`Expected "${option} <field>=<value>", received "${input}".`);
5373
5252
  }
5374
- return search;
5253
+ return [field, input.slice(index + 1)];
5375
5254
  }
5376
- function collectSelectValues(value, previous = []) {
5377
- return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--select")]);
5255
+ function sameField(config, selector) {
5256
+ return config.field === selector || config.fieldId === selector;
5378
5257
  }
5379
- function collectSortValues(value, previous = []) {
5380
- return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--sort")]);
5258
+ function toInputField(config) {
5259
+ const { fieldId: _fieldId, ...rest } = config;
5260
+ return { ...rest };
5381
5261
  }
5382
- function collectWhereExpressions(value, previous = []) {
5383
- return [...previous, parseExpressionValue(value)];
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;
5384
5270
  }
5385
- function splitKnownSuffix(input, suffixes) {
5386
- const index = input.lastIndexOf(":");
5387
- if (index !== -1) {
5388
- const suffix = input.slice(index + 1).trim().toLowerCase();
5389
- if (suffixes.includes(suffix)) {
5390
- return { head: input.slice(0, index).trim(), suffix };
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
+ });
5276
+ }
5277
+ function applyFieldModifiers(fields, options) {
5278
+ const each = (values, apply) => {
5279
+ for (const value of values ?? []) {
5280
+ apply(value);
5391
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
+ };
5392
5339
  }
5393
- return { head: input.trim() };
5394
- }
5395
- function parseGroupBy(input) {
5396
- const { head, suffix } = splitKnownSuffix(input, AGGREGATE_BUCKETS);
5397
- if (!head) {
5398
- throw new CliError(
5399
- "invalid_cli_usage",
5400
- `Invalid --group-by "${input}": expected <field>[:<bucket>] with bucket one of ${AGGREGATE_BUCKETS.join(", ")}.`
5401
- );
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;
5402
5391
  }
5403
- return suffix ? { field: head, bucket: suffix } : { field: head };
5404
- }
5405
- function parseMetric(input) {
5406
- const usage = `Invalid --metric "${input}": expected [<alias>=]<op>[:<field>], e.g. "count", "total=sum:amount" or "count_distinct:customer".`;
5407
- const aliasIndex = input.lastIndexOf("=");
5408
- const alias = aliasIndex === -1 ? void 0 : input.slice(0, aliasIndex).trim();
5409
- const expression = input.slice(aliasIndex + 1);
5410
- const fieldIndex = expression.indexOf(":");
5411
- const op = (fieldIndex === -1 ? expression : expression.slice(0, fieldIndex)).trim();
5412
- const field = fieldIndex === -1 ? void 0 : expression.slice(fieldIndex + 1).trim();
5413
- if (alias === "" || !/^[A-Za-z_]+$/.test(op) || field === "") {
5414
- 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.');
5415
5395
  }
5416
- return {
5417
- op,
5418
- ...field !== void 0 ? { field } : {},
5419
- ...alias !== void 0 ? { as: alias } : {}
5420
- };
5421
- }
5422
- function parseAggregateSort(input) {
5423
- const { head, suffix } = splitKnownSuffix(input, ["asc", "desc"]);
5424
- if (!head) {
5425
- throw new CliError(
5426
- "invalid_cli_usage",
5427
- `Invalid --sort "${input}": expected <alias|field>[:asc|desc].`
5428
- );
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);
5429
5400
  }
5430
- return { by: head, direction: (suffix ?? "asc").toUpperCase() };
5401
+ return input;
5431
5402
  }
5432
- function parseGroupLimit(input) {
5433
- const limit = /^\d+$/.test(input.trim()) ? Number(input) : Number.NaN;
5434
- if (!(limit >= 1 && limit <= 1e3)) {
5435
- throw new CliError(
5436
- "invalid_cli_usage",
5437
- `Invalid --limit "${input}": expected a number of groups from 1 to 1000.`
5438
- );
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 = [];
5439
5422
  }
5440
- return limit;
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;
5441
5437
  }
5442
- function collectGroupBy(value, previous = []) {
5443
- return [...previous, parseGroupBy(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;
5444
5452
  }
5445
- function collectMetrics(value, previous = []) {
5446
- return [...previous, parseMetric(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)" : ""}`;
5447
5458
  }
5448
- function collectAggregateSort(value, previous = []) {
5449
- return [...previous, parseAggregateSort(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
+ );
5450
5471
  }
5451
- function collectKeyValueAssignments(value, previous = []) {
5452
- return [...previous, parseKeyValueAssignment(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 "";
5485
+ }
5453
5486
  }
5454
- function collectJsonAssignments(value, previous = []) {
5455
- return [...previous, parseJsonKeyValueAssignment(value)];
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
+ );
5503
+ }
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
+ );
5456
5518
  }
5457
- function buildAssignmentObject(assignments = [], jsonAssignments = []) {
5458
- const output = {};
5459
- for (const assignment of assignments) {
5460
- output[assignment.key] = assignment.value;
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;
5461
5523
  }
5462
- for (const assignment of jsonAssignments) {
5463
- output[assignment.key] = assignment.value;
5524
+ if (!link.active) {
5525
+ writeLine(stdout, `The public link is off${link.hasPassword ? " (it keeps its password)" : ""}.`);
5526
+ return;
5464
5527
  }
5465
- return output;
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;
5560
+ }
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;
5569
+ }
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;
5587
+ }
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}).`);
5609
+ });
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;
5619
+ }
5620
+ writeLine(stdout, `Deleted form "${current.name ?? current.id}".`);
5621
+ });
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;
5631
+ }
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
+ });
5466
5669
  }
5467
- function toQueryExpressions(expressions) {
5468
- if (!expressions || expressions.length === 0) {
5469
- return void 0;
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
+ };
5470
5679
  }
5471
- return expressions.map((expression) => ({
5472
- field: expression.field,
5473
- comparator: expression.comparator,
5474
- value: expression.value
5475
- }));
5680
+ if (input.scope === "SCHEMA") {
5681
+ return {
5682
+ scope: input.scope,
5683
+ schema: input.schema.value
5684
+ };
5685
+ }
5686
+ return { scope: input.scope };
5476
5687
  }
5477
- function parseWhereJson(input) {
5478
- let parsed;
5479
- try {
5480
- parsed = JSON.parse(input);
5481
- } catch (error) {
5482
- const message = error instanceof Error ? error.message : "Invalid JSON.";
5483
- throw new CliError(
5484
- "invalid_cli_usage",
5485
- `Failed to parse JSON from --where-json: ${message}`
5688
+ var FormulasApi = class {
5689
+ constructor(client) {
5690
+ this.client = client;
5691
+ }
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
+ }
5486
5702
  );
5487
5703
  }
5488
- if (!Array.isArray(parsed) && !isJsonObject(parsed)) {
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) {
5489
5716
  throw new CliError(
5490
5717
  "invalid_cli_usage",
5491
- 'Expected --where-json to contain a JSON array of conditions or a JSON object (a condition or an {"and"|"or": [...]} group).'
5718
+ `Command "${commandName}" requires --yes because it may enqueue a large recalculation.`
5492
5719
  );
5493
5720
  }
5494
- return parsed;
5495
- }
5496
- function resolveWhere(options) {
5497
- const where = toQueryExpressions(options.where);
5498
- if (options.whereJson !== void 0) {
5499
- if (where) {
5500
- throw new CliError(
5501
- "invalid_cli_usage",
5502
- 'Provide either "--where" or "--where-json", not both.'
5503
- );
5504
- }
5505
- return parseWhereJson(options.whereJson);
5506
- }
5507
- return where;
5508
5721
  }
5509
- function buildRecordQueryInput(options, allowRaw) {
5510
- const input = allowRaw ? readRawObject(options.raw, options.rawFile) : {};
5511
- if (options.select && options.select.length > 0) {
5512
- input.select = [...options.select];
5513
- }
5514
- const where = resolveWhere(options);
5515
- if (where !== void 0) {
5516
- input.where = where;
5517
- }
5518
- if (options.search !== void 0) {
5519
- input.search = buildSearch(options);
5520
- }
5521
- if (options.sort && options.sort.length > 0) {
5522
- input.sort = [...options.sort];
5523
- }
5524
- if (options.limit !== void 0) {
5525
- input.limit = options.limit;
5526
- }
5527
- if (options.offset !== void 0) {
5528
- input.offset = options.offset;
5722
+ function emitResult(stdout, commandName, result, configPath, json) {
5723
+ if (json) {
5724
+ emitJson(stdout, commandName, result, configPath);
5725
+ return;
5529
5726
  }
5530
- return input;
5727
+ writeLine(
5728
+ stdout,
5729
+ `Queued ${result.eventsQueued} formula recalculation event(s) for ${result.scope.toLowerCase()} scope (request ${result.requestId}).`
5730
+ );
5531
5731
  }
5532
- function buildRecordAggregateInput(options) {
5533
- const input = readRawObject(options.raw, options.rawFile);
5534
- const where = resolveWhere(options);
5535
- if (where !== void 0) {
5536
- input.where = where;
5537
- }
5538
- if (options.search !== void 0) {
5539
- input.search = buildSearch(options);
5540
- }
5541
- if (options.groupBy && options.groupBy.length > 0) {
5542
- input.groupBy = [...options.groupBy];
5543
- }
5544
- if (options.metric && options.metric.length > 0) {
5545
- input.metrics = [...options.metric];
5546
- }
5547
- if (options.sort && options.sort.length > 0) {
5548
- input.sort = [...options.sort];
5549
- }
5550
- if (options.limit !== void 0) {
5551
- input.limit = options.limit;
5552
- }
5553
- if (options.timezone !== void 0) {
5554
- input.timezone = options.timezone;
5732
+ async function recompute(command, commandName, input, options, requireConfirmation, confirmed) {
5733
+ const configPath = options.configPath ?? defaultConfigPath;
5734
+ const stdout = options.stdout ?? process.stdout;
5735
+ const { api, json, readOnly } = createFormulasApi(command, configPath);
5736
+ ensureWritable(commandName, readOnly, "write");
5737
+ if (requireConfirmation) {
5738
+ ensureConfirmed(commandName, confirmed);
5555
5739
  }
5556
- return input;
5740
+ const result = await api.recompute(input);
5741
+ emitResult(stdout, commandName, result, configPath, json);
5557
5742
  }
5558
- function toAggregateTableRows(groups) {
5559
- return groups.map((group) => {
5560
- const row = {};
5561
- for (const [slug, key] of Object.entries(group.key ?? {})) {
5562
- row[slug] = key?.label ? key.label : key?.value ?? "(empty)";
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
5754
+ );
5563
5755
  }
5564
- for (const [alias, value] of Object.entries(group.metrics ?? {})) {
5565
- row[alias in row ? `${alias} (metric)` : alias] = value;
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
5766
+ );
5566
5767
  }
5567
- return row;
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
+ );
5568
5778
  });
5569
5779
  }
5570
- function readRecordsFromFile(path) {
5571
- let contents;
5572
- try {
5573
- contents = readFileSync5(path, "utf8");
5574
- } catch (error) {
5575
- const message = error instanceof Error ? error.message : "Unable to read file.";
5576
- throw new CliError(
5577
- "invalid_cli_usage",
5578
- `Failed to read records from ${path}: ${message}`
5579
- );
5580
- }
5581
- let parsed;
5582
- try {
5583
- parsed = JSON.parse(contents);
5584
- } catch (error) {
5585
- const message = error instanceof Error ? error.message : "Invalid JSON.";
5586
- throw new CliError(
5587
- "invalid_cli_usage",
5588
- `Failed to parse JSON from --records-file ${path}: ${message}`
5589
- );
5590
- }
5591
- if (!Array.isArray(parsed)) {
5592
- throw new CliError(
5593
- "invalid_cli_usage",
5594
- `Expected --records-file ${path} to contain a JSON array of record objects.`
5595
- );
5780
+
5781
+ // src/api/logs.ts
5782
+ var LogsApi = class {
5783
+ constructor(client) {
5784
+ this.client = client;
5596
5785
  }
5597
- if (parsed.length === 0) {
5598
- throw new CliError(
5599
- "invalid_cli_usage",
5600
- `--records-file ${path} must contain at least one record.`
5786
+ listLogs(schema, recordId) {
5787
+ return this.client.getJson(
5788
+ `/api/v2/schemas/${schema.value}/records/${recordId}/logs`
5601
5789
  );
5602
5790
  }
5603
- return parsed.map((record, index) => {
5604
- if (!isJsonObject(record)) {
5605
- throw new CliError(
5606
- "invalid_cli_usage",
5607
- `Record at index ${index} in --records-file ${path} must be a JSON object.`
5608
- );
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);
5808
+ if (json) {
5809
+ emitJson(stdout, "logs list", data);
5810
+ return;
5609
5811
  }
5610
- return record;
5812
+ emitTable(stdout, data);
5611
5813
  });
5612
5814
  }
5613
- function buildCreateRecords(options) {
5614
- const hasSingleRecordFlags = (options.set?.length ?? 0) > 0 || (options.setJson?.length ?? 0) > 0 || options.raw !== void 0 || options.rawFile !== void 0;
5615
- if (options.recordsFile !== void 0) {
5616
- if (hasSingleRecordFlags) {
5617
- throw new CliError(
5618
- "invalid_cli_usage",
5619
- 'Provide either "--records-file" or the single-record flags (--set/--set-json/--raw/--raw-file), not both.'
5620
- );
5621
- }
5622
- return readRecordsFromFile(options.recordsFile);
5815
+
5816
+ // src/api/members.ts
5817
+ var MembersApi = class {
5818
+ constructor(client) {
5819
+ this.client = client;
5623
5820
  }
5624
- const values = {
5625
- ...readRawObject(options.raw, options.rawFile),
5626
- ...buildAssignmentObject(options.set, options.setJson)
5627
- };
5628
- if (isEmptyObject(values)) {
5629
- throw new CliError(
5630
- "invalid_cli_usage",
5631
- 'Provide record fields via "--set", "--set-json", "--raw", "--raw-file", or load multiple records with "--records-file".'
5632
- );
5821
+ listMembers() {
5822
+ return this.client.getJson("/api/v2/members");
5633
5823
  }
5634
- return [values];
5635
- }
5636
- function buildRecordUpdateInput(options) {
5637
- const raw = readRawObject(options.raw, options.rawFile);
5638
- const input = {};
5639
- const setPayload = {
5640
- ...raw,
5641
- ...buildAssignmentObject(options.set, options.setJson)
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
5642
5832
  };
5643
- const unsetPayload = [...options.unset ?? []];
5644
- for (const key of Object.keys(setPayload)) {
5645
- const unsetIndex = unsetPayload.indexOf(key);
5646
- if (unsetIndex !== -1) {
5647
- unsetPayload.splice(unsetIndex, 1);
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();
5843
+ if (json) {
5844
+ emitJson(stdout, "members list", data);
5845
+ return;
5648
5846
  }
5847
+ emitTable(stdout, data);
5848
+ });
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;
5649
5867
  }
5650
- if (Object.keys(setPayload).length > 0) {
5651
- input.set = setPayload;
5652
- } else {
5653
- delete input.set;
5868
+ listFolders() {
5869
+ return this.client.getJson("/api/v2/navigation/folders");
5654
5870
  }
5655
- if (unsetPayload.length > 0) {
5656
- input.unset = [...new Set(unsetPayload)];
5657
- } else {
5658
- delete input.unset;
5871
+ createFolder(body) {
5872
+ return this.client.requestJson(
5873
+ "/api/v2/navigation/folders",
5874
+ jsonOptions8(body, "POST")
5875
+ );
5659
5876
  }
5660
- if (isEmptyObject(input)) {
5661
- throw new CliError(
5662
- "invalid_cli_usage",
5663
- 'Provide record updates via "--set", "--set-json", "--unset", "--raw", or "--raw-file".'
5877
+ updateFolder(folder, body) {
5878
+ return this.client.requestJson(
5879
+ `/api/v2/navigation/folders/${folder.value}`,
5880
+ jsonOptions8(body, "PATCH")
5664
5881
  );
5665
5882
  }
5666
- return input;
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
+ };
5667
5904
  }
5668
- function getQueryRecords(result) {
5669
- return Array.isArray(result.records) ? result.records : [];
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;
5670
5914
  }
5671
- function getRecordIdentifier(record) {
5672
- return typeof record.recordId === "string" ? record.recordId : "unknown";
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
+ }
5673
5935
  }
5674
- async function resolveSchemaSelector(api, selector) {
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) {
5675
5952
  if (selector.kind === "uuid") {
5676
- return selector;
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;
5677
5958
  }
5678
- const schemas = await api.listSchemas();
5679
- const match = schemas.find((entry) => entry.slug === selector.value);
5680
- if (!match || typeof match.id !== "string") {
5681
- throw new CliError("invalid_cli_usage", `Schema "${selector.value}" not found.`);
5959
+ const matches = folders.filter((folder) => folder.name === selector.value);
5960
+ if (matches.length === 1) {
5961
+ return matches[0];
5682
5962
  }
5683
- return {
5684
- kind: "uuid",
5685
- value: match.id
5686
- };
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.`);
5687
5970
  }
5688
- function registerRecordsCommands(program, options = {}) {
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 = {}) {
5689
5980
  const filePath = options.configPath ?? defaultConfigPath;
5690
5981
  const stdout = options.stdout ?? process.stdout;
5691
- const records = program.command("records").description("Manage schema records");
5692
- 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) {
5693
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5694
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5695
- const data = await api.listRecords(
5696
- resolvedSchema,
5697
- buildRecordQueryInput(commandOptions, false)
5698
- );
5699
- const recordsData = getQueryRecords(data);
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();
5700
5987
  if (json) {
5701
- emitJson(
5702
- stdout,
5703
- "records list",
5704
- recordsData,
5705
- filePath,
5706
- data.page ? { page: data.page } : {}
5707
- );
5988
+ emitJson(stdout, "navigation folders list", data, filePath);
5708
5989
  return;
5709
5990
  }
5710
- emitTable(stdout, recordsData);
5991
+ printTable(folderRows2(data), ["id", "order", "name", "resourceCount"], stdout);
5711
5992
  });
5712
- 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(
5713
- "--where <expression>",
5714
- 'condition "<field> <op> [value]" (repeatable, combined with AND)',
5715
- collectWhereExpressions,
5716
- []
5717
- ).option(
5718
- "--where-json <json>",
5719
- 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
5720
- ).option(
5721
- "--search <term>",
5722
- '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'
5723
- ).option(
5724
- "--search-fields <fields>",
5725
- "field slugs the search looks in (comma-separated, repeatable; default: every searchable field)",
5726
- collectSelectValues,
5727
- []
5728
- ).option(
5729
- "--search-timezone <iana>",
5730
- "timezone dates are searched in, e.g. Europe/Madrid (default: workspace timezone)"
5731
- ).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) {
5732
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5733
- const query = buildRecordQueryInput(commandOptions, true);
5734
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5735
- const data = await api.queryRecords(resolvedSchema, query);
5736
- const recordsData = getQueryRecords(data);
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);
5737
5997
  if (json) {
5738
- emitJson(
5739
- stdout,
5740
- "records query",
5741
- recordsData,
5742
- filePath,
5743
- data.page ? { page: data.page } : {}
5744
- );
5998
+ emitJson(stdout, "navigation folders get", resolved, filePath);
5745
5999
  return;
5746
6000
  }
5747
- emitTable(stdout, recordsData);
6001
+ printTable(folderRows2([resolved]), ["id", "order", "name", "resourceCount"], stdout);
5748
6002
  });
5749
- records.command("aggregate").description(
5750
- "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"
5751
- ).argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).option(
5752
- "--group-by <field[:bucket]>",
5753
- "group by a field slug; date fields take a bucket day|week|month|quarter|year (repeatable, up to 3)",
5754
- collectGroupBy,
5755
- []
5756
- ).option(
5757
- "--metric <[alias=]op[:field]>",
5758
- "metric count|count_distinct|sum|avg|min|max, e.g. count, total=sum:amount (repeatable, up to 10; default count)",
5759
- collectMetrics,
5760
- []
5761
- ).option(
5762
- "--where <expression>",
5763
- 'condition "<field> <op> [value]" (repeatable, combined with AND)',
5764
- collectWhereExpressions,
5765
- []
5766
- ).option(
5767
- "--where-json <json>",
5768
- 'native where as JSON: an array of conditions (AND) or one condition/{"and"|"or": [...]} group (not combinable with --where)'
5769
- ).option(
5770
- "--search <term>",
5771
- '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'
5772
- ).option(
5773
- "--search-fields <fields>",
5774
- "field slugs the search looks in (comma-separated, repeatable; default: every searchable field)",
5775
- collectSelectValues,
5776
- []
5777
- ).option(
5778
- "--search-timezone <iana>",
5779
- "timezone dates are searched in, e.g. Europe/Madrid (default: workspace timezone)"
5780
- ).option(
5781
- "--sort <alias|field[:direction]>",
5782
- "sort groups by a metric alias or group-by field, asc|desc (repeatable, up to 4)",
5783
- collectAggregateSort,
5784
- []
5785
- ).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) {
5786
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5787
- const input = buildRecordAggregateInput(commandOptions);
5788
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5789
- const data = await api.aggregateRecords(resolvedSchema, input);
5790
- const groups = Array.isArray(data.groups) ? data.groups : [];
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));
5791
6007
  if (json) {
5792
- emitJson(
5793
- stdout,
5794
- "records aggregate",
5795
- groups,
5796
- filePath,
5797
- data.meta ? { aggregate: data.meta } : {}
5798
- );
6008
+ emitJson(stdout, "navigation folders create", data, filePath);
5799
6009
  return;
5800
6010
  }
5801
- emitTable(stdout, toAggregateTableRows(groups));
5802
- if (data.meta?.truncated) {
5803
- writeLine(
5804
- stdout,
5805
- `Showing ${data.meta.count} of ${data.meta.total} groups; raise --limit (max 1000) or narrow the filters to see the rest.`
5806
- );
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}".`);
6057
+ });
6058
+ }
6059
+
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) {
6076
+ return {
6077
+ name: profileName,
6078
+ isDefault: defaultProfile === profileName,
6079
+ ...redactProfile(profile)
6080
+ };
6081
+ }
6082
+ function loadConfigForAdd(filePath) {
6083
+ return readConfigIfExists(filePath) ?? { profiles: {} };
6084
+ }
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;
6096
+ }
6097
+ }
6098
+ function emitProfilesTable(stdout, data) {
6099
+ printTable(
6100
+ data.map((profile) => ({
6101
+ name: profile.name,
6102
+ default: profile.isDefault ? "yes" : "",
6103
+ baseUrl: profile.baseUrl ?? "",
6104
+ credential: describeProfileCredential(profile)
6105
+ })),
6106
+ ["name", "default", "baseUrl", "credential"],
6107
+ stdout
6108
+ );
6109
+ }
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;
5807
6132
  }
6133
+ emitProfilesTable(stdout, [data]);
5808
6134
  });
5809
- 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) {
5810
- const { api, schemasApi, json } = createRecordsApi(this, filePath);
5811
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5812
- const data = await api.getRecord(resolvedSchema, record);
5813
- if (json) {
5814
- emitJson(stdout, "records get", data, filePath);
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);
5815
6146
  return;
5816
6147
  }
5817
- emitTable(stdout, data);
6148
+ writeLine(stdout, `Using profile "${profileName}".`);
5818
6149
  });
5819
- records.command("create").description("Create one or more records").argument("<schema>", "schema 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("--raw <json>", "raw JSON object payload").option("--raw-file <path>", "path to a raw JSON object payload").option(
5825
- "--records-file <path>",
5826
- "path to a JSON array of record objects (mutually exclusive with --set/--set-json/--raw/--raw-file)"
5827
- ).action(async function action(schema, commandOptions) {
5828
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5829
- ensureWritable("records create", readOnly, "write");
5830
- const records2 = buildCreateRecords(commandOptions);
5831
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5832
- const data = await api.createRecords(resolvedSchema, records2);
5833
- if (json) {
5834
- emitJson(stdout, "records create", data, filePath);
5835
- return;
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
+ );
5836
6157
  }
5837
- writeLine(stdout, `Created ${data.created.length} record(s) in schema "${schema.value}".`);
5838
- if (data.errors.length > 0) {
5839
- writeLine(stdout, `${data.errors.length} record(s) rejected:`);
5840
- for (const error of data.errors) {
5841
- writeLine(stdout, ` - index ${error.index}: ${error.message}`);
5842
- }
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);
5843
6165
  }
5844
- });
5845
- records.command("update").description("Update a record").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).argument("<record>", "record uuid or slug", parseUuidOrSlugSelector).option(
5846
- "--set <field=value>",
5847
- "set a string field (reference fields: a record id, 'recordId::label', or an exact display value)",
5848
- collectKeyValueAssignments,
5849
- []
5850
- ).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) {
5851
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5852
- ensureWritable("records update", readOnly, "write");
5853
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5854
- const data = await api.updateRecord(
5855
- resolvedSchema,
5856
- record,
5857
- buildRecordUpdateInput(commandOptions)
6166
+ writeConfig(nextConfig, filePath);
6167
+ const data = toDisplayProfile(
6168
+ profileName,
6169
+ nextConfig.profiles[profileName] ?? {},
6170
+ nextConfig.defaultProfile
5858
6171
  );
5859
- if (json) {
5860
- emitJson(stdout, "records update", data, filePath);
6172
+ if (this.optsWithGlobals().json) {
6173
+ emitJson(stdout, "profiles add", data, filePath);
5861
6174
  return;
5862
6175
  }
5863
- writeLine(stdout, `Updated record "${getRecordIdentifier(data)}".`);
6176
+ writeLine(stdout, `Added profile "${profileName}".`);
5864
6177
  });
5865
- 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(
5866
- "--records-file <path>",
5867
- "path to a file with one record uuid per line (merged with --record)"
5868
- ).action(async function action(schema, commandOptions) {
5869
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5870
- ensureWritable("records delete", readOnly, "destructive");
5871
- const recordIds = resolveDeleteRecordIds(commandOptions);
5872
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5873
- const data = await api.deleteRecords(resolvedSchema, recordIds);
5874
- if (json) {
5875
- emitJson(stdout, "records delete", data, filePath);
5876
- return;
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
+ );
5877
6184
  }
5878
- writeLine(
5879
- stdout,
5880
- `Deleted ${recordIds.length} record(s) from schema "${schema.value}".`
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
5881
6203
  );
6204
+ if (this.optsWithGlobals().json) {
6205
+ emitJson(stdout, "profiles update", data, filePath);
6206
+ return;
6207
+ }
6208
+ writeLine(stdout, `Updated profile "${profileName}".`);
5882
6209
  });
5883
- records.command("clear").description("Delete all records from a schema's table").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
5884
- const { api, schemasApi, json, readOnly } = createRecordsApi(this, filePath);
5885
- ensureWritable("records clear", readOnly, "destructive");
5886
- const resolvedSchema = await resolveSchemaSelector(schemasApi, schema);
5887
- const data = await api.clearRecords(resolvedSchema);
5888
- if (json) {
5889
- emitJson(stdout, "records clear", data, filePath);
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);
5890
6221
  return;
5891
6222
  }
5892
- writeLine(stdout, `Cleared all records from schema "${schema.value}".`);
6223
+ writeLine(stdout, `Removed profile "${profileName}".`);
5893
6224
  });
5894
6225
  }
5895
6226
 
5896
- // src/commands/schemas.ts
5897
- import { InvalidArgumentError as InvalidArgumentError4 } from "commander";
5898
- var HIGHLIGHTED_FIELD_HELP = `
5899
- Highlighted field:
5900
- The schema's "main" field. The frontend uses its value as each record's
5901
- display name, in two places:
5902
- - Activity panel: the record's title in the activity side panel
5903
- (the panel with the record's logs and comments).
5904
- - Detail view: the record's name in the left-hand record list you
5905
- browse to open each record's form.
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".
5906
6255
  `;
5907
- function createSchemasApi(command, filePath) {
6256
+ function createRecordsApi(command, filePath) {
5908
6257
  const { client, ...runtime } = createCommandContext(command, filePath);
5909
6258
  return {
5910
- api: new SchemasApi(client),
6259
+ api: new RecordsApi(client),
6260
+ schemasApi: new SchemasApi(client),
5911
6261
  ...runtime
5912
6262
  };
5913
6263
  }
5914
- function collectFieldSelectors(value, previous = []) {
5915
- return [...previous, parseUuidOrSlugSelector(value)];
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;
5916
6352
  }
5917
- function parseBooleanFlag(input) {
5918
- const normalized = input.trim().toLowerCase();
5919
- if (["true", "1", "yes", "y", "on"].includes(normalized)) {
5920
- return true;
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];
5921
6360
  }
5922
- if (["false", "0", "no", "n", "off"].includes(normalized)) {
5923
- return false;
6361
+ if (options.searchTimezone !== void 0) {
6362
+ search.timezone = options.searchTimezone;
5924
6363
  }
5925
- throw new InvalidArgumentError4(`Expected a boolean value, received "${input}".`);
6364
+ return search;
5926
6365
  }
5927
- function emitSchemasTable(stdout, schemas) {
5928
- printTable(
5929
- schemas.map((schema) => ({
5930
- id: schema.id ?? "",
5931
- name: schema.name ?? "",
5932
- slug: schema.slug ?? "",
5933
- auditable: schema.auditable ?? "",
5934
- commentable: schema.commentable ?? "",
5935
- ...folderColumns(schema.folder)
5936
- })),
5937
- ["id", "name", "slug", "auditable", "commentable", ...FOLDER_TABLE_KEYS],
5938
- stdout
5939
- );
6366
+ function collectSelectValues(value, previous = []) {
6367
+ return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--select")]);
5940
6368
  }
5941
- function emitFieldsTable(stdout, fields) {
5942
- printTable(
5943
- fields.map((field) => ({
5944
- id: field.id ?? "",
5945
- type: field.type ?? "",
5946
- slug: field.slug ?? "",
5947
- label: field.label ?? "",
5948
- required: field.required ?? ""
5949
- })),
5950
- ["id", "type", "slug", "label", "required"],
5951
- stdout
5952
- );
6369
+ function collectSortValues(value, previous = []) {
6370
+ return dedupeStrings([...previous, ...parseCommaSeparatedValues(value, "--sort")]);
5953
6371
  }
5954
- function buildSchemaUpdateInput(options) {
5955
- const input = {};
5956
- if (options.name !== void 0) {
5957
- input.name = options.name;
5958
- }
5959
- if (options.slug !== void 0) {
5960
- input.slug = options.slug;
5961
- }
5962
- if (options.auditable !== void 0) {
5963
- input.auditable = options.auditable;
5964
- }
5965
- if (options.commentable !== void 0) {
5966
- input.commentable = options.commentable;
5967
- }
5968
- return input;
6372
+ function collectWhereExpressions(value, previous = []) {
6373
+ return [...previous, parseExpressionValue(value)];
5969
6374
  }
5970
- function applyFieldDefaultValue(input, defaultValue) {
5971
- if (defaultValue === void 0) {
5972
- return;
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
+ }
5973
6382
  }
5974
- const config = input.config;
5975
- if (config !== void 0 && !isJsonObject(config)) {
6383
+ return { head: input.trim() };
6384
+ }
6385
+ function parseGroupBy(input) {
6386
+ const { head, suffix } = splitKnownSuffix(input, AGGREGATE_BUCKETS);
6387
+ if (!head) {
5976
6388
  throw new CliError(
5977
6389
  "invalid_cli_usage",
5978
- 'Expected field "config" to be a JSON object when using "--default".'
6390
+ `Invalid --group-by "${input}": expected <field>[:<bucket>] with bucket one of ${AGGREGATE_BUCKETS.join(", ")}.`
5979
6391
  );
5980
6392
  }
5981
- input.config = {
5982
- ...config ?? {},
5983
- defaultValue
5984
- };
6393
+ return suffix ? { field: head, bucket: suffix } : { field: head };
5985
6394
  }
5986
- function buildFieldCreateInput(options) {
5987
- const raw = normalizeSchemaFieldCreatePayload(readRawObject(options.raw, options.rawFile));
5988
- const rawType = typeof raw.type === "string" ? raw.type : void 0;
5989
- const rawSlug = typeof raw.slug === "string" ? raw.slug : void 0;
5990
- const rawLabel = typeof raw.label === "string" ? raw.label : void 0;
5991
- const type = options.type ?? rawType;
5992
- const slug = options.slug ?? rawSlug;
5993
- const label = options.label ?? rawLabel;
5994
- if (!type) {
5995
- throw new CliError("invalid_cli_usage", 'Provide field type via "--type" or "--raw".');
5996
- }
5997
- if (!slug) {
5998
- throw new CliError("invalid_cli_usage", 'Provide field slug via "--slug" or "--raw".');
5999
- }
6000
- if (!label) {
6001
- throw new CliError("invalid_cli_usage", 'Provide field label via "--label" or "--raw".');
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);
6002
6405
  }
6003
- const normalizedType = normalizeSchemaFieldType(type);
6004
- assertSupportedSchemaFieldType(normalizedType);
6005
- const input = {
6006
- ...raw,
6007
- type: normalizedType,
6008
- slug,
6009
- label
6406
+ return {
6407
+ op,
6408
+ ...field !== void 0 ? { field } : {},
6409
+ ...alias !== void 0 ? { as: alias } : {}
6010
6410
  };
6011
- if (options.required !== void 0) {
6012
- input.required = options.required;
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
+ );
6013
6419
  }
6014
- if (options.description !== void 0) {
6015
- input.description = options.description;
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
+ );
6016
6429
  }
6017
- applyFieldDefaultValue(input, options.default);
6018
- if ("config" in input && isJsonObject(input.config) && isEmptyObject(input.config)) {
6019
- delete input.config;
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;
6020
6451
  }
6021
- return input;
6452
+ for (const assignment of jsonAssignments) {
6453
+ output[assignment.key] = assignment.value;
6454
+ }
6455
+ return output;
6022
6456
  }
6023
- function readBackendErrorMessage(error) {
6024
- const responseBody = typeof error.responseBody === "object" && error.responseBody !== null ? error.responseBody : void 0;
6025
- const envelopeError = responseBody && "error" in responseBody && typeof responseBody.error === "object" && responseBody.error !== null ? responseBody.error : responseBody;
6026
- 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);
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
+ }));
6027
6466
  }
6028
- function toFieldCreateError(error, input) {
6029
- if (!(error instanceof ApiClientError)) {
6030
- throw error;
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
+ );
6031
6477
  }
6032
- const backendMessage = readBackendErrorMessage(error);
6033
- const isGenericValidationMessage = backendMessage === "Schema payload is invalid. One or more fields are invalid." || backendMessage === "Create field payload is invalid.";
6034
- if (!isGenericValidationMessage) {
6035
- throw error;
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
+ );
6036
6483
  }
6037
- throw new CliError(
6038
- "invalid_cli_usage",
6039
- buildSchemaFieldCreateValidationMessage(input.type),
6040
- {
6041
- fieldType: input.type,
6042
- status: error.status
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
+ );
6043
6494
  }
6044
- );
6495
+ return parseWhereJson(options.whereJson);
6496
+ }
6497
+ return where;
6045
6498
  }
6046
- function buildFieldUpdateInput(currentType, options) {
6047
- const input = {
6048
- ...normalizeSchemaFieldUpdatePayload(
6049
- currentType,
6050
- readRawObject(options.raw, options.rawFile)
6051
- ),
6052
- type: currentType
6053
- };
6054
- if (options.label !== void 0) {
6055
- input.label = options.label;
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;
6056
6507
  }
6057
- if (options.required !== void 0) {
6058
- input.required = options.required;
6508
+ if (options.search !== void 0) {
6509
+ input.search = buildSearch(options);
6059
6510
  }
6060
- if (options.description !== void 0) {
6061
- input.description = options.description;
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;
6062
6519
  }
6063
- applyFieldDefaultValue(input, options.default);
6064
6520
  return input;
6065
6521
  }
6066
- async function resolveSchemaSelector2(api, selector) {
6067
- if (selector.kind === "uuid") {
6068
- return selector;
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;
6069
6527
  }
6070
- const schemas = await api.listSchemas();
6071
- const match = schemas.find((schema) => schema.slug === selector.value);
6072
- if (!match || typeof match.id !== "string") {
6073
- throw new CliError("invalid_cli_usage", `Schema "${selector.value}" not found.`);
6528
+ if (options.search !== void 0) {
6529
+ input.search = buildSearch(options);
6074
6530
  }
6075
- return {
6076
- kind: "uuid",
6077
- value: match.id
6078
- };
6079
- }
6080
- async function resolveFieldSelector(api, schema, selector) {
6081
- if (selector.kind === "uuid") {
6082
- return selector;
6531
+ if (options.groupBy && options.groupBy.length > 0) {
6532
+ input.groupBy = [...options.groupBy];
6083
6533
  }
6084
- const fields = await api.listFields(schema);
6085
- const match = fields.find((field) => field.slug === selector.value);
6086
- if (!match || typeof match.id !== "string") {
6087
- throw new CliError("invalid_cli_usage", `Field "${selector.value}" not found.`);
6534
+ if (options.metric && options.metric.length > 0) {
6535
+ input.metrics = [...options.metric];
6088
6536
  }
6089
- return {
6090
- kind: "uuid",
6091
- value: match.id
6092
- };
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;
6093
6547
  }
6094
- function registerSchemasCommands(program, options = {}) {
6095
- const filePath = options.configPath ?? defaultConfigPath;
6096
- const stdout = options.stdout ?? process.stdout;
6097
- const schemas = program.command("schemas").description("Manage schemas and schema fields");
6098
- schemas.command("list").description("List schemas").action(async function action() {
6099
- const { api, json } = createSchemasApi(this, filePath);
6100
- const data = await api.listSchemas();
6101
- if (json) {
6102
- emitJson(stdout, "schemas list", data, filePath);
6103
- return;
6104
- }
6105
- emitSchemasTable(stdout, data);
6106
- });
6107
- schemas.command("get").description("Get a schema by UUID or slug").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
6108
- const { api, json } = createSchemasApi(this, filePath);
6109
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6110
- const data = await api.getSchema(resolvedSchema);
6111
- if (json) {
6112
- emitJson(stdout, "schemas get", data, filePath);
6113
- return;
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)";
6114
6553
  }
6115
- emitSchemasTable(stdout, [data]);
6116
- });
6117
- 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) {
6118
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6119
- ensureWritable("schemas create", readOnly, "write");
6120
- const input = {
6121
- name: commandOptions.name,
6122
- slug: commandOptions.slug,
6123
- auditable: Boolean(commandOptions.auditable),
6124
- commentable: Boolean(commandOptions.commentable)
6125
- };
6126
- const data = await api.createSchema(input);
6127
- if (json) {
6128
- emitJson(stdout, "schemas create", data, filePath);
6129
- return;
6554
+ for (const [alias, value] of Object.entries(group.metrics ?? {})) {
6555
+ row[alias in row ? `${alias} (metric)` : alias] = value;
6130
6556
  }
6131
- writeLine(stdout, `Created schema "${data.slug ?? commandOptions.slug}".`);
6557
+ return row;
6132
6558
  });
6133
- 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(
6134
- "--highlighted-field <field>",
6135
- "its value is used as each record's display name in the UI (field uuid or slug)",
6136
- parseUuidOrSlugSelector
6137
- ).action(async function action(schema, commandOptions) {
6138
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6139
- ensureWritable("schemas update", readOnly, "write");
6140
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6141
- const input = buildSchemaUpdateInput(commandOptions);
6142
- if (commandOptions.highlightedField !== void 0) {
6143
- const resolvedField = await resolveFieldSelector(
6144
- api,
6145
- resolvedSchema,
6146
- commandOptions.highlightedField
6147
- );
6148
- input.highlightedField = resolvedField.value;
6149
- }
6150
- if (isEmptyObject(input)) {
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
+ );
6570
+ }
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
+ );
6580
+ }
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
+ );
6586
+ }
6587
+ if (parsed.length === 0) {
6588
+ throw new CliError(
6589
+ "invalid_cli_usage",
6590
+ `--records-file ${path} must contain at least one record.`
6591
+ );
6592
+ }
6593
+ return parsed.map((record, index) => {
6594
+ if (!isJsonObject(record)) {
6151
6595
  throw new CliError(
6152
6596
  "invalid_cli_usage",
6153
- 'Provide at least one schema field to update via "--name", "--slug", "--auditable", "--commentable", or "--highlighted-field".'
6597
+ `Record at index ${index} in --records-file ${path} must be a JSON object.`
6154
6598
  );
6155
6599
  }
6156
- const data = await api.updateSchema(resolvedSchema, input);
6157
- if (json) {
6158
- emitJson(stdout, "schemas update", data, filePath);
6159
- return;
6160
- }
6161
- writeLine(stdout, `Updated schema "${data.slug ?? schema.value}".`);
6162
- }).addHelpText("after", HIGHLIGHTED_FIELD_HELP);
6163
- 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(
6164
- "--field <field>",
6165
- "field uuid or slug to include in the unique constraint (repeatable)",
6166
- collectFieldSelectors,
6167
- []
6168
- ).option("--clear", "clear the unique constraint (sends an empty field list)").action(async function action(schema, commandOptions) {
6169
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6170
- ensureWritable("schemas set-unique-fields", readOnly, "write");
6171
- const selectors = commandOptions.field ?? [];
6172
- if (commandOptions.clear && selectors.length > 0) {
6600
+ return record;
6601
+ });
6602
+ }
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) {
6173
6607
  throw new CliError(
6174
6608
  "invalid_cli_usage",
6175
- 'Use either "--field" or "--clear", not both.'
6609
+ 'Provide either "--records-file" or the single-record flags (--set/--set-json/--raw/--raw-file), not both.'
6176
6610
  );
6177
6611
  }
6178
- if (!commandOptions.clear && selectors.length === 0) {
6179
- throw new CliError(
6180
- "invalid_cli_usage",
6181
- 'Provide at least one field via "--field", or pass "--clear" to remove the unique constraint.'
6182
- );
6612
+ return readRecordsFromFile(options.recordsFile);
6613
+ }
6614
+ const values = {
6615
+ ...readRawObject(options.raw, options.rawFile),
6616
+ ...buildAssignmentObject(options.set, options.setJson)
6617
+ };
6618
+ if (isEmptyObject(values)) {
6619
+ throw new CliError(
6620
+ "invalid_cli_usage",
6621
+ 'Provide record fields via "--set", "--set-json", "--raw", "--raw-file", or load multiple records with "--records-file".'
6622
+ );
6623
+ }
6624
+ return [values];
6625
+ }
6626
+ function buildRecordUpdateInput(options) {
6627
+ const raw = readRawObject(options.raw, options.rawFile);
6628
+ const input = {};
6629
+ const setPayload = {
6630
+ ...raw,
6631
+ ...buildAssignmentObject(options.set, options.setJson)
6632
+ };
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);
6183
6638
  }
6184
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6185
- const fields2 = selectors.some((selector) => selector.kind === "slug") ? await api.listFields(resolvedSchema) : [];
6186
- const input = {
6187
- fieldIds: selectors.map((selector) => {
6188
- if (selector.kind === "uuid") {
6189
- return selector.value;
6190
- }
6191
- const match = fields2.find((field) => field.slug === selector.value);
6192
- if (!match || typeof match.id !== "string") {
6193
- throw new CliError("invalid_cli_usage", `Field "${selector.value}" not found.`);
6194
- }
6195
- return match.id;
6196
- })
6197
- };
6198
- const data = await api.setUniqueFields(resolvedSchema, input);
6639
+ }
6640
+ if (Object.keys(setPayload).length > 0) {
6641
+ input.set = setPayload;
6642
+ } else {
6643
+ delete input.set;
6644
+ }
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
+ );
6655
+ }
6656
+ return input;
6657
+ }
6658
+ function getQueryRecords(result) {
6659
+ return Array.isArray(result.records) ? result.records : [];
6660
+ }
6661
+ function getRecordIdentifier(record) {
6662
+ return typeof record.recordId === "string" ? record.recordId : "unknown";
6663
+ }
6664
+ async function resolveSchemaSelector2(api, selector) {
6665
+ if (selector.kind === "uuid") {
6666
+ return selector;
6667
+ }
6668
+ const schemas = await api.listSchemas();
6669
+ const match = schemas.find((entry) => entry.slug === selector.value);
6670
+ if (!match || typeof match.id !== "string") {
6671
+ throw new CliError("invalid_cli_usage", `Schema "${selector.value}" not found.`);
6672
+ }
6673
+ return {
6674
+ kind: "uuid",
6675
+ value: match.id
6676
+ };
6677
+ }
6678
+ function registerRecordsCommands(program, options = {}) {
6679
+ const filePath = options.configPath ?? defaultConfigPath;
6680
+ const stdout = options.stdout ?? process.stdout;
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);
6199
6690
  if (json) {
6200
- emitJson(stdout, "schemas set-unique-fields", data, filePath);
6691
+ emitJson(
6692
+ stdout,
6693
+ "records list",
6694
+ recordsData,
6695
+ filePath,
6696
+ data.page ? { page: data.page } : {}
6697
+ );
6201
6698
  return;
6202
6699
  }
6203
- if (input.fieldIds.length === 0) {
6204
- writeLine(stdout, `Cleared unique fields on schema "${schema.value}".`);
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,
6706
+ []
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);
6727
+ if (json) {
6728
+ emitJson(
6729
+ stdout,
6730
+ "records query",
6731
+ recordsData,
6732
+ filePath,
6733
+ data.page ? { page: data.page } : {}
6734
+ );
6205
6735
  return;
6206
6736
  }
6207
- const count = input.fieldIds.length;
6208
- writeLine(
6209
- stdout,
6210
- `Set unique fields on schema "${schema.value}" (${count} field${count === 1 ? "" : "s"}).`
6211
- );
6737
+ emitTable(stdout, recordsData);
6212
6738
  });
6213
- schemas.command("delete").description("Delete a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
6214
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6215
- ensureWritable("schemas delete", readOnly, "destructive");
6216
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6217
- await api.deleteSchema(resolvedSchema);
6218
- const data = {
6219
- schema: resolvedSchema.value,
6220
- deleted: true
6221
- };
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 : [];
6222
6781
  if (json) {
6223
- emitJson(stdout, "schemas delete", data, filePath);
6782
+ emitJson(
6783
+ stdout,
6784
+ "records aggregate",
6785
+ groups,
6786
+ filePath,
6787
+ data.meta ? { aggregate: data.meta } : {}
6788
+ );
6224
6789
  return;
6225
6790
  }
6226
- 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
+ }
6227
6798
  });
6228
- const fields = schemas.command("fields").description("Manage schema fields");
6229
- fields.command("list").description("List fields for a schema").argument("<schema>", "schema uuid or slug", parseUuidOrSlugSelector).action(async function action(schema) {
6230
- const { api, json } = createSchemasApi(this, filePath);
6231
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6232
- 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);
6233
6803
  if (json) {
6234
- emitJson(stdout, "schemas fields list", data, filePath);
6804
+ emitJson(stdout, "records get", data, filePath);
6235
6805
  return;
6236
6806
  }
6237
- emitFieldsTable(stdout, data);
6807
+ emitTable(stdout, data);
6238
6808
  });
6239
- 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) {
6240
- const { api, json } = createSchemasApi(this, filePath);
6241
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6242
- const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
6243
- 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);
6244
6823
  if (json) {
6245
- emitJson(stdout, "schemas fields get", data, filePath);
6824
+ emitJson(stdout, "records create", data, filePath);
6246
6825
  return;
6247
6826
  }
6248
- emitFieldsTable(stdout, [data]);
6249
- });
6250
- 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) {
6251
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6252
- ensureWritable("schemas fields create", readOnly, "write");
6253
- const input = buildFieldCreateInput(commandOptions);
6254
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6255
- let data;
6256
- try {
6257
- data = await api.createField(resolvedSchema, input);
6258
- } catch (error) {
6259
- 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
+ }
6260
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
+ );
6261
6849
  if (json) {
6262
- emitJson(stdout, "schemas fields create", data, filePath);
6850
+ emitJson(stdout, "records update", data, filePath);
6263
6851
  return;
6264
6852
  }
6265
- writeLine(stdout, `Created field "${data.slug ?? commandOptions.slug}".`);
6853
+ writeLine(stdout, `Updated record "${getRecordIdentifier(data)}".`);
6266
6854
  });
6267
- 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) {
6268
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6269
- ensureWritable("schemas fields update", readOnly, "write");
6270
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6271
- const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
6272
- const currentField = await api.getField(resolvedSchema, resolvedField);
6273
- const currentType = typeof currentField.type === "string" && currentField.type.length > 0 ? currentField.type : void 0;
6274
- if (!currentType) {
6275
- throw new CliError("invalid_cli_usage", `Field "${field.value}" is missing type metadata.`);
6276
- }
6277
- const input = buildFieldUpdateInput(currentType, commandOptions);
6278
- if (isEmptyObject(input)) {
6279
- throw new CliError(
6280
- "invalid_cli_usage",
6281
- 'Provide at least one field update via "--label", "--description", "--required", "--default", "--raw", or "--raw-file".'
6282
- );
6283
- }
6284
- 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);
6285
6864
  if (json) {
6286
- emitJson(stdout, "schemas fields update", data, filePath);
6865
+ emitJson(stdout, "records delete", data, filePath);
6287
6866
  return;
6288
6867
  }
6289
- writeLine(stdout, `Updated field "${data.slug ?? field.value}".`);
6868
+ writeLine(
6869
+ stdout,
6870
+ `Deleted ${recordIds.length} record(s) from schema "${schema.value}".`
6871
+ );
6290
6872
  });
6291
- 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) {
6292
- const { api, json, readOnly } = createSchemasApi(this, filePath);
6293
- ensureWritable("schemas fields delete", readOnly, "destructive");
6294
- const resolvedSchema = await resolveSchemaSelector2(api, schema);
6295
- const resolvedField = await resolveFieldSelector(api, resolvedSchema, field);
6296
- await api.deleteField(resolvedSchema, resolvedField);
6297
- const data = {
6298
- schema: resolvedSchema.value,
6299
- field: resolvedField.value,
6300
- deleted: true
6301
- };
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);
6302
6878
  if (json) {
6303
- emitJson(stdout, "schemas fields delete", data, filePath);
6879
+ emitJson(stdout, "records clear", data, filePath);
6304
6880
  return;
6305
6881
  }
6306
- writeLine(stdout, `Deleted field "${field.value}" from schema "${schema.value}".`);
6882
+ writeLine(stdout, `Cleared all records from schema "${schema.value}".`);
6307
6883
  });
6308
6884
  }
6309
6885
 
@@ -6518,7 +7094,7 @@ function registerSessionCommands(program, options = {}) {
6518
7094
  import { readFileSync as readFileSync6 } from "fs";
6519
7095
 
6520
7096
  // src/api/teamspace.ts
6521
- function jsonOptions8(body, method) {
7097
+ function jsonOptions9(body, method) {
6522
7098
  return {
6523
7099
  method,
6524
7100
  headers: {
@@ -6545,13 +7121,13 @@ var TeamspaceApi = class {
6545
7121
  createFolder(input) {
6546
7122
  return this.client.requestJson(
6547
7123
  "/api/v2/teamspaces/folders",
6548
- jsonOptions8(input, "POST")
7124
+ jsonOptions9(input, "POST")
6549
7125
  );
6550
7126
  }
6551
7127
  updateFolder(folder, input) {
6552
7128
  return this.client.requestJson(
6553
7129
  `/api/v2/teamspaces/folders/${folder.value}`,
6554
- jsonOptions8(input, "PATCH")
7130
+ jsonOptions9(input, "PATCH")
6555
7131
  );
6556
7132
  }
6557
7133
  deleteFolder(folder) {
@@ -6563,13 +7139,13 @@ var TeamspaceApi = class {
6563
7139
  publishResource(input) {
6564
7140
  return this.client.requestJson(
6565
7141
  "/api/v2/teamspaces/resources:publish",
6566
- jsonOptions8(input, "POST")
7142
+ jsonOptions9(input, "POST")
6567
7143
  );
6568
7144
  }
6569
7145
  unpublishResource(resourceId) {
6570
7146
  return this.client.requestJson(
6571
7147
  "/api/v2/teamspaces/resources:unpublish",
6572
- jsonOptions8({ resourceId }, "POST")
7148
+ jsonOptions9({ resourceId }, "POST")
6573
7149
  );
6574
7150
  }
6575
7151
  };
@@ -6789,7 +7365,7 @@ function registerTeamspaceCommands(program, options = {}) {
6789
7365
  var require2 = createRequire(import.meta.url);
6790
7366
  var { version } = require2("../package.json");
6791
7367
  function buildProgram(options = {}) {
6792
- const program = new Command4();
7368
+ const program = new Command5();
6793
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");
6794
7370
  registerProfilesCommands(program, options);
6795
7371
  registerSessionCommands(program, options);
@@ -6798,6 +7374,7 @@ function buildProgram(options = {}) {
6798
7374
  registerDisplaysCommands(program, options);
6799
7375
  registerDocumentTemplatesCommands(program, options);
6800
7376
  registerFilesCommands(program, options);
7377
+ registerFormsCommands(program, options);
6801
7378
  registerFormulasCommands(program, options);
6802
7379
  registerNavigationCommands(program, options);
6803
7380
  registerSchemasCommands(program, options);