mockpit 0.0.0-stage → 1.0.0

package/dist/server/base64.d.ts

@@ -0,0 +1 @@
+export declare function decodeBase64(b64: string): Uint8Array;

package/dist/server/base64.js

@@ -0,0 +1,16 @@
+// base64 -> bytes, runtime-agnostic (atob is a global in Node and Workers).
+// atob throws on malformed input; rethrow as a clean error so callers turn it
+// into a 400 instead of letting a raw DOMException surface as a 500.
+export function decodeBase64(b64) {
+    let bin;
+    try {
+        bin = atob(b64);
+    }
+    catch {
+        throw new Error("invalid base64 in `data`");
+    }
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return bytes;
+}

package/dist/server/cdn.d.ts

@@ -0,0 +1,6 @@
+export declare const CDN_ALLOWLIST: string[];
+export declare function checkCdnUrl(raw: unknown, field: string): {
+    url: string;
+} | {
+    error: string;
+};

package/dist/server/cdn.js

@@ -0,0 +1,33 @@
+// Origins html surfaces may load external resources from. Mirrors the allowlist
+// agents already know from Claude's inline widget surface. One list, so the CSP
+// and the kit URL check can never disagree about what a sandbox may fetch.
+//
+// Runtime-agnostic (no node imports).
+export const CDN_ALLOWLIST = [
+    "https://cdnjs.cloudflare.com",
+    "https://esm.sh",
+    "https://cdn.jsdelivr.net",
+    "https://unpkg.com",
+    "https://fonts.googleapis.com",
+    "https://fonts.gstatic.com",
+];
+// A kit URL becomes a <link>/<script> in the sandboxed document, so it must be
+// something the CSP would load anyway; anything else would silently fail there.
+// Returns the normalized URL, or an error naming the allowed origins.
+export function checkCdnUrl(raw, field) {
+    const allowed = `${field} must be an https URL on ${CDN_ALLOWLIST.map((o) => o.slice(8)).join(", ")}`;
+    if (typeof raw !== "string" || raw.length > 2048)
+        return { error: allowed };
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { error: allowed };
+    }
+    if (url.protocol !== "https:" || url.username || url.password)
+        return { error: allowed };
+    if (!CDN_ALLOWLIST.includes(url.origin))
+        return { error: allowed };
+    return { url: url.href };
+}

package/dist/server/codeRunner.d.ts

@@ -0,0 +1,5 @@
+import type { Executor } from "./run.ts";
+export interface NodeExecutorOptions {
+    graceMs?: number;
+}
+export declare function createNodeExecutor({ graceMs }?: NodeExecutorOptions): Executor;

package/dist/server/codeRunner.js

