serpkin 0.0.0-stage → 0.2.1

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,139 @@
-# Temporary Holding Version
+# serpkin
+
+**The SEO teammate for Claude Code, Codex and Cursor.** Serpkin reads your site and your real search data, picks the one SEO fix worth doing next, and hands it to your coding agent with the files to change. After you ship, it checks the preview and measures whether the change helped.
+
+```sh
+npx serpkin
+```
+
+[Website](https://serpkin.com) · [Guides](https://serpkin.com/guides) · [Free SEO checker](https://serpkin.com/tools/seo-check) · [Claude Code](https://serpkin.com/integrations/claude-code) · [Cursor](https://serpkin.com/integrations/cursor) · [Codex](https://serpkin.com/integrations/codex)
+
+## Quick start
+
+1. In your website's repository, run `npx serpkin`. It signs you in, connects your agent and registers the site (about a minute).
+2. Ask your agent: _"What should I do for SEO?"_
+3. Your agent implements the mission. Before you merge, run `npx serpkin check <preview-url>` to catch SEO regressions.
+
+Requires Node 22 or newer. No dependencies. There is a free plan (one site); see [pricing](https://serpkin.com/#pricing).
+
+## What you get
+
+- **One mission at a time**, chosen from a crawl of your site and, once connected, your Google Search Console data. Not a list of 200 warnings.
+- **Patch-ready instructions**: the files to edit (from your route map), code snippets for metadata, sitemaps, redirects and structured data, and a definition of done.
+- **A preview check** that fails on regressions such as a new `noindex`, a removed title or canonical, or a broken sitemap.
+- **Results**: Serpkin verifies the fix on production and reports what changed in search afterwards.
+
+| Agent       | How it connects                                                      |
+| ----------- | -------------------------------------------------------------------- |
+| Claude Code | Plugin with a skill, slash commands and hooks, or a plain MCP server |
+| Cursor      | `.cursor/mcp.json` plus a project rule                               |
+| Codex       | `~/.codex/config.toml` plus a section in `AGENTS.md`                 |
+| Others      | Any MCP client: `https://serpkin.com/api/mcp` with your agent key    |
+
+## 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.
+
+## What leaves your machine
+
+- **Sent to Serpkin:** your site URL, the answers you give during setup (the site description defaults to the one in `package.json`), and the route map (URL paths and the source file names that serve them, up to 2,000 routes). Your agent sends what it asks Serpkin for through MCP.
+- **Never sent:** your source code, environment files or the contents of your repository. To detect the framework and build the route map, the CLI reads `package.json` and the file names in your routes folder, not their contents. It also updates your agent's config files (`.mcp.json`, `.cursor/`, `AGENTS.md`, `~/.codex/config.toml`) as described above.
+- **Stored locally:** your agent key in `~/.config/serpkin/credentials.json` (mode 600), never in the repository.
+
+Details: [privacy policy](https://serpkin.com/legal/privacy).
+
+## Troubleshooting
+
+- **Serpkin can't reach your site**: Serpkin needs a public URL. Use a preview deploy with `--url`, not `localhost`.
+- **Preview check returns 401**: your preview is behind deployment protection. Allow Serpkin's requests or check a public preview.
+- **The agent doesn't see Serpkin**: make sure `SERPKIN_API_KEY` is exported in the shell your agent starts from, then restart the agent.
+- **Start over**: re-run `npx serpkin`. It reuses the stored key and site and refreshes only its own blocks.
+
+## Support and license
+
+Questions or bugs: [serpkin.com](https://serpkin.com) or the [plugin repository](https://github.com/apwn/serpkin-plugin/issues). MIT licensed (this CLI and the Claude Code plugin).
 
-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.

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.");
+}