pyric-tools 0.1.0-alpha.7

package/dist/serve/server.js

@@ -0,0 +1,328 @@
+/**
+ * `pyric dev` static server — the hosting half of the command.
+ *
+ * Bare `node:http` (house style — the bridge does the same; no superstatic
+ * dependency). Serves `hosting.public` from `firebase.json` with the minimal
+ * rewrite the local-dev case needs (`** → /index.html` SPA fallback when
+ * configured), and exposes two seams the `/__pyric/` namespace plugs into
+ * (`namespaceHandler`) and the import-map injection uses (`transformHtml`).
+ *
+ * UX parity targets: the `=== Serving from` banner, the labeled `Local server:`
+ * line, port 3473 default ("FIRE" on a phone keypad) with scan-forward on conflict, and SIGINT →
+ * `Shutting down...`.
+ */
+import { createServer } from 'node:http';
+import { createReadStream, existsSync, statSync } from 'node:fs';
+import { pipeline } from 'node:stream';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+export function consoleServeLogger() {
+    return {
+        info: (m) => console.log(m),
+        note: (m) => console.error(m),
+    };
+}
+export function silentServeLogger() {
+    return { info: () => { }, note: () => { } };
+}
+/** `--json` mode: the whole human banner moves to stderr so stdout carries
+ *  exactly one machine-readable line (the agent contract). */
+export function stderrServeLogger() {
+    return {
+        info: (m) => console.error(m),
+        note: (m) => console.error(m),
+    };
+}
+/**
+ * DNS-rebinding guard. A dev server bound to localhost is reachable by any
+ * webpage whose hostname resolves to 127.0.0.1 (`attacker.com` → A
+ * 127.0.0.1): the victim's browser then treats `http://attacker.com:PORT`
+ * as same-origin to the attacker's page and can read/write our endpoints —
+ * including `/__pyric/state` (auth users + plaintext passwords, and writes).
+ * Vite addresses the same class with `server.allowedHosts`.
+ *
+ * We accept only loopback hostnames + the host the server was bound to +
+ * any `--allowed-host`. A request with NO Host header is allowed (curl /
+ * same-origin fetches omit nothing in practice, but non-browser clients may;
+ * the attack requires a browser sending the attacker's Host).
+ */
+export function isAllowedHost(hostHeader, boundHost, extra = []) {
+    if (!hostHeader)
+        return true; // no Host → not a browser rebinding attack
+    const hostname = hostHeader.replace(/:\d+$/, '').replace(/^\[|\]$/g, '').toLowerCase();
+    const allowed = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0', boundHost.toLowerCase(), ...extra.map((h) => h.toLowerCase())]);
+    return allowed.has(hostname);
+}
+/**
+ * Origin allowlist for WebSocket `upgrade` handshakes. A browser sends an
+ * `Origin` header on WS handshakes carrying the page's origin; a hostile page
+ * that opens a WS to our loopback bridge sends ITS OWN cross-origin Origin,
+ * which we reject — otherwise the page hijacks the agent tool channel
+ * (`registerSandboxPeer` last-wins). We reuse `isAllowedHost`'s allow rule on
+ * the Origin's hostname (loopback names + bound host + `--allowed-host`).
+ *
+ * A missing `Origin` is allowed: the same-origin/non-browser peer (a CLI ws
+ * client, a test) is not the hijack vector, which requires a browser attaching
+ * the attacker's Origin. A malformed Origin is rejected.
+ */
+export function isAllowedOrigin(originHeader, boundHost, extra = []) {
+    if (!originHeader)
+        return true; // no Origin → non-browser client, not a hijack
+    let hostname;
+    try {
+        hostname = new URL(originHeader).hostname; // may be `[::1]` — isAllowedHost strips brackets
+    }
+    catch {
+        return false; // malformed Origin → reject
+    }
+    return isAllowedHost(hostname, boundHost, extra);
+}
+/**
+ * The combined guard for a WS `upgrade` request: BOTH the `Host` header
+ * (DNS-rebinding) AND the `Origin` header (cross-origin hijack) must pass.
+ * `upgrade` is a separate listener from the HTTP `request` event, so the
+ * static server's request-time `isAllowedHost` never runs on it — every
+ * upgrade mount point must call this before `wss.handleUpgrade`.
+ */
+export function isAllowedUpgrade(headers, boundHost, extra = []) {
+    return (isAllowedHost(headers.host, boundHost, extra) &&
+        isAllowedOrigin(headers.origin, boundHost, extra));
+}
+const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.webp': 'image/webp',
+    '.wasm': 'application/wasm',
+    '.txt': 'text/plain; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+};
+export function contentTypeFor(path) {
+    return CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}
+/** Resolve a request path inside `publicDir`, refusing traversal. Returns
+ *  null when the path escapes the root or doesn't exist as a file. */
+export function resolveStaticFile(publicDir, pathname) {
+    const decoded = decodeURIComponent(pathname);
+    const root = resolve(publicDir);
+    const candidate = normalize(join(root, decoded));
+    if (candidate !== root && !candidate.startsWith(root + sep))
+        return null; // traversal
+    let file = candidate;
+    if (existsSync(file) && statSync(file).isDirectory())
+        file = join(file, 'index.html');
+    if (!existsSync(file) || !statSync(file).isFile())
+        return null;
+    return file;
+}
+/**
+ * Stream a file to a response with the read stream's `'error'` event handled.
+ * A bare `createReadStream(file).pipe(res)` leaves the stream's error event
+ * unhandled — an fs error between the exists-check and the read (file swapped
+ * out, EMFILE under fd pressure, EISDIR race) then throws at the event-loop
+ * level and KILLS the whole serve process. Headers are usually already sent
+ * when the stream errors, so the recovery is: log, destroy the response (the
+ * client sees a truncated body), keep the server alive.
+ */
+export function pipeFileToResponse(file, res, onError) {
+    const stream = createReadStream(file);
+    // Read-side failures keep the old contract: log via onError and, when
+    // headers haven't gone out yet, answer 500. (Attached BEFORE pipeline so
+    // it runs ahead of pipeline's own teardown of `res`.)
+    stream.on('error', (err) => {
+        onError?.(err);
+        if (!res.headersSent) {
+            res.writeHead(500, { 'content-type': 'text/plain' }).end('read error');
+        }
+    });
+    // stream.pipeline (not a bare .pipe) so a failure on EITHER side tears both
+    // streams down: a client abort mid-download now destroys the read stream
+    // (closing its fd — the hole .pipe left open), and a mid-stream read
+    // failure destroys the response (the client sees a truncated body), all
+    // without an event-loop-level 'error' escaping.
+    pipeline(stream, res, () => {
+        // Errors on both sides are consumed by the handler above / the teardown
+        // itself; the callback's existence is what keeps the process alive.
+    });
+}
+async function handleRequest(req, res, opts, logger) {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    // DNS-rebinding guard (before ANY handling — protects static files,
+    // init.json/rules schema, and especially /__pyric/state credentials).
+    if (!isAllowedHost(req.headers.host, opts.host ?? 'localhost', opts.allowedHosts)) {
+        logger.note(`  ✖ 403 blocked Host '${req.headers.host}' (DNS-rebinding guard)`);
+        res.writeHead(403, { 'content-type': 'text/plain' }).end(`pyric dev: refused request for Host '${req.headers.host ?? ''}'. ` +
+            'Only localhost is allowed; use --allowed-host to add one.');
+        return;
+    }
+    if (opts.namespaceHandler && url.pathname.startsWith('/__pyric/')) {
+        const handled = await opts.namespaceHandler(req, res, url);
+        if (handled)
+            return;
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { allow: 'GET, HEAD' }).end('method not allowed');
+        return;
+    }
+    let file = resolveStaticFile(opts.publicDir, url.pathname);
+    if (!file && opts.spaRewrite && !extname(url.pathname)) {
+        file = resolveStaticFile(opts.publicDir, '/index.html');
+    }
+    if (!file && url.pathname === '/favicon.ico') {
+        // The browser requests /favicon.ico on every load; without this an app
+        // that ships no favicon logs a 404 in every console. Serve a tiny inline
+        // SVG (a neutral placeholder square — the real mark comes with the logo
+        // work) so consoles stay clean. An on-disk favicon.ico was already
+        // resolved above and wins.
+        res.writeHead(200, { 'content-type': 'image/svg+xml', 'cache-control': 'max-age=3600' });
+        res.end(req.method === 'HEAD'
+            ? undefined
+            : '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><rect x="2" y="2" width="12" height="12" rx="2" fill="#e8e8ee"/></svg>');
+        return;
+    }
+    if (!file) {
+        logger.note(`  ✖ 404 ${req.method} ${url.pathname}`);
+        res.writeHead(404, { 'content-type': 'text/plain' }).end('not found');
+        return;
+    }
+    const type = contentTypeFor(file);
+    logger.note(`  • ${req.method} ${url.pathname}`);
+    if (type.startsWith('text/html') && opts.transformHtml) {
+        const { readFile } = await import('node:fs/promises');
+        const html = opts.transformHtml(await readFile(file, 'utf8'));
+        res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' });
+        res.end(req.method === 'HEAD' ? undefined : html);
+        return;
+    }
+    res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' });
+    if (req.method === 'HEAD') {
+        res.end();
+        return;
+    }
+    pipeFileToResponse(file, res, (e) => logger.note(`  ✖ read failed ${url.pathname}: ${e.message}`));
+}
+/** Listen, scanning forward from `port` on conflict (default 3473 avoids macOS AirPlay, which squats 5000 on
+ *  macOS). Resolves with the bound port. */
+export function listenWithScan(server, host, port, limit, logger) {
+    return new Promise((resolvePort, reject) => {
+        let attempt = port;
+        const tryListen = () => {
+            const onError = (err) => {
+                server.removeListener('error', onError);
+                if (port !== 0 && (err.code === 'EADDRINUSE' || err.code === 'EACCES') && attempt - port < limit) {
+                    logger.note(`  ⚠ port ${attempt} is in use${attempt === 5000 ? ' (macOS AirPlay commonly holds 5000)' : ''} — trying ${attempt + 1}`);
+                    attempt += 1;
+                    tryListen();
+                    return;
+                }
+                reject(err);
+            };
+            server.once('error', onError);
+            server.listen(attempt, host, () => {
+                server.removeListener('error', onError);
+                // Read the BOUND port — `attempt` may be 0 (ephemeral, tests).
+                const addr = server.address();
+                resolvePort(typeof addr === 'object' && addr ? addr.port : attempt);
+            });
+        };
+        tryListen();
+    });
+}
+/**
+ * Loopback families to bind for `host`. The default `localhost` binds BOTH
+ * 127.0.0.1 (IPv4) and ::1 (IPv6) so a client using either reaches the server:
+ * `localhost` resolves to only ONE family, so the other 404s at the socket (the
+ * IPv4/IPv6 loopback trap). An explicit host binds only itself. Loopback
+ * families only — NEVER all-interfaces — so the sandbox stays off the LAN behind
+ * the DNS-rebinding guard.
+ */
+export function loopbackHosts(host) {
+    return host === 'localhost' ? ['127.0.0.1', '::1'] : [host];
+}
+export async function startStaticServer(opts) {
+    const logger = opts.logger ?? consoleServeLogger();
+    const host = opts.host ?? 'localhost';
+    const hosts = loopbackHosts(host);
+    // Track sockets so stop() can sever long-lived connections (SSE,
+    // keep-alive) on runtimes without `closeAllConnections` (bun) — otherwise
+    // `server.close()` waits forever on an open event stream.
+    const sockets = new Set();
+    const newServer = () => {
+        const s = createServer((req, res) => {
+            void handleRequest(req, res, opts, logger).catch((e) => {
+                logger.note(`  ✖ 500 ${req.url}: ${e instanceof Error ? e.message : String(e)}`);
+                if (!res.headersSent)
+                    res.writeHead(500);
+                res.end('internal error');
+            });
+        });
+        s.on('connection', (socket) => {
+            sockets.add(socket);
+            socket.on('close', () => sockets.delete(socket));
+        });
+        return s;
+    };
+    // Primary family: scan forward for a free port.
+    const primary = newServer();
+    const port = await listenWithScan(primary, hosts[0], opts.port ?? 3473, opts.portScanLimit ?? 10, logger);
+    // Remaining loopback families: bind the SAME port, best-effort. A loopback
+    // port free on one family is virtually always free on the other; if not, warn
+    // and keep going (the primary still serves) rather than fail the whole serve.
+    const servers = [primary];
+    for (const h of hosts.slice(1)) {
+        const extra = newServer();
+        try {
+            await new Promise((res2, rej) => {
+                const onErr = (e) => {
+                    extra.removeListener('error', onErr);
+                    rej(e);
+                };
+                extra.once('error', onErr);
+                extra.listen(port, h, () => {
+                    extra.removeListener('error', onErr);
+                    res2();
+                });
+            });
+            servers.push(extra);
+        }
+        catch (e) {
+            logger.note(`  ⚠ could not also bind ${h}:${port} (${e instanceof Error ? e.message : String(e)}) — ${hosts[0]} still serves`);
+        }
+    }
+    const url = `http://${host}:${port}`;
+    return {
+        port,
+        host,
+        url,
+        server: primary,
+        servers,
+        stop: () => new Promise((resolveStop, rejectStop) => {
+            let pending = servers.length;
+            let failed = null;
+            for (const s of servers) {
+                s.close((e) => {
+                    if (e && !failed)
+                        failed = e;
+                    if (--pending === 0)
+                        (failed ? rejectStop(failed) : resolveStop());
+                });
+                // Don't wait on keep-alive/SSE sockets during shutdown. Node has
+                // closeAllConnections; bun doesn't — destroy tracked sockets too.
+                s.closeAllConnections?.();
+            }
+            for (const socket of sockets)
+                socket.destroy();
+        }),
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/serve/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/serve/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAA0D,MAAM,WAAW,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AASnE,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED;8DAC8D;AAC9D,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7B,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;KAC9B,CAAC;AACJ,CAAC;AAsBD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,UAA8B,EAC9B,SAAiB,EACjB,QAAkB,EAAE;IAEpB,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC,CAAC,2CAA2C;IACzE,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACvF,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAC5G,CAAC;IACF,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,YAAgC,EAChC,SAAiB,EACjB,QAAkB,EAAE;IAEpB,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC,CAAC,+CAA+C;IAC/E,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC,iDAAiD;IAC9F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,4BAA4B;IAC5C,CAAC;IACD,OAAO,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA2C,EAC3C,SAAiB,EACjB,QAAkB,EAAE;IAEpB,OAAO,CACL,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC;QAC7C,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,CAClD,CAAC;AACJ,CAAC;AAgBD,MAAM,aAAa,GAA2B;IAC5C,OAAO,EAAE,0BAA0B;IACnC,KAAK,EAAE,gCAAgC;IACvC,MAAM,EAAE,gCAAgC;IACxC,MAAM,EAAE,yBAAyB;IACjC,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,iCAAiC;IACzC,MAAM,EAAE,eAAe;IACvB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,cAAc;IACtB,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,2BAA2B;IACnC,KAAK,EAAE,8BAA8B;IACrC,QAAQ,EAAE,YAAY;IACtB,OAAO,EAAE,WAAW;CACrB,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,0BAA0B,CAAC;AAClF,CAAC;AAED;sEACsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,QAAgB;IACnE,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,IAAI,SAAS,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,YAAY;IACtF,IAAI,IAAI,GAAG,SAAS,CAAC;IACrB,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;QAAE,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACtF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,GAAmB,EACnB,OAA8B;IAE9B,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACtC,sEAAsE;IACtE,yEAAyE;IACzE,sDAAsD;IACtD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;QAChC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;YACrB,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACzE,CAAC;IACH,CAAC,CAAC,CAAC;IACH,4EAA4E;IAC5E,yEAAyE;IACzE,qEAAqE;IACrE,wEAAwE;IACxE,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE;QACzB,wEAAwE;QACxE,oEAAoE;IACtE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,GAAoB,EACpB,GAAmB,EACnB,IAAyB,EACzB,MAAmB;IAEnB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,UAAU,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;IAEjF,oEAAoE;IACpE,sEAAsE;IACtE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAClF,MAAM,CAAC,IAAI,CAAC,yBAAyB,GAAG,CAAC,OAAO,CAAC,IAAI,yBAAyB,CAAC,CAAC;QAChF,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC,GAAG,CACtD,wCAAwC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,KAAK;YACjE,2DAA2D,CAC9D,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,gBAAgB,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAClE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3D,IAAI,OAAO;YAAE,OAAO;IACtB,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAClD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;QACrE,OAAO;IACT,CAAC;IAED,IAAI,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;QAC7C,uEAAuE;QACvE,yEAAyE;QACzE,wEAAwE;QACxE,mEAAmE;QACnE,2BAA2B;QAC3B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,CAAC,CAAC;QACzF,GAAG,CAAC,GAAG,CACL,GAAG,CAAC,MAAM,KAAK,MAAM;YACnB,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,oIAAoI,CACzI,CAAC;QACF,OAAO;IACT,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QACrD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACtE,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEjD,IAAI,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACtD,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9D,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAC;QAC1E,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO;IACT,CAAC;IAED,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAC;IAC1E,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC1B,GAAG,CAAC,GAAG,EAAE,CAAC;QACV,OAAO;IACT,CAAC;IACD,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,GAAG,CAAC,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AACrG,CAAC;AAaD;4CAC4C;AAC5C,MAAM,UAAU,cAAc,CAC5B,MAAsB,EACtB,IAAY,EACZ,IAAY,EACZ,KAAa,EACb,MAAmB;IAEnB,OAAO,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE;QACzC,IAAI,OAAO,GAAG,IAAI,CAAC;QACnB,MAAM,SAAS,GAAG,GAAS,EAAE;YAC3B,MAAM,OAAO,GAAG,CAAC,GAA0B,EAAQ,EAAE;gBACnD,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACxC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,OAAO,GAAG,IAAI,GAAG,KAAK,EAAE,CAAC;oBACjG,MAAM,CAAC,IAAI,CAAC,YAAY,OAAO,aAAa,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC,EAAE,aAAa,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;oBACtI,OAAO,IAAI,CAAC,CAAC;oBACb,SAAS,EAAE,CAAC;oBACZ,OAAO;gBACT,CAAC;gBACD,MAAM,CAAC,GAAG,CAAC,CAAC;YACd,CAAC,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9B,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE;gBAChC,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACxC,+DAA+D;gBAC/D,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC9B,WAAW,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACtE,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QACF,SAAS,EAAE,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAyB;IAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,WAAW,CAAC;IACtC,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAElC,iEAAiE;IACjE,0EAA0E;IAC1E,0DAA0D;IAC1D,MAAM,OAAO,GAAG,IAAI,GAAG,EAA6B,CAAC;IACrD,MAAM,SAAS,GAAG,GAAW,EAAE;QAC7B,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YAClC,KAAK,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;gBACrD,MAAM,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,GAAG,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACjF,IAAI,CAAC,GAAG,CAAC,WAAW;oBAAE,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBACzC,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE;YAC5B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IAEF,gDAAgD;IAChD,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,IAAI,CAAC,aAAa,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;IAE3G,2EAA2E;IAC3E,8EAA8E;IAC9E,8EAA8E;IAC9E,MAAM,OAAO,GAAa,CAAC,OAAO,CAAC,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,OAAO,CAAO,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;gBACpC,MAAM,KAAK,GAAG,CAAC,CAAwB,EAAQ,EAAE;oBAC/C,KAAK,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;oBACrC,GAAG,CAAC,CAAC,CAAC,CAAC;gBACT,CAAC,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBAC3B,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE;oBACzB,KAAK,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;oBACrC,IAAI,EAAE,CAAC;gBACT,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,IAAI,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;QACjI,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC;IACrC,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,GAAG;QACH,MAAM,EAAE,OAAO;QACf,OAAO;QACP,IAAI,EAAE,GAAG,EAAE,CACT,IAAI,OAAO,CAAO,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE;YAC5C,IAAI,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;YAC7B,IAAI,MAAM,GAAiB,IAAI,CAAC;YAChC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACxB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;oBACZ,IAAI,CAAC,IAAI,CAAC,MAAM;wBAAE,MAAM,GAAG,CAAC,CAAC;oBAC7B,IAAI,EAAE,OAAO,KAAK,CAAC;wBAAE,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;gBACrE,CAAC,CAAC,CAAC;gBACH,iEAAiE;gBACjE,kEAAkE;gBAClE,CAAC,CAAC,mBAAmB,EAAE,EAAE,CAAC;YAC5B,CAAC;YACD,KAAK,MAAM,MAAM,IAAI,OAAO;gBAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QACjD,CAAC,CAAC;KACL,CAAC;AACJ,CAAC"}

package/dist/serve/standalone-assets.d.ts

@@ -0,0 +1,66 @@
+/** The shape the compiled standalone entry installs on `globalThis`. */
+export interface EmbeddedAssets {
+    /** The `pyric` version the embedded bundles were built from. */
+    version: string;
+    /** Worker source hash stamped into the page (`<meta name="pyric-worker-v">`). */
+    workerVersion: string;
+    /** Lazy: flat map of SDK filename -> base64 bytes (app.js, worker.js, chunks). */
+    sdk: () => Promise<Record<string, string>>;
+    /** Lazy: Studio UI relpath (posix) -> base64 bytes (index.html, assets/*). */
+    studio: () => Promise<Record<string, string>>;
+    /** Lazy: Playground UI relpath (posix) -> base64 bytes. Optional for older
+     *  compiled binaries; missing means `/__pyric/playground/` is unavailable. */
+    playground?: () => Promise<Record<string, string>>;
+    /** Lazy: docs site relpath (posix) -> base64 bytes (the site-docs `dist/`
+     *  tree: `docs/*`, `_astro/*`, `index.html`, `llms.txt`). Optional for older
+     *  compiled binaries; missing means the Studio Docs tab 404s in standalone. */
+    docs?: () => Promise<Record<string, string>>;
+    /** Lazy: packed npm tarballs of the unpublished workspace packages
+     *  (`pyric.tgz`, `pyric-tools.tgz`) -> base64. Used by `pyric init` to vendor
+     *  them into a scaffolded project so `bun install` resolves them offline
+     *  instead of 404-ing on the registry. Optional so a binary built before this
+     *  existed degrades gracefully. */
+    tarballs?: () => Promise<Record<string, string>>;
+}
+declare global {
+    var __PYRIC_EMBEDDED__: EmbeddedAssets | undefined;
+}
+/** True only inside a `bun build --compile` binary produced by scripts/compile.ts. */
+export declare function isStandalone(): boolean;
+/** The worker content hash baked in at compile time (see serve.ts). */
+export declare function embeddedWorkerVersion(): string;
+/** The `pyric`/`pyric-tools` version baked into this binary (for npm-mode pinning). */
+export declare function embeddedVersion(): string;
+/**
+ * The pyric version for user-facing strings (CLI banner, bridge / MCP server
+ * version). The binary's baked version, or '0.0.0' outside a standalone build.
+ * SAFE: unlike {@link embeddedVersion} it never throws — the single source these
+ * strings derive from instead of hardcoding a literal in each place.
+ */
+export declare function pyricVersion(): string;
+/** Whether this binary carries the vendorable package tarballs (see EmbeddedAssets.tarballs). */
+export declare function hasEmbeddedTarballs(): boolean;
+/**
+ * Vendor the embedded `pyric` + `pyric-tools` tarballs into `<projectDir>/vendor/`
+ * and return the `package.json` dep spec for each (`file:vendor/<name>.tgz`). The
+ * scaffold's `.gitignore` ignores `.pyric/`, so we use `vendor/` to keep the
+ * tarballs committable — a clone then `bun install`s offline. Filenames are
+ * stable (`pyric.tgz`, `pyric-tools.tgz`) regardless of version.
+ */
+export declare function materializeVendorTarballs(projectDir: string): Promise<Record<string, string>>;
+/**
+ * Materialize the embedded SDK + worker bundles to a temp dir and return it as
+ * the `outDir` the serve namespace serves `/__pyric/sdk/*` from. Stand-in for
+ * `bundleSdk()` + `bundleWorker()` in the standalone build.
+ */
+export declare function materializeServeAssets(): Promise<{
+    outDir: string;
+    cached: boolean;
+}>;
+/** Materialize the embedded Studio UI tree to a temp dir for `dev --ui`. */
+export declare function materializeStudioUi(): Promise<string>;
+/** Materialize the embedded Playground UI tree to a temp dir for `dev --ui`. */
+export declare function materializePlaygroundUi(): Promise<string | null>;
+/** Materialize the embedded docs site tree to a temp dir for `dev --ui`. */
+export declare function materializeDocsUi(): Promise<string | null>;
+//# sourceMappingURL=standalone-assets.d.ts.map

package/dist/serve/standalone-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone-assets.d.ts","sourceRoot":"","sources":["../../src/serve/standalone-assets.ts"],"names":[],"mappings":"AAuBA,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,GAAG,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C,8EAA8E;IAC9E,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C;kFAC8E;IAC9E,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;mFAE+E;IAC/E,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C;;;;uCAImC;IACnC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,kBAAkB,EAAE,cAAc,GAAG,SAAS,CAAC;CACpD;AAED,sFAAsF;AACtF,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAUD,uEAAuE;AACvE,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,uFAAuF;AACvF,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,iGAAiG;AACjG,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAejC;AAiBD;;;;GAIG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAQ3F;AAID,4EAA4E;AAC5E,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAO3D;AAID,gFAAgF;AAChF,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQtE;AAID,4EAA4E;AAC5E,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQhE"}

package/dist/serve/standalone-assets.js

@@ -0,0 +1,144 @@
+/**
+ * Standalone-binary asset bridge.
+ *
+ * In a `bun build --compile` binary, `pyric dev` cannot run its esbuild SDK
+ * bundler: esbuild's native helper and the on-disk `pyric` dist it scans both
+ * live outside the embedded `/$bunfs` filesystem. The bundle is deterministic,
+ * though — a pure function of pyric-tools' wrapper entries and the `pyric`
+ * version baked into pyric-tools — so the compile step (`scripts/compile.ts`)
+ * runs the bundler ONCE on the build host and embeds the output (the SDK +
+ * worker bundles and the Studio UI) into the binary via
+ * `globalThis.__PYRIC_EMBEDDED__`. At runtime we materialize those bytes to a
+ * real temp dir so the existing serve namespace — which `createReadStream`s
+ * from a directory — works unchanged.
+ *
+ * The npm build never sets the global. `isStandalone()` is false there and
+ * `serve` keeps its runtime esbuild path untouched. The heavy base64 blobs are
+ * exposed behind lazy loaders so non-`serve` commands (rules:lint, deploy, …)
+ * never pay to parse them.
+ */
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** True only inside a `bun build --compile` binary produced by scripts/compile.ts. */
+export function isStandalone() {
+    return typeof globalThis.__PYRIC_EMBEDDED__ !== 'undefined';
+}
+function embedded() {
+    const e = globalThis.__PYRIC_EMBEDDED__;
+    if (!e) {
+        throw new Error('pyric: embedded serve assets are unavailable (not a standalone build)');
+    }
+    return e;
+}
+/** The worker content hash baked in at compile time (see serve.ts). */
+export function embeddedWorkerVersion() {
+    return embedded().workerVersion;
+}
+/** The `pyric`/`pyric-tools` version baked into this binary (for npm-mode pinning). */
+export function embeddedVersion() {
+    return embedded().version;
+}
+/**
+ * The pyric version for user-facing strings (CLI banner, bridge / MCP server
+ * version). The binary's baked version, or '0.0.0' outside a standalone build.
+ * SAFE: unlike {@link embeddedVersion} it never throws — the single source these
+ * strings derive from instead of hardcoding a literal in each place.
+ */
+export function pyricVersion() {
+    return globalThis.__PYRIC_EMBEDDED__?.version ?? '0.0.0';
+}
+/** Whether this binary carries the vendorable package tarballs (see EmbeddedAssets.tarballs). */
+export function hasEmbeddedTarballs() {
+    return typeof globalThis.__PYRIC_EMBEDDED__?.tarballs === 'function';
+}
+/**
+ * Vendor the embedded `pyric` + `pyric-tools` tarballs into `<projectDir>/vendor/`
+ * and return the `package.json` dep spec for each (`file:vendor/<name>.tgz`). The
+ * scaffold's `.gitignore` ignores `.pyric/`, so we use `vendor/` to keep the
+ * tarballs committable — a clone then `bun install`s offline. Filenames are
+ * stable (`pyric.tgz`, `pyric-tools.tgz`) regardless of version.
+ */
+export async function materializeVendorTarballs(projectDir) {
+    const e = embedded();
+    if (!e.tarballs) {
+        throw new Error('pyric: this binary has no embedded package tarballs to vendor');
+    }
+    const vendorDir = join(projectDir, 'vendor');
+    mkdirSync(vendorDir, { recursive: true });
+    const specs = {};
+    for (const [filename, b64] of Object.entries(await e.tarballs())) {
+        writeFileSync(join(vendorDir, filename), Buffer.from(b64, 'base64'));
+        // `pyric.tgz` -> package name `pyric`; `pyric-tools.tgz` -> `pyric-tools`.
+        const pkg = filename.replace(/\.tgz$/, '');
+        specs[pkg] = `file:vendor/${filename}`;
+    }
+    return specs;
+}
+/** Write a base64 file map under `root`, preserving nested relpaths, idempotently. */
+function materialize(root, files, version) {
+    const marker = join(root, '.complete');
+    if (existsSync(marker))
+        return;
+    mkdirSync(root, { recursive: true });
+    for (const [rel, b64] of Object.entries(files)) {
+        const dest = join(root, rel);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, Buffer.from(b64, 'base64'));
+    }
+    writeFileSync(marker, version);
+}
+let sdkDirOnce = null;
+/**
+ * Materialize the embedded SDK + worker bundles to a temp dir and return it as
+ * the `outDir` the serve namespace serves `/__pyric/sdk/*` from. Stand-in for
+ * `bundleSdk()` + `bundleWorker()` in the standalone build.
+ */
+export async function materializeServeAssets() {
+    if (sdkDirOnce)
+        return { outDir: sdkDirOnce, cached: true };
+    const e = embedded();
+    const outDir = join(tmpdir(), `pyric-serve-${e.version}`, 'sdk');
+    const cached = existsSync(join(outDir, '.complete'));
+    materialize(outDir, await e.sdk(), e.version);
+    sdkDirOnce = outDir;
+    return { outDir, cached };
+}
+let studioDirOnce = null;
+/** Materialize the embedded Studio UI tree to a temp dir for `dev --ui`. */
+export async function materializeStudioUi() {
+    if (studioDirOnce)
+        return studioDirOnce;
+    const e = embedded();
+    const dir = join(tmpdir(), `pyric-serve-${e.version}`, 'studio-ui');
+    materialize(dir, await e.studio(), e.version);
+    studioDirOnce = dir;
+    return dir;
+}
+let playgroundDirOnce = null;
+/** Materialize the embedded Playground UI tree to a temp dir for `dev --ui`. */
+export async function materializePlaygroundUi() {
+    if (playgroundDirOnce)
+        return playgroundDirOnce;
+    const e = embedded();
+    if (!e.playground)
+        return null;
+    const dir = join(tmpdir(), `pyric-serve-${e.version}`, 'playground-ui');
+    materialize(dir, await e.playground(), e.version);
+    playgroundDirOnce = dir;
+    return dir;
+}
+let docsDirOnce = null;
+/** Materialize the embedded docs site tree to a temp dir for `dev --ui`. */
+export async function materializeDocsUi() {
+    if (docsDirOnce)
+        return docsDirOnce;
+    const e = embedded();
+    if (!e.docs)
+        return null;
+    const dir = join(tmpdir(), `pyric-serve-${e.version}`, 'docs-ui');
+    materialize(dir, await e.docs(), e.version);
+    docsDirOnce = dir;
+    return dir;
+}
+//# sourceMappingURL=standalone-assets.js.map

package/dist/serve/standalone-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone-assets.js","sourceRoot":"","sources":["../../src/serve/standalone-assets.ts"],"names":[],"mappings":"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"}

package/dist/serve/state-store.d.ts

@@ -0,0 +1,45 @@
+import type { sandbox as authSandbox } from 'pyric/auth';
+export type ExportedUsers = ReturnType<typeof authSandbox.exportUsers>;
+export declare const STATE_FILE_VERSION: 1;
+/** Expected inner version of the sandbox persistence controller's blob.
+ *  MIRRORS pyric's `serialize.ts` `SCHEMA_VERSION` — bump in lockstep when
+ *  pyric does (they ship together). Drift-risk noted: not importable
+ *  (pyric doesn't export it), so a check, not a re-use. */
+export declare const EXPECTED_CONTROLLER_BLOB_VERSION = 1;
+export interface PyricStateFile {
+    version: typeof STATE_FILE_VERSION;
+    /** The sandbox persistence controller's blob, verbatim. Null = never flushed. */
+    firestore: unknown | null;
+    auth: {
+        users: ExportedUsers;
+    } | null;
+}
+export type StateSection = 'firestore' | 'auth';
+export declare class StateFileError extends Error {
+    constructor(message: string);
+}
+export interface StateStore {
+    /** The project directory this store persists for (for the
+     *  promote-the-wrong-project guard). */
+    projectDir: string;
+    /** Absolute path of the state file. */
+    path: string;
+    /** Absolute path of the one-deep recovery backup (`state.json.bak`). */
+    backupPath: string;
+    /** Parsed envelope, or null when the file doesn't exist. Throws
+     *  {@link StateFileError} on corrupt JSON or version mismatch —
+     *  fail fast over silent data loss. */
+    load(): PyricStateFile | null;
+    readSection(section: StateSection): unknown | null;
+    /** Read-modify-write the envelope; atomic tmp+rename. A firestore write
+     *  that would collapse a non-empty doc set to empty first preserves the
+     *  prior file as `.bak` (pre-mortem #2). */
+    writeSection(section: StateSection, value: unknown): void;
+    exists(): boolean;
+}
+export declare const STATE_RELATIVE_PATH: string;
+export declare function createStateStore(projectDir: string): StateStore;
+/** Doc count inside a controller firestore blob (`{…, firestore: {path:
+ *  fields}}`), 0 for null/empty/malformed. */
+export declare function firestoreDocCount(section: unknown): number;
+//# sourceMappingURL=state-store.d.ts.map

package/dist/serve/state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store.d.ts","sourceRoot":"","sources":["../../src/serve/state-store.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,WAAW,CAAC,CAAC;AAEvE,eAAO,MAAM,kBAAkB,EAAG,CAAU,CAAC;AAE7C;;;2DAG2D;AAC3D,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,kBAAkB,CAAC;IACnC,iFAAiF;IACjF,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE;QAAE,KAAK,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,MAAM,CAAC;AAEhD,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,UAAU;IACzB;4CACwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB;;2CAEuC;IACvC,IAAI,IAAI,cAAc,GAAG,IAAI,CAAC;IAC9B,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,GAAG,IAAI,CAAC;IACnD;;gDAE4C;IAC5C,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1D,MAAM,IAAI,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,mBAAmB,QAAwC,CAAC;AAEzE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAiF/D;AAED;8CAC8C;AAC9C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAG1D"}