@run0/jiki 0.1.0

package/src/transpiler.ts

@@ -0,0 +1,282 @@
+/**
+ * TypeScript/TSX/JSX transpiler and bundler powered by esbuild-wasm.
+ * Provides lazy initialization with singleton pattern for the WASM runtime.
+ */
+
+import * as esbuild from "esbuild-wasm";
+import type { MemFS } from "./memfs";
+import * as pathShim from "./polyfills/path";
+
+let initialized = false;
+let initializing: Promise<void> | null = null;
+
+export interface TranspileOptions {
+  jsx?: "transform" | "preserve" | "automatic";
+  jsxFactory?: string;
+  jsxFragment?: string;
+  jsxImportSource?: string;
+  target?: string;
+  sourcemap?: boolean;
+}
+
+export interface BundleOptions {
+  entryPoint: string;
+  format?: "esm" | "cjs" | "iife";
+  platform?: "browser" | "node" | "neutral";
+  minify?: boolean;
+  sourcemap?: boolean;
+  target?: string;
+  external?: string[];
+  outfile?: string;
+  loader?: Record<string, string>;
+  define?: Record<string, string>;
+}
+
+export interface BundleResult {
+  code: string;
+  map?: string;
+  errors: esbuild.Message[];
+  warnings: esbuild.Message[];
+}
+
+export interface InitOptions {
+  wasmURL?: string | URL;
+  /** When true, esbuild runs transpilation in a Web Worker (browser only). */
+  useWorker?: boolean;
+}
+
+let customWasmURL: string | URL | undefined;
+
+export function setWasmURL(url: string | URL): void {
+  customWasmURL = url;
+}
+
+function resolveWasmURL(options?: InitOptions): string | URL | undefined {
+  if (options?.wasmURL) return options.wasmURL;
+  if (customWasmURL) return customWasmURL;
+
+  const isBrowser =
+    typeof window !== "undefined" || typeof importScripts === "function";
+  if (!isBrowser) return undefined;
+
+  return "https://unpkg.com/esbuild-wasm@" + esbuild.version + "/esbuild.wasm";
+}
+
+export async function initTranspiler(options?: InitOptions): Promise<void> {
+  if (initialized) return;
+  if (initializing) return initializing;
+
+  const initOpts: esbuild.InitializeOptions = {
+    worker: options?.useWorker ?? false,
+  };
+  const wasmURL = resolveWasmURL(options);
+  if (wasmURL) initOpts.wasmURL = wasmURL;
+
+  initializing = esbuild.initialize(initOpts);
+  await initializing;
+  initialized = true;
+  initializing = null;
+}
+
+export function isInitialized(): boolean {
+  return initialized;
+}
+
+function loaderFromFilename(filename: string): esbuild.Loader {
+  if (filename.endsWith(".tsx")) return "tsx";
+  if (filename.endsWith(".ts")) return "ts";
+  if (filename.endsWith(".jsx")) return "jsx";
+  return "js";
+}
+
+export function needsTranspilation(filename: string): boolean {
+  return (
+    filename.endsWith(".ts") ||
+    filename.endsWith(".tsx") ||
+    filename.endsWith(".jsx")
+  );
+}
+
+export async function transpile(
+  code: string,
+  filename: string,
+  options: TranspileOptions = {},
+): Promise<string> {
+  await initTranspiler();
+
+  const loader = loaderFromFilename(filename);
+  const result = await esbuild.transform(code, {
+    loader,
+    format: "esm",
+    target: options.target || "esnext",
+    sourcemap: options.sourcemap ? "inline" : false,
+    jsx: options.jsx || "automatic",
+    jsxFactory: options.jsxFactory,
+    jsxFragment: options.jsxFragment,
+    jsxImportSource: options.jsxImportSource,
+  });
+
+  return result.code;
+}
+
+const isBrowserEnv =
+  typeof window !== "undefined" || typeof importScripts === "function";
+
+export function hasSyncSupport(): boolean {
+  return !isBrowserEnv;
+}
+
+export function transpileSync(
+  code: string,
+  filename: string,
+  options: TranspileOptions = {},
+): string {
+  if (!initialized) {
+    throw new Error(
+      "Transpiler not initialized. Call initTranspiler() first or use transpile() which auto-initializes.",
+    );
+  }
+
+  if (isBrowserEnv) {
+    throw new Error(
+      "transpileSync is not available in the browser. Use transpile() (async) or prepareFile() to pre-transpile.",
+    );
+  }
+
+  const loader = loaderFromFilename(filename);
+  const result = esbuild.transformSync(code, {
+    loader,
+    format: "esm",
+    target: options.target || "esnext",
+    sourcemap: options.sourcemap ? "inline" : false,
+    jsx: options.jsx || "automatic",
+    jsxFactory: options.jsxFactory,
+    jsxFragment: options.jsxFragment,
+    jsxImportSource: options.jsxImportSource,
+  });
+
+  return result.code;
+}
+
+function createMemFSPlugin(vfs: MemFS, cwd: string): esbuild.Plugin {
+  return {
+    name: "memfs",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, args => {
+        if (args.kind === "entry-point") {
+          const resolved = pathShim.isAbsolute(args.path)
+            ? args.path
+            : pathShim.resolve(cwd, args.path);
+          return { path: resolved, namespace: "memfs" };
+        }
+
+        const resolveDir = args.resolveDir || cwd;
+
+        if (args.path.startsWith(".") || args.path.startsWith("/")) {
+          const base = args.path.startsWith("/")
+            ? args.path
+            : pathShim.resolve(resolveDir, args.path);
+
+          for (const candidate of [
+            base,
+            `${base}.ts`,
+            `${base}.tsx`,
+            `${base}.js`,
+            `${base}.jsx`,
+            `${base}.json`,
+          ]) {
+            if (vfs.existsSync(candidate)) {
+              try {
+                if (vfs.statSync(candidate).isFile()) {
+                  return { path: candidate, namespace: "memfs" };
+                }
+              } catch {}
+            }
+          }
+
+          for (const indexFile of [
+            "index.ts",
+            "index.tsx",
+            "index.js",
+            "index.jsx",
+            "index.json",
+          ]) {
+            const indexPath = pathShim.join(base, indexFile);
+            if (vfs.existsSync(indexPath)) {
+              return { path: indexPath, namespace: "memfs" };
+            }
+          }
+        }
+
+        return { path: args.path, external: true };
+      });
+
+      build.onLoad({ filter: /.*/, namespace: "memfs" }, args => {
+        try {
+          const contents = vfs.readFileSync(args.path, "utf8");
+          return { contents, loader: loaderFromFilename(args.path) };
+        } catch (e) {
+          return {
+            errors: [
+              {
+                text: `File not found: ${args.path}`,
+              } as esbuild.PartialMessage,
+            ],
+          };
+        }
+      });
+    },
+  };
+}
+
+export async function bundle(
+  vfs: MemFS,
+  options: BundleOptions,
+): Promise<BundleResult> {
+  await initTranspiler();
+
+  const cwd = pathShim.dirname(
+    pathShim.isAbsolute(options.entryPoint)
+      ? options.entryPoint
+      : pathShim.resolve("/", options.entryPoint),
+  );
+
+  const result = await esbuild.build({
+    entryPoints: [options.entryPoint],
+    bundle: true,
+    write: false,
+    format: options.format || "esm",
+    platform: options.platform || "browser",
+    minify: options.minify || false,
+    sourcemap: options.sourcemap ? "inline" : false,
+    target: options.target || "esnext",
+    external: options.external,
+    define: options.define,
+    plugins: [createMemFSPlugin(vfs, cwd)],
+  });
+
+  const code = result.outputFiles?.[0]?.text || "";
+
+  if (options.outfile) {
+    const outDir = pathShim.dirname(options.outfile);
+    if (!vfs.existsSync(outDir)) {
+      vfs.mkdirSync(outDir, { recursive: true });
+    }
+    vfs.writeFileSync(options.outfile, code);
+  }
+
+  return {
+    code,
+    errors: result.errors,
+    warnings: result.warnings,
+  };
+}
+
+export async function stopTranspiler(): Promise<void> {
+  if (initialized) {
+    await esbuild.stop();
+    initialized = false;
+  }
+}
+
+export { esbuild };