@@ -0,0 +1,89 @@
+// The Node executor for `run`: one worker_thread per run, QuickJS in wasm
+// inside it, host calls relayed to the main thread where the flows live.
+// Node-only (worker_threads, fs); server/index.ts wires it in.
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+// The source tree runs codeWorker.ts directly; the published package runs the
+// compiled dist/server/codeWorker.js next to this file.
+const HERE = fileURLToPath(import.meta.url);
+const WORKER = join(dirname(HERE), HERE.endsWith(".ts") ? "codeWorker.ts" : "codeWorker.js");
+// @types/node declares the WebAssembly namespace without its values.
+const wasm = globalThis.WebAssembly;
+const COVERAGE = process.env.NODE_V8_COVERAGE;
+export function createNodeExecutor({ graceMs = 500 } = {}) {
+    // Compiled once per process and posted to each worker.
+    let module;
+    const load = () => (module ??= readFile(fileURLToPath(import.meta.resolve("quickjs-wasi/quickjs.wasm"))).then((bytes) => wasm.compile(bytes)));
+    return {
+        async run(req) {
+            const { limits } = req;
+            if (req.signal.aborted)
+                return stopped("aborted", "the caller went away");
+            const clock = new Float64Array(new SharedArrayBuffer(16));
+            const worker = new Worker(WORKER, {
+                workerData: {
+                    module: await load(),
+                    code: req.code,
+                    cpuMs: limits.cpuMs,
+                    memoryBytes: limits.memoryBytes,
+                    stackBytes: limits.stackBytes,
+                    clock: clock.buffer,
+                },
+                // The guest never sees the environment, but the thread needn't hold
+                // secrets either. Coverage is the one variable it needs to report.
+                env: COVERAGE ? { NODE_V8_COVERAGE: COVERAGE } : {},
+                stdout: true,
+                stderr: true,
+                // A backstop only: the guest heap is wasm linear memory, not V8 old-gen.
+                resourceLimits: { maxOldGenerationSizeMb: 64 },
+            });
+            return new Promise((resolve) => {
+                let done = false;
+                const finish = (result, kill) => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(deadline);
+                    clearInterval(watchdog);
+                    req.signal.removeEventListener("abort", onAbort);
+                    if (kill)
+                        void worker.terminate();
+                    resolve(result);
+                };
+                const onAbort = () => finish(stopped("aborted", "the caller went away"), true);
+                req.signal.addEventListener("abort", onAbort, { once: true });
+                const deadline = setTimeout(() => finish(stopped("timeout", `wall deadline of ${limits.deadlineMs / 1000} s reached`), true), limits.deadlineMs);
+                // A builtin (sort, repeat, a regex) can run long without reaching the
+                // interrupt handler; only terminate() stops it.
+                const watchdog = setInterval(() => {
+                    const start = clock[0];
+                    if (start && clock[1] + (Date.now() - start) > limits.cpuMs + graceMs) {
+                        finish(stopped("limit", `CPU budget of ${limits.cpuMs} ms exhausted`), true);
+                    }
+                }, Math.max(20, Math.min(250, graceMs / 2)));
+                worker.on("message", (m) => {
+                    if (done)
+                        return;
+                    if (m.t === "print")
+                        return req.print(String(m.line));
+                    if (m.t === "done")
+                        return finish(m.outcome, false);
+                    req.call(m.name, m.args).then((json) => done || worker.postMessage({ id: m.id, ok: true, json }), (err) => done ||
+                        worker.postMessage({
+                            id: m.id,
+                            ok: false,
+                            message: err instanceof Error ? err.message : String(err),
+                        }));
+                });
+                worker.on("error", (err) => finish(stopped("limit", `sandbox stopped: ${err.message}`), true));
+                worker.on("exit", () => finish(stopped("limit", "sandbox exited"), false));
+            });
+        },
+    };
+}
+const stopped = (kind, message) => ({
+    ok: false,
+    error: { kind, message },
+});

package/dist/server/codeWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/codeWorker.js

