serpkin 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serpkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# serpkin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The SEO teammate for your coding agent. One command connects your repository, your agent and Serpkin.
+
+```sh
+npx serpkin
+```
+
+Requires Node 22 or newer. No dependencies.
+
+## What `npx serpkin` does
+
+1. **Signs you in.** Opens `https://serpkin.com/cli` with a code like `BCDF-GHJK`. Confirm it matches your terminal and approve. That creates an agent key named "Serpkin CLI on <your machine>". You can revoke it in Settings → Agent setup.
+2. **Detects your framework.** Next.js (app and pages router) fully, plus Astro, SvelteKit, Nuxt and Remix as best effort. In a monorepo it asks which app under `apps/*` or `packages/*` is the website.
+3. **Connects your agent.**
+   - **Claude Code**: offers to install the **Serpkin plugin** (see below). Alternatively it merges `serpkin` into `.mcp.json` (other servers are kept) or runs `claude mcp add`. Without a terminal it writes `.mcp.json` and prints the plugin command. Pass `--plugin` to install the plugin without asking.
+   - **Cursor**: merges into `.cursor/mcp.json` and writes the project rule `.cursor/rules/serpkin.mdc` with the SEO loop.
+   - **Codex**: appends `[mcp_servers.serpkin]` to `~/.codex/config.toml` once and adds a short "Serpkin SEO" section to the project's `AGENTS.md` (it asks first, and creates the file if it's missing).
+
+   The rule and the `AGENTS.md` section sit between `<!-- serpkin:start -->` and `<!-- serpkin:end -->`. Re-running init refreshes only that block and keeps everything else.
+4. **Registers the site** and uploads a route map (URL path → source file), so missions can name the files to change.
+5. **Sets up ownership.** Either Google Search Console (opens the browser) or a `public/serpkin-verification.txt` file. Deploy it, then run `npx serpkin verify`.
+
+Then ask your agent: _"What should I do for SEO?"_
+
+## Claude Code plugin
+
+```sh
+claude plugin marketplace add apwn/serpkin-plugin && claude plugin install serpkin@serpkin
+```
+
+Inside a session you can run `/plugin marketplace add apwn/serpkin-plugin`, then `/plugin install serpkin@serpkin`. The plugin lives in [`plugin/serpkin`](plugin/serpkin) and includes:
+
+- the **`serpkin-seo` skill**, which runs the loop: next mission → implement → run checks → check the preview → submit → verify the preview → verify production after you deploy. It treats page text and search data as untrusted and never deploys.
+- **commands**: `/serpkin:next` gets the next mission and implements it. `/serpkin:ship <preview-url>` submits it, checks the preview and verifies. `/serpkin:check <preview-url>` runs `npx serpkin check`. `/serpkin:status` shows the site status.
+- the **Serpkin MCP server**. It reads `SERPKIN_API_KEY` and, for a self-hosted or local server, `SERPKIN_SERVER` (default `https://serpkin.com`).
+
+- **hooks** (quiet by design, only in repositories with `.serpkin.json`):
+  - **Session start**: one line with the next mission and "run /serpkin:next". It is fetched with a 2.5-second timeout and cached for 6 hours per site (failures for 30 minutes), and it says nothing when you are offline, signed out or the project isn't linked.
+  - **After a push or deploy** (`git push`, `vercel deploy`/`--prod`, `netlify deploy`, `wrangler deploy`, `fly deploy`, `firebase deploy`, `railway up`, `npm|pnpm|yarn|bun run deploy`): one reminder per session to run `/serpkin:check <preview-url>`.
+  - **Turn them off** with `SERPKIN_HOOKS=off` in your shell or in Claude Code's `settings.json` `env`. Keep just one with `SERPKIN_HOOKS=session` or `SERPKIN_HOOKS=deploy`.
+  - **Safety**: the hooks run only the plugin's own scripts (never a binary or script from the repository), never print or cache your key, and follow the same server rules as the CLI: a server named only in `.serpkin.json` is used only when it is `https://serpkin.com` or a server you already signed in to, and `SERPKIN_API_KEY` is only sent to `SERPKIN_SERVER` (or `https://serpkin.com`). The command text of a push or deploy is never echoed.
+
+Clients without plugins get the same loop as MCP prompts: `next_mission`, `ship_mission` and `check_preview`. The Cursor rule and the Codex `AGENTS.md` section carry a lighter version of the hooks: at session start, ask Serpkin for the next mission and mention it in one line; after a push or deploy, suggest `npx serpkin check` once.
+
+## Patch-ready missions
+
+`serpkin_next_mission` and `serpkin_get_mission` return an `implementation` block. It lists ordered `steps`, each with a `file` from your route map, an `action` (edit, create or run), an `intent` and, where Serpkin can generate it, a `snippet` (metadata export, `app/sitemap.ts`, `app/robots.ts`, a JSON-LD component with the required properties, a `redirects()` entry and more). It also lists `verify` commands and a `done_when` list that mirrors the acceptance checks. Snippets are templates for the agent to adapt. Page and search text only appears as clipped, escaped `const UNTRUSTED_…` strings.
+
+### Where the key goes
+
+The key is **never written into your repository.** It is stored in `~/.config/serpkin/credentials.json` (mode 600, keyed by server), and project files use an environment reference (`${SERPKIN_API_KEY}` / `${env:SERPKIN_API_KEY}` / `bearer_token_env_var`). Add the printed `export SERPKIN_API_KEY=…` line to your shell profile so your agent can read it.
+
+`.serpkin.json` (server and site id, no secrets) is written to the repo root. Commit it so CI knows which site to check.
+
+### Sites that aren't live yet
+
+Serpkin can't reach `localhost`. Deploy a preview (for example a `vercel.app` URL) and run `npx serpkin init --url <preview-url>`. Foundation checks work on the preview; production verification comes once the domain is live. Run `init --url https://your-domain` then.
+
+## Commands
+
+| Command                       |                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `serpkin` / `serpkin init`    | Setup (above). Safe to re-run; the stored key and site are reused.                 |
+| `serpkin check <preview-url>` | Compare a preview deploy with production. Exit code 1 on regressions, 2 on errors. |
+| `serpkin verify`              | Check ownership (verification file or DNS record).                                 |
+| `serpkin status`              | Site, ownership, data level, next mission and credits.                             |
+| `serpkin routes [--upload]`   | Print the route map; `--upload` sends it.                                          |
+| `serpkin next [--oneline]`    | The next mission in one line (fast, cached; `--oneline` is silent when offline).   |
+
+Options: `--url`, `--plugin`, `--server <origin>` (default `$SERPKIN_SERVER`, then `.serpkin.json`, then `https://serpkin.com`), `--agent claude,cursor,codex`, `--app apps/web`, `--ownership file|search-console|skip`, `--description`, `--audience`, `--country`, `--language`, `--login`, `--paths /,/pricing`, `--site <id>`, `--json`, `--yes`, `--no-browser`.
+
+Without a terminal (CI) or with `--yes`, the CLI never prompts. When it needs something it can't default, it stops and names the flag to pass.
+
+**Which server gets your key.** `.serpkin.json` is repository content, so it can't send your key anywhere new. A server named only there is used when it is `https://serpkin.com` or a server you already signed in to. Otherwise the CLI asks, and without a terminal it stops until you pass `--server` or set `SERPKIN_SERVER`. `SERPKIN_API_KEY` is only ever sent to `SERPKIN_SERVER`, or to `https://serpkin.com` when that is unset.
+
+For a local Serpkin server: `npx serpkin --server http://127.0.0.1:3000`.
+
+## Checks on pull requests
+
+`serpkin check` compares up to 25 paths (default: the homepage plus up to 10 known pages) on the preview and on production, and fails on regressions:
+
+- HTTP errors (non-2xx, including protected previews)
+- `noindex` added in the page's robots meta tag
+- title, meta description or H1 removed
+- canonical removed, invalid, or pointing to another site
+- `robots.txt` failing or removed, `sitemap.xml` no longer reachable or valid
+
+Problems that already exist in production are reported as warnings, not regressions.
+
+**Preview noindex rule.** Vercel adds `X-Robots-Tag: noindex` to every non-production deployment (other hosts do similar). Header-level noindex on the preview is therefore reported once as a warning, never as a regression. A `noindex` in the page's own `<meta name="robots">` is page code and fails the check. Likewise a preview `robots.txt` that blocks everything is a warning, since many apps do that deliberately on previews.
+
+Preview hosts must be the site's own domain or subdomains, or `*.vercel.app`, `*.netlify.app`, `*.pages.dev`.
+
+### GitHub Action
+
+Copy [`templates/github-action.yml`](templates/github-action.yml) to `.github/workflows/serpkin.yml` then add a repository secret `SERPKIN_API_KEY` (create a key with `npx serpkin` or in Settings → Agent setup) and a repository variable `SERPKIN_SITE_ID` (the `site_id` from `.serpkin.json`). The workflow doesn't check out the pull request, so code or config from a PR never runs while the key is available, and it pins the CLI version. It runs on `deployment_status` events, which Vercel sends when a preview finishes deploying. It checks the deployment's `target_url` and fails the job when the preview introduces a regression. If your previews use Vercel Deployment Protection, Serpkin's requests get HTTP 401. Allow them through, or the check reports the preview as unreachable.

