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

package/dist/launch.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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;
+    /** Distribution-specific root shared with the bundled extension. */
+    stateDir?: 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;
+    /**
+     * Launcher-computed agent flags (e.g. Claude-compat `--skill` /
+     * `--prompt-template` paths). Inserted before the user's passthrough args so
+     * anything the user passes explicitly still wins.
+     */
+    extraAgentArgs?: string[];
+}
+export declare function buildLaunch(creds: Credentials | null, passthroughArgs: string[], opts: BuildLaunchOptions): LaunchPlan;
+//# sourceMappingURL=launch.d.ts.map

package/dist/launch.js

@@ -0,0 +1,111 @@
+/**
+ * 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 { agentDirEnvVar } from "./branding.js";
+/**
+ * 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 const EXPIRY_WARNING_THRESHOLD_MS = 30 * 60 * 1000;
+/**
+ * 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 function classifyTokenExpiry(expiresAt, nowMs, thresholdMs = EXPIRY_WARNING_THRESHOLD_MS) {
+    if (!expiresAt)
+        return { kind: "unknown" };
+    const expiryMs = Date.parse(expiresAt);
+    if (Number.isNaN(expiryMs))
+        return { kind: "unknown" };
+    const remaining = expiryMs - nowMs;
+    if (remaining <= 0)
+        return { kind: "expired" };
+    if (remaining <= thresholdMs) {
+        return { kind: "approaching", minutesRemaining: Math.max(1, Math.ceil(remaining / 60_000)) };
+    }
+    return { kind: "valid" };
+}
+export function buildLaunch(creds, passthroughArgs, opts) {
+    if (!creds?.token) {
+        throw new Error("Not logged in. Run `yagni login` first.");
+    }
+    // Launch-time expiry preflight. An already-expired token would spawn a session
+    // that 401s on its very first completion and on every grounding tool, so block
+    // it here with an actionable login prompt instead. An approaching expiry is a
+    // non-fatal warning the caller surfaces; the session still launches.
+    const nowMs = opts.now ? opts.now() : Date.now();
+    const expiry = classifyTokenExpiry(creds.expiresAt, nowMs);
+    if (expiry.kind === "expired") {
+        throw new Error("Your YAGNI Code session has expired. Run `yagni login` to re-authenticate.");
+    }
+    const warnings = [];
+    if (expiry.kind === "approaching") {
+        const m = expiry.minutesRemaining;
+        warnings.push(`Your YAGNI Code session expires in about ${m} minute${m === 1 ? "" : "s"}. ` +
+            "Run `yagni login` to refresh it before it lapses.");
+    }
+    const env = {
+        ...(opts.baseEnv ?? {}),
+        YAGNI_TOKEN: creds.token,
+        YAGNI_BASE_URL: creds.baseUrl,
+        // Forward the token's expiry (when known) so the extension can surface a
+        // single in-session "expiring soon" notice. Read-only signal: no refresh.
+        ...(creds.expiresAt ? { YAGNI_TOKEN_EXPIRES_AT: creds.expiresAt } : {}),
+        // Forward the bound workspace id (when known) so the extension can key its
+        // one-time init-pass marker per workspace (Onramp Door B idempotency).
+        ...(creds.workspaceId ? { YAGNI_WORKSPACE_ID: creds.workspaceId } : {}),
+        // Forward the active profile's file path (when known) so the extension can
+        // atomically persist a mid-session token rotation back to the same profile
+        // the launcher read (0600). Absent when the caller can't resolve it.
+        ...(opts.profilePath ? { YAGNI_PROFILE_PATH: opts.profilePath } : {}),
+        ...(opts.stateDir ? { YAGNI_CODE_HOME: opts.stateDir } : {}),
+        // Rebrand pi's chrome ("pi"/"π" → "YAGNI Code"): pi reads piConfig.name from
+        // the package at PI_PACKAGE_DIR (a shadow package the launcher generates).
+        ...(opts.piPackageDir ? { PI_PACKAGE_DIR: opts.piPackageDir } : {}),
+        // Hermetic config: pin pi's agent dir to a YAGNI-owned location so the
+        // user's machine-wide ~/.pi/agent (providers, stored keys, saved default
+        // model, theme) can't bleed in or bypass the YAGNI proxy. The model scope
+        // is then exactly the backend catalog under the `yagni` provider.
+        //
+        // pi derives the env var NAME from its app name
+        // (`${APP_NAME.toUpperCase()}_CODING_AGENT_DIR`), so once rebranded it reads
+        // "YAGNI_CODING_AGENT_DIR". We set that key AND the plain
+        // PI_CODING_AGENT_DIR as defense-in-depth: if the rebrand ever fails the app
+        // name stays "pi", and the plain key keeps the hermetic boundary intact
+        // instead of silently falling back to ~/.pi/agent.
+        [agentDirEnvVar()]: opts.agentDir,
+        PI_CODING_AGENT_DIR: opts.agentDir,
+        // Match the e2b harness defaults: skip pi's update check + telemetry.
+        PI_SKIP_VERSION_CHECK: "1",
+        PI_TELEMETRY: "0",
+    };
+    // Always load our extension. Default the provider to `yagni` unless the user
+    // explicitly chose one (so power users can still point pi elsewhere).
+    const userChoseProvider = passthroughArgs.some(arg => arg === "--provider" || arg.startsWith("--provider="));
+    // Default the model to the `balanced` tier (YAG-380). Balanced drives on the
+    // judgment-grade `advanced` model — the same driver quality this default gave
+    // before — and additionally lets the session escalate hard calls to `peak`
+    // through the capped ask_advisor tool. So it is strictly additive: no session
+    // reasons worse than it did, and the hard ones can reason better. A user
+    // `--model` (e.g. `standard` or `efficient`) still wins. Without this, pi's
+    // default-model heuristic could land an interactive session on a weaker tier.
+    // Detect if the user explicitly set a model, whether via "--model" as a separate
+    // argument or using the equals form "--model=efficient". The previous check only
+    // caught the separate form, causing a duplicate "--model balanced" to be added
+    // when the equals form was used.
+    const userChoseModel = passthroughArgs.some(arg => arg === "--model" || arg.startsWith("--model="));
+    const argv = [
+        "-e",
+        opts.extensionPath,
+        ...(userChoseProvider ? [] : ["--provider", "yagni"]),
+        ...(userChoseModel ? [] : ["--model", "balanced"]),
+        ...(opts.extraAgentArgs ?? []),
+        ...passthroughArgs,
+    ];
+    return { env, argv, warnings };
+}
+//# sourceMappingURL=launch.js.map

package/dist/login.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Device-code login flow (RFC 8628 client side):
+ *   1. POST /api/yagni-code/auth/device → show the user_code + verification URL.
+ *   2. Poll POST /api/yagni-code/auth/token until the human approves in the
+ *      web app, then store the returned token.
+ */
+import type { Credentials } from "./credentials.js";
+export interface LoginDeps {
+    baseUrl?: string;
+    /** Which profile to store the minted token in. Defaults to the active one. */
+    profileName?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (msg: string) => void;
+    persist?: (creds: Credentials) => Promise<void>;
+    /** Open a URL in the user's default browser. Defaults to cross-platform open. */
+    openUrl?: (url: string) => Promise<void>;
+}
+/** Spawns a binary with a literal arg vector (no shell). */
+type OpenRunner = (cmd: string, args: string[]) => Promise<void>;
+/**
+ * Resolve the OS-native command + argv to open `url` in the default browser,
+ * cross-platform. The URL is always a standalone argv element so it is handed
+ * to the OS verbatim — it is NEVER interpolated into a shell string, where
+ * `$(...)` / backticks in a hostile verification URL could execute commands.
+ *
+ *   macOS:   open <url>
+ *   Linux:   xdg-open <url>
+ *   Windows: cmd /c start "" <url>   (the empty "" is start's window-title slot;
+ *            without it `start` swallows the URL as the title and opens nothing)
+ */
+export declare function resolveOpenCommand(url: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Open a URL in the user's default browser, best-effort. Uses `execFile` (no
+ * shell) so a hostile URL cannot inject commands. Failures are swallowed — the
+ * URL is still printed for manual copy. `runner` is injectable for tests.
+ */
+export declare const realOpenUrl: (url: string, runner?: OpenRunner) => Promise<void>;
+export declare function login(deps?: LoginDeps): Promise<Credentials>;
+export {};
+//# sourceMappingURL=login.d.ts.map