@@ -0,0 +1,196 @@
+// worker_thread entry for one run (Node only). QuickJS runs inside wasm here;
+// the guest reaches the host only through two functions the prelude captures,
+// and everything crossing them is a string, so no guest getter or proxy ever
+// runs host-side. The parent owns the wall deadline and can terminate() this
+// thread; the CPU and memory checks below are the soft stops in front of that.
+import { parentPort, workerData } from "node:worker_threads";
+import { JSException, QuickJS } from "quickjs-wasi";
+const input = workerData;
+const port = parentPort;
+const clock = new Float64Array(input.clock);
+// The call site is captured synchronously: after an await QuickJS keeps no
+// caller frames, so a host rejection would otherwise carry no line.
+const PRELUDE = `(function (call, out) {
+  const fmt = (v) => typeof v === "string" ? v : (() => { try { return JSON.stringify(v); } catch { return String(v); } })();
+  const print = (...a) => out(a.map(fmt).join(" "));
+  const fn = (name) => (...args) => {
+    const site = new Error();
+    let json;
+    try { json = JSON.stringify(args); } catch (e) { return Promise.reject(e); }
+    return call(name, json === undefined ? "[]" : json).then(JSON.parse, (e) => {
+      const err = new Error(e.message);
+      err.stack = site.stack.split("\\n").slice(1).join("\\n");
+      throw err;
+    });
+  };
+  globalThis.mockpit = Object.freeze({
+    guide: fn("guide"), read: fn("read"), publish: fn("publish"), ask: fn("ask"),
+    feedback: fn("feedback"), say: fn("say"), export: fn("export"), upload: fn("upload"),
+  });
+  globalThis.print = print;
+  globalThis.console = Object.freeze({ log: print, info: print, warn: print, error: print });
+  const fail = (e) => ({ ok: false, name: String(e && e.name), message: String(e && e.message !== undefined ? e.message : e), stack: String(e && e.stack || "") });
+  // A value JSON can't encode (a BigInt, a throwing toJSON) fails the script.
+  return (f) => f().then((v) => {
+    try { return { ok: true, json: v === undefined ? undefined : JSON.stringify(v) }; } catch (e) { return fail(e); }
+  }, fail);
+})`;
+const TS_HINT = /^\s*(interface|type\s+\w+\s*=|enum\s)|\b(const|let|var)\s+\w+\s*:\s*\w|\)\s*:\s*(string|number|boolean|void|Promise)\b|\bas\s+(const|string|number|any|unknown)\b/m;
+// The wrapper opens on line 1 so stack positions match the script as written;
+// only line 1's columns shift by the wrapper's length.
+const WRAP = "(async () => {";
+function position(stack, message) {
+    const m = /run\.js:(\d+)(?::(\d+))?/.exec(`${stack}\n${message}`);
+    if (!m)
+        return {};
+    const line = Number(m[1]);
+    if (!m[2])
+        return { line };
+    const column = Number(m[2]);
+    return { line, column: line === 1 ? Math.max(1, column - WRAP.length) : column };
+}
+function scriptError(name, message, stack, code) {
+    if (/out of memory/i.test(message)) {
+        return { ok: false, error: { kind: "limit", message: "memory limit reached" } };
+    }
+    let text = name && name !== "Error" && name !== "undefined" ? `${name}: ${message}` : message;
+    if (name === "SyntaxError" && TS_HINT.test(code)) {
+        text += " (this looks like TypeScript; write plain JavaScript)";
+    }
+    return { ok: false, error: { kind: "script", message: text, ...position(stack, message) } };
+}
+// Discard QuickJS's own stdout/stderr: the default shim would write to the
+// host's process.stdout.
+const discardStdio = (memory) => ({
+    fd_write(_fd, iovs, len, nwritten) {
+        const view = new DataView(memory.buffer);
+        let n = 0;
+        for (let i = 0; i < len; i++)
+            n += view.getUint32(iovs + i * 8 + 4, true);
+        view.setUint32(nwritten, n, true);
+        return 0;
+    },
+});
+const pending = new Map();
+let nextId = 1;
+let wake = () => { };
+port.on("message", (m) => {
+    const p = pending.get(m.id);
+    if (!p)
+        return;
+    pending.delete(m.id);
+    if (m.ok)
+        p.resolve(m.json ?? "null");
+    else
+        p.reject(new Error(m.message));
+    wake();
+});
+async function main() {
+    let stop = null;
+    let memory;
+    const burst = (fn) => {
+        clock[0] = Date.now();
+        try {
+            return fn();
+        }
+        finally {
+            clock[1] += Date.now() - clock[0];
+            clock[0] = 0;
+        }
+    };
+    const vm = await QuickJS.create({
+        wasm: input.module,
+        memoryLimit: input.memoryBytes,
+        maxStackSize: input.stackBytes,
+        wasi: (m) => {
+            memory = m;
+            return discardStdio(m);
+        },
+        // Called about every 10k bytecode ticks, never inside a long builtin: the
+        // parent's watchdog covers that case with terminate().
+        interruptHandler: () => {
+            if (stop)
+                return true;
+            if (clock[0] && clock[1] + (Date.now() - clock[0]) > input.cpuMs) {
+                stop = { kind: "limit", message: `CPU budget of ${input.cpuMs} ms exhausted` };
+            }
+            else if (memory && memory.buffer.byteLength >= input.memoryBytes) {
+                // Linear memory never shrinks, so reaching the cap means the guest hit
+                // the limit; stop rather than let a catch-and-retry loop spin in GC.
+                stop = { kind: "limit", message: "memory limit reached" };
+            }
+            return stop !== null;
+        },
+    });
+    try {
+        const call = vm.newFunction("__call", (nameH, argsH) => {
+            const name = nameH.toString();
+            const args = argsH.toString();
+            const deferred = vm.newPromise();
+            const id = nextId++;
+            pending.set(id, {
+                resolve: (json) => deferred.resolve(vm.newString(json)),
+                reject: (err) => deferred.reject(vm.newError(err.message)),
+            });
+            port.postMessage({ t: "call", id, name, args });
+            return deferred.handle;
+        });
+        const out = vm.newFunction("__out", (s) => {
+            port.postMessage({ t: "print", line: s.toString() });
+            return vm.undefined;
+        });
+        const runner = vm.callFunction(vm.evalCode(PRELUDE, "prelude.js"), vm.undefined, call, out);
+        let fnH;
+        try {
+            fnH = burst(() => vm.evalCode(`${WRAP}${input.code}\n})`, "run.js"));
+        }
+        catch (e) {
+            if (e instanceof JSException)
+                return scriptError(e.name, e.message, e.stack ?? "", input.code);
+            throw e;
+        }
+        const settled = burst(() => vm.callFunction(runner, vm.undefined, fnH));
+        for (;;) {
+            burst(() => vm.executePendingJobs());
+            if (stop)
+                return { ok: false, error: stop };
+            if (settled.promiseState !== 0)
+                break;
+            if (pending.size === 0) {
+                return {
+                    ok: false,
+                    error: { kind: "script", message: "the script awaits something that can never settle" },
+                };
+            }
+            await new Promise((resolve) => (wake = resolve));
+        }
+        // The runner settles every outcome as a value; it never rejects.
+        const r = await vm.resolvePromise(settled);
+        const result = vm.dump("value" in r ? r.value : r.error);
+        if (result.ok)
+            return { ok: true, json: result.json };
+        return scriptError(result.name ?? "", result.message ?? "", result.stack ?? "", input.code);
+    }
+    catch (e) {
+        if (stop)
+            return { ok: false, error: stop };
+        if (e instanceof JSException)
+            return scriptError(e.name, e.message, e.stack ?? "", input.code);
+        // A trap (stack overflow on the host side, an import that threw) leaves
+        // the VM unusable; it is discarded with this thread.
+        return {
+            ok: false,
+            error: { kind: "limit", message: `sandbox stopped: ${e instanceof Error ? e.message : e}` },
+        };
+    }
+    finally {
+        try {
+            vm.dispose();
+        }
+        catch {
+            // a trapped VM may refuse to dispose; the thread exits anyway
+        }
+    }
+}
+port.postMessage({ t: "done", outcome: await main() });
+port.close();

package/dist/server/designGuide.d.ts

@@ -0,0 +1,16 @@
+import type { DesignSettings } from "./types.ts";
+export declare const GUIDE_TOPICS: readonly ["knobs", "asks", "surfaces", "html", "feedback", "http", "scripts"];
+export type GuideTopic = (typeof GUIDE_TOPICS)[number];
+export declare const isGuideTopic: (id: unknown) => id is GuideTopic;
+export declare const unknownTopicMessage: (topic: string) => string;
+export declare function iconsLine(design: DesignSettings | null): string;
+/**
+ * What the repo's DESIGN.md, DTCG tokens and shadcn components.json say, as
+ * init stored them. Empty when the repo has none.
+ */
+export declare function designFilesSection(design: DesignSettings | null): string;
+/**
+ * The project-aware brief. `design` is the stored `design:<project>` settings,
+ * or null for a project that never ran `mockpit init`.
+ */
+export declare function renderBriefGuide(design: DesignSettings | null): string;