package/bin/serpkin.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { out, c, CliError } from "../lib/ui.mjs";
+import { init, check, verify, status, routes } from "../lib/commands.mjs";
+import { next } from "../lib/next.mjs";
+import { pluginInstallCommand } from "../lib/agents.mjs";
+
+const VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+const HELP = `${c.bold("serpkin")} — the SEO teammate for your coding agent
+
+${c.bold("Usage")}
+  npx serpkin [init]            Sign in, connect your agent, register the site, upload routes
+  npx serpkin check <url>       Compare a preview deploy with production; exit 1 on regressions
+  npx serpkin verify            Check site ownership (verification file or DNS)
+  npx serpkin status            Site, ownership, next mission and plan
+  npx serpkin next [--oneline]  The next mission in one line (fast, cached; silent when offline)
+  npx serpkin routes            Print the route map (--upload to send it)
+
+${c.bold("Options")}
+  --url <url>          Production URL (or a preview URL if the site isn't live yet)
+  --server <origin>    Serpkin server (default: $SERPKIN_SERVER, .serpkin.json, https://serpkin.com)
+  --agent <list>       claude, cursor, codex (comma-separated)
+  --plugin             Claude Code: install the Serpkin plugin without asking
+  --app <dir>          App directory in a monorepo, e.g. apps/web
+  --ownership <how>    file, search-console or skip
+  --description, --audience, --country, --language   Site details for registration
+  --login              Sign in again even if a key is stored
+  --paths </a,/b>      check: paths to compare (max 25; default: homepage + known pages)
+  --site <id>          Site id (default: .serpkin.json or $SERPKIN_SITE_ID)
+  --upload             routes: upload the route map
+  --json               Machine-readable output
+  --yes, -y            Accept defaults; never prompt
+  --no-browser         Don't open a browser
+  --help, -h | --version, -v
+
+Claude Code plugin (SEO skill + /serpkin:next, :ship, :check, :status):
+  ${pluginInstallCommand()}
+
+Keys are stored in ~/.config/serpkin/credentials.json (or read from SERPKIN_API_KEY), never in the repo.`;
+
+async function main(argv) {
+  const { values: f, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      url: { type: "string" },
+      server: { type: "string" },
+      agent: { type: "string" },
+      app: { type: "string" },
+      ownership: { type: "string" },
+      description: { type: "string" },
+      audience: { type: "string" },
+      country: { type: "string" },
+      language: { type: "string" },
+      paths: { type: "string" },
+      site: { type: "string" },
+      login: { type: "boolean" },
+      upload: { type: "boolean" },
+      oneline: { type: "boolean" },
+      refresh: { type: "boolean" },
+      plugin: { type: "boolean" },
+      json: { type: "boolean" },
+      yes: { type: "boolean", short: "y" },
+      "no-browser": { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+  });
+  const flags = { ...f, browser: !f["no-browser"] };
+  if (flags.version) return void out.line(VERSION);
+  const [cmd = "init", ...rest] = positionals;
+  if (flags.help || cmd === "help") return void out.line(HELP);
+  switch (cmd) {
+    case "init":
+      await init(flags);
+      return 0;
+    case "check":
+      return check(rest[0], flags);
+    case "verify":
+      return verify(flags);
+    case "status":
+      return status(flags);
+    case "routes":
+      return routes(flags);
+    case "next":
+      return next(flags);
+    default:
+      throw new CliError(
+        `Unknown command "${cmd}". Run \`npx serpkin --help\`.`,
+      );
+  }
+}
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (e) => {
+    if (
+      e?.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ||
+      e?.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE"
+    ) {
+      out.fail(`${e.message} Run \`npx serpkin --help\`.`);
+      process.exit(2);
+    }
+    out.fail(
+      e instanceof CliError
+        ? e.message
+        : `Unexpected error: ${e?.message ?? e}`,
+    );
+    process.exit(e instanceof CliError ? e.exitCode : 2);
+  },
+);