package/src/type-checker.ts

@@ -0,0 +1,241 @@
+/**
+ * Lightweight TypeScript type-checker for jiki.
+ *
+ * Provides on-demand batch type checking by analyzing TypeScript files
+ * in the VFS. Uses a simple heuristic-based approach that catches common
+ * type errors without requiring the full TypeScript compiler.
+ *
+ * For full type checking, the TypeScript compiler can be installed as an
+ * npm package and run via the shell: `npx tsc --noEmit`.
+ *
+ * @example
+ * ```ts
+ * const checker = new TypeChecker(container.vfs);
+ * const diagnostics = checker.check(['/src/app.ts', '/src/utils.ts']);
+ * for (const d of diagnostics) {
+ *   console.log(`${d.file}:${d.line} - ${d.message}`);
+ * }
+ * ```
+ */
+
+import type { MemFS } from "./memfs";
+import * as pathShim from "./polyfills/path";
+
+export interface Diagnostic {
+  file: string;
+  line: number;
+  column: number;
+  message: string;
+  severity: "error" | "warning" | "info";
+  code?: string;
+}
+
+export interface TypeCheckerOptions {
+  /** Strict mode (default: true). */
+  strict?: boolean;
+  /** Check for unused variables (default: false). */
+  noUnusedLocals?: boolean;
+  /** Check for implicit any (default: true in strict mode). */
+  noImplicitAny?: boolean;
+}
+
+/**
+ * Lightweight TypeScript type-checker that catches common errors
+ * using pattern matching and heuristics. Not a full type system,
+ * but catches the most common mistakes quickly.
+ */
+export class TypeChecker {
+  private vfs: MemFS;
+  private opts: Required<TypeCheckerOptions>;
+
+  constructor(vfs: MemFS, options: TypeCheckerOptions = {}) {
+    this.vfs = vfs;
+    this.opts = {
+      strict: options.strict ?? true,
+      noUnusedLocals: options.noUnusedLocals ?? false,
+      noImplicitAny: options.noImplicitAny ?? options.strict !== false,
+    };
+  }
+
+  /**
+   * Check a list of TypeScript files for common errors.
+   * Returns diagnostics sorted by file and line number.
+   */
+  check(files: string[]): Diagnostic[] {
+    const diagnostics: Diagnostic[] = [];
+
+    for (const file of files) {
+      if (!file.match(/\.(ts|tsx)$/)) continue;
+      try {
+        const source = this.vfs.readFileSync(file, "utf8");
+        diagnostics.push(...this.checkFile(file, source));
+      } catch {
+        diagnostics.push({
+          file,
+          line: 0,
+          column: 0,
+          message: `Cannot read file: ${file}`,
+          severity: "error",
+        });
+      }
+    }
+
+    return diagnostics.sort(
+      (a, b) => a.file.localeCompare(b.file) || a.line - b.line,
+    );
+  }
+
+  /**
+   * Discover all .ts/.tsx files in a directory and check them.
+   */
+  checkAll(dir: string = "/src"): Diagnostic[] {
+    const files = this.discoverFiles(dir);
+    return this.check(files);
+  }
+
+  private discoverFiles(dir: string): string[] {
+    const files: string[] = [];
+    try {
+      for (const entry of this.vfs.readdirSync(dir)) {
+        const full = pathShim.join(dir, entry);
+        try {
+          if (this.vfs.statSync(full).isDirectory()) {
+            if (entry !== "node_modules" && !entry.startsWith(".")) {
+              files.push(...this.discoverFiles(full));
+            }
+          } else if (entry.match(/\.(ts|tsx)$/) && !entry.endsWith(".d.ts")) {
+            files.push(full);
+          }
+        } catch {
+          /* skip */
+        }
+      }
+    } catch {
+      /* dir may not exist */
+    }
+    return files;
+  }
+
+  private checkFile(file: string, source: string): Diagnostic[] {
+    const diags: Diagnostic[] = [];
+    const lines = source.split("\n");
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNum = i + 1;
+
+      // Check for common TypeScript errors
+
+      // 1. Missing return type on exported functions (noImplicitAny)
+      if (this.opts.noImplicitAny) {
+        const exportFnMatch = line.match(
+          /^export\s+(?:default\s+)?function\s+(\w+)\s*\([^)]*\)\s*\{/,
+        );
+        if (exportFnMatch && !line.includes("):")) {
+          diags.push({
+            file,
+            line: lineNum,
+            column: 0,
+            message: `Function '${exportFnMatch[1]}' has no return type annotation`,
+            severity: "warning",
+            code: "TS7030",
+          });
+        }
+      }
+
+      // 2. Duplicate variable declarations in same scope
+      const constMatch = line.match(/^\s*(const|let|var)\s+(\w+)/);
+      if (constMatch) {
+        const varName = constMatch[2];
+        // Check for redeclaration in subsequent lines (same indentation level)
+        for (let j = i + 1; j < lines.length && j < i + 50; j++) {
+          const reDecl = lines[j].match(
+            new RegExp(`^\\s*(const|let)\\s+${varName}\\b`),
+          );
+          if (
+            reDecl &&
+            lines[j].match(/^\s*/)?.[0] === line.match(/^\s*/)?.[0]
+          ) {
+            diags.push({
+              file,
+              line: j + 1,
+              column: 0,
+              message: `Cannot redeclare block-scoped variable '${varName}'`,
+              severity: "error",
+              code: "TS2451",
+            });
+            break;
+          }
+        }
+      }
+
+      // 3. Using `any` when noImplicitAny is enabled
+      if (this.opts.noImplicitAny && this.opts.strict) {
+        const anyTypeMatch = line.match(/:\s*any\b/);
+        if (
+          anyTypeMatch &&
+          !line.includes("// @ts-ignore") &&
+          !line.includes("eslint-disable")
+        ) {
+          diags.push({
+            file,
+            line: lineNum,
+            column: anyTypeMatch.index ?? 0,
+            message: "Unexpected use of 'any' type",
+            severity: "warning",
+            code: "TS7006",
+          });
+        }
+      }
+
+      // 4. Unreachable code after return/throw
+      if (line.match(/^\s*(return|throw)\b/) && i + 1 < lines.length) {
+        const nextLine = lines[i + 1]?.trim();
+        if (
+          nextLine &&
+          !nextLine.startsWith("}") &&
+          !nextLine.startsWith("//") &&
+          !nextLine.startsWith("/*") &&
+          nextLine !== ""
+        ) {
+          diags.push({
+            file,
+            line: lineNum + 1,
+            column: 0,
+            message: "Unreachable code detected",
+            severity: "warning",
+            code: "TS7027",
+          });
+        }
+      }
+
+      // 5. Syntax: missing semicolons at statement boundaries (if strict)
+      // Only flag obvious cases: variable declarations without semicolons
+      if (this.opts.strict) {
+        const stmtMatch = line.match(
+          /^\s*(const|let|var)\s+\w+\s*=\s*.+[^;{,\s]\s*$/,
+        );
+        if (
+          stmtMatch &&
+          !line.includes("//") &&
+          !line.endsWith("=>") &&
+          !line.endsWith("(")
+        ) {
+          // Skip multi-line expressions
+          const nextLine = lines[i + 1]?.trim() || "";
+          if (
+            nextLine &&
+            !nextLine.startsWith(".") &&
+            !nextLine.startsWith("+") &&
+            !nextLine.startsWith("?") &&
+            !nextLine.startsWith(":")
+          ) {
+            // This is a potential missing semicolon — but too noisy, skip for now
+          }
+        }
+      }
+    }
+
+    return diags;
+  }
+}

