@getnoan/wizard 0.1.1 → 0.1.3

package/README.md

@@ -30,11 +30,12 @@ Run it again any time; every write is a merge, and nothing you have is overwritt
 4. **Your fact layer.** If the workspace holds fewer than ten facts, the wizard does not guess
    facts for you. It hands the seeding to your assistant, which has the procedure from the skill:
    read your website, repo and docs, propose a structure, and write only after you say yes.
-5. **The agent pack** (optional, `--agents`). Forks [getnoan/agent-pack](https://github.com/getnoan/agent-pack)
+5. **The agent pack** (optional, `--agents`). Asks what to call your agent — Verity by default, the
+   name she answers to in NOAN — then forks [getnoan/agent-pack](https://github.com/getnoan/agent-pack)
    to your account, verifies and stores your Anthropic and Resend keys (and optionally a Postgres URL
    and a Firecrawl key) as repository secrets, runs the pack's seed scripts so each agent's starting
-   instructions are in your workspace, records the block slugs as repository variables, and triggers
-   one dry run. Safe mode stays on: the wizard never sets `DRY_RUN` to 0. That switch is yours.
+   instructions are in your workspace, records the name and the block slugs as repository variables,
+   and triggers one dry run. Safe mode stays on: the wizard never sets `DRY_RUN` to 0. That switch is yours.
 6. **The report.** What happened, and the one thing to do next.
 
 ## For a coding assistant
@@ -65,12 +66,22 @@ Exit codes: 0 done, 2 the key did not work, 3 cancelled, 1 anything else.
 | `--agents` / `--no-agents` | include or skip the agent pack step |
 | `--no-mcp`, `--no-skill` | skip a step |
 | `--dry-run` | show every write without making it |
-| `--no-telemetry` | send nothing about this run (also `NOAN_WIZARD_NO_TELEMETRY=1`) |
+| `--no-telemetry` | send nothing about this run (also `NOAN_WIZARD_NO_TELEMETRY`, `DO_NOT_TRACK`, or any `CI`) |
 
 ## Telemetry
 
-Three counts and nothing else: runs started, completed, cancelled, with the Node version and
-platform. Never a key, never a path, never a workspace name. Off with `--no-telemetry`.
+Three events — a run started, and then completed or cancelled — carrying the Node version, the
+platform, the exit code, how long the run took, whether it was non-interactive (`--yes`), whether
+the report was JSON, and whether the workspace was empty. That is the whole payload. Never a key,
+never a path, never a workspace name, never anything read out of your fact layer.
+
+A run is identified by an id made up for that process and thrown away with it, so the events of one
+run line up and nothing links one run to the next. The events ask PostHog for no person profile and
+no geolocation. Like any HTTP request they arrive from your IP address.
+
+Nothing is sent when any of these is true: `--no-telemetry`, `NOAN_WIZARD_NO_TELEMETRY` set to
+anything but `0` or `false`, `DO_NOT_TRACK` likewise, or `CI` set — a pipeline running the wizard
+is not a person trying it.
 
 ## Why a wizard and not a prompt
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnoan/wizard",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "One command from nothing to a grounded agent: sign in to NOAN, wire your coding assistant, install the skill, and set up the agent pack.",
   "license": "MIT",
   "type": "module",

package/src/agents.mjs

@@ -34,6 +34,18 @@ export function parseSeedOutput(text) {
 export const PACK_SECRETS = ["NOAN_PERSONAL_API_KEY", "RESEND_API_KEY", "ANTHROPIC_API_KEY", "DATABASE_URL", "FIRECRAWL_API_KEY", "NEWSLETTER_UNSUB_SECRET"];
 export const PACK_VARS = ["MAIL_FROM", "REPLY_TO", "ESCALATE_TO", "STATE_BACKEND", "AGENT_NAME", "COMPANY_NAME", "AGENT_IDENTITY_IDS", "COMMANDERS", "REPORT_RECIPIENT_TAG"];
 
+/** What the agents call themselves, and how their own prose refers to them.
+ *  Verity is the default because that is the agent people meet in NOAN; anyone who
+ *  wants their own name says so and gets it. Unset, the pack signs as "Agent", which
+ *  is nobody, so the wizard always sends a name.
+ *  Pronouns default to she/her only for Verity: assuming them for a name someone
+ *  else chose is worse than the pack's own neutral fallback (they/them). */
+export function agentIdentity({ name, pronouns } = {}) {
+  const n = String(name ?? "").trim() || "Verity";
+  const p = String(pronouns ?? "").trim() || (n.toLowerCase() === "verity" ? "she/her" : "");
+  return { AGENT_NAME: n, ...(p && { AGENT_PRONOUNS: p }) };
+}
+
 export async function verifyAnthropic(key) {
   try { const r = await fetch("https://api.anthropic.com/v1/models", { headers: { "x-api-key": key, "anthropic-version": "2023-06-01" } }); return r.status === 200; } catch { return false; }
 }
@@ -86,6 +98,21 @@ export function runSeeds(dest, env, { dryRun = false } = {}) {
   return { slugs, rows };
 }
 
+/** The pack's grounding check: which blocks the agents read hold no fact. Runs in the clone; absent in an old pack. */
+export function runGroundingCheck(dest, env, { dryRun = false } = {}) {
+  const p = path.join(dest, "agents", "grounding-check.mjs");
+  if (!existsSync(p)) return { available: false };
+  const r = spawnSync(process.execPath, [p, "--json", ...(dryRun ? ["--dry-run"] : [])], { cwd: path.join(dest, "agents"), encoding: "utf8", env: { ...process.env, ...env } });
+  return { available: true, ...parseGroundingOutput(r.stdout), error: r.status === 0 ? undefined : (r.stderr || "").trim().split("\n").slice(-1)[0] };
+}
+export function parseGroundingOutput(text) {
+  for (const line of String(text || "").split("\n").reverse()) {
+    if (!line.trim().startsWith("{")) continue;
+    try { const j = JSON.parse(line); return { gaps: j.gaps || [], filed: j.filed || [] }; } catch {}
+  }
+  return { gaps: [], filed: [] };
+}
+
 export function dispatchDryRun(dest, workflow, dryRun) {
   if (dryRun) return { workflow, action: "would dispatch" };
   const r = gh(["workflow", "run", workflow, "-f", "dry_run=1"], { cwd: dest });

package/src/report.mjs

@@ -14,7 +14,7 @@ export function renderReport(report, { json = false } = {}) {
   }
   if (s.skill?.rows) L.push(`skill: ${s.skill.rows.map(r => `${r.id} (${r.written} written)`).join(" · ")}; pointers: ${s.skill.pointers.map(p => p.action).join(", ")}`);
   if (s.workspace) L.push(`facts: ${s.workspace.count ?? "?"} (${s.workspace.state})`);
-  if (s.agents && !s.agents.skipped) L.push(s.agents.ok ? `agents: ${s.agents.repo || s.agents.dest} — ${s.agents.secrets.length} secrets, ${s.agents.variables.length} variables, safe mode on` : `agents: not set up (${s.agents.reason})`);
+  if (s.agents && !s.agents.skipped) L.push(s.agents.ok ? `agents: ${s.agents.repo || s.agents.dest} — ${s.agents.agentName || "your agent"}, ${s.agents.secrets.length} secrets, ${s.agents.variables.length} variables, safe mode on` : `agents: not set up (${s.agents.reason})`);
   if (report.next?.length) { L.push("", "──────── next ────────"); for (const n of report.next) L.push(`• ${n.say}${n.why ? `  (${n.why})` : ""}`); }
   L.push("");
   return L.join("\n");

package/src/run.mjs

@@ -86,7 +86,7 @@ export async function run(args) {
   ui.step(5, "The agent pack");
   let wantAgents = args.agents;
   if (wantAgents == null) wantAgents = ui.interactive ? await ui.confirm("Set up the six open-source agents on your GitHub account too?", false) : false;
-  if (wantAgents) report.steps.agents = await setupAgents({ args, ui, dir, key, me });
+  if (wantAgents) report.steps.agents = await setupAgents({ args, ui, dir, key, me, report });
   else { ui.info("skipped" + (args.yes && args.agents == null ? " (pass --agents to include it)" : "")); report.steps.agents = { skipped: true }; }
 
   /* 6. report */
@@ -96,7 +96,7 @@ export async function run(args) {
 
 async function ask(ui, q, o) { return ui.ask(q, o); }
 
-async function setupAgents({ args, ui, dir, key, me }) {
+async function setupAgents({ args, ui, dir, key, me, report }) {
   const ready = pack.ghReady();
   if (!ready.ok) { ui.warn(ready.reason); return { ok: false, reason: ready.reason }; }
   const fork = pack.forkAndClone(dir, { dryRun: args.dryRun });
@@ -119,11 +119,17 @@ async function setupAgents({ args, ui, dir, key, me }) {
   const mailFrom = process.env.MAIL_FROM || (ui.interactive ? await ui.ask("Sender for the agents' mail, e.g. Agent <agent@yourdomain.com> (a domain verified in Resend)") : "");
   const replyTo = process.env.REPLY_TO || (ui.interactive ? await ui.ask("Reply-to address (a mailbox someone reads)", { dflt: mailFrom.replace(/^.*<|>.*$/g, "") }) : "");
   const escalateTo = process.env.ESCALATE_TO || (ui.interactive ? await ui.ask("Where the support agent escalates when it cannot answer") : "");
+  const askedName = process.env.AGENT_NAME || (ui.interactive ? await ui.ask("What should your agent be called?", { dflt: "Verity" }) : "");
+  const identity = pack.agentIdentity({ name: askedName, pronouns: process.env.AGENT_PRONOUNS
+    || (ui.interactive && askedName && askedName.toLowerCase() !== "verity"
+        ? await ui.ask(`Pronouns for ${askedName}, in ${askedName}'s own prose (blank for they/them)`)
+        : "") });
 
   const secrets = { NOAN_PERSONAL_API_KEY: key, ...(anthropic && { ANTHROPIC_API_KEY: anthropic }), ...(resend && { RESEND_API_KEY: resend }),
                     ...(db && { DATABASE_URL: db }), ...(firecrawl && { FIRECRAWL_API_KEY: firecrawl }), NEWSLETTER_UNSUB_SECRET: pack.randomSecret() };
   for (const [n, v] of Object.entries(secrets)) { const r = pack.setSecret(fork.dest, n, v, args.dryRun); out.secrets.push(r); ui.ok(`secret ${n}: ${r.action}${r.error ? ` — ${r.error}` : ""}`); }
   const vars = { DRY_RUN: "1", STATE_BACKEND: db ? "postgres" : "local", ...(mailFrom && { MAIL_FROM: mailFrom }), ...(replyTo && { REPLY_TO: replyTo }), ...(escalateTo && { ESCALATE_TO: escalateTo }),
+                 ...identity,
                  COMPANY_NAME: me.project?.name || "", ...(me.identity?.id && { AGENT_IDENTITY_IDS: me.identity.id }), ...(me.identity?.email && { COMMANDERS: me.identity.email }) };
   // The seeds need the key in the clone's .env; the pack's own .env.example documents the rest.
   pack.writePackEnv(fork.dest, { NOAN_PERSONAL_API_KEY: key, ...(anthropic && { ANTHROPIC_API_KEY: anthropic }), ...(resend && { RESEND_API_KEY: resend }) }, args.dryRun);
@@ -131,6 +137,16 @@ async function setupAgents({ args, ui, dir, key, me }) {
   out.seeds = seeds.rows;
   for (const r of seeds.rows) ui.ok(`${r.seed}: ${r.action}${r.slugs != null ? ` (${r.slugs} slug(s))` : ""}${r.error ? ` — ${r.error}` : ""}`);
   Object.assign(vars, seeds.slugs);
+  // The blocks the agents read that hold no fact: one task each on the user's board, and a line in the report.
+  const grounding = args.dryRun ? { available: false } : pack.runGroundingCheck(fork.dest, { NOAN_PERSONAL_API_KEY: key });
+  out.grounding = grounding;
+  if (grounding.available) {
+    if (grounding.gaps.length) {
+      ui.warn(`${grounding.gaps.length} block(s) the agents read hold no fact — ${grounding.filed.filter(f => f.action === "filed").length} task(s) filed on your NOAN board`);
+      for (const g of grounding.gaps) ui.info(`  ${g.title}: needed by ${g.agents.join(", ")}`);
+      report.next.push({ id: "grounding", say: `Fill the ${grounding.gaps.length} block(s) the agents read (tasks are on your NOAN board): ${grounding.gaps.map(g => g.title).join(", ")}.`, why: "an agent grounded in an empty block fails quietly" });
+    } else ui.ok("every block the agents read holds a fact");
+  }
   for (const [n, v] of Object.entries(vars)) { if (!v) continue; const r = pack.setVariable(fork.dest, n, v, args.dryRun); out.variables.push(r); }
   ui.ok(`${out.variables.length} repository variable(s) ${args.dryRun ? "to set" : "set"} (DRY_RUN=1: every agent stays in safe mode)`);
   // No point dispatching a run that will only fail for a missing key: say what is missing instead.
@@ -145,5 +161,6 @@ async function setupAgents({ args, ui, dir, key, me }) {
     ui.ok(`${wf}: ${d.action}${d.error ? ` — ${d.error}` : ""} — read it under Actions, then set DRY_RUN=0 for the agents you trust`);
   }
   out.repo = pack.repoSlug(fork.dest);
+  out.agentName = identity.AGENT_NAME;
   return out;
 }

package/src/telemetry.mjs

@@ -1,17 +1,45 @@
 /** Runs, completions and cancels — the three counts that say whether the wizard works for strangers.
- *  Off until a public project token is set here; off whenever the user says so. Never a key, never a path. */
-export const POSTHOG_TOKEN = "";   // public (write-only) PostHog project token; empty = telemetry off
+ *  Off whenever the user says so, and off in CI. Never a key, never a path, never a workspace name. */
+import { randomUUID } from "node:crypto";
+
+// The public, write-only PostHog project key. Embedding one is what it is for; it can send
+// events and read nothing. Empty = telemetry off.
+export const POSTHOG_TOKEN = "phc_7O3g17L9CuhzTtpKkrklUZpFGJymLxrO3iMMH1krn6s";
 const HOST = "https://us.i.posthog.com";
+const TIMEOUT_MS = 2000;           // a slow or blackholed endpoint must never hold up the wizard or its report
+const RUN_ID = randomUUID();       // this process only, never stored: pairs started with completed/cancelled
+
+/** Everything an event may carry, and the only thing it can. README and SECURITY.md list exactly
+ *  this set; a property from any caller that is not here is dropped rather than sent. The promise
+ *  is "never a key, never a path, never a workspace name", and a promise one call site can break
+ *  by passing an extra key is not a promise — so the guard lives here, not in the callers. */
+export const ALLOWED_PROPERTIES = new Set([
+  "$process_person_profile", "$geoip_disable",
+  "node", "platform", "yes", "json", "exit", "ms", "empty",
+]);
+const onlyAllowed = (props) => Object.fromEntries(Object.entries(props).filter(([k]) => ALLOWED_PROPERTIES.has(k)));
+
+/** An opt-out env var is set unless it is absent, empty, "0" or "false" — because someone who
+ *  writes NO_TELEMETRY=true means it, and the old exact match on "1" silently ignored them. */
+const optedOut = (v) => {
+  const s = String(v ?? "").trim().toLowerCase();
+  return s !== "" && s !== "0" && s !== "false";
+};
 
 export function telemetryEnabled(args) {
-  return !!POSTHOG_TOKEN && args.telemetry !== false && process.env.NOAN_WIZARD_NO_TELEMETRY !== "1";
+  if (!POSTHOG_TOKEN || args.telemetry === false) return false;
+  if (optedOut(process.env.NOAN_WIZARD_NO_TELEMETRY) || optedOut(process.env.DO_NOT_TRACK)) return false;
+  if (optedOut(process.env.CI)) return false;   // a pipeline running the wizard is not a person trying it
+  return true;
 }
 export async function capture(args, event, props = {}) {
   if (!telemetryEnabled(args)) return false;
   try {
     await fetch(`${HOST}/capture/`, { method: "POST", headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ api_key: POSTHOG_TOKEN, event: `wizard_${event}`, distinct_id: "anonymous",
-        properties: { $process_person_profile: false, node: process.version, platform: process.platform, yes: !!args.yes, json: !!args.json, ...props } }) });
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      body: JSON.stringify({ api_key: POSTHOG_TOKEN, event: `wizard_${event}`, distinct_id: RUN_ID,
+        properties: onlyAllowed({ $process_person_profile: false, $geoip_disable: true,
+          node: process.version, platform: process.platform, yes: !!args.yes, json: !!args.json, ...props }) }) });
     return true;
   } catch { return false; }
 }