agent-led-growth 0.7.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-led-growth",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Score: evals for agents as customers. Runs a real agent through signup, key and first call on your product, before you ship. Track, the analytics half, measures which agents convert after.",
   "author": {
     "name": "Kat Laszlo",

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.8.0 (2026-10-23)
+
+- `alg connect`: sets up Track's key without copying a secret by hand. It prints a code and opens the browser; once approved it writes `AGENT_TRAFFIC_KEY` (and `AGENT_TRAFFIC_PROJECT_ID`, not a secret) to `.env` or `--env-file`, replacing existing lines for those names and keeping the rest, and creates a new file with mode 0600. It warns when the file is not gitignored in a git repo and offers to add it. In a folder linked to Vercel, or with `--vercel`, it offers to run `vercel env add AGENT_TRAFFIC_KEY production` with the key on stdin. The key is never printed, logged or put on a command line. `--endpoint` or `AGENT_TRAFFIC_ENDPOINT` points it at another Track server, which is then written as `AGENT_TRAFFIC_ENDPOINT`.
+
 ## 0.7.0 (2026-10-23)
 
 - `test` no longer stops when `alg.yml` has no `verify_call` and the product has no OpenAPI document. At a terminal it asks for a GET that needs a key (and the header that carries it, default `Authorization: Bearer {key}`), checks the answer, saves it to `alg.yml` and continues the run; Enter with nothing skips the check for that run. Answering "n" to an inferred call asks the same way instead of cancelling. Before, it printed `verify_call_invalid` and left the person to edit the file and start over.

package/README.md

@@ -104,6 +104,14 @@ Add agent traffic to this API: read https://alg.katrinalaszlo.com/SKILL.md and f
 Add agent traffic to this API: read https://alg.katrinalaszlo.com/SKILL.md and follow it.
 ```
 
+To set up the key yourself, run this in your API's folder:
+
+```bash
+npx agent-led-growth connect
+```
+
+It prints a code and opens your browser; approve there, and it writes `AGENT_TRAFFIC_KEY` to `.env` (plus `AGENT_TRAFFIC_PROJECT_ID`, which is not a secret and is optional). Nothing to copy: the key is never printed, logged or put on a command line. If `.env` is not in `.gitignore` it says so and offers to add it. In a folder linked to Vercel (`.vercel/project.json`) it asks whether to also save the key in Vercel production, and passes it to `vercel env add` on stdin. Then restart your server and open `https://alg.katrinalaszlo.com/install` to watch the first event.
+
 ## Full command reference
 
 ### The three steps
@@ -142,7 +150,7 @@ Commit `alg.yml` so CI reuses your answers. `test` needs Claude Code installed a
 
 ### Installed
 
-`npm i -g agent-led-growth`, then `alg check …` and `alg test …`.
+`npm i -g agent-led-growth`, then `alg check …`, `alg test …` and `alg connect`.
 
 ### Flags
 
@@ -169,6 +177,17 @@ Commit `alg.yml` so CI reuses your answers. `test` needs Claude Code installed a
 | `--inbox <address>` | An inbox you relay mail from, for products that email a code. Or set `AGENTMAIL_API_KEY` and each run gets its own. |
 | `--json` | `agent-ready/verify@1` (or `verify-plan@1` with `--check`) to stdout. |
 
+`connect`
+
+| Flag | Does |
+| --- | --- |
+| `--endpoint <url>` | Track server. Default `AGENT_TRAFFIC_ENDPOINT`, else `https://alg.katrinalaszlo.com`. |
+| `--env-file <path>` | File to write the key to. Default `.env`. Existing lines for the same names are replaced; the rest of the file is kept. A new file is created readable only by you. |
+| `--vercel` | Also save the key in Vercel production. Asked by default when `.vercel/project.json` exists; without a terminal, only this flag does it. |
+| `--no-vercel` | Do not offer Vercel. |
+
+`connect` exits `0` when the key is saved and `1` when the sign-in is denied or expires.
+
 Exit codes, both commands: `0` done or passed, `1` fixes found or test failed, `2` usage or setup, `3` the site did not answer or the run was inconclusive, `130` cancelled.
 
 ### Cost, accounts and data

package/bin/cli.js

@@ -35,6 +35,7 @@ import { inferVerifyCall, latestInterface, latestAnswers } from "../src/verify/i
 import { askVerifyCall } from "../src/verify/wizard.js";
 import { renderPrompt } from "../src/audit/prompts.js";
 import { patternInfo } from "../src/audit/index.js";
+import { connect, resolveEndpoint } from "../src/connect/index.js";
 import { createInterface } from "node:readline/promises";
 import { spawnSync } from "node:child_process";
 
@@ -469,6 +470,46 @@ Examples:
     process.exitCode = verdict.exitCode;
   });
 
