@run0/jiki 0.1.0

package/src/container.ts

@@ -0,0 +1,343 @@
+import { MemFS } from "./memfs";
+import { Kernel, RuntimeOptions } from "./kernel";
+import {
+  PackageManager,
+  InstallOptions,
+  InstallResult,
+  NpmLayout,
+} from "./npm/index";
+import { PnpmLayout } from "./npm/pnpm";
+import { Shell, ShellOptions, createShell } from "./shell";
+import type { IExecuteResult, VFSSnapshot } from "./runtime-interface";
+import * as pathShim from "./polyfills/path";
+import { base64ToUint8 } from "./utils/binary-encoding";
+import {
+  setStreamingCallbacks,
+  clearStreamingCallbacks,
+  sendStdin,
+} from "./polyfills/child_process";
+import { SyncAutoInstaller } from "./npm/sync-installer";
+import { PluginRegistry, type JikiPlugin } from "./plugin";
+import type { PersistenceAdapter } from "./persistence";
+import {
+  registerBuiltin,
+  registerBuiltins,
+  unregisterBuiltin,
+} from "./builtins";
+import { shouldUseWorker, type WorkerMode } from "./worker-runtime";
+import { SandboxGuard, type SandboxOptions } from "./sandbox";
+import { Metrics } from "./metrics";
+import { NetworkInterceptor, type MockResponse } from "./network-interceptor";
+
+export interface ContainerOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  registry?: string;
+  /** `'npm'` (default) or `'pnpm'` */
+  packageManager?: "npm" | "pnpm";
+  /** Automatically install missing packages on require() */
+  autoInstall?: boolean;
+  onConsole?: (method: string, args: unknown[]) => void;
+  onStdout?: (data: string) => void;
+  onStderr?: (data: string) => void;
+  /** Plugins to register on this container. */
+  plugins?: JikiPlugin[];
+  /** Persistence adapter for surviving page refreshes. */
+  persistence?: PersistenceAdapter;
+  /** Enable inline source maps for TypeScript/JSX transpilation (default: false). */
+  sourceMaps?: boolean;
+  /**
+   * Worker mode for CPU-intensive operations.
+   * - `false` (default) — everything on the main thread
+   * - `true` — transpilation runs in a Web Worker
+   * - `'auto'` — use workers when available (browser), skip in Node.js
+   */
+  worker?: boolean | "auto";
+  /** Resource limits and access controls. */
+  sandbox?: SandboxOptions;
+}
+
+export interface RunOptions extends ShellOptions {
+  signal?: AbortSignal;
+}
+
+export interface RunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export class Container {
+  readonly vfs: MemFS;
+  readonly runtime: Kernel;
+  readonly packageManager: PackageManager;
+  readonly shell: Shell;
+  /** Plugin registry for this container. */
+  readonly plugins: PluginRegistry;
+  /** Sandbox guard enforcing resource limits. */
+  readonly sandbox: SandboxGuard;
+  /** Performance metrics for this container. */
+  readonly metrics: Metrics;
+  /** Network request interceptor for mocking fetch calls. */
+  readonly network: NetworkInterceptor;
+  private _pnpmPm?: PackageManager;
+  private _containerCwd: string;
+  private _containerRegistry?: string;
+  private _workerMode: WorkerMode;
+
+  constructor(options: ContainerOptions = {}) {
+    const cwd = options.cwd || "/";
+    const usePnpm = options.packageManager === "pnpm";
+    this._containerCwd = cwd;
+    this._containerRegistry = options.registry;
+    this._workerMode = options.worker ?? false;
+
+    // Initialise plugin registry, sandbox, and metrics before other subsystems.
+    this.plugins = new PluginRegistry();
+    this.sandbox = new SandboxGuard(options.sandbox || {});
+    this.metrics = new Metrics();
+    this.network = new NetworkInterceptor();
+    if (options.plugins) {
+      for (const p of options.plugins) this.plugins.register(p);
+    }
+
+    this.vfs = new MemFS({
+      persistence: options.persistence,
+      sandbox: this.sandbox,
+    });
+
+    const layout = usePnpm ? new PnpmLayout() : new NpmLayout();
+    this.packageManager = new PackageManager(this.vfs, {
+      cwd,
+      registry: options.registry,
+      layout,
+    });
+
+    const autoInstallProvider = options.autoInstall
+      ? new SyncAutoInstaller(this.vfs, layout, {
+          cwd,
+          registry: options.registry,
+        })
+      : undefined;
+
+    this.runtime = new Kernel(
+      this.vfs,
+      {
+        cwd,
+        env: options.env,
+        onConsole: options.onConsole,
+        onStdout: options.onStdout,
+        onStderr: options.onStderr,
+        autoInstall: options.autoInstall,
+        autoInstallProvider,
+        sourceMaps: options.sourceMaps,
+      },
+      this.plugins,
+    );
+
+    if (usePnpm) {
+      this._pnpmPm = this.packageManager;
+    }
+
+    this.shell = createShell(this.vfs, this.runtime, this.packageManager, {
+      cwd,
+      env: options.env,
+      onStdout: options.onStdout,
+      onStderr: options.onStderr,
+      pnpmPm: usePnpm ? this.packageManager : undefined,
+      lazyPnpmPm: usePnpm ? undefined : () => this.lazyPnpmPm,
+    });
+
+    // Register plugin-provided shell commands.
+    for (const entry of this.plugins.getCommandHooks()) {
+      this.shell.registerCommand(entry.name, entry.handler);
+    }
+  }
+
+  private get lazyPnpmPm(): PackageManager {
+    if (!this._pnpmPm) {
+      this._pnpmPm = new PackageManager(this.vfs, {
+        cwd: this._containerCwd,
+        registry: this._containerRegistry,
+        layout: new PnpmLayout(),
+      });
+    }
+    return this._pnpmPm;
+  }
+
+  async init(options?: { wasmURL?: string | URL }): Promise<void> {
+    await this.vfs.hydrate();
+    await this.runtime.init({
+      ...options,
+      useWorker: shouldUseWorker(this._workerMode),
+    });
+    this.plugins.runBoot();
+  }
+
+  writeFile(path: string, content: string | Uint8Array): void {
+    const dir = pathShim.dirname(path);
+    if (dir !== "/" && !this.vfs.existsSync(dir)) {
+      this.vfs.mkdirSync(dir, { recursive: true });
+    }
+    // Sandbox checks are enforced at the VFS level (MemFS.putFile)
+    // so they apply to all write paths: Container, Shell, executed code.
+    this.vfs.writeFileSync(path, content);
+    this.metrics.trackWrite();
+  }
+
+  readFile(path: string): string;
+  readFile(path: string, encoding: null): Uint8Array;
+  readFile(path: string, encoding?: null): string | Uint8Array {
+    this.metrics.trackRead();
+    return encoding === null
+      ? this.vfs.readFileSync(path)
+      : this.vfs.readFileSync(path, "utf8");
+  }
+
+  mkdir(path: string): void {
+    this.vfs.mkdirSync(path, { recursive: true });
+  }
+  readdir(path: string): string[] {
+    return this.vfs.readdirSync(path);
+  }
+  exists(path: string): boolean {
+    return this.vfs.existsSync(path);
+  }
+  rm(path: string): void {
+    this.vfs.rmSync(path, { recursive: true, force: true });
+  }
+
+  execute(code: string, filename?: string): IExecuteResult {
+    return this.runtime.execute(code, filename);
+  }
+
+  runFile(filename: string): IExecuteResult {
+    return this.runtime.runFile(filename);
+  }
+
+  async run(command: string, options?: RunOptions): Promise<RunResult> {
+    this.metrics.trackCommand();
+    if (options?.onStdout || options?.onStderr || options?.signal) {
+      setStreamingCallbacks({
+        onStdout: options.onStdout,
+        onStderr: options.onStderr,
+        signal: options.signal,
+      });
+    }
+    try {
+      return await this.shell.exec(command, options);
+    } finally {
+      clearStreamingCallbacks();
+    }
+  }
+
+  sendInput(data: string): void {
+    sendStdin(data);
+    // Also push to process.stdin so readline/inquirer can receive it.
+    (this.runtime.process.stdin as any)?._push?.(data);
+  }
+
+  /** Register a custom polyfill for a built-in module. */
+  registerPolyfill(name: string, factory: () => unknown): void {
+    registerBuiltin(name, factory);
+  }
+
+  /** Register multiple custom polyfills at once. */
+  registerPolyfills(map: Record<string, () => unknown>): void {
+    registerBuiltins(map);
+  }
+
+  /** Unregister a custom polyfill. */
+  unregisterPolyfill(name: string): void {
+    unregisterBuiltin(name);
+  }
+
+  /** Mock a fetch URL with a static response. */
+  mockFetch(pattern: string | RegExp, response: MockResponse): void {
+    this.network.mock(pattern, response);
+  }
+
+  /** Register a dynamic fetch interceptor. */
+  onFetch(
+    handler: (
+      url: string,
+      init?: RequestInit,
+    ) =>
+      | MockResponse
+      | null
+      | undefined
+      | Promise<MockResponse | null | undefined>,
+  ): void {
+    this.network.onFetch(handler);
+  }
+
+  /** Get a snapshot of performance metrics. */
+  getMetrics() {
+    return this.metrics.snapshot();
+  }
+
+  async install(
+    packages: string | string[],
+    options?: InstallOptions,
+  ): Promise<InstallResult> {
+    const start = Date.now();
+    const result = await this.packageManager.install(packages, options);
+    this.metrics.trackInstall(Date.now() - start);
+    const names = Array.isArray(packages) ? packages : [packages];
+    this.plugins.runInstall(names);
+    return result;
+  }
+
+  async installDependencies(options?: InstallOptions): Promise<InstallResult> {
+    const result = await this.packageManager.installFromPackageJson(options);
+    this.plugins.runInstall([]);
+    return result;
+  }
+
+  toSnapshot(): VFSSnapshot {
+    return this.vfs.toSnapshot();
+  }
+
+  static fromSnapshot(
+    snapshot: VFSSnapshot,
+    options?: ContainerOptions,
+  ): Container {
+    const container = new Container(options);
+
+    for (const entry of snapshot.files) {
+      if (entry.path === "/") continue;
+      if (entry.type === "directory") {
+        container.vfs.mkdirSync(entry.path, { recursive: true });
+      } else if (entry.type === "file" && entry.content) {
+        const dir = pathShim.dirname(entry.path);
+        if (dir !== "/") container.vfs.mkdirSync(dir, { recursive: true });
+        container.vfs.writeFileSync(entry.path, base64ToUint8(entry.content));
+      } else if (entry.type === "symlink" && entry.target) {
+        container.vfs.symlinkSync(entry.target, entry.path);
+      }
+    }
+    return container;
+  }
+
+  export(path = "/"): Record<string, unknown> {
+    return this.vfs.export(path);
+  }
+
+  destroy(): void {
+    this.runtime.clearCache();
+  }
+}
+
+/** Register a plugin on an existing container (post-construction). */
+export function registerPlugin(container: Container, plugin: JikiPlugin): void {
+  container.plugins.register(plugin);
+  for (const entry of container.plugins.getCommandHooks()) {
+    container.shell.registerCommand(entry.name, entry.handler);
+  }
+}
+
+export function boot(options?: ContainerOptions): Container {
+  return new Container(options);
+}
+
+export { boot as createContainer };

