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

package/dist/doctor.js

@@ -0,0 +1,343 @@
+/**
+ * `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 { currentCliVersion, fetchLatestVersion, isNewerVersion } from "./upgrade.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: "YAGNI extension not found (dist/extension/index.js missing)",
+            hint: "reinstall it: npm i -g @yagni-app/code (monorepo: pnpm --filter @yagni-app/code build)",
+            required: true,
+        };
+    }
+    return { name: "extension", status: "ok", detail: "YAGNI extension loaded", 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 checkCliUpdate(probe) {
+    if (probe.latest === null) {
+        return {
+            name: "cli version",
+            status: "ok",
+            detail: `v${probe.current} (update check unavailable)`,
+            required: false,
+        };
+    }
+    if (isNewerVersion(probe.current, probe.latest)) {
+        return {
+            name: "cli version",
+            status: "warn",
+            detail: `v${probe.current} — v${probe.latest} is available`,
+            hint: "run `yagni upgrade`",
+            required: false,
+        };
+    }
+    return { name: "cli version", status: "ok", detail: `v${probe.current} (latest)`, 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 probeLatestVersion = deps.probeLatestVersion ?? (() => fetchLatestVersion());
+    const checks = [];
+    checks.push(checkPiEngine(probePiEngine()));
+    checks.push(checkExtension(probeExtension()));
+    checks.push(checkCliUpdate({
+        current: deps.currentVersion ?? currentCliVersion(),
+        latest: await probeLatestVersion(),
+    }));
+    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/extension/advisor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The PURE half of the ask_advisor escalation (YAG-380).
+ *
+ * Balanced sessions drive on `advanced` and escalate hard judgment calls to
+ * `peak`. This module owns every decision about whether a consult may happen and
+ * what it cost; `askAdvisorTool.ts` owns the spawn. Same split as `permission.ts`
+ * (`decideGate` pure, wiring separate), for the same reason: the rules are what
+ * need exhaustive tests, and they must not require a child process to exercise.
+ *
+ * Two bounds, both necessarily POST-HOC. pi exposes no pre-emptive turn or token
+ * ceiling (see `pipeline/budget.ts`), so a consult's cost is only knowable once
+ * the child has exited:
+ *
+ *   - `maxConsults` is the real product bound. It makes escalation predictable
+ *     and priceable, which is the point of the cap.
+ *   - `maxSpend` is a RUNAWAY CATCH, not a budget — deliberately generous, in
+ *     the same spirit as `DEFAULT_RUN_BUDGET`. A thorough consult on a large
+ *     repo runs $0.40-$1.00, so a full 5-consult session lands near $2-$5 and
+ *     never approaches this. It exists only so an advisor stuck in a loop has
+ *     something to stop it.
+ *
+ * State is held in a closure via {@link makeAdvisorState}; no module-level
+ * mutable state, so two sessions in one process cannot bleed into each other.
+ */
+/** The session tier that may escalate. Balanced only, by design. */
+export declare const ADVISOR_TIER = "balanced";
+/** The tier a consult itself runs on. */
+export declare const ADVISOR_MODEL_TIER = "peak";
+/** Bounds on escalation within a single session. */
+export interface AdvisorLimits {
+    /** Hard cap on consults per session. */
+    maxConsults: number;
+    /** Runaway-catch ceiling on aggregate advisor spend, in the same unit as StageUsage.cost. */
+    maxSpend: number;
+}
+export declare const DEFAULT_ADVISOR_LIMITS: AdvisorLimits;
+/** Mutable per-session advisor accounting. */
+export interface AdvisorState {
+    consults: number;
+    spend: number;
+}
+/** A live session's advisor accounting, held in a closure. */
+export interface AdvisorStateHandle {
+    read(): AdvisorState;
+    /** Record a completed consult. Returns the state after recording. */
+    record(cost: number): AdvisorState;
+}
+export declare function makeAdvisorState(): AdvisorStateHandle;
+/** The outcome of the pre-consult gate. */
+export interface ConsultDecision {
+    allow: boolean;
+    /** Plain-text explanation when disallowed, surfaced to the model verbatim. */
+    reason?: string;
+}
+export interface ConsultGateInput {
+    /** The LIVE session model id (pi's picker can change this mid-session). */
+    model: string | undefined;
+    state: AdvisorState;
+    limits: AdvisorLimits;
+}
+/**
+ * Decide whether one consult may proceed. PURE.
+ *
+ * The tier check reads the model at CALL time rather than at registration time:
+ * tools register once at activation but pi's picker can switch the session model
+ * afterwards, so a registration-time check would both leave the tool live after
+ * switching away from Balanced and hide it forever from a session that switched
+ * to Balanced.
+ */
+export declare function decideConsult(input: ConsultGateInput): ConsultDecision;
+/**
+ * The line appended to a consult's advice so spend is visible at the moment it
+ * happens. `/cost` cannot see child processes at all (it accumulates off the
+ * parent's `turn_end`), so without this an advisor consult is invisible — see
+ * YAG-383 for the server-authoritative fix.
+ */
+export declare function formatConsultCost(input: {
+    cost: number;
+    consults: number;
+    limits: AdvisorLimits;
+}): string;
+/** The advisor subtotal line `/cost` appends when a session has escalated. */
+export declare function formatAdvisorSubtotal(state: AdvisorState, limits: AdvisorLimits): string;
+//# sourceMappingURL=advisor.d.ts.map

