@yagni-app/code 0.1.0

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,74 @@
+/**
+ * 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";
+/**
+ * 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(), ".yagni-code");
+}
+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/doctor.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `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 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;
+    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

package/dist/doctor.js

@@ -0,0 +1,317 @@
+/**
+ * `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 { existsSync, readFileSync, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { credentialsDir } from "./credentials.js";
+import { classifyTokenExpiry } from "./launch.js";
+import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
+import { readActiveProfile } from "./profiles.js";
+// ── Pure check builders ─────────────────────────────────────────────────────
+export function checkPiEngine(probe) {
+    if (!probe.binPath || !probe.binExists) {
+        return {
+            name: "pi engine",
+            status: "fail",
+            detail: "not found or not built",
+            hint: "reinstall it: npm i -g @yagni-app/code (monorepo: npm i -g ./packages/yagni-code-cli)",
+            required: true,
+        };
+    }
+    return {
+        name: "pi engine",
+        status: "ok",
+        detail: probe.version ? `installed and built (v${probe.version})` : "installed and built",
+        required: true,
+    };
+}
+export function checkExtension(probe) {
+    if (!probe.path || !probe.exists) {
+        return {
+            name: "extension",
+            status: "fail",
+            detail: "pi-extension-yagni not built (dist/index.js missing)",
+            hint: "reinstall it: npm i -g @yagni-app/code (monorepo: pnpm --filter pi-extension-yagni build)",
+            required: true,
+        };
+    }
+    return { name: "extension", status: "ok", detail: "pi-extension-yagni built", required: true };
+}
+export function checkProfileToken(profile) {
+    if (!profile.token) {
+        return {
+            name: "profile",
+            status: "fail",
+            detail: `not logged in to "${profile.name}"`,
+            hint: "run `yagni login`",
+            required: true,
+        };
+    }
+    return {
+        name: "profile",
+        status: "ok",
+        detail: `logged in to "${profile.name}"`,
+        required: true,
+    };
+}
+export function checkTokenExpiry(status) {
+    switch (status.kind) {
+        case "expired":
+            return {
+                name: "token",
+                status: "fail",
+                detail: "expired",
+                hint: "run `yagni login` to re-authenticate",
+                required: true,
+            };
+        case "approaching":
+            return {
+                name: "token",
+                status: "warn",
+                detail: `expires in about ${status.minutesRemaining} minute${status.minutesRemaining === 1 ? "" : "s"}`,
+                hint: "run `yagni login` (launch also auto-refreshes within 7 days of expiry)",
+                required: false,
+            };
+        case "valid":
+            return { name: "token", status: "ok", detail: "valid", required: false };
+        case "unknown":
+        default:
+            return { name: "token", status: "ok", detail: "no expiry recorded (older login)", required: false };
+    }
+}
+export function checkBackend(probe) {
+    if (probe.kind === "skipped") {
+        return {
+            name: "backend",
+            status: "warn",
+            detail: "skipped (not logged in)",
+            hint: "run `yagni login`",
+            required: false,
+        };
+    }
+    if (probe.kind === "network") {
+        return {
+            name: "backend",
+            status: "warn",
+            detail: "could not reach the backend (network)",
+            hint: "check your connection, or `yagni use <env>` to point at the right host",
+            required: false,
+        };
+    }
+    const { status } = probe;
+    if (status === 200) {
+        return { name: "backend", status: "ok", detail: "reachable, YAGNI Code enabled", required: true };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            name: "backend",
+            status: "fail",
+            detail: `token rejected (HTTP ${status})`,
+            hint: "run `yagni login` to re-authenticate",
+            required: true,
+        };
+    }
+    if (status === 404) {
+        return {
+            name: "backend",
+            status: "fail",
+            detail: "YAGNI Code is not enabled for this workspace (HTTP 404)",
+            hint: "ask an admin to enable the yagni_code.enabled feature flag",
+            required: true,
+        };
+    }
+    return {
+        name: "backend",
+        status: "warn",
+        detail: `unexpected response (HTTP ${status})`,
+        hint: "retry in a moment; if it persists, contact support",
+        required: false,
+    };
+}
+export function checkStateDir(probe) {
+    if (!probe.exists || probe.mode === null) {
+        return {
+            name: "state dir",
+            status: "ok",
+            detail: `${probe.path} not created yet`,
+            required: false,
+        };
+    }
+    // Any group/other bit set on a dir that holds live tokens is a leak.
+    if ((probe.mode & 0o077) !== 0) {
+        return {
+            name: "state dir",
+            status: "warn",
+            detail: `${probe.path} is ${toOctal(probe.mode)} (should be 0700)`,
+            hint: `run: chmod 700 ${probe.path}`,
+            required: false,
+        };
+    }
+    return { name: "state dir", status: "ok", detail: `${probe.path} is 0700`, required: false };
+}
+export function checkGh(onPath) {
+    if (onPath) {
+        return {
+            name: "gh (optional)",
+            status: "ok",
+            detail: "on PATH (for `yagni /go --pr`)",
+            required: false,
+        };
+    }
+    return {
+        name: "gh (optional)",
+        status: "warn",
+        detail: "not found (only needed for `yagni /go --pr`)",
+        hint: "install the GitHub CLI: https://cli.github.com",
+        required: false,
+    };
+}
+function toOctal(mode) {
+    return `0${(mode & 0o777).toString(8).padStart(3, "0")}`;
+}
+/** Exit 1 iff any REQUIRED check failed; advisory warns never flip it. */
+export function buildDoctorReport(checks) {
+    const failedRequired = checks.some((c) => c.required && c.status === "fail");
+    return { checks, exitCode: failedRequired ? 1 : 0 };
+}
+const SYMBOL = { ok: "✓", warn: "!", fail: "✗" };
+export function formatDoctorReport(report) {
+    const lines = ["YAGNI Code doctor", ""];
+    const width = Math.max(...report.checks.map((c) => c.name.length), 0);
+    for (const c of report.checks) {
+        lines.push(`  ${SYMBOL[c.status]} ${c.name.padEnd(width)}  ${c.detail}`);
+        if (c.status !== "ok" && c.hint) {
+            lines.push(`  ${" ".repeat(width + 3)}→ ${c.hint}`);
+        }
+    }
+    lines.push("");
+    const problems = report.checks.filter((c) => c.required && c.status === "fail").length;
+    const advisories = report.checks.filter((c) => c.status === "warn").length;
+    if (problems > 0) {
+        lines.push(`${problems} problem${problems === 1 ? "" : "s"} found — see the hints above.`);
+    }
+    else if (advisories > 0) {
+        lines.push(`All required checks passed (${advisories} advisory note${advisories === 1 ? "" : "s"}).`);
+    }
+    else {
+        lines.push("All checks passed. You're ready to run `yagni`.");
+    }
+    return lines.join("\n");
+}
+function defaultProbePiEngine() {
+    try {
+        const binPath = resolvePiCliPath();
+        const binExists = existsSync(binPath);
+        let version;
+        try {
+            const pkg = JSON.parse(readFileSync(join(resolvePiPackageDir(), "package.json"), "utf8"));
+            version = typeof pkg.version === "string" ? pkg.version : undefined;
+        }
+        catch {
+            /* version is nice-to-have */
+        }
+        return { binPath, binExists, version };
+    }
+    catch {
+        return { binExists: false };
+    }
+}
+function defaultProbeExtension() {
+    try {
+        const path = resolveExtensionPath();
+        return { path, exists: existsSync(path) };
+    }
+    catch {
+        return { exists: false };
+    }
+}
+function defaultProbeStateDir() {
+    const path = credentialsDir();
+    try {
+        const st = statSync(path);
+        return { path, exists: true, mode: st.mode & 0o777 };
+    }
+    catch {
+        return { path, exists: false, mode: null };
+    }
+}
+async function defaultProbeBackend(baseUrl, token) {
+    if (!token)
+        return { kind: "skipped" };
+    try {
+        const res = await fetch(`${baseUrl}/api/yagni-code/models`, {
+            method: "GET",
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        return { kind: "status", status: res.status };
+    }
+    catch {
+        return { kind: "network" };
+    }
+}
+/** Whether a `gh` executable is resolvable on PATH (no subprocess spawn). */
+export function ghOnPathDefault(env = process.env) {
+    const raw = env.PATH ?? "";
+    const names = process.platform === "win32" ? ["gh.exe", "gh.cmd", "gh"] : ["gh"];
+    for (const dir of raw.split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            if (existsSync(join(dir, name)))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Gather every check result against the (injectable) probes. Pure ordering; each
+ * individual check is a pure function of its probe.
+ */
+export async function gatherChecks(deps = {}) {
+    const now = deps.now ?? Date.now;
+    const probePiEngine = deps.probePiEngine ?? defaultProbePiEngine;
+    const probeExtension = deps.probeExtension ?? defaultProbeExtension;
+    const readProfile = deps.readActiveProfile ?? readActiveProfile;
+    const probeBackend = deps.probeBackend ?? defaultProbeBackend;
+    const probeStateDir = deps.probeStateDir ?? defaultProbeStateDir;
+    const ghOnPath = deps.ghOnPath ?? (() => ghOnPathDefault());
+    const checks = [];
+    checks.push(checkPiEngine(probePiEngine()));
+    checks.push(checkExtension(probeExtension()));
+    const profile = await readProfile();
+    checks.push(checkProfileToken(profile));
+    if (profile.token) {
+        checks.push(checkTokenExpiry(classifyTokenExpiry(profile.expiresAt, now())));
+    }
+    const backend = profile.token
+        ? await probeBackend(profile.baseUrl, profile.token)
+        : { kind: "skipped" };
+    checks.push(checkBackend(backend));
+    checks.push(checkStateDir(probeStateDir()));
+    checks.push(checkGh(ghOnPath()));
+    return checks;
+}
+/**
+ * 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 async function runDoctor(deps = {}) {
+    const log = deps.log ?? ((m) => process.stdout.write(`${m}\n`));
+    const checks = await gatherChecks(deps);
+    const report = buildDoctorReport(checks);
+    log(formatDoctorReport(report));
+    return report.exitCode;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/launch.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Build the configured pi launch. `buildLaunch` is pure (no spawn, no fs) so it
+ * is fully unit-testable: it returns the child environment and the pi argv that
+ * registers pi-extension-yagni and defaults the provider to `yagni`.
+ */
+import type { Credentials } from "./credentials.js";
+export interface LaunchPlan {
+    env: NodeJS.ProcessEnv;
+    argv: string[];
+    /**
+     * Non-fatal launch-time notices for the caller to surface (e.g. an
+     * expiry-approaching warning). Empty when there is nothing to say.
+     */
+    warnings: string[];
+}
+/**
+ * How close to expiry the token can be before launch warns. A coding session
+ * easily outlives a token, so warn early enough that re-logging in before a long
+ * task is worthwhile, without nagging on every launch.
+ */
+export declare const EXPIRY_WARNING_THRESHOLD_MS: number;
+export type TokenExpiryStatus = {
+    kind: "unknown";
+} | {
+    kind: "valid";
+} | {
+    kind: "approaching";
+    minutesRemaining: number;
+} | {
+    kind: "expired";
+};
+/**
+ * Pure classifier for a token's ISO `expiresAt` against the current time. A
+ * missing or unparseable expiry is "unknown" (older profiles predate the field,
+ * so we proceed rather than block). Never throws.
+ */
+export declare function classifyTokenExpiry(expiresAt: string | undefined, nowMs: number, thresholdMs?: number): TokenExpiryStatus;
+export interface BuildLaunchOptions {
+    /** Absolute path to pi-extension-yagni's entry (resolved by the caller). */
+    extensionPath: string;
+    /**
+     * Isolated pi config dir. Pinning this keeps YAGNI Code hermetic: it never
+     * reads the user's machine-wide `~/.pi/agent`, so local providers
+     * (Together/OpenRouter), stored keys, a saved default model, and theme cannot
+     * bleed in or route around the YAGNI proxy.
+     */
+    agentDir: string;
+    /**
+     * Shadow pi package dir to expose as `PI_PACKAGE_DIR` so pi rebrands its
+     * chrome to "YAGNI Code". Optional: if the shadow package could not be
+     * generated, we omit it and pi runs un-rebranded but still hermetic.
+     */
+    piPackageDir?: string;
+    /**
+     * Absolute path of the active profile's JSON file. Forwarded to the child as
+     * `YAGNI_PROFILE_PATH` so the extension can persist a mid-session token
+     * rotation back to the same profile the launcher read. Optional: omitted when
+     * the caller cannot resolve it (the extension then keeps its rotation
+     * in-process only, still fail-soft).
+     */
+    profilePath?: string;
+    /** Base environment to extend (defaults to process.env at call sites). */
+    baseEnv?: NodeJS.ProcessEnv;
+    /** Clock seam for the token-expiry preflight (defaults to Date.now). */
+    now?: () => number;
+}
+export declare function buildLaunch(creds: Credentials | null, passthroughArgs: string[], opts: BuildLaunchOptions): LaunchPlan;
+//# sourceMappingURL=launch.d.ts.map