serpkin 0.0.0-stage → 0.2.0

package/lib/commands.mjs

@@ -0,0 +1,813 @@
+import { hostname as osHostname } from "node:os";
+import { join, relative } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import {
+  c,
+  out,
+  ask,
+  confirm,
+  choose,
+  openBrowser,
+  table,
+  interactive,
+  CliError,
+} from "./ui.mjs";
+import { createClient, deviceLogin, ApiError } from "./api.mjs";
+import {
+  apiKeyFor,
+  saveCredential,
+  credentialsPath,
+  loadProject,
+  saveProject,
+  resolveServer,
+  projectServerTrusted,
+  PROJECT_FILE,
+} from "./config.mjs";
+import {
+  detectApps,
+  buildRouteMap,
+  publicDir,
+  routeMapFramework,
+} from "./detect.mjs";
+import {
+  AGENTS,
+  detectAgents,
+  onPath,
+  mergeMcpJson,
+  appendCodexConfig,
+  codexConfigPath,
+  claudeEntry,
+  cursorEntry,
+  claudeMcpAdd,
+  installClaudePlugin,
+  pluginInstallCommand,
+} from "./agents.mjs";
+import { writeCursorRule, writeAgentsSection } from "./rules.mjs";
+import { DEFAULT_SERVER } from "./config.mjs";
+
+const PREVIEW_HOSTS = /\.(vercel\.app|netlify\.app|pages\.dev)$/i;
+const FRAMEWORK_NAMES = {
+  nextjs: "Next.js",
+  "nextjs-app": "Next.js (app router)",
+  "nextjs-pages": "Next.js (pages router)",
+  astro: "Astro",
+  sveltekit: "SvelteKit",
+  nuxt: "Nuxt",
+  remix: "Remix",
+};
+
+/** Shared context: injectable for tests. */
+export function context(overrides = {}) {
+  return {
+    cwd: process.cwd(),
+    env: process.env,
+    fetchImpl: globalThis.fetch,
+    wait: undefined,
+    ...overrides,
+  };
+}
+
+/**
+ * Resolve the server. .serpkin.json is repository content anyone can commit, so a server named only
+ * there must be known (default, or already signed in to) or confirmed; otherwise keys could be sent
+ * to an attacker's origin.
+ */
+export async function pickServer(flags, project, ctx) {
+  const { server, source } = resolveServer(flags.server, project, ctx.env);
+  if (source !== "project" || (await projectServerTrusted(server, ctx.env)))
+    return server;
+  const msg = `${PROJECT_FILE} points to ${server}, a Serpkin server you haven't signed in to.`;
+  if (!interactive(flags))
+    throw new CliError(
+      `${msg} If you trust it, pass --server ${server} or set SERPKIN_SERVER=${server}.`,
+    );
+  out.warn(msg);
+  if (!(await confirm(`Use ${server}?`, { def: false, opts: flags })))
+    throw new CliError("Stopped. Pass --server <origin> to choose the server.");
+  return server;
+}
+
+async function session(flags, ctx, { required = true } = {}) {
+  const project = await loadProject(ctx.cwd);
+  const server = await pickServer(flags, project, ctx);
+  const cred = await apiKeyFor(server, ctx.env);
+  if (!cred && required)
+    throw new CliError(
+      `Not signed in to ${server}. Run \`npx serpkin\` first, or set SERPKIN_API_KEY.`,
+    );
+  const api = createClient({
+    server,
+    apiKey: cred?.api_key,
+    fetchImpl: ctx.fetchImpl,
+  });
+  return { project, server, cred, api };
+}
+function siteIdFrom(flags, project, env) {
+  const id = flags.site || env.SERPKIN_SITE_ID || project?.site_id;
+  if (!id)
+    throw new CliError(
+      `No site found. Run \`npx serpkin init\` in this repository (it writes ${PROJECT_FILE}), or pass --site <id>.`,
+    );
+  return id;
+}
+function cleanHost() {
+  return (
+    osHostname()
+      .replace(/\.(local|lan|home)$/i, "")
+      .slice(0, 64) || "this machine"
+  );
+}
+const sameOrigin = (url, origin) => {
+  try {
+    return new URL(url).origin === origin;
+  } catch {
+    return false;
+  }
+};
+export function normalizeUrl(input) {
+  const s = String(input ?? "").trim();
+  if (!s) return null;
+  try {
+    const u = new URL(/^[a-z]+:\/\//i.test(s) ? s : `https://${s}`);
+    if (!["http:", "https:"].includes(u.protocol)) return null;
+    return u.origin;
+  } catch {
+    return null;
+  }
+}
+const isLocal = (origin) =>
+  /^(localhost|127\.|0\.0\.0\.0|\[::1\])|\.local$/i.test(
+    new URL(origin).hostname,
+  );
+
+/* ─────────────────────────────── init ─────────────────────────────── */
+
+export async function init(flags, ctx = context()) {
+  const project = await loadProject(ctx.cwd);
+  const server = await pickServer(flags, project, ctx);
+  out.line(c.bold("Serpkin setup") + c.dim(`  ${server}`));
+  out.line();
+
+  // 1. Sign in (device code), unless a working key is already stored.
+  let cred = flags.login ? null : await apiKeyFor(server, ctx.env);
+  let api = createClient({
+    server,
+    apiKey: cred?.api_key,
+    fetchImpl: ctx.fetchImpl,
+  });
+  if (cred) {
+    try {
+      await api.get("/api/records?kind=site&limit=1");
+      out.ok(
+        `Signed in ${c.dim(`(${cred.source === "env" ? "SERPKIN_API_KEY" : (cred.key_prefix ?? "stored key")})`)}`,
+      );
+    } catch (e) {
+      if (!(e instanceof ApiError) || e.status !== 401) throw e;
+      out.warn("The stored key no longer works. Signing in again.");
+      cred = null;
+    }
+  }
+  if (!cred) {
+    const token = await deviceLogin(api, {
+      clientName: "Serpkin CLI",
+      hostname: cleanHost(),
+      wait: ctx.wait,
+      onCode: (d) => {
+        // Only show/open approval pages on the server we are signing in to.
+        for (const u of [d.verification_uri, d.verification_uri_complete])
+          if (!sameOrigin(u, server))
+            throw new CliError(
+              `The server returned a sign-in page on another origin (${String(u).slice(0, 80)}); stopping.`,
+            );
+        d.user_code = String(d.user_code)
+          .replace(/[^A-Z0-9-]/gi, "")
+          .slice(0, 12);
+        out.step("Sign in to connect this machine.");
+        out.line(
+          `  Open ${c.cyan(d.verification_uri)} and confirm the code ${c.bold(d.user_code)}`,
+        );
+        if (openBrowser(d.verification_uri_complete, flags, server))
+          out.note("Opened your browser. Waiting for approval…");
+        else out.note("Waiting for approval…");
+      },
+    });
+    const path = await saveCredential(
+      server,
+      {
+        api_key: token.api_key,
+        key_prefix: token.key_prefix,
+        project_id: token.project_id,
+        created_at: new Date().toISOString(),
+      },
+      ctx.env,
+    );
+    cred = { ...token, source: "file" };
+    api = createClient({
+      server,
+      apiKey: token.api_key,
+      fetchImpl: ctx.fetchImpl,
+    });
+    out.ok(
+      `Signed in. Key saved to ${c.dim(tilde(path, ctx.env))} ${c.dim("(outside this repo)")}`,
+    );
+  }
+  const mcpUrl = `${server}/api/mcp`;
+
+  // 2. Framework and route map.
+  const apps = await detectApps(ctx.cwd);
+  let app = null;
+  if (flags.app) {
+    app =
+      apps.find(
+        (a) => a.root === flags.app.replace(/^\.\//, "").replace(/\/$/, ""),
+      ) ?? null;
+    if (!app) throw new CliError(`No supported app found at ${flags.app}.`);
+  } else if (apps.length === 1) app = apps[0];
+  else if (apps.length > 1)
+    app = await choose(
+      "Which app is the website?",
+      apps.map((a) => ({
+        value: a,
+        label: `${a.root} ${c.dim(`(${FRAMEWORK_NAMES[a.framework]}, ${a.name})`)}`,
+      })),
+      {
+        opts: flags,
+        needed: `Found ${apps.length} apps (${apps.map((a) => a.root).join(", ")}). Pass --app <dir> to choose one.`,
+      },
+    );
+  let routeMap = null;
+  if (app) {
+    routeMap = await buildRouteMap(app, ctx.cwd);
+    const dyn = routeMap.routes.filter((r) => r.dynamic).length;
+    out.ok(
+      `${FRAMEWORK_NAMES[app.framework]}${app.router ? ` (${app.router.replace("+", " + ")} router)` : ""}` +
+        `${app.root !== "." ? ` in ${app.root}` : ""}: ${routeMap.routes.length} routes${dyn ? `, ${dyn} dynamic` : ""}`,
+    );
+  } else
+    out.warn(
+      "No supported framework found here. Missions still work by URL; the route map is skipped.",
+    );
+
+  // 3. Coding agents.
+  const { usedEnv, plugin } = await setupAgents(flags, ctx, {
+    mcpUrl,
+    apiKey: cred.api_key,
+  });
+
+  // 4. Register the site.
+  let origin =
+    normalizeUrl(flags.url) ??
+    (flags.url ? null : (project?.origin ?? normalizeUrl(app?.homepage)));
+  if (flags.url && !origin)
+    throw new CliError(`"${flags.url}" isn't a website address.`);
+  if (!origin) {
+    const answer = await ask(
+      "Production URL of the site (or a preview URL if it isn't live yet):",
+      {
+        opts: flags,
+        needed: "Pass the site's address with --url https://example.com.",
+      },
+    );
+    origin = normalizeUrl(answer);
+    if (!origin) throw new CliError(`"${answer}" isn't a website address.`);
+  }
+  let site = null,
+    token = null;
+  if (isLocal(origin)) {
+    out.warn(`${origin} is on this machine, so Serpkin can't reach it.`);
+    out.note(
+      "Deploy a preview (for example a vercel.app URL) and run `npx serpkin init --url <preview-url>`.",
+    );
+    out.note(
+      "Foundation checks work on a preview; production verification comes once the domain is live.",
+    );
+  } else {
+    const pkg = app
+      ? await readFile(join(app.dir, "package.json"), "utf8").then(
+          JSON.parse,
+          () => ({}),
+        )
+      : {};
+    const locale = Intl.DateTimeFormat().resolvedOptions().locale || "en-US";
+    const [lang, region] = locale.split("-");
+    const description =
+      flags.description ||
+      (await ask("In one sentence, what does the site offer?", {
+        opts: flags,
+        def:
+          app?.description ||
+          pkg.description ||
+          `The website at ${new URL(origin).hostname}`,
+      }));
+    const audience =
+      flags.audience ||
+      (await ask("Who is it for?", {
+        opts: flags,
+        def: "People searching for what the site offers",
+      }));
+    const register = (country) =>
+      api.tool("serpkin_register_site", {
+        origin,
+        business_description: description,
+        audience,
+        ...(app ? { framework: routeMapFramework(app) } : {}),
+        country,
+        language: flags.language || lang || "en",
+        idempotency_key: `cli-${randomUUID()}`,
+      });
+    const guessed = /^[A-Z]{2}$/.test(region ?? "") ? region : "US";
+    let r;
+    try {
+      r = await register((flags.country || guessed).toUpperCase()).catch(
+        (e) => {
+          // A guessed (not requested) market that isn't enabled yet falls back to US.
+          if (
+            !flags.country &&
+            guessed !== "US" &&
+            e instanceof ApiError &&
+            e.code === "UNSUPPORTED_CAPABILITY"
+          )
+            return register("US");
+          throw e;
+        },
+      );
+    } catch (e) {
+      if (e instanceof ApiError && e.code === "QUOTA_EXCEEDED")
+        throw new CliError(
+          `${e.message} Remove a site or upgrade in ${server}/app, then run this again.`,
+        );
+      throw e;
+    }
+    site = r.result.site;
+    token =
+      r.result.ownership_instructions
+        ?.join("\n")
+        .match(/exactly:\s*(\S+)/)?.[1] ?? null;
+    await saveProject(ctx.cwd, {
+      server,
+      site_id: site.site_id,
+      origin: site.origin,
+    });
+    out.ok(
+      `Site registered: ${site.origin} ${c.dim(`(${PROJECT_FILE} saved; it holds no secrets)`)}`,
+    );
+    if (PREVIEW_HOSTS.test(new URL(origin).hostname))
+      out.note(
+        "This is a preview address. Run `npx serpkin init --url https://your-domain` once production is live.",
+      );
+  }
+
+  // 5. Route map upload.
+  if (site && routeMap?.routes.length) {
+    const { truncated, ...body } = routeMap;
+    await api.post("/api/cli/sites/route-map", {
+      site_id: site.site_id,
+      ...body,
+    });
+    out.ok(
+      `Route map uploaded${truncated ? " (first 2,000 routes)" : ""}. Missions can now name the files to change.`,
+    );
+  }
+
+  // 6. Ownership.
+  if (site && site.ownership_status !== "verified")
+    await ownership(flags, ctx, { server, site, token, app });
+  else if (site) out.ok("Ownership already verified.");
+
+  // 7. Next step.
+  out.line();
+  if (usedEnv && cred.source !== "env") {
+    out.line(
+      "Add your key to your shell profile (for example ~/.zshrc) so your agent can read it:",
+    );
+    out.line(`  ${c.cyan(`export SERPKIN_API_KEY="${cred.api_key}"`)}`);
+    // The plugin's MCP server reads its origin from SERPKIN_SERVER (default https://serpkin.com).
+    if (plugin && server !== DEFAULT_SERVER)
+      out.line(`  ${c.cyan(`export SERPKIN_SERVER="${server}"`)}`);
+    out.line();
+  }
+  out.line(
+    `${c.bold("Done.")} Ask your agent: ${c.violet('"What should I do for SEO?"')}`,
+  );
+  return { server, site, routeMap, app };
+}
+
+async function setupAgents(flags, ctx, { mcpUrl, apiKey }) {
+  const detected = await detectAgents(ctx.cwd, ctx.env);
+  let chosen;
+  if (flags.agent) {
+    chosen = flags.agent.split(",").map((s) => s.trim().toLowerCase());
+    for (const a of chosen)
+      if (!AGENTS[a])
+        throw new CliError(
+          `Unknown agent "${a}". Use claude, cursor or codex.`,
+        );
+  } else if (detected.length && !interactive(flags)) chosen = detected;
+  else if (detected.length) {
+    chosen = [];
+    for (const a of detected)
+      if (await confirm(`Connect ${AGENTS[a]}?`, { opts: flags }))
+        chosen.push(a);
+  } else {
+    const pick = await choose(
+      "Which coding agent do you use?",
+      [
+        ...Object.entries(AGENTS).map(([value, label]) => ({ value, label })),
+        { value: "none", label: "Skip for now" },
+      ],
+      { opts: flags, def: "none" },
+    );
+    chosen = pick === "none" ? [] : [pick];
+  }
+  if (!chosen.length) {
+    out.note(
+      "No agent configured. Settings → Agent setup in the web app has the snippets.",
+    );
+    return { usedEnv: false, plugin: false };
+  }
+  let usedEnv = false,
+    plugin = false;
+  for (const a of chosen) {
+    try {
+      if (a === "claude") {
+        const hasClaude = onPath("claude", ctx.env);
+        let how = flags.plugin && hasClaude ? "plugin" : "json";
+        if (hasClaude && interactive(flags) && !flags.plugin)
+          how = await choose(
+            "How should Claude Code get Serpkin?",
+            [
+              {
+                value: "plugin",
+                label: `Install the Serpkin plugin ${c.dim("(SEO skill, /serpkin:next, /serpkin:ship, /serpkin:check, /serpkin:status and the MCP server; reads $SERPKIN_API_KEY)")}`,
+              },
+              {
+                value: "json",
+                label: `Write .mcp.json in this repo ${c.dim("(shareable; reads $SERPKIN_API_KEY)")}`,
+              },
+              {
+                value: "cli",
+                label: `Run \`claude mcp add\` ${c.dim("(just you; key stored in your Claude config)")}`,
+              },
+            ],
+            { opts: flags, def: "plugin" },
+          );
+        if (how === "plugin") {
+          const r = (ctx.installPlugin ?? installClaudePlugin)(ctx.env);
+          if (r.ok) {
+            out.ok(
+              "Claude Code: installed the Serpkin plugin. Try /serpkin:next in a new session.",
+            );
+            usedEnv = plugin = true;
+            continue;
+          }
+          out.warn(`Claude Code plugin: ${r.message}`);
+          out.note("Falling back to .mcp.json.");
+          how = "json";
+        }
+        if (how === "cli") {
+          const r = claudeMcpAdd(mcpUrl, apiKey);
+          if (r.ok)
+            out.ok(
+              "Claude Code: added the serpkin server with `claude mcp add`.",
+            );
+          else if (r.exists)
+            out.ok(
+              "Claude Code: a serpkin server is already configured (left as is).",
+            );
+          else throw new Error(r.message);
+        } else {
+          const s = await mergeMcpJson(
+            join(ctx.cwd, ".mcp.json"),
+            claudeEntry(mcpUrl),
+          );
+          out.ok(
+            `Claude Code: .mcp.json ${s === "unchanged" ? "already set up" : s}.`,
+          );
+          usedEnv = true;
+        }
+        out.note(
+          `For the Serpkin skill and /serpkin:* commands, install the plugin: ${pluginInstallCommand(ctx.env)}`,
+        );
+      } else if (a === "cursor") {
+        await mkdir(join(ctx.cwd, ".cursor"), { recursive: true });
+        const s = await mergeMcpJson(
+          join(ctx.cwd, ".cursor", "mcp.json"),
+          cursorEntry(mcpUrl),
+        );
+        out.ok(
+          `Cursor: .cursor/mcp.json ${s === "unchanged" ? "already set up" : s}.`,
+        );
+        usedEnv = true;
+        const rule = await writeCursorRule(
+          join(ctx.cwd, ".cursor", "rules", "serpkin.mdc"),
+        );
+        out.ok(
+          `Cursor: .cursor/rules/serpkin.mdc ${rule === "unchanged" ? "already up to date" : rule}.`,
+        );
+      } else if (a === "codex") {
+        const path = codexConfigPath(ctx.env);
+        const s = await appendCodexConfig(path, mcpUrl);
+        if (s === "different")
+          out.warn(
+            `Codex: ${tilde(path, ctx.env)} already has [mcp_servers.serpkin] with another URL; left as is.`,
+          );
+        else
+          out.ok(
+            `Codex: ${tilde(path, ctx.env)} ${s === "unchanged" ? "already set up" : s}.`,
+          );
+        usedEnv = true;
+        const agentsMd = join(ctx.cwd, "AGENTS.md");
+        if (
+          !interactive(flags) ||
+          (await confirm(
+            'Add a short "Serpkin SEO" section to AGENTS.md so Codex knows the loop?',
+            { opts: flags },
+          ))
+        ) {
+          const r = await writeAgentsSection(agentsMd);
+          out.ok(
+            `Codex: ${r === "unchanged" ? "AGENTS.md already has the Serpkin SEO section" : r === "created" ? "created AGENTS.md with a Serpkin SEO section" : r === "added" ? "added a Serpkin SEO section to AGENTS.md" : "updated the Serpkin SEO section in AGENTS.md"}.`,
+          );
+        } else out.note("Skipped AGENTS.md.");
+      }
+    } catch (e) {
+      out.warn(`${AGENTS[a]}: ${e.message}`);
+      out.note(
+        "Settings → Agent setup in the web app shows the snippet to add by hand.",
+      );
+    }
+  }
+  return { usedEnv, plugin };
+}
+
+async function ownership(flags, ctx, { server, site, token, app }) {
+  const method =
+    flags.ownership ||
+    (await choose(
+      "Verify that you own the site: with Google Search Console (opens browser) or add a verification file to this repo?",
+      [
+        { value: "file", label: "Add a verification file to this repo" },
+        {
+          value: "search-console",
+          label: "Google Search Console (opens browser)",
+        },
+        { value: "skip", label: "Later" },
+      ],
+      { opts: flags, def: app && token ? "file" : "skip" },
+    ));
+  if (method === "search-console") {
+    const url = `${server}/app/site?connect=google&site_id=${encodeURIComponent(site.site_id)}`;
+    out.step(`Connect Search Console: ${c.cyan(url)}`);
+    openBrowser(url, flags, server);
+  } else if (method === "file") {
+    if (!token)
+      throw new CliError(
+        "The server didn't return a verification token. Use Search Console or the web app.",
+      );
+    const dir = app ? publicDir(app) : join(ctx.cwd, "public");
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, "serpkin-verification.txt");
+    await writeFile(file, token + "\n");
+    out.ok(
+      `Wrote ${relative(ctx.cwd, file)}. Deploy, then run \`npx serpkin verify\`.`,
+    );
+  } else if (method === "skip")
+    out.note("Verify later with `npx serpkin verify` or from the web app.");
+  else
+    throw new CliError(
+      `Unknown ownership method "${method}". Use file, search-console or skip.`,
+    );
+  out.note(
+    "Foundation checks and missions work now; production verification follows ownership.",
+  );
+}
+
+const tilde = (p, env) => {
+  const h = env.HOME || env.USERPROFILE;
+  return h && p.startsWith(h) ? "~" + p.slice(h.length) : p;
+};
+
+/* ─────────────────────────────── check ─────────────────────────────── */
+
+export async function check(previewUrl, flags, ctx = context()) {
+  if (!previewUrl)
+    throw new CliError(
+      "Usage: serpkin check <preview-url> [--paths /,/pricing] [--json]",
+    );
+  const { project, api } = await session(flags, ctx);
+  const siteId = siteIdFrom(flags, project, ctx.env);
+  const url = /^[a-z]+:\/\//i.test(previewUrl)
+    ? previewUrl
+    : `https://${previewUrl}`;
+  const paths = flags.paths
+    ? flags.paths
+        .split(",")
+        .map((p) => p.trim())
+        .filter(Boolean)
+    : undefined;
+  if (!flags.json) out.step(`Checking ${url} against production…`);
+  const r = await api.post("/api/check", {
+    site_id: siteId,
+    preview_url: url,
+    ...(paths ? { paths } : {}),
+  });
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+    return r.status === "pass" ? 0 : 1;
+  }
+  printCheck(r);
+  return r.status === "pass" ? 0 : 1;
+}
+export function printCheck(r) {
+  out.line();
+  if (r.regressions.length) {
+    out.line(
+      c.bold(
+        c.red(
+          `${r.regressions.length} regression${r.regressions.length === 1 ? "" : "s"}`,
+        ),
+      ),
+    );
+    out.line(
+      table(
+        r.regressions.map((x) => [
+          x.path,
+          x.check,
+          x.production ?? "—",
+          x.preview ?? "—",
+        ]),
+        ["Path", "Check", "Production", "Preview"],
+      ),
+    );
+    out.line();
+    for (const x of r.regressions)
+      out.line(`${c.red("✗")} ${x.path}  ${x.message}`);
+  }
+  if (r.warnings.length) {
+    if (r.regressions.length) out.line();
+    for (const w of r.warnings)
+      out.line(`${c.yellow("!")} ${w.path}  ${c.dim(w.message)}`);
+  }
+  out.line();
+  const n = r.checked_paths.length;
+  if (r.status === "pass")
+    out.ok(`No SEO regressions across ${n} page${n === 1 ? "" : "s"}.`);
+  else
+    out.fail(
+      `Found regressions on the preview (${n} page${n === 1 ? "" : "s"} checked).`,
+    );
+}
+
+/* ─────────────────────────────── verify ─────────────────────────────── */
+
+export async function verify(flags, ctx = context()) {
+  const { project, api } = await session(flags, ctx);
+  const siteId = siteIdFrom(flags, project, ctx.env);
+  try {
+    const s = await api.post("/api/ownership", { site_id: siteId });
+    out.ok(`Ownership verified for ${s.origin}.`);
+    return 0;
+  } catch (e) {
+    if (e instanceof ApiError && e.code === "SITE_NOT_VERIFIED") {
+      out.fail(e.message);
+      out.note(
+        "Deploy public/serpkin-verification.txt to production first, or connect Search Console in the web app.",
+      );
+      return 1;
+    }
+    throw e;
+  }
+}
+
+/* ─────────────────────────────── status ─────────────────────────────── */
+
+export async function status(flags, ctx = context()) {
+  const { project, api, server } = await session(flags, ctx);
+  const siteId = siteIdFrom(flags, project, ctx.env);
+  const s = (await api.tool("serpkin_get_site_context", { site_id: siteId }))
+    .result;
+  // serpkin_next_mission is the V3 primary tool; older servers only have serpkin_get_missions.
+  let next = null;
+  try {
+    next = (await api.tool("serpkin_next_mission", { site_id: siteId })).result;
+  } catch (e) {
+    if (!(e instanceof ApiError) || e.status !== 404) throw e;
+  }
+  let mission = next?.mission ?? null;
+  if (!next) {
+    const r = await api
+      .tool("serpkin_get_missions", {
+        site_id: siteId,
+        status: "ready",
+        limit: 1,
+      })
+      .catch(() => null);
+    mission = r?.result?.missions?.[0] ?? null;
+  }
+  const state = await api.get("/api/state?limit=1").catch(() => null);
+  const level = next?.level ?? s.level ?? null;
+  // CreditState {plan_total, used, reserved, remaining, resets_at} when the server exposes it.
+  const credits = state?.credits ?? null;
+  const included = state?.limits?.credits ?? null;
+  const LEVELS = {
+    search_console: "Search Console connected",
+    estimated: "Established (estimated rankings)",
+    new: "New site",
+  };
+  const rows = [
+    ["Site", s.origin],
+    [
+      "Ownership",
+      s.ownership_status === "verified"
+        ? c.green("verified")
+        : c.yellow(s.ownership_status ?? "unverified"),
+    ],
+    [
+      "Framework",
+      s.framework ? (FRAMEWORK_NAMES[s.framework] ?? s.framework) : "—",
+    ],
+    ...(level
+      ? [["Level", LEVELS[level] ?? String(level).replaceAll("_", " ")]]
+      : []),
+    [
+      "Next mission",
+      mission?.title ??
+        c.dim(
+          next?.suggested_action ??
+            "none ready yet; ask your agent to scan the site",
+        ),
+    ],
+    ["Plan", state?.project?.plan ?? "—"],
+    ...(credits
+      ? [
+          [
+            "Credits",
+            `${credits.remaining} of ${credits.plan_total} left${credits.resets_at ? c.dim(`, resets ${String(credits.resets_at).slice(0, 10)}`) : ""}`,
+          ],
+        ]
+      : included != null
+        ? [["Credits", `${included} included per month`]]
+        : []),
+  ];
+  if (flags.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          site: s,
+          level,
+          next_mission: mission,
+          credits,
+          plan: state?.project?.plan ?? null,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return 0;
+  }
+  for (const [k, v] of rows) out.line(`${c.dim(k.padEnd(13))}${v}`);
+  return 0;
+}
+
+/* ─────────────────────────────── routes ─────────────────────────────── */
+
+export async function routes(flags, ctx = context()) {
+  const apps = await detectApps(ctx.cwd);
+  const project = await loadProject(ctx.cwd);
+  const app = flags.app
+    ? apps.find((a) => a.root === flags.app.replace(/\/$/, ""))
+    : apps.length === 1
+      ? apps[0]
+      : null;
+  if (!app)
+    throw new CliError(
+      apps.length
+        ? `Found ${apps.length} apps (${apps.map((a) => a.root).join(", ")}). Pass --app <dir>.`
+        : "No supported framework found in this directory.",
+    );
+  const map = await buildRouteMap(app, ctx.cwd);
+  if (flags.json) process.stdout.write(JSON.stringify(map, null, 2) + "\n");
+  else {
+    out.line(
+      c.dim(
+        `${FRAMEWORK_NAMES[app.framework]}${app.root !== "." ? ` in ${app.root}` : ""}: ${map.routes.length} routes`,
+      ),
+    );
+    out.line(
+      table(
+        map.routes.map((r) => [r.path, r.file, r.dynamic ? "dynamic" : ""]),
+        ["Path", "File", ""],
+      ),
+    );
+  }
+  if (flags.upload) {
+    const { api } = await session(flags, ctx);
+    const siteId = siteIdFrom(flags, project, ctx.env);
+    const { truncated, ...body } = map;
+    await api.post("/api/cli/sites/route-map", { site_id: siteId, ...body });
+    if (!flags.json) out.ok("Route map uploaded.");
+  } else if (!flags.json)
+    out.note("Run `serpkin routes --upload` to send this to Serpkin.");
+  return 0;
+}