@nimbus-sh/worker 0.1.0

package/dist/vfs/dev-provider.d.ts

@@ -0,0 +1,64 @@
+/**
+ * dev-provider.ts — virtual /dev provider.
+ *
+ * BUG-SWEEP-R3-1 (2026-05-11): pre-fix `cmd > /dev/null` and
+ * `cmd 2>/dev/null` returned `ENOENT: '/dev': no such file or
+ * directory` because /dev wasn't mounted. Standard Unix idioms
+ * (`make 2>/dev/null`, `cmd > /dev/null 2>&1`, scripts piping
+ * to /dev/null) all failed.
+ *
+ * This provider implements the standard device-file subset:
+ *
+ *   /dev/null    — write: discard; read: EOF (empty)
+ *   /dev/zero    — write: discard; read: infinite zeros (capped per read)
+ *   /dev/random  — write: discard; read: crypto.getRandomValues()
+ *   /dev/urandom — alias of /dev/random
+ *   /dev/stdin   — passthrough placeholder (not really useful here)
+ *   /dev/stdout  — passthrough placeholder
+ *   /dev/stderr  — passthrough placeholder
+ *   /dev/full    — write: ENOSPC; read: infinite zeros
+ *
+ * The provider is mounted at `/dev` (no leading slash for Kernel
+ * convention which already does that). All entries are virtual:
+ * stat returns synthesized FileType-shaped objects. The MountProvider
+ * surface lifo-sh expects (readFile/writeFile/exists/stat/readdir/
+ * unlink/mkdir/rmdir/rename/copyFile) is fully implemented — reads
+ * from non-existent dev nodes return ENOENT, writes to read-only
+ * nodes silently succeed (Unix /dev/null/zero/random semantics).
+ */
+/**
+ * MountProvider impl for /dev. lifo-sh's Kernel routes any path
+ * under /dev/* through these methods.
+ */
+export declare class DevProvider {
+    private nodes;
+    constructor();
+    /** Normalize "/foo" or "foo" to "foo". Kernel passes either shape
+     *  depending on call site; defensive normalization. */
+    private norm;
+    readFile(sub: string): Uint8Array;
+    readFileString(sub: string): string;
+    writeFile(sub: string, content: string | Uint8Array): void;
+    exists(sub: string): boolean;
+    stat(sub: string): {
+        type: string;
+        size: number;
+        mtime: number;
+        ctime: number;
+        mode: number;
+    };
+    readdir(sub: string): {
+        name: string;
+        type: string;
+    }[];
+    unlink(sub: string): void;
+    mkdir(_sub: string, _opts?: {
+        recursive?: boolean;
+    }): void;
+    rmdir(_sub: string): void;
+    rename(_o: string, _n: string): void;
+    copyFile(_s: string, _d: string): void;
+    appendFile(_sub: string, _content: string | Uint8Array): void;
+    isDirectory(sub: string): boolean;
+}
+//# sourceMappingURL=dev-provider.d.ts.map

package/dist/vfs/dev-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-provider.d.ts","sourceRoot":"","sources":["../../src/vfs/dev-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA0EH;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAuB;;IAMpC;2DACuD;IACvD,OAAO,CAAC,IAAI;IAMZ,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;IAQjC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAInC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAc1D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAa7F,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;IAgBtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAI1D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAEzB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAIpC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAItC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAK7D,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAIlC"}

package/dist/vfs/dev-provider.js

