@maudecode/talaria-web 0.0.0

package/dist/sidecar/client.js

@@ -0,0 +1,252 @@
+/**
+ * Sidecar client: spawns `python -m talaria_sidecar` on the Agent venv, speaks
+ * newline-delimited JSON-RPC 2.0 over its stdio, and restarts it on crash
+ * (docs/architecture/sidecar-rpc.md).
+ *
+ * The server never imports Agent code; every Agent-backed capability is one
+ * `call()` here. While the sidecar is absent, restarting, stale, or
+ * incompatible, calls fail closed with a `SidecarError` whose `condition` the
+ * HTTP layer forwards as the 503 `condition` field.
+ */
+import { delimiter } from 'node:path';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { RPC_ERROR_CODES, RpcIncomingSchema, SIDECAR_METHODS, SIDECAR_RPC_VERSION, } from '@maudecode/talaria-web-contracts';
+export class SidecarError extends Error {
+    code;
+    condition;
+    data;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'SidecarError';
+        this.code = opts.code ?? RPC_ERROR_CODES.application;
+        this.condition = opts.condition;
+        this.data = opts.data ?? {};
+    }
+    static fromRpc(error) {
+        const condition = error.data?.condition ?? (error.code === RPC_ERROR_CODES.cancelled ? 'cancelled' : 'sidecar_error');
+        return new SidecarError(error.message, { code: error.code, condition, data: error.data ?? {} });
+    }
+}
+const DEFAULT_BACKOFF = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
+/** The configured environment (credentials, proxies, CA bundles) flows through as it did in-process in Python; the sidecar identity keys win. */
+export function sidecarSpawnEnv(opts) {
+    const env = typeof opts.env === 'function' ? opts.env() : opts.env;
+    return {
+        PATH: process.env.PATH ?? '',
+        HOME: process.env.HOME ?? '',
+        ...env,
+        HERMES_HOME: opts.hermesHome,
+        TALARIA_SIDECAR_AGENT_DIR: opts.agentDir,
+        PYTHONPATH: env?.PYTHONPATH ? `${opts.sidecarDir}${delimiter}${env.PYTHONPATH}` : opts.sidecarDir,
+        PYTHONUNBUFFERED: '1',
+    };
+}
+export class SidecarClient {
+    opts;
+    status = 'stopped';
+    describe = null;
+    child = null;
+    nextId = 1;
+    pending = new Map();
+    restartAttempt = 0;
+    restartTimer = null;
+    closed = false;
+    log;
+    constructor(opts) {
+        this.opts = opts;
+        this.log = opts.log ?? ((line) => { process.stderr.write(line + '\n'); });
+    }
+    /** Spawn and handshake. Resolves with the handshake payload; rejects only on spawn failure. */
+    async start() {
+        if (this.closed)
+            throw new SidecarError('sidecar client closed', { condition: 'sidecar_unavailable' });
+        this.status = 'starting';
+        const [command, ...args] = this.opts.command ?? [this.opts.python, '-m', 'talaria_sidecar'];
+        const child = spawn(command ?? this.opts.python, args, {
+            cwd: this.opts.sidecarDir,
+            env: sidecarSpawnEnv(this.opts),
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child = child;
+        if (!child.stdout || !child.stderr)
+            throw new SidecarError('sidecar stdio pipes unavailable', { condition: 'sidecar_unavailable' });
+        const stdout = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        stdout.on('line', (line) => { this.onLine(line); });
+        const stderr = createInterface({ input: child.stderr, crlfDelay: Infinity });
+        stderr.on('line', (line) => { this.log(`[sidecar] ${line}`); });
+        child.on('exit', (code, signal) => { this.onExit(child, code, signal); });
+        // A spawn failure (missing executable, interpreter mid-replacement) emits `error` and `close` but no `exit`:
+        // recover through the same path so a restart is scheduled; `onExit` ignores a child it already retired.
+        child.on('error', (error) => { this.log(`[sidecar] spawn error: ${error.message}`); this.onExit(child, null, null); });
+        // A request or cancel written to a child that just died surfaces as EPIPE on stdin; the exit handler owns recovery.
+        child.stdin?.on('error', (error) => { this.log(`[sidecar] stdin write failed: ${error.message}`); });
+        try {
+            const describe = await this.rawCall('runtime.handshake', { rpc_version: SIDECAR_RPC_VERSION }, { timeoutMs: this.opts.handshakeTimeoutMs ?? 60_000 });
+            this.describe = describe;
+            this.status = describe.compatible && !describe.stale ? 'ready' : 'incompatible';
+            this.restartAttempt = 0;
+            return describe;
+        }
+        catch (error) {
+            // A decoded version mismatch is final: the sidecar exits 3 on its own and restarting cannot help.
+            if (error instanceof SidecarError && error.condition === 'sidecar_rpc_version_mismatch') {
+                this.status = 'incompatible';
+                throw error;
+            }
+            // `incompatible` is reserved for a decoded handshake that says so (or the version-mismatch exit). A handshake
+            // that hangs, fails to parse, or dies is operational: kill a still-running child so its exit schedules a restart.
+            if (this.child === child && !this.closed) {
+                this.log(`[sidecar] handshake failed: ${error.message}; restarting`);
+                this.status = 'restarting';
+                child.kill('SIGKILL');
+            }
+            throw error;
+        }
+    }
+    onLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            this.log(`[sidecar] non-JSON stdout line: ${line.slice(0, 200)}`);
+            return;
+        }
+        const incoming = RpcIncomingSchema.safeParse(parsed);
+        if (!incoming.success) {
+            this.log(`[sidecar] invalid message: ${line.slice(0, 200)}`);
+            return;
+        }
+        const message = incoming.data;
+        if ('method' in message) {
+            if (message.method === 'stream') {
+                const frame = message.params;
+                this.pending.get(frame.id)?.onStream?.({ seq: frame.seq, event: frame.event, data: frame.data });
+            }
+            return;
+        }
+        if (message.id === null)
+            return;
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        this.pending.delete(message.id);
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        if ('error' in message)
+            pending.reject(SidecarError.fromRpc(message.error));
+        else
+            pending.resolve(message.result);
+    }
+    onExit(child, code, signal) {
+        if (this.child !== child)
+            return;
+        this.child = null;
+        this.log(`[sidecar] exited code=${code} signal=${signal ?? ''}`);
+        const error = new SidecarError('sidecar exited', { condition: 'sidecar_unavailable', data: { code, signal } });
+        for (const [id, pending] of this.pending) {
+            this.pending.delete(id);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        if (this.closed) {
+            this.status = 'stopped';
+            return;
+        }
+        if (code === 3 || this.status === 'incompatible') {
+            // Version mismatch: restarting cannot help.
+            this.status = 'incompatible';
+            return;
+        }
+        this.scheduleRestart();
+    }
+    scheduleRestart() {
+        this.status = 'restarting';
+        const schedule = this.opts.backoffMs ?? DEFAULT_BACKOFF;
+        const delay = schedule[Math.min(this.restartAttempt, schedule.length - 1)] ?? 30_000;
+        this.restartAttempt += 1;
+        this.restartTimer = setTimeout(() => {
+            this.restartTimer = null;
+            this.start().catch((error) => { this.log(`[sidecar] restart failed: ${String(error)}`); });
+        }, delay);
+        this.restartTimer.unref();
+    }
+    /** Typed call; fails closed with `sidecar_unavailable` unless the sidecar is ready. */
+    call(method, params, opts = {}) {
+        if (this.status !== 'ready' && !method.startsWith('runtime.') && method !== 'rpc.methods') {
+            const condition = this.status === 'incompatible' ? (this.describe?.stale ? 'agent_runtime_stale' : 'agent_incompatible') : 'sidecar_unavailable';
+            return Promise.reject(new SidecarError(`sidecar not ready (${this.status})`, { condition }));
+        }
+        return this.rawCall(method, params, opts);
+    }
+    async rawCall(method, params, opts = {}) {
+        // A signal that already fired never reaches the sidecar: the abort listener below would otherwise be installed
+        // after the fact and the call (e.g. a `chat.start` behind an earlier await) would run to completion uncancelled.
+        if (opts.signal?.aborted)
+            throw new SidecarError(`sidecar call ${method} cancelled before it was sent`, { condition: 'cancelled' });
+        const stdin = this.child?.stdin;
+        if (!stdin?.writable)
+            throw new SidecarError('sidecar process is not running', { condition: 'sidecar_unavailable' });
+        const schema = SIDECAR_METHODS[method];
+        const id = this.nextId++;
+        const request = { jsonrpc: '2.0', id, method, params: schema.params.parse(params) };
+        const raw = await new Promise((resolve, reject) => {
+            const pending = { method, resolve, reject, onStream: opts.onStream };
+            if (opts.timeoutMs !== 0) {
+                pending.timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    this.sendCancel(id);
+                    reject(new SidecarError(`sidecar call ${method} timed out`, { condition: 'sidecar_timeout' }));
+                }, opts.timeoutMs ?? 120_000);
+                pending.timer.unref();
+            }
+            this.pending.set(id, pending);
+            opts.signal?.addEventListener('abort', () => { this.sendCancel(id); }, { once: true });
+            stdin.write(JSON.stringify(request) + '\n', (error) => {
+                if (error) {
+                    this.pending.delete(id);
+                    if (pending.timer)
+                        clearTimeout(pending.timer);
+                    reject(new SidecarError(`sidecar write failed: ${error.message}`, { condition: 'sidecar_unavailable' }));
+                }
+            });
+        });
+        return schema.result.parse(raw);
+    }
+    sendCancel(id) {
+        const child = this.child;
+        if (!child?.stdin?.writable)
+            return;
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: this.nextId++, method: 'rpc.cancel', params: { id } }) + '\n');
+    }
+    recycle(reason) {
+        const child = this.child;
+        if (!child || this.closed)
+            return;
+        this.log(`[sidecar] recycling: ${reason}`);
+        this.status = 'restarting';
+        child.kill('SIGKILL');
+    }
+    async close() {
+        this.closed = true;
+        if (this.restartTimer) {
+            clearTimeout(this.restartTimer);
+            this.restartTimer = null;
+        }
+        const child = this.child;
+        if (!child) {
+            this.status = 'stopped';
+            return;
+        }
+        await new Promise((resolve) => {
+            const done = () => { resolve(); };
+            child.once('exit', done);
+            child.stdin?.end();
+            setTimeout(() => { child.kill('SIGKILL'); done(); }, 5_000).unref();
+        });
+        this.status = 'stopped';
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/sidecar/client.js.map

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

package/dist/sidecar/discover.d.ts

@@ -0,0 +1,22 @@
+import { SidecarClient } from './client.js';
+export interface DiscoverOptions {
+    env: Record<string, string | undefined>;
+    hermesHome: string;
+    webRoot: string;
+    home: string;
+}
+export declare function agentCandidates(opts: DiscoverOptions): string[];
+export declare function discoverAgentDir(opts: DiscoverOptions): string | null;
+export declare function which(name: string, env: Record<string, string | undefined>): string | null;
+/** Python `_agent_dir_from_hermes_cli`: read the `hermes` launcher and walk up from any absolute path it references. */
+export declare function agentDirFromHermesCli(env: Record<string, string | undefined>): string | null;
+/** Python `discover_agent_dir` with the launcher fallbacks (`run_agent.py` is the marker). */
+export declare function discoverAgentDirForLaunch(opts: DiscoverOptions): string | null;
+export declare function discoverAgentPython(env: Record<string, string | undefined>, agentDir: string | null): string | null;
+export interface LaunchOptions extends DiscoverOptions {
+    log: (line: string) => void;
+}
+/** `HERMES_WEBUI_SIDECAR_COMMAND`: a JSON array (or whitespace-separated command) that replaces `<python> -m talaria_sidecar`, e.g. the fixture replay sidecar. */
+export declare function scriptedSidecarCommand(env: Record<string, string | undefined>): string[] | null;
+/** Discover the Agent and spawn the sidecar on its venv; null when no Agent is installed (chat answers 503 `sidecar_unavailable`). */
+export declare function launchSidecar(opts: LaunchOptions): SidecarClient | null;

package/dist/sidecar/discover.js

@@ -0,0 +1,146 @@
+/**
+ * Hermes Agent discovery for the sidecar spawn (Python `bootstrap.py` rules):
+ * `HERMES_WEBUI_AGENT_DIR`, `$HERMES_HOME/hermes-agent`, a sibling checkout of
+ * this repository, `~/hermes-agent`, `/opt/hermes`, `/usr/local/lib/hermes-agent`;
+ * the interpreter is `HERMES_WEBUI_PYTHON` or the Agent's `venv`/`.venv`.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { SidecarClient } from './client.js';
+function isAgentCheckout(dir) {
+    try {
+        if (!statSync(dir).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return ['run_agent.py', 'hermes_cli', 'agent'].some((marker) => existsSync(join(dir, marker)));
+}
+export function agentCandidates(opts) {
+    const explicit = (opts.env.HERMES_WEBUI_AGENT_DIR ?? '').trim().replace(/^~(?=$|\/)/, opts.home);
+    return [
+        explicit,
+        join(opts.hermesHome, 'hermes-agent'),
+        resolve(opts.webRoot, '..', 'hermes-agent'),
+        join(opts.home, 'hermes-agent'),
+        '/opt/hermes',
+        '/usr/local/lib/hermes-agent',
+    ].filter(Boolean).map((p) => resolve(p));
+}
+export function discoverAgentDir(opts) {
+    for (const candidate of agentCandidates(opts))
+        if (isAgentCheckout(candidate))
+            return candidate;
+    return null;
+}
+function walkUpForRunAgent(start) {
+    let dir = dirname(start);
+    for (;;) {
+        if (existsSync(join(dir, 'run_agent.py')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function which(name, env) {
+    for (const dir of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
+        const candidate = join(dir, name);
+        try {
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch { /* next */ }
+    }
+    return null;
+}
+/** Python `_agent_dir_from_hermes_cli`: read the `hermes` launcher and walk up from any absolute path it references. */
+export function agentDirFromHermesCli(env) {
+    const launcher = which('hermes', env);
+    if (!launcher)
+        return null;
+    let head;
+    try {
+        head = readFileSync(launcher, { encoding: 'utf8', flag: 'r' }).split('\n').slice(0, 20).join('\n');
+    }
+    catch {
+        return null;
+    }
+    if (!head.startsWith('#!'))
+        return null;
+    const lines = head.split('\n');
+    const candidates = [];
+    const interp = (lines[0] ?? '').slice(2).trim().split(/\s+/)[0] ?? '';
+    if (interp.startsWith('/') && !interp.endsWith('/env'))
+        candidates.push(interp);
+    for (const line of lines.slice(1))
+        for (const m of line.matchAll(/['"](\/[^'"]+)['"]/g))
+            candidates.push(m[1] ?? '');
+    for (const c of candidates) {
+        const found = c ? walkUpForRunAgent(c) : null;
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Python `discover_agent_dir` with the launcher fallbacks (`run_agent.py` is the marker). */
+export function discoverAgentDirForLaunch(opts) {
+    for (const candidate of [...agentCandidates(opts), join(opts.home, '.hermes', 'hermes-agent')])
+        if (existsSync(join(candidate, 'run_agent.py')))
+            return resolve(candidate);
+    return agentDirFromHermesCli(opts.env);
+}
+export function discoverAgentPython(env, agentDir) {
+    const explicit = (env.HERMES_WEBUI_PYTHON ?? '').trim();
+    if (explicit)
+        return explicit;
+    if (!agentDir)
+        return null;
+    for (const venv of ['venv', '.venv']) {
+        for (const bin of [join(agentDir, venv, 'bin', 'python'), join(agentDir, venv, 'Scripts', 'python.exe')])
+            if (existsSync(bin))
+                return bin;
+    }
+    return null;
+}
+/** `HERMES_WEBUI_SIDECAR_COMMAND`: a JSON array (or whitespace-separated command) that replaces `<python> -m talaria_sidecar`, e.g. the fixture replay sidecar. */
+export function scriptedSidecarCommand(env) {
+    const raw = (env.HERMES_WEBUI_SIDECAR_COMMAND ?? '').trim();
+    if (!raw)
+        return null;
+    if (raw.startsWith('[')) {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed) || !parsed.length || !parsed.every((v) => typeof v === 'string'))
+            throw new Error('HERMES_WEBUI_SIDECAR_COMMAND must be a JSON array of strings');
+        return parsed;
+    }
+    return raw.split(/\s+/);
+}
+/** The configured process environment (shell plus launcher-loaded `.env` files) as the Agent saw it in-process in Python. */
+function stringEnv(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Discover the Agent and spawn the sidecar on its venv; null when no Agent is installed (chat answers 503 `sidecar_unavailable`). */
+export function launchSidecar(opts) {
+    const scripted = scriptedSidecarCommand(opts.env);
+    if (scripted) {
+        opts.log(`[sidecar] starting scripted sidecar ${scripted.join(' ')}`);
+        return new SidecarClient({ python: scripted[0] ?? '', command: scripted, agentDir: discoverAgentDirForLaunch(opts) ?? '', sidecarDir: join(opts.webRoot, 'sidecar'), hermesHome: opts.hermesHome, env: () => stringEnv(opts.env), log: opts.log });
+    }
+    const agentDir = discoverAgentDirForLaunch(opts);
+    const python = discoverAgentPython(opts.env, agentDir);
+    if (!agentDir || !python) {
+        opts.log(`[sidecar] Hermes Agent not found (looked in ${agentCandidates(opts).join(', ')}); set HERMES_WEBUI_AGENT_DIR to enable chat`);
+        return null;
+    }
+    const client = new SidecarClient({ python, agentDir, sidecarDir: join(opts.webRoot, 'sidecar'), hermesHome: opts.hermesHome, env: () => stringEnv(opts.env), log: opts.log });
+    opts.log(`[sidecar] starting on ${python} (agent ${agentDir})`);
+    return client;
+}
+//# sourceMappingURL=discover.js.map

package/dist/sidecar/discover.js.map

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

package/dist/sidecar/fake.d.ts

@@ -0,0 +1,37 @@
+import { type RuntimeDescribe, type SidecarMethodName, type SidecarParams, type SidecarResult } from '@maudecode/talaria-web-contracts';
+import { type CallOptions, type SidecarLike, type SidecarStatus, type StreamFrame } from './client.js';
+type Responder<M extends SidecarMethodName> = (params: SidecarParams<M>, emit: (frame: Omit<StreamFrame, 'seq'>) => void, opts: CallOptions) => SidecarResult<M> | Promise<SidecarResult<M>>;
+export interface FakeSidecarOptions {
+    fixturesDir?: string;
+    status?: SidecarStatus;
+}
+export interface FixtureEntry {
+    params: unknown;
+    result: unknown;
+    stream?: {
+        event: string;
+        data: unknown;
+    }[];
+}
+/** Recorded sidecar responses: one JSON file per namespace mapping method to recorded calls (sidecar/scripts/record-fixtures.py). */
+export declare function loadSidecarFixtures(dir?: string): Map<string, FixtureEntry[]>;
+export declare class FakeSidecar implements SidecarLike {
+    status: SidecarStatus;
+    describe: RuntimeDescribe | null;
+    readonly calls: {
+        method: SidecarMethodName;
+        params: unknown;
+    }[];
+    private readonly responders;
+    private readonly fixtures;
+    constructor(opts?: FakeSidecarOptions);
+    /** The responder currently installed for `method`, so a test can restore it. */
+    responderFor<M extends SidecarMethodName>(method: M): Responder<M> | undefined;
+    /** Override one method for the rest of the test. */
+    respond<M extends SidecarMethodName>(method: M, responder: Responder<M>): void;
+    call<M extends SidecarMethodName>(method: M, params: SidecarParams<M>, opts?: CallOptions): Promise<SidecarResult<M>>;
+    close(): Promise<void>;
+    readonly recycled: string[];
+    recycle(reason: string): void;
+}
+export {};

package/dist/sidecar/fake.js

@@ -0,0 +1,79 @@
+/**
+ * In-process fake sidecar for unit tests. Answers each method from the
+ * contracts fixtures (or a per-test override) and validates params and
+ * results with the same schemas the real client uses, so a test can never
+ * pass against a shape the real sidecar would reject.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { SIDECAR_METHODS } from '@maudecode/talaria-web-contracts';
+import { SidecarError } from './client.js';
+/** Recorded sidecar responses: one JSON file per namespace mapping method to recorded calls (sidecar/scripts/record-fixtures.py). */
+export function loadSidecarFixtures(dir = resolve(import.meta.dirname, '../../../contracts/fixtures/sidecar')) {
+    const out = new Map();
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.json'))
+            continue;
+        const byMethod = JSON.parse(readFileSync(resolve(dir, file), 'utf8'));
+        for (const [method, entries] of Object.entries(byMethod))
+            out.set(method, entries);
+    }
+    return out;
+}
+export class FakeSidecar {
+    status;
+    describe = null;
+    calls = [];
+    responders = new Map();
+    fixtures = new Map();
+    constructor(opts = {}) {
+        this.status = opts.status ?? 'ready';
+        for (const [method, entries] of loadSidecarFixtures(opts.fixturesDir))
+            this.fixtures.set(method, entries);
+        const handshake = this.fixtures.get('runtime.handshake')?.[0];
+        if (handshake)
+            this.describe = SIDECAR_METHODS['runtime.handshake'].result.parse(handshake.result);
+    }
+    /** The responder currently installed for `method`, so a test can restore it. */
+    responderFor(method) {
+        return this.responders.get(method);
+    }
+    /** Override one method for the rest of the test. */
+    respond(method, responder) {
+        this.responders.set(method, responder);
+    }
+    async call(method, params, opts = {}) {
+        const schema = SIDECAR_METHODS[method];
+        const parsedParams = schema.params.parse(params);
+        this.calls.push({ method, params: parsedParams });
+        if (this.status !== 'ready' && !method.startsWith('runtime.')) {
+            throw new SidecarError(`sidecar not ready (${this.status})`, { condition: 'sidecar_unavailable' });
+        }
+        let seq = 0;
+        const emit = (frame) => { opts.onStream?.({ ...frame, seq: ++seq }); };
+        const responder = this.responders.get(method);
+        let raw;
+        if (responder) {
+            raw = await responder(parsedParams, emit, opts);
+        }
+        else {
+            const fixture = this.fixtures.get(method)?.[0];
+            if (!fixture)
+                throw new SidecarError(`no fixture or responder for ${method}`, { condition: 'sidecar_error' });
+            for (const frame of fixture.stream ?? [])
+                emit(frame);
+            raw = fixture.result;
+        }
+        return schema.result.parse(raw);
+    }
+    close() {
+        this.status = 'stopped';
+        return Promise.resolve();
+    }
+    recycled = [];
+    recycle(reason) {
+        this.recycled.push(reason);
+        this.status = 'restarting';
+    }
+}
+//# sourceMappingURL=fake.js.map

