wasm-idle 1.1.0 → 1.1.2

package/dist/playground/container/runtime-adapter.d.ts

@@ -0,0 +1,73 @@
+import { type ProgressLike, type WorkspaceFile } from '@wasm-idle/core';
+import { type Container, type ContainerProcess, type LiveCommandAdapter, type MemoryFileSystem } from '@wasm-idle/container';
+import { createPlaygroundBinding } from '../index';
+import type { SandboxRuntimeAssets } from '../sandbox';
+import type { SandboxExecutionOptions } from '../options';
+import type { ContainerWorkerEvent, ContainerWorkspaceEntry } from './protocol';
+interface Job {
+    id: string;
+    language: string;
+    method: 'load' | 'prepare' | 'run';
+    requestId: number;
+    code: string;
+    log: boolean;
+    args: string[];
+    options: SandboxExecutionOptions;
+    signal: AbortSignal;
+    progress?: ProgressLike;
+    result?: boolean | string;
+    error?: unknown;
+    process?: ContainerProcess;
+    writer?: WritableStreamDefaultWriter<Uint8Array>;
+    output?: (data: string) => void;
+    readyForInput?: boolean;
+}
+interface RuntimeAdapterOptions {
+    runtimeAssets: SandboxRuntimeAssets;
+    emit(event: ContainerWorkerEvent): void;
+    /** Only a trusted local app factory is used in contract tests. */
+    createBinding?: typeof createPlaygroundBinding;
+}
+/** Existing real engines keep their private runtime FS; their source snapshot is the common VFS. */
+export declare class WebsiteRuntimeAdapter {
+    #private;
+    private readonly settings;
+    readonly adapter: LiveCommandAdapter;
+    readonly commands: {
+        "website-playground-engine": {
+            adapter: string;
+            bytes: Uint8Array<ArrayBuffer>;
+            argv0: string;
+        };
+    };
+    readonly filesystemProfile = "shared-source-snapshot; runtime-private-files-not-exported";
+    constructor(settings: RuntimeAdapterOptions);
+    attach(container: Container): void;
+    get fs(): MemoryFileSystem;
+    directory(language: string): string;
+    private session;
+    syncWorkspace(language: string, files: readonly WorkspaceFile[], expectedBaseFiles?: readonly WorkspaceFile[]): void;
+    readWorkspace(language: string): WorkspaceFile[];
+    /** Enumerate the common namespace without copying file bodies or following links. */
+    listWorkspaceFiles(): ContainerWorkspaceEntry[];
+    inputs(language: string, code: string, options: SandboxExecutionOptions): {
+        code: string;
+        options: SandboxExecutionOptions;
+    };
+    execute(method: Job['method'], language: string, code: string | undefined, log: boolean | undefined, args: string[] | undefined, options: SandboxExecutionOptions | undefined, signal: AbortSignal, progress?: ProgressLike, requestId?: number): Promise<string | boolean | undefined>;
+    private flushInput;
+    write(language: string, value: string): Promise<void>;
+    eof(language: string): Promise<void>;
+    stop(language: string): Promise<void>;
+    clear(language: string): Promise<void>;
+    restart(language: string): Promise<void>;
+    debug(language: string, method: string, args: unknown[]): Promise<any>;
+    inspect(): {
+        language: string;
+        pid: number | undefined;
+        phase: "load" | "run" | "prepare";
+        filesystem: string;
+    }[];
+    dispose(): Promise<void>;
+}
+export {};

package/dist/playground/container/runtime-adapter.js

