@erdoai/cli 0.203.0 → 0.205.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.
- package/dist/index.js +100 -10
- 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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);
|