mockpit 1.3.0 → 3.0.0

package/dist/server/runApi.js

@@ -2,13 +2,13 @@
 // tool description, the scripts guide topic and `mockpit run --help`, so the
 // tiers cannot describe different APIs. Hand-shaped rather than generated from
 // mcpSpec: a generator repeats Surface per tool and the run-level params on
-// every function, roughly tripling the size. test/run.test.ts checks that every
-// host function named here exists and vice versa.
+// every function, roughly tripling the size. Every host function named here
+// must exist, and vice versa.
 export const RUN_API = `// The body of an async function, in plain JavaScript (no TypeScript syntax).
 // \`await mockpit.*\`, \`return\` a JSON value, print() adds an output line.
 // No network, timers, imports or process. Session, project and agent are fixed
 // for the run; pass the returned session to the next run.
-type Ref = { mock: string; state?: string; variant?: string };
+type Ref = { design: string; state?: string; variant?: string };
 type Knobs = Record<string, unknown>; // path → [default,min,max,step] | boolean | {type:"select",options} | "#hex"
 type Surface =
   | { kind: "html"; html: string; kits?: string[] }
@@ -20,35 +20,43 @@ type Surface =
   | { kind: "json"; data: unknown; title?: string }
   | { kind: "code"; code: string; language?: string; lineStart?: number };
 type Ask = {
-  id?: string; text: string; scope?: "mock" | "state" | "part"; state?: string; part?: string; multi?: boolean;
-  options: { id?: string; label: string; variant?: string; set?: Knobs }[];
+  id?: string; text: string; scope?: "design" | "state" | "part"; state?: string; part?: string; multi?: boolean;
+  options: { id?: string; label: string; variant?: string; set?: Knobs; recommended?: boolean }[];
 };
 type Written = {
-  post: { state: string | null; variant: string; version: number }; url: string;
-  parts: { state: string | null; parts: { name: string }[] }[];
+  post?: { state: string | null; variant: string; version: number }; planned?: true; url: string;
+  parts?: { state: string | null; parts: { name: string }[] }[];
   partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };
-  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged
+  nudges?: string[]; suggestedAsk?: Ask; suggestedFillAsks?: Ask[]; // send with ask when nudged
 };
 type Feedback = {
-  mock: string | null;
-  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };
-  comments: { text: string; state: string | null; variant: string | null }[];
-  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];
+  design: string | null;
+  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; comment?: string }[]; borrowed: Record<string, string>; tuned: Knobs; comments: { part: string | null; text: string }[]; verdict?: { kind: "use" | "revise"; state: string | null; variant: string; version?: number } };
+  messages: { text: string; state: string | null; variant: string | null }[];
+  inUse: { state: string | null; variant: string; version: number }[]; archived: { state: string | null; variant: string }[];
 };
-type Pending = { mock: string; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };
+type Pending = { design: string; archived?: true; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };
 declare const mockpit: {
   guide(topic?: "knobs" | "asks" | "surfaces" | "html" | "feedback" | "http" | "scripts"): Promise<string>;
-  /** No mock: every mock, the flows, plus pending. With one: its states, variants, asks, parts, knobs. */
-  read(mock?: string, opts?: { body?: boolean; history?: boolean }): Promise<unknown>;
-  /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list
+  /** Read first: decisionList is what the user already settled; it stands unless they say otherwise.
+   * No design: every design, the flows, plus pending. With one: its states, variants, asks, parts, knobs.
+   * opts.decisions: only the whole list, when a read cut it. */
+  read(design?: string, opts?: { body?: boolean; history?: boolean; decisions?: boolean }): Promise<unknown>;
+  /** Creates or versions (design, state, variant). One of: html; surfaces, the full ordered list
    * ({id} alone keeps that surface, a missing id is removed); parts {"name"|"name#key": outer html};
-   * fills {"part#fill": outer html}, replacing or adding one alternative of a slot. */
-  publish(v: Ref & { title?: string; kind?: "component" | "page"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; fills?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number; prompt?: string; note?: string; widths?: number[]; flow?: string; step?: number }): Promise<Written>;
-  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string; nudges?: string[] }>;
+   * fills {"part#fill": outer html}, replacing or adding one fill of a part.
+   * None of them, with kind screen or component: plans it, for a later publish to draw. */
+  publish(v: Ref & { title?: string; kind?: "screen" | "component" | "idea"; area?: string; source?: string; html?: string; poster?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; fills?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number; prompt?: string; description?: string; widths?: number[]; flow?: string; step?: number }): Promise<Written>;
+  ask(design: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string; nudges?: string[] }>;
   /** Never waits: what the user sent since you last heard, and what they are doing now. */
   feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;
   say(v: Ref, message: string): Promise<void>;
-  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string }[]; reply: unknown }>;
+  /** to or toState moves variants there; archive hides them; restore brings them back. */
+  move(v: Ref & { variants: string[]; to?: string; toState?: string; archive?: boolean; restore?: boolean }): Promise<{ variants: { state: string | null; variant: string; status: string }[]; skipped: { variant: string; why: string }[]; url: string }>;
+  /** No new version; "" clears. { rename } or { areaOrder } without design edits the project.
+   * notes: a short plain-text spec; not applied over the user's own edit (notes.applied says). */
+  edit(v: { design?: string; slug?: string; title?: string; kind?: string; area?: string; source?: string; firstState?: string; notes?: string; rename?: string; areaOrder?: string[] }): Promise<{ url: string; notes?: { applied: boolean; text?: string } }>;
+  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string; allFills?: string }[]; reply: unknown }>;
   /** data: base64 bytes. Use id as an image surface's assetId. */
   upload(data: string, opts: { contentType: string; filename?: string; kind?: "image" | "file" }): Promise<{ id: string; url: string }>;
 };
@@ -61,17 +69,19 @@ export const RUN_FUNCTIONS = [
     "ask",
     "feedback",
     "say",
+    "move",
+    "edit",
     "export",
     "upload",
 ];
 export const RUN_EXAMPLE = `const html = (tone) => \`<section data-part="hero" class="\${tone}"><h1>Writer</h1></section>\`;
-await mockpit.publish({ mock: "writer", variant: "calm", html: html("calm") });
-await mockpit.publish({ mock: "writer", variant: "bold", html: html("bold") });
-const { url } = await mockpit.ask("writer", [{ id: "look", text: "Which look?",
+await mockpit.publish({ design: "writer", variant: "calm", html: html("calm") });
+await mockpit.publish({ design: "writer", variant: "bold", html: html("bold") });
+const { url } = await mockpit.ask("writer", [{ id: "tone", text: "Calm or bold?",
   options: [{ label: "Calm", variant: "calm" }, { label: "Bold", variant: "bold" }] }]);
 // Tell the user where to look and end the turn; a later run reads mockpit.feedback().
 return url;`;