package/dist/login.js

@@ -0,0 +1,142 @@
+/**
+ * Device-code login flow (RFC 8628 client side):
+ *   1. POST /api/yagni-code/auth/device → show the user_code + verification URL.
+ *   2. Poll POST /api/yagni-code/auth/token until the human approves in the
+ *      web app, then store the returned token.
+ */
+import { execFile } from "node:child_process";
+import { resolveBaseUrl } from "./config.js";
+import { getActiveProfileName, persistProfileCredentials } from "./profiles.js";
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Per-poll wall-clock cap so a single hung token request can't stall the whole
+ * device-code wait. A timed-out poll is swallowed and the loop tries again until
+ * the device code's own deadline.
+ */
+const POLL_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * RFC 8628 `slow_down`: when the server signals we are polling too fast (HTTP
+ * 429), lengthen the interval by 5s and keep waiting rather than failing.
+ */
+const SLOW_DOWN_INCREMENT_MS = 5_000;
+/** Whether an error is a per-request timeout/abort (vs. a real network error). */
+function isTimeoutError(err) {
+    return err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+}
+/**
+ * Resolve the OS-native command + argv to open `url` in the default browser,
+ * cross-platform. The URL is always a standalone argv element so it is handed
+ * to the OS verbatim — it is NEVER interpolated into a shell string, where
+ * `$(...)` / backticks in a hostile verification URL could execute commands.
+ *
+ *   macOS:   open <url>
+ *   Linux:   xdg-open <url>
+ *   Windows: cmd /c start "" <url>   (the empty "" is start's window-title slot;
+ *            without it `start` swallows the URL as the title and opens nothing)
+ */
+export function resolveOpenCommand(url, platform = process.platform) {
+    if (platform === "darwin")
+        return { cmd: "open", args: [url] };
+    if (platform === "win32")
+        return { cmd: "cmd", args: ["/c", "start", "", url] };
+    return { cmd: "xdg-open", args: [url] };
+}
+const spawnRunner = (cmd, args) => new Promise((resolve, reject) => {
+    execFile(cmd, args, (err) => (err ? reject(err) : resolve()));
+});
+/**
+ * Open a URL in the user's default browser, best-effort. Uses `execFile` (no
+ * shell) so a hostile URL cannot inject commands. Failures are swallowed — the
+ * URL is still printed for manual copy. `runner` is injectable for tests.
+ */
+export const realOpenUrl = (url, runner = spawnRunner) => {
+    const { cmd, args } = resolveOpenCommand(url);
+    return runner(cmd, args).catch(() => {
+        // Silently fail — the user can still copy the URL manually.
+    });
+};
+export async function login(deps = {}) {
+    const baseUrl = deps.baseUrl ?? resolveBaseUrl();
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? realSleep;
+    const log = deps.log ?? ((m) => process.stdout.write(`${m}\n`));
+    // By default the token lands in the active profile; tests inject `persist`.
+    const persist = deps.persist ??
+        (async (creds) => {
+            const profileName = deps.profileName ?? (await getActiveProfileName());
+            await persistProfileCredentials(profileName, creds);
+        });
+    // Open the verification URL automatically; failures are swallowed so the
+    // user can still copy it manually.
+    const openUrl = deps.openUrl ?? realOpenUrl;
+    const startRes = await fetchImpl(`${baseUrl}/api/yagni-code/auth/device`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+        signal: AbortSignal.timeout(POLL_REQUEST_TIMEOUT_MS),
+    });
+    if (!startRes.ok) {
+        throw new Error(`Could not start login (HTTP ${startRes.status}). Is YAGNI Code enabled for your workspace?`);
+    }
+    const start = (await startRes.json());
+    log("");
+    log("Opening your browser to authorize YAGNI Code…");
+    log(`    ${start.verification_url}`);
+    log("If it doesn't open automatically, copy the URL above and enter the code:");
+    log(`    ${start.user_code}`);
+    log("");
+    log("Waiting for approval…");
+    // Best-effort auto-open; the URL is already printed above.
+    await openUrl(start.verification_url).catch(() => { });
+    const deadline = now() + start.expires_in * 1000;
+    // Interval can grow across the loop when the server asks us to slow down, so
+    // it's mutable rather than a one-shot constant.
+    let intervalMs = Math.max(1, start.interval) * 1000;
+    while (now() < deadline) {
+        await sleep(intervalMs);
+        let res;
+        try {
+            res = await fetchImpl(`${baseUrl}/api/yagni-code/auth/token`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ device_code: start.device_code }),
+                signal: AbortSignal.timeout(POLL_REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            // A per-request timeout (or transient blip) must not abandon a long
+            // device-code wait — keep polling until the code's own deadline. A
+            // genuine, non-timeout error still propagates.
+            if (isTimeoutError(err))
+                continue;
+            throw err;
+        }
+        if (res.status === 200) {
+            const data = (await res.json());
+            const creds = {
+                token: data.token,
+                baseUrl,
+                workspaceId: data.workspaceId,
+                expiresAt: data.expiresAt,
+            };
+            await persist(creds);
+            log("✓ Logged in. Run `yagni` in a repo to start.");
+            return creds;
+        }
+        if (res.status === 428) {
+            continue; // authorization_pending — keep polling
+        }
+        if (res.status === 429) {
+            // slow_down — back off by 5s (RFC 8628) and keep polling.
+            intervalMs += SLOW_DOWN_INCREMENT_MS;
+            continue;
+        }
+        if (res.status === 410) {
+            throw new Error("The login code expired before approval. Run `yagni login` again.");
+        }
+        throw new Error(`Login failed (HTTP ${res.status}).`);
+    }
+    throw new Error("Login timed out before approval. Run `yagni login` again.");
+}
+//# sourceMappingURL=login.js.map

