@trygocode/notify 0.1.0

package/dist/src/repo_key.js

@@ -0,0 +1,98 @@
+// `repo_key` derivation — a stable per-repo identity both the dev machine and the
+// phone app agree on (PRD §2.5). Per-project auto-push overrides + the app's
+// branch picker key off this so "this repo" means the same thing everywhere.
+//
+//   repo_key = sha256( normalize(git remote get-url origin) )[:16]
+//
+// normalize() lowercases, strips a trailing `.git`, and canonicalises the SCP
+// form `git@github.com:owner/repo` and the URL form
+// `https://github.com/owner/repo` to the SAME `github.com/owner/repo` string so
+// the two clone styles of one repo derive an IDENTICAL key. If there is no
+// `origin` remote we fall back to `local:<basename>` — clearly machine-local
+// (not syncable across machines).
+//
+// Zero runtime deps beyond Node built-ins; the git runner is injectable so this
+// is unit-testable with a fake `git` (no real subprocess).
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { makeGitRunner } from "./push.js";
+/**
+ * Canonicalise a git remote URL to a scheme-/auth-/`.git`-free
+ * `host/owner/repo` string so that the SSH and HTTPS clone forms of the same
+ * repo normalise IDENTICALLY (PRD §2.5). Returns "" for empty input.
+ *
+ * Handled forms:
+ *   - `https://github.com/owner/repo(.git)`
+ *   - `https://user@github.com/owner/repo`        (userinfo stripped)
+ *   - `git@github.com:owner/repo(.git)`           (SCP syntax)
+ *   - `ssh://git@github.com:22/owner/repo(.git)`  (scheme + port stripped)
+ *   - `git://github.com/owner/repo(.git)`
+ */
+export function normalizeRemoteUrl(raw) {
+    let s = raw.trim();
+    if (!s)
+        return "";
+    // Strip any `scheme://` prefix (https, http, ssh, git, …).
+    s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+    // Strip `user@` / `user:pass@` userinfo (the leading authority chunk).
+    s = s.replace(/^[^@/]+@/, "");
+    // If a ':' precedes any '/', it separates host from either an SCP path
+    // (`host:owner/repo`) or a port (`host:22/owner/repo`). Canonicalise both to
+    // `host/owner/repo`.
+    const colon = s.indexOf(":");
+    const slash = s.indexOf("/");
+    if (colon !== -1 && (slash === -1 || colon < slash)) {
+        const host = s.slice(0, colon);
+        let rest = s.slice(colon + 1);
+        const port = rest.match(/^(\d+)(\/.*)?$/); // `22/owner/repo` or bare `22`
+        if (port)
+            rest = port[2] ?? "";
+        rest = rest.replace(/^\/+/, "");
+        s = rest ? `${host}/${rest}` : host;
+    }
+    // Collapse duplicate slashes, drop trailing slash + `.git`, lowercase.
+    s = s.replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+    s = s.replace(/\.git$/i, "");
+    return s.toLowerCase();
+}
+/**
+ * Derive a friendly `owner/repo` label from a normalised remote (the last two
+ * path segments). Falls back to the final segment, or "" when there is none.
+ */
+export function repoLabelFromNormalized(normalized) {
+    const parts = normalized.split("/").filter(Boolean);
+    if (parts.length === 0)
+        return "";
+    if (parts.length === 1)
+        return parts[0]; // pathless — shouldn't happen for a real remote
+    return parts.slice(-2).join("/");
+}
+/** The 16-hex-char repo key for a normalised remote URL (PRD §2.5). */
+export function repoKeyFromNormalized(normalized) {
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+/**
+ * Resolve this repo's {@link RepoIdentity} via the injected git runner.
+ *
+ *   - `git remote get-url origin` succeeds with a non-empty URL → key derived
+ *     from the normalised URL; `synced: true`.
+ *   - no origin (no remote, git missing, not a repo, empty URL) → fall back to
+ *     `local:<basename of cwd>`; `synced: false`.
+ *
+ * Never throws: the runner reports failures as non-zero codes, which map to the
+ * local fallback.
+ */
+export async function deriveRepoIdentity(cwd = process.cwd(), git = makeGitRunner(cwd)) {
+    const res = await git(["remote", "get-url", "origin"]);
+    const url = res.code === 0 ? res.stdout.trim() : "";
+    const normalized = normalizeRemoteUrl(url);
+    if (!normalized) {
+        const base = path.basename(path.resolve(cwd)) || "repo";
+        return { repo_key: `local:${base}`, repo_label: base, synced: false };
+    }
+    return {
+        repo_key: repoKeyFromNormalized(normalized),
+        repo_label: repoLabelFromNormalized(normalized) || normalized,
+        synced: true,
+    };
+}

package/dist/src/rule-content.js

@@ -0,0 +1,71 @@
+// Shared rule/skill content (PRD §5.5 — anti-double-ping) — the single source of
+// truth for the on-demand-notification guidance shipped into BOTH clients:
+//
+//   • Claude Code → `~/.claude/skills/gocode-notify/SKILL.md`
+//   • Cursor      → `~/.cursor/rules/gocode-notify.md`
+//
+// The body is identical for both clients; only two things differ per client:
+//   1. The frontmatter block (Claude SKILL.md `name:`+`description:` vs Cursor
+//      rule `description:`+`alwaysApply:`).
+//   2. The parenthetical naming WHICH runtime hook owns the automatic pings
+//      (Claude fires `Stop`+`Notification`+`SubagentStop`; Cursor fires `stop`).
+//
+// Centralising the prose here means the anti-double-ping invariant ("the hooks
+// own the automatic done/idle/error pings — only call the MCP tool when the user
+// EXPLICITLY asks") cannot silently drift between the two clients. `claude.ts`
+// and `cursor.ts` build their shipped constants from this module.
+//
+// Zero runtime deps — pure string assembly.
+/**
+ * Build the §5.5 rule/skill Markdown for one client. The body is byte-identical
+ * across clients except for the frontmatter and the named hook mechanism, so the
+ * anti-double-ping guidance stays in lockstep.
+ */
+export function buildRuleContent({ frontmatter, hookDescription }) {
+    return `${frontmatter}
+
+# gocode-notify — on-demand phone notifications
+
+You have a \`gocode_notify\` MCP tool that sends a push notification to the user's
+phone via the GoCode app.
+
+## CRITICAL: do NOT double-notify
+
+Automatic "session done", "agent idle / needs input", and "error" notifications
+are ALREADY handled by a runtime hook (${hookDescription}). You MUST NOT call
+\`gocode_notify\` for those — the user would get two pings. The hook is
+deterministic and always fires.
+
+## When to call gocode_notify
+
+ONLY when the user EXPLICITLY asks to be pinged about a specific thing mid-task,
+e.g. "let me know when the build passes", "ping my phone when the migration is
+done". Then call it once, at that moment, with a clear \`title\`/\`body\`.
+
+## If it fails
+
+If \`gocode_notify_status\` reports no credentials, tell the user to run
+\`npx @trygocode/notify login\` and pair from the GoCode app's "Connect a coding
+agent" screen. Do not retry more than twice.
+`;
+}
+/**
+ * Claude Code SKILL.md frontmatter (PRD §5.5). The `description` is trigger-y so
+ * the skill surfaces on "text me / ping me / notify me when …".
+ */
+export const CLAUDE_FRONTMATTER = `---
+name: gocode-notify
+description: On-demand phone notifications via the GoCode app. Use ONLY when the user EXPLICITLY asks to be pinged/notified when something finishes (e.g. "text me when the build is done").
+---`;
+/** How Claude Code's automatic-ping hooks are named in the double-notify warning. */
+export const CLAUDE_HOOK_DESCRIPTION = "Claude Code `Stop` + `Notification` +\n`SubagentStop`";
+/**
+ * Cursor rule frontmatter (PRD §5.5). `alwaysApply: false` + a trigger-y
+ * description so Cursor surfaces it on "notify me / ping me / let me know when".
+ */
+export const CURSOR_FRONTMATTER = `---
+description: On-demand phone notifications via the GoCode app. Use ONLY when the user EXPLICITLY asks to be pinged/notified when something finishes (e.g. "notify me when the build is done", "ping me", "let me know when").
+alwaysApply: false
+---`;
+/** How Cursor's automatic-ping hook is named in the double-notify warning. */
+export const CURSOR_HOOK_DESCRIPTION = "Cursor `stop`";

package/dist/src/send.js

@@ -0,0 +1,141 @@
+// Internal send() — the single code path every trigger (hook / loop / MCP / CLI)
+// funnels through to POST `/api/v1/notify/send` (PRD §3.2, §4.4).
+//
+// Contract (PRD §4.4 "Never block the agent"):
+//   - Hard timeout (default 5s) via AbortController.
+//   - NEVER throws and NEVER rejects — always resolves to a {@link SendResult}.
+//     A failed notification must never block a hook's turn or fail a loop.
+//   - Failures are appended to `~/.gocode/notify.log` (size-capped + rotated).
+//
+// This module owns ONLY the request build + timeout + logging. The CLI `send`
+// command (kind-enum validation, flag parsing) and the offline outbox are
+// separate tasks; this stays self-contained and dependency-free.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DEFAULT_SERVER, gocodeDir, readCredentials, } from "./creds.js";
+/** Canonical notification kinds accepted by `/notify/send` (PRD §3.2). */
+export const NOTIFY_KINDS = [
+    "finished",
+    "error",
+    "awaiting_input",
+    "loop_completed",
+    "loop_halted",
+];
+/** True when `value` is one of the canonical {@link NOTIFY_KINDS}. */
+export function isNotifyKind(value) {
+    return typeof value === "string" && NOTIFY_KINDS.includes(value);
+}
+/** Default request timeout (PRD §4.4: 5s hard cap). */
+export const DEFAULT_TIMEOUT_MS = 5000;
+/** Rotate `notify.log` once it grows past this (keeps one `.1` backup). */
+export const MAX_LOG_BYTES = 256 * 1024;
+/** Absolute path to the failure log. */
+export function notifyLogPath(opts) {
+    return path.join(gocodeDir(opts), "notify.log");
+}
+function errMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/** Strip trailing slashes so `${server}/path` is always clean. */
+function normalizeServer(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+/** Build the JSON body, dropping any undefined/empty optional fields. */
+function buildBody(payload) {
+    const body = { kind: payload.kind };
+    for (const field of ["title", "body", "source", "project", "dedupe_key"]) {
+        const v = payload[field];
+        if (typeof v === "string" && v !== "")
+            body[field] = v;
+    }
+    return body;
+}
+/**
+ * Append one line to `~/.gocode/notify.log`. Best-effort: any error here is
+ * swallowed — logging must never be the thing that blocks a notification.
+ * Rotates to `notify.log.1` once the file exceeds {@link MAX_LOG_BYTES}.
+ */
+export async function appendLog(line, opts) {
+    try {
+        await fs.mkdir(gocodeDir(opts), { recursive: true, mode: 0o700 });
+        const file = notifyLogPath(opts);
+        try {
+            const st = await fs.stat(file);
+            if (st.size > MAX_LOG_BYTES) {
+                // Overwrite any prior backup; keep exactly one rotation.
+                await fs.rename(file, `${file}.1`).catch(() => { });
+            }
+        }
+        catch {
+            // No existing log → nothing to rotate.
+        }
+        const ts = opts?.timestamp ? opts.timestamp() : new Date().toISOString();
+        await fs.appendFile(file, `${ts} ${line}\n`);
+    }
+    catch {
+        // Intentionally silent — see contract above.
+    }
+}
+async function failure(reason, opts, extra = {}) {
+    await appendLog(`SEND FAIL: ${reason}`, opts);
+    return { ok: false, error: reason, ...extra };
+}
+/**
+ * Send one push to `/notify/send`. Resolves (never rejects) to a
+ * {@link SendResult}; callers may treat ANY result as "exit 0".
+ */
+export async function send(payload, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    let creds;
+    try {
+        creds = await readCredentials(opts);
+    }
+    catch (err) {
+        return failure(`credentials unreadable: ${errMessage(err)}`, opts);
+    }
+    if (!creds) {
+        return failure("not paired — run `gocode-notify login` first", opts);
+    }
+    const server = normalizeServer(opts.server ?? creds.server ?? DEFAULT_SERVER);
+    const url = `${server}/api/v1/notify/send`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${creds.api_key}`,
+            },
+            body: JSON.stringify(buildBody(payload)),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            return failure(`server responded ${res.status} for kind=${payload.kind}`, opts, {
+                status: res.status,
+            });
+        }
+        let sent;
+        try {
+            const json = (await res.json());
+            if (typeof json?.sent === "number")
+                sent = json.sent;
+        }
+        catch {
+            // A 2xx with an unparseable body still counts as delivered.
+        }
+        return { ok: true, status: res.status, sent };
+    }
+    catch (err) {
+        const reason = controller.signal.aborted
+            ? `timeout after ${timeoutMs}ms for kind=${payload.kind}`
+            : `request failed: ${errMessage(err)}`;
+        return failure(reason, opts);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/settings.js

@@ -0,0 +1,213 @@
+// settings.ts — the canonical GoCode Notify settings schema (PRD §3.4), mirrored
+// in the TypeScript CLI. ONE source of truth for:
+//   • the default settings blob (auto-push OFF, all kinds on — the conservative
+//     posture from §0.5),
+//   • the set of VALID dotted setting keys + their value types/enums,
+//   • coercion of a CLI string value into the typed value the schema expects,
+//   • the deep-merge that layers a per-repo override over the global blob (§3.4).
+//
+// `config.ts` (T-C5) uses this to validate `config set <key> <value>` before it
+// PUTs to the server, and to merge cached global ← per-repo settings on read.
+//
+// Zero runtime deps — only the type system + plain objects; no Node built-ins
+// needed here. Keep this in lockstep with the server validator (§3.3) and the
+// Flutter `notify_settings.dart` model (§3.4, T-A1).
+/** Schema version stamped into a fresh settings blob (PRD §3.4). */
+export const NOTIFY_SETTINGS_VERSION = 1;
+/**
+ * The default global settings blob (PRD §3.4). Conservative posture (§0.5):
+ * auto-push OFF, branch guard ON, every notification kind ON. Used as the
+ * fail-safe when no server/cache value is available.
+ */
+export const DEFAULT_NOTIFY_SETTINGS = {
+    version: NOTIFY_SETTINGS_VERSION,
+    kinds: {
+        finished: true,
+        error: true,
+        awaiting_input: true,
+        loop_completed: true,
+        loop_halted: true,
+    },
+    min_duration_seconds: 0,
+    quiet_hours: {
+        enabled: false,
+        start: "23:00",
+        end: "07:00",
+        tz: "America/Chicago",
+    },
+    auto_push: {
+        enabled: false,
+        default_branch: null,
+        allow_protected: false,
+        remote: "origin",
+        skip_git_hooks: false,
+    },
+    commit_message: {
+        mode: "auto",
+        command: null,
+        max_diff_bytes: 61440,
+    },
+};
+/**
+ * Every dotted setting key the CLI accepts in `config set <key> <value>`, with
+ * the value type the schema requires. This is the allow-list: any key NOT here is
+ * rejected with a helpful error (PRD §2.6 "reject unknown keys").
+ */
+export const KEY_SPECS = {
+    "kinds.finished": { kind: "boolean" },
+    "kinds.error": { kind: "boolean" },
+    "kinds.awaiting_input": { kind: "boolean" },
+    "kinds.loop_completed": { kind: "boolean" },
+    "kinds.loop_halted": { kind: "boolean" },
+    min_duration_seconds: { kind: "int_nonneg" },
+    "quiet_hours.enabled": { kind: "boolean" },
+    "quiet_hours.start": { kind: "time" },
+    "quiet_hours.end": { kind: "time" },
+    "quiet_hours.tz": { kind: "string" },
+    "auto_push.enabled": { kind: "boolean" },
+    "auto_push.default_branch": { kind: "string_or_null" },
+    // Per-repo override branch — only meaningful with --repo (§2.4 step 1).
+    "auto_push.branch": { kind: "string_or_null", repoOnly: true },
+    "auto_push.allow_protected": { kind: "boolean" },
+    "auto_push.remote": { kind: "string" },
+    "auto_push.skip_git_hooks": { kind: "boolean" },
+    "commit_message.mode": { kind: "enum", enumValues: ["auto", "ai", "deterministic"] },
+    "commit_message.command": { kind: "string_or_null" },
+    "commit_message.max_diff_bytes": { kind: "int_pos" },
+};
+/** Sorted list of every valid `config set` key — for help text + error messages. */
+export function validKeys() {
+    return Object.keys(KEY_SPECS).sort();
+}
+const TIME_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+// Convenience shorthand: `config set quiet_hours "23:00-07:00"` (PRD §2.6 example).
+const QUIET_RANGE_RE = /^([01]\d|2[0-3]:[0-5]\d|[0-2]?\d:[0-5]\d)-([0-2]?\d:[0-5]\d)$/;
+function ok(partial) {
+    return { ok: true, partial };
+}
+function fail(error) {
+    return { ok: false, error };
+}
+/** Build the nested partial blob `{ a: { b: value } }` from a dotted key path. */
+function nest(key, value) {
+    const parts = key.split(".");
+    const root = {};
+    let cursor = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const next = {};
+        cursor[parts[i]] = next;
+        cursor = next;
+    }
+    cursor[parts[parts.length - 1]] = value;
+    return root;
+}
+/** Coerce a raw CLI string into the typed value the key expects, or an error. */
+function coerce(spec, key, raw) {
+    switch (spec.kind) {
+        case "boolean": {
+            if (raw === "true")
+                return { value: true };
+            if (raw === "false")
+                return { value: false };
+            return { error: `"${key}" expects a boolean (true|false), got "${raw}"` };
+        }
+        case "int_nonneg":
+        case "int_pos": {
+            if (!/^-?\d+$/.test(raw))
+                return { error: `"${key}" expects an integer, got "${raw}"` };
+            const n = Number.parseInt(raw, 10);
+            if (spec.kind === "int_nonneg" && n < 0)
+                return { error: `"${key}" must be ≥ 0, got ${n}` };
+            if (spec.kind === "int_pos" && n <= 0)
+                return { error: `"${key}" must be > 0, got ${n}` };
+            return { value: n };
+        }
+        case "time": {
+            if (!TIME_RE.test(raw))
+                return { error: `"${key}" expects a time HH:MM (24h), got "${raw}"` };
+            return { value: raw };
+        }
+        case "string": {
+            if (raw.trim() === "")
+                return { error: `"${key}" must be a non-empty string` };
+            return { value: raw };
+        }
+        case "string_or_null": {
+            if (raw === "null")
+                return { value: null };
+            if (raw.trim() === "")
+                return { error: `"${key}" must be a non-empty string or "null"` };
+            return { value: raw };
+        }
+        case "enum": {
+            const allowed = spec.enumValues ?? [];
+            if (!allowed.includes(raw)) {
+                return { error: `"${key}" must be one of: ${allowed.join(", ")} (got "${raw}")` };
+            }
+            return { value: raw };
+        }
+    }
+}
+/**
+ * Validate + coerce a single `config set <key> <value>` into the partial blob to
+ * PUT to the server. `repo` indicates the write targets a per-repo override
+ * (`--repo`); per-repo-only keys are rejected on the global path and vice-versa.
+ *
+ * Special case: the `quiet_hours` shorthand `HH:MM-HH:MM` (PRD §2.6 example)
+ * expands to `{ quiet_hours: { enabled: true, start, end } }`.
+ */
+export function setSetting(key, raw, opts = {}) {
+    // Convenience: `quiet_hours "23:00-07:00"` → enable + start/end (PRD §2.6).
+    if (key === "quiet_hours") {
+        const m = raw.match(QUIET_RANGE_RE);
+        if (!m)
+            return fail(`"quiet_hours" shorthand expects "HH:MM-HH:MM" (e.g. 23:00-07:00), got "${raw}"`);
+        const start = m[1].length === 2 ? `${m[1]}:00` : m[1];
+        const end = m[2];
+        if (!TIME_RE.test(start) || !TIME_RE.test(end)) {
+            return fail(`"quiet_hours" times must be HH:MM (24h), got "${raw}"`);
+        }
+        return ok({ quiet_hours: { enabled: true, start, end } });
+    }
+    const spec = KEY_SPECS[key];
+    if (!spec) {
+        return fail(`unknown setting key "${key}". Valid keys:\n  ${validKeys().join("\n  ")}`);
+    }
+    if (spec.repoOnly && !opts.repo) {
+        return fail(`"${key}" is a per-repo override — pass --repo to set it for the current repo`);
+    }
+    const c = coerce(spec, key, raw);
+    if ("error" in c)
+        return fail(c.error);
+    return ok(nest(key, c.value));
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Deep-merge `override` over `base` (PRD §3.4): nested plain objects merge
+ * recursively; scalars, arrays, and explicit `null` in the override replace the
+ * base value. Neither input is mutated.
+ */
+export function deepMerge(base, override) {
+    const out = { ...base };
+    for (const [k, ov] of Object.entries(override)) {
+        const bv = out[k];
+        if (isPlainObject(ov) && isPlainObject(bv)) {
+            out[k] = deepMerge(bv, ov);
+        }
+        else {
+            out[k] = ov;
+        }
+    }
+    return out;
+}
+/**
+ * Merge a per-repo override blob over the global blob (PRD §3.4 "Merge = deep-merge
+ * of the override over the global blob"). Returns a new object; inputs untouched.
+ */
+export function mergeSettings(global, override) {
+    if (!override)
+        return { ...global };
+    return deepMerge(global, override);
+}

package/dist/src/setup.js

@@ -0,0 +1,148 @@
+// gocode-notify `setup` — the one-line installer orchestration (PRD §5).
+//
+// Drives the documented install sequence end-to-end:
+//   1. Pair        — exchange a 6-digit code for an API key (skip if already
+//                    paired; `--force` re-pairs). Reuses the `login` flow.
+//   2. Detect      — probe well-known config dirs for installed agent runtimes
+//                    (Claude Code / Cursor / OpenCode). Reuses `detectRuntimes`.
+//   3. Write configs — for each DETECTED runtime, write its hooks/rule/MCP entry.
+//   4. Summary     — report exactly what was paired / detected / written.
+//
+// This module owns the ORCHESTRATION and its idempotency contract. The actual
+// per-runtime config writers (Claude Code / Cursor) are dedicated follow-up
+// tracker tasks; `setup` consumes them through the {@link RuntimeConfigWriter}
+// seam. Until those land, the default writer reports each detected runtime as
+// "pending" (nothing written, no failure) so the orchestration is complete,
+// honest, and testable now, and the writers drop in without touching this file.
+//
+// Every step is reported as a {@link StepLine}, so the CLI layer can render the
+// same result either as a human summary or as one JSON line per step in
+// `--agent-driven` mode (PRD §2 Path 2, §4.4) without re-deriving anything.
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { login } from "./login.js";
+import { readCredentials } from "./creds.js";
+import { detectRuntimes } from "./status.js";
+import { writeClaudeConfig, CLAUDE_RUNTIME_NAME } from "./claude.js";
+import { writeCursorConfig, CURSOR_RUNTIME_NAME } from "./cursor.js";
+/**
+ * Default config writer: reports the detected runtime as pending. Replaced by
+ * the Claude Code / Cursor config-writer tasks (which register real writers via
+ * {@link SetupOptions.writeConfig}). Writing nothing is fully idempotent.
+ */
+export const pendingConfigWriter = async (runtime) => ({
+    runtime: runtime.name,
+    written: [],
+    skipped: true,
+    detail: "config writer not yet implemented",
+});
+/**
+ * The default config writer used in production: routes each detected runtime to
+ * its dedicated writer. Claude Code is wired to {@link writeClaudeConfig} and
+ * Cursor to {@link writeCursorConfig}; runtimes whose writer has not landed yet
+ * (OpenCode) fall through to {@link pendingConfigWriter} (a no-op, fully
+ * idempotent).
+ */
+export const defaultConfigWriter = async (runtime, opts) => {
+    if (runtime.name === CLAUDE_RUNTIME_NAME)
+        return writeClaudeConfig(runtime, opts);
+    if (runtime.name === CURSOR_RUNTIME_NAME)
+        return writeCursorConfig(runtime, opts);
+    return pendingConfigWriter(runtime, opts);
+};
+/**
+ * Run the installer orchestration (PRD §5). Resolves (never rejects) to a
+ * {@link SetupResult}. Idempotent: a second run with credentials already present
+ * skips pairing (unless `--force`), and the config writers are themselves
+ * idempotent, so re-running converges without clobbering.
+ */
+export async function setup(opts = {}) {
+    const pathOpts = { home: opts.home };
+    const steps = [];
+    // ── Step 1: pair (skip when already paired and not forced) ────────────────
+    const pair = await runPairStep(opts, pathOpts);
+    steps.push({
+        step: pair.skipped ? "pair (skipped)" : "pair",
+        ok: pair.ok,
+        detail: pair.detail,
+    });
+    // ── Step 2: detect installed runtimes ─────────────────────────────────────
+    const detect = opts.detectImpl ?? detectRuntimes;
+    const detected = await detect(pathOpts);
+    const detectedNames = detected.filter((r) => r.detected).map((r) => r.name);
+    steps.push({
+        step: "detect",
+        ok: true,
+        detail: detectedNames.length > 0
+            ? `detected: ${detectedNames.join(", ")}`
+            : "no agent runtimes detected",
+    });
+    // ── Step 3: write configs for each DETECTED runtime ───────────────────────
+    // Undetected runtimes are skipped silently (PRD §5.2) — only what's installed
+    // gets configured.
+    const writeConfig = opts.writeConfig ?? defaultConfigWriter;
+    const configs = [];
+    for (const runtime of detected.filter((r) => r.detected)) {
+        const result = await writeConfig(runtime, pathOpts);
+        configs.push(result);
+        steps.push({
+            step: `config:${result.runtime}`,
+            ok: !result.failed,
+            detail: result.detail,
+        });
+    }
+    // ── Step 4: summary ───────────────────────────────────────────────────────
+    const writtenCount = configs.filter((c) => c.written.length > 0).length;
+    const hardFail = configs.some((c) => c.failed);
+    const ok = pair.ok && !hardFail;
+    steps.push({
+        step: "summary",
+        ok,
+        detail: `${pair.skipped ? "already paired" : pair.ok ? "paired" : "not paired"}; ` +
+            `${detectedNames.length} runtime(s) detected; ${writtenCount} config(s) written`,
+    });
+    return { ok, pair, detected, configs, steps };
+}
+/**
+ * The pairing sub-step. Reads existing credentials first: if valid creds are
+ * present and `--force` was not passed, pairing is SKIPPED (idempotent re-run).
+ * Otherwise it runs the `login` flow (code from `--pair-code` or the injected
+ * prompt). A malformed creds file is treated as "not paired" so `--force` is
+ * not required to recover from corruption.
+ */
+async function runPairStep(opts, pathOpts) {
+    let existing = null;
+    try {
+        existing = await readCredentials(pathOpts);
+    }
+    catch {
+        existing = null; // malformed → re-pair to recover
+    }
+    if (existing && !opts.force) {
+        return {
+            ok: true,
+            skipped: true,
+            credentials: existing,
+            detail: `already paired as ${existing.user_id} (${existing.label}) — use --force to re-pair`,
+        };
+    }
+    const pair = opts.pairImpl ?? login;
+    const result = await pair({
+        code: opts.pairCode,
+        label: opts.label,
+        server: opts.server,
+        home: opts.home,
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs,
+        promptCode: opts.promptCode,
+    });
+    if (result.ok && result.credentials) {
+        return {
+            ok: true,
+            skipped: false,
+            credentials: result.credentials,
+            detail: `paired as ${result.credentials.user_id} (${result.credentials.label})`,
+        };
+    }
+    return { ok: false, skipped: false, detail: result.error ?? "pairing failed" };
+}