package/dist/extension/advisor.js

@@ -0,0 +1,101 @@
+/**
+ * The PURE half of the ask_advisor escalation (YAG-380).
+ *
+ * Balanced sessions drive on `advanced` and escalate hard judgment calls to
+ * `peak`. This module owns every decision about whether a consult may happen and
+ * what it cost; `askAdvisorTool.ts` owns the spawn. Same split as `permission.ts`
+ * (`decideGate` pure, wiring separate), for the same reason: the rules are what
+ * need exhaustive tests, and they must not require a child process to exercise.
+ *
+ * Two bounds, both necessarily POST-HOC. pi exposes no pre-emptive turn or token
+ * ceiling (see `pipeline/budget.ts`), so a consult's cost is only knowable once
+ * the child has exited:
+ *
+ *   - `maxConsults` is the real product bound. It makes escalation predictable
+ *     and priceable, which is the point of the cap.
+ *   - `maxSpend` is a RUNAWAY CATCH, not a budget — deliberately generous, in
+ *     the same spirit as `DEFAULT_RUN_BUDGET`. A thorough consult on a large
+ *     repo runs $0.40-$1.00, so a full 5-consult session lands near $2-$5 and
+ *     never approaches this. It exists only so an advisor stuck in a loop has
+ *     something to stop it.
+ *
+ * State is held in a closure via {@link makeAdvisorState}; no module-level
+ * mutable state, so two sessions in one process cannot bleed into each other.
+ */
+/** The session tier that may escalate. Balanced only, by design. */
+export const ADVISOR_TIER = "balanced";
+/** The tier a consult itself runs on. */
+export const ADVISOR_MODEL_TIER = "peak";
+export const DEFAULT_ADVISOR_LIMITS = {
+    maxConsults: 5,
+    maxSpend: 10,
+};
+export function makeAdvisorState() {
+    const state = { consults: 0, spend: 0 };
+    return {
+        read: () => ({ ...state }),
+        record(cost) {
+            state.consults += 1;
+            // A child that reports no usage still counts as a consult — the cap is
+            // about escalation attempts, not only about money.
+            state.spend += Number.isFinite(cost) && cost > 0 ? cost : 0;
+            return { ...state };
+        },
+    };
+}
+/**
+ * Decide whether one consult may proceed. PURE.
+ *
+ * The tier check reads the model at CALL time rather than at registration time:
+ * tools register once at activation but pi's picker can switch the session model
+ * afterwards, so a registration-time check would both leave the tool live after
+ * switching away from Balanced and hide it forever from a session that switched
+ * to Balanced.
+ */
+export function decideConsult(input) {
+    const { model, state, limits } = input;
+    if (model !== ADVISOR_TIER) {
+        return {
+            allow: false,
+            reason: `ask_advisor is only available on the Balanced tier (this session is on ` +
+                `"${model ?? "unknown"}"). Switch the model to Balanced to consult the ` +
+                `peak-tier advisor, or reason it through on the current tier.`,
+        };
+    }
+    if (state.consults >= limits.maxConsults) {
+        return {
+            allow: false,
+            reason: `Advisor consult cap reached (${state.consults} of ${limits.maxConsults} ` +
+                `used this session). Escalation is capped so a session's cost stays ` +
+                `predictable. Decide this one yourself, or start a fresh session.`,
+        };
+    }
+    if (state.spend >= limits.maxSpend) {
+        return {
+            allow: false,
+            reason: `Advisor spend ceiling reached ($${state.spend.toFixed(2)} this session). ` +
+                `This is a runaway guard rather than a budget, so hitting it usually ` +
+                `means a consult looped. Decide this one yourself, or start a fresh session.`,
+        };
+    }
+    return { allow: true };
+}
+/**
+ * The line appended to a consult's advice so spend is visible at the moment it
+ * happens. `/cost` cannot see child processes at all (it accumulates off the
+ * parent's `turn_end`), so without this an advisor consult is invisible — see
+ * YAG-383 for the server-authoritative fix.
+ */
+export function formatConsultCost(input) {
+    const { cost, consults, limits } = input;
+    return `Advisor consult: $${cost.toFixed(2)} (${consults} of ${limits.maxConsults} used this session).`;
+}
+/** The advisor subtotal line `/cost` appends when a session has escalated. */
+export function formatAdvisorSubtotal(state, limits) {
+    if (state.consults === 0)
+        return "";
+    const plural = state.consults === 1 ? "consult" : "consults";
+    return (`Advisor: ${state.consults} ${plural} of ${limits.maxConsults}, ` +
+        `$${state.spend.toFixed(2)} on peak.`);
+}
+//# sourceMappingURL=advisor.js.map

