mockpit 1.3.0 → 3.0.0

package/dist/server/index.js

@@ -1,12 +1,15 @@
 import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { compress } from "hono/compress";
 import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { homedir, networkInterfaces } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createApp } from "./app.js";
 import { createNodeExecutor } from "./codeRunner.js";
 import { GUIDE_TOPICS } from "./designGuide.js";
+import { GUIDE_PACKS } from "./guidance.js";
 import { createFileLog } from "./logFile.js";
 import { SqlStore } from "./sqlStore.js";
 import { createSqliteStorage } from "./sqliteStorage.js";
@@ -16,16 +19,18 @@ import { createSqliteStorage } from "./sqliteStorage.js";
 let root = join(dirname(fileURLToPath(import.meta.url)), "..");
 if (basename(root) === "dist")
     root = join(root, "..");
-const [viewerHtml, setupText, topicTexts, pkgJson] = await Promise.all([
+const [viewerHtml, setupText, topicTexts, packTexts, pkgJson] = await Promise.all([
     readFile(join(root, "viewer", "dist", "index.html"), "utf8").catch(() => {
         console.error("viewer build missing — run `npm run build:viewer` first");
         return process.exit(1);
     }),
     readFile(join(root, "guide", "AGENT_SETUP.md"), "utf8"),
     Promise.all(GUIDE_TOPICS.map((id) => readFile(join(root, "guide", "topics", `${id}.md`), "utf8"))),
+    Promise.all(GUIDE_PACKS.map((id) => readFile(join(root, "guide", "packs", `${id}.md`), "utf8"))),
     readFile(join(root, "package.json"), "utf8"),
 ]);
 const topics = Object.fromEntries(GUIDE_TOPICS.map((id, i) => [id, topicTexts[i]]));
+const packs = Object.fromEntries(GUIDE_PACKS.map((id, i) => [id, packTexts[i]]));
 // What renders surface documents: this server's own files and the locked
 // library versions. Hashed whole rather than picked apart, so an edit in dev or
 // an upgrade both reach browsers holding an old document; a change elsewhere
@@ -37,6 +42,10 @@ for (const name of (await readdir(serverDir)).sort()) {
         renderHash.update(await readFile(join(serverDir, name)));
 }
 renderHash.update(await readFile(join(root, "package-lock.json")).catch(() => pkgJson));
+// Browsers keep a version's document for a year, so a version changed outside
+// the API (a direct store edit) stays stale in them; a new salt on restart
+// re-fetches every document without touching code.
+renderHash.update(process.env.MOCKPIT_RENDER_SALT ?? "");
 const renderRev = renderHash.digest("hex").slice(0, 10);
 const pr = process.env.MOCKPIT_PUBLIC_READ;
 const publicRead = pr === "session" || pr === "full" ? pr : undefined;
@@ -45,7 +54,9 @@ const publicRead = pr === "session" || pr === "full" ? pr : undefined;
 // default lives in ~/.mockpit/, a user-owned dir that survives reinstalls and
 // is writable however the package was installed.
 const dbPath = process.env.MOCKPIT_DB ?? join(homedir(), ".mockpit", "mockpit.db");
-const store = new SqlStore(createSqliteStorage(dbPath));
+// Far past the Durable Object's budget: one lab of inlined pages can be 70 MB,
+// and a design that doesn't fit is re-read and re-parsed on every request.
+const store = new SqlStore(createSqliteStorage(dbPath), { postCacheBytes: 256 * 1024 * 1024 });
 console.log(`mockpit store: SQLite at ${dbPath}`);
 // The event log is on by default, next to the database, so a session can be
 // diagnosed after the fact without having planned to (`scripts/inspect.ts`).
@@ -57,11 +68,38 @@ const logPath = logSetting === "off"
     : logSetting || (dbPath === ":memory:" ? undefined : join(dirname(dbPath), "events.jsonl"));
 if (logPath)
     console.log(`mockpit event log: ${logPath}`);
+// The user's own rules live next to the database, so a throwaway or test
+// database never picks up the real ones.
+const rulesPath = dbPath === ":memory:" ? undefined : join(dirname(dbPath), "rules.md");
+const userRules = rulesPath ? () => readFile(rulesPath, "utf8").catch(() => null) : undefined;
+const port = Number(process.env.PORT ?? 8228);
+// MOCKPIT_HOST (or `serve --host`) restricts the listener to one address.
+// Unset keeps the previous behaviour — node's default, every interface — because
+// that is what a container or a LAN-shared instance needs. Set it to 127.0.0.1
+// when the server shares a host with anything you don't want reaching it; that
+// is stronger than the token, which is a single shared secret by design.
+const hostname = process.env.MOCKPIT_HOST || undefined;
+// The addresses a phone might open this server at. Read when asked, since a laptop
+// changes networks while it runs.
+const networkHosts = () => {
+    if (hostname === "127.0.0.1" || hostname === "::1" || hostname === "localhost") {
+        return { localOnly: true, hosts: [] };
+    }
+    if (hostname && hostname !== "0.0.0.0" && hostname !== "::") {
+        return { localOnly: false, hosts: [`${hostname}:${port}`] };
+    }
+    const hosts = Object.values(networkInterfaces())
+        .flat()
+        .flatMap((a) => (a && a.family === "IPv4" && !a.internal ? [`${a.address}:${port}`] : []));
+    return { localOnly: false, hosts: hosts.slice(0, 3) };
+};
 const app = createApp({
     store,
     viewerHtml,
     setupText,
     topics,
+    packs,
+    userRules,
     authToken: process.env.MOCKPIT_TOKEN,
     publicRead,
     // MOCKPIT_VERSION fakes the running version (manual testing of the
@@ -71,16 +109,16 @@ const app = createApp({
     renderRev,
     // `run` scripts execute in QuickJS inside a worker thread per run.
     executor: createNodeExecutor(),
+    networkHosts,
     log: logPath ? createFileLog(logPath) : undefined,
 });
-const port = Number(process.env.PORT ?? 8228);
-// MOCKPIT_HOST (or `serve --host`) restricts the listener to one address.
-// Unset keeps the previous behaviour — node's default, every interface — because
-// that is what a container or a LAN-shared instance needs. Set it to 127.0.0.1
-// when the server shares a host with anything you don't want reaching it; that
-// is stronger than the token, which is a single shared secret by design.
-const hostname = process.env.MOCKPIT_HOST || undefined;
-serve({ fetch: app.fetch, port, hostname }, (info) => {
+// Cloudflare compresses at its edge; a Node server reached over a network
+// (a tailnet, a LAN) would otherwise send the viewer and every list uncompressed.
+// Hono's filter leaves SSE streams alone.
+const outer = new Hono();
+outer.use(compress());
+outer.all("*", (c) => app.fetch(c.req.raw, c.env));
+serve({ fetch: outer.fetch, port, hostname }, (info) => {
     // Report the address actually bound. Printing "localhost" unconditionally hid
     // the fact that the default listens on every interface.
     const shown = hostname ?? "localhost";

package/dist/server/jump.d.ts

@@ -0,0 +1,21 @@
+import { type JumpRows, type DesignKind } from "./types.ts";
+export type JumpMatch = "title" | "state" | "variant" | "area" | "question" | "description";
+export interface JumpHit {
+    project: string;
+    id: string | null;
+    slug: string | null;
+    title: string;
+    kind: DesignKind | null;
+    width: number | null;
+    area: string | null;
+    match: JumpMatch;
+    text: string | null;
+    state: string | null;
+    variant: string | null;
+    archived: boolean;
+    open: number;
+    designArchived: boolean;
+    inUse: boolean;
+}
+export declare function jumpHits(rows: JumpRows, query: string, project: string | null): JumpHit[];
+export declare function recentHits(rows: JumpRows, ids: string[]): JumpHit[];

package/dist/server/jump.js

@@ -0,0 +1,175 @@
+// Search to jump: find a design by anything the user might remember it by, its
+// title, a state, a variant's name or note, a question, or its area. It reads
+// what `listJumpRows` hands it, which never includes surfaces, so a big
+// workspace costs its metadata and not its pages. This project comes first, then
+// the others. Runtime-agnostic (no node imports).
+import { isLive, openAsks } from "./types.js";
+const MAX_HERE = 20;
+const MAX_ELSEWHERE = 12;
+// A design whose variants all carry the word shouldn't push every other design off the list.
+const MAX_PER_DESIGN = 3;
+const SNIPPET = 90;
+// Precision before recall: what a design is called beats what was once said about it.
+const RANK = {
+    exact: 0,
+    prefix: 1,
+    word: 2,
+    title: 3,
+    state: 4,
+    variant: 5,
+    area: 6,
+    question: 7,
+    description: 8,
+};
+// "Cafe" finds "Café", and "food" finds "Food".
+const fold = (s) => s.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+function clip(text, term) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    if (flat.length <= SNIPPET)
+        return flat;
+    const at = Math.max(0, fold(flat).indexOf(term));
+    const start = at < SNIPPET / 3 ? 0 : at - Math.floor(SNIPPET / 3);
+    const cut = flat.slice(start, start + SNIPPET).trim();
+    return `${start > 0 ? "…" : ""}${cut}${start + SNIPPET < flat.length ? "…" : ""}`;
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function allHits(rows, terms, whole) {
+    const byDesign = new Map();
+    for (const v of rows.variants) {
+        const list = byDesign.get(v.designId);
+        if (list)
+            list.push(v);
+        else
+            byDesign.set(v.designId, [v]);
+    }
+    const has = (text) => {
+        const f = fold(text);
+        return terms.every((t) => f.includes(t));
+    };
+    const out = [];
+    const areasSeen = new Set();
+    for (const m of rows.designs) {
+        const variants = byDesign.get(m.id) ?? [];
+        const base = {
+            project: m.project,
+            id: m.id,
+            slug: m.slug,
+            title: m.title,
+            kind: m.kind,
+            width: m.widths[0] ?? null,
+            area: m.area,
+            open: openAsks(m).length,
+            designArchived: !!m.archivedAt,
+            inUse: variants.some((v) => v.status === "accepted"),
+            text: null,
+            state: null,
+            variant: null,
+            archived: false,
+        };
+        const mine = [];
+        const add = (rank, match, extra = {}) => mine.push({ hit: { ...base, match, ...extra }, rank, updatedAt: m.updatedAt });
+        const title = fold(m.title);
+        if (title === whole)
+            add(RANK.exact, "title");
+        else if (title.startsWith(whole))
+            add(RANK.prefix, "title");
+        else if (terms.every((t) => new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRe(t)}`, "u").test(title)))
+            add(RANK.word, "title");
+        else if (has(m.title) || has(m.slug))
+            add(RANK.title, "title");
+        for (const state of m.states) {
+            if (has(state))
+                add(RANK.state, "state", { text: state, state });
+        }
+        const namesSeen = new Set();
+        for (const v of variants) {
+            const gone = !isLive(v.status);
+            const tail = gone ? 0.5 : 0;
+            // A variant named "default" says nothing the design's title doesn't.
+            if (v.variant !== "default" && !namesSeen.has(v.variant) && has(v.variant)) {
+                namesSeen.add(v.variant);
+                add(RANK.variant + tail, "variant", {
+                    text: v.variant,
+                    state: v.state,
+                    variant: v.variant,
+                    archived: gone,
+                });
+            }
+            if (v.description && has(v.description)) {
+                add(RANK.description + tail, "description", {
+                    text: clip(v.description, terms[0]),
+                    state: v.state,
+                    variant: v.variant,
+                    archived: gone,
+                });
+            }
+        }
+        for (const ask of m.asks) {
+            if (has(ask.text)) {
+                add(RANK.question, "question", {
+                    text: clip(ask.text, terms[0]),
+                    state: ask.state ?? null,
+                });
+            }
+        }
+        mine.sort((a, b) => a.rank - b.rank);
+        out.push(...mine.slice(0, MAX_PER_DESIGN));
+        if (m.area && has(m.area) && !areasSeen.has(`${m.project}\n${m.area}`)) {
+            areasSeen.add(`${m.project}\n${m.area}`);
+            out.push({
+                hit: {
+                    ...base,
+                    id: null,
+                    slug: null,
+                    title: m.area,
+                    kind: null,
+                    width: null,
+                    match: "area",
+                    open: 0,
+                    designArchived: false,
+                    inUse: false,
+                },
+                rank: RANK.area,
+                updatedAt: m.updatedAt,
+            });
+        }
+    }
+    return out;
+}
+export function jumpHits(rows, query, project) {
+    const whole = fold(query).trim().replace(/\s+/g, " ");
+    const terms = whole.split(" ").filter(Boolean);
+    if (!terms.length)
+        return [];
+    const order = (a, b) => a.rank - b.rank || b.updatedAt.localeCompare(a.updatedAt);
+    const all = allHits(rows, terms, whole);
+    const here = all.filter((h) => h.hit.project === project).sort(order);
+    const elsewhere = all.filter((h) => h.hit.project !== project).sort(order);
+    return [...here.slice(0, MAX_HERE), ...elsewhere.slice(0, MAX_ELSEWHERE)].map((h) => h.hit);
+}
+// The designs this browser opened last, in that order, as they are called now: a
+// renamed one follows, and a deleted one drops out.
+export function recentHits(rows, ids) {
+    const wanted = new Map(ids.map((id, i) => [id, i]));
+    const inUse = new Set(rows.variants.filter((v) => v.status === "accepted").map((v) => v.designId));
+    return rows.designs
+        .filter((m) => wanted.has(m.id))
+        .sort((a, b) => wanted.get(a.id) - wanted.get(b.id))
+        .map((m) => ({
+        project: m.project,
+        id: m.id,
+        slug: m.slug,
+        title: m.title,
+        kind: m.kind,
+        width: m.widths[0] ?? null,
+        area: m.area,
+        match: "title",
+        text: null,
+        state: null,
+        variant: null,
+        archived: false,
+        open: openAsks(m).length,
+        designArchived: !!m.archivedAt,
+        inUse: inUse.has(m.id),
+    }));
+}

package/dist/server/knobs.d.ts

@@ -1,4 +1,4 @@
-import type { ExplicitKnob, KnobConfig, Knobs, KnobValue, Mock, Post } from "./types.ts";
+import type { ExplicitKnob, KnobConfig, Knobs, KnobValue, Design, Post } from "./types.ts";
 export type Checked<T> = {
     ok: true;
     value: T;
@@ -10,10 +10,10 @@ export declare function explicitKnob(config: KnobConfig): ExplicitKnob;
 export declare function checkKnobConfig(path: string, raw: unknown): Checked<KnobConfig>;
 export declare function checkKnobs(raw: unknown): Checked<Knobs>;
 export declare function checkKnobValue(path: string, config: KnobConfig, value: unknown): Checked<KnobValue>;
-export declare function knobFor(path: string, mock: Pick<Mock, "knobs">, posts: (Pick<Post, "knobs"> & {
+export declare function knobFor(path: string, design: Pick<Design, "knobs">, posts: (Pick<Post, "knobs"> & {
     surfaces?: Post["surfaces"];
 })[]): KnobConfig | undefined;
-export declare function checkKnobValues(raw: unknown, mock: Pick<Mock, "knobs">, posts: (Pick<Post, "knobs"> & {
+export declare function checkKnobValues(raw: unknown, design: Pick<Design, "knobs">, posts: (Pick<Post, "knobs"> & {
     surfaces?: Post["surfaces"];
 })[], what: string): Checked<Record<string, KnobValue>>;
 export declare function discreteChoices(config: KnobConfig): number | null;

package/dist/server/knobs.js

@@ -293,12 +293,12 @@ export function checkKnobValue(path, config, value) {
         }
     }
 }
-// The declared knob for a path: the mock's own, else a variant's override,
+// The declared knob for a path: the design's own, else a variant's override,
 // else the knob a variant's slot implies (fills.ts), so an option can `set` a
 // slot's fill without the agent declaring anything.
-export function knobFor(path, mock, posts) {
-    if (Object.hasOwn(mock.knobs, path))
-        return mock.knobs[path];
+export function knobFor(path, design, posts) {
+    if (Object.hasOwn(design.knobs, path))
+        return design.knobs[path];
     for (const p of posts)
         if (p.knobs && Object.hasOwn(p.knobs, path))
             return p.knobs[path];
@@ -311,7 +311,7 @@ export function knobFor(path, mock, posts) {
     }
     return undefined;
 }
-export function checkKnobValues(raw, mock, posts, what) {
+export function checkKnobValues(raw, design, posts, what) {
     if (raw === undefined || raw === null)
         return { ok: true, value: {} };
     if (typeof raw !== "object" || Array.isArray(raw)) {
@@ -319,7 +319,7 @@ export function checkKnobValues(raw, mock, posts, what) {
     }
     const out = {};
     for (const [path, value] of Object.entries(raw)) {
-        const config = knobFor(path, mock, posts);
+        const config = knobFor(path, design, posts);
         if (config === undefined)
             return { ok: false, error: `${what}: no knob "${path}" is declared` };
         const checked = checkKnobValue(path, config, value);

package/dist/server/mcpHttp.d.ts

@@ -11,13 +11,16 @@ export interface McpFlows {
     tree: Flow<[query: {
         project?: string;
     }]>;
+    decisions: 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<[
+    exportDesign: Flow<[
         ref: unknown,
         query: {
             project?: unknown;
@@ -27,10 +30,13 @@ export interface McpFlows {
         ctx: FlowContext
     ]>;
     say: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
+    move: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
     feedback: Flow<[query: {
         session?: unknown;
         project?: unknown;
     }, ctx: FlowContext]>;
+    edit: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
+    editProject: Flow<[name: unknown, body: any, ctx: FlowContext]>;
 }
 export interface McpDeps {
     store: Store;
@@ -52,5 +58,6 @@ export interface McpDeps {
     guide(project: string, topic?: GuideTopic): string | Promise<string>;
 }
 export declare function unwrap(result: FlowResult): unknown;
+export declare function editCall(flows: Pick<McpFlows, "edit" | "editProject">, args: any, ctx: FlowContext, project: string | undefined): Promise<FlowResult>;
 export declare function registerMcp(app: Hono, deps: McpDeps): void;
 export {};

package/dist/server/mcpHttp.js

@@ -11,6 +11,27 @@ export function unwrap(result) {
     }
     return result.body;
 }
+// `edit` is one verb with two shapes: `rename` or `areaOrder` edits the
+// project, anything else edits the design. Shared by both MCP transports' HTTP
+// side and `run`.
+export function editCall(flows, args, ctx, project) {
+    if (args.rename === undefined && args.areaOrder === undefined) {
+        return flows.edit(args.design, args, ctx);
+    }
+    if (args.design !== undefined) {
+        return Promise.resolve({
+            status: 400,
+            body: { error: '"rename" and "areaOrder" edit the project; edit the design without them' },
+        });
+    }
+    if (!project) {
+        return Promise.resolve({
+            status: 400,
+            body: { error: 'provide "project": the project to edit' },
+        });
+    }
+    return flows.editProject(project, { name: args.rename, areaOrder: args.areaOrder, session: args.session }, ctx);
+}
 export function registerMcp(app, deps) {
     const { flows, store } = deps;
     async function projectOf(args) {
@@ -24,6 +45,15 @@ export function registerMcp(app, deps) {
         const projects = await store.listProjects();
         return projects[0]?.name ?? "workspace";
     }
+    // Only a project the call names, or its session's: a rename never falls back
+    // to whichever project happens to be first.
+    async function namedProject(args) {
+        if (typeof args.project === "string" && args.project)
+            return args.project;
+        if (typeof args.session !== "string")
+            return undefined;
+        return (await store.getSession(args.session))?.project ?? undefined;
+    }
     async function loadImage(ref) {
         const asset = await store.getAsset(ref.id);
         return asset ? { data: asset.data, mimeType: asset.contentType } : null;
@@ -33,14 +63,17 @@ export function registerMcp(app, deps) {
             case "publish":
                 return unwrap(await flows.publish(args, ctx));
             case "ask":
-                return unwrap(await flows.ask(args.mock, args, ctx));
+                return unwrap(await flows.ask(args.design, args, ctx));
             case "read":
-                if (args.mock === undefined && args.tree === true) {
+                if (args.decisions === true) {
+                    return unwrap(await flows.decisions({ project: args.project }));
+                }
+                if (args.design === undefined && args.tree === true) {
                     return unwrap(await flows.tree({ project: args.project }));
                 }
-                if (args.mock === undefined)
+                if (args.design === undefined)
                     return unwrap(await flows.list({ project: args.project }));
-                return unwrap(await flows.get(args.mock, {
+                return unwrap(await flows.get(args.design, {
                     project: args.project,
                     body: args.body === true,
                     history: args.history === true,
@@ -48,9 +81,13 @@ export function registerMcp(app, deps) {
             case "feedback":
                 return unwrap(await flows.feedback({ session: args.session, project: args.project }, ctx));
             case "say":
-                return unwrap(await flows.say(args.mock, args, ctx));
+                return unwrap(await flows.say(args.design, args, ctx));
+            case "move":
+                return unwrap(await flows.move(args.design, args, ctx));
             case "export":
-                return unwrap(await flows.exportMock(args.mock, args, ctx));
+                return unwrap(await flows.exportDesign(args.design, args, ctx));
+            case "edit":
+                return unwrap(await editCall(flows, args, ctx, await namedProject(args)));
             case "upload": {
                 if (typeof args.data !== "string" || args.data.length === 0) {
                     throw new Error("upload needs base64 `data`");
@@ -87,7 +124,7 @@ export function registerMcp(app, deps) {
     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.
+        // harness of their own: one `run` tool instead of the design 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;

package/dist/server/mcpSpec.d.ts

@@ -19,6 +19,7 @@ export declare const mcpSurfaceSchema: z.ZodObject<{
     }>>;
     html: z.ZodOptional<z.ZodString>;
     kits: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    poster: z.ZodOptional<z.ZodString>;
     markdown: z.ZodOptional<z.ZodString>;
     mermaid: z.ZodOptional<z.ZodString>;
     patch: z.ZodOptional<z.ZodString>;
@@ -53,7 +54,7 @@ type Param = {
     d?: string;
     req?: boolean;
 } | {
-    t: "surfaces" | "asks" | "object" | "integers";
+    t: "surfaces" | "asks" | "object" | "integers" | "strings";
     d?: string;
     req?: boolean;
 };