package/src/dev-server.ts

@@ -0,0 +1,322 @@
+import { EventEmitter } from "./polyfills/events";
+import { MemFS } from "./memfs";
+import { BufferImpl as Buffer } from "./polyfills/stream";
+import { safePath } from "./utils/safe-path";
+
+export interface DevServerOptions {
+  port: number;
+  root?: string;
+}
+
+export interface ResponseData {
+  statusCode: number;
+  statusMessage: string;
+  headers: Record<string, string>;
+  body: Buffer;
+}
+
+export interface HMRUpdate {
+  type: "update" | "full-reload";
+  path: string;
+  timestamp?: number;
+}
+
+/**
+ * Check if a filename contains a content hash (e.g., app.a1b2c3d4.js, chunk-HASH.css).
+ * Content-hashed files are safe to cache immutably since the hash changes when content changes.
+ */
+function hasContentHash(filepath: string): boolean {
+  // Match patterns like: file.abc123ef.js, file-abc123ef.css, file.ABCDEF01.chunk.js
+  // The hash segment should be 8+ hex characters between dots or after a dash before the extension
+  return /[.\-][a-fA-F0-9]{8,}[.\-]/.test(filepath);
+}
+
+/**
+ * Determine the appropriate Cache-Control header for a given file path.
+ * - Content-hashed assets get immutable caching (1 year)
+ * - HTML and non-hashed assets get no-cache for development freshness
+ */
+function inferCacheControl(filepath: string): string {
+  const ext = filepath.split(".").pop()?.toLowerCase() || "";
+  // HTML files should never be cached immutably
+  if (ext === "html" || ext === "htm") {
+    return "no-cache";
+  }
+  // Content-hashed files are safe to cache immutably
+  if (hasContentHash(filepath)) {
+    return "public, max-age=31536000, immutable";
+  }
+  return "no-cache";
+}
+
+function inferMimeType(filepath: string): string {
+  const ext = filepath.split(".").pop()?.toLowerCase() || "";
+  switch (ext) {
+    case "html":
+    case "htm":
+      return "text/html; charset=utf-8";
+    case "css":
+      return "text/css; charset=utf-8";
+    case "js":
+    case "mjs":
+    case "cjs":
+    case "jsx":
+    case "ts":
+    case "tsx":
+      return "application/javascript; charset=utf-8";
+    case "json":
+    case "map":
+      return "application/json; charset=utf-8";
+    case "png":
+      return "image/png";
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "gif":
+      return "image/gif";
+    case "svg":
+      return "image/svg+xml";
+    case "ico":
+      return "image/x-icon";
+    case "webp":
+      return "image/webp";
+    case "woff":
+      return "font/woff";
+    case "woff2":
+      return "font/woff2";
+    case "ttf":
+      return "font/ttf";
+    case "otf":
+      return "font/otf";
+    case "mp3":
+      return "audio/mpeg";
+    case "wav":
+      return "audio/wav";
+    case "mp4":
+      return "video/mp4";
+    case "webm":
+      return "video/webm";
+    case "pdf":
+      return "application/pdf";
+    case "xml":
+      return "application/xml";
+    case "txt":
+      return "text/plain; charset=utf-8";
+    case "md":
+      return "text/markdown; charset=utf-8";
+    case "wasm":
+      return "application/wasm";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+interface FileContent {
+  path: string;
+  data: Uint8Array;
+  mime: string;
+}
+
+class HttpResponder {
+  static fromContent(fc: FileContent): ResponseData {
+    const buf = Buffer.from(fc.data);
+    return {
+      statusCode: 200,
+      statusMessage: "OK",
+      headers: {
+        "Content-Type": fc.mime,
+        "Content-Length": String(buf.length),
+        "Cache-Control": inferCacheControl(fc.path),
+      },
+      body: buf,
+    };
+  }
+
+  static text(code: number, statusMsg: string, body: string): ResponseData {
+    const buf = Buffer.from(body);
+    return {
+      statusCode: code,
+      statusMessage: statusMsg,
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Content-Length": String(buf.length),
+      },
+      body: buf,
+    };
+  }
+
+  static redirect(
+    location: string,
+    status: 301 | 302 | 307 | 308 = 302,
+  ): ResponseData {
+    const labels: Record<number, string> = {
+      301: "Moved Permanently",
+      302: "Found",
+      307: "Temporary Redirect",
+      308: "Permanent Redirect",
+    };
+    return {
+      statusCode: status,
+      statusMessage: labels[status] || "Found",
+      headers: {
+        Location: location,
+        "Content-Type": "text/plain; charset=utf-8",
+        "Content-Length": "0",
+      },
+      body: Buffer.from(""),
+    };
+  }
+}
+
+export abstract class DevServer extends EventEmitter {
+  protected vfs: MemFS;
+  protected port: number;
+  protected root: string;
+  protected running = false;
+
+  constructor(vfs: MemFS, options: DevServerOptions) {
+    super();
+    this.vfs = vfs;
+    this.port = options.port;
+    this.root = options.root || "/";
+  }
+
+  abstract handleRequest(
+    method: string,
+    url: string,
+    headers: Record<string, string>,
+    body?: Buffer,
+  ): Promise<ResponseData>;
+
+  abstract startWatching(): void;
+
+  /**
+   * CORS headers added to all responses for cross-origin iframe support.
+   * This is essential since the dev server is typically accessed from
+   * a sandboxed iframe on a different origin.
+   */
+  private static readonly CORS_HEADERS: Record<string, string> = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+    "Access-Control-Allow-Headers":
+      "Content-Type, Authorization, X-Requested-With",
+    "Access-Control-Max-Age": "86400",
+  };
+
+  /**
+   * Add CORS headers to a response.
+   */
+  protected addCorsHeaders(response: ResponseData): ResponseData {
+    return {
+      ...response,
+      headers: { ...response.headers, ...DevServer.CORS_HEADERS },
+    };
+  }
+
+  /**
+   * Handle CORS preflight OPTIONS requests.
+   */
+  protected handleOptionsRequest(): ResponseData {
+    return {
+      statusCode: 204,
+      statusMessage: "No Content",
+      headers: {
+        ...DevServer.CORS_HEADERS,
+        "Content-Length": "0",
+      },
+      body: Buffer.from(""),
+    };
+  }
+
+  stop(): void {
+    this.running = false;
+    this.emit("close");
+  }
+
+  start(): void {
+    this.running = true;
+    this.startWatching();
+    this.emit("listening", this.port);
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+  getPort(): number {
+    return this.port;
+  }
+
+  protected serveFile(filePath: string): ResponseData {
+    const resolved = this.resolvePath(filePath);
+    let raw: Uint8Array;
+    try {
+      raw = this.vfs.readFileSync(resolved);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return this.notFound(filePath);
+      }
+      return this.serverError(err);
+    }
+    return HttpResponder.fromContent({
+      path: resolved,
+      data: raw,
+      mime: this.getMimeType(filePath),
+    });
+  }
+
+  protected resolvePath(urlPath: string): string {
+    return safePath(this.root, urlPath);
+  }
+
+  protected notFound(path: string): ResponseData {
+    return HttpResponder.text(404, "Not Found", `Not found: ${path}`);
+  }
+
+  protected serverError(error: unknown): ResponseData {
+    const msg =
+      error instanceof Error ? error.message : "Internal Server Error";
+    return HttpResponder.text(
+      500,
+      "Internal Server Error",
+      `Server Error: ${msg}`,
+    );
+  }
+
+  protected redirect(
+    location: string,
+    status: 301 | 302 | 307 | 308 = 302,
+  ): ResponseData {
+    return HttpResponder.redirect(location, status);
+  }
+
+  protected getMimeType(path: string): string {
+    return inferMimeType(path);
+  }
+
+  protected exists(path: string): boolean {
+    return this.vfs.existsSync(path);
+  }
+
+  protected isDirectory(path: string): boolean {
+    try {
+      return this.vfs.statSync(path).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  protected broadcastChange(update: HMRUpdate): void {
+    this.emit("hmr-update", {
+      ...update,
+      timestamp: update.timestamp || Date.now(),
+    });
+  }
+
+  /** @deprecated Use broadcastChange instead */
+  protected emitHMRUpdate(update: HMRUpdate): void {
+    this.broadcastChange(update);
+  }
+}
+
+export { hasContentHash, inferCacheControl };
+export default DevServer;