@trygocode/notify 0.1.0

package/dist/src/creds.js

@@ -0,0 +1,158 @@
+// Credentials + config storage for gocode-notify (PRD §4.2).
+//
+// Two files live under `~/.gocode/`:
+//   - credentials  JSON { api_key, server, user_id, label } — chmod 600 (secret)
+//   - config.json  non-secret prefs { server?, source? }
+//
+// Server-URL precedence (PRD §4.2, the acceptance criterion for this task):
+//   --server flag  >  GOCODE_SERVER env  >  credentials file  >  built-in default
+//
+// Zero runtime deps — only Node built-ins, to match the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Built-in default server, used when nothing else resolves a URL. */
+export const DEFAULT_SERVER = "https://oh.jeltechsolutions.com";
+/**
+ * Resolve the home directory. Prefers an explicit override, then `$HOME`
+ * (so tests can point at a temp dir via the env), then `os.homedir()`.
+ */
+export function resolveHome(opts) {
+    return opts?.home ?? process.env.HOME ?? os.homedir();
+}
+/** Absolute path to the `~/.gocode/` directory. */
+export function gocodeDir(opts) {
+    return path.join(resolveHome(opts), ".gocode");
+}
+/** Absolute path to the secret credentials file. */
+export function credentialsPath(opts) {
+    return path.join(gocodeDir(opts), "credentials");
+}
+/** Absolute path to the non-secret config file. */
+export function configPath(opts) {
+    return path.join(gocodeDir(opts), "config.json");
+}
+/** Trim a URL and strip any trailing slashes (so `${server}/path` is clean). */
+function normalizeServer(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+/** First value that is a non-empty string after trimming; else undefined. */
+function firstNonEmpty(...values) {
+    for (const v of values) {
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+    }
+    return undefined;
+}
+async function ensureGocodeDir(opts) {
+    // 0o700: the dir holds a secret; keep it owner-only.
+    await fs.mkdir(gocodeDir(opts), { recursive: true, mode: 0o700 });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readJsonFile(file) {
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`gocode-notify: ${file} contains invalid JSON`);
+    }
+}
+/**
+ * Read `~/.gocode/credentials`. Returns null when the file does not exist.
+ * Throws if it exists but is not a JSON object with the required string fields.
+ */
+export async function readCredentials(opts) {
+    const parsed = await readJsonFile(credentialsPath(opts));
+    if (parsed === undefined)
+        return null;
+    if (!isRecord(parsed)) {
+        throw new Error(`gocode-notify: ${credentialsPath(opts)} is not a JSON object`);
+    }
+    for (const field of ["api_key", "server", "user_id", "label"]) {
+        if (typeof parsed[field] !== "string") {
+            throw new Error(`gocode-notify: credentials missing string field "${field}"`);
+        }
+    }
+    return {
+        api_key: parsed.api_key,
+        server: parsed.server,
+        user_id: parsed.user_id,
+        label: parsed.label,
+    };
+}
+/**
+ * Write `~/.gocode/credentials` with mode 0o600 (owner read/write only).
+ * Creates `~/.gocode/` (0o700) if needed.
+ */
+export async function writeCredentials(creds, opts) {
+    await ensureGocodeDir(opts);
+    const file = credentialsPath(opts);
+    const body = JSON.stringify(creds, null, 2) + "\n";
+    // mode on writeFile is masked by umask, so chmod explicitly afterwards to
+    // guarantee 0o600 regardless of the caller's umask.
+    await fs.writeFile(file, body, { mode: 0o600 });
+    await fs.chmod(file, 0o600);
+}
+/**
+ * Read `~/.gocode/config.json`. Returns null when absent. Throws if it exists
+ * but is not a JSON object.
+ */
+export async function readConfig(opts) {
+    const parsed = await readJsonFile(configPath(opts));
+    if (parsed === undefined)
+        return null;
+    if (!isRecord(parsed)) {
+        throw new Error(`gocode-notify: ${configPath(opts)} is not a JSON object`);
+    }
+    return parsed;
+}
+/** Write `~/.gocode/config.json` (non-secret; default 0o644 perms). */
+export async function writeConfig(config, opts) {
+    await ensureGocodeDir(opts);
+    const body = JSON.stringify(config, null, 2) + "\n";
+    await fs.writeFile(configPath(opts), body);
+}
+/**
+ * Resolve the effective server URL from the precedence chain
+ * `flag > env > creds.server > default`. Empty/whitespace values are skipped.
+ * The result is trimmed and has trailing slashes stripped.
+ */
+export function resolveServer(sources) {
+    const chosen = firstNonEmpty(sources.flag, sources.env, sources.creds?.server, sources.default ?? DEFAULT_SERVER);
+    // The default is always non-empty, so `chosen` is defined here.
+    return normalizeServer(chosen ?? DEFAULT_SERVER);
+}
+/**
+ * Convenience wrapper: resolve the server URL using the `--server` flag, the
+ * live `GOCODE_SERVER` env var, and the on-disk credentials file.
+ */
+export async function resolveServerUrl(flag, opts) {
+    // Credentials are the LOWEST non-default precedence tier, so a corrupt or
+    // unreadable credentials file must never block a higher-precedence --server
+    // flag or GOCODE_SERVER env. Swallow read errors here and treat them as
+    // "no creds" — callers that actually need a valid api_key (e.g. `send`)
+    // call readCredentials() directly and get the strict error there.
+    let creds = null;
+    try {
+        creds = await readCredentials(opts);
+    }
+    catch {
+        creds = null;
+    }
+    return resolveServer({
+        flag,
+        env: process.env.GOCODE_SERVER ?? null,
+        creds,
+    });
+}

