mockpit 1.0.0 → 1.2.0

package/README.md

@@ -70,8 +70,10 @@ mockpit turns that into a design-decision loop:
 
 **Home** lists the project's mocks with a thumbnail, their states and how many
 questions are open, with "Answer next ›" to jump to the first one. Dark and
-light themes, toggled from the top bar. On a narrow screen the panel becomes a
-bottom sheet.
+light themes, toggled from the top bar. On a phone or tablet the panel becomes a
+bottom sheet, the stage scrolls under your finger and renders the design at a
+chosen width (Phone 390, Tablet 744, Desktop 820, Wide 1280), and Inspect opens
+the stage full screen to pan and pinch-zoom it.
 
 ## Quick start
 
@@ -155,7 +157,7 @@ and `mockpit watch` (one line per Send, for a background monitor).
   list (an entry that is only `{id}` keeps that surface), or `parts` to replace
   just the marked elements.
 - **`feedback` returns at once** with what the user sent since the agent last
-  heard, plus `pending`: whether the viewer is open and how far the user's
+  heard, plus `pending`: whether each mock is open in the viewer and how far the user's
   draft has got (`2 of 3 answered`). Every write returns `feedback` too, and
   each Send is delivered exactly once across all of them.
 - **Asks are nudged.** A publish that leaves several variants with no ask
@@ -185,6 +187,13 @@ It runs locally as a small Node server (SQLite at `~/.mockpit/mockpit.db`), or o
 Cloudflare Workers when your agent and browser are on different machines. See
 **[docs/deploying.md](docs/deploying.md)**.
 
+The server keeps an event log, one JSON line per agent call, viewer write and
+live-feed connection (ids and shapes, never content), at
+`~/.mockpit/events.jsonl` next to the database. It rolls over at 10 MB. Set
+`MOCKPIT_LOG` to another path, or to `off` to disable it; on Workers it goes to
+Workers Logs. `node scripts/inspect.ts` in a checkout reads it alongside the
+database and Claude Code transcripts.
+
 The server app is importable from `mockpit/server` (`createApp`, `SqlStore`,
 `createSqliteStorage`). The embeddable viewer engine (`mockpit/viewer-embed`,
 `mountViewer`) is gone: the viewer is self-hosted only.

package/bin/mockpit.js

@@ -19,6 +19,12 @@ const BASE = (process.env.MOCKPIT_URL ?? "http://localhost:8228").replace(/\/$/,
 const TOKEN = process.env.MOCKPIT_TOKEN;
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_VERSION = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
+// Every request names this client and its version, so the server's event log
+// can tell the CLI from MCP and spot one older than the server.
+const HEADERS = {
+  "x-mockpit-client": `cli/${PKG_VERSION}`,
+  ...(TOKEN ? { authorization: `Bearer ${TOKEN}` } : {}),
+};
 
 const HELP = `mockpit — a live visual surface for terminal coding agents
 
@@ -31,7 +37,9 @@ the loop (never blocks on the user):
   1. mockpit init once per repo; read the brief (mockpit guide).
   2. mockpit publish once per variant; mark parts with data-part.
   3. A choice is several variants plus one ask that binds them: mockpit ask
-     with options bound to variants. One render plus a control: --knobs.
+     with options bound to variants. A variant decides everything it differs
+     on; don't re-ask it. Visual options carry a variant or knob set. One
+     render plus a control: --knobs.
   4. Tell the user in one line where to look, then end your turn. The question
      itself lives in the mock (ask), never in chat. The user answers in the
      browser at their own pace. Never poll.
@@ -66,7 +74,8 @@ verbs:
                         --data is a JSON tree)
   mockpit ask --mock <slug> "<question>" --option <label[=variant]> ...
                                           ask the user; bind options to variants
-      --option <l[=v]>  an option (repeatable); "=variant" binds it to a variant
+      --option <l[=v]>  an option (repeatable); "=variant" binds it to a variant,
+                        "=knob:path=value" sets one knob
       --scope <s>       mock|state|part (default mock)
       --state <label>   the state a state-scoped ask is about
       --part <name>     the part a part-scoped ask is about
@@ -118,6 +127,7 @@ environment:
   MOCKPIT_URL      server base URL (default http://localhost:8228)
   MOCKPIT_TOKEN    bearer token for a deployed instance
   MOCKPIT_HOST     address serve binds to (default: every interface)
+  MOCKPIT_LOG      serve's event log file, or "off" (default ~/.mockpit/events.jsonl)
   MOCKPIT_SESSION  fixed session id (overrides auto-detection)
   MOCKPIT_AGENT    agent name used when creating sessions
 `;
@@ -241,7 +251,7 @@ async function api(path, init = {}, { report, fix } = {}) {
       ...init,
       headers: {
         "content-type": "application/json",
-        ...(TOKEN ? { authorization: `Bearer ${TOKEN}` } : {}),
+        ...HEADERS,
         ...init.headers,
       },
     });
