mockpit 0.0.0-stage → 1.0.0

package/dist/server/knobs.js

@@ -0,0 +1,333 @@
+// Knob schema and value validation (plan Q3: values are checked against the
+// declared schema before they are stored or used). Runtime-agnostic. The config
+// shape mirrors tunekit's usePane config; see the knob types in types.ts.
+const MAX_KNOBS = 100;
+const MAX_OPTIONS = 100;
+const MAX_STRING = 500;
+const MAX_TEXT_VALUE = 2000;
+// A path is "size" (global) or "<part>.<name>"; segments stay CSS/attribute-safe
+// because the bridge turns them into `--k-<path>` vars and `data-k-<path>` attrs.
+const PATH_RE = /^[A-Za-z_][\w-]{0,63}(\.[A-Za-z_][\w-]{0,63}){0,3}$/;
+// Color values end up inside CSS custom properties, so only the characters a
+// CSS color or gradient needs are allowed.
+const COLOR_RE = /^[#\w\s(),.%/+-]{1,300}$/;
+// The character class above still admits `url(//host/x)` and `image(...)`, which
+// would turn a colour var into a network fetch inside the sandbox; a colour never
+// needs either function.
+const COLOR_FETCH_RE = /\b(url|image|image-set|src)\s*\(/i;
+const isCssColor = (v) => COLOR_RE.test(v) && !COLOR_FETCH_RE.test(v);
+const COLOR_HINT = /^(#|rgba?\(|hsla?\(|hwb\(|lab\(|lch\(|oklab\(|oklch\(|color\(|(linear|radial|conic)-gradient\()/i;
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isStr = (v, max = MAX_STRING) => typeof v === "string" && v.length <= max;
+function checkAxis(raw, name) {
+    if (!Array.isArray(raw) || raw.length < 3 || raw.length > 4 || !raw.every(isNum)) {
+        return { ok: false, error: `${name} must be [default, min, max, step?] numbers` };
+    }
+    const [value, min, max, step] = raw;
+    if (min > max)
+        return { ok: false, error: `${name} min is above max` };
+    if (value < min || value > max)
+        return { ok: false, error: `${name} default is outside min..max` };
+    if (step !== undefined && step <= 0)
+        return { ok: false, error: `${name} step must be positive` };
+    return { ok: true, value: raw.slice() };
+}
+function checkOptions(raw, name) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_OPTIONS) {
+        return { ok: false, error: `${name} options must be a non-empty array` };
+    }
+    const out = [];
+    for (const o of raw) {
+        if (isStr(o))
+            out.push(o);
+        else if (o && typeof o === "object" && isStr(o.value) && isStr(o.label)) {
+            out.push({ value: o.value, label: o.label });
+        }
+        else
+            return { ok: false, error: `${name} options must be strings or {value, label}` };
+    }
+    return { ok: true, value: out };
+}
+const optionValues = (options) => (options ?? []).map((o) => (typeof o === "string" ? o : o.value));
+// Expand tunekit's shorthands into an explicit control, the same way tunekit's
+// config parser does (a string is a color when it looks like one, else text).
+export function explicitKnob(config) {
+    if (Array.isArray(config)) {
+        const [value, min, max, step] = config;
+        return { type: "slider", value, min, max, ...(step === undefined ? {} : { step }) };
+    }
+    if (typeof config === "number") {
+        if (config >= 0 && config <= 1)
+            return { type: "slider", value: config, min: 0, max: 1 };
+        if (config >= 0)
+            return { type: "slider", value: config, min: 0, max: config * 3 || 10 };
+        return { type: "slider", value: config, min: config * 3, max: -config * 3 };
+    }
+    if (typeof config === "boolean")
+        return { type: "toggle", value: config };
+    if (typeof config === "string") {
+        return COLOR_HINT.test(config)
+            ? { type: "color", value: config }
+            : { type: "text", value: config };
+    }
+    return config;
+}
+// Validate one declared knob and return a clean copy (unknown keys dropped).
+export function checkKnobConfig(path, raw) {
+    const name = `knob "${path}"`;
+    if (Array.isArray(raw))
+        return checkAxis(raw, name);
+    if (isNum(raw) || typeof raw === "boolean")
+        return { ok: true, value: raw };
+    if (typeof raw === "string") {
+        return raw.length <= MAX_STRING
+            ? { ok: true, value: raw }
+            : { ok: false, error: `${name} is too long` };
+    }
+    if (!raw || typeof raw !== "object")
+        return { ok: false, error: `${name} is not a knob` };
+    const k = raw;
+    switch (k.type) {
+        case "slider": {
+            const axis = checkAxis([k.value, k.min, k.max, ...(k.step === undefined ? [] : [k.step])], name);
+            if (!axis.ok)
+                return axis;
+            const [value, min, max, step] = axis.value;
+            return {
+                ok: true,
+                value: { type: "slider", value, min, max, ...(step === undefined ? {} : { step }) },
+            };
+        }
+        case "toggle":
+            return typeof k.value === "boolean"
+                ? { ok: true, value: { type: "toggle", value: k.value } }
+                : { ok: false, error: `${name} toggle needs a boolean value` };
+        case "select": {
+            const options = checkOptions(k.options, name);
+            if (!options.ok)
+                return options;
+            if (k.value !== undefined && !optionValues(options.value).includes(k.value)) {
+                return { ok: false, error: `${name} value is not one of its options` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "select",
+                    options: options.value,
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                },
+            };
+        }
+        case "color": {
+            if (k.value !== undefined && !(typeof k.value === "string" && isCssColor(k.value))) {
+                return { ok: false, error: `${name} color value is not a CSS color` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "color",
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                    ...(k.gradient === true ? { gradient: true } : {}),
+                    ...(isStr(k.contrast) && isCssColor(k.contrast) ? { contrast: k.contrast } : {}),
+                },
+            };
+        }
+        case "text":
+            if (k.value !== undefined && !isStr(k.value, MAX_TEXT_VALUE)) {
+                return { ok: false, error: `${name} text value must be a string` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "text",
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                    ...(isStr(k.placeholder) ? { placeholder: k.placeholder } : {}),
+                },
+            };
+        case "spring": {
+            const out = { type: "spring" };
+            for (const key of ["stiffness", "damping", "mass", "visualDuration", "bounce"]) {
+                if (k[key] === undefined)
+                    continue;
+                if (!isNum(k[key]))
+                    return { ok: false, error: `${name} ${key} must be a number` };
+                out[key] = k[key];
+            }
+            return { ok: true, value: out };
+        }
+        case "easing": {
+            if (!isNum(k.duration) || k.duration < 0) {
+                return { ok: false, error: `${name} easing needs a duration` };
+            }
+            if (!Array.isArray(k.ease) || k.ease.length !== 4 || !k.ease.every(isNum)) {
+                return { ok: false, error: `${name} ease must be four numbers` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "easing",
+                    duration: k.duration,
+                    ease: [...k.ease],
+                },
+            };
+        }
+        case "image": {
+            let options;
+            if (k.options !== undefined) {
+                const checked = checkOptions(k.options, name);
+                if (!checked.ok)
+                    return checked;
+                options = checked.value;
+            }
+            if (k.value !== undefined && !isStr(k.value, MAX_TEXT_VALUE)) {
+                return { ok: false, error: `${name} image value must be a string` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "image",
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                    ...(options ? { options } : {}),
+                },
+            };
+        }
+        case "pad": {
+            const out = { type: "pad" };
+            for (const axis of ["x", "y"]) {
+                if (k[axis] === undefined)
+                    continue;
+                const checked = checkAxis(k[axis], `${name} ${axis}`);
+                if (!checked.ok)
+                    return checked;
+                out[axis] = checked.value;
+            }
+            if (k.labels && typeof k.labels === "object") {
+                out.labels = {
+                    ...(isStr(k.labels.x) ? { x: k.labels.x } : {}),
+                    ...(isStr(k.labels.y) ? { y: k.labels.y } : {}),
+                };
+            }
+            return { ok: true, value: out };
+        }
+        default:
+            return { ok: false, error: `${name} has unknown type "${String(k.type)}"` };
+    }
+}
+export function checkKnobs(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: {} };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: "knobs must be an object of path → knob" };
+    }
+    const entries = Object.entries(raw);
+    if (entries.length > MAX_KNOBS)
+        return { ok: false, error: `at most ${MAX_KNOBS} knobs` };
+    const out = {};
+    for (const [path, config] of entries) {
+        if (!PATH_RE.test(path)) {
+            return { ok: false, error: `knob path "${path}" must be "name" or "part.name"` };
+        }
+        const checked = checkKnobConfig(path, config);
+        if (!checked.ok)
+            return checked;
+        out[path] = checked.value;
+    }
+    return { ok: true, value: out };
+}
+const axisOf = (axis) => axis ? [axis[1], axis[2]] : [-1, 1];
+// Whether `value` is something the declared knob could hold.
+export function checkKnobValue(path, config, value) {
+    const knob = explicitKnob(config);
+    const bad = (what) => ({
+        ok: false,
+        error: `value for knob "${path}" ${what}`,
+    });
+    switch (knob.type) {
+        case "slider":
+            if (!isNum(value))
+                return bad("must be a number");
+            if (value < knob.min || value > knob.max)
+                return bad(`must be within ${knob.min}..${knob.max}`);
+            return { ok: true, value };
+        case "toggle":
+            return typeof value === "boolean" ? { ok: true, value } : bad("must be true or false");
+        case "select":
+            return typeof value === "string" && optionValues(knob.options).includes(value)
+                ? { ok: true, value }
+                : bad(`must be one of ${optionValues(knob.options).join(", ")}`);
+        case "color":
+            return typeof value === "string" && isCssColor(value)
+                ? { ok: true, value }
+                : bad("must be a CSS color");
+        case "text":
+            return isStr(value, MAX_TEXT_VALUE) ? { ok: true, value } : bad("must be a string");
+        case "image":
+            if (!isStr(value, MAX_TEXT_VALUE))
+                return bad("must be a string");
+            if (knob.options && !optionValues(knob.options).includes(value)) {
+                return bad(`must be one of ${optionValues(knob.options).join(", ")}`);
+            }
+            return { ok: true, value };
+        case "pad": {
+            if (!value || typeof value !== "object")
+                return bad("must be {x, y}");
+            const { x, y } = value;
+            const [xMin, xMax] = axisOf(knob.x);
+            const [yMin, yMax] = axisOf(knob.y);
+            if (!isNum(x) || !isNum(y) || x < xMin || x > xMax || y < yMin || y > yMax) {
+                return bad("must be {x, y} within the pad's range");
+            }
+            return { ok: true, value: { x, y } };
+        }
+        case "spring":
+        case "easing": {
+            // tunekit lets a transition knob switch between spring and easing modes.
+            const checked = checkKnobConfig(path, value);
+            if (!checked.ok)
+                return checked;
+            const t = checked.value;
+            return t && typeof t === "object" && (t.type === "spring" || t.type === "easing")
+                ? { ok: true, value: t }
+                : bad("must be a spring or easing");
+        }
+    }
+}
+// The declared knob for a path: the mock's own, else a variant's override.
+export function knobFor(path, mock, posts) {
+    if (Object.hasOwn(mock.knobs, path))
+        return mock.knobs[path];
+    for (const p of posts)
+        if (p.knobs && Object.hasOwn(p.knobs, path))
+            return p.knobs[path];
+    return undefined;
+}
+export function checkKnobValues(raw, mock, posts, what) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: {} };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: `${what} must be an object of knob path → value` };
+    }
+    const out = {};
+    for (const [path, value] of Object.entries(raw)) {
+        const config = knobFor(path, mock, posts);
+        if (config === undefined)
+            return { ok: false, error: `${what}: no knob "${path}" is declared` };
+        const checked = checkKnobValue(path, config, value);
+        if (!checked.ok)
+            return checked;
+        out[path] = checked.value;
+    }
+    return { ok: true, value: out };
+}
+// How many discrete choices a knob offers, or null when it is continuous. A knob
+// with only a handful is usually a decision dressed as a control (plan D12).
+export function discreteChoices(config) {
+    const knob = explicitKnob(config);
+    if (knob.type === "toggle")
+        return 2;
+    if (knob.type === "select")
+        return knob.options.length;
+    if (knob.type === "image" && knob.options)
+        return knob.options.length;
+    return null;
+}

