@erdoai/cli 0.117.0 → 0.118.0

package/dist/index.js

@@ -1149,6 +1149,13 @@ var ErdoClient = class {
     const qs = q.toString();
     return this.request("GET", `/v1/datasets-purposes${qs ? `?${qs}` : ""}`);
   }
+  // Reads the declared write contract through the slug-addressed fetch route's
+  // declared_schema view. That route is the one a dataset-scoped API key can
+  // reach (and is confined to its own datasets there); the dataset-details
+  // route is not, because its response also names other datasets.
+  getDatasetDeclaredSchema(slug) {
+    return this.request("POST", `/v1/datasets/${encodeURIComponent(slug)}/fetch`, { view: "declared_schema" });
+  }
   // Create an empty dataset with its declared columns. The server refuses a
   // create without a schema unless the purpose's columns are platform-defined.
   createDataset(input) {
@@ -1583,6 +1590,15 @@ var ErdoClient = class {
     );
   }
   // --- knowledge ---
+  getKnowledge(id) {
+    return this.request("GET", `/v1/knowledge/${encodeURIComponent(id)}`);
+  }
+  updateKnowledge(id, input) {
+    return this.request("POST", `/v1/knowledge/${encodeURIComponent(id)}/actions`, {
+      action: "update",
+      ...input
+    });
+  }
   listKnowledge(visibility, options) {
     const params = new URLSearchParams();
     if (visibility) params.set("visibility", visibility);
@@ -1719,6 +1735,7 @@ var ErdoClient = class {
   // what the evidence said afterwards. Referenced by slug, never UUID.
   listDecisions(opts) {
     const params = new URLSearchParams();
+    if (opts.organization_slug) params.set("organization_slug", opts.organization_slug);
     if (opts.workstream_slug) params.set("workstream_slug", opts.workstream_slug);
     if (opts.source) params.set("source", opts.source);
     if (opts.decision_class) params.set("decision_class", opts.decision_class);
@@ -4254,7 +4271,7 @@ function renderReportEffect(e) {
     console.log(`    outcome: ${e.outcome_label}`);
   }
 }
-decisionsCmd.command("list").description("List decisions, newest first").option("--workstream <slug>", "only decisions filed under this workstream/Strategy").option(
+decisionsCmd.command("list").description("List decisions, newest first").option("--organization <slug>", "read an authorized client organization (default: active organization)").option("--workstream <slug>", "only decisions filed under this workstream/Strategy").option(
   "--source <source>",
   "producer family: approval | escalation | engine_gate | allocator | experiment | workstream_commitment"
 ).option("--class <class>", "decision class, e.g. paid_media.ad_group.pause").option("--subject-kind <kind>", "only decisions about this kind of subject").option("--subject-ref <id>", "only decisions about this exact subject").option(
@@ -4267,6 +4284,7 @@ decisionsCmd.command("list").description("List decisions, newest first").option(
   async (opts) => {
     try {
       const res = await new ErdoClient().listDecisions({
+        organization_slug: opts.organization,
         workstream_slug: opts.workstream,
         source: opts.source,
         decision_class: opts.class,
@@ -6747,10 +6765,36 @@ Read one with: erdo datasets fetch ${res.dataset_slug} --revision <id> --sql "SE
   }
 });
 datasetsCmd.command("schema <slug>").alias("describe").description(
-  "Show a dataset's physical columns \u2014 the names and types you can reference in `datasets fetch --sql`, read from the stored `data` table itself (DuckDB DESCRIBE) so they are what is actually there, not what was declared. For a database or warehouse dataset, DESCRIBE its real table names instead: `datasets fetch <slug> --sql 'DESCRIBE <table>'`."
-).option("--json", "print the raw JSON result instead of a table").action(async (slug, opts) => {
+  "Show physical columns by default, or the declared write contract with --declared. Physical columns are the names and types you can reference in `datasets fetch --sql`, read from the stored `data` table itself (DuckDB DESCRIBE) so they are what is actually there, not what was declared. For a database or warehouse dataset, DESCRIBE its real table names instead: `datasets fetch <slug> --sql 'DESCRIBE <table>'`."
+).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) instead of the physical columns").action(async (slug, opts) => {
   try {
-    const res = await new ErdoClient().fetchDatasetContents(slug, { sql_query: "DESCRIBE data" });
+    const client = new ErdoClient();
+    if (opts.declared) {
+      const res2 = await client.getDatasetDeclaredSchema(slug);
+      if (!res2 || typeof res2 !== "object" || res2.view !== "declared_schema")
+        throw new Error("Invalid dataset schema response: the server did not answer the declared_schema view");
+      const schema = res2.declared_schema;
+      if (schema != null && (!Array.isArray(schema.columns) || schema.columns.some((column) => !column || typeof column.name !== "string" || !column.name.trim())))
+        throw new Error("Invalid dataset schema response: declared columns are malformed");
+      if (opts.json) {
+        print(res2);
+        return;
+      }
+      if (schema == null) {
+        console.log(`${slug} has no declared column contract. Use datasets schema ${slug} to inspect physical columns.`);
+        return;
+      }
+      if (!schema.columns.length) {
+        console.log(`${slug}'s declared column contract contains no columns.`);
+        return;
+      }
+      printAlignedTable(
+        ["column", "type", "required", "semantic role", "description"],
+        schema.columns.map((column) => [column.name, column.type || "", column.required ? "yes" : "no", column.semantic_role || "", column.description || ""])
+      );
+      return;
+    }
+    const res = await client.fetchDatasetContents(slug, { sql_query: "DESCRIBE data" });
     if (opts.json) {
       print(res);
       return;
@@ -8050,7 +8094,7 @@ pipelinesCmd.command("get <slug>").description("Show one event pipeline \u2014 s
 });
 pipelinesCmd.command("update <slug>").description(
   "Update an event pipeline's editable fields \u2014 omitted fields keep their current values (merge). Use get first for the current transform/actions; --transform-js/--pipeline accept @file"
-).option("--name <name>", "new name").option("--description <description>", "new description").option("--state <state>", "new state: active, disabled, or proposed").option("--transform-js <jsOr@file>", "new transform \u2014 function transform(event) { \u2026 } (or @path to a file)").option("--turnstile <jsonOr@file>", `optional managed form protection settings; use @file for widget credentials, or '{"enabled":false}' to disable`).option(
+).option("--sample-payload <jsonOr@file>", "complete representative event used to validate and initialize target contracts; JSON or @path").option("--name <name>", "new name").option("--description <description>", "new description").option("--state <state>", "new state: active, disabled, or proposed").option("--transform-js <jsOr@file>", "new transform \u2014 function transform(event) { \u2026 } (or @path to a file)").option("--turnstile <jsonOr@file>", `optional managed form protection settings; use @file for widget credentials, or '{"enabled":false}' to disable`).option(
   "--pipeline <jsonOr@file>",
   `replacement ordered actions array as JSON (or @path to a file), e.g. '[{"type":"dataset.write","key_column":"email","dataset_slug":"acme-leads"}]'`
 ).action(
@@ -8083,10 +8127,18 @@ pipelinesCmd.command("update <slug>").description(
         fail(new Error(`--pipeline must be a JSON array of actions: ${e instanceof Error ? e.message : String(e)}`));
       }
     }
+    const sampleRaw = readMaybeFile(opts.samplePayload);
+    if (sampleRaw !== void 0) {
+      try {
+        body.sample_payload = JSON.parse(sampleRaw);
+      } catch {
+        fail(new Error("--sample-payload must be valid JSON"));
+      }
+    }
     if (Object.keys(body).length === 0) {
       fail(
         new Error(
-          "nothing to update \u2014 pass at least one of --name, --description, --state, --transform-js, --pipeline, --turnstile"
+          "nothing to update \u2014 pass at least one of --name, --description, --state, --transform-js, --pipeline, --turnstile, --sample-payload"
         )
       );
     }
@@ -8134,6 +8186,36 @@ pipelinesCmd.command("executions <slug>").description("Show an event pipeline's
   }
 });
 var knowledgeCmd = program.command("knowledge").description("Knowledge objects");
+knowledgeCmd.command("get <id>").description("Get one full typed Knowledge object, including links and related objects").action(async (id) => {
+  try {
+    print(await new ErdoClient().getKnowledge(id));
+  } catch (e) {
+    fail(e);
+  }
+});
+knowledgeCmd.command("update <id>").description("Update a Knowledge object while preserving fields omitted from the command").option("--body <value>", "new body text, or @file; pass an empty value to clear the body").option("--config <file>", "JSON object file containing the complete replacement config, or @file").option("--title <title>", "new title").action(async (id, opts) => {
+  try {
+    if (opts.title === void 0 && opts.body === void 0 && opts.config === void 0) {
+      throw new Error("provide at least one of --title, --body, or --config");
+    }
+    if (opts.title !== void 0 && !opts.title.trim()) {
+      throw new Error("title must not be empty");
+    }
+    const replacementConfig = opts.config === void 0 ? void 0 : readJSONObject(opts.config.startsWith("@") ? opts.config.slice(1) : opts.config, "--config");
+    const replacementBody = opts.body === void 0 ? void 0 : readMaybeFile(opts.body) ?? "";
+    const client = new ErdoClient();
+    const current = await client.getKnowledge(id);
+    const object = current.object;
+    print(await client.updateKnowledge(id, {
+      title: opts.title ?? object.title,
+      body_markdown: replacementBody ?? object.body_markdown,
+      config_json: replacementConfig ?? object.config_json,
+      expected_updated_at: object.updated_at
+    }));
+  } catch (e) {
+    fail(e);
+  }
+});
 knowledgeCmd.command("list").description("List knowledge objects").option(
   "--public",
   "only entries opted into anonymous external surfaces (website widgets)"

package/package.json

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