@@ -364,7 +374,7 @@ async function resolveSession(flags, { create = false } = {}) {
   const state = readState();
   if (state.session && !flags["new-session"]) {
     const ok = await fetch(`${BASE}/api/sessions/${state.session}`, {
-      headers: TOKEN ? { authorization: `Bearer ${TOKEN}` } : {},
+      headers: HEADERS,
     }).then(
       (r) => r.ok,
       () => false,
@@ -394,7 +404,7 @@ async function resolveSession(flags, { create = false } = {}) {
 async function resolveSessionByCwd(cwd = process.cwd()) {
   try {
     const res = await fetch(`${BASE}/api/sessions`, {
-      headers: TOKEN ? { authorization: `Bearer ${TOKEN}` } : {},
+      headers: HEADERS,
     });
     if (!res.ok) return null;
     const sessions = await res.json();
@@ -533,7 +543,7 @@ async function uploadBytes(bytes, { filename, contentType, session, kind } = {})
       method: "POST",
       headers: {
         "content-type": contentType ?? "application/octet-stream",
-        ...(TOKEN ? { authorization: `Bearer ${TOKEN}` } : {}),
+        ...HEADERS,
       },
       body: bytes,
     });
@@ -818,19 +828,17 @@ function printFeedback(feedback) {
   if (feedback?.length) console.log(`feedback: ${JSON.stringify(feedback)}`);
 }
 
-// What the user is doing right now. viewerOpen is workspace-wide, so it is
-// said once rather than per mock.
+// What the user is doing right now, per mock.
 function pendingLines(pending) {
-  const rows = pending ?? [];
-  const lines = rows
-    .filter((p) => p.draft)
-    .map(
-      (p) =>
-        `pending: ${p.mock} — the user is answering (${p.draft.answered} of ${p.draft.of} answered, ${p.draft.comments} comment${p.draft.comments === 1 ? "" : "s"})`,
-    );
-  if (lines.length === 0 && rows.some((p) => p.viewerOpen))
-    lines.push("pending: the viewer is open");
-  return lines;
+  return (pending ?? []).flatMap((p) =>
+    p.draft
+      ? [
+          `pending: ${p.mock} — the user is answering (${p.draft.answered} of ${p.draft.of} answered, ${p.draft.comments} comment${p.draft.comments === 1 ? "" : "s"})`,
+        ]
+      : p.viewerOpen
+        ? [`pending: ${p.mock} — open in the viewer`]
+        : [],
+  );
 }
 
 function parsePublishFlags() {
@@ -953,8 +961,23 @@ async function publishMock() {
   return result;
 }
 
-// "Quiet" is an unbound option; "Quiet=quiet" binds it to the quiet variant.
+// "Quiet" is an unbound option; "Quiet=quiet" binds it to the quiet variant;
+// "Above=knob:trim.position=top" sets one knob. The value is JSON when it
+// parses (17, true), else a string, so slider and toggle values keep their type.
 function parseOption(raw) {
+  const knob = raw.indexOf("=knob:");
+  if (knob > 0) {
+    const pair = raw.slice(knob + "=knob:".length);
+    const eq = pair.indexOf("=");
+    if (eq <= 0)
+      die(`option "${raw}" needs knob:<path>=<value>`, "--option Above=knob:trim.position=top");
+    const text = pair.slice(eq + 1);
+    let value = text;
+    try {
+      value = JSON.parse(text);
+    } catch {}
+    return { label: raw.slice(0, knob), set: { [pair.slice(0, eq)]: value } };
+  }
   const at = raw.lastIndexOf("=");
   if (at <= 0) return { label: raw };
   return { label: raw.slice(0, at), variant: raw.slice(at + 1) };
@@ -981,6 +1004,7 @@ function printRun(r) {
 function watchLines(batch) {
   const lines = [];
   const name = batch.mock ?? "a mock";
+  if (batch.handoff) lines.push(`mockpit handoff on ${name}: ${batch.handoff}`);
   if (batch.reply) {
     const r = batch.reply;
     const bits = [
@@ -999,6 +1023,7 @@ function watchLines(batch) {
             .join(", ")}`
         : "",
       r.comments?.length ? `${r.comments.length} comment${r.comments.length === 1 ? "" : "s"}` : "",
+      r.reactions?.length ? r.reactions.join(", ") : "",
       r.decision ? r.decision.kind : "",
       r.text ?? "",
     ].filter(Boolean);
@@ -1020,7 +1045,7 @@ async function apiSoft(path) {
   let res;
   try {
     res = await fetch(`${BASE}${path}`, {
-      headers: TOKEN ? { authorization: `Bearer ${TOKEN}` } : {},
+      headers: HEADERS,
     });
   } catch {
     die(`cannot reach mockpit at ${BASE}`, "mockpit serve");
@@ -1375,6 +1400,7 @@ const commands = {
         `asked on ${result.mock}: ${ask.text} [${ask.options.map((o) => o.label).join(" | ")}]`,
       );
     }
+    for (const nudge of result.nudges ?? []) console.log(`nudge: ${nudge}`);
     console.log(`tell the user to look at ${result.url}, then end your turn`);
     printFeedback(result.feedback);
   },
@@ -1543,7 +1569,7 @@ const commands = {
       try {
         const res = await fetch(
           `${BASE}/api/comments${query({ session, author: "user", after: firstAfter, wait: 60 })}`,
-          { headers: TOKEN ? { authorization: `Bearer ${TOKEN}` } : {} },
+          { headers: HEADERS },
         );
         if (!res.ok) {
           await sleep(2000);

package/dist/mcp/server.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, STDIO_MCP_CATALOG, STDIO_MCP_TOOLS, STDIO_RUN_CATALOG, STDIO_RUN_TOOLS, toolResult, } from "../server/mcpSpec.js";
+import { MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, STDIO_MCP_CATALOG, STDIO_MCP_TOOLS, STDIO_RUN_CATALOG, STDIO_RUN_TOOLS, toolResult, withFeedbackImages, } from "../server/mcpSpec.js";
 import { RUN_INSTRUCTIONS } from "../server/runApi.js";
 // Point at a deployed instance later by setting MOCKPIT_URL.
 const API = process.env.MOCKPIT_URL ?? "http://localhost:8228";
@@ -12,8 +14,28 @@ const TOKEN = process.env.MOCKPIT_TOKEN;
 const AGENT = process.env.MOCKPIT_AGENT ?? "claude-code";
 // "code" serves the codemode catalog: one `run` tool instead of the mock tools.
 const CODE_MODE = process.env.MOCKPIT_MCP_MODE === "code";
+// Names this client in the server's event log; the version is how a stdio
+// server left running across an upgrade shows up there.
+const CLIENT = `mcp-stdio/${packageVersion()}`;
+// Source runs as mcp/server.ts, the published copy as dist/mcp/server.js.
+function packageVersion() {
+    for (const rel of ["../package.json", "../../package.json"]) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), rel), "utf8"));
+            if (pkg.name === "mockpit")
+                return String(pkg.version);
+        }
+        catch {
+            // Not at this depth.
+        }
+    }
+    return "unknown";
+}
 async function api(path, init = {}) {
-    const headers = { "content-type": "application/json" };
+    const headers = {
+        "content-type": "application/json",
+        "x-mockpit-client": CLIENT,
+    };
     if (TOKEN)
         headers.authorization = `Bearer ${TOKEN}`;
     let res;
@@ -208,18 +230,35 @@ async function run(args) {
         body: JSON.stringify({ code, session, project: resolveProject(args.project), agent: AGENT }),
     });
 }
+async function loadImage(ref) {
+    const res = await fetch(`${API}/a/${encodeURIComponent(ref.id)}`, {
+        headers: TOKEN ? { authorization: `Bearer ${TOKEN}` } : {},
+    });
+    if (!res.ok)
+        return null;
+    return {
+        data: new Uint8Array(await res.arrayBuffer()),
+        mimeType: res.headers.get("content-type") ?? "image/png",
+    };
+}
 const server = new McpServer(MCP_SERVER_INFO, {
     instructions: CODE_MODE ? RUN_INSTRUCTIONS : MCP_INSTRUCTIONS,
 });
 if (CODE_MODE) {
     const [{ name, ...config }] = STDIO_RUN_TOOLS;
-    server.registerTool(name, config, async (args) => runToolResult(await run(args)));
+    server.registerTool(name, config, async (args) => {
+        const envelope = await run(args);
+        return withFeedbackImages(runToolResult(envelope), envelope, loadImage);
+    });
 }
 else {
     for (const tool of STDIO_MCP_TOOLS) {
         const handler = handlers[tool.name];
         const { name, ...config } = tool;
-        server.registerTool(name, config, async (args) => toolResult(name, await handler(args)));
+        server.registerTool(name, config, async (args) => {
+            const value = await handler(args);
+            return withFeedbackImages(toolResult(name, value), value, loadImage);
+        });
     }
 }
 // Replaces the SDK's own listing (registered above), so stdio advertises the

package/dist/server/apiViews.d.ts

@@ -203,6 +203,15 @@ export interface StateParts {
 }
 export declare function partsByState(mock: Mock, posts: Post[]): StateParts[];
 export declare const mockSummaryView: (mock: Mock, posts: Post[]) => {
+    sessionId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    thumbnail: {
+        postId: string;
+        surface: number;
+        version: number;
+    } | null;
+    drafted?: number | undefined;
     id: string;
     project: string;
     slug: string;
@@ -212,14 +221,6 @@ export declare const mockSummaryView: (mock: Mock, posts: Post[]) => {
     stateCount: number;
     variants: number;
     open: number;
-    sessionId: string | null;
-    createdAt: string;
-    updatedAt: string;
-    thumbnail: {
-        postId: string;
-        surface: number;
-        version: number;
-    } | null;
 };
 export declare const mockDetailView: (mock: Mock, posts: Post[], opts?: VariantViewOptions & {
     tuned?: Record<string, unknown>;
@@ -326,4 +327,6 @@ export declare const sessionRowView: (session: Session, postCount: number) => {
     lastActiveAt: string;
     agentSeq: number;
     project: string | null;
+    agentActiveAt: string | null;
+    keyed: boolean;
 };

package/dist/server/apiViews.js

@@ -1,7 +1,7 @@
 // Response shapes shared by every tier (REST, both MCP transports, the CLI), so
 // one mock reads the same however an agent asks for it.
 import { mergeParts, partsInSurfaces } from "./parts.js";
-import { isSandboxedSurfaceKind, openCount, SURFACE_CONTENT_FIELDS, } from "./types.js";
+import { isSandboxedSurfaceKind, draftedCount, openCount, SURFACE_CONTENT_FIELDS, } from "./types.js";
 export const surfaceRef = (surface, index) => ({
     id: surface.id,
     kind: surface.kind,
@@ -94,21 +94,26 @@ function thumbnail(mock, posts) {
     const surface = pick.surfaces.findIndex((s) => isSandboxedSurfaceKind(s.kind));
     return { postId: pick.id, surface: Math.max(surface, 0), version: pick.version };
 }
-export const mockSummaryView = (mock, posts) => ({
-    id: mock.id,
-    project: mock.project,
-    slug: mock.slug,
-    title: mock.title,
-    kind: mock.kind,
-    states: mock.states,
-    stateCount: Math.max(mock.states.length, 1),
-    variants: posts.length,
-    open: openCount(mock, posts),
-    sessionId: mock.sessionId,
-    createdAt: mock.createdAt,
-    updatedAt: mock.updatedAt,
-    thumbnail: thumbnail(mock, posts),
-});
+export const mockSummaryView = (mock, posts) => {
+    const drafted = draftedCount(mock, posts);
+    return {
+        id: mock.id,
+        project: mock.project,
+        slug: mock.slug,
+        title: mock.title,
+        kind: mock.kind,
+        states: mock.states,
+        stateCount: Math.max(mock.states.length, 1),
+        variants: posts.length,
+        open: openCount(mock, posts),
+        // Only once the user has started one, so a list with no drafts costs nothing.
+        ...(drafted === null ? {} : { drafted }),
+        sessionId: mock.sessionId,
+        createdAt: mock.createdAt,
+        updatedAt: mock.updatedAt,
+        thumbnail: thumbnail(mock, posts),
+    };
+};
 // One mock as anyone outside the viewer's own draft sees it: the draft is the
 // user's unsent work and never leaves through this view.
 export const mockDetailView = (mock, posts, opts = {}) => ({

package/dist/server/app.d.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { type FeedEvent } from "./events.ts";
 import { type GuideTopic } from "./designGuide.ts";
 import { type Executor, type RunLimits } from "./run.ts";
+import { type LogSink } from "./eventLog.ts";
 import { type Store } from "./types.ts";
 export type { FeedEvent } from "./events.ts";
 export type { FeedbackBatch } from "./feedbackBatch.ts";
@@ -25,6 +26,7 @@ export interface AppOptions {
     maxHoldConnections?: number;
     executor?: Executor;
     runLimits?: Partial<RunLimits>;
+    log?: LogSink;
 }
 export interface LatestRelease {
     version: string;
@@ -50,4 +52,4 @@ export interface FlowContext {
     request?: Request;
     signal?: AbortSignal;
 }
-export declare function createApp({ store, viewerHtml, setupText, topics, authenticate, authToken, basePath, publicRead, screenshots, version, upgradeCommand, fetchLatestRelease, onEvent, maxHoldConnections, executor, runLimits, }: AppOptions): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export declare function createApp({ store, viewerHtml, setupText, topics, authenticate, authToken, basePath, publicRead, screenshots, version, upgradeCommand, fetchLatestRelease, onEvent, maxHoldConnections, executor, runLimits, log, }: AppOptions): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;