@run0/jiki 0.1.0

package/src/persistence.ts

@@ -0,0 +1,235 @@
+/**
+ * Persistence layer for MemFS.
+ *
+ * Provides a `PersistenceAdapter` interface and an `IndexedDBAdapter`
+ * implementation that synchronises the in-memory filesystem to IndexedDB.
+ *
+ * Writes are fire-and-forget — they never block the synchronous VFS API.
+ * Mutations are batched and flushed via microtask debounce (~100 ms) so
+ * rapid consecutive writes result in a single IndexedDB transaction.
+ *
+ * @example
+ * ```ts
+ * const adapter = new IndexedDBAdapter('my-project');
+ * const vfs = new MemFS({ persistence: adapter });
+ * await vfs.hydrate(); // load persisted state
+ * vfs.writeFileSync('/hello.txt', 'world'); // auto-persisted
+ * ```
+ */
+
+import type { FSNode } from "./memfs";
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+/** Serialised form of a single filesystem entry stored in the adapter. */
+export interface PersistedEntry {
+  path: string;
+  type: "file" | "directory" | "symlink";
+  /** File content as Uint8Array. Only set for type === "file". */
+  content?: Uint8Array;
+  /** Symlink target. Only set for type === "symlink". */
+  target?: string;
+  mtime: number;
+}
+
+/**
+ * Backend-agnostic interface for persisting MemFS state.
+ * Implement this to plug in any storage backend (IndexedDB, OPFS,
+ * localStorage, etc.).
+ */
+export interface PersistenceAdapter {
+  /** Persist a single entry (upsert by path). */
+  save(entry: PersistedEntry): void;
+  /** Delete a persisted entry by path. */
+  delete(path: string): void;
+  /** Load all persisted entries. */
+  loadAll(): Promise<PersistedEntry[]>;
+  /** Delete all persisted entries. */
+  clear(): Promise<void>;
+  /** Flush any pending writes immediately. Returns when the flush completes. */
+  flush(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// IndexedDB adapter
+// ---------------------------------------------------------------------------
+
+/** Options for the IndexedDB adapter. */
+export interface IndexedDBAdapterOptions {
+  /** IndexedDB database name. Defaults to `"jiki-vfs"`. */
+  dbName?: string;
+  /** Object store name. Defaults to `"files"`. */
+  storeName?: string;
+  /** Batch flush interval in milliseconds. Defaults to 100. */
+  flushIntervalMs?: number;
+}
+
+/**
+ * Persists MemFS entries to IndexedDB.
+ *
+ * Mutations are batched into a queue and flushed periodically (default
+ * every 100 ms) in a single readwrite transaction for performance.
+ */
+export class IndexedDBAdapter implements PersistenceAdapter {
+  private dbName: string;
+  private storeName: string;
+  private flushIntervalMs: number;
+  private db: IDBDatabase | null = null;
+  private queue: Array<
+    { type: "save"; entry: PersistedEntry } | { type: "delete"; path: string }
+  > = [];
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private flushPromise: Promise<void> | null = null;
+
+  constructor(options: IndexedDBAdapterOptions = {}) {
+    this.dbName = options.dbName ?? "jiki-vfs";
+    this.storeName = options.storeName ?? "files";
+    this.flushIntervalMs = options.flushIntervalMs ?? 100;
+  }
+
+  private async openDB(): Promise<IDBDatabase> {
+    if (this.db) return this.db;
+    return new Promise<IDBDatabase>((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, 1);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName, { keyPath: "path" });
+        }
+      };
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve(this.db);
+      };
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  save(entry: PersistedEntry): void {
+    this.queue.push({ type: "save", entry });
+    this.scheduleFlush();
+  }
+
+  delete(path: string): void {
+    this.queue.push({ type: "delete", path });
+    this.scheduleFlush();
+  }
+
+  async loadAll(): Promise<PersistedEntry[]> {
+    const db = await this.openDB();
+    return new Promise<PersistedEntry[]>((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readonly");
+      const store = tx.objectStore(this.storeName);
+      const request = store.getAll();
+      request.onsuccess = () => resolve(request.result as PersistedEntry[]);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async clear(): Promise<void> {
+    const db = await this.openDB();
+    return new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      const request = store.clear();
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async flush(): Promise<void> {
+    if (this.flushTimer !== null) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.queue.length === 0) return;
+
+    const batch = this.queue.splice(0);
+    const db = await this.openDB();
+
+    return new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+
+      for (const op of batch) {
+        if (op.type === "save") {
+          store.put(op.entry);
+        } else {
+          store.delete(op.path);
+        }
+      }
+
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer !== null) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flushPromise = this.flush().catch(err => {
+        console.error("[jiki:persistence] flush failed:", err);
+      });
+    }, this.flushIntervalMs);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// In-memory adapter (for testing and non-browser environments)
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory adapter that stores entries in a `Map`.
+ * Useful for tests and server-side usage where IndexedDB is unavailable.
+ */
+export class InMemoryAdapter implements PersistenceAdapter {
+  private store = new Map<string, PersistedEntry>();
+
+  save(entry: PersistedEntry): void {
+    this.store.set(entry.path, entry);
+  }
+
+  delete(path: string): void {
+    this.store.delete(path);
+  }
+
+  async loadAll(): Promise<PersistedEntry[]> {
+    return Array.from(this.store.values());
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+
+  async flush(): Promise<void> {
+    // No-op — writes are synchronous in memory.
+  }
+
+  /** Return the number of stored entries (test helper). */
+  get size(): number {
+    return this.store.size;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: convert FSNode ↔ PersistedEntry
+// ---------------------------------------------------------------------------
+
+/** Convert an FSNode at the given path to a PersistedEntry. */
+export function nodeToEntry(path: string, node: FSNode): PersistedEntry {
+  const entry: PersistedEntry = {
+    path,
+    type: node.type,
+    mtime: node.mtime,
+  };
+  if (node.type === "file" && node.content) {
+    entry.content = node.content;
+  }
+  if (node.type === "symlink" && node.target) {
+    entry.target = node.target;
+  }
+  return entry;
+}

package/src/plugin.ts

@@ -0,0 +1,293 @@
+/**
+ * Plugin system for jiki.
+ *
+ * Provides lifecycle hooks that let external code intercept and extend
+ * jiki's behaviour at key points: module resolution, module loading,
+ * code transformation, shell command registration, package installation,
+ * and container boot.
+ *
+ * The API mirrors esbuild's plugin conventions so it feels familiar to
+ * most JavaScript developers.
+ *
+ * @example
+ * ```ts
+ * const myPlugin: JikiPlugin = {
+ *   name: 'my-plugin',
+ *   setup(hooks) {
+ *     hooks.onResolve(/^virtual:/, (args) => ({
+ *       path: `/virtual/${args.path.slice(8)}`,
+ *     }));
+ *     hooks.onLoad(/^\/virtual\//, (args) => ({
+ *       contents: `module.exports = "hello from ${args.path}";`,
+ *     }));
+ *   },
+ * };
+ *
+ * const container = boot({ plugins: [myPlugin] });
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Arguments passed to an `onResolve` callback. */
+export interface OnResolveArgs {
+  /** The raw module specifier (e.g. `"virtual:config"` or `"./foo"`). */
+  path: string;
+  /** Directory the import originates from. */
+  resolveDir: string;
+}
+
+/** Return value from an `onResolve` callback. */
+export interface OnResolveResult {
+  /** Resolved absolute path. Returning this skips the default resolver. */
+  path: string;
+}
+
+/** Arguments passed to an `onLoad` callback. */
+export interface OnLoadArgs {
+  /** The fully-resolved module path. */
+  path: string;
+}
+
+/** Return value from an `onLoad` callback. */
+export interface OnLoadResult {
+  /** Source code to use instead of reading from the VFS. */
+  contents: string;
+}
+
+/** Arguments passed to an `onTransform` callback. */
+export interface OnTransformArgs {
+  /** The fully-resolved file path. */
+  path: string;
+  /** Source code *after* previous transforms in the pipeline. */
+  contents: string;
+}
+
+/** Return value from an `onTransform` callback. */
+export interface OnTransformResult {
+  /** Transformed source code. */
+  contents: string;
+}
+
+/** Callback types for lifecycle hooks. */
+export type OnResolveCallback = (
+  args: OnResolveArgs,
+) => OnResolveResult | null | undefined | void;
+export type OnLoadCallback = (
+  args: OnLoadArgs,
+) => OnLoadResult | null | undefined | void;
+export type OnTransformCallback = (
+  args: OnTransformArgs,
+) => OnTransformResult | null | undefined | void;
+export type OnInstallCallback = (packages: string[]) => void;
+export type OnBootCallback = () => void;
+
+import type { CommandHandler } from "./shell";
+
+/** Hook registration API handed to {@link JikiPlugin.setup}. */
+export interface PluginHooks {
+  /**
+   * Intercept module resolution.  The first callback whose `filter` matches
+   * **and** returns a non-null result wins — later callbacks are skipped.
+   */
+  onResolve(filter: RegExp, callback: OnResolveCallback): void;
+  /**
+   * Intercept module loading.  The first callback whose `filter` matches
+   * **and** returns a non-null result wins — later callbacks are skipped.
+   */
+  onLoad(filter: RegExp, callback: OnLoadCallback): void;
+  /**
+   * Intercept code transformation.  Unlike resolve/load, this is a
+   * **pipeline**: every matching callback runs in registration order,
+   * each receiving the output of the previous one.
+   */
+  onTransform(filter: RegExp, callback: OnTransformCallback): void;
+  /** Register a custom shell command. */
+  onCommand(name: string, handler: CommandHandler): void;
+  /** Called after packages are installed. */
+  onInstall(callback: OnInstallCallback): void;
+  /** Called after the container is fully initialised. */
+  onBoot(callback: OnBootCallback): void;
+}
+
+/** A jiki plugin. */
+export interface JikiPlugin {
+  /** Human-readable name (used in error messages and debugging). */
+  name: string;
+  /** Called once during container construction. Register hooks here. */
+  setup(hooks: PluginHooks): void;
+}
+
+// ---------------------------------------------------------------------------
+// Internal registry
+// ---------------------------------------------------------------------------
+
+interface ResolveEntry {
+  filter: RegExp;
+  callback: OnResolveCallback;
+  plugin: string;
+}
+interface LoadEntry {
+  filter: RegExp;
+  callback: OnLoadCallback;
+  plugin: string;
+}
+interface TransformEntry {
+  filter: RegExp;
+  callback: OnTransformCallback;
+  plugin: string;
+}
+interface CommandEntry {
+  name: string;
+  handler: CommandHandler;
+  plugin: string;
+}
+interface InstallEntry {
+  callback: OnInstallCallback;
+  plugin: string;
+}
+interface BootEntry {
+  callback: OnBootCallback;
+  plugin: string;
+}
+
+/**
+ * Central registry that collects hooks from all plugins and exposes
+ * methods for the runtime to invoke them.
+ *
+ * Intentionally not a singleton — each {@link Container} gets its own
+ * `PluginRegistry` so plugins cannot leak between containers.
+ */
+export class PluginRegistry {
+  private resolveHooks: ResolveEntry[] = [];
+  private loadHooks: LoadEntry[] = [];
+  private transformHooks: TransformEntry[] = [];
+  private commandHooks: CommandEntry[] = [];
+  private installHooks: InstallEntry[] = [];
+  private bootHooks: BootEntry[] = [];
+
+  /** True if at least one plugin has been registered. */
+  get hasPlugins(): boolean {
+    return (
+      this.resolveHooks.length > 0 ||
+      this.loadHooks.length > 0 ||
+      this.transformHooks.length > 0 ||
+      this.commandHooks.length > 0 ||
+      this.installHooks.length > 0 ||
+      this.bootHooks.length > 0
+    );
+  }
+
+  /** Number of registered resolve hooks. */
+  get resolveHookCount(): number {
+    return this.resolveHooks.length;
+  }
+  /** Number of registered load hooks. */
+  get loadHookCount(): number {
+    return this.loadHooks.length;
+  }
+  /** Number of registered transform hooks. */
+  get transformHookCount(): number {
+    return this.transformHooks.length;
+  }
+  /** Number of registered command hooks. */
+  get commandHookCount(): number {
+    return this.commandHooks.length;
+  }
+
+  // -- Registration ---------------------------------------------------------
+
+  /** Register all hooks from a single plugin. */
+  register(plugin: JikiPlugin): void {
+    const hooks: PluginHooks = {
+      onResolve: (filter, callback) => {
+        this.resolveHooks.push({ filter, callback, plugin: plugin.name });
+      },
+      onLoad: (filter, callback) => {
+        this.loadHooks.push({ filter, callback, plugin: plugin.name });
+      },
+      onTransform: (filter, callback) => {
+        this.transformHooks.push({ filter, callback, plugin: plugin.name });
+      },
+      onCommand: (name, handler) => {
+        this.commandHooks.push({ name, handler, plugin: plugin.name });
+      },
+      onInstall: callback => {
+        this.installHooks.push({ callback, plugin: plugin.name });
+      },
+      onBoot: callback => {
+        this.bootHooks.push({ callback, plugin: plugin.name });
+      },
+    };
+    plugin.setup(hooks);
+  }
+
+  // -- Invocation -----------------------------------------------------------
+
+  /**
+   * Run resolve hooks.  First matching callback that returns a result wins.
+   * Returns `null` if no plugin handled the specifier.
+   */
+  runResolve(path: string, resolveDir: string): OnResolveResult | null {
+    for (const entry of this.resolveHooks) {
+      if (entry.filter.test(path)) {
+        const result = entry.callback({ path, resolveDir });
+        if (result && result.path) return result;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Run load hooks.  First matching callback that returns a result wins.
+   * Returns `null` if no plugin provided contents.
+   */
+  runLoad(path: string): OnLoadResult | null {
+    for (const entry of this.loadHooks) {
+      if (entry.filter.test(path)) {
+        const result = entry.callback({ path });
+        if (result && result.contents !== undefined) return result;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Run transform hooks as a pipeline.
+   * Every matching callback runs in order, each receiving the output of the
+   * previous one.  Returns the final transformed source.
+   */
+  runTransform(path: string, contents: string): string {
+    let current = contents;
+    for (const entry of this.transformHooks) {
+      if (entry.filter.test(path)) {
+        const result = entry.callback({ path, contents: current });
+        if (result && result.contents !== undefined) {
+          current = result.contents;
+        }
+      }
+    }
+    return current;
+  }
+
+  /** Return all command hooks so the shell can register them. */
+  getCommandHooks(): CommandEntry[] {
+    return this.commandHooks;
+  }
+
+  /** Notify all install hooks. */
+  runInstall(packages: string[]): void {
+    for (const entry of this.installHooks) {
+      entry.callback(packages);
+    }
+  }
+
+  /** Notify all boot hooks. */
+  runBoot(): void {
+    for (const entry of this.bootHooks) {
+      entry.callback();
+    }
+  }
+}

package/src/polyfills/assert.ts

@@ -0,0 +1,164 @@
+import { isDeepStrictEqual } from "./util";
+
+class AssertionError extends Error {
+  actual: unknown;
+  expected: unknown;
+  operator: string;
+  constructor(
+    message: string,
+    actual?: unknown,
+    expected?: unknown,
+    operator?: string,
+  ) {
+    super(message);
+    this.name = "AssertionError";
+    this.actual = actual;
+    this.expected = expected;
+    this.operator = operator || "";
+  }
+}
+
+function assert(value: unknown, message?: string): asserts value {
+  if (!value)
+    throw new AssertionError(
+      message || `Expected truthy value, got ${value}`,
+      value,
+      true,
+      "==",
+    );
+}
+
+assert.ok = assert;
+assert.equal = (actual: unknown, expected: unknown, message?: string) => {
+  if (actual != expected)
+    throw new AssertionError(
+      message || `${actual} != ${expected}`,
+      actual,
+      expected,
+      "==",
+    );
+};
+assert.notEqual = (actual: unknown, expected: unknown, message?: string) => {
+  if (actual == expected)
+    throw new AssertionError(
+      message || `${actual} == ${expected}`,
+      actual,
+      expected,
+      "!=",
+    );
+};
+assert.strictEqual = (actual: unknown, expected: unknown, message?: string) => {
+  if (actual !== expected)
+    throw new AssertionError(
+      message || `${actual} !== ${expected}`,
+      actual,
+      expected,
+      "===",
+    );
+};
+assert.notStrictEqual = (
+  actual: unknown,
+  expected: unknown,
+  message?: string,
+) => {
+  if (actual === expected)
+    throw new AssertionError(
+      message || `${actual} === ${expected}`,
+      actual,
+      expected,
+      "!==",
+    );
+};
+assert.deepEqual = (actual: unknown, expected: unknown, message?: string) => {
+  if (!isDeepStrictEqual(actual, expected))
+    throw new AssertionError(
+      message || "Values not deep equal",
+      actual,
+      expected,
+      "deepEqual",
+    );
+};
+assert.deepStrictEqual = assert.deepEqual;
+assert.notDeepEqual = (
+  actual: unknown,
+  expected: unknown,
+  message?: string,
+) => {
+  if (isDeepStrictEqual(actual, expected))
+    throw new AssertionError(
+      message || "Values are deep equal",
+      actual,
+      expected,
+      "notDeepEqual",
+    );
+};
+assert.notDeepStrictEqual = assert.notDeepEqual;
+assert.throws = (
+  fn: () => void,
+  errorOrMessage?: unknown,
+  message?: string,
+) => {
+  let threw = false;
+  try {
+    fn();
+  } catch {
+    threw = true;
+  }
+  if (!threw)
+    throw new AssertionError(
+      typeof errorOrMessage === "string"
+        ? errorOrMessage
+        : message || "Expected function to throw",
+    );
+};
+assert.doesNotThrow = (fn: () => void, message?: string) => {
+  try {
+    fn();
+  } catch (e) {
+    throw new AssertionError(message || `Function threw: ${e}`);
+  }
+};
+assert.rejects = async (
+  fn: (() => Promise<unknown>) | Promise<unknown>,
+  message?: string,
+) => {
+  try {
+    await (typeof fn === "function" ? fn() : fn);
+  } catch {
+    return;
+  }
+  throw new AssertionError(
+    typeof message === "string" ? message : "Expected promise to reject",
+  );
+};
+assert.doesNotReject = async (
+  fn: (() => Promise<unknown>) | Promise<unknown>,
+  message?: string,
+) => {
+  try {
+    await (typeof fn === "function" ? fn() : fn);
+  } catch (e) {
+    throw new AssertionError(
+      typeof message === "string" ? message : `Promise rejected: ${e}`,
+    );
+  }
+};
+assert.ifError = (value: unknown) => {
+  if (value) throw value;
+};
+assert.fail = (message?: string) => {
+  throw new AssertionError(message || "Failed");
+};
+assert.match = (string: string, regexp: RegExp, message?: string) => {
+  if (!regexp.test(string))
+    throw new AssertionError(message || `${string} does not match ${regexp}`);
+};
+assert.doesNotMatch = (string: string, regexp: RegExp, message?: string) => {
+  if (regexp.test(string))
+    throw new AssertionError(message || `${string} matches ${regexp}`);
+};
+assert.AssertionError = AssertionError;
+assert.strict = assert;
+
+export { AssertionError };
+export default assert;