@erdoai/cli 0.203.0 → 0.204.0

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.
Files changed (2) hide show
  1. package/dist/index.js +100 -10
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -1759,6 +1759,12 @@ var ErdoClient = class {
1759
1759
  updateDatasetSchema(slug, input) {
1760
1760
  return this.request("POST", `/v1/datasets/${encodeURIComponent(slug)}/schema`, input);
1761
1761
  }
1762
+ // Owner, record role and row provenance are declarations on a durable
1763
+ // dataset, set through the same schema route as class and purpose so one
1764
+ // owner (the dataset service) validates and persists them.
1765
+ setDatasetStewardship(slug, input) {
1766
+ return this.updateDatasetSchema(slug, input);
1767
+ }
1762
1768
  // Dataset row writes are deliberately never replayed after a network
1763
1769
  // failure: the server may have committed the rows before the response was
1764
1770
  // lost, and repeating an append or upsert can change the result.
@@ -8810,7 +8816,7 @@ datasetsCmd.command("ensure <purpose>").description(
8810
8816
  fail(e);
8811
8817
  }
8812
8818
  });
8813
- datasetsCmd.command("update-schema <slug>").description("Evolve an existing dataset's column contract. For populated lead-identity datasets, use add_column operations only; existing rows and lead ids are preserved.").requiredOption("--input <file>", "JSON request containing operations and optional class/purpose changes").action(async (slug, opts) => {
8819
+ datasetsCmd.command("update-schema <slug>").description("Evolve an existing dataset's column contract. For populated lead-identity datasets, use add_column operations only; existing rows and lead ids are preserved.").requiredOption("--input <file>", "JSON request containing operations and optional class/purpose/owner/record/provenance changes").action(async (slug, opts) => {
8814
8820
  try {
8815
8821
  const input = JSON.parse(readFileSync5(opts.input, "utf8"));
8816
8822
  if (!input || typeof input !== "object" || Array.isArray(input)) {
@@ -8834,6 +8840,91 @@ datasetsCmd.command("delete <slug>").description("Permanently delete a dataset a
8834
8840
  fail(e);
8835
8841
  }
8836
8842
  });
8843
+ function printDatasetStewardship(res) {
8844
+ if (!res) return;
8845
+ const lines = [];
8846
+ if (res.owner) {
8847
+ const who = res.owner.email || res.owner.user_id;
8848
+ lines.push(["owner", res.owner.name ? `${res.owner.name} <${who}>` : who]);
8849
+ }
8850
+ if (res.record_role === "mirror") lines.push(["record", `mirror of ${res.record_of || "(unnamed system)"}`]);
8851
+ else if (res.record_role) lines.push(["record", "this dataset is the record"]);
8852
+ if (res.row_provenance) {
8853
+ lines.push(["provenance", `required: every row needs ${res.row_provenance.source_column} and ${res.row_provenance.checked_at_column}`]);
8854
+ }
8855
+ if (!lines.length) return;
8856
+ console.log("");
8857
+ printAlignedTable(["declares", "value"], lines);
8858
+ }
8859
+ function printStewardshipResult(slug, res) {
8860
+ console.log(slug);
8861
+ if (res.stewardship) printDatasetStewardship(res.stewardship);
8862
+ else console.log("(no owner, record role or provenance requirement declared)");
8863
+ }
8864
+ datasetsCmd.command("set-owner <slug> [owner]").description(
8865
+ "Name the person who answers for a durable dataset: their email, user id, or `me`. The owner must be a member of the dataset's organization. Ownership is accountability, not access; sharing still decides who can read or edit."
8866
+ ).option("--clear", "remove the dataset's owner").action(async (slug, owner, opts) => {
8867
+ try {
8868
+ if (opts.clear === Boolean(owner)) {
8869
+ fail(new Error("pass an owner to set, or --clear to remove one"));
8870
+ return;
8871
+ }
8872
+ const res = await new ErdoClient().setDatasetStewardship(slug, opts.clear ? { clear_owner: true } : { owner });
8873
+ printStewardshipResult(slug, res);
8874
+ } catch (e) {
8875
+ fail(e);
8876
+ }
8877
+ });
8878
+ datasetsCmd.command("set-record <slug> [role]").description(
8879
+ 'Say whether a durable dataset is the record for its rows (`record`) or a copy of a record another system holds (`mirror`, with --of naming it, e.g. "Attio people"), so people fix a fact once, in the right place.'
8880
+ ).option("--of <system>", "with mirror: where the record lives").option("--clear", "remove the dataset's record role").action(async (slug, role, opts) => {
8881
+ try {
8882
+ if (opts.clear) {
8883
+ if (role || opts.of) {
8884
+ fail(new Error("pass a role or --clear, not both"));
8885
+ return;
8886
+ }
8887
+ printStewardshipResult(slug, await new ErdoClient().setDatasetStewardship(slug, { clear_record_role: true }));
8888
+ return;
8889
+ }
8890
+ if (role !== "record" && role !== "mirror") {
8891
+ fail(new Error("pass `record` or `mirror` (with --of <system>), or --clear"));
8892
+ return;
8893
+ }
8894
+ if (role === "mirror" && !opts.of?.trim()) {
8895
+ fail(new Error('a mirror needs --of naming where the record lives, e.g. --of "Attio people"'));
8896
+ return;
8897
+ }
8898
+ if (role === "record" && opts.of) {
8899
+ fail(new Error("--of applies only to mirror; a record dataset is itself the record"));
8900
+ return;
8901
+ }
8902
+ printStewardshipResult(slug, await new ErdoClient().setDatasetStewardship(slug, {
8903
+ record_role: role,
8904
+ ...opts.of ? { record_of: opts.of } : {}
8905
+ }));
8906
+ } catch (e) {
8907
+ fail(e);
8908
+ }
8909
+ });
8910
+ datasetsCmd.command("require-provenance <slug>").description(
8911
+ "Require every row of a durable dataset to say where its facts came from and when they were last checked. Later writes whose rows leave either column blank are refused, naming the rows. Both columns must be in the declared schema when the dataset has one. Use --off to remove the requirement."
8912
+ ).option("--source-column <name>", "column holding each row's source (default source_url)").option("--checked-at-column <name>", "column holding when each row was last checked (default checked_at)").option("--off", "remove the requirement").action(async (slug, opts) => {
8913
+ try {
8914
+ if (opts.off && (opts.sourceColumn || opts.checkedAtColumn)) {
8915
+ fail(new Error("--off removes the requirement; it takes no column names"));
8916
+ return;
8917
+ }
8918
+ const res = await new ErdoClient().setDatasetStewardship(slug, opts.off ? { provenance_required: false } : {
8919
+ provenance_required: true,
8920
+ ...opts.sourceColumn ? { provenance_source_column: opts.sourceColumn } : {},
8921
+ ...opts.checkedAtColumn ? { provenance_checked_at_column: opts.checkedAtColumn } : {}
8922
+ });
8923
+ printStewardshipResult(slug, res);
8924
+ } catch (e) {
8925
+ fail(e);
8926
+ }
8927
+ });
8837
8928
  datasetsCmd.command("set-purpose <slug> [purpose]").description(
8838
8929
  "Set (or with --clear, remove) the dataset's purpose \u2014 the org-vocabulary role `datasets purposes` reports. Use it to CORRECT a purpose that names the wrong dataset: one purpose maps to one dataset per org, so a purpose left on the wrong one points everything that resolves through the vocabulary at the wrong rows. Setting a purpose another dataset carries is an atomic MOVE: the old carrier is cleared in the same transaction, so one call on the right dataset lands it (the response says which dataset it moved from). Use --sibling only when deliberately running a parallel table for the same purpose."
8839
8930
  ).option("--clear", "remove the dataset's purpose instead of setting one").option(
@@ -8984,7 +9075,7 @@ Read one with: erdo datasets fetch ${res.dataset_slug} --revision <id> --sql "SE
8984
9075
  });
8985
9076
  datasetsCmd.command("schema <slug>").alias("describe").description(
8986
9077
  "Show physical columns by default, or the declared write contract with --declared. File datasets read the stored `data` table; integration datasets show their discovered resource tables and columns. For an integration dataset, choose a resource/table explicitly when fetching: `datasets fetch <slug> --sql 'SELECT * FROM <table>'`."
8987
- ).option("--json", "print the raw JSON result instead of a table").option("--declared", "read the declared write contract (column names, type hints, required flags, semantic roles, currency) instead of the physical columns").action(async (slug, opts) => {
9078
+ ).option("--json", "print the raw JSON result instead of a table").option("--declared", "read the declared write contract (column names, type hints, required flags, semantic roles, currency, plus the dataset's owner, record role and provenance requirement) instead of the physical columns").action(async (slug, opts) => {
8988
9079
  try {
8989
9080
  const client = new ErdoClient();
8990
9081
  if (opts.declared) {
@@ -9000,16 +9091,15 @@ datasetsCmd.command("schema <slug>").alias("describe").description(
9000
9091
  }
9001
9092
  if (schema == null) {
9002
9093
  console.log(`${slug} has no declared column contract. Use datasets schema ${slug} to inspect physical columns.`);
9003
- return;
9004
- }
9005
- if (!schema.columns.length) {
9094
+ } else if (!schema.columns.length) {
9006
9095
  console.log(`${slug}'s declared column contract contains no columns.`);
9007
- return;
9096
+ } else {
9097
+ printAlignedTable(
9098
+ ["column", "type", "required", "semantic role", "currency", "description"],
9099
+ schema.columns.map((column) => [column.name, column.type || "", column.required ? "yes" : "no", column.semantic_role || "", column.currency || "", column.description || ""])
9100
+ );
9008
9101
  }
9009
- printAlignedTable(
9010
- ["column", "type", "required", "semantic role", "currency", "description"],
9011
- schema.columns.map((column) => [column.name, column.type || "", column.required ? "yes" : "no", column.semantic_role || "", column.currency || "", column.description || ""])
9012
- );
9102
+ printDatasetStewardship(res2.stewardship);
9013
9103
  return;
9014
9104
  }
9015
9105
  const res = await client.getDatasetResourceSchema(slug);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@erdoai/cli",
3
- "version": "0.203.0",
3
+ "version": "0.204.0",
4
4
  "description": "Erdo CLI \u2014 drive datasets, pages, and evals from the terminal or CI",
5
5
  "type": "module",
6
6
  "bin": {