@nimbus-sh/core 0.1.0

package/dist/substrate/lifo/utils/glob.js

@@ -0,0 +1,150 @@
+import { resolve } from './path.js';
+/**
+ * Match a glob pattern against a text string.
+ * Supports: * ? [abc] [!abc] [a-z]
+ */
+export function globMatch(pattern, text) {
+    let pi = 0;
+    let ti = 0;
+    let starPi = -1;
+    let starTi = -1;
+    while (ti < text.length) {
+        if (pi < pattern.length && pattern[pi] === '[') {
+            const result = matchCharClass(pattern, pi, text[ti]);
+            if (result.matched) {
+                pi = result.end;
+                ti++;
+                continue;
+            }
+            // No match in char class
+            if (starPi >= 0) {
+                pi = starPi + 1;
+                starTi++;
+                ti = starTi;
+                continue;
+            }
+            return false;
+        }
+        if (pi < pattern.length && pattern[pi] === '?') {
+            pi++;
+            ti++;
+            continue;
+        }
+        if (pi < pattern.length && pattern[pi] === '*') {
+            starPi = pi;
+            starTi = ti;
+            pi++;
+            continue;
+        }
+        if (pi < pattern.length && pattern[pi] === text[ti]) {
+            pi++;
+            ti++;
+            continue;
+        }
+        if (starPi >= 0) {
+            pi = starPi + 1;
+            starTi++;
+            ti = starTi;
+            continue;
+        }
+        return false;
+    }
+    while (pi < pattern.length && pattern[pi] === '*') {
+        pi++;
+    }
+    return pi === pattern.length;
+}
+function matchCharClass(pattern, pos, ch) {
+    let i = pos + 1; // skip [
+    let negate = false;
+    if (i < pattern.length && (pattern[i] === '!' || pattern[i] === '^')) {
+        negate = true;
+        i++;
+    }
+    let matched = false;
+    const start = i;
+    while (i < pattern.length && (pattern[i] !== ']' || i === start)) {
+        if (i + 2 < pattern.length && pattern[i + 1] === '-' && pattern[i + 2] !== ']') {
+            // Range
+            if (ch >= pattern[i] && ch <= pattern[i + 2]) {
+                matched = true;
+            }
+            i += 3;
+        }
+        else {
+            if (ch === pattern[i]) {
+                matched = true;
+            }
+            i++;
+        }
+    }
+    if (i < pattern.length && pattern[i] === ']') {
+        i++; // skip ]
+    }
+    return { matched: negate ? !matched : matched, end: i };
+}
+/**
+ * Expand a glob pattern against the VFS.
+ * Returns sorted matching paths, or [pattern] if no matches.
+ */
+export function expandGlob(pattern, cwd, vfs) {
+    // If no glob chars, return as-is
+    if (!hasGlobChars(pattern)) {
+        return [pattern];
+    }
+    const absPattern = pattern.startsWith('/') ? pattern : resolve(cwd, pattern);
+    const parts = absPattern.split('/').filter(Boolean);
+    const isAbsolute = pattern.startsWith('/');
+    let candidates = ['/'];
+    for (const part of parts) {
+        const nextCandidates = [];
+        if (!hasGlobChars(part)) {
+            // Literal path segment
+            for (const dir of candidates) {
+                const full = dir === '/' ? `/${part}` : `${dir}/${part}`;
+                if (vfs.exists(full)) {
+                    nextCandidates.push(full);
+                }
+            }
+        }
+        else {
+            // Glob segment -- match against directory entries
+            for (const dir of candidates) {
+                try {
+                    const entries = vfs.readdir(dir);
+                    for (const entry of entries) {
+                        if (globMatch(part, entry.name)) {
+                            const full = dir === '/' ? `/${entry.name}` : `${dir}/${entry.name}`;
+                            nextCandidates.push(full);
+                        }
+                    }
+                }
+                catch {
+                    // dir doesn't exist or isn't a directory
+                }
+            }
+        }
+        candidates = nextCandidates;
+    }
+    if (candidates.length === 0) {
+        return [pattern]; // no matches, return literal
+    }
+    // Convert back to relative paths if pattern was relative
+    let results;
+    if (isAbsolute) {
+        results = candidates;
+    }
+    else {
+        const prefix = cwd === '/' ? '/' : cwd + '/';
+        results = candidates.map((c) => {
+            if (c.startsWith(prefix)) {
+                return c.slice(prefix.length);
+            }
+            return c;
+        });
+    }
+    return results.sort();
+}
+function hasGlobChars(s) {
+    return s.includes('*') || s.includes('?') || s.includes('[');
+}

package/dist/substrate/lifo/utils/mime.d.ts

@@ -0,0 +1,4 @@
+export declare function getMimeType(filename: string): string;
+export declare function getFileCategory(mime: string): 'text' | 'image' | 'video' | 'audio' | 'archive' | 'binary';
+export declare function isBinaryMime(mime: string): boolean;
+//# sourceMappingURL=mime.d.ts.map

package/dist/substrate/lifo/utils/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../src/substrate/lifo/utils/mime.ts"],"names":[],"mappings":"AAoFA,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAgB7D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD"}