package/dist/server/mcpHttp.d.ts

@@ -0,0 +1,53 @@
+import type { Hono } from "hono";
+import type { FlowContext, FlowResult } from "./app.ts";
+import { type GuideTopic } from "./designGuide.ts";
+import type { Asset, AssetKind, Store } from "./types.ts";
+type Flow<A extends unknown[]> = (...args: A) => Promise<FlowResult>;
+export interface McpFlows {
+    publish: Flow<[body: any, ctx: FlowContext]>;
+    list: Flow<[query: {
+        project?: string;
+    }]>;
+    get: Flow<[ref: unknown, query: {
+        project?: unknown;
+        body?: boolean;
+        history?: boolean;
+    }]>;
+    ask: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
+    exportMock: Flow<[
+        ref: unknown,
+        query: {
+            project?: unknown;
+            state?: unknown;
+            variant?: unknown;
+        },
+        ctx: FlowContext
+    ]>;
+    say: Flow<[ref: unknown, body: any]>;
+    feedback: Flow<[query: {
+        session?: unknown;
+        project?: unknown;
+    }]>;
+}
+export interface McpDeps {
+    store: Store;
+    basePath?: (request: Request) => string;
+    flows: McpFlows;
+    run: Flow<[body: any, ctx: FlowContext]>;
+    uploadAsset(input: {
+        data: Uint8Array;
+        contentType: string;
+        filename?: string;
+        kind?: AssetKind;
+        session?: string;
+    }): Promise<{
+        asset: Omit<Asset, "data">;
+    } | {
+        error: string;
+        status: number;
+    }>;
+    guide(project: string, topic?: GuideTopic): string | Promise<string>;
+}
+export declare function unwrap(result: FlowResult): unknown;
+export declare function registerMcp(app: Hono, deps: McpDeps): void;
+export {};