@@ -0,0 +1,191 @@
+/**
+ * dev-provider.ts — virtual /dev provider.
+ *
+ * BUG-SWEEP-R3-1 (2026-05-11): pre-fix `cmd > /dev/null` and
+ * `cmd 2>/dev/null` returned `ENOENT: '/dev': no such file or
+ * directory` because /dev wasn't mounted. Standard Unix idioms
+ * (`make 2>/dev/null`, `cmd > /dev/null 2>&1`, scripts piping
+ * to /dev/null) all failed.
+ *
+ * This provider implements the standard device-file subset:
+ *
+ *   /dev/null    — write: discard; read: EOF (empty)
+ *   /dev/zero    — write: discard; read: infinite zeros (capped per read)
+ *   /dev/random  — write: discard; read: crypto.getRandomValues()
+ *   /dev/urandom — alias of /dev/random
+ *   /dev/stdin   — passthrough placeholder (not really useful here)
+ *   /dev/stdout  — passthrough placeholder
+ *   /dev/stderr  — passthrough placeholder
+ *   /dev/full    — write: ENOSPC; read: infinite zeros
+ *
+ * The provider is mounted at `/dev` (no leading slash for Kernel
+ * convention which already does that). All entries are virtual:
+ * stat returns synthesized FileType-shaped objects. The MountProvider
+ * surface lifo-sh expects (readFile/writeFile/exists/stat/readdir/
+ * unlink/mkdir/rmdir/rename/copyFile) is fully implemented — reads
+ * from non-existent dev nodes return ENOENT, writes to read-only
+ * nodes silently succeed (Unix /dev/null/zero/random semantics).
+ */
+const enc = new TextEncoder();
+function makeNode(opts) {
+    const now = Date.now();
+    return {
+        type: opts.type,
+        size: opts.size ?? 0,
+        mtime: opts.mtime ?? now,
+        mode: opts.mode ?? (opts.type === 'directory' ? 0o755 : 0o666),
+        read: opts.read ?? (() => new Uint8Array(0)),
+        write: opts.write ?? (() => { }),
+    };
+}
+// Cap any single read of /dev/zero or /dev/random to prevent OOM
+// on `dd if=/dev/zero ... count=∞`. Real Unix lets you read forever;
+// our model is sync + bounded, so we cap reads. 64 KiB is generous
+// for any reasonable test/script.
+const DEV_READ_CAP = 64 * 1024;
+function makeNodes() {
+    const nodes = new Map();
+    nodes.set('', makeNode({ type: 'directory' }));
+    nodes.set('null', makeNode({
+        type: 'file',
+        read: () => new Uint8Array(0),
+        write: () => { },
+    }));
+    nodes.set('zero', makeNode({
+        type: 'file',
+        read: () => new Uint8Array(DEV_READ_CAP),
+        write: () => { },
+    }));
+    nodes.set('random', makeNode({
+        type: 'file',
+        read: () => {
+            const buf = new Uint8Array(DEV_READ_CAP);
+            try {
+                crypto.getRandomValues(buf);
+            }
+            catch { /* runtime without crypto — return zeros */ }
+            return buf;
+        },
+        write: () => { },
+    }));
+    nodes.set('urandom', makeNode({
+        type: 'file',
+        read: () => {
+            const buf = new Uint8Array(DEV_READ_CAP);
+            try {
+                crypto.getRandomValues(buf);
+            }
+            catch { /* fallthrough */ }
+            return buf;
+        },
+        write: () => { },
+    }));
+    nodes.set('full', makeNode({
+        type: 'file',
+        read: () => new Uint8Array(DEV_READ_CAP),
+        write: () => { throw new Error('ENOSPC: no space left on device'); },
+    }));
+    nodes.set('stdin', makeNode({ type: 'file' }));
+    nodes.set('stdout', makeNode({ type: 'file' }));
+    nodes.set('stderr', makeNode({ type: 'file' }));
+    nodes.set('tty', makeNode({ type: 'file' }));
+    return nodes;
+}
+/**
+ * MountProvider impl for /dev. lifo-sh's Kernel routes any path
+ * under /dev/* through these methods.
+ */
+export class DevProvider {
+    nodes;
+    constructor() {
+        this.nodes = makeNodes();
+    }
+    /** Normalize "/foo" or "foo" to "foo". Kernel passes either shape
+     *  depending on call site; defensive normalization. */
+    norm(sub) {
+        return sub.replace(/^\/+/, '').replace(/\/+$/, '');
+    }
+    // ── MountProvider surface ──
+    readFile(sub) {
+        const n = this.norm(sub);
+        const node = this.nodes.get(n);
+        if (!node)
+            throw new Error(`ENOENT: '/dev/${n}': no such file or directory`);
+        if (node.type === 'directory')
+            throw new Error(`EISDIR: '/dev/${n}': is a directory`);
+        return node.read();
+    }
+    readFileString(sub) {
+        return new TextDecoder('utf-8').decode(this.readFile(sub));
+    }
+    writeFile(sub, content) {
+        const n = this.norm(sub);
+        let node = this.nodes.get(n);
+        if (!node) {
+            // Creating new files under /dev is not supported (real Unix
+            // allows it as root; we don't). Silently discard the data —
+            // matches /dev/null semantics for anything written here.
+            return;
+        }
+        if (node.type === 'directory')
+            throw new Error(`EISDIR: '/dev/${n}': is a directory`);
+        const bytes = typeof content === 'string' ? enc.encode(content) : content;
+        node.write(bytes);
+    }
+    exists(sub) {
+        return this.nodes.has(this.norm(sub));
+    }
+    stat(sub) {
+        const n = this.norm(sub);
+        const node = this.nodes.get(n);
+        if (!node)
+            throw new Error(`ENOENT: '/dev/${n}': no such file or directory`);
+        return {
+            type: node.type,
+            size: node.size,
+            mtime: node.mtime,
+            ctime: node.mtime,
+            mode: node.mode,
+        };
+    }
+    readdir(sub) {
+        const n = this.norm(sub);
+        if (n !== '') {
+            const node = this.nodes.get(n);
+            if (!node)
+                throw new Error(`ENOENT: '/dev/${n}': no such file or directory`);
+            if (node.type !== 'directory')
+                throw new Error(`ENOTDIR: '/dev/${n}': not a directory`);
+            return [];
+        }
+        const results = [];
+        for (const [name, node] of this.nodes) {
+            if (name === '')
+                continue;
+            results.push({ name, type: node.type });
+        }
+        return results;
+    }
+    unlink(sub) {
+        // Real /dev nodes can't be removed by user code. Silently no-op
+        // (errors here break `rm -rf X && touch X` idioms).
+    }
+    mkdir(_sub, _opts) {
+        // No-op; /dev is read-only.
+    }
+    rmdir(_sub) { }
+    rename(_o, _n) {
+        throw new Error('EROFS: read-only filesystem');
+    }
+    copyFile(_s, _d) {
+        throw new Error('EROFS: read-only filesystem');
+    }
+    appendFile(_sub, _content) {
+        // Append to /dev/null = discard
+    }
+    // Optional methods that some MountProvider consumers expect.
+    isDirectory(sub) {
+        const node = this.nodes.get(this.norm(sub));
+        return !!node && node.type === 'directory';
+    }
+}

