@erdoai/cli 0.44.0 → 0.46.0

package/README.md

@@ -13,6 +13,14 @@ erdo update                  # self-update to the latest published version
 
 Requires Node.js 18+. User-facing install docs: https://docs.erdo.ai/cli
 
+When a newer version is published, every command prints one line on **stderr**
+naming the installed version and `erdo update`. It is on stderr so stdout stays
+clean JSON for scripts and agents, the published version is remembered on disk
+and re-checked about once a day, and an unreachable registry says nothing at
+all. Set `ERDO_NO_UPDATE_NOTIFIER=1` to silence it. An old build's `--help` is
+correct about itself and wrong about the product — that is the failure this
+notice exists to stop.
+
 ## Auth
 
 Multi-account, like `gh`. Log in with an API key (created in Erdo); it's stored
@@ -34,6 +42,47 @@ erdo --org acme eval suites     # one-off override for a single command
 Env overrides for CI/scripting: `ERDO_API_KEY`, `ERDO_ORG`, `ERDO_API_URL`,
 `ERDO_ACCOUNT`.
 
+## Datasets
+
+Two ways to read a dataset, and the difference matters.
+
+**`datasets fetch` is the read.** You write the SQL, so the same command gives
+the same rows every time — use it for anything mechanical, scripted, or run by
+an agent. It answers with `{columns, rows, row_count}`.
+
+```bash
+erdo --org 2200-brickell datasets fetch 2200-brickell.page-events \
+  --sql "SELECT event, count(*) FROM data GROUP BY 1 ORDER BY 2 DESC" --limit 20
+
+erdo datasets fetch acme.leads --limit 50        # no SQL: just the rows
+erdo datasets fetch acme.leads --filter <name>   # opt into a saved filter
+```
+
+The table is named **`data`** — for file datasets (CSV, Excel, and anything
+written by an event pipeline) that is the name regardless of the dataset's slug
+or resource key, and it is not guessable, so it is the first thing to get right.
+Database and warehouse datasets are queried through their real table names, which
+come from the dataset's schema. The SQL dialect is DuckDB. A dataset's default
+filters apply on every read; `--filter <name>` adds a saved filter on top, and
+narrows further — a named filter never bypasses a default. See
+`erdo datasets filter list <slug>` for the names a dataset offers.
+
+**`datasets query` is the natural-language wrapper.** Erdo writes and runs the
+SQL for you, and answers with that SQL alongside the values, so it is the one to
+reach for when you don't yet know the shape of the data. It runs an agent, so it
+is slower and it is not deterministic — two identical questions can produce two
+different queries.
+
+```bash
+erdo --org 2200-brickell datasets query 2200-brickell.page-events \
+  "which pages get the most views, and how many convert?"
+```
+
+```bash
+erdo datasets list                     # slug, type, status, class, name
+erdo datasets upload ./leads.csv       # create a dataset from a file
+```
+
 ## Agents & pages
 
 ```bash
@@ -86,15 +135,13 @@ npm run build             # bundle to dist/ (bin: erdo)
 
 ## Release
 
-Publishing is automated by `.github/workflows/publish-cli.yml`: pushing a
-`cli-v*` tag builds, typechecks, stamps the version from the tag, and runs
-`npm publish` to the npm registry (auth via the repo's `NPM_TOKEN` secret).
-
-```bash
-# bump cli/package.json "version", commit, then tag + push:
-git tag cli-v0.4.1
-git push origin cli-v0.4.1
-```
+**The version in `cli/package.json` is the release.** Bump it in the same PR as
+the change (semver: `feat` → minor, `fix` → patch) and merge;
+`.github/workflows/publish-cli.yml` publishes whatever `main` says and tags the
+result. There is no tag to remember — forgetting one is how the CLI sat at npm
+0.5.1 while `package.json` read 0.23.0 and every work-engine command was
+unreachable for anyone who installed it.
 
-The tag's version (`cli-v0.4.1` → `0.4.1`) is the published version; keep
-`cli/package.json` in sync so `erdo --version` matches locally.
+npm itself is the guard: an already-published version stops the job before it
+builds, so a `cli/` change with no bump, a re-run, and a revert all no-op. A
+change under `cli/` that ships no bump ships to nobody.

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { basename } from "path";
 import { select } from "@inquirer/prompts";
 import { Command } from "commander";
@@ -14,6 +14,9 @@ var DEFAULT_API_URL = "https://api.erdo.ai";
 var CONFIG_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "erdo");
 var CONFIG_PATH = join(CONFIG_DIR, "config.json");
 var LEGACY_KEY = "default";
+function configPath(name) {
+  return join(CONFIG_DIR, name);
+}
 function loadConfigFile() {
   if (!existsSync(CONFIG_PATH)) return null;
   try {
@@ -284,6 +287,13 @@ var ErdoClient = class {
   queryPageAnalytics(query) {
     return this.request("POST", "/v1/page-analytics/query", { query });
   }
+  // Read which analytics destinations the org's published pages send visitor data
+  // to — the check that stops "this audience is big enough to retarget" being
+  // concluded from traffic no pixel was ever tagging. Read-only: destinations are
+  // Erdo-provisioned, never caller-set.
+  getPageTracking() {
+    return this.request("GET", "/v1/page-tracking");
+  }
   listEvalSuites() {
     return this.request("GET", "/v1/evals/suites");
   }
@@ -535,6 +545,7 @@ var ErdoClient = class {
     if (params?.offset) q.set("offset", String(params.offset));
     if (params?.categories) q.set("categories", params.categories);
     if (params?.scope) q.set("scope", params.scope);
+    if (params?.workstream_slug) q.set("workstream_slug", params.workstream_slug);
     const qs = q.toString();
     return this.request(
       "GET",
@@ -656,6 +667,10 @@ var ErdoClient = class {
   }
   // The endpoint's field is `question` (QueryDataNaturalLanguageInput). Sending
   // `query` made every `erdo datasets query` fail with "question is required".
+  //
+  // `rows` carries the values in `columns` order — the answer to the question —
+  // and `output` the same result rendered to read. `row_count` is how many rows
+  // the generated SQL matched and can exceed `rows.length`, which is capped.
   queryDataset(slug, question, timezone) {
     return this.request("POST", `/v1/datasets/${encodeURIComponent(slug)}/query-nl`, {
       question,
@@ -850,6 +865,7 @@ var ErdoClient = class {
     const params = new URLSearchParams();
     if (opts.status) params.set("status", opts.status);
     if (opts.limit) params.set("limit", String(opts.limit));
+    if (opts.workstream_slug) params.set("workstream_slug", opts.workstream_slug);
     const qs = params.toString();
     return this.request(
       "GET",
@@ -1090,9 +1106,14 @@ async function browserLogin() {
 }
 
 // src/update.ts
-import { spawnSync } from "child_process";
+import { spawn as spawn2, spawnSync } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
 var PKG = "@erdoai/cli";
 var MANUAL_HINT = `npm install -g ${PKG}@latest`;
+var CACHE_PATH = configPath("update-check.json");
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REFRESH_COMMAND = "__update-check";
 function parseVersion(v) {
   const [core, pre = ""] = v.split("-", 2);
   const nums = core.split(".").map((s) => Number.parseInt(s, 10) || 0);
@@ -1111,19 +1132,65 @@ function isNewer(latest, current) {
   if (a.pre && !b.pre) return false;
   return a.pre > b.pre;
 }
-async function update(current) {
-  let latest;
+async function fetchLatestVersion(timeoutMs) {
   try {
     const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, {
-      signal: AbortSignal.timeout(1e4)
+      signal: AbortSignal.timeout(timeoutMs)
     });
-    if (res.ok) latest = (await res.json()).version;
+    if (res.ok) return (await res.json()).version;
+  } catch {
+  }
+  return void 0;
+}
+function readVersionCache() {
+  try {
+    if (!existsSync2(CACHE_PATH)) return {};
+    const raw = JSON.parse(readFileSync2(CACHE_PATH, "utf8"));
+    return raw && typeof raw === "object" ? raw : {};
   } catch {
+    return {};
+  }
+}
+function writeVersionCache(cache) {
+  try {
+    mkdirSync2(dirname2(CACHE_PATH), { recursive: true });
+    writeFileSync2(CACHE_PATH, `${JSON.stringify(cache)}
+`);
+  } catch {
+  }
+}
+async function refreshVersionCache() {
+  const latest = await fetchLatestVersion(1e4);
+  if (latest) writeVersionCache({ latest, checkedAt: Date.now() });
+}
+function notifyIfOutdated(current) {
+  if (process.env.ERDO_NO_UPDATE_NOTIFIER) return;
+  const cache = readVersionCache();
+  if (cache.latest && isNewer(cache.latest, current)) {
+    console.error(
+      `erdo v${current} is out of date (v${cache.latest} is published) \u2014 run \`erdo update\`.`
+    );
   }
