mockpit 0.0.0-stage → 1.0.0

package/dist/server/types.js

@@ -0,0 +1,299 @@
+// Shared data model — no runtime imports, safe for any platform.
+// A post is an ordered list of surfaces. Each surface declares its own kind;
+// the post itself is kind-agnostic. An `html` surface is arbitrary agent
+// markup rendered in an opaque-origin iframe. Rich text/code kinds are structured
+// data rendered into sandboxed documents; image/json stay as data rendered
+// natively by the trusted viewer. A diagram-with-its-diff is `[html, diff]`.
+// The canonical, ordered list of every surface kind — the single source of
+// truth. `SurfaceKind` derives from it, and the MCP tool schemas (mcpSpec.ts)
+// build their `kind` enums from it, so a kind can't be added to the model
+// without the MCP tier advertising it too (the gap that left `json`/`code`
+// publishable over CLI/REST but invisible to MCP). The per-kind FIELD schemas
+// in postSurfaces.ts and mcpSpec.ts are still hand-written; test/mcpSpec.test.ts
+// guards that every kind here round-trips through both the MCP schema and the
+// validator with its fields, so neither half can silently fall behind.
+export const SURFACE_KINDS = [
+    "html",
+    "diff",
+    "image",
+    "markdown",
+    "terminal",
+    "mermaid",
+    "json",
+    "code",
+];
+export const SURFACE_KIND_METADATA = {
+    html: { contentField: "html", sandboxed: true },
+    diff: { contentField: "patch", sandboxed: true, frameClass: "diffframe" },
+    image: { sandboxed: false },
+    markdown: { contentField: "markdown", sandboxed: true, frameClass: "mdframe" },
+    terminal: { contentField: "text", sandboxed: true, frameClass: "termframe" },
+    mermaid: { contentField: "mermaid", sandboxed: true, frameClass: "mermaidframe" },
+    json: { contentField: "data", sandboxed: false },
+    code: { contentField: "code", sandboxed: true, frameClass: "codeframe" },
+};
+export const SURFACE_KIND_LIST = SURFACE_KINDS.join(", ");
+export const SANDBOXED_SURFACE_KINDS = SURFACE_KINDS.filter((kind) => SURFACE_KIND_METADATA[kind].sandboxed);
+export const NATIVE_SURFACE_KINDS = SURFACE_KINDS.filter((kind) => !SURFACE_KIND_METADATA[kind].sandboxed);
+export const SURFACE_CONTENT_FIELDS = Object.fromEntries(SURFACE_KINDS.flatMap((kind) => {
+    const meta = SURFACE_KIND_METADATA[kind];
+    const field = "contentField" in meta ? meta.contentField : undefined;
+    return field ? [[kind, field]] : [];
+}));
+export const SURFACE_FRAME_CLASSES = Object.fromEntries(SURFACE_KINDS.flatMap((kind) => {
+    const meta = SURFACE_KIND_METADATA[kind];
+    const frameClass = "frameClass" in meta ? meta.frameClass : undefined;
+    return frameClass ? [[kind, frameClass]] : [];
+}));
+export function isSurfaceKind(kind) {
+    return typeof kind === "string" && Object.hasOwn(SURFACE_KIND_METADATA, kind);
+}
+export function isSandboxedSurfaceKind(kind) {
+    return isSurfaceKind(kind) && SURFACE_KIND_METADATA[kind].sandboxed;
+}
+// The viewer's write-in option on every ask. Reserved, so a delivered
+// `{id: "other", other: true}` choice never shadows an option the agent declared.
+export const OTHER_ID = "other";
+export const HISTORY_LIMIT = 20;
+// "user" is the reserved trust label for genuine human comments. A session
+// agent with that name could otherwise have its programmatic comments delivered
+// as user feedback, so the store normalizes it when creating sessions.
+export function reservedAgent(name) {
+    return name === "user" ? "agent" : name;
+}
+// SQLite terminates a TEXT value at the first embedded NUL byte. A NUL has no
+// place in a title/comment/label anyway, so stored text is stripped of it
+// (removing the byte, not truncating). Returns the input untouched when there's
+// nothing to strip, so the common path is free.
+const NUL_CHAR = String.fromCharCode(0);
+export function stripNul(s) {
+    return (typeof s === "string" && s.includes(NUL_CHAR) ? s.replaceAll(NUL_CHAR, "") : s);
+}
+// Per-asset upload cap (enforced at the HTTP/MCP edge → 413) and the workspace-wide
+// budget the store evicts down to. One Durable Object holds the whole workspace, so
+// the budget sits well under its ~10 GB SQLite ceiling.
+export const MAX_ASSET_BYTES = 5 * 1024 * 1024;
+export const MAX_WORKSPACE_ASSET_BYTES = 2 * 1024 * 1024 * 1024;
+// Short, unguessable id: 8 random bytes (64 bits) as 11 url-safe base64 chars.
+// These double as bearer capabilities: in publicRead mode `/s/:id` and
+// `/api/mocks/:id` are reachable without the workspace token, so the id IS the
+// share secret and must resist enumeration. btoa is a global in both Node and
+// Workers.
+export const newId = () => {
+    let id = btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(8))))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+    // Ids are used as CLI positional args and path segments. A leading "-" or
+    // "_" makes node:util parseArgs treat them as options, so swap a leading
+    // separator for an alphanumeric.
+    if (id[0] === "-" || id[0] === "_")
+        id = "0" + id.slice(1);
+    return id;
+};
+// Content-addressed asset id: the lowercase hex SHA-256 of the bytes. Because
+// it depends only on the content, an agent can derive `/a/:id` from the bytes
+// alone — no upload round-trip — and write the URL into a surface before (or
+// while) the upload lands. Identical uploads collapse to one stored blob.
+export async function hashAssetId(data) {
+    // Copy into a fresh ArrayBuffer-backed view: digest wants a definite
+    // ArrayBuffer, and this also avoids the SharedArrayBuffer-backed lib type.
+    const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(data));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+// Assign a stable id to every surface that lacks one, preserving existing ids.
+export function normalizeSurfaceIds(surfaces) {
+    return surfaces.map((s) => (s.id ? s : { ...s, id: newId() }));
+}
+// Fallback project for sessions that never declared one (bare `curl` publishes).
+export const DEFAULT_PROJECT = "workspace";
+export const DEFAULT_VARIANT = "default";
+// Stable, url-safe slug derived from a title. Empty input yields "mock" so a
+// slug is never the empty string.
+export function slugify(input) {
+    const slug = input
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)
+        .replace(/-+$/g, "");
+    return slug || "mock";
+}
+// Last path segment of a working directory, for sessions that never declared a
+// project. Handles both separators so a Windows cwd resolves the same way.
+export function projectFromCwd(cwd) {
+    if (!cwd)
+        return null;
+    const parts = cwd.split(/[/\\]+/).filter(Boolean);
+    return parts.length > 0 ? parts[parts.length - 1] : null;
+}
+export const htmlSurface = (html, kits) => ({
+    kind: "html",
+    html,
+    ...(Array.isArray(kits) && kits.length > 0
+        ? { kits: kits.filter((k) => typeof k === "string") }
+        : {}),
+});
+// An open ask is one no reply has answered yet: a write-in or a note alone
+// answers it too ("Neither, because…").
+export const askAnswered = (a) => a.answer !== undefined || a.other !== undefined || a.note !== undefined;
+export const openAsks = (mock) => mock.asks.filter((a) => !askAnswered(a));
+// How many built-in "Which one?" asks the viewer shows: one mock-wide when every
+// state needs one and the live names line up, else one per needing state. Same
+// rule as viewer/src/logic.ts builtinAsks, so Home, `read` and `pending` count
+// the question the user actually sees. Answering it archives the losers, which
+// is what makes it stop counting.
+export function builtinAskCount(mock, posts, mockId) {
+    const live = (state) => posts
+        .filter((p) => p.mock === mockId && p.state === state && p.status !== "archived")
+        .map((p) => p.variant);
+    const needs = (state) => {
+        const names = live(state);
+        if (names.length < 2)
+            return false;
+        return !mock.asks.some((a) => (a.scope === "mock" || (a.scope === "state" && a.state === state)) &&
+            names.every((n) => a.options.some((o) => o.variant === n)));
+    };
+    const states = mock.states.length ? mock.states : [null];
+    const needing = states.filter(needs);
+    if (!needing.length)
+        return 0;
+    const key = (state) => [...live(state)].sort().join("\n");
+    const first = key(needing[0]);
+    return needing.length === states.length && states.every((st) => key(st) === first)
+        ? 1
+        : needing.length;
+}
+export const openCount = (mock, posts) => openAsks(mock).length + builtinAskCount(mock, posts, mock.id);
+// The viewer's built-in "Which one?" for variants no agent ask binds: `variant`
+// mock-wide, `variant:<state>` per state. Never stored; synthesized from the
+// variants so a reply answering it validates, flips and reads like any ask. An
+// option's id is the variant name, so the viewer needs no id mapping.
+export const BUILTIN_ASK_ID = "variant";
+export function builtinAsk(mock, posts, id) {
+    let state = null;
+    if (id !== BUILTIN_ASK_ID) {
+        if (!id.startsWith(`${BUILTIN_ASK_ID}:`))
+            return undefined;
+        state = id.slice(BUILTIN_ASK_ID.length + 1);
+        if (!mock.states.includes(state))
+            return undefined;
+    }
+    const names = [
+        ...new Set(posts.filter((p) => state === null || p.state === state).map((p) => p.variant)),
+    ];
+    if (names.length === 0)
+        return undefined;
+    return {
+        id,
+        text: "Which one?",
+        scope: state === null ? "mock" : "state",
+        ...(state === null ? {} : { state }),
+        options: names.map((v) => ({ id: v, label: v, variant: v })),
+        at: "",
+    };
+}
+// Per-project rollup for the projects list. Pure, so every store agrees on
+// what "open" and "lastActiveAt" mean.
+export function summarizeProjects(mocks, sessions, posts = []) {
+    const byProject = new Map();
+    for (const m of mocks) {
+        const list = byProject.get(m.project);
+        if (list)
+            list.push(m);
+        else
+            byProject.set(m.project, [m]);
+    }
+    const sessionCounts = new Map();
+    const sessionActive = new Map();
+    for (const s of sessions) {
+        const name = s.project ?? projectFromCwd(s.cwd) ?? DEFAULT_PROJECT;
+        sessionCounts.set(name, (sessionCounts.get(name) ?? 0) + 1);
+        const prev = sessionActive.get(name);
+        if (!prev || s.lastActiveAt > prev)
+            sessionActive.set(name, s.lastActiveAt);
+    }
+    const names = new Set([...byProject.keys(), ...sessionCounts.keys()]);
+    return [...names]
+        .map((name) => {
+        const list = byProject.get(name) ?? [];
+        const lastMock = list.reduce((max, m) => (m.updatedAt > max ? m.updatedAt : max), "");
+        return {
+            name,
+            mocks: list.length,
+            open: list.reduce((n, m) => n + openCount(m, posts), 0),
+            lastActiveAt: [lastMock, sessionActive.get(name) ?? ""].sort().pop() ?? "",
+            sessions: sessionCounts.get(name) ?? 0,
+        };
+    })
+        .sort((a, b) => b.lastActiveAt.localeCompare(a.lastActiveAt));
+}
+// The combined byte weight of a post's surfaces, for size limits. image
+// surfaces are tiny refs — the asset bytes they point at are bounded separately
+// by MAX_ASSET_BYTES, not this post cap.
+export function surfacesByteLength(surfaces) {
+    let n = 0;
+    for (const p of surfaces) {
+        if (p.kind === "html")
+            n += p.html.length;
+        else if (p.kind === "diff") {
+            n += p.patch?.length ?? 0;
+            for (const f of p.files ?? [])
+                n += f.before.length + f.after.length;
+        }
+        else if (p.kind === "image") {
+            n += p.assetId.length + (p.alt?.length ?? 0) + (p.caption?.length ?? 0);
+        }
+        else if (p.kind === "markdown") {
+            n += p.markdown.length;
+        }
+        else if (p.kind === "terminal") {
+            n += p.text.length + (p.title?.length ?? 0);
+        }
+        else if (p.kind === "mermaid") {
+            n += p.mermaid.length;
+        }
+        else if (p.kind === "json") {
+            n += JSON.stringify(p.data).length;
+        }
+        else {
+            n +=
+                p.code.length + (p.language?.length ?? 0) + (p.title?.length ?? 0) + (p.lineStart ? 4 : 0);
+        }
+    }
+    return n;
+}
+// Collect the asset ids an ordered surfaces list references (image surfaces).
+// Used to keep referenced assets out of eviction's first wave. Assets embedded
+// by raw URL inside html markup are invisible here — touch-on-serve keeps those
+// warm instead.
+export function collectAssetIds(surfaces, out) {
+    for (const p of surfaces) {
+        if (p.kind === "image")
+            out.add(p.assetId);
+    }
+}
+// Pick the assets to evict so `incomingBytes` fits under `budget`. Oldest
+// (lastAccessedAt) first, but unreferenced assets go before referenced ones —
+// a live embed is only evicted as a last resort, once unreferenced candidates
+// are exhausted. Returns the ids to remove (possibly empty).
+export function selectEvictions(candidates, incomingBytes, budget) {
+    let total = candidates.reduce((sum, c) => sum + c.byteLength, 0);
+    if (total + incomingBytes <= budget)
+        return [];
+    const order = [...candidates].sort((a, b) => {
+        if (a.referenced !== b.referenced)
+            return a.referenced ? 1 : -1;
+        return a.lastAccessedAt.localeCompare(b.lastAccessedAt);
+    });
+    const evict = [];
+    for (const c of order) {
+        if (total + incomingBytes <= budget)
+            break;
+        evict.push(c.id);
+        total -= c.byteLength;
+    }
+    return evict;
+}

package/dist/workers/public.d.ts

@@ -0,0 +1 @@
+export { SqlStore } from "../server/sqlStore.js";

package/dist/workers/public.js

@@ -0,0 +1,3 @@
+// Stable Workers entrypoint for integrations that embed mockpit inside a
+// Cloudflare Durable Object and want the SQLite-backed Store implementation.
+export { SqlStore } from "../server/sqlStore.js";