+program
+  .command("connect")
+  .description("Connect this app to Track: approve in the browser, and the key is written to .env for you (and to Vercel if you say yes). The key is never printed.")
+  .option("--endpoint <url>", "Track server (default: AGENT_TRAFFIC_ENDPOINT, else https://alg.katrinalaszlo.com)")
+  .option("--env-file <path>", "env file to write the key to", ".env")
+  .option("--vercel", "also save the key in Vercel production (asked by default when .vercel/project.json exists)")
+  .option("--no-vercel", "do not offer to save the key in Vercel")
+  .option("--no-color", "plain output")
+  .addHelpText("after", `
+Examples:
+  alg connect                         sign in, write AGENT_TRAFFIC_KEY to .env
+  alg connect --env-file .env.local   write it to another file
+  alg connect --no-vercel             skip the Vercel question`)
+  .exitOverride(usageExit)
+  .action(async (opts) => {
+    const endpoint = resolveEndpoint(opts.endpoint, process.env);
+    if (!/^https?:\/\/[^/]+/.test(endpoint)) fail(opts, 2, "invalid_address", `"${endpoint}" is not a web address.`, "Try: alg connect --endpoint https://alg.katrinalaszlo.com");
+    const style = makeStyle(Boolean(process.stderr.isTTY) && opts.color && !process.env.NO_COLOR);
+    const ask = async (question) => {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      const reply = await rl.question(question).catch((err) => {
+        if (err.code === "ABORT_ERR") return "n";
+        throw err;
+      });
+      rl.close();
+      return reply;
+    };
+    process.exitCode = await connect({
+      endpoint,
+      envFile: resolve(opts.envFile),
+      vercel: opts.vercel,
+      cwd: process.cwd(),
+      interactive: Boolean(process.stdin.isTTY),
+      sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+      ask,
+      say: (line) => console.error(line),
+      style,
+    });
+  });
+
 // 0.3 kept a Tanso workspace for verify runs. check and test need no Tanso account now; these
 // commands stay so scripts written for 0.3 get a clear answer instead of "unknown command".
 for (const name of ["account", "login", "logout"]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-led-growth",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Score: evals for agents as customers. Runs a real agent through signup, key and first call on your product, before you ship. Track, the analytics half, measures which agents convert after.",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "bin/cli.js",
     "src/index.js",
     "src/audit/",
+    "src/connect/",
     "src/dashboard/strip.js",
     "src/crash/",
     "src/harness/",

package/src/connect/index.js

@@ -0,0 +1,209 @@
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+
+// `alg connect`: a device login against Track. The person approves in the browser, and the key Track returns is
+// written to the env file (and, if they say yes, to Vercel) without ever being printed, logged or put on a command
+// line. Everything that touches the outside (fetch, child processes, the clock, the prompt) is passed in, so tests
+// run it against a fake server.
+
+export const DEFAULT_ENDPOINT = "https://alg.katrinalaszlo.com";
+
+export function resolveEndpoint(flag, env) {
+  return (flag || env.AGENT_TRAFFIC_ENDPOINT || DEFAULT_ENDPOINT).replace(/\/+$/, "");
+}
+
+const defaultRun = (cmd, args, options = {}) => spawnSync(cmd, args, { encoding: "utf8", ...options });
+
+async function postJson(fetchImpl, url, body) {
+  let res;
+  try {
+    res = await fetchImpl(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  } catch (err) {
+    throw new Error(`Could not reach ${url}: ${err.cause?.message || err.message}`);
+  }
+  // A proxy or a 5xx page can answer in HTML: only a JSON answer is read, and the status alone says what happened.
+  const isJson = (res.headers.get("content-type") || "").includes("json");
+  return { status: res.status, body: isJson ? await res.json() : null };
+}
+
+export async function startDeviceLogin({ endpoint, fetchImpl }) {
+  const res = await postJson(fetchImpl, `${endpoint}/v1/connect/start`, { client: "agent-led-growth" });
+  if (res.status !== 201 || !res.body?.device_code || !res.body?.user_code || !res.body?.verification_url) {
+    throw new Error(`${endpoint} did not start a sign-in (${res.status}${res.body?.error ? ` ${res.body.error}` : ""}).`);
+  }
+  return res.body;
+}
+
+// Polls until the person approves, denies, or the code expires. Returns { ok: true, result } or
+// { ok: false, reason, message }.
+export async function pollForKey({ endpoint, start, fetchImpl, sleep, now }) {
+  let intervalSeconds = Number(start.interval) || 5;
+  const deadline = now() + (Number(start.expires_in) || 600) * 1000;
+  const expired = { ok: false, reason: "expired", message: "The sign-in code expired before it was approved. Run alg connect again." };
+  for (;;) {
+    await sleep(intervalSeconds * 1000);
+    if (now() >= deadline) return expired;
+    const res = await postJson(fetchImpl, `${endpoint}/v1/connect/poll`, { device_code: start.device_code });
+    if (res.status === 202) continue;
+    if (res.status === 429) {
+      intervalSeconds += 2;
+      continue;
+    }
+    if (res.status === 200 && res.body?.key) return { ok: true, result: res.body };
+    if (res.status === 403) return { ok: false, reason: "denied", message: "The sign-in was denied in the browser. Nothing was saved." };
+    if (res.status === 410) return expired;
+    return { ok: false, reason: "unexpected", message: `${endpoint} answered ${res.status}${res.body?.error ? ` ${res.body.error}` : ""} while waiting for approval. Nothing was saved.` };
+  }
+}
+
+// Sets each name in values in the env file: an existing line for that name is replaced in place (a second one is
+// dropped), every other line is kept as it is, and a missing name is added at the end. A new file is created
+// readable only by its owner. Returns { created }.
+export function writeEnvFile(path, values) {
+  const created = !existsSync(path);
+  const lines = created ? [] : readFileSync(path, "utf8").split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  const written = new Set();
+  const out = [];
+  for (const line of lines) {
+    const name = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+    if (name && name in values) {
+      if (written.has(name)) continue;
+      out.push(`${name}=${values[name]}`);
+      written.add(name);
+      continue;
+    }
+    out.push(line);
+  }
+  for (const [name, value] of Object.entries(values)) if (!written.has(name)) out.push(`${name}=${value}`);
+  const text = out.join("\n") + "\n";
+  if (created) writeFileSync(path, text, { mode: 0o600 });
+  else writeFileSync(path, text);
+  return { created };
+}
+
+// "ignored", "not_ignored", "no_repo" (not inside a git work tree) or "no_git" (git is not installed).
+export function gitIgnoreStatus(path, run = defaultRun) {
+  const cwd = dirname(path);
+  const inside = run("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+  if (inside.error) return "no_git";
+  if (inside.status !== 0 || inside.stdout.trim() !== "true") return "no_repo";
+  const check = run("git", ["check-ignore", "-q", basename(path)], { cwd });
+  return check.status === 0 ? "ignored" : "not_ignored";
+}
+
+// Adds the file's name to the .gitignore next to it, creating that .gitignore if there is none.
+export function addToGitignore(path) {
+  const gitignore = join(dirname(path), ".gitignore");
+  const before = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+  appendFileSync(gitignore, `${before === "" || before.endsWith("\n") ? "" : "\n"}${basename(path)}\n`);
+  return gitignore;
+}
+
+export function openBrowser(url, run = defaultRun, platform = process.platform) {
+  if (platform === "darwin") return run("open", [url]);
+  if (platform === "win32") return run("cmd", ["/c", "start", '""', url.replace(/&/g, "^&")], { windowsVerbatimArguments: true });
+  return run("xdg-open", [url]);
+}
+
+const vercelByHand = "To add it yourself: run vercel env add AGENT_TRAFFIC_KEY production and paste the AGENT_TRAFFIC_KEY value from your env file when asked, or add it in the Vercel dashboard under Settings, Environment Variables.";
+
+// The key goes to the child on stdin only. Child output is shown only on failure, with the key cut out.
+export async function saveKeyInVercel({ key, ask, say, run = defaultRun, cwd }) {
+  const hide = (text) => String(text || "").split(key).join("[key]").trim();
+  const version = run("vercel", ["--version"], { cwd });
+  if (version.error) {
+    say("  The vercel command was not found, so the key was not saved in Vercel.");
+    say(`  ${vercelByHand}`);
+    return "vercel_missing";
+  }
+  const list = run("vercel", ["env", "ls", "production"], { cwd });
+  if (list.status !== 0) {
+    say(`  vercel env ls failed, so the key was not saved in Vercel: ${hide(list.stderr) || `exit ${list.status}`}`);
+    say(`  ${vercelByHand}`);
+    return "failed";
+  }
+  if (/(^|\s)AGENT_TRAFFIC_KEY(\s|$)/m.test(list.stdout)) {
+    const reply = await ask("  AGENT_TRAFFIC_KEY is already set in Vercel production. Replace it? (Y/n) ");
+    if (!/^(y(es)?)?$/i.test(reply.trim())) {
+      say("  Kept the existing AGENT_TRAFFIC_KEY in Vercel production.");
+      return "kept";
+    }
+    const removed = run("vercel", ["env", "rm", "AGENT_TRAFFIC_KEY", "production", "--yes"], { cwd });
+    if (removed.status !== 0) {
+      say(`  vercel env rm failed, so the key was not replaced in Vercel: ${hide(removed.stderr) || `exit ${removed.status}`}`);
+      say(`  ${vercelByHand}`);
+      return "failed";
+    }
+  }
+  const added = run("vercel", ["env", "add", "AGENT_TRAFFIC_KEY", "production"], { cwd, input: key });
+  if (added.status !== 0) {
+    say(`  vercel env add failed, so the key was not saved in Vercel: ${hide(added.stderr) || `exit ${added.status}`}`);
+    say(`  ${vercelByHand}`);
+    return "failed";
+  }
+  say("  Saved AGENT_TRAFFIC_KEY in Vercel production. It takes effect on the next deploy.");
+  return "saved";
+}
+
+// Runs the whole flow and returns the exit code: 0 connected, 1 denied, expired or failed.
+export async function connect({ endpoint, envFile, vercel, cwd, interactive, fetchImpl = fetch, sleep, now = Date.now, run = defaultRun, ask, say, style }) {
+  const bold = style?.bold || ((s) => s);
+  const dim = style?.dim || ((s) => s);
+  say("");
+  say(`  ${bold("alg connect")} · ${new URL(endpoint).host}`);
+  const start = await startDeviceLogin({ endpoint, fetchImpl });
+  say("");
+  say(`  Your code: ${bold(start.user_code)}`);
+  const opened = openBrowser(start.verification_url, run);
+  if (opened.error || opened.status) say(`  Open ${start.verification_url} in your browser.`);
+  else say(`  Opened ${start.verification_url} in your browser.`);
+  say(`  Check the code there matches, then approve. ${dim("Waiting…")}`);
+
+  const polled = await pollForKey({ endpoint, start, fetchImpl, sleep, now });
+  if (!polled.ok) {
+    say("");
+    say(`  ${polled.message}`);
+    return 1;
+  }
+  const { key, project_id: projectId, project_name: projectName } = polled.result;
+  const trackEndpoint = (polled.result.endpoint || endpoint).replace(/\/+$/, "");
+
+  const values = { AGENT_TRAFFIC_KEY: key };
+  if (projectId) values.AGENT_TRAFFIC_PROJECT_ID = projectId;
+  // The middleware sends to the default host unless told otherwise.
+  if (trackEndpoint !== DEFAULT_ENDPOINT) values.AGENT_TRAFFIC_ENDPOINT = trackEndpoint;
+  const { created } = writeEnvFile(envFile, values);
+  const shown = relative(cwd, envFile).startsWith("..") ? envFile : relative(cwd, envFile);
+  say("");
+  say(`  Connected to ${bold(projectName || projectId || "your Track project")}.`);
+  say(`  Saved ${Object.keys(values).join(", ")} to ${shown}${created ? " (new file, readable only by you)" : ""}.`);
+
+  const ignored = gitIgnoreStatus(envFile, run);
+  if (ignored === "not_ignored") {
+    say(`  ${shown} is not in .gitignore, so git would commit the key.`);
+    const reply = interactive ? await ask(`  Add ${basename(envFile)} to .gitignore? (Y/n) `) : "n";
+    if (/^(y(es)?)?$/i.test(reply.trim())) {
+      const gitignore = addToGitignore(envFile);
+      say(`  Added ${basename(envFile)} to ${relative(cwd, gitignore).startsWith("..") ? gitignore : relative(cwd, gitignore)}.`);
+    } else say(`  Add ${basename(envFile)} to .gitignore before you commit.`);
+  } else if (ignored === "no_git") say(`  ${dim("git was not found, so .gitignore was not checked.")}`);
+
+  const linked = existsSync(join(cwd, ".vercel", "project.json"));
+  if (vercel === true || (vercel !== false && linked)) {
+    say("");
+    if (interactive) {
+      const reply = await ask("  Also save the key in Vercel production? (Y/n) ");
+      if (/^(y(es)?)?$/i.test(reply.trim())) await saveKeyInVercel({ key, ask, say, run, cwd });
+      else say("  Not saved in Vercel.");
+    } else if (vercel === true) {
+      await saveKeyInVercel({ key, ask: async () => "y", say, run, cwd });
+    } else say(`  ${dim("This folder is linked to Vercel. Run alg connect --vercel to save the key there too.")}`);
+  }
+
+  say("");
+  say(`  Next: restart your server, then open ${trackEndpoint}/install to watch the first event.`);
+  say("");
+  return 0;
+}