package/dist/server/mcpHttp.js

@@ -0,0 +1,143 @@
+import { decodeBase64 } from "./base64.js";
+import { isGuideTopic, unknownTopicMessage } from "./designGuide.js";
+import { HTTP_MCP_TOOLS, HTTP_RUN_TOOLS, MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, toolResult, } from "./mcpSpec.js";
+import { RUN_INSTRUCTIONS } from "./runApi.js";
+// A flow's error status becomes a tool error carrying the same JSON body the
+// REST tier returns, so the agent sees the hint (states, variants) either way.
+export function unwrap(result) {
+    if (result.status >= 400) {
+        const { error, ...extra } = result.body ?? {};
+        throw new Error(Object.keys(extra).length ? `${error} ${JSON.stringify(extra)}` : String(error));
+    }
+    return result.body;
+}
+export function registerMcp(app, deps) {
+    const { flows, store } = deps;
+    async function projectOf(args) {
+        if (typeof args.project === "string" && args.project)
+            return args.project;
+        if (typeof args.session === "string") {
+            const session = await store.getSession(args.session);
+            if (session?.project)
+                return session.project;
+        }
+        const projects = await store.listProjects();
+        return projects[0]?.name ?? "workspace";
+    }
+    async function callTool(name, args, ctx) {
+        switch (name) {
+            case "publish":
+                return unwrap(await flows.publish(args, ctx));
+            case "ask":
+                return unwrap(await flows.ask(args.mock, args, ctx));
+            case "read":
+                if (args.mock === undefined)
+                    return unwrap(await flows.list({ project: args.project }));
+                return unwrap(await flows.get(args.mock, {
+                    project: args.project,
+                    body: args.body === true,
+                    history: args.history === true,
+                }));
+            case "feedback":
+                return unwrap(await flows.feedback({ session: args.session, project: args.project }));
+            case "say":
+                return unwrap(await flows.say(args.mock, args));
+            case "export":
+                return unwrap(await flows.exportMock(args.mock, args, ctx));
+            case "upload": {
+                if (typeof args.data !== "string" || args.data.length === 0) {
+                    throw new Error("upload needs base64 `data`");
+                }
+                const result = await deps.uploadAsset({
+                    data: decodeBase64(args.data),
+                    contentType: typeof args.contentType === "string" ? args.contentType : "",
+                    filename: typeof args.filename === "string" ? args.filename : undefined,
+                    kind: args.kind === "image" || args.kind === "file" ? args.kind : undefined,
+                    session: typeof args.session === "string" ? args.session : undefined,
+                });
+                if ("error" in result)
+                    throw new Error(result.error);
+                return {
+                    id: result.asset.id,
+                    sessionId: result.asset.sessionId,
+                    url: `${ctx.base}/a/${result.asset.id}`,
+                    contentType: result.asset.contentType,
+                    byteLength: result.asset.byteLength,
+                    kind: result.asset.kind,
+                };
+            }
+            case "guide": {
+                if (args.topic === undefined)
+                    return await deps.guide(await projectOf(args));
+                if (!isGuideTopic(args.topic))
+                    throw new Error(unknownTopicMessage(String(args.topic)));
+                return await deps.guide("", args.topic);
+            }
+            default:
+                throw new Error(`unknown tool: ${name}`);
+        }
+    }
+    app.post("/mcp", async (c) => {
+        const rpc = (id, result) => c.json({ jsonrpc: "2.0", id, result });
+        // `?mode=code` is the opt-in codemode catalog for clients without a
+        // harness of their own: one `run` tool instead of the mock tools.
+        const code = c.req.query("mode") === "code";
+        const rpcError = (id, code, message, status = 200) => c.json({ jsonrpc: "2.0", id, error: { code, message } }, status);
+        let msg;
+        try {
+            msg = await c.req.json();
+        }
+        catch {
+            return rpcError(null, -32700, "parse error", 400);
+        }
+        if (Array.isArray(msg)) {
+            return rpcError(null, -32600, "batch requests are not supported", 400);
+        }
+        if (msg.method === "initialize") {
+            return rpc(msg.id, {
+                protocolVersion: typeof msg.params?.protocolVersion === "string"
+                    ? msg.params.protocolVersion
+                    : "2025-03-26",
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: MCP_SERVER_INFO,
+                instructions: code ? RUN_INSTRUCTIONS : MCP_INSTRUCTIONS,
+            });
+        }
+        if (msg.id === undefined)
+            return c.body(null, 202); // notifications
+        if (msg.method === "ping")
+            return rpc(msg.id, {});
+        if (msg.method === "tools/list") {
+            return rpc(msg.id, { tools: code ? HTTP_RUN_TOOLS : HTTP_MCP_TOOLS });
+        }
+        if (msg.method === "tools/call") {
+            const url = new URL(c.req.url);
+            const ctx = {
+                base: `${url.origin}${deps.basePath?.(c.req.raw) ?? ""}`,
+                // An MCP caller is an agent, never the viewer.
+                viewer: false,
+                strict: false,
+                request: c.req.raw,
+                signal: c.req.raw.signal,
+            };
+            try {
+                const name = msg.params?.name;
+                if (name === "run") {
+                    const args = msg.params?.arguments ?? {};
+                    return rpc(msg.id, runToolResult(unwrap(await deps.run(args, ctx))));
+                }
+                return rpc(msg.id, toolResult(name, await callTool(name, msg.params?.arguments ?? {}, ctx)));
+            }
+            catch (err) {
+                return rpc(msg.id, {
+                    content: [{ type: "text", text: `error: ${err instanceof Error ? err.message : err}` }],
+                    isError: true,
+                });
+            }
+        }
+        return rpcError(msg.id, -32601, `method not found: ${msg.method}`);
+    });
+    // Stateless server: no SSE stream to resume, no session to delete.
+    app.get("/mcp", (c) => c.text("mockpit MCP is stateless — POST JSON-RPC messages here", 405));
+    app.delete("/mcp", (c) => c.body(null, 405));
+}