@erdoai/cli 0.100.0 → 0.101.1

package/dist/index.js

@@ -1072,22 +1072,27 @@ var ErdoClient = class {
     const qs = q.toString();
     return this.request("GET", `/v1/datasets${qs ? `?${qs}` : ""}`);
   }
-  // The org's dataset vocabulary: every purpose in use, its description, and
-  // the dataset that established it (the canonical write target for that role).
+  // The org's dataset vocabulary: every purpose in use, its current dataset,
+  // and the declared producer contract on that same dataset.
   // scope="managed" reads the same across every client organization a manager
   // account operates; each entry then names its organization and its
-  // established_by slug is org-qualified, so it can be queried as-is.
+  // current dataset slug is org-qualified, so it can be queried as-is.
   listDatasetPurposes(params) {
     const q = new URLSearchParams();
     if (params?.scope) q.set("scope", params.scope);
     const qs = q.toString();
     return this.request("GET", `/v1/datasets-purposes${qs ? `?${qs}` : ""}`);
   }
+  ensureDataset(input) {
+    return this.request("POST", "/v1/datasets-ensure", input);
+  }
   // Correct which dataset carries a purpose. Pass `purpose` to set one,
-  // `clear_purpose` to remove it; moving a purpose is clearing it from the old
-  // dataset and setting it on the right one. Setting a purpose the org already
-  // uses elsewhere succeeds and answers with a warning naming what it shadows,
-  // since one purpose is meant to map to one dataset.
+  // `clear_purpose` to remove it. Setting a purpose another dataset carries is
+  // an atomic MOVE — the old carrier is cleared in the same transaction — and
+  // the response warns naming the dataset it moved from. Pass
+  // `purpose_sibling: true` only to declare a deliberate parallel carrier (a
+  // separate program a human chose to run), which leaves the other carriers
+  // alone.
   setDatasetPurpose(slug, input) {
     return this.request("POST", `/v1/datasets/${encodeURIComponent(slug)}/schema`, input);
   }
@@ -6097,7 +6102,7 @@ datasetsCmd.command("list").description("List datasets").option(
   }
 });
 datasetsCmd.command("purposes").description(
-  "List the org's dataset purposes \u2014 the vocabulary of dataset roles in use (e.g. leads, page events). The established_by slug is the canonical dataset for that role: write there rather than creating a sibling (one purpose = one dataset per org)."
+  "List the org's dataset purposes \u2014 the vocabulary of dataset roles in use (e.g. leads, page events). Each purpose resolves to the current dataset and its declared schema: write there rather than creating a sibling (one purpose = one dataset per org)."
 ).option(
   "--scope <own|managed>",
   "whose vocabulary to read: own (default) or managed, which reads every client organization a manager account operates and prints the organization alongside each purpose"
@@ -6114,7 +6119,7 @@ datasetsCmd.command("purposes").description(
       return;
     }
     for (const p of purposes) {
-      const target = p.established_by_dataset_slug ?? p.established_by_dataset_id;
+      const target = p.dataset_count > 1 ? `(split: ${p.dataset_count} datasets)` : p.dataset_slug ?? p.dataset_id ?? "(unbound)";
       const count = `${p.dataset_count} dataset${p.dataset_count === 1 ? "" : "s"}`;
       console.log(
         scope === "managed" ? `${p.organization_slug ?? "-"}	${p.purpose}	${target}	${count}	${p.description}` : `${p.purpose}	${target}	${count}	${p.description}`
@@ -6124,9 +6129,36 @@ datasetsCmd.command("purposes").description(
     fail(e);
   }
 });
+datasetsCmd.command("ensure <purpose>").description(
+  "Create or reuse the one dataset for a purpose and verify its declared producer contract. Refuses legacy splits and incompatible populated datasets instead of choosing silently."
+).requiredOption("--schema <file>", "JSON file containing { columns: [...] } or a columns array").option("--name <name>", "dataset name when creation is required").option("--description <text>", "dataset description when creation is required").option("--purpose-description <text>", "what writes and reads this purpose").option("--preferred-dataset <slug>", "existing bound dataset slug or id to adopt").option("--email-column <name>", "for a leads purpose: which declared column holds the email (default email)").option("--phone-column <name>", "for a leads purpose: which declared column holds the phone (default phone)").action(async (purpose, opts) => {
+  try {
+    const parsed = JSON.parse(readFileSync4(opts.schema, "utf8"));
+    const declaredSchema = Array.isArray(parsed) ? { columns: parsed } : parsed;
+    if (!declaredSchema || !Array.isArray(declaredSchema.columns)) {
+      throw new Error('--schema must contain a JSON columns array or {"columns": [...]} object');
+    }
+    const result = await new ErdoClient().ensureDataset({
+      purpose,
+      ...opts.name ? { name: opts.name } : {},
+      ...opts.description ? { description: opts.description } : {},
+      ...opts.purposeDescription ? { purpose_description: opts.purposeDescription } : {},
+      ...opts.preferredDataset ? { preferred_dataset: opts.preferredDataset } : {},
+      ...opts.emailColumn ? { email_column: opts.emailColumn } : {},
+      ...opts.phoneColumn ? { phone_column: opts.phoneColumn } : {},
+      declared_schema: declaredSchema
+    });
+    console.log(`${result.slug}	${result.created ? "created" : "reused"}	${result.purpose}`);
+  } catch (e) {
+    fail(e);
+  }
+});
 datasetsCmd.command("set-purpose <slug> [purpose]").description(
-  "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. Moving a purpose is two calls \u2014 clear it from the old dataset, set it on the right one. Setting a purpose the org already uses elsewhere succeeds and prints a warning naming what it now shadows."
+  "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."
 ).option("--clear", "remove the dataset's purpose instead of setting one").option(
+  "--sibling",
+  "declare this dataset a deliberate parallel carrier of the purpose (a separate program a human chose to run) instead of moving the purpose off other datasets"
+).option(
   "--description <text>",
   "description for a purpose new to this org; ignored when the org already has an entry for it"
 ).action(async (slug, purpose, opts) => {
@@ -6142,6 +6174,7 @@ datasetsCmd.command("set-purpose <slug> [purpose]").description(
     const res = await new ErdoClient().setDatasetPurpose(slug, {
       ...purpose ? { purpose } : {},
       ...opts.clear ? { clear_purpose: true } : {},
+      ...opts.sibling ? { purpose_sibling: true } : {},
       ...opts.description ? { purpose_description: opts.description } : {}
     });
     for (const w of res.warnings ?? []) console.error(`warning: ${w}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdoai/cli",
-  "version": "0.100.0",
+  "version": "0.101.1",
   "description": "Erdo CLI — drive datasets, pages, and evals from the terminal or CI",
   "type": "module",
   "bin": {