@getnoan/wizard 0.1.2 → 0.1.4

package/README.md

@@ -30,11 +30,17 @@ 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)
-   to your account, verifies and stores your Anthropic and Resend keys (and optionally a Postgres URL
+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 model 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.
+
+   The model does not have to be Anthropic's. Set `ANTHROPIC_BASE_URL` in the environment before
+   running — `https://openrouter.ai/api`, say, or your own gateway — and the wizard verifies your key
+   against *that* endpoint, stores it as `LLM_API_KEY`, and records the endpoint as a repository
+   variable so the fork actually uses it. Unset, nothing changes: it asks for an Anthropic key.
 6. **The report.** What happened, and the one thing to do next.
 
 ## For a coding assistant
@@ -65,12 +71,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.2",
+  "version": "0.1.4",
   "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

@@ -31,12 +31,70 @@ export function parseSeedOutput(text) {
 }
 
 /** The secrets and variables the pack documents, and which are required for which agent. */
-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"];
+/** LLM_API_KEY is an ALTERNATIVE to ANTHROPIC_API_KEY, not an addition: the pack accepts either
+ *  name for the model key and one of the two is required. It is listed so a caller enumerating
+ *  the pack's secrets knows the name exists, not so anyone sets both. */
+export const PACK_SECRETS = ["NOAN_PERSONAL_API_KEY", "RESEND_API_KEY", "ANTHROPIC_API_KEY", "LLM_API_KEY", "DATABASE_URL", "FIRECRAWL_API_KEY", "NEWSLETTER_UNSUB_SECRET"];
+export const PACK_VARS = ["MAIL_FROM", "REPLY_TO", "ESCALATE_TO", "STATE_BACKEND", "ANTHROPIC_BASE_URL", "AGENT_NAME", "COMPANY_NAME", "AGENT_IDENTITY_IDS", "COMMANDERS", "REPORT_RECIPIENT_TAG"];
 
-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; }
+/** The pack's model endpoint, from the same variable the pack itself reads. Bare base, no
+ *  trailing slash; empty string means the default vendor.
+ *
+ *  A bad value THROWS rather than falling back, and both rules are the pack's own
+ *  (resolveBaseUrl in agents/anthropic.mjs), deliberately down to the wording.
+ *
+ *  This returned "" on anything URL() rejected until review caught it. "" means "default
+ *  vendor", so `ANTHROPIC_BASE_URL=openrouter.ai/api` — a missing scheme, the likeliest typo
+ *  there is — silently became "no endpoint": the key went in under the vendor's name, was
+ *  verified against the vendor's host, came back 401 and was DISCARDED. That is precisely the
+ *  sequence this whole change exists to stop, reached by a typo instead of by design.
+ *
+ *  The scheme rule matters for the opposite reason: URL() happily parses `ftp://host` and
+ *  `javascript:...`, and accepting one writes a repository variable the agents refuse at
+ *  runtime — on a schedule, where nobody is watching. Better to refuse it here, in front of
+ *  someone who can retype it. */
+export function modelBase(env = process.env) {
+  const raw = (env.ANTHROPIC_BASE_URL || "").trim().replace(/\/+$/, "");
+  if (!raw) return "";
+  let url;
+  try { url = new URL(raw); } catch { throw new Error(`ANTHROPIC_BASE_URL is not a valid URL: ${raw}`); }
+  if (!/^https?:$/.test(url.protocol)) throw new Error(`ANTHROPIC_BASE_URL must be http(s): ${raw}`);
+  return raw;
+}
+export const DEFAULT_MODEL_BASE = "https://api.anthropic.com";
+/** Which secret name the model key is STORED under: the neutral one once an endpoint is set,
+ *  because "ANTHROPIC_API_KEY" holding an OpenRouter key is a lie the next reader has to unpick. */
+export const modelKeyName = (env = process.env) => (modelBase(env) ? "LLM_API_KEY" : "ANTHROPIC_API_KEY");
+
+/** 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 }) };
+}
+
+/** Verify the model key against the endpoint that will actually be called.
+ *
+ *  Against the default vendor this is a straight yes/no. Against a configured endpoint it is
+ *  advisory: `/v1/models` is not part of the Messages contract, so a gateway may not implement
+ *  it, and a 404 there says nothing about the key. Returning "unknown" rather than false is the
+ *  point — the previous behaviour verified every key against the vendor's own host, so a valid
+ *  gateway key came back 401 and was DISCARDED with "not accepted by its service". */
+export async function verifyModelKey(key, base = "") {
+  const root = base || DEFAULT_MODEL_BASE;
+  try {
+    const r = await fetch(`${root}/v1/models`, { headers: { "x-api-key": key, "anthropic-version": "2023-06-01" } });
+    if (r.status === 200) return true;
+    // Only the vendor's own host is trusted to mean "this key is bad".
+    return base ? "unknown" : false;
+  } catch { return base ? "unknown" : false; }
 }
+export const verifyAnthropic = (key) => verifyModelKey(key, "");
 export async function verifyResend(key) {
   try { const r = await fetch("https://api.resend.com/domains", { headers: { Authorization: `Bearer ${key}` } }); return r.status === 200; } catch { return false; }
 }

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

