@yagni-app/code-staging 0.0.0 → 0.1.0-staging.997.1

package/dist/cli.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * yagni — the thin launcher (package `yagni-code`, command `yagni`).
+ *
+ *   yagni login        device-code auth, stores a scoped token
+ *   yagni logout       revoke + delete the local token
+ *   yagni doctor       green/red readiness checklist
+ *   yagni [pi args…]   launch pi configured with the yagni provider +
+ *                      the ask_yagni tool (default command)
+ *
+ * The launcher holds NO model or business logic — it is credential plumbing
+ * plus a configured pi spawn. Everything that makes this "YAGNI Code" lives in
+ * pi-extension-yagni and the YAGNI backend.
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, realpathSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { PI_CONFIG_NAME } from "./branding.js";
+import { claudeCompatArgs } from "./claudeCompat.js";
+import { agentDir, credentialsDir, piPackageDir } from "./credentials.js";
+import { DISTRIBUTION } from "./distribution.js";
+import { login } from "./login.js";
+import { logout } from "./logout.js";
+import { buildLaunch } from "./launch.js";
+import { runDoctor } from "./doctor.js";
+import { currentCliVersion, maybeNudgeAndRefresh, upgradeCommand } from "./upgrade.js";
+import { maybeRefreshAtLaunch } from "./refresh.js";
+import { ensureShadowPiPackage } from "./piPackage.js";
+import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
+import { credentialsFromProfile, getActiveProfileName, listProfiles, migrateLegacyCredentials, persistProfileTokenRotation, profilePath, readActiveProfile, useProfile, } from "./profiles.js";
+// Present as "yagni" in process listings, not "node".
+process.title = DISTRIBUTION.commandName;
+/** The one-time Claude-compat trust question, asked on the launch TTY. */
+async function confirmOnTty(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`${question} [Y/n] `);
+        return !/^n/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runDefault(passthroughArgs) {
+    // Cache-backed update nudge (never a network wait), then a background cache
+    // refresh that completes while the session runs. Both fail soft.
+    await maybeNudgeAndRefresh({ current: cliVersion() });
+    // Load the active environment's credentials (base URL respects a per-run
+    // YAGNI_BASE_URL override). The token must belong to this environment.
+    const profile = await readActiveProfile();
+    let creds = credentialsFromProfile(profile);
+    if (!creds?.token) {
+        process.stderr.write(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`yagni login\` first.\n`);
+        return 1;
+    }
+    // Refresh-at-launch: if the token is inside the 7-day refresh window (and not
+    // yet expired), rotate it before spawning so a long session doesn't 401
+    // mid-flight. Fail-soft: a refresh failure keeps the current token and warns.
+    // Persist ONLY the token rotation — never the (possibly YAGNI_BASE_URL-
+    // overridden) base URL, so a single-run override can't become sticky.
+    const refresh = await maybeRefreshAtLaunch(creds, {
+        persist: (c) => persistProfileTokenRotation(profile.name, c),
+    });
+    for (const warning of refresh.warnings) {
+        process.stderr.write(`${warning}\n`);
+    }
+    creds = refresh.creds;
+    // Hermetic config dir, scoped per environment — created up front (0700) so pi
+    // reads/writes its settings, auth, model scope, and theme here (per profile)
+    // instead of ~/.pi/agent, and prod state never bleeds into staging.
+    const piAgentDir = agentDir(profile.name);
+    mkdirSync(piAgentDir, { recursive: true, mode: 0o700 });
+    // Generate the shadow pi package so the terminal title/process name read
+    // "YAGNI Code" instead of "pi"/"π". Best-effort: if it can't be built we
+    // still launch (un-rebranded but hermetic), never blocking the agent.
+    let shadowPiDir;
+    try {
+        shadowPiDir = ensureShadowPiPackage({
+            realPiDir: resolvePiPackageDir(),
+            shadowDir: piPackageDir(),
+            name: PI_CONFIG_NAME,
+        });
+    }
+    catch {
+        shadowPiDir = undefined;
+    }
+    // Zero-config Claude Code compat: wire this repo's (and the user's)
+    // .claude/skills and .claude/commands into the agent, asking the one-time
+    // per-folder trust question when needed. Fail-soft: compat can only add
+    // flags, never block a launch.
+    let compatArgs = [];
+    try {
+        compatArgs = await claudeCompatArgs({
+            cwd: process.cwd(),
+            agentDir: piAgentDir,
+            confirm: confirmOnTty,
+        });
+    }
+    catch {
+        compatArgs = [];
+    }
+    // buildLaunch runs the token-expiry preflight: it throws (with an actionable
+    // login prompt) on an already-expired token so we never spawn a session that
+    // immediately 401s, and returns non-fatal warnings (e.g. expiry approaching).
+    // `creds` was read fresh from the profile file above, so an out-of-band
+    // re-login in another terminal is picked up here with no stale cached token.
+    let plan;
+    try {
+        plan = buildLaunch(creds, passthroughArgs, {
+            extensionPath: resolveExtensionPath(),
+            agentDir: piAgentDir,
+            piPackageDir: shadowPiDir,
+            extraAgentArgs: compatArgs,
+            // Forward the active profile's file path so the extension can persist a
+            // mid-session token rotation back to the same profile the launcher read.
+            profilePath: profilePath(profile.name),
+            stateDir: credentialsDir(),
+            baseEnv: process.env,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    for (const warning of plan.warnings) {
+        process.stderr.write(`${warning}\n`);
+    }
+    const { env, argv } = plan;
+    const piCli = resolvePiCliPath();
+    return await new Promise((resolve) => {
+        const child = spawn(process.execPath, [piCli, ...argv], {
+            stdio: "inherit",
+            env,
+        });
+        child.on("exit", (code) => resolve(code ?? 0));
+        child.on("error", (err) => {
+            process.stderr.write(`Failed to start YAGNI Code: ${err.message}\n`);
+            resolve(1);
+        });
+    });
+}
+export const HELP_TEXT = [
+    "YAGNI Code — a business-context-grounded terminal coding agent.",
+    "",
+    "Usage:",
+    "  yagni [args…]            Launch the agent in the current repo.",
+    "  yagni -c                 Continue the most recent session.",
+    "  yagni -r                 Browse and resume a previous session.",
+    '  yagni -p "prompt"        Print one response and exit (reads piped stdin too).',
+    "  yagni login              Authorize the active environment (device-code flow).",
+    "  yagni logout             Revoke and clear the active environment's token.",
+    "  yagni doctor             Check that everything is ready (green/red checklist).",
+    "  yagni use <name>         Switch the active environment (sticky).",
+    "                           Presets: prod, local. Others need --base-url <url>.",
+    "  yagni profiles           List saved environments; the active one is marked.",
+    "  yagni upgrade [x.y.z]    Upgrade the CLI to the latest (or a given) version.",
+    "  yagni version            Print the CLI version.",
+    "",
+    "Common agent flags (passed straight through):",
+    "  --model <tier>           Pick the model tier (balanced by default).",
+    "  --thinking <level>       off | minimal | low | medium | high | xhigh | max",
+    "  --session <id>           Open a specific session; --fork <id> branches one.",
+    "  --mode json              Emit machine-readable events (for scripts and CI).",
+    "",
+    "In a session:",
+    "  /name                    Runs this repo's .claude/commands/<name>.md template.",
+    "  /mode plan|review|auto   Hold writes for planning, or confirm each change.",
+    "  /todos                   Show the agent's live task list.",
+    "  /cost                    Session usage and credit headroom.",
+    "",
+    "The active environment is sticky; `use` switches it (prod is the default).",
+    "Set YAGNI_BASE_URL to override the base URL for a single run.",
+    "Set YAGNI_DISABLE_UPDATE_CHECK=1 to silence the new-version notice.",
+    "Set YAGNI_DISABLE_CLAUDE_COMPAT=1 to skip loading .claude assets.",
+].join("\n");
+/** Parse `use <name> [--base-url <url>]` argv into its parts. */
+export function parseUseArgs(args) {
+    let name;
+    let baseUrl;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--base-url") {
+            baseUrl = args[++i];
+            continue;
+        }
+        if (a.startsWith("--base-url=")) {
+            baseUrl = a.slice("--base-url=".length);
+            continue;
+        }
+        if (!a.startsWith("-") && name === undefined)
+            name = a;
+    }
+    return { name, baseUrl };
+}
+/** `yagni use <name> [--base-url <url>]` — switch the sticky environment. */
+export async function useCommand(args) {
+    const { name, baseUrl } = parseUseArgs(args);
+    if (!name) {
+        process.stderr.write("Usage: yagni use <name> [--base-url <url>]\n");
+        return 1;
+    }
+    try {
+        const profile = await useProfile(name, { baseUrl });
+        const hint = profile.token ? "" : " — run `yagni login` to authorize it";
+        process.stdout.write(`Active environment: ${profile.name} → ${profile.baseUrl}${hint}\n`);
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+/** `yagni profiles` — list saved environments, marking the active one. */
+export async function profilesCommand() {
+    const active = await getActiveProfileName();
+    const stored = await listProfiles();
+    const rows = [...stored];
+    // Surface the active environment even if it has no saved file yet.
+    if (!rows.some((p) => p.name === active))
+        rows.push(await readActiveProfile());
+    rows.sort((a, b) => a.name.localeCompare(b.name));
+    for (const p of rows) {
+        const marker = p.name === active ? "*" : " ";
+        const status = p.token ? "logged in" : "not logged in";
+        process.stdout.write(`${marker} ${p.name.padEnd(12)} ${p.baseUrl}  (${status})\n`);
+    }
+    return 0;
+}
+/**
+ * Whether to show YAGNI Code's own help instead of launching the agent.
+ *
+ * `--help`/`-h` are intercepted ANYWHERE in argv (not just position 0) so the
+ * underlying agent's branded help never leaks (e.g. `yagni <flag> --help`).
+ */
+export function wantsHelp(argv) {
+    return argv[0] === "help" || argv.includes("--help") || argv.includes("-h");
+}
+/**
+ * Whether to print YAGNI Code's own version instead of launching the agent.
+ *
+ * `--version` AND `-v` are intercepted ANYWHERE in argv for the same reason as
+ * `--help`: pi parses both as its version flag, so letting either through
+ * leaks the agent's branded version line (or a login error before it).
+ */
+export function wantsVersion(argv) {
+    return argv[0] === "version" || argv.includes("--version") || argv.includes("-v");
+}
+/** The CLI's own version (see `currentCliVersion` — upgrade.ts owns it). */
+export function cliVersion() {
+    return currentCliVersion();
+}
+export async function main(argv) {
+    const [command, ...rest] = argv;
+    // Help never touches storage; everything else first adopts any pre-profiles
+    // credentials.json as a named profile (one-shot, no-op once migrated).
+    if (wantsHelp(argv)) {
+        process.stdout.write(`${HELP_TEXT}\n`);
+        return 0;
+    }
+    // Bare semver on stdout (script-friendly); like help, never touches storage.
+    if (wantsVersion(argv)) {
+        process.stdout.write(`${cliVersion()}\n`);
+        return 0;
+    }
+    await migrateLegacyCredentials();
+    // login/logout act on the active environment; use/profiles manage which one
+    // that is. Anything else is passed straight through to the agent.
+    if (command === "login") {
+        const profile = await readActiveProfile();
+        await login({ baseUrl: profile.baseUrl, profileName: profile.name });
+        return 0;
+    }
+    if (command === "logout") {
+        await logout();
+        return 0;
+    }
+    if (command === "doctor") {
+        return runDoctor();
+    }
+    if (command === "upgrade") {
+        return upgradeCommand(rest, { current: cliVersion() });
+    }
+    if (command === "use") {
+        return useCommand(rest);
+    }
+    if (command === "profiles") {
+        return profilesCommand();
+    }
+    return runDefault(command === undefined ? [] : [command, ...rest]);
+}
+/**
+ * Whether this module is the process entrypoint (vs. imported by a test).
+ *
+ * Symlink-safe: when `yagni-code` is installed globally, the shell runs it
+ * through a symlink in the bin dir, so `process.argv[1]` is that symlink path.
+ * Node resolves symlinks for `import.meta.url`, so a raw `argv[1] === metaPath`
+ * compare is ALWAYS false for a symlinked install and `main()` never runs (the
+ * "nothing happens" bug). We realpath both sides so the symlinked bin and a
+ * direct `node dist/cli.js` invocation both count as the entrypoint, while a
+ * test import (argv[1] points at the test runner) does not.
+ */
+export function isEntrypoint(argv1, moduleUrl) {
+    if (argv1 === undefined)
+        return false;
+    const resolve = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p; // path may not exist on disk; fall back to the raw value
+        }
+    };
+    return resolve(argv1) === resolve(fileURLToPath(moduleUrl));
+}
+// Only auto-run when invoked as the CLI entry, so tests can import this module
+// (e.g. to exercise wantsHelp) without spawning the agent.
+if (isEntrypoint(process.argv[1], import.meta.url)) {
+    main(process.argv.slice(2))
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+/** Shared CLI config: where the YAGNI backend lives + the environment presets. */
+export declare const DEFAULT_BASE_URL: string;
+/**
+ * Built-in environment presets. These only SEED a profile's base URL when you
+ * `yagni use <name>` without `--base-url`; once stored, the profile's own
+ * baseUrl wins. `prod` is the default profile; `local` points at the dev backend
+ * (`pnpm dev` serves /api + /v1 on 3456). Any other environment is user-defined
+ * (pass `--base-url`).
+ */
+export declare const PRESET_BASE_URLS: Record<string, string>;
+/** The base URL a named preset resolves to, or undefined for a custom name. */
+export declare function presetBaseUrl(name: string): string | undefined;
+/**
+ * The YAGNI_BASE_URL env override (back-compat / per-run escape hatch). Profiles
+ * are the primary mechanism now; this still wins when set so a one-off run can
+ * target an ad-hoc host without flipping the active profile.
+ */
+export declare function resolveBaseUrl(env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,28 @@
+/** Shared CLI config: where the YAGNI backend lives + the environment presets. */
+import { DISTRIBUTION } from "./distribution.js";
+export const DEFAULT_BASE_URL = DISTRIBUTION.defaultBaseUrl;
+/**
+ * Built-in environment presets. These only SEED a profile's base URL when you
+ * `yagni use <name>` without `--base-url`; once stored, the profile's own
+ * baseUrl wins. `prod` is the default profile; `local` points at the dev backend
+ * (`pnpm dev` serves /api + /v1 on 3456). Any other environment is user-defined
+ * (pass `--base-url`).
+ */
+export const PRESET_BASE_URLS = {
+    prod: "https://yagni.app",
+    staging: "https://yagni-staging.app",
+    local: "http://localhost:3456",
+};
+/** The base URL a named preset resolves to, or undefined for a custom name. */
+export function presetBaseUrl(name) {
+    return PRESET_BASE_URLS[name];
+}
+/**
+ * The YAGNI_BASE_URL env override (back-compat / per-run escape hatch). Profiles
+ * are the primary mechanism now; this still wins when set so a one-off run can
+ * target an ad-hoc host without flipping the active profile.
+ */
+export function resolveBaseUrl(env = process.env) {
+    return (env.YAGNI_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+//# sourceMappingURL=config.js.map

package/dist/credentials.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Credential storage for the yagni-code CLI: `~/.yagni-code/credentials.json`,
+ * written 0600 (owner read/write only) since it holds a live API token.
+ */
+export interface Credentials {
+    token: string;
+    baseUrl: string;
+    workspaceId: string;
+    expiresAt?: string;
+}
+export declare function _setYagniCodeHomeForTest(dir: string | null): void;
+export declare function credentialsDir(): string;
+export declare function credentialsPath(): string;
+/**
+ * Isolated pi config/state dir for YAGNI Code: `~/.yagni-code/agent/<profile>`.
+ *
+ * The launcher pins pi's `PI_CODING_AGENT_DIR` here so YAGNI Code never reads
+ * the user's machine-wide `~/.pi/agent` — keeping its own providers (only
+ * `yagni`), stored auth, model scope (the backend catalog), and theme out of
+ * the agent. Everything routes through the YAGNI proxy; the user's local
+ * Together/OpenRouter keys and saved default model cannot bleed in or bypass it.
+ *
+ * Scoping the dir per profile keeps each environment's pi state (session
+ * history, theme, settings) separate, so pointing at staging never bleeds prod
+ * state. Called with no profile it returns the legacy un-scoped dir.
+ */
+export declare function agentDir(profileName?: string): string;
+/**
+ * Hermetic shadow pi package dir: `~/.yagni-code/pi-package`.
+ *
+ * Holds a generated `package.json` (pi's, with `piConfig.name` set so the
+ * terminal title/process name read "YAGNI Code" instead of "pi"/"π") plus
+ * symlinks back to the real pi package's assets. The launcher pins pi's
+ * `PI_PACKAGE_DIR` here. Kept under the YAGNI-owned dir so it never collides
+ * with the user's machine-wide pi install.
+ */
+export declare function piPackageDir(): string;
+export declare function writeCredentials(creds: Credentials, path?: string): Promise<void>;
+export declare function readCredentials(path?: string): Promise<Credentials | null>;
+export declare function deleteCredentials(path?: string): Promise<void>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.js

@@ -0,0 +1,75 @@
+/**
+ * Credential storage for the yagni-code CLI: `~/.yagni-code/credentials.json`,
+ * written 0600 (owner read/write only) since it holds a live API token.
+ */
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DISTRIBUTION } from "./distribution.js";
+/**
+ * Test seam: when set, all path resolution roots here instead of
+ * `~/.yagni-code`, so tests can exercise profile/credential storage against a
+ * tmpdir without touching the real home dir. Mirrors the `_setTestPool` style
+ * used elsewhere in the repo (no public env var). Pass `null` to restore.
+ */
+let homeOverride = null;
+export function _setYagniCodeHomeForTest(dir) {
+    homeOverride = dir;
+}
+export function credentialsDir() {
+    return homeOverride ?? join(homedir(), DISTRIBUTION.stateDirName);
+}
+export function credentialsPath() {
+    return join(credentialsDir(), "credentials.json");
+}
+/**
+ * Isolated pi config/state dir for YAGNI Code: `~/.yagni-code/agent/<profile>`.
+ *
+ * The launcher pins pi's `PI_CODING_AGENT_DIR` here so YAGNI Code never reads
+ * the user's machine-wide `~/.pi/agent` — keeping its own providers (only
+ * `yagni`), stored auth, model scope (the backend catalog), and theme out of
+ * the agent. Everything routes through the YAGNI proxy; the user's local
+ * Together/OpenRouter keys and saved default model cannot bleed in or bypass it.
+ *
+ * Scoping the dir per profile keeps each environment's pi state (session
+ * history, theme, settings) separate, so pointing at staging never bleeds prod
+ * state. Called with no profile it returns the legacy un-scoped dir.
+ */
+export function agentDir(profileName) {
+    const base = join(credentialsDir(), "agent");
+    return profileName ? join(base, profileName) : base;
+}
+/**
+ * Hermetic shadow pi package dir: `~/.yagni-code/pi-package`.
+ *
+ * Holds a generated `package.json` (pi's, with `piConfig.name` set so the
+ * terminal title/process name read "YAGNI Code" instead of "pi"/"π") plus
+ * symlinks back to the real pi package's assets. The launcher pins pi's
+ * `PI_PACKAGE_DIR` here. Kept under the YAGNI-owned dir so it never collides
+ * with the user's machine-wide pi install.
+ */
+export function piPackageDir() {
+    return join(credentialsDir(), "pi-package");
+}
+export async function writeCredentials(creds, path = credentialsPath()) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+    // writeFile honors mode only on create; chmod guarantees 0600 on overwrite too.
+    await chmod(path, 0o600);
+}
+export async function readCredentials(path = credentialsPath()) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed.token !== "string")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export async function deleteCredentials(path = credentialsPath()) {
+    await rm(path, { force: true });
+}
+//# sourceMappingURL=credentials.js.map

package/dist/distribution.d.ts

@@ -0,0 +1,15 @@
+export type DistributionChannel = "production" | "staging";
+export interface CodeDistribution {
+    channel: DistributionChannel;
+    packageName: string;
+    commandName: string;
+    displayName: string;
+    defaultBaseUrl: string;
+    defaultProfile: string;
+    stateDirName: string;
+    updateTag: "latest" | "staging";
+}
+export declare function distributionForPackageName(packageName: string): CodeDistribution;
+export declare function resolveDistribution(env?: NodeJS.ProcessEnv, packageName?: string): CodeDistribution;
+export declare const DISTRIBUTION: CodeDistribution;
+//# sourceMappingURL=distribution.d.ts.map

package/dist/distribution.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const PRODUCTION = {
+    channel: "production",
+    packageName: "@yagni-app/code",
+    commandName: "yagni",
+    displayName: "YAGNI Code",
+    defaultBaseUrl: "https://yagni.app",
+    defaultProfile: "prod",
+    stateDirName: ".yagni-code",
+    updateTag: "latest",
+};
+const STAGING = {
+    channel: "staging",
+    packageName: "@yagni-app/code-staging",
+    commandName: "yagni-staging",
+    displayName: "YAGNI Code Staging",
+    defaultBaseUrl: "https://yagni-staging.app",
+    defaultProfile: "staging",
+    stateDirName: ".yagni-code-staging",
+    updateTag: "staging",
+};
+export function distributionForPackageName(packageName) {
+    return packageName === STAGING.packageName ? { ...STAGING } : { ...PRODUCTION };
+}
+function installedPackageName() {
+    try {
+        const path = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed.name ?? PRODUCTION.packageName;
+    }
+    catch {
+        return PRODUCTION.packageName;
+    }
+}
+export function resolveDistribution(env = process.env, packageName = installedPackageName()) {
+    if (env.YAGNI_CODE_DISTRIBUTION === "staging")
+        return { ...STAGING };
+    if (env.YAGNI_CODE_DISTRIBUTION === "production")
+        return { ...PRODUCTION };
+    return distributionForPackageName(packageName);
+}
+export const DISTRIBUTION = resolveDistribution();
+//# sourceMappingURL=distribution.js.map

package/dist/doctor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `yagni doctor` — a green/red readiness checklist.
+ *
+ * Diagnoses whether a `yagni` launch will actually work: the pi engine is built,
+ * the extension is built, the active profile has a live (unexpired) token, the
+ * backend is reachable with YAGNI Code enabled, the state dir is locked down, and
+ * `gh` is available for `/go --pr`. Every failing/soft check carries a one-line
+ * actionable fix.
+ *
+ * The check LOGIC is pure (given probe inputs) so it is fully unit-testable; the
+ * impure probes (fs, fetch, profile read) are injectable seams. `runDoctor`
+ * returns the process exit code: 0 when all REQUIRED checks pass, 1 otherwise.
+ * Advisory checks (loose perms, missing `gh`) never flip the exit code.
+ */
+import { type TokenExpiryStatus } from "./launch.js";
+import { type Profile } from "./profiles.js";
+export type CheckStatus = "ok" | "warn" | "fail";
+export interface CheckResult {
+    /** Short column label, e.g. "pi engine". */
+    name: string;
+    status: CheckStatus;
+    /** One-line current state. */
+    detail: string;
+    /** Actionable fix, shown when the check is not `ok`. */
+    hint?: string;
+    /** Only `required` failures flip the exit code to 1. */
+    required: boolean;
+}
+export interface PiEngineProbe {
+    binPath?: string;
+    binExists: boolean;
+    version?: string;
+}
+export interface ExtensionProbe {
+    path?: string;
+    exists: boolean;
+}
+export interface StateDirProbe {
+    path: string;
+    exists: boolean;
+    /** The dir's permission bits (mode & 0o777), or null when it doesn't exist. */
+    mode: number | null;
+}
+export type BackendProbe = {
+    kind: "skipped";
+} | {
+    kind: "status";
+    status: number;
+} | {
+    kind: "network";
+};
+export declare function checkPiEngine(probe: PiEngineProbe): CheckResult;
+export declare function checkExtension(probe: ExtensionProbe): CheckResult;
+export declare function checkProfileToken(profile: Pick<Profile, "name" | "token">): CheckResult;
+export declare function checkTokenExpiry(status: TokenExpiryStatus): CheckResult;
+export declare function checkBackend(probe: BackendProbe): CheckResult;
+export declare function checkStateDir(probe: StateDirProbe): CheckResult;
+export declare function checkCliUpdate(probe: {
+    current: string;
+    latest: string | null;
+}): CheckResult;
+export declare function checkGh(onPath: boolean): CheckResult;
+export interface DoctorReport {
+    checks: CheckResult[];
+    exitCode: number;
+}
+/** Exit 1 iff any REQUIRED check failed; advisory warns never flip it. */
+export declare function buildDoctorReport(checks: CheckResult[]): DoctorReport;
+export declare function formatDoctorReport(report: DoctorReport): string;
+export interface DoctorDeps {
+    now?: () => number;
+    probePiEngine?: () => PiEngineProbe;
+    probeExtension?: () => ExtensionProbe;
+    readActiveProfile?: () => Promise<Profile>;
+    probeBackend?: (baseUrl: string, token: string) => Promise<BackendProbe>;
+    probeStateDir?: () => StateDirProbe;
+    ghOnPath?: () => boolean;
+    currentVersion?: string;
+    probeLatestVersion?: () => Promise<string | null>;
+    log?: (msg: string) => void;
+}
+/** Whether a `gh` executable is resolvable on PATH (no subprocess spawn). */
+export declare function ghOnPathDefault(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Gather every check result against the (injectable) probes. Pure ordering; each
+ * individual check is a pure function of its probe.
+ */
+export declare function gatherChecks(deps?: DoctorDeps): Promise<CheckResult[]>;
+/**
+ * Run the full doctor flow: gather → assemble → print → return the exit code.
+ * Never throws (a probe failure degrades to a failing/soft check, not a crash).
+ */
+export declare function runDoctor(deps?: DoctorDeps): Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map