package/dist/extension/askAdvisorTool.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `ask_advisor` — the peak-tier escalation available to Balanced sessions (YAG-380).
+ *
+ * Cheap driver, expensive consultant: a Balanced session drives on `advanced` and
+ * calls this when it hits a judgment call worth the strongest model. The consult
+ * spawns a child pi at `peak` through the same `runStage` seam `/go` uses, and
+ * returns the advice as plain TEXT the driver acts on — text we own, so
+ * `record_decision` can bank it into the corpus afterwards.
+ *
+ * Two deliberate design calls, both of which cost money and buy quality:
+ *
+ *   1. The advisor gets REAL read-only recon (read/grep/find/ls), the same set
+ *      the plan stage uses. An advisor limited to what the driver pre-digested
+ *      rubber-stamps the driver's framing; half the value of escalation is
+ *      looking where the driver did not think to look. This makes a consult an
+ *      agentic loop, so a thorough one on a large repo runs $0.40-$1.00 rather
+ *      than the ~4c a single-shot completion would cost. That is the price of
+ *      the advisor being useful. It gets NO bash: a consultant reasons and
+ *      reads, it must not build, run, or write.
+ *   2. The input schema is NARROW on purpose — question, what was tried,
+ *      relevant excerpts. There is deliberately no field a conversation
+ *      transcript fits into, because passing the transcript is how a consult
+ *      silently becomes more expensive than just running peak.
+ *
+ * The gate, the cap and the spend ceiling live in `advisor.ts` and are pure;
+ * this module is the I/O.
+ */
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { type AdvisorLimits, type AdvisorStateHandle } from "./advisor.js";
+import { runStage as defaultRunStage } from "./pipeline/runner.js";
+import type { PipelineStage } from "./pipeline/types.js";
+/**
+ * Read-only recon plus grounding. Mirrors the `plan` stage's allowlist for the
+ * reason documented there: enough tools to navigate instead of flailing on a
+ * single `read`. No `bash`.
+ */
+export declare const ADVISOR_TOOLS: string[];
+declare const parameters: Type.TObject<{
+    question: Type.TString;
+    tried: Type.TOptional<Type.TString>;
+    excerpts: Type.TOptional<Type.TString>;
+}>;
+export interface MakeAskAdvisorToolOptions {
+    /** Per-session consult accounting. Created once per session in index.ts. */
+    state: AdvisorStateHandle;
+    limits?: AdvisorLimits;
+    /** Injectable so tests never spawn a child. */
+    runStage?: typeof defaultRunStage;
+}
+/**
+ * Assemble the consult brief. The advisor's persona already tells it not to take
+ * this framing on trust, so the brief orients rather than constrains.
+ */
+export declare function buildConsultBrief(params: {
+    question: string;
+    tried?: string;
+    excerpts?: string;
+}): string;
+/**
+ * The synthetic stage a consult runs as.
+ *
+ * `id` reuses the existing `plan` StageId rather than adding an advisor member:
+ * the advisor is NOT a pipeline stage, and a new StageId would ripple into the
+ * feed/activity reducers that switch over it. `agent` is what selects the
+ * persona, and that is the advisor's own.
+ */
+export declare function advisorStage(): PipelineStage;
+export declare function makeAskAdvisorTool(opts: MakeAskAdvisorToolOptions): ToolDefinition<typeof parameters, {
+    consults: number;
+    cost: number;
+}>;
+/**
+ * `/advise <question>` — the manual escalation lever.
+ *
+ * Runs the SAME tool the model calls, sharing one state handle, so a manual
+ * consult draws on the same cap rather than opening a side channel around it.
+ * The advice is sent into the conversation (like /go-compare's report) so the
+ * driver sees it in context and can act on it.
+ */
+export declare function registerAdviseCommand(pi: ExtensionAPI, tool: ReturnType<typeof makeAskAdvisorTool>): void;
+export {};
+//# sourceMappingURL=askAdvisorTool.d.ts.map