@@ -105,28 +105,67 @@ async function setupAgents({ args, ui, dir, key, me, report }) {
   const out = { ok: true, dest: fork.dest, secrets: [], variables: [], seeds: [], skipped: [] };
 
   // Keys: from the environment (an agent's run) or a prompt (a person's). Verified before they are stored.
-  const need = async (name, verify, prompt, { optional = false } = {}) => {
-    let v = (process.env[name] || "").trim();
+  const need = async (name, verify, prompt, { optional = false, from = [] } = {}) => {
+    // `from` is other env names that may carry the same value. The model key has two accepted
+    // spellings and a user who set the one we are not storing under has still configured it.
+    let v = "";
+    for (const n of [name, ...from]) { v = (process.env[n] || "").trim(); if (v) break; }
     if (!v && ui.interactive) v = await ui.ask(prompt, { secret: true });
     if (!v) { out.skipped.push({ name, why: optional ? "not provided" : "required, not provided" }); return null; }
-    if (verify && !(await verify(v))) { ui.warn(`${name} was not accepted by its service; not stored`); out.skipped.push({ name, why: "rejected" }); return null; }
+    if (verify) {
+      // A verdict of "unknown" means the endpoint could not answer, not that the key is bad —
+      // see verifyModelKey. Discarding on that would throw away a working key.
+      const verdict = await verify(v);
+      if (verdict === "unknown") ui.warn(`${name} could not be confirmed by ${prompt.replace(/^.*for /, "").replace(/ \(.*$/, "")}; storing it anyway`);
+      else if (!verdict) { ui.warn(`${name} was not accepted by its service; not stored`); out.skipped.push({ name, why: "rejected" }); return null; }
+    }
     return v;
   };
-  const anthropic = await need("ANTHROPIC_API_KEY", pack.verifyAnthropic, "Anthropic API key (the agents' model)");
+  /* The model endpoint is configuration in the pack (ANTHROPIC_BASE_URL), so it is here too.
+   * With one set, the key is verified against THAT endpoint and stored under the neutral name —
+   * verifying a gateway key against the vendor's own host returns 401, and the wizard used to
+   * discard a perfectly good key on the strength of it. Either spelling is accepted as a source. */
+  /* A bad ANTHROPIC_BASE_URL stops the agents step and says why, rather than being treated as
+   * "unset". Falling back would put the key in under the vendor's name and verify it against the
+   * vendor's host — the discarded-key failure this change exists to fix, reached by a typo.
+   *
+   * The fork and clone have already happened by here, so the message says what is and is not
+   * true: no secret, variable or .env has been written, and re-running is safe because
+   * forkAndClone reuses an existing clone. */
+  let mBase;
+  try { mBase = pack.modelBase(); }
+  catch (e) {
+    ui.warn(`${e.message}\n  Fix it (or unset it to use the default) and run again — no secret or variable was written, and the clone is reused.`);
+    return { ok: false, reason: e.message };
+  }
+  const mName = pack.modelKeyName();
+  const mHost = mBase ? new URL(mBase).host : "Anthropic";
+  const anthropic = await need(mName, (k) => pack.verifyModelKey(k, mBase),
+    `API key for ${mHost} (the agents' model)`,
+    { from: [mName === "LLM_API_KEY" ? "ANTHROPIC_API_KEY" : "LLM_API_KEY"] });
   const resend = await need("RESEND_API_KEY", pack.verifyResend, "Resend API key (the agents' email)");
   const db = await need("DATABASE_URL", null, "Postgres URL for the agents' state ledger (blank to skip; then only market research runs)", { optional: true });
   const firecrawl = await need("FIRECRAWL_API_KEY", pack.verifyFirecrawl, "Firecrawl API key (market research; blank to skip)", { optional: true });
   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 }),
+  const secrets = { NOAN_PERSONAL_API_KEY: key, ...(anthropic && { [mName]: 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 }),
+  // The endpoint is a repository VARIABLE, not a secret: without it the fork holds a gateway key
+  // and still calls the default vendor, which is the same "documented is not delivered" trap the
+  // pack's own workflows had.
+  const vars = { DRY_RUN: "1", STATE_BACKEND: db ? "postgres" : "local", ...(mBase && { ANTHROPIC_BASE_URL: mBase }), ...(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);
+  pack.writePackEnv(fork.dest, { NOAN_PERSONAL_API_KEY: key, ...(anthropic && { [mName]: anthropic }), ...(mBase && { ANTHROPIC_BASE_URL: mBase }), ...(resend && { RESEND_API_KEY: resend }) }, args.dryRun);
   const seeds = pack.runSeeds(fork.dest, { NOAN_PERSONAL_API_KEY: key }, { dryRun: args.dryRun });
   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}` : ""}`);
@@ -145,7 +184,7 @@ async function setupAgents({ args, ui, dir, key, me, report }) {
   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.
   if (!anthropic || !resend) {
-    const missing = [!anthropic && "ANTHROPIC_API_KEY", !resend && "RESEND_API_KEY"].filter(Boolean);
+    const missing = [!anthropic && mName, !resend && "RESEND_API_KEY"].filter(Boolean);
     out.incomplete = missing;
     ui.warn(`not dispatching a run: ${missing.join(" and ")} still missing. Add them as repository secrets (or re-run with them in the environment), then run any agent workflow with dry_run=1.`);
   } else {
@@ -155,5 +194,6 @@ async function setupAgents({ args, ui, dir, key, me, report }) {
     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; }
 }