package/dist/vfs/events.d.ts

@@ -0,0 +1,51 @@
+/**
+ * VFS Event System — EventEmitter for filesystem mutations.
+ *
+ * Fires on every write/unlink/rename/mkdir. Foundation for fs.watch(),
+ * chokidar shim, and HMR in Phase 4.
+ *
+ * Events are debounce-batched: rapid mutations (e.g. npm install writing
+ * thousands of files) are coalesced into a single batch emission per
+ * microtask, reducing listener overhead.
+ */
+export type VfsEventType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir' | 'rename';
+export interface VfsEvent {
+    type: VfsEventType;
+    path: string;
+    /** For rename events, the original path */
+    oldPath?: string;
+    timestamp: number;
+}
+export type VfsEventListener = (events: VfsEvent[]) => void;
+export type VfsPathListener = (event: VfsEvent) => void;
+/**
+ * Lightweight EventEmitter for VFS mutations.
+ * - Global listeners receive batched events per microtask.
+ * - Path listeners receive individual events for matching paths.
+ */
+export declare class VfsEventEmitter {
+    private _globalListeners;
+    private _pathListeners;
+    private _pending;
+    private _flushScheduled;
+    private _totalEmitted;
+    private _totalBatches;
+    /** Register a global listener that receives batched events. */
+    on(listener: VfsEventListener): () => void;
+    /** Register a listener for a specific path (or path prefix with recursive). */
+    onPath(path: string, listener: VfsPathListener): () => void;
+    /** Emit a VFS event. Batched and flushed on the next microtask. */
+    emit(type: VfsEventType, path: string, oldPath?: string): void;
+    private _deliverToPathListeners;
+    private _flush;
+    /** Remove all listeners. */
+    removeAll(): void;
+    get stats(): {
+        totalEmitted: number;
+        totalBatches: number;
+        globalListeners: number;
+        pathListeners: number;
+        pending: number;
+    };
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/vfs/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/vfs/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3F,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC;AAC5D,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;AAExD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,gBAAgB,CAA0B;IAClD,OAAO,CAAC,cAAc,CAAwC;IAC9D,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,eAAe,CAAS;IAGhC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAAK;IAE1B,+DAA+D;IAC/D,EAAE,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAQ1C,+EAA+E;IAC/E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;IAiB3D,mEAAmE;IACnE,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAc9D,OAAO,CAAC,uBAAuB;IAqB/B,OAAO,CAAC,MAAM;IAcd,4BAA4B;IAC5B,SAAS,IAAI,IAAI;IAOjB,IAAI,KAAK;;;;;;MAQR;CACF"}

package/dist/vfs/events.js

@@ -0,0 +1,127 @@
+/**
+ * VFS Event System — EventEmitter for filesystem mutations.
+ *
+ * Fires on every write/unlink/rename/mkdir. Foundation for fs.watch(),
+ * chokidar shim, and HMR in Phase 4.
+ *
+ * Events are debounce-batched: rapid mutations (e.g. npm install writing
+ * thousands of files) are coalesced into a single batch emission per
+ * microtask, reducing listener overhead.
+ */
+/**
+ * Lightweight EventEmitter for VFS mutations.
+ * - Global listeners receive batched events per microtask.
+ * - Path listeners receive individual events for matching paths.
+ */
+export class VfsEventEmitter {
+    _globalListeners = [];
+    _pathListeners = new Map();
+    _pending = [];
+    _flushScheduled = false;
+    // Stats
+    _totalEmitted = 0;
+    _totalBatches = 0;
+    /** Register a global listener that receives batched events. */
+    on(listener) {
+        this._globalListeners.push(listener);
+        return () => {
+            const idx = this._globalListeners.indexOf(listener);
+            if (idx >= 0)
+                this._globalListeners.splice(idx, 1);
+        };
+    }
+    /** Register a listener for a specific path (or path prefix with recursive). */
+    onPath(path, listener) {
+        let list = this._pathListeners.get(path);
+        if (!list) {
+            list = [];
+            this._pathListeners.set(path, list);
+        }
+        list.push(listener);
+        return () => {
+            const arr = this._pathListeners.get(path);
+            if (arr) {
+                const idx = arr.indexOf(listener);
+                if (idx >= 0)
+                    arr.splice(idx, 1);
+                if (arr.length === 0)
+                    this._pathListeners.delete(path);
+            }
+        };
+    }
+    /** Emit a VFS event. Batched and flushed on the next microtask. */
+    emit(type, path, oldPath) {
+        const event = { type, path, timestamp: Date.now(), oldPath };
+        this._pending.push(event);
+        // Immediately deliver to path listeners (no batching for these)
+        this._deliverToPathListeners(event);
+        // Schedule batch flush for global listeners
+        if (!this._flushScheduled) {
+            this._flushScheduled = true;
+            queueMicrotask(() => this._flush());
+        }
+    }
+    _deliverToPathListeners(event) {
+        // Exact match
+        const exact = this._pathListeners.get(event.path);
+        if (exact) {
+            for (const listener of exact) {
+                try {
+                    listener(event);
+                }
+                catch (e) {
+                    console.error('[vfs-events] path listener error:', e);
+                }
+            }
+        }
+        // Parent directory listeners (recursive watching)
+        let dir = event.path;
+        while (dir.includes('/')) {
+            dir = dir.substring(0, dir.lastIndexOf('/'));
+            const parent = this._pathListeners.get(dir);
+            if (parent) {
+                for (const listener of parent) {
+                    try {
+                        listener(event);
+                    }
+                    catch (e) {
+                        console.error('[vfs-events] path listener error:', e);
+                    }
+                }
+            }
+        }
+    }
+    _flush() {
+        this._flushScheduled = false;
+        const batch = this._pending;
+        this._pending = [];
+        if (batch.length === 0)
+            return;
+        this._totalEmitted += batch.length;
+        this._totalBatches++;
+        for (const listener of this._globalListeners) {
+            try {
+                listener(batch);
+            }
+            catch (e) {
+                console.error('[vfs-events] global listener error:', e);
+            }
+        }
+    }
+    /** Remove all listeners. */
+    removeAll() {
+        this._globalListeners = [];
+        this._pathListeners.clear();
+        this._pending = [];
+        this._flushScheduled = false;
+    }
+    get stats() {
+        return {
+            totalEmitted: this._totalEmitted,
+            totalBatches: this._totalBatches,
+            globalListeners: this._globalListeners.length,
+            pathListeners: this._pathListeners.size,
+            pending: this._pending.length,
+        };
+    }
+}

package/dist/vfs/path.d.ts

@@ -0,0 +1,30 @@
+/**
+ * vfs-path.ts — Canonical VFS path normalization.
+ *
+ * Replaces three near-duplicate implementations that lived in
+ * git-commands.ts, esbuild-service.ts, and require-resolver.ts. The
+ * git-commands version had a defensive bounds check (`out.length > 0`
+ * before pop) that the others lacked — that safer behavior is the one
+ * preserved here.
+ *
+ * Facet-isolate code-string copies (e.g. inside
+ * generateGitNetworkFacetCode in git-network-facet.ts, and inside
+ * node-shims.ts) cannot import this module and must keep their inline
+ * implementations; those copies are documented as justified.
+ *
+ * Semantics:
+ *   - Strip empty segments (collapses `//` runs)
+ *   - Drop `.` segments
+ *   - Pop on `..`, but only if there's something to pop (won't escape root)
+ *   - Returns slash-joined string with NO leading/trailing slash, suitable
+ *     for direct VFS lookup keys
+ *
+ * Examples:
+ *   normalizeVfsPath('/foo/./bar/../baz') -> 'foo/baz'
+ *   normalizeVfsPath('/foo//bar/')         -> 'foo/bar'
+ *   normalizeVfsPath('../escape')          -> 'escape'  (bounded; doesn't go negative)
+ */
+export declare function normalizeVfsPath(p: string): string;
+/** Strip leading slashes only — does not touch internal segments. */
+export declare function stripLeadingSlashes(p: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/vfs/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/vfs/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQlD;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/vfs/path.js

@@ -0,0 +1,41 @@
+/**
+ * vfs-path.ts — Canonical VFS path normalization.
+ *
+ * Replaces three near-duplicate implementations that lived in
+ * git-commands.ts, esbuild-service.ts, and require-resolver.ts. The
+ * git-commands version had a defensive bounds check (`out.length > 0`
+ * before pop) that the others lacked — that safer behavior is the one
+ * preserved here.
+ *
+ * Facet-isolate code-string copies (e.g. inside
+ * generateGitNetworkFacetCode in git-network-facet.ts, and inside
+ * node-shims.ts) cannot import this module and must keep their inline
+ * implementations; those copies are documented as justified.
+ *
+ * Semantics:
+ *   - Strip empty segments (collapses `//` runs)
+ *   - Drop `.` segments
+ *   - Pop on `..`, but only if there's something to pop (won't escape root)
+ *   - Returns slash-joined string with NO leading/trailing slash, suitable
+ *     for direct VFS lookup keys
+ *
+ * Examples:
+ *   normalizeVfsPath('/foo/./bar/../baz') -> 'foo/baz'
+ *   normalizeVfsPath('/foo//bar/')         -> 'foo/bar'
+ *   normalizeVfsPath('../escape')          -> 'escape'  (bounded; doesn't go negative)
+ */
+export function normalizeVfsPath(p) {
+    const segments = String(p ?? '').split('/');
+    const out = [];
+    for (const seg of segments) {
+        if (seg === '..' && out.length > 0)
+            out.pop();
+        else if (seg !== '.' && seg !== '' && seg !== undefined)
+            out.push(seg);
+    }
+    return out.join('/');
+}
+/** Strip leading slashes only — does not touch internal segments. */
+export function stripLeadingSlashes(p) {
+    return p.replace(/^\/+/, '');
+}

package/dist/vfs/seed-project.d.ts

@@ -0,0 +1,62 @@
+/**
+ * seed-project.ts — Materialize a polished Vite + React + TS + Tailwind +
+ * React Router starter at /home/user/app on first boot.
+ *
+ * Invariants:
+ *   - Idempotent: won't re-seed once the sentinel (~/.nimbus-seeded) exists.
+ *   - Atomic-ish: file bodies written in ONE writeBatch(); sentinel written
+ *     in a SECOND writeBatch() so a crash between the two re-runs the whole
+ *     seed on next boot (writeFile is idempotent, so retry is safe).
+ *   - User escape hatch: `rm -rf ~/app ~/.nimbus-seeded` → next session
+ *     regenerates from factory defaults (hard reset semantics).
+ *
+ * Design choices (see plan):
+ *   - Root: /home/user/app (doesn't pollute the home dir)
+ *   - Polished deps: react-router, framer-motion, lucide-react, tailwindcss
+ *   - No pre-install of node_modules (~200MB; let the user see install run)
+ *   - No auto-start of vite (surprising; README says `npm run dev`)
+ *   - Basename injection (commit 2) handles the /preview/ basepath wiring.
+ */
+import type { SqliteVFS } from './sqlite-vfs.js';
+/** Sentinel: if present, seed never runs again (until user deletes it). */
+export declare const SEED_SENTINEL_PATH = "home/user/.nimbus-seeded";
+/** Project root. Absolute VFS path (no leading slash). */
+export declare const SEED_PROJECT_DIR = "home/user/app";
+export interface SeedFile {
+    /** VFS path, no leading slash. */
+    path: string;
+    content: string;
+}
+export declare const SEED_FILES: SeedFile[];
+/**
+ * Should we run the starter-project seed?
+ * Returns false if:
+ *   - Sentinel exists (already seeded; user can `rm ~/.nimbus-seeded` to opt in again)
+ *   - Project dir already exists (user has their own ~/app we must not clobber)
+ */
+export declare function shouldSeedProject(vfs: SqliteVFS): boolean;
+/**
+ * Returns true if the sentinel is present (seed has completed at least once).
+ * Used to gate MOTD hints about the starter app.
+ */
+export declare function hasSeededProject(vfs: SqliteVFS): boolean;
+/**
+ * Materialize the seed project.
+ *
+ * Two-phase write for crash recovery:
+ *   1. Write all file bodies + directory inodes in ONE writeBatch().
+ *   2. Only on success, write the sentinel in a SEPARATE writeBatch().
+ *
+ * If the process dies between (1) and (2), the next boot will re-run this
+ * function (sentinel absent). All writes are `INSERT OR REPLACE` so retry
+ * is idempotent. If (1) itself fails mid-transaction, sqlite rolls back and
+ * we start clean next boot.
+ */
+export declare function seedProject(vfs: SqliteVFS, opts?: {
+    log?: (msg: string) => void;
+}): {
+    seeded: boolean;
+    files: number;
+    reason?: string;
+};
+//# sourceMappingURL=seed-project.d.ts.map

package/dist/vfs/seed-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-project.d.ts","sourceRoot":"","sources":["../../src/vfs/seed-project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,SAAS,EAGV,MAAM,iBAAiB,CAAC;AAIzB,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAE7D,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,MAAM,WAAW,QAAQ;IACvB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAg3BD,eAAO,MAAM,UAAU,EAAE,QAAQ,EAehC,CAAC;AAIF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAQzD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,SAAS,EACd,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CA4GrD"}