-export const RUN_DESCRIPTION = "Run a script against mockpit, which shows design work to the user (project > mock > state > " +
+export const RUN_DESCRIPTION = "Run a script against mockpit, which shows design work to the user (project > design > state > " +
     "variant > version). Publish variants and ask in one call; nothing waits for the user. Returns " +
     "value, prints, calls (every host call in order: which writes landed), error {kind, message, " +
     "line} and feedback (every batch received, even if the script failed). Read mockpit.guide() " +

package/dist/server/sqlStore.d.ts

@@ -1,13 +1,26 @@
-import { type Ask, type Asset, type Comment, type CommentQuery, type CommitReplyInput, type CreateAssetInput, type CreateCommentInput, type CreateMockInput, type CreatePostInput, type CreateSessionInput, type Draft, type Knobs, type Mock, type MockKind, type Post, type PostQuery, type PostStatus, type PostVersion, type Session, type Embed, type Flow, type FlowStep, type ForkRef, type SqlStorage, type Store, type Surface, type UpdateMockInput, type UpdatePostInput } from "./types.ts";
+import { type Ask, type JumpRows, type DesignKind, type Asset, type Comment, type CommentQuery, type CommitReplyInput, type CreateAssetInput, type CreateCommentInput, type CreateDesignInput, type CreatePostInput, type CreateSessionInput, type Draft, type Knobs, type Design, type DesignNotes, type AnswerAddition, type AnswerSet, type AnswerStanding, type StateOutline, type Post, type CopyRef, type LiveCopy, type PostHead, type PostQuery, type PostStatus, type PostVersion, type Session, type Embed, type Flow, type FlowStep, type ForkRef, type SqlStorage, type Store, type Surface, type UpdateDesignInput, type UpdatePostInput, type AmendPostInput, type DecisionVariant } from "./types.ts";
+import type { Mode } from "./themes.ts";
 export declare class SqlStore implements Store {
     private sql;
     private assetRefCache;
-    constructor(sql: SqlStorage);
+    private postCache;
+    private postCacheBytes;
+    private postCacheLimit;
+    private raw;
+    private holdPostDrop;
+    constructor(sql: SqlStorage, opts?: {
+        postCacheBytes?: number;
+    });
     private atomic;
     private tables;
     private columns;
     private addMissing;
+    private migrateToDesignWords;
+    private migrateAskScopeWord;
+    private renameMocksToDesigns;
     private migrate;
+    private migrateSituations;
+    private migrateToContractTerms;
     private createIndexes;
     private migrateLegacy;
     private migrateToSurfaces;
@@ -15,14 +28,15 @@ export declare class SqlStore implements Store {
     private migrateSurfaceIds;
     private migrateToItems;
     private migrateToVersions;
-    private migrateToMocks;
+    private migrateToDesigns;
+    private migrateToSketches;
     private settingSync;
     private insertVersion;
     private rowToVersion;
     private historiesFor;
     private rowsToPosts;
     private rowToSession;
-    private rowToMock;
+    private rowToDesign;
     private rowToPost;
     private rowToAsset;
     private rowToComment;
@@ -39,39 +53,60 @@ export declare class SqlStore implements Store {
     getSetting(key: string): Promise<string | null>;
     setSetting(key: string, value: string): Promise<void>;
     listProjects(): Promise<import("./types.ts").ProjectSummary[]>;
-    listMocks(project?: string): Promise<Mock[]>;
-    getMock(id: string): Promise<Mock | null>;
-    findMock(project: string, slug: string): Promise<Mock | null>;
-    createMock(input: CreateMockInput): Promise<Mock>;
-    updateMock(id: string, patch: UpdateMockInput): Promise<Mock | null>;
-    removeMock(id: string): Promise<boolean>;
+    listJumpRows(): Promise<JumpRows>;
+    listDesigns(project?: string): Promise<Design[]>;
+    getDesign(id: string): Promise<Design | null>;
+    findDesign(project: string, slug: string): Promise<Design | null>;
+    createDesign(input: CreateDesignInput): Promise<Design>;
+    updateDesign(id: string, patch: UpdateDesignInput): Promise<Design | null>;
+    removeDesign(id: string): Promise<boolean>;
+    nameFirstState(id: string, state: string): Promise<Design | null>;
+    renameDesign(id: string, slug: string): Promise<Design | null>;
+    renameProject(from: string, to: string): Promise<boolean>;
     private flowsOf;
     private writeFlow;
     listFlows(project: string): Promise<Flow[]>;
     placeFlowStep(project: string, name: string, screen: FlowStep, step: number): Promise<Flow | null>;
-    putDraft(mockId: string, draft: Draft | null): Promise<{
+    putDraft(designId: string, draft: Draft | null): Promise<{
         draft: Draft | null;
         id: string;
         project: string;
         slug: string;
         title: string;
-        kind: MockKind;
+        kind: DesignKind;
+        area: string | null;
+        source: string | null;
         states: string[];
         asks: Ask[];
         knobs: Knobs;
         widths: number[];
         sessionId: string | null;
-        resolvedAt: string | null;
+        shortlist: boolean;
+        archivedAt: string | null;
+        archiveReason: string | null;
+        notes: DesignNotes | null;
+        stateOutlines: Record<string, StateOutline>;
+        answerAdditions: AnswerAddition[];
+        standings: Record<string, AnswerStanding>;
+        sets: AnswerSet[];
         createdAt: string;
         updatedAt: string;
     } | null>;
-    private touchMock;
+    private touchDesign;
     listPosts(query?: PostQuery): Promise<Post[]>;
+    listPostHeads(project?: string): Promise<PostHead[]>;
+    listCopies(project: string): Promise<LiveCopy[]>;
+    private postsOfDesign;
+    private trimPostCache;
+    private writingPosts;
+    private cachedPost;
+    private recache;
     countPostsBySession(): Promise<Map<string, number>>;
     getPost(id: string): Promise<Post | null>;
-    findPost(mockId: string, state: string | null, variant: string): Promise<Post | null>;
+    findPost(designId: string, state: string | null, variant: string): Promise<Post | null>;
     createPost(input: CreatePostInput): Promise<Post | null>;
     updatePost(id: string, patch: UpdatePostInput): Promise<{
+        publishedBy?: string | undefined;
         author?: string | undefined;
         embeds: Embed[];
         state: string | null;
@@ -80,119 +115,107 @@ export declare class SqlStore implements Store {
         history: PostVersion[];
         from: number;
         prompt: string;
-        note?: string | undefined;
+        description?: string | undefined;
         knobs?: Knobs | undefined;
         title: string;
         surfaces: Surface[];
         id: string;
         sessionId: string;
-        mock: string;
+        design: string;
         variant: string;
         status: PostStatus;
         createdAt: string;
         forkedFrom?: ForkRef;
-        starred?: true;
+        copiedFrom?: CopyRef;
         acceptedVersion?: number;
         hiddenVersions?: number[];
+        archiveReason?: string;
+        archivedAt?: string;
+        stayedVersion?: number;
+        rewrites?: number;
     } | null>;
-    removePost(id: string): Promise<boolean>;
-    setPostStatus(id: string, status: PostStatus, acceptedVersion?: number): Promise<{
-        status: PostStatus;
-        id: string;
-        sessionId: string;
-        mock: string;
-        state: string | null;
-        variant: string;
-        title: string;
-        surfaces: Surface[];
-        createdAt: string;
-        updatedAt: string;
-        version: number;
-        history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
+    amendPost(id: string, version: number, patch: AmendPostInput): Promise<{
+        amendedAt: string;
+        rewrites: number;
+        author?: string | undefined;
+        prompt?: string | undefined;
+        from?: number | undefined;
         embeds: Embed[];
-        forkedFrom?: ForkRef;
-        starred?: true;
-        hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
-    } | {
-        status: PostStatus;
-        acceptedVersion: number;
-        id: string;
-        sessionId: string;
-        mock: string;
-        state: string | null;
-        variant: string;
+        description?: string | undefined;
+        knobs?: Knobs | undefined;
         title: string;
         surfaces: Surface[];
-        createdAt: string;
-        updatedAt: string;
-        version: number;
-        history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
-        embeds: Embed[];
-        forkedFrom?: ForkRef;
-        starred?: true;
-        hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
-    } | null>;
-    setPostStarred(id: string, starred: boolean): Promise<{
         id: string;
         sessionId: string;
-        mock: string;
+        design: string;
         state: string | null;
         variant: string;
         status: PostStatus;
-        title: string;
-        surfaces: Surface[];
         createdAt: string;
         updatedAt: string;
         version: number;
         history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
-        embeds: Embed[];
         forkedFrom?: ForkRef;
+        copiedFrom?: CopyRef;
         acceptedVersion?: number;
         hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
+        archiveReason?: string;
+        archivedAt?: string;
+        stayedVersion?: number;
+        publishedBy?: string;
+    } | null>;
+    setPosterOnce(id: string, version: number, poster: string, mode?: Mode): Promise<boolean>;
+    withdrawVersion(id: string, version: number, embeds: Embed[]): Promise<{
+        post: null;
     } | {
-        starred: true;
-        id: string;
-        sessionId: string;
-        mock: string;
-        state: string | null;
-        variant: string;
-        status: PostStatus;
-        title: string;
-        surfaces: Surface[];
-        createdAt: string;
-        updatedAt: string;
-        version: number;
-        history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
-        embeds: Embed[];
-        forkedFrom?: ForkRef;
-        acceptedVersion?: number;
-        hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
+        post: {
+            rewrites: number;
+            hiddenVersions?: number[] | undefined;
+            amendedAt?: string | undefined;
+            publishedBy?: string | undefined;
+            author?: string | undefined;
+            prompt?: string | undefined;
+            from?: number | undefined;
+            title: string;
+            surfaces: Surface[];
+            embeds: Embed[];
+            updatedAt: string;
+            version: number;
+            history: PostVersion[];
+            id: string;
+            sessionId: string;
+            design: string;
+            state: string | null;
+            variant: string;
+            status: PostStatus;
+            createdAt: string;
+            knobs?: Knobs;
+            description?: string;
+            forkedFrom?: ForkRef;
+            copiedFrom?: CopyRef;
+            acceptedVersion?: number;
+            archiveReason?: string;
+            archivedAt?: string;
+            stayedVersion?: number;
+        };
     } | null>;
+    removePost(id: string): Promise<boolean>;
+    setPostStatus(id: string, status: PostStatus, acceptedVersion?: number): Promise<Post | null>;
+    setPostArchived(id: string, archivedAt: string, reason: string | null): Promise<Post | null>;
+    setForkedFrom(id: string, from: ForkRef | null): Promise<Post | null>;
+    bumpRewrites(designId: string): Promise<void>;
     setVersionHidden(id: string, version: number, hidden: boolean): Promise<Post | null>;
+    deleteOldVersions(id: string, versions: number[]): Promise<Post | null>;
+    setPostReason(id: string, reason: string | null): Promise<Post | null>;
+    setPostStayed(id: string, version: number): Promise<Post | null>;
     listComments(query: CommentQuery): Promise<Comment[]>;
     private insertComment;
     createComment(input: CreateCommentInput): Promise<Comment | null>;
     removeComment(id: string): Promise<Comment | null>;
+    listDecisionSources(project: string): Promise<{
+        variants: DecisionVariant[];
+        decidedAt: Record<string, string>;
+    }>;
     commitReply(input: CommitReplyInput): Promise<Comment | null>;
     private referencedAssetIds;
     private addAssetRefs;