limn-review 0.1.123

package/dist/ai/runtime.js

@@ -0,0 +1,535 @@
+// THE AI RUNTIME LOADER — the ONE module allowed to import an AI SDK.
+//
+// Claude Review, the review chat and AI Fix are free and ship in the public npm package, but the
+// SDKs they run on do NOT: `@anthropic-ai/claude-agent-sdk` pulls a native `claude` binary of
+// ~110 MB to download (~240 MB unpacked) per platform, against a ~18 MB package. Putting it in
+// `dependencies` (or `optionalDependencies`, which npm installs by default and a dependent package
+// cannot switch off under `npx`) would make every `npx limn-review` fifteen times heavier for
+// people who never press a Review button. So the four packages are INSTALLED ON FIRST USE:
+//
+//   @anthropic-ai/claude-agent-sdk · @anthropic-ai/sdk · @modelcontextprotocol/sdk · zod
+//
+// at EXACT pinned versions into `<dataDir>/ai-runtime` (`~/.limn/ai-runtime`), by
+// `npm install --prefix`, after the reader presses "Set up AI" or runs `limn ai install`. The pins
+// ride the release manifest as a NON-dependency field (`limnAiRuntime`), generated by
+// scripts/build-release.mjs from what the workspace actually installed — so a user downloads the
+// versions the test suite ran against.
+//
+// ⚠ HOW A MODULE OUTSIDE OUR OWN node_modules IS LOADED. A bare specifier in ESM cannot see another
+// prefix and NODE_PATH does not apply to ESM, so each package is located by walking
+// `<dir>/node_modules` the way ESM resolution does, and then imported by FILE URL. The entry
+// is picked with the ESM conditions (`node`, `import`, `default`), NEVER `require.resolve`: zod
+// publishes `index.cjs` under `require` and `index.js` under `import`, and the SDK's own
+// `import 'zod'` takes the ESM one. Loading the CJS twin would give our tool schemas a SECOND zod
+// instance, which silently breaks the SDK's schema conversion. Same install, same conditions,
+// same instance — the test pins it.
+//
+// ⚠ DEV IS UNCHANGED. When the workspace's own node_modules resolve the Agent SDK (`pnpm dev`, the
+// test suite), everything loads by plain bare specifier exactly as the static imports did, and no
+// runtime directory is consulted first. The cloud image is the third case: it ships
+// `@anthropic-ai/sdk` as a real dependency (`--with-pro`, for the metered summary path) and no
+// Agent SDK, so a package missing from one source falls through to the other.
+//
+// ⚠ NOTHING ELSE MAY IMPORT THESE PACKAGES. Type-only imports are fine (erased at emit); a value
+// import anywhere else fails with ERR_MODULE_NOT_FOUND on an npm install — and only when someone
+// clicks the feature. scripts/build-release.mjs greps the emitted JS and fails the build on one.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolveDataDir } from '../data-dir.js';
+export const AI_RUNTIME_PACKAGES = [
+    '@anthropic-ai/claude-agent-sdk',
+    '@anthropic-ai/sdk',
+    '@modelcontextprotocol/sdk',
+    'zod',
+];
+/** The release manifest's field carrying the pins. Spelled once; build-release.mjs mirrors it. */
+export const AI_RUNTIME_MANIFEST_FIELD = 'limnAiRuntime';
+/** An exact semver version — no range, no tag. Anything else is refused before npm sees it. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const AGENT_SDK = '@anthropic-ai/claude-agent-sdk';
+/**
+ * The entry each package is loaded through. ⚠ The MCP SDK's ROOT export names a file it does not
+ * ship (`dist/esm/index.js` is absent in 1.29) — its real entries are subpaths — so it is checked and
+ * loaded through `./server`. Measured on the real download, not assumed.
+ */
+const ENTRY_SUBPATH = {
+    '@anthropic-ai/claude-agent-sdk': '.',
+    '@anthropic-ai/sdk': '.',
+    '@modelcontextprotocol/sdk': './server',
+    zod: '.',
+};
+const specifierFor = (name) => ENTRY_SUBPATH[name] === '.' ? name : `${name}${ENTRY_SUBPATH[name].slice(1)}`;
+export const AI_RUNTIME_MISSING_MESSAGE = 'AI is not set up yet. Press "Set up AI" in Limn, or run: limn ai install';
+/** Thrown by a loader when no source carries the package. Its message is safe to show. */
+export class AiRuntimeMissingError extends Error {
+    pkg;
+    code = 'AI_RUNTIME_MISSING';
+    constructor(pkg) {
+        super(AI_RUNTIME_MISSING_MESSAGE);
+        this.pkg = pkg;
+        this.name = 'AiRuntimeMissingError';
+    }
+}
+// ---- package location (no exports-map surprises) ----------------------------------------------
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The package's directory as an ESM `import '<spec>'` from `fromDir` would find it: the nearest
+ * `node_modules/<spec>` walking up the ancestors. ⚠ NOT `createRequire(...).resolve.paths()` — that
+ * list also carries NODE_PATH and the global folders (`~/.node_modules`, `<prefix>/lib/node`),
+ * which ESM ignores, so a package found there would be one the real import cannot see. (Under
+ * pnpm/vitest NODE_PATH points into the workspace store, which is how this was found.)
+ */
+function findPackageDir(spec, fromDir) {
+    let dir = resolve(fromDir);
+    for (;;) {
+        const candidate = join(dir, 'node_modules', spec);
+        if (existsSync(join(candidate, 'package.json'))) {
+            try {
+                return realpathSync(candidate);
+            }
+            catch {
+                return candidate;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+const ESM_CONDITIONS = new Set(['node', 'import', 'default']);
+/** Walk one exports target with the ESM conditions, in the package's own key order. */
+function pickTarget(target) {
+    if (typeof target === 'string')
+        return target;
+    if (Array.isArray(target)) {
+        for (const t of target) {
+            const hit = pickTarget(t);
+            if (hit)
+                return hit;
+        }
+        return null;
+    }
+    if (target && typeof target === 'object') {
+        for (const [key, value] of Object.entries(target)) {
+            if (!ESM_CONDITIONS.has(key))
+                continue;
+            const hit = pickTarget(value);
+            if (hit)
+                return hit;
+        }
+    }
+    return null;
+}
+/**
+ * The file an ESM `import '<pkg>'` (or `'<pkg>/<subpath>'`) resolves to, given the package
+ * directory. `subpath` is an exports key: '.' for the root, './server' for a subpath.
+ */
+export function esmEntryOf(pkgDir, subpath = '.') {
+    const pkg = readJson(join(pkgDir, 'package.json'));
+    if (!pkg)
+        return null;
+    const exp = pkg.exports;
+    let rel = null;
+    if (exp !== undefined) {
+        const isSubpathMap = !!exp && typeof exp === 'object' && !Array.isArray(exp) &&
+            Object.keys(exp).some((k) => k.startsWith('.'));
+        if (isSubpathMap)
+            rel = pickTarget(exp[subpath]);
+        else if (subpath === '.')
+            rel = pickTarget(exp);
+    }
+    else if (subpath !== '.') {
+        rel = subpath;
+    }
+    if (subpath === '.') {
+        if (!rel && typeof pkg.module === 'string' && pkg.type === 'module')
+            rel = pkg.module;
+        if (!rel && typeof pkg.main === 'string')
+            rel = pkg.main;
+        if (!rel)
+            rel = 'index.js';
+    }
+    if (!rel)
+        return null;
+    const file = resolve(pkgDir, rel);
+    return existsSync(file) ? file : null;
+}
+function installedVersion(pkgDir) {
+    if (!pkgDir)
+        return null;
+    const v = readJson(join(pkgDir, 'package.json'))?.version;
+    return typeof v === 'string' ? v : null;
+}
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * Build a runtime over one data directory. The app uses the module-level default below; tests
+ * build their own over temp directories.
+ */
+export function createAiRuntime(opts = {}) {
+    const env = opts.env ?? process.env;
+    const dataDir = opts.dataDir ?? resolveDataDir(env);
+    const runtimeDir = join(dataDir, 'ai-runtime');
+    const workspaceFrom = opts.workspaceFrom ?? HERE;
+    // src/ai/runtime.ts → apps/backend; dist/ai/runtime.js → the release root. Both hold the
+    // package.json the pins are read from.
+    const packageRoot = opts.packageRoot ?? resolve(HERE, '..', '..');
+    let workspaceHasSdk = null;
+    const workspaceReady = () => {
+        if (workspaceHasSdk === null) {
+            workspaceHasSdk =
+                findPackageDir(AGENT_SDK, workspaceFrom) !== null &&
+                    findPackageDir('zod', workspaceFrom) !== null;
+        }
+        return workspaceHasSdk;
+    };
+    // ---- pins ----
+    function pins() {
+        const fromManifest = readJson(join(packageRoot, 'package.json'))?.[AI_RUNTIME_MANIFEST_FIELD];
+        const out = {};
+        for (const name of AI_RUNTIME_PACKAGES) {
+            let v = fromManifest && typeof fromManifest === 'object'
+                ? fromManifest[name]
+                : undefined;
+            // A dev checkout has no manifest field: pin to what the workspace itself installed.
+            if (v === undefined)
+                v = installedVersion(findPackageDir(name, workspaceFrom));
+            if (typeof v !== 'string' || !EXACT_VERSION.test(v))
+                return null;
+            out[name] = v;
+        }
+        return out;
+    }
+    /**
+     * 'ready' when every package is installed at its pin; 'stale' when installed at another;
+     * 'no_binary' when the JS is there but the Agent SDK's native `claude` program is not (and no
+     * LIMN_CLAUDE_PATH stands in for it).
+     */
+    function runtimeDirState() {
+        if (!existsSync(join(runtimeDir, 'package.json')))
+            return 'absent';
+        const want = pins();
+        let anyMissing = false;
+        let anyMismatch = false;
+        for (const name of AI_RUNTIME_PACKAGES) {
+            const dir = findPackageDir(name, runtimeDir);
+            const have = installedVersion(dir);
+            if (!dir || !have || !esmEntryOf(dir, ENTRY_SUBPATH[name]))
+                anyMissing = true;
+            else if (want && want[name] !== have)
+                anyMismatch = true;
+        }
+        if (anyMissing)
+            return 'absent';
+        if (!binaryOk(runtimeDir))
+            return 'no_binary';
+        return anyMismatch ? 'stale' : 'ready';
+    }
+    // ⚠ THE AGENT SDK'S NATIVE PROGRAM IS AN OPTIONAL DEPENDENCY (one package per platform), and npm
+    // treats a failed optional dependency as NON-FATAL: a fetch error or a libc/cpu mismatch still
+    // exits 0. An install made with LIMN_CLAUDE_PATH set skips it on purpose (`--omit=optional`), and
+    // that variable can be unset later. Either way the JS loads and every run then fails with
+    // "Claude Code executable not found" — so 'ready' requires the binary, unless the user's own
+    // `claude` is configured right now.
+    function binaryOk(fromDir) {
+        if (env.LIMN_CLAUDE_PATH?.trim())
+            return true;
+        const sdkDir = findPackageDir(AGENT_SDK, fromDir);
+        if (!sdkDir)
+            return false;
+        const exe = process.platform === 'win32' ? 'claude.exe' : 'claude';
+        // The same candidates, in any order, the SDK itself tries (linux: glibc or musl).
+        const base = `${AGENT_SDK}-${process.platform}-${process.arch}`;
+        const names = process.platform === 'linux' ? [base, `${base}-musl`] : [base];
+        return names.some((name) => {
+            const dir = findPackageDir(name, sdkDir);
+            return dir !== null && existsSync(join(dir, exe));
+        });
+    }
+    // ---- status ----
+    let inFlight = null;
+    const listeners = new Set();
+    let lastFailure = null;
+    function status() {
+        if (inFlight)
+            return { runtime: 'installing', runtimeMessage: null };
+        if (workspaceReady())
+            return { runtime: 'ready', runtimeMessage: null };
+        const state = runtimeDirState();
+        if (state === 'ready')
+            return { runtime: 'ready', runtimeMessage: null };
+        if (lastFailure)
+            return { runtime: 'failed', runtimeMessage: lastFailure };
+        if (state === 'no_binary') {
+            return {
+                runtime: 'absent',
+                runtimeMessage: 'The Claude Code program is missing from the AI download. Set up AI again, or set LIMN_CLAUDE_PATH to your own claude.',
+            };
+        }
+        if (state === 'stale') {
+            return {
+                runtime: 'absent',
+                runtimeMessage: 'Limn was updated. Set up AI again to get the matching version.',
+            };
+        }
+        return { runtime: 'absent', runtimeMessage: null };
+    }
+    // ---- loading ----
+    const loaded = new Map();
+    function load(spec) {
+        const hit = loaded.get(spec);
+        if (hit)
+            return hit;
+        const p = (async () => {
+            const order = workspaceReady()
+                ? ['workspace', 'runtime']
+                : ['runtime', 'workspace'];
+            for (const source of order) {
+                if (source === 'workspace') {
+                    // Plain bare specifier: identical to the static imports this module replaced.
+                    const dir = findPackageDir(spec, workspaceFrom);
+                    if (dir && workspaceFrom === HERE)
+                        return (await import(specifierFor(spec)));
+                    const entry = dir ? esmEntryOf(dir, ENTRY_SUBPATH[spec]) : null;
+                    if (entry)
+                        return (await import(pathToFileURL(entry).href));
+                }
+                else if (['ready', 'stale'].includes(runtimeDirState())) {
+                    const dir = findPackageDir(spec, runtimeDir);
+                    const entry = dir ? esmEntryOf(dir, ENTRY_SUBPATH[spec]) : null;
+                    if (entry)
+                        return (await import(pathToFileURL(entry).href));
+                }
+            }
+            throw new AiRuntimeMissingError(spec);
+        })();
+        loaded.set(spec, p);
+        // A miss must not be remembered: the reader may set AI up a minute later.
+        p.catch(() => loaded.delete(spec));
+        return p;
+    }
+    // ---- install ----
+    function emit(p) {
+        for (const l of listeners) {
+            try {
+                l(p);
+            }
+            catch {
+                /* a listener's failure is its own */
+            }
+        }
+    }
+    function resolveNpm() {
+        // Run npm's own JS entry with THIS node, so there is no shell and no PATH guessing on Windows
+        // (where `npm` is a .cmd that cannot be spawned without one).
+        const viaEnv = env.npm_execpath;
+        if (viaEnv && /npm-cli\.c?js$/.test(viaEnv) && existsSync(viaEnv)) {
+            return { command: process.execPath, args: [viaEnv] };
+        }
+        const nodeDir = dirname(process.execPath);
+        for (const candidate of [
+            join(nodeDir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+            join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        ]) {
+            if (existsSync(candidate))
+                return { command: process.execPath, args: [candidate] };
+        }
+        if (process.platform !== 'win32')
+            return { command: 'npm', args: [] };
+        return null;
+    }
+    function install(onProgress, installOpts = {}) {
+        if (onProgress)
+            listeners.add(onProgress);
+        const detach = () => {
+            if (onProgress)
+                listeners.delete(onProgress);
+        };
+        // Single-flight: a second press (or a second tab) joins the running download.
+        if (inFlight)
+            return inFlight.finally(detach);
+        inFlight = runInstall(installOpts).finally(() => {
+            inFlight = null;
+        });
+        return inFlight.finally(detach);
+    }
+    async function runInstall(installOpts) {
+        const failWith = (message) => {
+            lastFailure = message;
+            emit({ phase: 'failed', message });
+            return { ok: false, message };
+        };
+        const want = pins();
+        if (!want) {
+            return failWith('This copy of Limn does not list which AI runtime versions to download. Update Limn and try again.');
+        }
+        const npm = installOpts.npm ?? resolveNpm();
+        if (!npm)
+            return failWith('npm was not found. Install Node.js with npm, then try again.');
+        lastFailure = null;
+        emit({ phase: 'starting', message: 'Starting the one-time download (about 110 MB).' });
+        const staging = `${runtimeDir}.staging-${process.pid}-${Date.now()}`;
+        try {
+            mkdirSync(staging, { recursive: true });
+            writeFileSync(join(staging, 'package.json'), JSON.stringify({
+                name: 'limn-ai-runtime',
+                private: true,
+                description: 'The AI runtime Limn downloads on first use. Safe to delete; Limn can download it again.',
+                dependencies: want,
+            }, null, 2) + '\n');
+        }
+        catch (err) {
+            rmSync(staging, { recursive: true, force: true });
+            return failWith(`Could not write to ${dataDir}: ${err.message}`);
+        }
+        const args = [
+            ...npm.args,
+            'install',
+            '--prefix',
+            staging,
+            '--no-audit',
+            '--no-fund',
+            '--no-update-notifier',
+            // None of the four needs an install script, so none gets to run one.
+            '--ignore-scripts',
+            '--no-package-lock',
+        ];
+        // Using your own `claude`: skip the SDK's bundled ~110 MB binary (its optional dependencies).
+        if (env.LIMN_CLAUDE_PATH?.trim())
+            args.push('--omit=optional');
+        const timeoutMs = installOpts.timeoutMs ?? 10 * 60_000;
+        const tail = [];
+        const exit = await new Promise((done) => {
+            let child;
+            try {
+                child = spawn(npm.command, args, {
+                    cwd: staging,
+                    env: { ...env, npm_config_loglevel: 'http' },
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    shell: false,
+                    windowsHide: true,
+                });
+            }
+            catch (err) {
+                done({ code: null, error: err.message, timedOut: false });
+                return;
+            }
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+            }, timeoutMs);
+            const onData = (buf) => {
+                for (const raw of buf.toString('utf8').split(/\r?\n/)) {
+                    const line = raw.trim();
+                    if (!line)
+                        continue;
+                    tail.push(line);
+                    if (tail.length > 8)
+                        tail.shift();
+                    emit({ phase: 'downloading', message: line.slice(0, 200) });
+                }
+            };
+            child.stdout?.on('data', onData);
+            child.stderr?.on('data', onData);
+            child.on('error', (err) => {
+                clearTimeout(timer);
+                done({
+                    code: null,
+                    error: err.code === 'ENOENT'
+                        ? 'npm was not found. Install Node.js with npm, then try again.'
+                        : err.message,
+                    timedOut: false,
+                });
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                done({ code, error: null, timedOut });
+            });
+        });
+        if (exit.error || exit.timedOut || exit.code !== 0) {
+            rmSync(staging, { recursive: true, force: true });
+            if (exit.error)
+                return failWith(exit.error);
+            if (exit.timedOut) {
+                return failWith(`The download took longer than ${Math.round(timeoutMs / 60_000)} minutes and was stopped. Check your network and try again: limn ai install`);
+            }
+            const last = tail.filter((l) => /err/i.test(l)).slice(-2).join(' ') || tail.slice(-1)[0] || '';
+            return failWith(`The download failed (npm exit code ${exit.code}). Check your network or proxy and try again: limn ai install${last ? `. npm said: ${last.slice(0, 300)}` : ''}`);
+        }
+        emit({ phase: 'verifying', message: 'Checking the download.' });
+        for (const name of AI_RUNTIME_PACKAGES) {
+            const dir = findPackageDir(name, staging);
+            const have = installedVersion(dir);
+            if (!dir || have !== want[name] || !esmEntryOf(dir, ENTRY_SUBPATH[name])) {
+                rmSync(staging, { recursive: true, force: true });
+                return failWith(`The download finished but ${name} ${want[name]} is missing from it. Try again: limn ai install`);
+            }
+        }
+        if (!binaryOk(staging)) {
+            rmSync(staging, { recursive: true, force: true });
+            return failWith(`The download finished but the Claude Code program for ${process.platform}-${process.arch} is missing from it. Try again: limn ai install. Or set LIMN_CLAUDE_PATH to your own claude.`);
+        }
+        // Swap in place: the previous runtime (if any) moves aside first, so a failure here leaves
+        // either the old one or the new one — never half of each.
+        const old = `${runtimeDir}.old-${process.pid}-${Date.now()}`;
+        try {
+            if (existsSync(runtimeDir))
+                renameSync(runtimeDir, old);
+            renameSync(staging, runtimeDir);
+        }
+        catch (err) {
+            if (!existsSync(runtimeDir) && existsSync(old))
+                renameSync(old, runtimeDir);
+            rmSync(staging, { recursive: true, force: true });
+            return failWith(`Could not finish setting up AI in ${runtimeDir}: ${err.message}`);
+        }
+        rmSync(old, { recursive: true, force: true });
+        lastFailure = null;
+        emit({ phase: 'done', message: 'AI is set up.' });
+        return { ok: true };
+    }
+    return { runtimeDir, pins, status, load, install };
+}
+// ---- the app's runtime ----------------------------------------------------------------------
+const runtime = createAiRuntime();
+/** The AI runtime's state, for `/api/me` (`ai.runtime` / `ai.runtimeMessage`). Cheap and sync. */
+export function getAiRuntimeStatus() {
+    return runtime.status();
+}
+/** Download the pinned SDKs into `<dataDir>/ai-runtime`. Single-flight; never throws. */
+export function installAiRuntime(onProgress, opts) {
+    return runtime.install(onProgress, opts);
+}
+/** The exact versions this copy of Limn downloads, or null when it cannot tell. */
+export function aiRuntimePins() {
+    return runtime.pins();
+}
+export const loadAgentSdk = () => runtime.load('@anthropic-ai/claude-agent-sdk');
+export const loadAnthropicSdk = () => runtime.load('@anthropic-ai/sdk');
+export const loadMcpSdk = () => runtime.load('@modelcontextprotocol/sdk');
+export const loadZodModule = () => runtime.load('zod');
+/** zod's `z` namespace, from the SAME install the Agent SDK uses. */
+export const loadZod = async () => (await loadZodModule()).z;
+/**
+ * `LIMN_CLAUDE_PATH` → the Agent SDK's `pathToClaudeCodeExecutable`: run the user's own installed
+ * `claude` instead of the SDK's bundled binary (and `limn ai install` then skips downloading it).
+ * Opt-in only — the bundled binary is version-locked to the SDK; a different `claude` may not be.
+ * Spread into every `query()` options object.
+ */
+export function claudeExecutableOptions(env = process.env) {
+    const raw = env.LIMN_CLAUDE_PATH?.trim();
+    if (!raw)
+        return {};
+    return { pathToClaudeCodeExecutable: isAbsolute(raw) ? raw : resolve(raw) };
+}
+//# sourceMappingURL=runtime.js.map