@@ -0,0 +1,474 @@
+import { normalizeLanguageId, normalizeWorkspacePath, validateWorkspaceFiles } from '@wasm-idle/core';
+import { ContainerError } from '@wasm-idle/container';
+import { createPlaygroundBinding } from '../index';
+const COMMAND = 'website-playground-engine';
+const ADAPTER = 'website-playground-host-v1';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const defaultSource = (language) => ({
+    C: 'main.c',
+    CPP: 'main.cpp',
+    PYTHON: 'main.py',
+    PYTHON3: 'main.py',
+    JAVA: 'Main.java',
+    RUST: 'main.rs',
+    GO: 'main.go',
+    JAVASCRIPT: 'main.js',
+    TYPESCRIPT: 'main.ts'
+})[language] ?? 'main.txt';
+/** Existing real engines keep their private runtime FS; their source snapshot is the common VFS. */
+export class WebsiteRuntimeAdapter {
+    settings;
+    adapter;
+    commands = {
+        [COMMAND]: { adapter: ADAPTER, bytes: new Uint8Array(), argv0: COMMAND }
+    };
+    filesystemProfile = 'shared-source-snapshot; runtime-private-files-not-exported';
+    #container;
+    #sessions = new Map();
+    #jobs = new Map();
+    #published = new Map();
+    #nextJob = 0;
+    #disposed = false;
+    constructor(settings) {
+        this.settings = settings;
+        this.adapter = {
+            id: ADAPTER,
+            filesystem: 'live',
+            start: async (request) => {
+                const job = this.#jobs.get(request.invocation.args[0]);
+                if (!job ||
+                    request.invocation.args.length !== 1 ||
+                    request.fs !== this.fs ||
+                    request.invocation.cwd !== this.directory(job.language))
+                    throw new ContainerError('INVALID_ARGUMENT', 'Unknown application runtime job');
+                let output, errors;
+                let closed = false, bytes = 0;
+                const stdout = new ReadableStream({
+                    start(controller) {
+                        output = controller;
+                    }
+                });
+                const stderr = new ReadableStream({
+                    start(controller) {
+                        errors = controller;
+                    }
+                });
+                const session = this.session(job.language);
+                job.output = (data) => {
+                    if (closed || request.signal.aborted)
+                        return;
+                    const chunk = encoder.encode(data);
+                    bytes += chunk.byteLength;
+                    if (bytes > request.limits.maxOutputBytes) {
+                        job.error = new ContainerError('RESOURCE_LIMIT', 'Runtime output exceeds the container limit');
+                        void this.stop(job.language).catch(() => { });
+                        return;
+                    }
+                    if (chunk.byteLength)
+                        output.enqueue(chunk);
+                };
+                const abort = () => {
+                    void session.sandbox.then((sandbox) => sandbox.terminate()).catch(() => { });
+                };
+                request.signal.addEventListener('abort', abort, { once: true });
+                return {
+                    stdin: new WritableStream({
+                        write: (chunk) => this.write(job.language, decoder.decode(chunk, { stream: true })),
+                        close: () => (job.method === 'run' ? this.eof(job.language) : undefined)
+                    }),
+                    stdout,
+                    stderr,
+                    run: async () => {
+                        try {
+                            const sandbox = await session.sandbox;
+                            request.signal.throwIfAborted();
+                            const options = { ...job.options, signal: request.signal };
+                            if (job.method === 'load') {
+                                await sandbox.load(job.code, job.log, job.args, options, job.progress);
+                                job.result = true;
+                            }
+                            else {
+                                const running = sandbox.run(job.code, job.method === 'prepare', job.log, job.progress, job.args, options);
+                                if (job.method === 'run') {
+                                    job.readyForInput = true;
+                                    await this.flushInput(session, sandbox);
+                                }
+                                job.result = await running;
+                            }
+                            if (job.error)
+                                throw job.error;
+                            return { code: job.result === false ? 1 : 0 };
+                        }
+                        catch (error) {
+                            job.error = error;
+                            throw error;
+                        }
+                    },
+                    dispose: async () => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        request.signal.removeEventListener('abort', abort);
+                        job.readyForInput = false;
+                        if (request.signal.aborted)
+                            await session.sandbox
+                                .then((sandbox) => sandbox.terminate())
+                                .catch(() => { });
+                        output.close();
+                        errors.close();
+                    }
+                };
+            }
+        };
+    }
+    attach(container) {
+        if (this.#container)
+            throw new Error('Runtime adapter is already attached');
+        this.#container = container;
+    }
+    get fs() {
+        if (!this.#container)
+            throw new Error('Container not attached');
+        return this.#container.fs;
+    }
+    directory(language) {
+        if (typeof language !== 'string' ||
+            !/^[A-Z][A-Z0-9_]{0,63}$/u.test(language) ||
+            !normalizeLanguageId(language))
+            throw new TypeError('Unsupported workspace language');
+        const path = `/workspace/${language}`;
+        this.fs.mkdir(path, { recursive: true });
+        return path;
+    }
+    session(language) {
+        if (this.#disposed)
+            throw new Error('Runtime owner disposed');
+        let session = this.#sessions.get(language);
+        if (session)
+            return session;
+        const binding = (this.settings.createBinding ?? createPlaygroundBinding)(this.settings.runtimeAssets);
+        session = {
+            binding,
+            sandbox: undefined,
+            pendingInput: [],
+            pendingBytes: 0,
+            pendingEof: false
+        };
+        const owner = session;
+        session.sandbox = binding.load(language).then((value) => {
+            const sandbox = value;
+            sandbox.output = (data) => owner.active?.output?.(data);
+            for (const [property, name] of [
+                ['ondebug', 'debug'],
+                ['oncompilerdiagnostic', 'diagnostic'],
+                ['image', 'image']
+            ])
+                sandbox[property] = (data) => this.settings.emit({
+                    language,
+                    name,
+                    data,
+                    requestId: owner.active?.requestId
+                });
+            return sandbox;
+        });
+        void session.sandbox.catch(() => { });
+        this.#sessions.set(language, session);
+        return session;
+    }
+    syncWorkspace(language, files, expectedBaseFiles) {
+        const path = this.directory(language);
+        const validated = validateWorkspaceFiles(files, {
+            maxFiles: 2048,
+            maxFileBytes: 16 * 1024 * 1024,
+            maxTotalBytes: 64 * 1024 * 1024,
+            caseSensitive: true
+        });
+        const next = new Set(validated.map((file) => file.path));
+        const asBytes = (content) => typeof content === 'string' ? encoder.encode(content) : content;
+        const equal = (left, right) => left === undefined || right === undefined
+            ? left === right
+            : left.length === right.length &&
+                left.every((byte, index) => byte === right[index]);
+        const current = (name) => {
+            try {
+                return this.fs.readFile(name, { root: path, cwd: path });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                return undefined;
+            }
+        };
+        const base = expectedBaseFiles === undefined
+            ? undefined
+            : new Map(validateWorkspaceFiles(expectedBaseFiles, {
+                maxFiles: 2048,
+                maxFileBytes: 16 * 1024 * 1024,
+                maxTotalBytes: 64 * 1024 * 1024,
+                caseSensitive: true
+            }).map((file) => [file.path, asBytes(file.content)]));
+        const previousPaths = base?.keys() ?? this.#published.get(language) ?? [];
+        const deletions = [...previousPaths].filter((previous) => !next.has(previous));
+        // Compare all touched files before publishing even the first edit. Shell-created
+        // paths outside the editor's baseline are retained unless explicitly supplied.
+        if (base) {
+            for (const file of validated) {
+                const before = base.get(file.path), after = asBytes(file.content), present = current(file.path);
+                if (!equal(before, after) && !equal(present, before) && !equal(present, after))
+                    throw new ContainerError('FILESYSTEM_CONFLICT', `Workspace changed while editing ${file.path}`);
+            }
+            for (const file of deletions)
+                if (current(file) !== undefined && !equal(current(file), base.get(file)))
+                    throw new ContainerError('FILESYSTEM_CONFLICT', `Workspace changed before deleting ${file}`);
+        }
+        for (const previous of deletions) {
+            try {
+                this.fs.unlink(previous, { root: path, cwd: path });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        for (const file of validated) {
+            // An unchanged editor buffer must not overwrite a newer shell revision.
+            if (base?.has(file.path) && equal(base.get(file.path), asBytes(file.content)))
+                continue;
+            const parent = file.path.split('/').slice(0, -1).join('/');
+            if (parent)
+                this.fs.mkdir(parent, { recursive: true, root: path, cwd: path });
+            const bytes = typeof file.content === 'string' ? encoder.encode(file.content) : file.content;
+            let previous;
+            try {
+                previous = this.fs.readFile(file.path, { root: path, cwd: path });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (previous?.length === bytes.length &&
+                previous.every((byte, index) => byte === bytes[index]))
+                continue;
+            this.fs.writeFile(file.path, bytes, { root: path, cwd: path });
+        }
+        this.#published.set(language, next);
+    }
+    readWorkspace(language) {
+        const root = this.directory(language), files = [];
+        const visit = (path) => {
+            for (const name of this.fs.readdir(path || '.', { root, cwd: root })) {
+                const relative = path ? `${path}/${name}` : name;
+                const stat = this.fs.lstat(relative, { root, cwd: root });
+                if (stat.type === 'directory')
+                    visit(relative);
+                else if (stat.type === 'file')
+                    files.push({
+                        path: relative,
+                        content: this.fs.readFile(relative, { root, cwd: root })
+                    });
+            }
+        };
+        visit('');
+        return files;
+    }
+    /** Enumerate the common namespace without copying file bodies or following links. */
+    listWorkspaceFiles() {
+        const entries = [];
+        const options = { root: '/workspace', cwd: '/workspace' };
+        const visit = (parent) => {
+            for (const name of this.fs.readdir(parent || '.', options)) {
+                const path = parent ? `${parent}/${name}` : name;
+                const stat = this.fs.lstat(path, options);
+                if (stat.type !== 'file' && stat.type !== 'directory' && stat.type !== 'symlink')
+                    continue;
+                entries.push({ path, type: stat.type, size: stat.size });
+                if (stat.type === 'directory')
+                    visit(path);
+            }
+        };
+        visit('');
+        return entries;
+    }
+    inputs(language, code, options) {
+        const root = this.directory(language);
+        const activePath = normalizeWorkspacePath(options.activePath ?? defaultSource(language));
+        try {
+            this.fs.stat(activePath, { root, cwd: root });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            this.syncWorkspace(language, [
+                ...new Map([...(options.workspaceFiles ?? []), { path: activePath, content: code }].map((entry) => [entry.path, entry])).values()
+            ]);
+        }
+        const files = this.readWorkspace(language);
+        return {
+            code: new TextDecoder('utf-8', { fatal: true }).decode(this.fs.readFile(activePath, { root, cwd: root })),
+            options: {
+                ...options,
+                activePath,
+                workspaceFiles: files
+            }
+        };
+    }
+    async execute(method, language, code = '', log = true, args = [], options = {}, signal, progress, requestId = 0) {
+        const session = this.session(language);
+        if (session.active)
+            throw new ContainerError('RESOURCE_LIMIT', `${language} already has an active runtime job`);
+        const source = this.inputs(language, code, options);
+        const job = {
+            id: String(++this.#nextJob),
+            language,
+            method,
+            code: source.code,
+            log,
+            args: [...args],
+            options: source.options,
+            signal,
+            progress,
+            requestId
+        };
+        session.active = job;
+        this.#jobs.set(job.id, job);
+        try {
+            const process = await this.#container.spawn(COMMAND, [job.id], {
+                cwd: this.directory(language),
+                env: options.env,
+                signal
+            });
+            job.process = process;
+            const drain = async (stream) => {
+                const reader = stream.getReader(), text = new TextDecoder();
+                try {
+                    for (;;) {
+                        const { value, done } = await reader.read();
+                        if (done)
+                            break;
+                        const data = text.decode(value, { stream: true });
+                        if (data)
+                            this.settings.emit({ language, name: 'output', data, requestId });
+                    }
+                    const tail = text.decode();
+                    if (tail)
+                        this.settings.emit({ language, name: 'output', data: tail, requestId });
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            };
+            const [result] = await Promise.all([
+                process.exited,
+                drain(process.stdout),
+                drain(process.stderr)
+            ]);
+            if (signal.aborted)
+                throw signal.reason ?? new DOMException('Runtime cancelled', 'AbortError');
+            if (job.error)
+                throw job.error;
+            if (result.reason !== 'exited')
+                throw new Error(`Runtime ended with ${result.reason}`);
+            return method === 'load' ? undefined : (job.result ?? result.code === 0);
+        }
+        finally {
+            if (session.active === job)
+                session.active = undefined;
+            this.#jobs.delete(job.id);
+        }
+    }
+    async flushInput(session, sandbox) {
+        if (!session.active?.readyForInput)
+            return;
+        for (const value of session.pendingInput.splice(0))
+            sandbox.write?.(value);
+        session.pendingBytes = 0;
+        if (session.pendingEof) {
+            session.pendingEof = false;
+            sandbox.eof();
+        }
+    }
+    async write(language, value) {
+        if (typeof value !== 'string')
+            throw new TypeError('Runtime input must be text');
+        const session = this.session(language);
+        if (session.pendingEof)
+            throw new Error('Runtime input is closed');
+        const size = encoder.encode(value).byteLength;
+        if (session.pendingBytes + size > 8 * 1024 * 1024)
+            throw new Error('Pending runtime input exceeds the container limit');
+        session.pendingInput.push(value);
+        session.pendingBytes += size;
+        if (session.active?.readyForInput)
+            await this.flushInput(session, await session.sandbox);
+    }
+    async eof(language) {
+        const session = this.session(language);
+        session.pendingEof = true;
+        if (session.active?.readyForInput)
+            await this.flushInput(session, await session.sandbox);
+    }
+    async stop(language) {
+        const session = this.#sessions.get(language);
+        if (!session)
+            return;
+        session.pendingInput.length = 0;
+        session.pendingBytes = 0;
+        session.pendingEof = false;
+        await Promise.all([
+            session.active?.process?.terminate(),
+            session.sandbox.then((sandbox) => sandbox.terminate()).catch(() => { })
+        ]);
+    }
+    async clear(language) {
+        await (await this.session(language).sandbox).clear();
+    }
+    async restart(language) {
+        await this.stop(language);
+        const session = this.#sessions.get(language);
+        this.#sessions.delete(language);
+        await session?.binding.dispose?.();
+    }
+    async debug(language, method, args) {
+        const allowed = new Set([
+            'debugCommand',
+            'debugPause',
+            'setBreakpoints',
+            'debugEvaluate',
+            'debugVariables',
+            'debugScopes',
+            'debugFrameScopes',
+            'debugFrameName',
+            'debugReadMemory',
+            'debugWriteMemory',
+            'debugDataBreakpointInfo',
+            'debugSetDataBreakpoints'
+        ]);
+        if (!allowed.has(method))
+            throw new TypeError('Unknown debugger method');
+        const sandbox = await this.session(language).sandbox;
+        const handler = sandbox[method];
+        if (typeof handler !== 'function')
+            throw new Error(`The ${language} runtime does not support ${method}`);
+        return await handler.apply(sandbox, args);
+    }
+    inspect() {
+        return [...this.#jobs.values()].map((job) => ({
+            language: job.language,
+            pid: job.process?.pid,
+            phase: job.method,
+            filesystem: this.filesystemProfile
+        }));
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        await Promise.allSettled([...this.#sessions.values()].map(async (session) => {
+            await session.active?.process?.terminate();
+            await session.binding.dispose?.();
+        }));
+        this.#sessions.clear();
+        this.#jobs.clear();
+    }
+}

package/dist/playground/container/shell-control.d.ts

@@ -0,0 +1,49 @@
+import type { CommandDefinition, HostCommandInvocation, LiveCommandAdapter, MemoryFileSystem } from '@wasm-idle/container';
+export declare const SHELL_CONTROL_COMMAND = "wasm-idle-shell-control";
+export declare const SHELL_CONTROL_FUNCTION_ENV = "BASH_FUNC___wasm_idle_poll%%";
+export declare const SHELL_CONTROL_ROUTE = "/usr/local/bin/wasm-idle-shell-control";
+export declare const SHELL_CONTROL_MOUNT = "/usr/share/wasm-idle-shell-control";
+export declare const SHELL_CONTROL_RCFILE = "/usr/share/wasm-idle-shell-control/rcfile";
+export declare const SHELL_CONTROL_REQUEST = "/tmp/.wasm-idle-shell-control-request";
+export interface ShellControlInspection {
+    readonly ready: boolean;
+    readonly disposed: boolean;
+    /** Last cwd confirmed by the actual shell host invocation, or the host's initial cwd. */
+    readonly cwd: string;
+    readonly pendingCwd: string | null;
+    readonly generation: number;
+    readonly appliedGeneration: number;
+    readonly error: string | null;
+}
+interface ShellControlOptions {
+    languages: readonly string[];
+    initialDirectory?: string;
+    onChange?: (inspection: ShellControlInspection) => void;
+    /** Trusted deterministic protocol fixture input; never read from guest messages. */
+    session?: string;
+}
+/** Host directory requests are read only at the producer's real primary-prompt boundary. */
+export declare function createShellControl(options: ShellControlOptions): Readonly<{
+    adapter: LiveCommandAdapter;
+    commands: Readonly<Record<string, CommandDefinition>>;
+    route: Readonly<{
+        path: "/usr/local/bin/wasm-idle-shell-control";
+        command: "wasm-idle-shell-control";
+    }>;
+    setup(fs: MemoryFileSystem): Readonly<{
+        mountPath: "/usr/share/wasm-idle-shell-control";
+        rcfilePath: "/usr/share/wasm-idle-shell-control/rcfile";
+        requestPath: "/tmp/.wasm-idle-shell-control-request";
+        args: readonly string[];
+        env: Readonly<{
+            WASM_IDLE_SHELL_CONTROL: "1";
+            INPUTRC: "/tmp/.wasm-idle-shell-inputrc";
+            "BASH_FUNC___wasm_idle_poll%%": `() ${string}`;
+        }>;
+    }>;
+    requestDirectory(language: string): Promise<void>;
+    onInvocation(invocation: HostCommandInvocation): number | undefined;
+    inspect: () => ShellControlInspection;
+    dispose(): void;
+}>;
+export {};