package/lib/agents.mjs

@@ -0,0 +1,192 @@
+// Coding-agent detection and MCP configuration. Formats match Settings → Agent setup in the web app.
+// No secret is ever written into the project: project files reference the SERPKIN_API_KEY variable.
+import { readFile, stat, mkdir, appendFile } from "node:fs/promises";
+import { join, delimiter } from "node:path";
+import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
+import { home, writeFileAtomic } from "./config.mjs";
+
+const exists = (p) =>
+  stat(p).then(
+    () => true,
+    () => false,
+  );
+export const AGENTS = {
+  claude: "Claude Code",
+  cursor: "Cursor",
+  codex: "Codex",
+};
+
+export function onPath(cmd, env = process.env) {
+  const exts =
+    process.platform === "win32"
+      ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")
+      : [""];
+  for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean))
+    for (const ext of exts)
+      if (statSync(join(dir, cmd + ext), { throwIfNoEntry: false })?.isFile())
+        return true;
+  return false;
+}
+
+/** Which agents look present for this project/machine. */
+export async function detectAgents(cwd, env = process.env) {
+  const found = [];
+  if ((await exists(join(cwd, ".mcp.json"))) || onPath("claude", env))
+    found.push("claude");
+  if (await exists(join(cwd, ".cursor"))) found.push("cursor");
+  if (await exists(join(home(env), ".codex"))) found.push("codex");
+  return found;
+}
+
+export const claudeEntry = (mcpUrl) => ({
+  type: "http",
+  url: mcpUrl,
+  headers: { Authorization: "Bearer ${SERPKIN_API_KEY}" },
+});
+export const cursorEntry = (mcpUrl) => ({
+  url: mcpUrl,
+  headers: { Authorization: "Bearer ${env:SERPKIN_API_KEY}" },
+});
+export const codexBlock = (mcpUrl) =>
+  `[mcp_servers.serpkin]\nurl = "${mcpUrl}"\nbearer_token_env_var = "SERPKIN_API_KEY"\n`;
+
+/**
+ * Merge `mcpServers.serpkin` into a JSON config file, keeping every other server and key.
+ * Returns "created" | "updated" | "unchanged"; refuses (throws) on a file it cannot parse.
+ */
+export async function mergeMcpJson(path, entry) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  let config = {};
+  if (raw !== undefined && raw.trim()) {
+    try {
+      config = JSON.parse(raw);
+    } catch {
+      const err = new Error(
+        `${path} isn't valid JSON, so it was left untouched.`,
+      );
+      err.code = "INVALID_JSON";
+      throw err;
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+      const err = new Error(
+        `${path} isn't a JSON object, so it was left untouched.`,
+      );
+      err.code = "INVALID_JSON";
+      throw err;
+    }
+  }
+  const servers =
+    config.mcpServers && typeof config.mcpServers === "object"
+      ? config.mcpServers
+      : {};
+  if (JSON.stringify(servers.serpkin) === JSON.stringify(entry))
+    return "unchanged";
+  const status =
+    raw === undefined ? "created" : servers.serpkin ? "updated" : "added";
+  config.mcpServers = { ...servers, serpkin: entry };
+  await writeFileAtomic(path, JSON.stringify(config, null, 2) + "\n");
+  return status;
+}
+
+/** Append the Codex block once. An existing [mcp_servers.serpkin] table is never rewritten. */
+export async function appendCodexConfig(path, mcpUrl) {
+  let raw = "";
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  if (/^\s*\[mcp_servers\.serpkin\]\s*$/m.test(raw)) {
+    const url = raw.match(
+      /\[mcp_servers\.serpkin\][^[]*?url\s*=\s*"([^"]*)"/,
+    )?.[1];
+    return url && url !== mcpUrl ? "different" : "unchanged";
+  }
+  await mkdir(join(path, ".."), { recursive: true });
+  const sep = raw && !raw.endsWith("\n") ? "\n\n" : raw ? "\n" : "";
+  await appendFile(path, sep + codexBlock(mcpUrl));
+  return raw ? "added" : "created";
+}
+
+export const codexConfigPath = (env = process.env) =>
+  join(home(env), ".codex", "config.toml");
+
+/** `claude mcp add` stores the key in the user's local Claude config, never in the repo. */
+export function claudeMcpAdd(mcpUrl, apiKey) {
+  const r = spawnSync(
+    "claude",
+    [
+      "mcp",
+      "add",
+      "--transport",
+      "http",
+      "serpkin",
+      mcpUrl,
+      "--header",
+      `Authorization: Bearer ${apiKey}`,
+    ],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+  );
+  const text = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+  if (r.status === 0) return { ok: true };
+  return {
+    ok: false,
+    exists: /already exists/i.test(text),
+    message: text.trim().split("\n")[0] || "claude mcp add failed",
+  };
+}
+
+/* Claude Code plugin (skills, /serpkin:* commands and the MCP server in one install). */
+export const PLUGIN_ID = "serpkin@serpkin";
+/**
+ * Public GitHub repository that hosts .claude-plugin/marketplace.json. This is the one place the
+ * name lives: the --help text and every printed install command read it from here. The repository
+ * is generated by cli/scripts/export-plugin-repo.mjs. Override for forks or local testing.
+ */
+export const PLUGIN_MARKETPLACE_REPO = "apwn/serpkin-plugin";
+export const pluginMarketplace = (env = process.env) =>
+  env.SERPKIN_PLUGIN_MARKETPLACE || PLUGIN_MARKETPLACE_REPO;
+export const pluginInstallCommand = (env = process.env) =>
+  `claude plugin marketplace add ${pluginMarketplace(env)} && claude plugin install ${PLUGIN_ID}`;
+export const pluginSessionCommands = (env = process.env) => [
+  `/plugin marketplace add ${pluginMarketplace(env)}`,
+  `/plugin install ${PLUGIN_ID}`,
+];
+
+/**
+ * Run `claude plugin marketplace add` then `claude plugin install` (user scope).
+ * `run` is injectable for tests. Returns {ok, message}.
+ */
+export function installClaudePlugin(
+  env = process.env,
+  run = (args) =>
+    spawnSync("claude", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+    }),
+) {
+  const steps = [
+    ["plugin", "marketplace", "add", pluginMarketplace(env)],
+    ["plugin", "install", PLUGIN_ID],
+  ];
+  for (const args of steps) {
+    const r = run(args);
+    const text = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+    // An already-added marketplace or installed plugin is fine.
+    if (r.status !== 0 && !/already (added|installed|exists)/i.test(text))
+      return {
+        ok: false,
+        message:
+          text.trim().split("\n").filter(Boolean).pop() ||
+          `claude ${args.join(" ")} failed`,
+      };
+  }
+  return { ok: true };
+}

