@nimbus-sh/core 0.1.0

package/src/substrate/lifo/utils/glob.ts

@@ -0,0 +1,172 @@
+import type { VFS } from '../kernel/vfs/index.js';
+import { resolve } from './path.js';
+
+/**
+ * Match a glob pattern against a text string.
+ * Supports: * ? [abc] [!abc] [a-z]
+ */
+export function globMatch(pattern: string, text: string): boolean {
+  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: string, pos: number, ch: string): { matched: boolean; end: number } {
+  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: string, cwd: string, vfs: VFS): string[] {
+  // 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: string[] = [];
+
+    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: string[];
+  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: string): boolean {
+  return s.includes('*') || s.includes('?') || s.includes('[');
+}

package/src/substrate/lifo/utils/mime.ts

@@ -0,0 +1,114 @@
+const mimeTypes = new Map<string, string>([
+  // 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: string): string {
+  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: string,
+): 'text' | 'image' | 'video' | 'audio' | 'archive' | 'binary' {
+  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: string): boolean {
+  return getFileCategory(mime) !== 'text';
+}

package/src/substrate/lifo/utils/path.ts

@@ -0,0 +1,83 @@
+/**
+ * POSIX path operations -- pure string manipulation, no I/O.
+ */
+
+export function normalize(path: string): string {
+  if (path === '') return '.';
+
+  const absolute = path.startsWith('/');
+  const parts = path.split('/');
+  const resolved: string[] = [];
+
+  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: string): boolean {
+  return path.startsWith('/');
+}
+
+export function join(...segments: string[]): string {
+  return normalize(segments.filter(Boolean).join('/'));
+}
+
+export function resolve(cwd: string, ...segments: string[]): string {
+  let result = cwd;
+  for (const seg of segments) {
+    if (isAbsolute(seg)) {
+      result = seg;
+    } else {
+      result = result + '/' + seg;
+    }
+  }
+  return normalize(result);
+}
+
+export function dirname(path: string): string {
+  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: string, ext?: string): string {
+  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: string): string {
+  const base = basename(path);
+  const dotIndex = base.lastIndexOf('.');
+  if (dotIndex <= 0) return '';
+  return base.slice(dotIndex);
+}
+
+export function split(path: string): string[] {
+  const normalized = normalize(path);
+  if (normalized === '/') return ['/'];
+  const parts = normalized.split('/').filter(Boolean);
+  if (normalized.startsWith('/')) {
+    return ['/', ...parts];
+  }
+  return parts;
+}

package/src/types/assets.d.ts

@@ -0,0 +1,4 @@
+declare module 'esbuild-wasm/esbuild.wasm' {
+  const url: string;
+  export default url;
+}

package/src/vfs/events.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 class VfsEventEmitter {
+  private _globalListeners: VfsEventListener[] = [];
+  private _pathListeners = new Map<string, VfsPathListener[]>();
+  private _pending: VfsEvent[] = [];
+  private _flushScheduled = false;
+
+  // Stats
+  private _totalEmitted = 0;
+  private _totalBatches = 0;
+
+  /** Register a global listener that receives batched events. */
+  on(listener: VfsEventListener): () => void {
+    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: string, listener: VfsPathListener): () => void {
+    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: VfsEventType, path: string, oldPath?: string): void {
+    const event: VfsEvent = { 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());
+    }
+  }
+
+  private _deliverToPathListeners(event: VfsEvent): void {
+    // 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); }
+        }
+      }
+    }
+  }
+
+  private _flush(): void {
+    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(): void {
+    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/src/vfs/path.ts

@@ -0,0 +1,71 @@
+/**
+ * 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: string): string {
+  const segments = String(p ?? '').split('/');
+  const out: string[] = [];
+  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: string, cwd: string): string {
+  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: string): string {
+  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: string): string {
+  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: string): string {
+  const base = path.slice(path.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(dot) : '';
+}