package/dist/sidecar/fake.js.map

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

package/dist/spa.d.ts

@@ -0,0 +1,42 @@
+export declare const SPA_EXACT_PATHS: Set<string>;
+export declare const SPA_PREFIX_PATHS: string[];
+export declare const SERVER_OWNED_PREFIXES: string[];
+export declare const SERVER_OWNED_EXACT: Set<string>;
+export declare const SPA_PUBLIC_EXACT: Set<string>;
+export declare const SPA_PUBLIC_PREFIXES: string[];
+export declare function isServerOwned(path: string): boolean;
+export declare function isSpaPath(path: string): boolean;
+export declare function isPublicSpaPath(path: string): boolean;
+/** `/` and `/settings` -> `./`; `/session/abc` -> `../`. */
+export declare function baseHrefFor(path: string): string;
+export interface Asset {
+    body: Buffer;
+    gz: Buffer | null;
+    etag: string;
+    contentType: string;
+}
+/** Percent-encode like Python `urllib.parse.quote(value, safe='')`. */
+export declare function quoteAll(value: string): string;
+/** Cached files under one root: raw bytes, gzip twin for compressible types over 1 KiB, weak ETag from (size, mtime_ns). */
+export declare class AssetCache {
+    readonly root: string;
+    private readonly entries;
+    constructor(root: string);
+    /** Resolve `<root>/<rel>`; null when missing, not a file, or escaping the root. */
+    get(rel: string): Asset | null;
+}
+export declare class SpaShell {
+    readonly distRoot: string;
+    private readonly assets;
+    private shell;
+    constructor(distRoot: string);
+    available(): boolean;
+    private readTemplate;
+    renderShell(path: string, opts: {
+        lang?: string;
+        version: string;
+    }): string;
+    /** Resolve `static/dist/<rel>` inside the root; null when missing or escaping. */
+    asset(rel: string): Asset | null;
+    serviceWorker(version: string): Buffer | null;
+}