package/src/types/package-json.ts

@@ -0,0 +1,17 @@
+export interface PackageJson {
+  name?: string;
+  version?: string;
+  main?: string;
+  module?: string;
+  browser?: string | Record<string, string | false>;
+  exports?: unknown;
+  imports?: Record<string, unknown>;
+  bin?: string | Record<string, string>;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  type?: "module" | "commonjs";
+  [key: string]: unknown;
+}

package/src/utils/binary-encoding.ts

@@ -0,0 +1,38 @@
+const CHUNK = 8192;
+
+export function uint8ToBase64(bytes: Uint8Array): string {
+  const parts: string[] = [];
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    parts.push(
+      String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK))),
+    );
+  }
+  return btoa(parts.join(""));
+}
+
+export function base64ToUint8(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+export function uint8ToHex(bytes: Uint8Array): string {
+  const hex = new Array(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    hex[i] = bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex.join("");
+}
+
+export function uint8ToBinaryString(bytes: Uint8Array): string {
+  const parts: string[] = [];
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    parts.push(
+      String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK))),
+    );
+  }
+  return parts.join("");
+}

package/src/utils/hash.ts

@@ -0,0 +1,24 @@
+/**
+ * FNV-1a hash producing a 64-bit result (two 32-bit halves).
+ * Returns base36 string (~12 chars). Much lower collision probability
+ * than the previous 32-bit djb2 (~6 chars).
+ */
+export function simpleHash(str: string): string {
+  // FNV-1a 64-bit offset basis and prime (split into high/low 32-bit)
+  let h0 = 0x811c9dc5; // low 32 bits of offset basis
+  let h1 = 0xcbf29ce4; // high 32 bits of offset basis
+
+  for (let i = 0; i < str.length; i++) {
+    const c = str.charCodeAt(i);
+    // XOR with byte
+    h0 ^= c;
+    // Multiply by FNV prime 0x00000100000001B3
+    // Using schoolbook multiplication for two 32-bit halves
+    const lo = Math.imul(h0, 0x01b3) >>> 0;
+    const hi = (Math.imul(h1, 0x01b3) + Math.imul(h0, 0x0100)) >>> 0;
+    h0 = lo;
+    h1 = hi;
+  }
+
+  return (h1 >>> 0).toString(36) + (h0 >>> 0).toString(36);
+}