package/dist/src/cursor.js

@@ -0,0 +1,273 @@
+// Cursor config writer (PRD §5.4, §5.5) — the installer's per-runtime writer for
+// Cursor. It does three things, all idempotently and without clobbering the
+// user's existing config:
+//
+//   1. MERGE a fire-and-forget `stop` hook into `~/.cursor/hooks.json`:
+//        stop → "finished" (the agent completed a turn).
+//      The command shells out to `gocode-notify send … || true` so a failed push
+//      NEVER blocks the agent's turn (PRD §4.4, §5.4). The file's `version` is
+//      preserved (or set to 1 when creating it fresh).
+//   2. MERGE an `mcpServers` entry into `~/.cursor/mcp.json` pointing at
+//      `npx -y @trygocode/notify mcp`.
+//   3. WRITE the on-demand rule to `~/.cursor/rules/gocode-notify.md` (the
+//      anti-double-ping rule, PRD §5.5, `alwaysApply: false`).
+//
+// MERGE, never clobber: the user's own hooks / MCP servers / top-level keys are
+// preserved. Re-running converges (idempotent) — our stop entry and MCP entry
+// are replaced in place, not duplicated. `uninstallCursorConfig` removes EXACTLY
+// our entries and nothing else (PRD §11, the uninstall test).
+//
+// Our entries are identified by a stable marker (the command contains both
+// `gocode-notify` and `--source cursor`) so idempotency and uninstall work even
+// across version bumps to the exact command string.
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveHome } from "./creds.js";
+import { buildRuleContent, CURSOR_FRONTMATTER, CURSOR_HOOK_DESCRIPTION, } from "./rule-content.js";
+/** Display name of the runtime this writer handles (matches the detector). */
+export const CURSOR_RUNTIME_NAME = "Cursor";
+/** MCP server key written into `~/.cursor/mcp.json` `mcpServers`. */
+export const MCP_SERVER_NAME = "gocode-notify";
+/** The MCP server entry we register (PRD §4.3, §5.4 invocation form). */
+export const MCP_SERVER_ENTRY = {
+    command: "npx",
+    args: ["-y", "@trygocode/notify", "mcp"],
+};
+/**
+ * The Cursor `stop` hook command (PRD §5.4, verbatim shape). Ends in `|| true`
+ * so a notification failure can never block the agent's turn, and carries a
+ * `--dedupe-key` so overlapping triggers (e.g. Cursor `stop` + Claude `Stop`)
+ * coalesce server-side.
+ */
+export const CURSOR_STOP_COMMAND = "gocode-notify send --kind finished --source cursor --dedupe-key cursor-stop || true";
+/**
+ * Substrings that together identify a `stop` hook entry as OURS. Used for
+ * idempotent merge (replace, don't duplicate) and for surgical uninstall (remove
+ * exactly ours). A command must contain BOTH to be considered ours.
+ */
+const HOOK_MARKERS = ["gocode-notify", "--source cursor"];
+/**
+ * The on-demand rule written to `~/.cursor/rules/gocode-notify.md` (PRD §5.5).
+ * The crucial content is the anti-double-ping rule: the automatic pings are
+ * owned by the Cursor `stop` hook, so the agent must only call the MCP tool when
+ * the user EXPLICITLY asks. `alwaysApply: false` + a trigger-y description so
+ * Cursor surfaces it on "notify me / ping me / let me know when". Built from the
+ * shared {@link buildRuleContent} so the body stays in lockstep with the Claude
+ * Code skill.
+ */
+export const RULE_CONTENT = buildRuleContent({
+    frontmatter: CURSOR_FRONTMATTER,
+    hookDescription: CURSOR_HOOK_DESCRIPTION,
+});
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** `~/.cursor/` directory for the given (optional) HOME override. */
+function cursorDir(opts) {
+    return path.join(resolveHome(opts), ".cursor");
+}
+/** Absolute path to Cursor's `hooks.json`. */
+export function cursorHooksPath(opts) {
+    return path.join(cursorDir(opts), "hooks.json");
+}
+/** Absolute path to Cursor's `mcp.json`. */
+export function cursorMcpPath(opts) {
+    return path.join(cursorDir(opts), "mcp.json");
+}
+/** Absolute path to the directory holding Cursor rules. */
+export function cursorRulesDir(opts) {
+    return path.join(cursorDir(opts), "rules");
+}
+/** Absolute path to our rule file. */
+export function cursorRulePath(opts) {
+    return path.join(cursorRulesDir(opts), "gocode-notify.md");
+}
+/**
+ * Read a JSON object from `file`. Returns null when the file does not exist.
+ * Throws when it exists but is not a JSON object — so we never silently clobber
+ * a file we failed to parse (the caller surfaces it as a write failure).
+ */
+async function readJsonObject(file) {
+    let raw;
+    try {
+        raw = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`gocode-notify: ${file} contains invalid JSON`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error(`gocode-notify: ${file} is not a JSON object`);
+    }
+    return parsed;
+}
+/** Write a JSON object with 2-space indent + trailing newline (matches creds). */
+async function writeJsonFile(file, value) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(value, null, 2) + "\n");
+}
+/** True when a single `stop` hook entry (`{ command }`) is one we wrote. */
+function isOurStopHook(h) {
+    return (isRecord(h) &&
+        typeof h.command === "string" &&
+        HOOK_MARKERS.every((m) => h.command.includes(m)));
+}
+/**
+ * Strip OUR entries out of the `stop` array. Returns the cleaned array plus
+ * whether anything of ours was removed (so callers can detect a real change).
+ * Never mutates the input.
+ */
+function stripOurStopHooks(entries) {
+    const kept = entries.filter((h) => !isOurStopHook(h));
+    return { entries: kept, removed: kept.length !== entries.length };
+}
+/**
+ * Merge our `stop` hook into the hooks config, preserving the user's own stop
+ * entries and `version`. Strips any prior copy of OUR command (idempotent /
+ * version-safe) then appends a single fresh entry. Mutates `config` in place.
+ * A fresh file gets `version: 1` (PRD §5.4); an existing `version` is preserved.
+ */
+function mergeStopHook(config) {
+    if (typeof config.version !== "number")
+        config.version = 1;
+    const hooks = isRecord(config.hooks) ? config.hooks : {};
+    const existing = Array.isArray(hooks.stop) ? hooks.stop : [];
+    const preserved = stripOurStopHooks(existing).entries;
+    preserved.push({ command: CURSOR_STOP_COMMAND });
+    hooks.stop = preserved;
+    config.hooks = hooks;
+}
+/** Merge our MCP server entry into `mcp.mcpServers`. Mutates in place. */
+function mergeMcp(mcp) {
+    const servers = isRecord(mcp.mcpServers) ? mcp.mcpServers : {};
+    servers[MCP_SERVER_NAME] = { ...MCP_SERVER_ENTRY, args: [...MCP_SERVER_ENTRY.args] };
+    mcp.mcpServers = servers;
+}
+/**
+ * Install Cursor config (PRD §5.4): merge the `stop` hook into `hooks.json`,
+ * merge the MCP entry into `mcp.json`, and write the rule. A
+ * {@link RuntimeConfigWriter} — never throws; returns a {@link ConfigWriteResult}.
+ * Idempotent: re-running converges without duplicating our entries.
+ */
+export async function writeCursorConfig(runtime, opts) {
+    const name = runtime?.name ?? CURSOR_RUNTIME_NAME;
+    // Track paths as they land so a mid-way failure reports what WAS actually
+    // written rather than claiming nothing changed.
+    const written = [];
+    try {
+        await fs.mkdir(cursorDir(opts), { recursive: true });
+        const hooksPath = cursorHooksPath(opts);
+        const hooksConfig = (await readJsonObject(hooksPath)) ?? {};
+        mergeStopHook(hooksConfig);
+        await writeJsonFile(hooksPath, hooksConfig);
+        written.push(hooksPath);
+        const mcpPath = cursorMcpPath(opts);
+        const mcpConfig = (await readJsonObject(mcpPath)) ?? {};
+        mergeMcp(mcpConfig);
+        await writeJsonFile(mcpPath, mcpConfig);
+        written.push(mcpPath);
+        const rulePath = cursorRulePath(opts);
+        await fs.mkdir(cursorRulesDir(opts), { recursive: true });
+        await fs.writeFile(rulePath, RULE_CONTENT);
+        written.push(rulePath);
+        return {
+            runtime: name,
+            written,
+            skipped: false,
+            detail: "merged stop hook + MCP entry; wrote rule",
+        };
+    }
+    catch (err) {
+        return {
+            runtime: name,
+            written,
+            skipped: false,
+            failed: true,
+            detail: `Cursor config write failed: ${errMessage(err)}`,
+        };
+    }
+}
+/**
+ * Remove EXACTLY the entries this writer added (PRD §11): our `stop` hook entry,
+ * our MCP server entry, and our rule file. The user's own hooks, MCP servers,
+ * `version`, and other keys are preserved untouched. Idempotent — a second run
+ * (or a run when nothing was installed) is a clean no-op. Never throws.
+ */
+export async function uninstallCursorConfig(opts) {
+    const removed = [];
+    try {
+        // hooks.json — strip our stop entry (command-level, preserving the user's).
+        const hooksPath = cursorHooksPath(opts);
+        const hooksConfig = await readJsonObject(hooksPath);
+        if (hooksConfig && isRecord(hooksConfig.hooks)) {
+            const hooks = hooksConfig.hooks;
+            let changed = false;
+            if (Array.isArray(hooks.stop)) {
+                const { entries: kept, removed: r } = stripOurStopHooks(hooks.stop);
+                if (r) {
+                    changed = true;
+                    if (kept.length > 0)
+                        hooks.stop = kept;
+                    else
+                        delete hooks.stop;
+                }
+            }
+            if (Object.keys(hooks).length === 0)
+                delete hooksConfig.hooks;
+            if (changed) {
+                await writeJsonFile(hooksPath, hooksConfig);
+                removed.push(hooksPath);
+            }
+        }
+        // mcp.json — remove our server entry only.
+        const mcpPath = cursorMcpPath(opts);
+        const mcpConfig = await readJsonObject(mcpPath);
+        if (mcpConfig && isRecord(mcpConfig.mcpServers) && MCP_SERVER_NAME in mcpConfig.mcpServers) {
+            delete mcpConfig.mcpServers[MCP_SERVER_NAME];
+            if (Object.keys(mcpConfig.mcpServers).length === 0)
+                delete mcpConfig.mcpServers;
+            await writeJsonFile(mcpPath, mcpConfig);
+            removed.push(mcpPath);
+        }
+        // rules/gocode-notify.md — remove only OUR rule file, never the rules dir.
+        const rulePath = cursorRulePath(opts);
+        let ruleExisted = false;
+        try {
+            await fs.stat(rulePath);
+            ruleExisted = true;
+        }
+        catch (err) {
+            // Only ENOENT means "not installed". A permission/IO error must surface as
+            // a failure, not be silently reported as a clean uninstall.
+            if (err.code !== "ENOENT")
+                throw err;
+            ruleExisted = false;
+        }
+        if (ruleExisted) {
+            await fs.rm(rulePath, { force: true });
+            removed.push(rulePath);
+        }
+        return {
+            removed,
+            detail: removed.length > 0
+                ? `removed gocode-notify entries (${removed.length} path${removed.length === 1 ? "" : "s"})`
+                : "no gocode-notify entries found",
+        };
+    }
+    catch (err) {
+        return { removed, failed: true, detail: `Cursor uninstall failed: ${errMessage(err)}` };
+    }
+}

