@tokenfactory/acc-runner 0.25.0 → 0.27.0

package/dist/doctor.js

@@ -1,658 +0,0 @@
-/**
- * `acc-runner doctor` — environment checks. Returns 0 if all green, 1 if
- * any check failed. Each check carries a remediation hint so users can
- * self-serve.
- */
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { execa } from "execa";
-import chalk from "chalk";
-import { buildEnv } from "./bin-resolve.js";
-import { resolveAuthMode, describeAuthMode, authPrecedenceHint } from "./anthropic-auth.js";
-import { configSources, loadConfigOrNull } from "./config.js";
-import { getTokenProvider, resolveTokenMode } from "./token-provider.js";
-import { createRunnerClient } from "./supabase.js";
-import { checkVersion } from "./version-check.js";
-import { PROTOCOL_VERSION } from "./types.js";
-import { locksDir, listStaleLocks } from "./runtime/locks.js";
-import { workDir, listOrphanWorktrees } from "./runtime/worktree.js";
-import { getQuarantine, quarantineFile } from "./runtime/quarantine.js";
-import { findLiveLockHolder, listForeignRunnerPids, singletonLockPath, } from "./runtime/singleton.js";
-import { getClaudeVersion, npmLatestVersion, readTaskEnv, } from "./runtime/version-drift.js";
-import { compareSemver as compareSemverVer } from "./version-check.js";
-import { PACKAGE_VERSION } from "./pkg-version.js";
-export const LAUNCHD_LABEL = "com.tokenfactory.acc-runner";
-export function launchdPlistPath() {
-    return path.join(os.homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
-}
-export const ENV_NAMES = {
-    publicUrl: "ACC_PUBLIC_URL",
-    supabaseUrl: "ACC_SUPABASE_URL",
-    supabaseAnonKey: "ACC_SUPABASE_ANON_KEY",
-    repoPath: "ACC_REPO_PATH",
-    targetRepo: "ACC_TARGET_REPO",
-    integrationBranch: "ACC_INTEGRATION_BRANCH",
-    capabilities: "ACC_RUNNER_CAPABILITIES",
-    worktreeRepoPath: "ACC_WORKTREE_REPO_PATH",
-};
-export const CONFIG_LABELS = {
-    publicUrl: "ACC public URL:",
-    supabaseUrl: "Supabase URL:",
-    supabaseAnonKey: "Supabase anon key:",
-    repoPath: "ACC repo path:",
-    targetRepo: "Target repo:",
-    integrationBranch: "Integration branch:",
-    capabilities: "Capabilities:",
-    worktreeRepoPath: "Worktree repo path:",
-};
-function maskKey(s) {
-    if (s.length <= 8)
-        return "<short>";
-    return `${s.slice(0, 4)}…${s.slice(-4)} (len ${s.length})`;
-}
-function formatConfig(cfg) {
-    const src = configSources();
-    const lines = Object.keys(CONFIG_LABELS).map((k) => {
-        // v0.41-B: worktreeRepoPath is optional at the config layer
-        // (undefined means "use repoPath"). Render "<not set>" rather than
-        // the literal string "undefined" so the doctor output is clean.
-        const raw = cfg[k];
-        const value = k === "supabaseAnonKey"
-            ? maskKey(cfg[k])
-            : raw === undefined
-                ? "<not set>"
-                : raw;
-        const tag = src[k] === "env"
-            ? chalk.gray(`(env: ${ENV_NAMES[k]})`)
-            : chalk.gray("(default)");
-        return `  ${CONFIG_LABELS[k].padEnd(20, " ")}${value} ${tag}`;
-    });
-    return [chalk.bold("Config:"), ...lines].join("\n");
-}
-async function checkBinary(bin, args) {
-    try {
-        const { stdout } = await execa(bin, args, { env: buildEnv() });
-        const first = stdout.split(/\r?\n/)[0]?.trim() ?? bin;
-        return { ok: true, detail: first };
-    }
-    catch (err) {
-        return { ok: false, detail: err.message.split("\n")[0] };
-    }
-}
-async function checkNode() {
-    const major = Number(process.versions.node.split(".")[0]);
-    return {
-        name: "node 20+",
-        ok: major >= 20,
-        detail: `node ${process.versions.node}`,
-        fix: "Install Node 20.6+ (https://nodejs.org).",
-    };
-}
-async function checkClaude() {
-    const r = await checkBinary("claude", ["--version"]);
-    return {
-        name: "claude CLI in PATH",
-        ok: r.ok,
-        detail: r.detail,
-        fix: "Install Claude Code (https://claude.com/claude-code) and re-run.",
-    };
-}
-/**
- * v0.74-B (T-1780800000740201): advisory check that ANTHROPIC_API_KEY is set.
- * When present, spawned claude sessions authenticate via the API account,
- * which has no per-session cap. When absent claude falls back to the
- * operator's interactive OAuth session, which is subject to 429 session caps
- * during long autonomous runs — worth flagging but not a hard environment
- * failure, so this is a WARN (advisory, never fails the doctor exit code).
- */
-async function checkAnthropicKey() {
-    const mode = resolveAuthMode();
-    if (mode === "api-key") {
-        const hint = authPrecedenceHint();
-        return {
-            name: "ANTHROPIC_API_KEY set",
-            ok: true,
-            detail: hint ? `${describeAuthMode(mode)} — ${hint}` : describeAuthMode(mode),
-        };
-    }
-    return {
-        name: "ANTHROPIC_API_KEY set",
-        ok: false,
-        warn: true,
-        detail: describeAuthMode(mode),
-        fix: "export ANTHROPIC_API_KEY=sk-ant-… so spawned claude sessions bill against the API account and avoid 429 session caps.",
-    };
-}
-async function checkGh() {
-    const ghOk = await checkBinary("gh", ["--version"]);
-    if (!ghOk.ok) {
-        return {
-            name: "gh CLI in PATH",
-            ok: false,
-            detail: ghOk.detail,
-            fix: "Install GitHub CLI (https://cli.github.com).",
-        };
-    }
-    try {
-        await execa("gh", ["auth", "status"], { env: buildEnv() });
-        return { name: "gh CLI in PATH", ok: true, detail: ghOk.detail };
-    }
-    catch {
-        return {
-            name: "gh CLI in PATH",
-            ok: false,
-            detail: "gh installed but not authenticated",
-            fix: "Run `gh auth login`.",
-        };
-    }
-}
-async function checkGit() {
-    const r = await checkBinary("git", ["--version"]);
-    if (!r.ok) {
-        return {
-            name: "git installed",
-            ok: false,
-            detail: r.detail,
-            fix: "Install git (https://git-scm.com).",
-        };
-    }
-    // Soft-check that user.email is set; agents can't push commits without it.
-    try {
-        const { stdout } = await execa("git", ["config", "user.email"], { env: buildEnv() });
-        if (!stdout.trim())
-            throw new Error("user.email empty");
-        return { name: "git installed and configured", ok: true, detail: r.detail };
-    }
-    catch {
-        return {
-            name: "git installed and configured",
-            ok: false,
-            detail: "git.user.email is not set",
-            fix: "Run `git config --global user.email <you@example.com>`.",
-        };
-    }
-}
-async function checkKeychain() {
-    // v0.12.0 (T-52-7): env-token runners (containers) have no OS keychain;
-    // the check is inapplicable rather than broken.
-    if (resolveTokenMode() === "env") {
-        return {
-            name: "keychain read/write",
-            ok: true,
-            detail: "skipped (token mode: env)",
-        };
-    }
-    try {
-        const keytar = (await import("keytar"));
-        const k = keytar.default ?? keytar;
-        await k.setPassword("acc-runner-doctor", "sentinel", "ok");
-        const v = await k.getPassword("acc-runner-doctor", "sentinel");
-        await k.deletePassword("acc-runner-doctor", "sentinel");
-        return {
-            name: "keychain read/write",
-            ok: v === "ok",
-            detail: v === "ok" ? "ok" : `unexpected: ${String(v)}`,
-        };
-    }
-    catch (err) {
-        return {
-            name: "keychain read/write",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: "On Linux: install libsecret. On macOS/Windows: ensure the keychain service is unlocked.",
-        };
-    }
-}
-async function checkServer(publicUrl) {
-    try {
-        const res = await fetch(`${publicUrl.replace(/\/+$/, "")}/api/health`, {
-            headers: { "User-Agent": `acc-runner/${PROTOCOL_VERSION}` },
-        });
-        if (!res.ok) {
-            return {
-                name: "/api/health reachable",
-                ok: false,
-                detail: `HTTP ${res.status}`,
-                fix: "Check ACC_PUBLIC_URL points to a deployment that is up.",
-            };
-        }
-        return { name: "/api/health reachable", ok: true, detail: "200 OK" };
-    }
-    catch (err) {
-        return {
-            name: "/api/health reachable",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: "Check ACC_PUBLIC_URL and your network connection.",
-        };
-    }
-}
-async function checkProtocolVersion(publicUrl) {
-    const r = await checkVersion(publicUrl);
-    if (r.ok) {
-        return {
-            name: "protocol version",
-            ok: true,
-            detail: `server min v${r.serverMin}, you have v${PROTOCOL_VERSION}`,
-        };
-    }
-    if (r.reason === "outdated") {
-        return {
-            name: "protocol version",
-            ok: false,
-            detail: `server min v${r.serverMin}, you have v${PROTOCOL_VERSION}`,
-            fix: "Run `pnpm add -g @tokenfactory/acc-runner@latest`.",
-        };
-    }
-    return {
-        name: "protocol version",
-        ok: false,
-        detail: r.detail ?? "unreachable",
-        fix: "Check ACC_PUBLIC_URL and connectivity.",
-    };
-}
-async function dirEntryCount(dir) {
-    try {
-        const entries = await fs.readdir(dir);
-        return entries.length;
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return null;
-        throw err;
-    }
-}
-async function checkWorktreeDir() {
-    const count = await dirEntryCount(workDir());
-    if (count === null) {
-        return {
-            name: "worktree cache present",
-            ok: true,
-            detail: `not yet created (${workDir()})`,
-        };
-    }
-    return {
-        name: "worktree cache present",
-        ok: true,
-        detail: `${count} entr${count === 1 ? "y" : "ies"} under ${workDir()}`,
-    };
-}
-async function checkOrphanWorktrees(cfg) {
-    if (!cfg) {
-        return {
-            name: "no orphan worktrees",
-            ok: false,
-            detail: "config unavailable",
-            fix: "Re-run `acc-runner doctor` once config loads.",
-        };
-    }
-    try {
-        const orphans = await listOrphanWorktrees(cfg.repoPath);
-        if (orphans.length === 0) {
-            return { name: "no orphan worktrees", ok: true, detail: "clean" };
-        }
-        const first = orphans.slice(0, 3).map((o) => o.taskId).join(", ");
-        const more = orphans.length > 3 ? ` (+${orphans.length - 3} more)` : "";
-        return {
-            name: "no orphan worktrees",
-            ok: false,
-            detail: `${orphans.length} stale dir(s): ${first}${more}`,
-            fix: `Run \`git -C ${cfg.repoPath} worktree prune\` and \`rm -rf ${workDir()}/<task_id>\` for the listed ids.`,
-        };
-    }
-    catch (err) {
-        return {
-            name: "no orphan worktrees",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: "Check that ACC_REPO_PATH is a valid git repo.",
-        };
-    }
-}
-async function checkQuarantine() {
-    try {
-        const q = await getQuarantine();
-        if (!q) {
-            return { name: "runner quarantine", ok: true, detail: "not quarantined" };
-        }
-        // v0.53 T-53-4: surface the consecutive instant-empty count when present
-        // so an operator can see whether this was a confirmed env_broken (2) or
-        // a definitive failure (1).
-        const consec = q.consecutive !== undefined ? `, consecutive: ${q.consecutive}` : "";
-        return {
-            name: "runner quarantine",
-            ok: false,
-            detail: `QUARANTINED (${q.cause}): ${q.detail} — task: ${q.taskId}, at: ${q.classifiedAt}${consec}`,
-            fix: `Resolve the underlying ${q.cause} issue then delete ${quarantineFile()} or run \`acc-runner quarantine clear\`.`,
-        };
-    }
-    catch (err) {
-        return {
-            name: "runner quarantine",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: `Check permissions on ${quarantineFile()}.`,
-        };
-    }
-}
-async function checkStaleLocks() {
-    try {
-        const stale = await listStaleLocks();
-        if (stale.length === 0) {
-            return { name: "no stale task locks", ok: true, detail: "clean" };
-        }
-        const first = stale.slice(0, 3).map((l) => l.taskId).join(", ");
-        const more = stale.length > 3 ? ` (+${stale.length - 3} more)` : "";
-        return {
-            name: "no stale task locks",
-            ok: false,
-            detail: `${stale.length} stale lock(s): ${first}${more}`,
-            fix: `Delete dead pid files under ${locksDir()}/ — the runner ignores live-pid entries.`,
-        };
-    }
-    catch (err) {
-        return {
-            name: "no stale task locks",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: `Check permissions on ${locksDir()}.`,
-        };
-    }
-}
-export async function checkSingleton(cfg, deps = {}) {
-    if (!cfg) {
-        return {
-            name: "no duplicate runner",
-            ok: true,
-            detail: "config unavailable (skipped)",
-        };
-    }
-    const scan = deps.scan ?? listForeignRunnerPids;
-    try {
-        const holder = await findLiveLockHolder(cfg.repoPath, process.pid);
-        if (holder) {
-            return {
-                name: "no duplicate runner",
-                ok: false,
-                detail: `pid ${holder.pid} already serves ${holder.repoPath} (since ${holder.acquiredAt})`,
-                fix: `Stop it: kill ${holder.pid}  — or remove ${singletonLockPath(cfg.repoPath)} if that pid is dead.`,
-            };
-        }
-        // No lock holder for our repo path. Scan for any other acc-runner watch
-        // process that predates the singleton lock (no lock file written).
-        const foreign = await scan(process.pid);
-        if (foreign.length > 0) {
-            return {
-                name: "no duplicate runner",
-                ok: false,
-                warn: true,
-                detail: `another acc-runner watch process is running (pid ${foreign.join(", ")}); cannot confirm its repo path`,
-                fix: "Confirm it is not serving this repo path; if it is, stop it before running watch here.",
-            };
-        }
-        return { name: "no duplicate runner", ok: true, detail: "no other runner on this repo path" };
-    }
-    catch (err) {
-        return {
-            name: "no duplicate runner",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: `Check permissions on ${singletonLockPath(cfg.repoPath)}.`,
-        };
-    }
-}
-// v0.14.0 (T-54-2, GA-6) ------------------------------------------------
-// Version-drift WARNs. Both are advisory (never fail the run): a stale
-// binary or a swapped-out claude CLI is worth surfacing but is not a hard
-// environment break. The npm lookup is cached + offline-safe (skips
-// silently when the registry is unreachable and no cache exists).
-export async function checkUpdateAvailable(deps = {}) {
-    let latest;
-    try {
-        latest = await npmLatestVersion(deps);
-    }
-    catch {
-        latest = null;
-    }
-    if (!latest) {
-        return {
-            name: "acc-runner up to date",
-            ok: true,
-            detail: "skipped (registry unreachable)",
-        };
-    }
-    if (compareSemverVer(PACKAGE_VERSION, latest) < 0) {
-        return {
-            name: "acc-runner up to date",
-            ok: false,
-            warn: true,
-            detail: `running v${PACKAGE_VERSION}, npm latest is v${latest}`,
-            fix: "Run `npm install -g @tokenfactory/acc-runner@latest` then reload launchd.",
-        };
-    }
-    return {
-        name: "acc-runner up to date",
-        ok: true,
-        detail: `v${PACKAGE_VERSION} (npm latest v${latest})`,
-    };
-}
-export async function checkClaudeDrift(deps = {}) {
-    const record = await readTaskEnv();
-    if (!record || !record.claudeVersion) {
-        return {
-            name: "claude CLI stable",
-            ok: true,
-            detail: "no successful task recorded yet (skipped)",
-        };
-    }
-    const current = await (deps.currentVersion ?? getClaudeVersion)();
-    if (!current) {
-        // claude missing/erroring is already covered by checkClaude — don't
-        // double-report it here.
-        return { name: "claude CLI stable", ok: true, detail: "current version unavailable (skipped)" };
-    }
-    if (current !== record.claudeVersion) {
-        return {
-            name: "claude CLI stable",
-            ok: false,
-            warn: true,
-            detail: `claude changed since last green task: was "${record.claudeVersion}", now "${current}"`,
-            fix: "Verify the new claude works (`acc-runner doctor` after a task), or pin the prior version if the update regressed.",
-        };
-    }
-    return {
-        name: "claude CLI stable",
-        ok: true,
-        detail: `unchanged since last green task (${current})`,
-    };
-}
-async function checkRegistration() {
-    const cfg = loadConfigOrNull();
-    if (!cfg) {
-        // With defaults baked in this branch is unreachable, but keep a
-        // defensive guard so a future config refactor that re-enables
-        // throws still produces a meaningful error.
-        return {
-            name: "runner registered",
-            ok: false,
-            detail: "config could not be loaded",
-            fix: "Run `acc-runner doctor` and report the failing config line.",
-        };
-    }
-    // v0.12.0 (T-52-7): session may come from the keychain (desktop) or
-    // env vars (ephemeral container) depending on ACC_RUNNER_TOKEN_MODE.
-    const provider = getTokenProvider();
-    let session;
-    try {
-        session = await provider.load();
-    }
-    catch (err) {
-        return {
-            name: "runner registered",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: "Set ACC_RUNNER_ACCESS_TOKEN (token mode: env).",
-        };
-    }
-    if (!session) {
-        return {
-            name: "runner registered",
-            ok: false,
-            detail: provider.mode === "env" ? "no session in env" : "no session in keychain",
-            fix: provider.mode === "env"
-                ? "Set ACC_RUNNER_ACCESS_TOKEN."
-                : "Run `acc-runner login`.",
-        };
-    }
-    try {
-        const supabase = createRunnerClient(cfg, session.access_token);
-        const { data, error } = await supabase
-            .from("runners")
-            .select("id,bound_user_id,status")
-            .eq("id", session.runner_id)
-            .maybeSingle();
-        if (error) {
-            return {
-                name: "runner registered",
-                ok: false,
-                detail: error.message,
-                fix: "Re-run `acc-runner login`.",
-            };
-        }
-        if (!data) {
-            return {
-                name: "runner registered",
-                ok: false,
-                detail: `runner row ${session.runner_id} not found`,
-                fix: "Re-run `acc-runner login`.",
-            };
-        }
-        if (data.bound_user_id !== session.user_id) {
-            return {
-                name: "runner registered",
-                ok: false,
-                detail: "runner bound to a different user",
-                fix: "Run `acc-runner logout` then `acc-runner login` again.",
-            };
-        }
-        return { name: "runner registered", ok: true, detail: `${session.runner_id} (status=${data.status})` };
-    }
-    catch (err) {
-        return {
-            name: "runner registered",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: "Re-run `acc-runner login`.",
-        };
-    }
-}
-// v0.12-RUNNER-HEALTH ----------------------------------------------------
-// macOS LaunchAgent + caffeinate are how the operator side stays up:
-// launchd auto-restarts the watch process on crash, caffeinate keeps
-// the Mac from sleeping mid-task. Both are no-ops outside Darwin so
-// the checks report as "skipped" and stay green.
-async function checkCaffeinate() {
-    if (process.platform !== "darwin") {
-        return { name: "caffeinate available", ok: true, detail: "skipped (non-darwin)" };
-    }
-    const r = await checkBinary("caffeinate", ["-h"]);
-    // caffeinate -h exits non-zero (prints usage to stderr) but the
-    // binary is present. Treat ENOENT as the only failure mode.
-    const present = r.ok || !/not found|ENOENT/i.test(r.detail);
-    if (present) {
-        return { name: "caffeinate available", ok: true, detail: "/usr/bin/caffeinate" };
-    }
-    return {
-        name: "caffeinate available",
-        ok: false,
-        detail: r.detail,
-        fix: "caffeinate ships with macOS at /usr/bin/caffeinate; ensure $PATH includes /usr/bin.",
-    };
-}
-async function checkLaunchd() {
-    if (process.platform !== "darwin") {
-        return { name: "launchd agent loaded", ok: true, detail: "skipped (non-darwin)" };
-    }
-    const plist = launchdPlistPath();
-    try {
-        await fs.access(plist);
-    }
-    catch {
-        return {
-            name: "launchd agent loaded",
-            ok: false,
-            detail: `plist missing at ${plist}`,
-            fix: "Run packages/acc-runner/scripts/install-launchd.sh from the repo clone.",
-        };
-    }
-    try {
-        const { stdout } = await execa("launchctl", ["list"], { env: process.env });
-        const loaded = stdout
-            .split(/\r?\n/)
-            .some((line) => line.trim().split(/\s+/).pop() === LAUNCHD_LABEL);
-        if (!loaded) {
-            return {
-                name: "launchd agent loaded",
-                ok: false,
-                detail: `${LAUNCHD_LABEL} not in launchctl list`,
-                fix: `launchctl load ${plist}`,
-            };
-        }
-        return { name: "launchd agent loaded", ok: true, detail: LAUNCHD_LABEL };
-    }
-    catch (err) {
-        return {
-            name: "launchd agent loaded",
-            ok: false,
-            detail: err.message.split("\n")[0],
-            fix: "Ensure launchctl is on PATH (default on macOS).",
-        };
-    }
-}
-function format(outcome) {
-    const tag = outcome.ok
-        ? chalk.green("[OK ]")
-        : outcome.warn
-            ? chalk.yellow("[WARN]")
-            : chalk.red("[FAIL]");
-    const fix = !outcome.ok && outcome.fix ? chalk.gray(`\n        → ${outcome.fix}`) : "";
-    return `${tag} ${outcome.name.padEnd(28, " ")} ${chalk.gray(outcome.detail)}${fix}`;
-}
-export async function doctorCommand(options = {}) {
-    const cfg = loadConfigOrNull();
-    const checks = options.checks ?? [
-        checkNode,
-        checkClaude,
-        checkAnthropicKey,
-        checkGh,
-        checkGit,
-        checkKeychain,
-        ...(cfg ? [() => checkServer(cfg.publicUrl)] : []),
-        ...(cfg ? [() => checkProtocolVersion(cfg.publicUrl)] : []),
-        checkRegistration,
-        checkQuarantine,
-        checkWorktreeDir,
-        () => checkOrphanWorktrees(cfg),
-        checkStaleLocks,
-        () => checkSingleton(cfg),
-        checkUpdateAvailable,
-        checkClaudeDrift,
-        checkCaffeinate,
-        checkLaunchd,
-    ];
-    if (cfg && !options.checks) {
-        console.log(formatConfig(cfg));
-        console.log("");
-    }
-    let failed = 0;
-    for (const fn of checks) {
-        const outcome = await fn();
-        // v0.14.0 (T-54-2): WARN outcomes are advisory and never fail the run.
-        if (!outcome.ok && !outcome.warn)
-            failed++;
-        console.log(format(outcome));
-    }
-    return failed === 0 ? 0 : 1;
-}
-//# sourceMappingURL=doctor.js.map