@trygocode/notify 0.1.0

package/dist/src/commit_message.js

@@ -0,0 +1,321 @@
+// Commit-message composition for `gocode-notify push-on-stop` (PRD §2.3).
+//
+// SCOPE OF THIS MODULE (T-C1): the DETERMINISTIC fallback only — the structured
+// message built purely from the staged diff stat + branch + agent source, plus
+// the cheap path-based `<type>` inference. This path has zero dependencies, never
+// touches the network, and never shells out, so it is ALWAYS available and is the
+// guaranteed fallback the PRD requires ("the push must NEVER block or fail because
+// the AI summary was unavailable" — §0.4).
+//
+// The local-summariser resolution chain + sanitiser + 8s cap that wrap this
+// fallback (the full `composeCommitMessage()` entry point — T-C2) are layered on
+// top of these pure functions at the bottom of this file: they call
+// `buildDeterministicMessage` when the AI path is disabled, fails, or times out.
+//
+// Zero runtime deps — only Node built-ins (child_process / fs for the local
+// summariser subprocess), to match the package's zero-dep rule.
+import { spawn } from "node:child_process";
+import { accessSync, constants as fsConstants } from "node:fs";
+import path from "node:path";
+/** Max number of per-file stat lines rendered before collapsing to "...and M more". */
+const MAX_STAT_LINES = 10;
+const MARKDOWN_RE = /\.(?:md|mdx|markdown)$/i;
+// A path counts as "test" if any segment is a conventional test directory, or the
+// filename carries a `.test.`/`.spec.` infix (covers TS/JS/Dart/Python conventions).
+const TEST_DIR_RE = /(?:^|\/)(?:tests?|__tests__|spec|specs)\//i;
+const TEST_FILE_RE = /(?:^|\/)[^/]*\.(?:test|spec)\.[^/]+$/i;
+// "chore" = config / lockfiles / dotfiles that aren't product code. Kept deliberately
+// conservative: a clear lockfile, a known config filename, or a repo dotfile.
+const LOCKFILE_RE = /(?:^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|pubspec\.lock|poetry\.lock|Cargo\.lock|Gemfile\.lock|composer\.lock)$/i;
+const CONFIG_FILE_RE = /(?:^|\/)(?:package\.json|tsconfig(?:\.[^/]+)?\.json|pubspec\.yaml|\.gitignore|\.gitattributes|\.editorconfig|\.npmrc|\.nvmrc|\.eslintrc(?:\.[^/]+)?|\.prettierrc(?:\.[^/]+)?|[^/]*\.config\.[^/]+)$/i;
+function isDocsPath(path) {
+    return MARKDOWN_RE.test(path);
+}
+function isTestPath(path) {
+    return TEST_DIR_RE.test(path) || TEST_FILE_RE.test(path);
+}
+function isChorePath(path) {
+    return LOCKFILE_RE.test(path) || CONFIG_FILE_RE.test(path);
+}
+/**
+ * Infer the commit `<type>` from the changed paths (PRD §2.3), deterministically:
+ *   • `docs`  — every path is markdown.
+ *   • `test`  — every path lives in a test dir or is a `.test.`/`.spec.` file.
+ *   • `chore` — every path is a lockfile / known config / repo dotfile.
+ *   • `feat`  — anything else (the catch-all; also the empty-changeset default).
+ *
+ * "Every path" semantics: a mixed changeset (e.g. a `.ts` source file + its test)
+ * falls through to `feat`, which is the safe, honest default for a real change.
+ */
+export function inferCommitType(paths) {
+    if (paths.length === 0)
+        return "feat";
+    if (paths.every(isDocsPath))
+        return "docs";
+    if (paths.every(isTestPath))
+        return "test";
+    if (paths.every(isChorePath))
+        return "chore";
+    return "feat";
+}
+/**
+ * Parse `git diff --staged --numstat` output into {@link FileStat}s. numstat emits
+ * one tab-separated `added\tdeleted\tpath` record per file; binary files report
+ * `-` for both counts. Blank lines and malformed records are skipped (forgiving —
+ * this feeds a best-effort commit message, never a hard gate).
+ *
+ * Rename records (`old => new`, `dir/{a => b}/file`) are preserved verbatim in
+ * `path`; we do not attempt to expand them — the raw git rendering is fine for a
+ * commit-body stat line.
+ */
+export function parseNumstat(numstat) {
+    const out = [];
+    for (const rawLine of numstat.split("\n")) {
+        const line = rawLine.replace(/\r$/, "");
+        if (line.trim() === "")
+            continue;
+        const m = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
+        if (!m)
+            continue;
+        const [, addedRaw, deletedRaw, path] = m;
+        const binary = addedRaw === "-" || deletedRaw === "-";
+        out.push({
+            path,
+            added: addedRaw === "-" ? 0 : Number.parseInt(addedRaw, 10),
+            deleted: deletedRaw === "-" ? 0 : Number.parseInt(deletedRaw, 10),
+            ...(binary ? { binary: true } : {}),
+        });
+    }
+    return out;
+}
+/** Render one file's stat line for the commit body: `path | +A -D` (or `| bin`). */
+function statLine(f) {
+    if (f.binary)
+        return `${f.path} | bin`;
+    return `${f.path} | +${f.added} -${f.deleted}`;
+}
+/**
+ * Build the deterministic fallback commit message (PRD §2.3 template):
+ *
+ *   <type>: <N> file(s) changed on <branch>
+ *
+ *   <up to 10 "path | +A -D" lines, then "...and M more">
+ *
+ *   Auto-committed by GoCode Notify (source: <source>).
+ *
+ * Pure and total: given the same input it always returns the same string, and it
+ * never throws on an empty changeset (returns a coherent "0 files" message — the
+ * caller is responsible for the clean-tree no-op gate, §2.1 step 5).
+ */
+export function buildDeterministicMessage({ files, branch, source }) {
+    const type = inferCommitType(files.map((f) => f.path));
+    const n = files.length;
+    const subject = `${type}: ${n} ${n === 1 ? "file" : "files"} changed on ${branch}`;
+    const shown = files.slice(0, MAX_STAT_LINES);
+    const lines = shown.map(statLine);
+    const more = n - shown.length;
+    if (more > 0)
+        lines.push(`...and ${more} more`);
+    const statBlock = lines.join("\n");
+    const footer = `Auto-committed by GoCode Notify (source: ${source}).`;
+    // A real changeset always has a stat block; guard the empty case so we never
+    // emit a stray blank line that would confuse `git commit -F`.
+    return statBlock === ""
+        ? `${subject}\n\n${footer}`
+        : `${subject}\n\n${statBlock}\n\n${footer}`;
+}
+/** Hard cap (ms) on the WHOLE AI attempt, per PRD §2.3 ("8s hard cap total"). */
+export const AI_TIMEOUT_MS = 8000;
+/** Default diff byte cap (PRD §2.3 / §3.4 `max_diff_bytes`: 60 KB). */
+export const DEFAULT_MAX_DIFF_BYTES = 61440;
+/** Max subject-line length the sanitiser clamps AI output to (PRD §2.3: ≤ 72). */
+export const SUBJECT_MAX = 72;
+/** Fixed prompt prefix sent to the local summariser (PRD §2.3). */
+export const COMMIT_PROMPT = "Write a concise git commit message (imperative subject ≤ 72 chars, optional " +
+    "1–3 line body) describing these staged changes. Output ONLY the message.";
+/**
+ * Resolve the local summariser command (PRD §2.3 detection order):
+ *   1. `settings.command` (explicit user-provided) — wins if non-empty.
+ *   2. Auto-detect from `source`: `claude_code` → `claude`, `cursor` →
+ *      `cursor-agent`, each only if on PATH.
+ *   3. Else `ollama` if present.
+ * Returns `null` when nothing is configured/available (→ deterministic fallback).
+ */
+export function resolveSummariserCommand(settings, source, commandExists) {
+    const explicit = settings?.command?.trim();
+    if (explicit)
+        return explicit;
+    if (source === "claude_code" && commandExists("claude"))
+        return "claude -p";
+    if (source === "cursor" && commandExists("cursor-agent"))
+        return "cursor-agent --print";
+    if (commandExists("ollama"))
+        return "ollama run llama3.2";
+    return null;
+}
+/**
+ * Sanitise raw AI output into a usable commit message (PRD §2.3):
+ *   • normalise newlines, strip surrounding whitespace;
+ *   • drop ``` code-fence lines wherever they appear;
+ *   • drop a single leading "Here is…"/"Sure,…"/"Commit message:" preamble line;
+ *   • strip an inline `Commit message:` prefix off the subject;
+ *   • clamp the subject (first line) to {@link SUBJECT_MAX} chars.
+ * Returns `""` for empty/garbage input so the caller uses the deterministic path.
+ */
+export function sanitiseAiMessage(raw) {
+    if (!raw)
+        return "";
+    let text = raw.replace(/\r\n/g, "\n").trim();
+    if (text === "")
+        return "";
+    // Drop any code-fence marker lines (handles ```lang … ``` wrapping robustly).
+    text = text
+        .split("\n")
+        .filter((l) => !/^\s*```/.test(l))
+        .join("\n")
+        .trim();
+    const lines = text.split("\n");
+    while (lines.length && lines[0].trim() === "")
+        lines.shift();
+    if (lines.length === 0)
+        return "";
+    // Strip ONE leading conversational preamble off the subject — whether it sits
+    // on its own line ("Here is the commit message:") or is an inline prefix on
+    // the subject ("Sure! feat: …", "Commit message: chore: …"). When the line was
+    // pure preamble it becomes empty and we drop it, falling through to the body.
+    const PREAMBLE_PREFIX_RE = /^\s*(?:here(?:'s| is)\b[^\n:]*:\s*|sure[,!.:]+\s*|certainly[,!.:]*\s*|of course[,!.:]*\s*|okay[,!.:]+\s*|commit message:\s*)/i;
+    lines[0] = lines[0].replace(PREAMBLE_PREFIX_RE, "");
+    while (lines.length && lines[0].trim() === "")
+        lines.shift();
+    if (lines.length === 0)
+        return "";
+    // Clamp the subject (first line) to SUBJECT_MAX chars.
+    lines[0] = lines[0].trim();
+    if (lines[0].length > SUBJECT_MAX)
+        lines[0] = lines[0].slice(0, SUBJECT_MAX).trimEnd();
+    return lines.join("\n").trim();
+}
+/**
+ * Truncate `diff` to at most `maxBytes` UTF-8 bytes, appending a clear marker
+ * when it was cut. Best-effort: a multibyte char straddling the boundary may be
+ * dropped — acceptable for a prompt hint that the AI only needs the gist of.
+ */
+export function truncateDiff(diff, maxBytes) {
+    const buf = Buffer.from(diff, "utf8");
+    if (buf.byteLength <= maxBytes)
+        return diff;
+    const head = buf.subarray(0, maxBytes).toString("utf8");
+    return `${head}\n…[diff truncated at ${maxBytes} bytes]`;
+}
+/** Build the summariser stdin: prompt prefix, then the stat summary + diff. */
+function buildSummariserInput(diff, statSummary) {
+    const stat = statSummary.trim();
+    const statBlock = stat === "" ? "" : `\n\n${stat}`;
+    return `${COMMIT_PROMPT}${statBlock}\n\n${diff}`;
+}
+/**
+ * Default `commandExists`: true when `bin` is executable on PATH (or, if it
+ * contains a path separator, executable at that exact path).
+ */
+export function defaultCommandExists(bin) {
+    if (bin.includes(path.sep)) {
+        try {
+            accessSync(bin, fsConstants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        try {
+            accessSync(path.join(dir, bin), fsConstants.X_OK);
+            return true;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return false;
+}
+/**
+ * Default summariser runner: argv-split the command on whitespace, spawn it with
+ * the prompt+diff on stdin, and resolve with stdout. The `signal` (the 8s cap)
+ * is passed to spawn so an over-budget call is killed. Rejects on spawn error,
+ * non-zero exit, or abort — all of which the caller maps to the fallback.
+ */
+export const defaultSummariserRunner = ({ command, input, signal }) => new Promise((resolve, reject) => {
+    const argv = command.split(/\s+/).filter(Boolean);
+    if (argv.length === 0) {
+        reject(new Error("empty summariser command"));
+        return;
+    }
+    const child = spawn(argv[0], argv.slice(1), { signal, stdio: ["pipe", "pipe", "ignore"] });
+    let out = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        out += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+        if (code === 0)
+            resolve(out);
+        else
+            reject(new Error(`summariser exited with code ${code}`));
+    });
+    // The child may exit before draining stdin; swallow the resulting EPIPE.
+    child.stdin.on("error", () => { });
+    child.stdin.end(input);
+});
+/**
+ * Attempt the local-AI summary path. Returns the sanitised message on success,
+ * or `null` for ANY non-success (disabled mode, no resolvable command, runner
+ * error, timeout, empty/garbage output). Never throws.
+ */
+async function tryAiSummary(input, deps) {
+    const settings = input.settings ?? {};
+    const mode = settings.mode ?? "auto";
+    if (mode === "deterministic")
+        return null;
+    const commandExists = deps.commandExists ?? defaultCommandExists;
+    const command = resolveSummariserCommand(settings, input.source, commandExists);
+    if (!command)
+        return null;
+    const runSummariser = deps.runSummariser ?? defaultSummariserRunner;
+    const timeoutMs = deps.timeoutMs ?? AI_TIMEOUT_MS;
+    const maxBytes = settings.max_diff_bytes ?? DEFAULT_MAX_DIFF_BYTES;
+    const stdin = buildSummariserInput(truncateDiff(input.stagedDiff, maxBytes), input.statSummary ?? "");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const stdout = await runSummariser({ command, input: stdin, signal: controller.signal });
+        const cleaned = sanitiseAiMessage(stdout ?? "");
+        return cleaned === "" ? null : cleaned;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Compose the commit message for `push-on-stop` (PRD §2.3). Tries the local-AI
+ * summariser (subject to mode + availability + the 8s cap) and ALWAYS falls back
+ * to {@link buildDeterministicMessage}. Total + non-blocking: it resolves with a
+ * usable message for every input and never rejects.
+ */
+export async function composeCommitMessage(input, deps = {}) {
+    const ai = await tryAiSummary(input, deps);
+    if (ai !== null)
+        return { message: ai, generator: "ai" };
+    return {
+        message: buildDeterministicMessage({
+            files: input.files,
+            branch: input.branch,
+            source: input.source,
+        }),
+        generator: "deterministic",
+    };
+}

package/dist/src/config.js

@@ -0,0 +1,348 @@
+// `gocode-notify config get|set|pull` — the dev-machine settings editor + the
+// hot-path settings resolver/cache (PRD §2.6, §2.1 step 1, §3.6).
+//
+// Two responsibilities live here:
+//
+//   1. The `config` CLI subcommand (PRD §2.6):
+//        config get [--repo]                 → print merged settings (server or cache)
+//        config set <key> <value> [--repo]   → validate key, PUT to server, refresh cache
+//        config pull                          → force-refresh the local cache from server
+//      Writes go to the server (the source of truth) AND update the local cache so
+//      the next stop-hook is immediate. Keys are validated against `settings.ts`
+//      (unknown keys rejected with the valid-key list).
+//
+//   2. The settings RESOLUTION + 60s-TTL cache the auto-push hot path needs
+//      (PRD §2.1 step 1) — deferred to here by `push.ts` (T-C3). `resolveNotifySettings`
+//      returns the merged blob for a repo: a fresh cache hit short-circuits the
+//      network; a stale entry re-pulls; if the network is down it falls back to the
+//      (possibly stale) cache; with no cache at all it returns the conservative
+//      defaults (auto-push OFF — fail-safe, §0.5).
+//
+// The cache lives in `~/.gocode/config.json` under `notify_settings` (PRD §2.1):
+//   notify_settings: { entries: { "<repo_key|__global__>": { settings, fetched_at_ms, repo_label? } } }
+//
+// Zero runtime deps — Node built-ins + an injectable `fetch` (so tests stub the
+// network and a temp HOME stubs fs).
+import { readConfig, writeConfig, readCredentials, } from "./creds.js";
+import { DEFAULT_NOTIFY_SETTINGS, setSetting, } from "./settings.js";
+import { deriveRepoIdentity } from "./repo_key.js";
+/** Server paths for the Notify settings API (PRD §3.3). */
+export const SETTINGS_PATH = "/api/v1/notify/settings";
+export const PROJECTS_PATH = "/api/v1/notify/settings/projects";
+/** Default cache TTL on the hot path (PRD §2.1 step 1: "short TTL (default 60s)"). */
+export const DEFAULT_CACHE_TTL_MS = 60_000;
+/** Default network timeout for `config` round-trips (mirrors `send`'s 5s cap). */
+export const DEFAULT_CONFIG_TIMEOUT_MS = 5000;
+/** Cache key used for the no-repo (global) entry. */
+export const GLOBAL_CACHE_KEY = "__global__";
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function normalizeServer(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+/** The cache key for a scope: a repo's `repo_key`, or the global sentinel. */
+export function cacheKeyForScope(scope) {
+    return scope.kind === "repo" ? scope.repo.repo_key : GLOBAL_CACHE_KEY;
+}
+// ── cache read/write (within ~/.gocode/config.json) ──────────────────────────
+function readCacheBlock(config) {
+    const block = config?.notify_settings;
+    if (block && typeof block === "object" && !Array.isArray(block)) {
+        const entries = block.entries;
+        if (entries && typeof entries === "object" && !Array.isArray(entries)) {
+            return { entries: entries };
+        }
+    }
+    return { entries: {} };
+}
+/** Read the settings cache out of `~/.gocode/config.json` (empty when absent). */
+export async function readSettingsCache(opts) {
+    let config = null;
+    try {
+        config = await readConfig(opts);
+    }
+    catch {
+        // A corrupt config.json must never wedge the hot path — treat as empty cache.
+        config = null;
+    }
+    return readCacheBlock(config);
+}
+/**
+ * Upsert one cache entry under `~/.gocode/config.json` `notify_settings.entries`,
+ * preserving every other key in config.json (round-trips unknown prefs, §0.1).
+ */
+export async function writeCacheEntry(key, entry, opts) {
+    let config = null;
+    try {
+        config = await readConfig(opts);
+    }
+    catch {
+        config = null;
+    }
+    const base = config ?? {};
+    const cache = readCacheBlock(base);
+    cache.entries[key] = entry;
+    await writeConfig({ ...base, notify_settings: cache }, opts);
+}
+/** True when `entry` is within `ttlMs` of `now` (i.e. still fresh). */
+export function isFresh(entry, ttlMs, now) {
+    return now - entry.fetched_at_ms < ttlMs;
+}
+function buildUrl(net, scope, forWrite) {
+    const base = normalizeServer(net.server);
+    if (scope.kind === "repo") {
+        const repo = scope.repo;
+        if (forWrite) {
+            const q = new URLSearchParams({ repo_label: repo.repo_label });
+            return `${base}${PROJECTS_PATH}/${encodeURIComponent(repo.repo_key)}?${q.toString()}`;
+        }
+        const q = new URLSearchParams({ repo_key: repo.repo_key, repo_label: repo.repo_label });
+        return `${base}${SETTINGS_PATH}?${q.toString()}`;
+    }
+    return `${base}${SETTINGS_PATH}`;
+}
+async function request(net, url, method, body) {
+    const fetchImpl = net.fetchImpl ?? globalThis.fetch;
+    const timeoutMs = net.timeoutMs ?? DEFAULT_CONFIG_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${net.apiKey}`,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            throw new Error(`server responded ${res.status}`);
+        const json = (await res.json());
+        if (json && typeof json === "object" && !Array.isArray(json)) {
+            return json;
+        }
+        throw new Error("server returned a non-object settings body");
+    }
+    catch (err) {
+        if (controller.signal.aborted)
+            throw new Error(`timeout after ${timeoutMs}ms`);
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** GET the merged settings for a scope from the server (PRD §3.3). */
+export async function fetchSettings(net, scope) {
+    return request(net, buildUrl(net, scope, false), "GET");
+}
+/** PUT a partial settings blob (global) or per-repo override (PRD §3.3). */
+export async function putSettings(net, scope, partial) {
+    return request(net, buildUrl(net, scope, true), "PUT", partial);
+}
+/**
+ * Resolve the merged Notify settings for a repo (PRD §2.1 step 1, §3.6). Order:
+ *   1. fresh cache hit (within TTL) and not forcing → use cache (no network).
+ *   2. else pull from server → cache it → return ("network").
+ *   3. server unreachable / unpaired → fall back to the (possibly stale) cache.
+ *   4. no cache at all → conservative DEFAULTS (auto-push OFF — fail-safe).
+ * NEVER throws: the caller (a stop hook) must never be blocked by settings I/O.
+ */
+export async function resolveNotifySettings(opts = {}) {
+    const now = (opts.now ?? Date.now)();
+    const ttlMs = opts.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+    const scope = opts.repo ? { kind: "repo", repo: opts.repo } : { kind: "global" };
+    const key = cacheKeyForScope(scope);
+    const cache = await readSettingsCache(opts);
+    const cached = cache.entries[key];
+    if (cached && !opts.forcePull && isFresh(cached, ttlMs, now)) {
+        return { settings: cached.settings, source: "cache" };
+    }
+    // Need a network pull. Resolve credentials; if unpaired, fall back gracefully.
+    let creds;
+    try {
+        creds = await readCredentials(opts);
+    }
+    catch {
+        creds = null;
+    }
+    if (creds) {
+        const net = {
+            server: normalizeServer(opts.server ?? creds.server),
+            apiKey: creds.api_key,
+            fetchImpl: opts.fetchImpl,
+            timeoutMs: opts.timeoutMs,
+        };
+        try {
+            const settings = await fetchSettings(net, scope);
+            await writeCacheEntry(key, {
+                settings,
+                fetched_at_ms: now,
+                repo_label: opts.repo?.repo_label,
+            }, opts).catch(() => { });
+            return { settings, source: "network" };
+        }
+        catch {
+            // fall through to cache / default
+        }
+    }
+    if (cached)
+        return { settings: cached.settings, source: "cache" };
+    return { settings: { ...DEFAULT_NOTIFY_SETTINGS }, source: "default" };
+}
+/**
+ * Parse `config <sub> [positionals] [--repo] [--json] [--server URL]`. Unlike
+ * `cli.parseFlags`, this PRESERVES bare positionals (the `<key> <value>` of
+ * `config set`) while still pulling the known flags out of the stream.
+ */
+export function parseConfigArgs(args) {
+    const out = { positionals: [], repo: false, json: false };
+    out.sub = args[0];
+    for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--repo") {
+            out.repo = true;
+        }
+        else if (a === "--json") {
+            out.json = true;
+        }
+        else if (a === "--server") {
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                out.server = next;
+                i++;
+            }
+        }
+        else if (a.startsWith("--server=")) {
+            out.server = a.slice("--server=".length);
+        }
+        else if (a.startsWith("--")) {
+            // Unknown flag — ignore (keeps positionals clean).
+        }
+        else {
+            out.positionals.push(a);
+        }
+    }
+    return out;
+}
+async function resolveScope(parsed, deps) {
+    if (!parsed.repo)
+        return { kind: "global" };
+    const derive = deps.deriveRepo ?? ((cwd) => deriveRepoIdentity(cwd ?? process.cwd()));
+    const repo = await derive(deps.cwd);
+    return { kind: "repo", repo };
+}
+async function netFromCreds(parsed, deps) {
+    let creds;
+    try {
+        creds = await readCredentials(deps);
+    }
+    catch (e) {
+        return { error: `credentials unreadable: ${errMessage(e)}` };
+    }
+    if (!creds)
+        return { error: "not paired — run `gocode-notify login` first" };
+    return {
+        server: normalizeServer(parsed.server ?? creds.server),
+        apiKey: creds.api_key,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+    };
+}
+/**
+ * Handle `gocode-notify config get|set|pull`. Interactive diagnostic — exits
+ * non-zero on a usage/validation/IO error so the human/agent sees it (unlike the
+ * fire-and-forget hooks which always exit 0).
+ */
+export async function cmdConfig(args, deps = {}) {
+    const out = deps.out ?? ((l) => console.log(l));
+    const err = deps.err ?? ((l) => console.error(l));
+    const parsed = parseConfigArgs(args);
+    switch (parsed.sub) {
+        case "get":
+            return cmdConfigGet(parsed, deps, out, err);
+        case "set":
+            return cmdConfigSet(parsed, deps, out, err);
+        case "pull":
+            return cmdConfigPull(parsed, deps, out, err);
+        default:
+            err(`gocode-notify config: expected a subcommand (get | set | pull), got "${parsed.sub ?? ""}"`);
+            return 2;
+    }
+}
+async function cmdConfigGet(parsed, deps, out, err) {
+    const scope = await resolveScope(parsed, deps);
+    const result = await resolveNotifySettings({
+        home: deps.home,
+        repo: scope.kind === "repo" ? scope.repo : undefined,
+        server: parsed.server,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        ttlMs: deps.ttlMs,
+        now: deps.now,
+    });
+    out(JSON.stringify(result.settings, null, 2));
+    if (result.source === "default") {
+        err("gocode-notify config get: server unreachable and no cache — showing defaults");
+    }
+    return 0;
+}
+async function cmdConfigSet(parsed, deps, out, err) {
+    const [key, ...valueParts] = parsed.positionals;
+    if (key === undefined || valueParts.length === 0) {
+        err("gocode-notify config set: usage: config set <key> <value> [--repo]");
+        return 2;
+    }
+    const value = valueParts.join(" ");
+    const validated = setSetting(key, value, { repo: parsed.repo });
+    if (!validated.ok) {
+        err(`gocode-notify config set: ${validated.error}`);
+        return 2;
+    }
+    const scope = await resolveScope(parsed, deps);
+    const net = await netFromCreds(parsed, deps);
+    if ("error" in net) {
+        err(`gocode-notify config set: ${net.error}`);
+        return 1;
+    }
+    let merged;
+    try {
+        merged = await putSettings(net, scope, validated.partial);
+    }
+    catch (e) {
+        err(`gocode-notify config set: write failed (${errMessage(e)})`);
+        return 1;
+    }
+    // Refresh the local cache immediately so the next stop-hook honours it (§2.6).
+    const now = (deps.now ?? Date.now)();
+    await writeCacheEntry(cacheKeyForScope(scope), {
+        settings: merged,
+        fetched_at_ms: now,
+        repo_label: scope.kind === "repo" ? scope.repo.repo_label : undefined,
+    }, deps).catch(() => { });
+    const where = scope.kind === "repo" ? ` for ${scope.repo.repo_label}` : "";
+    out(`✓ Set ${key}=${value}${where}.`);
+    return 0;
+}
+async function cmdConfigPull(parsed, deps, out, err) {
+    const scope = await resolveScope(parsed, deps);
+    const result = await resolveNotifySettings({
+        home: deps.home,
+        repo: scope.kind === "repo" ? scope.repo : undefined,
+        server: parsed.server,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        ttlMs: deps.ttlMs,
+        now: deps.now,
+        forcePull: true,
+    });
+    if (result.source !== "network") {
+        err("gocode-notify config pull: server unreachable — local cache unchanged");
+        return 1;
+    }
+    out(JSON.stringify(result.settings, null, 2));
+    out(`✓ Pulled latest settings${scope.kind === "repo" ? ` for ${scope.repo.repo_label}` : ""}.`);
+    return 0;
+}