+  const age = Date.now() - (cache.checkedAt ?? 0);
+  if (age < CHECK_INTERVAL_MS) return;
+  writeVersionCache({ ...cache, checkedAt: Date.now() });
+  try {
+    const entry = process.argv[1];
+    if (!entry) return;
+    spawn2(process.execPath, [entry, REFRESH_COMMAND], {
+      detached: true,
+      stdio: "ignore"
+    }).unref();
+  } catch {
+  }
+}
+async function update(current) {
+  const latest = await fetchLatestVersion(1e4);
   if (!latest) {
     console.error(`Could not reach the npm registry. Try manually: ${MANUAL_HINT}`);
     process.exit(1);
   }
+  writeVersionCache({ latest, checkedAt: Date.now() });
   if (!isNewer(latest, current)) {
     console.log(`Already up to date (v${current}).`);
     return;
@@ -1146,7 +1213,7 @@ async function update(current) {
 }
 
 // src/index.ts
-var pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = JSON.parse(readFileSync3(new URL("../package.json", import.meta.url), "utf8"));
 function fail(err) {
   if (err instanceof ErdoApiError) {
     console.error(`Error ${err.status}: ${err.message}`);
@@ -1307,6 +1374,9 @@ program.command("update").description("Update the CLI to the latest published ve
     fail(e);
   }
 });
+program.command(REFRESH_COMMAND, { hidden: true }).description("Internal: refresh the remembered latest published version").action(async () => {
+  await refreshVersionCache();
+});
 var org = program.command("org").description("Manage the active organization");
 org.command("list").description("List your organizations (* = active)").action(async () => {
   try {
@@ -2309,9 +2379,13 @@ runsCmd.command("get <id>").description("Show an agent run (status, output, trac
   }
 });
 var approvalsCmd = program.command("approvals").description("List and decide approval requests (actions agents paused on)");
-approvalsCmd.command("list").description("List approval requests, optionally filtered by status").option("-s, --status <status>", "pending | approved | rejected | expired (default: all)").option("-l, --limit <n>", "max requests", (v) => parseInt(v, 10)).option("--json", "output raw JSON").action(async (opts) => {
+approvalsCmd.command("list").description("List approval requests, optionally filtered by status").option("-s, --status <status>", "pending | approved | rejected | expired (default: all)").option("-l, --limit <n>", "max requests", (v) => parseInt(v, 10)).option("--workstream <slug>", "only approvals for this workstream").option("--json", "output raw JSON").action(async (opts) => {
   try {
-    const res = await new ErdoClient().listApprovals(opts);
+    const res = await new ErdoClient().listApprovals({
+      status: opts.status,
+      limit: opts.limit,
+      workstream_slug: opts.workstream
+    });
     if (opts.json) {
       print(res);
       return;
@@ -2328,22 +2402,59 @@ approvalsCmd.command("list").description("List approval requests, optionally fil
 });
 approvalsCmd.command("decide <id>").description("Approve or reject a pending approval request").option("--approve", "approve the request").option("--reject", "reject the request").option(
   "--scope <scope>",
-  "once (default) | always_this_job | always_org | always_user",
+  "once (default) | always_this_job | always_this_workstream | always_org | always_user",
   "once"
-).action(async (id, opts) => {
-  try {
-    if (opts.approve === opts.reject) {
-      throw new Error("specify exactly one of --approve or --reject");
+).option(
+  "--option <n>",
+  "for standing (non-once) approvals: use the request's Nth scope option (1-based) as the policy's parameter constraints \u2014 list them with `erdo approvals list --json`",
+  (v) => parseInt(v, 10)
+).option(
+  "--constraints <json>",
+  `explicit parameter constraints for the standing policy, e.g. '{"spreadsheet_id":{"values":["..."]}}'`
+).action(
+  async (id, opts) => {
+    try {
+      if (opts.approve === opts.reject) {
+        throw new Error("specify exactly one of --approve or --reject");
+      }
+      if (opts.option !== void 0 && opts.constraints !== void 0) {
+        throw new Error("specify at most one of --option or --constraints");
+      }
+      const client = new ErdoClient();
+      let constraints;
+      if (opts.constraints !== void 0) {
+        try {
+          constraints = JSON.parse(opts.constraints);
+        } catch {
+          throw new Error(
+            `--constraints must be JSON, e.g. '{"spreadsheet_id":{"values":["abc"]}}'`
+          );
+        }
+      } else if (opts.option !== void 0) {
+        const res2 = await client.listApprovals({ status: "pending" });
+        const req = res2.requests.find((r) => r.id === id);
+        if (!req) {
+          throw new Error(`pending approval ${id} not found`);
+        }
+        const options = req.scope_options ?? [];
+        if (opts.option < 1 || opts.option > options.length) {
+          const listing = options.length ? options.map((o, i) => `  ${i + 1}. ${o.label}`).join("\n") : "  (none \u2014 pass --constraints instead)";
+          throw new Error(`--option must be 1..${options.length}; available options:
+${listing}`);
+        }
+        constraints = options[opts.option - 1].constraints;
+      }
+      const res = await client.decideApproval(id, {
+        decision: opts.approve ? "approved" : "rejected",
+        scope: opts.scope,
+        parameter_constraints: constraints
+      });
+      console.log(res.message);
+    } catch (e) {
+      fail(e);
     }
-    const res = await new ErdoClient().decideApproval(id, {
-      decision: opts.approve ? "approved" : "rejected",
-      scope: opts.scope
-    });
-    console.log(res.message);
-  } catch (e) {
-    fail(e);
   }
-});
+);
 var attnCmd = program.command("attention").description("The attention feed \u2014 digests, choices, escalations awaiting a human");
 attnCmd.command("list").description("List attention items").option("--status <status...>", "open | answered | dismissed | expired").option("--open", "shorthand for --status open").option("--engine-actions", "only engine-generated items").option("-n, --limit <n>", "max items", (v) => parseInt(v, 10)).option("--offset <n>", "pagination offset", (v) => parseInt(v, 10)).action(
   async (opts) => {
@@ -2466,14 +2577,15 @@ program.command("activity").alias("feed").description(
 ).option("-n, --limit <n>", "max items (default 20, max 100)", (v) => parseInt(v, 10)).option("--offset <n>", "pagination offset", (v) => parseInt(v, 10)).option(
   "--categories <list>",
   "comma-separated: attention,approval,workstream,catalog,job,heartbeat (default: attention,approval,workstream)"
-).option("--scope <scope>", "following | all (default all)").option("--json", "raw JSON response").action(
+).option("--scope <scope>", "following | all (default all)").option("--workstream <slug>", "only this workstream").option("--json", "raw JSON response").action(
   async (opts) => {
     try {
       const feed = await new ErdoClient().listActivityFeed({
         limit: opts.limit,
         offset: opts.offset,
         categories: opts.categories,
-        scope: opts.scope
+        scope: opts.scope,
+        workstream_slug: opts.workstream
       });
       if (opts.json) {
         print(feed);
@@ -2676,7 +2788,7 @@ reviewsCmd.command("decide <id>").description(
 var pagesCmd = program.command("pages").description("Create and manage pages/artifacts");
 function readMaybeFile(v) {
   if (!v) return void 0;
-  return v.startsWith("@") ? readFileSync2(v.slice(1), "utf8") : v;
+  return v.startsWith("@") ? readFileSync3(v.slice(1), "utf8") : v;
 }
 function grantList(v) {
   if (v === void 0) return void 0;
@@ -2855,14 +2967,21 @@ datasetsCmd.command("list").description("List datasets").option(
     fail(e);
   }
 });
-datasetsCmd.command("query <slug> <question>").description("Ask a natural-language question of a dataset").action(async (slug, question) => {
+datasetsCmd.command("query <slug> <question>").description(
+  "Ask a natural-language question of a dataset \u2014 Erdo writes and runs the SQL, and answers with that SQL alongside the values. It runs an agent, so it is slower and two identical questions can produce two different queries: for a deterministic or scripted read, write the SQL yourself with `datasets fetch --sql`."
+).action(async (slug, question) => {
   try {
     print(await new ErdoClient().queryDataset(slug, question));
   } catch (e) {
     fail(e);
   }
 });
-datasetsCmd.command("fetch <slug>").description("Fetch rows from a dataset, optionally shaped by SQL and named filters").option("-q, --sql <query>", "SQL query to filter/transform the rows").option("-l, --limit <n>", "max rows to return", (v) => parseInt(v, 10)).option(
+datasetsCmd.command("fetch <slug>").description(
+  "Read rows from a dataset \u2014 the deterministic read, and the one to use for anything mechanical or scripted. Returns {columns, rows, row_count}."
+).option(
+  "-q, --sql <query>",
+  "DuckDB SQL shaping the rows. File datasets (including anything an event pipeline writes) are queried as a table named `data`, whatever the dataset's slug; database and warehouse datasets use their real table names from the schema."
+).option("-l, --limit <n>", "max rows to return", (v) => parseInt(v, 10)).option(
   "-f, --filter <name>",
   "opt into a saved filter by name (repeatable); additive on top of the dataset's default filters (see: erdo datasets filter list <slug>)",
   (v, acc) => acc.concat(v),
@@ -2883,7 +3002,7 @@ datasetsCmd.command("fetch <slug>").description("Fetch rows from a dataset, opti
 var MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 datasetsCmd.command("upload <file>").description("Upload a file (CSV, Excel, JSON, ...) and create a dataset from it").option("-n, --name <name>", "display name for the dataset (defaults to the filename)").option("-d, --description <text>", "description shown to agents analyzing the dataset").action(async (file, opts) => {
   try {
-    const content = readFileSync2(file);
+    const content = readFileSync3(file);
     if (content.byteLength > MAX_UPLOAD_BYTES) {
       fail(
         new Error(
@@ -2944,7 +3063,7 @@ function printAnalyticsTable(columns, rows) {
   console.log(widths.map((w) => "-".repeat(w)).join("  "));
   for (const r of rows) console.log(line(columns.map((_, i) => cell(r[i]))));
 }
-var analytics = program.command("analytics").description("Query page analytics (how published pages perform with real visitors)");
+var analytics = program.command("analytics").description("Page analytics \u2014 what is tracking your published pages, and how they perform with real visitors");
 analytics.command("query <hogql>").description("Run a read-only HogQL query against this org's page-analytics events").option("--json", "print the raw JSON result instead of a table").action(async (hogql, opts) => {
   try {
     const res = await new ErdoClient().queryPageAnalytics(hogql);
@@ -2963,6 +3082,44 @@ analytics.command("query <hogql>").description("Run a read-only HogQL query agai
     fail(e);
   }
 });
+var TRACKING_KINDS = [
+  { kind: "session_analytics", what: "heatmaps, session replay, and the events behind `erdo analytics query`" },
+  { kind: "google_analytics", what: "GA4 measurement" },
+  { kind: "meta_pixel", what: "cookies visitors so Meta retargeting audiences can be built" }
+];
+analytics.command("tracking").description("Show which analytics destinations this org's published pages send visitor data to").option("--json", "print the raw JSON result instead of a table").action(async (opts) => {
+  try {
+    const res = await new ErdoClient().getPageTracking();
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    const destinations = res.destinations ?? [];
+    const byKind = new Map(destinations.map((d) => [d.kind, d]));
+    const rows = TRACKING_KINDS.map(({ kind, what }) => {
+      const d = byKind.get(kind);
+      const status = d === void 0 ? "not configured" : d.enabled ? "on" : "configured, off";
+      return [kind, status, d?.public_id ?? "", d?.provider ?? "", what];
+    });
+    for (const d of destinations) {
+      if (!TRACKING_KINDS.some((k) => k.kind === d.kind)) {
+        rows.push([d.kind, d.enabled ? "on" : "configured, off", d.public_id ?? "", d.provider ?? "", ""]);
+      }
+    }
+    printAnalyticsTable(["kind", "status", "public id", "provider", "what it does"], rows);
+    console.log(`
+session replay input masking: ${res.mask_inputs ? "on" : "OFF \u2014 form values are recorded"}`);
+    console.log(`consent: ${res.consent}${res.consent === "required" ? " (recording waits on a consent banner, so thin volume may be the gate, not the traffic)" : ""}`);
+    if (!byKind.get("meta_pixel")?.enabled) {
+      console.log(`
+No Meta pixel is firing on these pages, so no retargeting audience is accumulating \u2014 page traffic alone does not mean those visitors can be served ads.`);
+    }
+    console.log(`
+Erdo's own page-events beacon is provisioned per page at render time and is not listed above \u2014 it records independently of every vendor here.`);
+  } catch (e) {
+    fail(e);
+  }
+});
 var OPERATORS = ["equals", "not_equals", "greater_than", "less_than", "contains", "not_contains", "between"];
 function parseCondition(s) {
   const m = s.trim().match(/^(\S+)\s+(\S+)\s+([\s\S]+)$/);
@@ -3191,7 +3348,7 @@ autoCmd.command("update <id>").description("Edit an automation \u2014 rename, re
         fail(new Error("pass either --script-js or --script-file, not both"));
         return;
       }
-      const scriptJs = opts.scriptFile ? readFileSync2(opts.scriptFile, "utf8") : opts.scriptJs;
+      const scriptJs = opts.scriptFile ? readFileSync3(opts.scriptFile, "utf8") : opts.scriptJs;
       const body = {
         name: opts.name,
         description: opts.description,
@@ -3269,4 +3426,8 @@ kvCmd.command("delete <slug> <key>").description("Delete a KV item").action(asyn
     fail(e);
   }
 });
+{
+  const first = process.argv[2];
+  if (first !== "update" && first !== REFRESH_COMMAND) notifyIfOutdated(pkg.version);
+}
 program.parseAsync(process.argv).catch(fail);

package/package.json

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