package/dist/src/detect.js

@@ -0,0 +1,109 @@
+// Canonical agent-runtime detection (PRD §5.2).
+//
+// Owns the runtime table, the {@link RuntimeStatus} shape, and the detector that
+// both `setup` (the installer) and `status` consume through a single seam. A
+// runtime counts as "detected" when EITHER:
+//   - one of its well-known config dirs exists under the home dir, OR
+//   - one of its `pathCommands` resolves to a file on `$PATH`.
+// The PATH branch covers the PRD §5.2 rule for Claude Code — "`~/.claude/` exists
+// OR `claude` on PATH" — so a globally-installed runtime is found even before it
+// has written its config dir.
+//
+// Both the home dir (`PathOpts.home`) and `$PATH` (`DetectOptions.path`) are
+// injectable, so the whole detector is unit-testable against fixture HOMEs with
+// zero reliance on the machine's real config dirs or installed binaries.
+//
+// Detection is best-effort and NEVER throws (a stat failure just reads as
+// "absent"). Zero runtime deps — Node built-ins only, matching the package rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveHome } from "./creds.js";
+/** The runtimes we detect, in install-priority order (PRD §5.2). */
+export const RUNTIMES = [
+    {
+        name: "Claude Code",
+        detectDirs: [".claude"],
+        configBasename: "settings.json",
+        pathCommands: ["claude"],
+    },
+    { name: "Cursor", detectDirs: [".cursor"], configBasename: "hooks.json" },
+    {
+        name: "OpenCode",
+        detectDirs: [".config/opencode", ".opencode"],
+        configBasename: "mcp.json",
+    },
+];
+/** True when `p` exists (any stat error → false). Never throws. */
+async function pathExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Best-effort check: does `cmd` resolve to a file on any entry of `pathEnv`?
+ * On Windows we also try the usual executable extensions. Empty/undefined PATH →
+ * false. Never throws.
+ */
+async function commandOnPath(cmd, pathEnv) {
+    if (!pathEnv)
+        return false;
+    const names = process.platform === "win32" ? [cmd, `${cmd}.exe`, `${cmd}.cmd`, `${cmd}.bat`] : [cmd];
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            if (await pathExists(path.join(dir, name)))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Detect every runtime in {@link RUNTIMES}. The installer (`setup`) and `status`
+ * both consume this as their single detection seam, so detection stays
+ * consistent across the CLI. Resolves (never rejects).
+ */
+export async function detectRuntimes(opts) {
+    return Promise.all(RUNTIMES.map((spec) => detectRuntime(spec, opts)));
+}
+/**
+ * Detect one runtime: which (if any) detect-dir exists, else whether a PATH
+ * command resolves, plus the config path we'd write and whether it already
+ * exists.
+ */
+export async function detectRuntime(spec, opts) {
+    const home = resolveHome(opts);
+    let detectedDir;
+    for (const rel of spec.detectDirs) {
+        if (await pathExists(path.join(home, rel))) {
+            detectedDir = rel;
+            break;
+        }
+    }
+    // Only consult PATH when no config dir was found (cheap-first), and only for
+    // runtimes that declare PATH commands.
+    let onPath = false;
+    if (detectedDir === undefined && spec.pathCommands?.length) {
+        const pathEnv = opts?.path ?? process.env.PATH;
+        for (const cmd of spec.pathCommands) {
+            if (await commandOnPath(cmd, pathEnv)) {
+                onPath = true;
+                break;
+            }
+        }
+    }
+    const detected = detectedDir !== undefined || onPath;
+    // Anchor the config path at the detected dir, else the primary detect-dir.
+    const baseDir = detectedDir ?? spec.detectDirs[0];
+    const configPath = path.join(home, baseDir, spec.configBasename);
+    return {
+        name: spec.name,
+        detected,
+        configPath,
+        configWritten: detected ? await pathExists(configPath) : false,
+    };
+}

package/dist/src/login.js

@@ -0,0 +1,152 @@
+// gocode-notify `login` — device pairing flow (PRD §1.1, §4.1, §5.1).
+//
+// Exchanges a 6-digit pairing code (shown in the GoCode app's "Connect a coding
+// agent" screen) for a scoped push-only API key via
+//   POST /api/v1/notify/pair/claim   (NO JWT — the CLI has none yet)
+// then writes ~/.gocode/credentials (chmod 600) so every later `send` is
+// authenticated. When `--code` is absent the code is read interactively.
+//
+// The server URL follows the same precedence as everywhere else:
+//   --server flag  >  GOCODE_SERVER env  >  credentials file  >  built-in default
+// (resolved via resolveServerUrl in creds.ts).
+//
+// Zero runtime deps — only Node built-ins, to match the package's zero-dep rule.
+import os from "node:os";
+import { createInterface } from "node:readline/promises";
+import { resolveServerUrl, writeCredentials, } from "./creds.js";
+/** Endpoint the CLI hits to exchange a pairing code for an API key (PRD §3.2). */
+export const CLAIM_PATH = "/api/v1/notify/pair/claim";
+/**
+ * Default timeout for the claim request. Longer than `send`'s 5s because login
+ * is an explicit, user-initiated action (not a fire-and-forget hook), so a
+ * brief extra wait is acceptable and surfaces a clearer failure than a clip.
+ */
+export const LOGIN_TIMEOUT_MS = 10_000;
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Strip trailing slashes so `${server}/path` is always clean. */
+function normalizeServer(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+/** First non-empty (after trim) string, else undefined. */
+function firstNonEmpty(...values) {
+    for (const v of values) {
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+    }
+    return undefined;
+}
+/** A short, friendly default label for this machine (hostname, sans domain). */
+export function defaultLabel() {
+    const host = os.hostname().split(".")[0];
+    return firstNonEmpty(host) ?? "this machine";
+}
+/** Read a 6-digit code from the terminal (the non-test, interactive path). */
+async function defaultPromptCode() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await rl.question("Enter the 6-digit pairing code from the GoCode app: ");
+    }
+    finally {
+        rl.close();
+    }
+}
+function isClaimResponse(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const r = value;
+    return typeof r.api_key === "string" && typeof r.user_id === "string";
+}
+/**
+ * Exchange a pairing `code` for an API key at `POST /pair/claim`. No JWT and no
+ * API key are sent (this is the unauthenticated bootstrap). Resolves (never
+ * rejects) to a {@link ClaimResult}; failures carry a generic message because
+ * the server intentionally does not leak which condition failed (PRD §3.2).
+ */
+export async function claim(code, label, opts) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const url = `${normalizeServer(opts.server)}${CLAIM_PATH}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? LOGIN_TIMEOUT_MS);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ code, label }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            return {
+                ok: false,
+                status: res.status,
+                error: `pairing failed (server responded ${res.status}) — check the code and try again`,
+            };
+        }
+        let data;
+        try {
+            data = await res.json();
+        }
+        catch {
+            return { ok: false, status: res.status, error: "pairing response was not valid JSON" };
+        }
+        if (!isClaimResponse(data)) {
+            return { ok: false, status: res.status, error: "pairing response missing api_key/user_id" };
+        }
+        return { ok: true, data };
+    }
+    catch (err) {
+        const reason = controller.signal.aborted
+            ? "pairing request timed out"
+            : `pairing request failed: ${errMessage(err)}`;
+        return { ok: false, error: reason };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Run the full `login` flow: resolve the server, obtain the 6-digit code (flag
+ * or interactive prompt), claim an API key, and write ~/.gocode/credentials.
+ * Credentials are written ONLY on success. Resolves (never rejects) to a
+ * {@link LoginResult}.
+ */
+export async function login(opts = {}) {
+    const server = await resolveServerUrl(opts.server, opts);
+    // Resolve the code. Prompt ONLY when the --code flag is truly absent
+    // (undefined). An explicitly-supplied-but-empty code must NOT silently fall
+    // into the interactive prompt — it falls through to validation and is
+    // rejected, so a bad `--code ""` never hangs on stdin.
+    let code = opts.code;
+    if (code === undefined) {
+        const prompt = opts.promptCode ?? defaultPromptCode;
+        try {
+            code = await prompt();
+        }
+        catch (err) {
+            return { ok: false, error: `could not read pairing code: ${errMessage(err)}` };
+        }
+    }
+    code = code.trim();
+    if (!/^\d{6}$/.test(code)) {
+        return { ok: false, error: "pairing code must be 6 digits" };
+    }
+    const label = firstNonEmpty(opts.label) ?? defaultLabel();
+    const result = await claim(code, label, {
+        server,
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs,
+    });
+    if (!result.ok) {
+        return { ok: false, status: result.status, error: result.error };
+    }
+    const creds = {
+        api_key: result.data.api_key,
+        server,
+        user_id: result.data.user_id,
+        // Prefer the label the server echoed back; fall back to the one we sent.
+        label: firstNonEmpty(result.data.label, label) ?? label,
+    };
+    await writeCredentials(creds, opts);
+    return { ok: true, credentials: creds };
+}