package/dist/substrate/lifo/utils/mime.js

@@ -0,0 +1,107 @@
+const mimeTypes = new Map([
+    // Text
+    ['.txt', 'text/plain'],
+    ['.md', 'text/markdown'],
+    ['.json', 'application/json'],
+    ['.js', 'text/javascript'],
+    ['.ts', 'text/typescript'],
+    ['.jsx', 'text/jsx'],
+    ['.tsx', 'text/tsx'],
+    ['.css', 'text/css'],
+    ['.html', 'text/html'],
+    ['.xml', 'text/xml'],
+    ['.yaml', 'text/yaml'],
+    ['.yml', 'text/yaml'],
+    ['.toml', 'text/toml'],
+    ['.ini', 'text/plain'],
+    ['.cfg', 'text/plain'],
+    ['.conf', 'text/plain'],
+    ['.sh', 'text/x-shellscript'],
+    ['.bash', 'text/x-shellscript'],
+    ['.zsh', 'text/x-shellscript'],
+    ['.py', 'text/x-python'],
+    ['.rb', 'text/x-ruby'],
+    ['.go', 'text/x-go'],
+    ['.rs', 'text/x-rust'],
+    ['.c', 'text/x-c'],
+    ['.cpp', 'text/x-c++'],
+    ['.h', 'text/x-c'],
+    ['.hpp', 'text/x-c++'],
+    ['.java', 'text/x-java'],
+    ['.csv', 'text/csv'],
+    ['.log', 'text/plain'],
+    ['.env', 'text/plain'],
+    ['.gitignore', 'text/plain'],
+    ['.dockerignore', 'text/plain'],
+    ['.sql', 'text/x-sql'],
+    ['.graphql', 'text/x-graphql'],
+    ['.vue', 'text/x-vue'],
+    ['.svelte', 'text/x-svelte'],
+    // Images
+    ['.png', 'image/png'],
+    ['.jpg', 'image/jpeg'],
+    ['.jpeg', 'image/jpeg'],
+    ['.gif', 'image/gif'],
+    ['.svg', 'image/svg+xml'],
+    ['.webp', 'image/webp'],
+    ['.ico', 'image/x-icon'],
+    ['.bmp', 'image/bmp'],
+    ['.tiff', 'image/tiff'],
+    // Video
+    ['.mp4', 'video/mp4'],
+    ['.webm', 'video/webm'],
+    ['.avi', 'video/x-msvideo'],
+    ['.mov', 'video/quicktime'],
+    ['.mkv', 'video/x-matroska'],
+    // Audio
+    ['.mp3', 'audio/mpeg'],
+    ['.wav', 'audio/wav'],
+    ['.ogg', 'audio/ogg'],
+    ['.flac', 'audio/flac'],
+    ['.aac', 'audio/aac'],
+    ['.m4a', 'audio/mp4'],
+    // Archives
+    ['.zip', 'application/zip'],
+    ['.tar', 'application/x-tar'],
+    ['.gz', 'application/gzip'],
+    ['.tgz', 'application/gzip'],
+    ['.bz2', 'application/x-bzip2'],
+    ['.7z', 'application/x-7z-compressed'],
+    ['.rar', 'application/vnd.rar'],
+    // Binary / Application
+    ['.pdf', 'application/pdf'],
+    ['.wasm', 'application/wasm'],
+    ['.exe', 'application/x-msdownload'],
+    ['.dll', 'application/x-msdownload'],
+    ['.so', 'application/x-sharedlib'],
+    ['.dylib', 'application/x-sharedlib'],
+]);
+export function getMimeType(filename) {
+    const dot = filename.lastIndexOf('.');
+    if (dot === -1)
+        return 'application/octet-stream';
+    const ext = filename.slice(dot).toLowerCase();
+    return mimeTypes.get(ext) ?? 'application/octet-stream';
+}
+export function getFileCategory(mime) {
+    if (mime.startsWith('text/') || mime === 'application/json')
+        return 'text';
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'video';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    if (mime === 'application/zip' ||
+        mime === 'application/x-tar' ||
+        mime === 'application/gzip' ||
+        mime === 'application/x-bzip2' ||
+        mime === 'application/x-7z-compressed' ||
+        mime === 'application/vnd.rar') {
+        return 'archive';
+    }
+    return 'binary';
+}
+export function isBinaryMime(mime) {
+    return getFileCategory(mime) !== 'text';
+}

package/dist/substrate/lifo/utils/path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * POSIX path operations -- pure string manipulation, no I/O.
+ */
+export declare function normalize(path: string): string;
+export declare function isAbsolute(path: string): boolean;
+export declare function join(...segments: string[]): string;
+export declare function resolve(cwd: string, ...segments: string[]): string;
+export declare function dirname(path: string): string;
+export declare function basename(path: string, ext?: string): string;
+export declare function extname(path: string): string;
+export declare function split(path: string): string[];
+//# sourceMappingURL=path.d.ts.map

package/dist/substrate/lifo/utils/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../../src/substrate/lifo/utils/path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuB9C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,wBAAgB,IAAI,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAElD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAUlE;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ5C"}