package/src/utils/safe-path.ts

@@ -0,0 +1,38 @@
+import { posix } from "../polyfills/path";
+
+/**
+ * Resolve a URL path safely within a root directory.
+ * Strips query/hash, decodes, normalizes, and ensures the result
+ * never escapes outside root via .. traversal.
+ */
+export function safePath(root: string, urlPath: string): string {
+  // Strip query string and hash
+  let p = urlPath.split("?")[0].split("#")[0];
+
+  // Decode percent-encoded characters
+  try {
+    p = decodeURIComponent(p);
+  } catch {
+    /* keep as-is */
+  }
+
+  // Ensure leading slash
+  if (!p.startsWith("/")) p = "/" + p;
+
+  // Normalize (resolves .., ., double slashes)
+  p = posix.normalize(p);
+
+  // Join with root
+  const full = root === "/" ? p : posix.normalize(root + "/" + p);
+
+  // Verify the result starts with root
+  const normalRoot = root === "/" ? "/" : posix.normalize(root);
+  if (
+    !full.startsWith(normalRoot === "/" ? "/" : normalRoot + "/") &&
+    full !== normalRoot
+  ) {
+    return normalRoot;
+  }
+
+  return full;
+}

package/src/worker-runtime.ts

@@ -0,0 +1,42 @@
+/**
+ * Worker runtime configuration.
+ *
+ * When `worker` mode is enabled, CPU-intensive operations (transpilation via
+ * esbuild-wasm) are offloaded to a Web Worker. This prevents UI freezes
+ * during TypeScript/JSX compilation.
+ *
+ * The `worker` option on Container controls this:
+ * - `false` (default) — everything runs on the main thread
+ * - `true` — enable worker-based transpilation
+ * - `'auto'` — use workers when `Worker` is available (browser), skip in Node.js
+ *
+ * Full kernel isolation (executing `require()` and `new Function()` in a
+ * worker) is planned for a future release and requires SharedArrayBuffer
+ * for synchronous VFS access from the worker.
+ *
+ * @module
+ */
+
+export type WorkerMode = boolean | "auto";
+
+/**
+ * Determine whether to use worker-based transpilation.
+ * Returns `true` if workers should be enabled based on the mode
+ * and the current runtime environment.
+ */
+export function shouldUseWorker(mode: WorkerMode): boolean {
+  if (mode === false) return false;
+  if (mode === true) return true;
+  // 'auto' — use workers in browser environments where Worker is available
+  return typeof Worker !== "undefined" && typeof window !== "undefined";
+}
+
+/**
+ * Configuration for the worker runtime.
+ * Currently only affects transpilation; future versions will support
+ * full kernel isolation.
+ */
+export interface WorkerRuntimeConfig {
+  /** Whether to use Web Workers for transpilation. */
+  useWorker: boolean;
+}