@run0/jiki 0.1.0

package/dist/shell.d.ts

@@ -0,0 +1,101 @@
+import { MemFS } from "./memfs";
+import { Kernel } from "./kernel";
+import { PackageManager } from "./npm/index";
+import { EventEmitter } from "./polyfills/events";
+export interface ShellOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    onExit?: (code: number) => void;
+    pnpmPm?: PackageManager;
+    lazyPnpmPm?: () => PackageManager;
+}
+export interface ShellProcess {
+    stdin: {
+        write(data: string): void;
+    };
+    stdout: EventEmitter;
+    stderr: EventEmitter;
+    kill(signal?: string): void;
+    wait(): Promise<number>;
+    pid: number;
+}
+export interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface ShellContext {
+    vfs: MemFS;
+    runtime: Kernel;
+    pm: PackageManager;
+    pnpmPm?: PackageManager;
+    cwd: string;
+    env: Record<string, string>;
+    stdinData?: string;
+    setCwd(dir: string): void;
+    exec(command: string, options?: ShellOptions): Promise<ShellResult>;
+    write?(text: string): void;
+    writeErr?(text: string): void;
+}
+export type CommandHandler = (args: string[], ctx: ShellContext) => ShellResult | Promise<ShellResult>;
+/** Command history with up/down navigation. */
+export declare class ShellHistory {
+    private entries;
+    private cursor;
+    private maxSize;
+    constructor(maxSize?: number);
+    push(command: string): void;
+    up(): string | undefined;
+    down(): string | undefined;
+    reset(): void;
+    getAll(): string[];
+    get length(): number;
+}
+export declare class Shell {
+    private vfs;
+    private runtime;
+    private packageManager;
+    private pnpmPm?;
+    private lazyPnpmPm?;
+    private binCache;
+    private cwd;
+    private env;
+    private commands;
+    /** Command history for this shell session. */
+    readonly history: ShellHistory;
+    /** Background jobs spawned with `&`. */
+    private backgroundJobs;
+    private nextJobId;
+    constructor(vfs: MemFS, runtime: Kernel, packageManager: PackageManager, options?: ShellOptions);
+    registerCommand(name: string, handler: CommandHandler): void;
+    /**
+     * Tab completion for a partial input string.
+     * Returns sorted candidate completions.
+     */
+    complete(partial: string): string[];
+    private completeFilePath;
+    exec(command: string, options?: ShellOptions): Promise<ShellResult>;
+    private execPipeline;
+    private splitControlFlow;
+    private parseRedirects;
+    private execSingle;
+    private expandVar;
+    private parseCommand;
+    /** Consume a $VAR or ${VAR} starting at position i (pointing at '$'), returning expanded value and end index */
+    private consumeVariable;
+    private expandGlob;
+    /** Expand brace patterns like `{a,b}` into multiple strings. */
+    private expandBraces;
+    /** Expand `**` recursive glob patterns. */
+    private expandRecursiveGlob;
+    private matchGlobSegments;
+    private resolveBin;
+    clearBinCache(): void;
+    getCwd(): string;
+    setCwd(dir: string): void;
+    getEnv(): Record<string, string>;
+    setEnv(key: string, value: string): void;
+}
+export declare function createShell(vfs: MemFS, runtime: Kernel, pm: PackageManager, options?: ShellOptions): Shell;

package/dist/transpiler.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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";
+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;
+}
+export declare function setWasmURL(url: string | URL): void;
+export declare function initTranspiler(options?: InitOptions): Promise<void>;
+export declare function isInitialized(): boolean;
+export declare function needsTranspilation(filename: string): boolean;
+export declare function transpile(code: string, filename: string, options?: TranspileOptions): Promise<string>;
+export declare function hasSyncSupport(): boolean;
+export declare function transpileSync(code: string, filename: string, options?: TranspileOptions): string;
+export declare function bundle(vfs: MemFS, options: BundleOptions): Promise<BundleResult>;
+export declare function stopTranspiler(): Promise<void>;
+export { esbuild };

package/dist/type-checker.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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";
+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 declare class TypeChecker {
+    private vfs;
+    private opts;
+    constructor(vfs: MemFS, options?: TypeCheckerOptions);
+    /**
+     * Check a list of TypeScript files for common errors.
+     * Returns diagnostics sorted by file and line number.
+     */
+    check(files: string[]): Diagnostic[];
+    /**
+     * Discover all .ts/.tsx files in a directory and check them.
+     */
+    checkAll(dir?: string): Diagnostic[];
+    private discoverFiles;
+    private checkFile;
+}

package/dist/types/package-json.d.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/dist/utils/binary-encoding.d.ts

@@ -0,0 +1,4 @@
+export declare function uint8ToBase64(bytes: Uint8Array): string;
+export declare function base64ToUint8(base64: string): Uint8Array;
+export declare function uint8ToHex(bytes: Uint8Array): string;
+export declare function uint8ToBinaryString(bytes: Uint8Array): string;

package/dist/utils/hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function simpleHash(str: string): string;

package/dist/utils/safe-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function safePath(root: string, urlPath: string): string;

package/dist/worker-runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare function shouldUseWorker(mode: WorkerMode): boolean;
+/**
+ * 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;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@run0/jiki",
+  "version": "0.1.0",
+  "description": "Lightweight browser-based Node.js runtime with virtual filesystem, npm support, and dev servers.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bugs": "https://github.com/prxm-labs/jiki/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prxm-labs/jiki.git",
+    "directory": "packages/jiki"
+  },
+  "homepage": "https://jiki.sh",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "acorn": "^8.14.0",
+    "acorn-jsx": "^5.3.2",
+    "comlink": "^4.4.2",
+    "esbuild-wasm": "^0.27.3",
+    "pako": "^2.1.0",
+    "resolve.exports": "^2.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/pako": "^2.0.3",
+    "typescript": "^5.7.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc --project tsconfig.build.json",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}