package/lib/api.mjs

@@ -0,0 +1,147 @@
+// HTTP client for the Serpkin server. `fetchImpl` is injectable so tests can route to handlers directly.
+import { CliError } from "./ui.mjs";
+
+export class ApiError extends CliError {
+  constructor(message, status, code) {
+    super(message, 2);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export function createClient({
+  server,
+  apiKey = undefined,
+  fetchImpl = globalThis.fetch,
+  userAgent = "serpkin-cli",
+}) {
+  async function request(
+    method,
+    path,
+    body,
+    { auth = true, raw = false } = {},
+  ) {
+    const headers = { accept: "application/json", "user-agent": userAgent };
+    if (body !== undefined) headers["content-type"] = "application/json";
+    if (auth) {
+      if (!apiKey)
+        throw new CliError(
+          "Not signed in. Run `npx serpkin` (or set SERPKIN_API_KEY).",
+        );
+      headers.authorization = `Bearer ${apiKey}`;
+    }
+    let r;
+    try {
+      r = await fetchImpl(server + path, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(150_000),
+      });
+    } catch (e) {
+      throw new CliError(
+        `Couldn't reach ${server} (${e?.cause?.code ?? e?.name ?? "network error"}).`,
+      );
+    }
+    const text = await r.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      data = { error: { message: text.slice(0, 200) } };
+    }
+    if (raw) return { status: r.status, data };
+    if (!r.ok) {
+      const err = data?.error;
+      const message =
+        (typeof err === "object"
+          ? err?.message
+          : (data?.error_description ?? err)) ??
+        `Request failed with HTTP ${r.status}.`;
+      if (r.status === 401)
+        throw new ApiError(
+          "Your Serpkin key is invalid or revoked. Run `npx serpkin init --login` to sign in again.",
+          401,
+          "UNAUTHORIZED",
+        );
+      throw new ApiError(
+        message,
+        r.status,
+        typeof err === "object" ? err?.code : err,
+      );
+    }
+    return data;
+  }
+  const api = {
+    server,
+    get: (path, o) => request("GET", path, undefined, o),
+    post: (path, body, o) => request("POST", path, body, o),
+    /** REST tool route: the server fills project_id from the key. */
+    async tool(name, input = {}) {
+      const r = await request("POST", "/api/tool", { tool: name, input });
+      if (r?.status === "failed")
+        throw new ApiError(
+          r.error?.message ?? `${name} failed.`,
+          400,
+          r.error?.code,
+        );
+      return r;
+    },
+  };
+  return api;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Device-code sign-in. `onCode` shows the code/URL; `wait` is injectable for tests.
+ * Resolves with {api_key, key_prefix, project_id, origin, mcp_url}.
+ */
+export async function deviceLogin(
+  api,
+  { clientName, hostname, onCode, wait = sleep },
+) {
+  const d = await api.post(
+    "/api/cli/device",
+    { client_name: clientName, hostname },
+    { auth: false },
+  );
+  await onCode?.(d);
+  let interval = Number(d.interval) || 5;
+  const deadline = Date.now() + (Number(d.expires_in) || 600) * 1000;
+  while (Date.now() < deadline) {
+    await wait(interval * 1000);
+    const { status, data } = await api.post(
+      "/api/cli/token",
+      { device_code: d.device_code },
+      { auth: false, raw: true },
+    );
+    if (status === 200 && data.api_key) return data;
+    switch (data?.error) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        interval = Number(data.interval) || interval + 5;
+        continue;
+      case "access_denied":
+        throw new CliError(
+          "Sign-in was denied in the browser. Nothing was changed.",
+        );
+      case "expired_token":
+        throw new CliError(
+          "The sign-in code expired. Run `npx serpkin` again.",
+        );
+      default:
+        if (status === 429) {
+          interval += 5;
+          continue;
+        }
+        throw new CliError(
+          data?.error_description ??
+            data?.error?.message ??
+            `Sign-in failed (HTTP ${status}).`,
+        );
+    }
+  }
+  throw new CliError("The sign-in code expired. Run `npx serpkin` again.");
+}