package/dist/substrate/lifo/utils/path.js

@@ -0,0 +1,82 @@
+/**
+ * POSIX path operations -- pure string manipulation, no I/O.
+ */
+export function normalize(path) {
+    if (path === '')
+        return '.';
+    const absolute = path.startsWith('/');
+    const parts = path.split('/');
+    const resolved = [];
+    for (const part of parts) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (resolved.length > 0 && resolved[resolved.length - 1] !== '..') {
+                resolved.pop();
+            }
+            else if (!absolute) {
+                resolved.push('..');
+            }
+        }
+        else {
+            resolved.push(part);
+        }
+    }
+    let result = resolved.join('/');
+    if (absolute)
+        result = '/' + result;
+    return result || (absolute ? '/' : '.');
+}
+export function isAbsolute(path) {
+    return path.startsWith('/');
+}
+export function join(...segments) {
+    return normalize(segments.filter(Boolean).join('/'));
+}
+export function resolve(cwd, ...segments) {
+    let result = cwd;
+    for (const seg of segments) {
+        if (isAbsolute(seg)) {
+            result = seg;
+        }
+        else {
+            result = result + '/' + seg;
+        }
+    }
+    return normalize(result);
+}
+export function dirname(path) {
+    const normalized = normalize(path);
+    const lastSlash = normalized.lastIndexOf('/');
+    if (lastSlash === -1)
+        return '.';
+    if (lastSlash === 0)
+        return '/';
+    return normalized.slice(0, lastSlash);
+}
+export function basename(path, ext) {
+    const normalized = normalize(path);
+    const lastSlash = normalized.lastIndexOf('/');
+    let base = lastSlash === -1 ? normalized : normalized.slice(lastSlash + 1);
+    if (ext && base.endsWith(ext)) {
+        base = base.slice(0, -ext.length);
+    }
+    return base;
+}
+export function extname(path) {
+    const base = basename(path);
+    const dotIndex = base.lastIndexOf('.');
+    if (dotIndex <= 0)
+        return '';
+    return base.slice(dotIndex);
+}
+export function split(path) {
+    const normalized = normalize(path);
+    if (normalized === '/')
+        return ['/'];
+    const parts = normalized.split('/').filter(Boolean);
+    if (normalized.startsWith('/')) {
+        return ['/', ...parts];
+    }
+    return parts;
+}

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,46 @@
+/**
+ * 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 (for example git-network-facet,
+ * pre-bundle-facet, and node-shims generated/runtime strings) 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;
+/** Resolve a user path against a VFS cwd and return a canonical VFS key. */
+export declare function resolveVfsPath(path: string, cwd: string): string;
+/** Return the canonical VFS parent key, or an empty string for root-level paths. */
+export declare function parentVfsPath(path: string): string;
+/** Strip leading slashes only — does not touch internal segments. */
+export declare function stripLeadingSlashes(p: string): string;
+/**
+ * The basename's extension including its leading dot, or an empty string when
+ * there is none. A dot that opens the basename belongs to the name (`.bashrc`)
+ * rather than to an extension, matching Node's `path.extname`.
+ *
+ * `endsWith` and `split('.').pop()` are not substitutes for callers deciding
+ * how to PARSE a file: neither can say "this path has no extension", and the
+ * latter answers `js/bin/tsc` for `home/user.js/bin/tsc`. Extensionless files
+ * are the shape of nearly every npm `bin` script, so that answer is
+ * load-bearing rather than an edge case.
+ */
+export declare function vfsPathExtension(path: 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,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIhE;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD"}

package/dist/vfs/path.js

@@ -0,0 +1,69 @@
+/**
+ * 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 (for example git-network-facet,
+ * pre-bundle-facet, and node-shims generated/runtime strings) 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('/');
+}
+/** Resolve a user path against a VFS cwd and return a canonical VFS key. */
+export function resolveVfsPath(path, cwd) {
+    return path.startsWith('/')
+        ? normalizeVfsPath(path)
+        : normalizeVfsPath(`${cwd}/${path}`);
+}
+/** Return the canonical VFS parent key, or an empty string for root-level paths. */
+export function parentVfsPath(path) {
+    const clean = normalizeVfsPath(path);
+    const idx = clean.lastIndexOf('/');
+    return idx > 0 ? clean.slice(0, idx) : '';
+}
+/** Strip leading slashes only — does not touch internal segments. */
+export function stripLeadingSlashes(p) {
+    return p.replace(/^\/+/, '');
+}
+/**
+ * The basename's extension including its leading dot, or an empty string when
+ * there is none. A dot that opens the basename belongs to the name (`.bashrc`)
+ * rather than to an extension, matching Node's `path.extname`.
+ *
+ * `endsWith` and `split('.').pop()` are not substitutes for callers deciding
+ * how to PARSE a file: neither can say "this path has no extension", and the
+ * latter answers `js/bin/tsc` for `home/user.js/bin/tsc`. Extensionless files
+ * are the shape of nearly every npm `bin` script, so that answer is
+ * load-bearing rather than an edge case.
+ */
+export function vfsPathExtension(path) {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(dot) : '';
+}