package/dist/logout.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Logout: revoke the active profile's token server-side (best-effort) and clear
+ * it locally. The environment binding (name + base URL) is kept so a later
+ * `yagni login` re-authenticates the same environment without re-`use`.
+ */
+import { type Credentials } from "./credentials.js";
+export interface LogoutDeps {
+    fetchImpl?: typeof fetch;
+    read?: () => Promise<Credentials | null>;
+    remove?: () => Promise<void>;
+    log?: (msg: string) => void;
+}
+export declare function logout(deps?: LogoutDeps): Promise<void>;
+//# sourceMappingURL=logout.d.ts.map

package/dist/logout.js

@@ -0,0 +1,34 @@
+/**
+ * Logout: revoke the active profile's token server-side (best-effort) and clear
+ * it locally. The environment binding (name + base URL) is kept so a later
+ * `yagni login` re-authenticates the same environment without re-`use`.
+ */
+import { clearProfileToken, credentialsFromProfile, getActiveProfileName, readActiveProfile, } from "./profiles.js";
+export async function logout(deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const read = deps.read ?? (async () => credentialsFromProfile(await readActiveProfile()));
+    const remove = deps.remove ??
+        (async () => {
+            await clearProfileToken(await getActiveProfileName());
+        });
+    const log = deps.log ?? ((m) => process.stdout.write(`${m}\n`));
+    const creds = await read();
+    if (creds?.token) {
+        try {
+            await fetchImpl(`${creds.baseUrl}/api/yagni-code/auth/revoke`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${creds.token}`,
+                },
+                body: "{}",
+            });
+        }
+        catch {
+            // Best-effort: a network failure shouldn't block local logout.
+        }
+    }
+    await remove();
+    log("✓ Logged out.");
+}
+//# sourceMappingURL=logout.js.map

package/dist/paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Resolve the dependency entry points the launcher needs: pi's CLI and the
+ * YAGNI extension. pi is a package dependency, so we resolve it from this module
+ * rather than assuming a global install; the extension ships inside our own dist.
+ *
+ * We use the ESM-native `import.meta.resolve` (NOT `createRequire().resolve`):
+ * pi is an ESM-only package whose `exports` map declares only the `import`
+ * condition, so the CommonJS `require` resolver throws ERR_PACKAGE_PATH_NOT_EXPORTED
+ * on it. pi's package.json is also not an exported subpath, so we read it from
+ * disk after resolving the package's main entry.
+ */
+/**
+ * Absolute path to the extension's built entry.
+ *
+ * Published installs read the copy bundled into this package's own
+ * `dist/extension/` (see scripts/bundle-extension.mjs) — pi-extension-yagni is a
+ * private workspace package and is never on the registry, so module resolution
+ * would fail. In the monorepo the bundled copy only exists after a build, so we
+ * fall back to resolving the workspace-linked package, which keeps `pnpm test`
+ * and a fresh checkout working before anything is bundled.
+ */
+export declare function resolveExtensionPath(): string;
+/**
+ * Absolute path to pi's package root — the dir whose package.json names the
+ * package. The shadow package dir is built from this (we read its package.json
+ * and symlink its `dist/`). Uses the same upward walk as resolvePiCliPath.
+ */
+export declare function resolvePiPackageDir(): string;
+/** Absolute path to pi's CLI entry (its package.json `bin.pi`). */
+export declare function resolvePiCliPath(): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.js

@@ -0,0 +1,87 @@
+/**
+ * Resolve the dependency entry points the launcher needs: pi's CLI and the
+ * YAGNI extension. pi is a package dependency, so we resolve it from this module
+ * rather than assuming a global install; the extension ships inside our own dist.
+ *
+ * We use the ESM-native `import.meta.resolve` (NOT `createRequire().resolve`):
+ * pi is an ESM-only package whose `exports` map declares only the `import`
+ * condition, so the CommonJS `require` resolver throws ERR_PACKAGE_PATH_NOT_EXPORTED
+ * on it. pi's package.json is also not an exported subpath, so we read it from
+ * disk after resolving the package's main entry.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveModulePath(specifier) {
+    return fileURLToPath(import.meta.resolve(specifier));
+}
+/**
+ * Absolute path to the extension's built entry.
+ *
+ * Published installs read the copy bundled into this package's own
+ * `dist/extension/` (see scripts/bundle-extension.mjs) — pi-extension-yagni is a
+ * private workspace package and is never on the registry, so module resolution
+ * would fail. In the monorepo the bundled copy only exists after a build, so we
+ * fall back to resolving the workspace-linked package, which keeps `pnpm test`
+ * and a fresh checkout working before anything is bundled.
+ */
+export function resolveExtensionPath() {
+    const bundled = fileURLToPath(new URL("./extension/index.js", import.meta.url));
+    if (existsSync(bundled))
+        return bundled;
+    return resolveModulePath("pi-extension-yagni");
+}
+/**
+ * Absolute path to pi's package root — the dir whose package.json names the
+ * package. The shadow package dir is built from this (we read its package.json
+ * and symlink its `dist/`). Uses the same upward walk as resolvePiCliPath.
+ */
+export function resolvePiPackageDir() {
+    const mainEntry = resolveModulePath("@earendil-works/pi-coding-agent");
+    let dir = dirname(mainEntry);
+    for (let i = 0; i < 6; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === "@earendil-works/pi-coding-agent") {
+                return dir;
+            }
+        }
+        catch {
+            // No package.json here (or unreadable) — keep walking up.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: pi ships its main entry under <root>/dist/, so the root is two
+    // levels up from the resolved entry.
+    return dirname(dirname(mainEntry));
+}
+/** Absolute path to pi's CLI entry (its package.json `bin.pi`). */
+export function resolvePiCliPath() {
+    // Resolves pi's main entry (e.g. <root>/@earendil-works/pi-coding-agent/dist/index.js).
+    const mainEntry = resolveModulePath("@earendil-works/pi-coding-agent");
+    // Walk up to the package root (the dir whose package.json names the package)
+    // and read `bin.pi` from disk.
+    let dir = dirname(mainEntry);
+    for (let i = 0; i < 6; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === "@earendil-works/pi-coding-agent") {
+                const binRel = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.pi ?? "dist/cli.js";
+                return join(dir, binRel);
+            }
+        }
+        catch {
+            // No package.json here (or unreadable) — keep walking up.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: pi ships its CLI alongside its main entry under dist/.
+    return join(dirname(mainEntry), "cli.js");
+}
+//# sourceMappingURL=paths.js.map

package/dist/piPackage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shadow pi package dir.
+ *
+ * pi reads its identity (`piConfig.name`) and all bundled assets (theme, TUI
+ * assets, export-html, CHANGELOG) relative to the package dir returned by
+ * `getPackageDir()`, which honors the `PI_PACKAGE_DIR` env var. To rebrand
+ * "pi"/"π" out of the chrome WITHOUT modifying `node_modules` (lost on
+ * reinstall) or copying pi wholesale, we generate a tiny shadow dir that:
+ *
+ *   - owns its own `package.json` (pi's, with `piConfig.name` injected), and
+ *   - symlinks `dist/` (+ CHANGELOG/README/docs/examples) back to the real pi
+ *     package, so asset/theme resolution still finds the real files.
+ *
+ * The launcher points `PI_PACKAGE_DIR` at this dir. Regenerated every launch so
+ * a pi upgrade or store-path move can never leave a stale package.json or a
+ * dangling symlink behind.
+ */
+export interface ShadowPiPackageOptions {
+    /** The real pi package root (the dir whose package.json names the package). */
+    realPiDir: string;
+    /** Where to materialize the shadow package (a hermetic, YAGNI-owned dir). */
+    shadowDir: string;
+    /** The `piConfig.name` to inject — what pi shows as its app name. */
+    name: string;
+}
+/**
+ * Materialize (idempotently) the shadow pi package and return its path.
+ *
+ * @throws if the real pi package.json cannot be read — the launcher needs it to
+ * derive pi's version/name, and a silent fallback would re-leak "pi".
+ */
+export declare function ensureShadowPiPackage(opts: ShadowPiPackageOptions): string;
+//# sourceMappingURL=piPackage.d.ts.map

package/dist/piPackage.js

@@ -0,0 +1,71 @@
+/**
+ * Shadow pi package dir.
+ *
+ * pi reads its identity (`piConfig.name`) and all bundled assets (theme, TUI
+ * assets, export-html, CHANGELOG) relative to the package dir returned by
+ * `getPackageDir()`, which honors the `PI_PACKAGE_DIR` env var. To rebrand
+ * "pi"/"π" out of the chrome WITHOUT modifying `node_modules` (lost on
+ * reinstall) or copying pi wholesale, we generate a tiny shadow dir that:
+ *
+ *   - owns its own `package.json` (pi's, with `piConfig.name` injected), and
+ *   - symlinks `dist/` (+ CHANGELOG/README/docs/examples) back to the real pi
+ *     package, so asset/theme resolution still finds the real files.
+ *
+ * The launcher points `PI_PACKAGE_DIR` at this dir. Regenerated every launch so
+ * a pi upgrade or store-path move can never leave a stale package.json or a
+ * dangling symlink behind.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+// Entries pi resolves relative to its package dir. `dist` carries theme + TUI
+// assets + export templates (the load-bearing ones); the rest back /changelog,
+// /about, etc. Each is symlinked only if it exists in the real package.
+const LINKED_ENTRIES = ["dist", "CHANGELOG.md", "README.md", "docs", "examples"];
+function linkInto(shadowDir, realPiDir, entry) {
+    const target = join(realPiDir, entry);
+    if (!existsSync(target))
+        return;
+    const linkPath = join(shadowDir, entry);
+    // Clear any prior entry so we never stack or dangle. A symlink must be
+    // unlinked directly: rmSync stats THROUGH it, so on a dangling link (target
+    // checkout deleted) it sees ENOENT, force-swallows it, and leaves the link
+    // in place - then symlinkSync throws EEXIST and the rebrand silently drops.
+    if (isSymlink(linkPath)) {
+        unlinkSync(linkPath);
+    }
+    else if (existsSync(linkPath)) {
+        rmSync(linkPath, { recursive: true, force: true });
+    }
+    const type = statSync(target).isDirectory() ? "dir" : "file";
+    symlinkSync(target, linkPath, type);
+}
+function isSymlink(p) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Materialize (idempotently) the shadow pi package and return its path.
+ *
+ * @throws if the real pi package.json cannot be read — the launcher needs it to
+ * derive pi's version/name, and a silent fallback would re-leak "pi".
+ */
+export function ensureShadowPiPackage(opts) {
+    const { realPiDir, shadowDir, name } = opts;
+    const realPkgRaw = readFileSync(join(realPiDir, "package.json"), "utf8");
+    const realPkg = JSON.parse(realPkgRaw);
+    mkdirSync(shadowDir, { recursive: true });
+    const shadowPkg = {
+        ...realPkg,
+        piConfig: { ...(realPkg.piConfig ?? {}), name },
+    };
+    writeFileSync(join(shadowDir, "package.json"), `${JSON.stringify(shadowPkg, null, 2)}\n`);
+    for (const entry of LINKED_ENTRIES) {
+        linkInto(shadowDir, realPiDir, entry);
+    }
+    return shadowDir;
+}
+//# sourceMappingURL=piPackage.js.map