mockpit 1.3.0 → 3.0.0

package/dist/server/decisionList.js

@@ -0,0 +1,302 @@
+// The project's decision list: what the user has settled, as plain lines any
+// agent can read first, so a new session stops contradicting it. Nothing here
+// summarises and no agent has to keep it: every line is built from what replies
+// already left on the design, the answers on its questions and the variants in
+// use. Those are the current truth, so a later reply on a question replaces its
+// line by construction. Runtime-agnostic (no node imports).
+import { DEFAULT_VARIANT, optionState, } from "./types.js";
+import { standingOf } from "./standings.js";
+export function parseDecisionEdits(raw) {
+    if (!raw)
+        return {};
+    try {
+        const value = JSON.parse(raw);
+        return value && typeof value === "object" ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+// A write-in or note that hands the question back rather than settling it: the
+// agent still hears it in the reply, but "I don't get this" is no decision. Only
+// plain patterns, so it errs both ways on real replies; the user can remove what
+// slips through. "but" or "i think" rescues an unsure opening, since what follows
+// is usually the real answer ("idk what it means, but it hurt when I stopped").
+const TAKES_A_SIDE = /^((i\s+guess\s+)?(yes|no|yep|nope)\b|(i\s+)?don.?t\s+like\b)/i;
+const UNSURE = /^(idk\s+(what|if|how|why|i\s+already)\b|i\s+don.?t\s+(get|understand|know)\b|i.?m\s+(a\s+bit\s+|even\s+)?(confused|not\s+(even\s+)?sure)\b|not\s+sure\b|this\s+(one\s+)?is\s+(a\s+bit\s+)?confusing\b|so\s+i\s+don.?t\s+get\b)/i;
+const ASKS_BACK = /^(also\s+)?(what|how|why|can|could|is\s+it|do\s+we|does)\b/i;
+function handsItBack(words) {
+    const text = words.trim();
+    if (TAKES_A_SIDE.test(text))
+        return false;
+    const sentences = text.match(/[^.!?…]+[.!?…]*/g) ?? [];
+    const asking = sentences.filter((s) => s.trim().endsWith("?"));
+    if (asking.length > sentences.length / 2)
+        return true;
+    if (sentences[0]?.trim().endsWith("?") && ASKS_BACK.test(text))
+        return true;
+    return UNSURE.test(text) && !/\b(but|i\s+think)\b/i.test(text);
+}
+const answerIds = (answer) => answer === undefined ? [] : Array.isArray(answer) ? answer : [answer];
+// An older habit of writing the agent's pick into the label; the mark is the
+// option's own now, and in a decision it reads as noise.
+const cleanLabel = (label) => label.replace(/\s*\(recommended\)\s*$/i, "").trim();
+// "Yes. Not: No." says nothing the answer doesn't.
+const YES_NO = /^(yes|no|maybe|sim|não|nao|keep|drop)\b/i;
+const MAX_NOT_CHARS = 90;
+const MAX_NOT = 4;
+// As many of the options left behind as fit, then how many more: enough to stop
+// an agent proposing them again, without the line becoming the option list.
+function notList(labels) {
+    const kept = [];
+    let used = 0;
+    for (const label of labels) {
+        if (kept.length === MAX_NOT || (kept.length && used + label.length > MAX_NOT_CHARS))
+            break;
+        kept.push(label);
+        used += label.length;
+    }
+    if (!kept.length)
+        return undefined;
+    const rest = labels.length - kept.length;
+    return rest ? `${listed(kept)} and ${rest} more` : listed(kept);
+}
+// Labels often hold commas of their own ("Ring, in its own socket").
+function listed(labels) {
+    return labels.join(labels.some((l) => l.includes(",")) ? "; " : ", ");
+}
+const stop = (text) => (/[.!?…:]$/.test(text) ? text : `${text}.`);
+function joinParts(p) {
+    return [
+        p.asked,
+        p.chose ? stop(p.chose) : "",
+        p.kept ? `Kept for later: ${p.kept}.` : "",
+        p.not ? `Not: ${p.not}.` : "",
+        p.words ? `“${p.words}”` : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+function askParts(design, ask) {
+    const ids = answerIds(ask.answer);
+    const chosen = ask.options.filter((o) => ids.includes(o.id)).map((o) => cleanLabel(o.label));
+    const said = [ask.other, ask.comment]
+        .map((w) => w?.trim() ?? "")
+        .filter((w) => w && !handsItBack(w))
+        .join(" ");
+    const standing = standingOf(design, ask.id);
+    const kept = ask.options
+        .filter((o) => standing.kept.includes(o.id) && !ids.includes(o.id))
+        .map((o) => cleanLabel(o.label));
+    // A reason is taste a new session should know before it offers the same again.
+    const why = standing.hidden.filter((h) => h.why);
+    if (!chosen.length && !said && !why.length)
+        return null;
+    const question = ask.text.trim();
+    // "Keep this idea?" repeated per state means nothing without the state.
+    const state = ask.state && design.states.includes(ask.state) ? ask.state : null;
+    const where = state && !question.toLowerCase().includes(state.toLowerCase()) ? `${state}: ` : "";
+    const reasoned = why.map((h) => `${cleanLabel(h.label)} (${h.why})`);
+    const left = ask.options
+        .filter((o) => !ids.includes(o.id) && !standing.kept.includes(o.id))
+        .filter((o) => !why.some((h) => h.id === o.id))
+        .map((o) => cleanLabel(o.label));
+    const not = (chosen.length || reasoned.length) &&
+        !ask.other &&
+        ![...chosen, ...left].some((l) => YES_NO.test(l))
+        ? notList([...reasoned, ...(chosen.length ? left : [])])
+        : undefined;
+    return {
+        asked: `${where}${/[?:.]$/.test(question) ? question : `${question}:`}`,
+        ...(chosen.length ? { chose: listed(chosen) } : {}),
+        ...(kept.length ? { kept: listed(kept) } : {}),
+        ...(not ? { not } : {}),
+        ...(said ? { words: said } : {}),
+    };
+}
+// The variants a question's answer put in use, by the states it settled.
+function pickedVariants(design, ask) {
+    if (ask.scope === "part")
+        return [];
+    const ids = answerIds(ask.answer);
+    return ask.options
+        .filter((o) => ids.includes(o.id) && o.variant)
+        .flatMap((o) => (o.version !== undefined
+        ? [optionState(ask, design)]
+        : ask.scope === "state"
+            ? [ask.state ?? null]
+            : design.states.length
+                ? design.states
+                : [null]).map((state) => ({ state, variant: o.variant })));
+}
+function useParts(v, siblings) {
+    const version = v.version > 1 ? `v${v.acceptedVersion ?? v.version}` : "";
+    const named = v.variant === DEFAULT_VARIANT ? "" : v.variant;
+    const not = notList(siblings.filter((s) => s.status === "archived").map((s) => s.variant));
+    return {
+        asked: v.state ? `${v.state}, in use:` : "In use:",
+        chose: [named, version].filter(Boolean).join(" ") || "this design",
+        ...(not ? { not } : {}),
+    };
+}
+const sameQuestion = (ask) => `${ask.state ?? ""}\n${ask.text.trim().toLowerCase()}`;
+// The questions that still stand: an answered one, once per wording (the agent
+// may have re-asked it under a new id, and the later answer is the decision),
+// whose picked variant, if it picked one, was not replaced since. Ask order is
+// the order the agent asked in.
+function standingAsks(design, variants) {
+    const seen = new Set();
+    const out = [];
+    for (const ask of [...design.asks].reverse()) {
+        if (ask.dismissed)
+            continue;
+        const reasons = standingOf(design, ask.id).hidden.some((h) => h.why);
+        if (ask.answer === undefined && !ask.other && !ask.comment && !reasons)
+            continue;
+        const wording = sameQuestion(ask);
+        if (seen.has(wording))
+            continue;
+        seen.add(wording);
+        const picks = pickedVariants(design, ask);
+        const named = picks.filter((p) => variants.some((v) => v.state === p.state && v.variant === p.variant));
+        const replaced = named.length > 0 &&
+            !named.some((p) => variants.some((v) => v.state === p.state && v.variant === p.variant && v.status === "accepted"));
+        if (!replaced)
+            out.unshift(ask);
+    }
+    return out;
+}
+// Kept and hidden answers change the line, so they're part of what an edit was made on.
+// Absent when there are none, so edits made before standings existed still apply.
+function standingBasis(design, ask) {
+    const s = standingOf(design, ask.id);
+    if (!s.kept.length && !s.hidden.length)
+        return [];
+    return [JSON.stringify([s.kept, s.hidden.map((h) => [h.id, h.why ?? ""])])];
+}
+// Every line the project's replies add up to, as derived: newest decided design
+// first, an archived design after every live one, each design's lines as it asked them
+// with what it put in use first.
+export function deriveDecisionLines(designs, sources) {
+    const byDesign = new Map();
+    for (const v of sources.variants) {
+        const list = byDesign.get(v.designId);
+        if (list)
+            list.push(v);
+        else
+            byDesign.set(v.designId, [v]);
+    }
+    const order = [...designs].sort((a, b) => Number(!!a.archivedAt) - Number(!!b.archivedAt) ||
+        (sources.decidedAt[b.id] ?? "").localeCompare(sources.decidedAt[a.id] ?? ""));
+    const out = [];
+    for (const design of order) {
+        const variants = byDesign.get(design.id) ?? [];
+        const base = {
+            design: design.slug,
+            title: design.title,
+            ...(design.archivedAt ? { closed: true } : {}),
+            ...(sources.decidedAt[design.id] ? { at: sources.decidedAt[design.id] } : {}),
+        };
+        const asks = standingAsks(design, variants);
+        const answered = new Set(asks.flatMap((a) => pickedVariants(design, a).map((p) => `${p.state}\n${p.variant}`)));
+        for (const v of variants) {
+            // The question that put it in use already says so, in better words.
+            if (v.status !== "accepted" || answered.has(`${v.state}\n${v.variant}`))
+                continue;
+            const parts = useParts(v, variants.filter((s) => s.state === v.state && s.variant !== v.variant));
+            out.push({
+                ...base,
+                id: `use:${design.id}:${v.state ?? ""}:${v.variant}`,
+                ...(v.state ? { state: v.state } : {}),
+                text: joinParts(parts),
+                parts,
+                basis: `${v.variant}@${v.acceptedVersion ?? v.version}`,
+            });
+        }
+        for (const ask of asks) {
+            const parts = askParts(design, ask);
+            if (!parts)
+                continue;
+            out.push({
+                ...base,
+                id: `ask:${design.id}:${ask.id}`,
+                ...(ask.state && design.states.includes(ask.state) ? { state: ask.state } : {}),
+                text: joinParts(parts),
+                parts,
+                basis: JSON.stringify([
+                    ask.answer ?? null,
+                    ask.other ?? null,
+                    ask.comment ?? null,
+                    ...standingBasis(design, ask),
+                ]),
+            });
+        }
+    }
+    return out;
+}
+// The hand edits laid over the derived lines. An edit made on an older answer
+// no longer applies: the user has decided again since.
+export function applyDecisionEdits(lines, edits) {
+    const out = [];
+    for (const { basis, ...line } of lines) {
+        const edit = edits[line.id];
+        if (!edit || edit.basis !== basis) {
+            out.push(line);
+        }
+        else if (!edit.removed) {
+            const { parts: _, ...rest } = line;
+            out.push({ ...rest, text: edit.text ?? line.text, edited: true });
+        }
+    }
+    return out;
+}
+// A read must stay cheap to hold in a prompt, and an agent reads often, so it
+// gets the design it asked about and then the newest lines up to a budget, each
+// clipped. A long line is a long write-in, and the rest of it is one call away.
+const AGENT_LINE_CHARS = 280;
+const AGENT_LIST_CHARS = 6000;
+export function agentDecisionList(lines, here) {
+    const ordered = here
+        ? [...lines.filter((l) => l.design === here), ...lines.filter((l) => l.design !== here)]
+        : lines;
+    const kept = [];
+    let used = 0;
+    let clipped = false;
+    for (const l of ordered) {
+        const long = l.text.length > AGENT_LINE_CHARS;
+        const text = long ? `${l.text.slice(0, AGENT_LINE_CHARS - 1)}…` : l.text;
+        used += text.length + l.design.length;
+        if (used > AGENT_LIST_CHARS && kept.length)
+            break;
+        clipped ||= long;
+        kept.push({
+            design: l.design,
+            text,
+            ...(l.design === here ? { here: true } : {}),
+            ...(l.edited ? { edited: true } : {}),
+            ...(l.archived ? { archived: true } : {}),
+        });
+    }
+    const left = lines.length - kept.length;
+    const cut = [left ? `${left} older lines left out` : "", clipped ? "long lines clipped" : ""]
+        .filter(Boolean)
+        .join(", ");
+    return {
+        total: lines.length,
+        lines: kept,
+        ...(cut ? { more: `${cut}; read with decisions for all of it` } : {}),
+    };
+}
+// The list as an agent asked for it whole: nothing cut, without what only the
+// viewer's layout needs.
+export function fullAgentDecisionList(lines) {
+    return {
+        total: lines.length,
+        lines: lines.map((l) => ({
+            design: l.design,
+            text: l.text,
+            ...(l.edited ? { edited: true } : {}),
+            ...(l.archived ? { archived: true } : {}),
+        })),
+    };
+}

package/dist/server/decisions.d.ts

@@ -1,23 +1,23 @@
 import { type SlotInfo } from "./fills.ts";
-import { type KnobValue, type Mock, type Post, type Reply } from "./types.ts";
-export interface SlotDecision {
+import { type KnobValue, type Design, type Post, type Reply } from "./types.ts";
+export interface FillDecision {
     fill: string;
     label?: string;
-    from?: string;
-    slots?: Record<string, SlotDecision>;
+    borrowedFrom?: string;
+    parts?: Record<string, FillDecision>;
 }
 export interface StateDecision {
     variant: string;
-    slots: Record<string, SlotDecision>;
+    parts: Record<string, FillDecision>;
 }
 export interface Decisions {
     states: Record<string, StateDecision>;
     knobs: Record<string, KnobValue>;
 }
-export declare function replyValues(reply: Pick<Reply, "answers" | "tuned">, mock: Pick<Mock, "asks">): Record<string, KnobValue>;
-export declare function settledValues(replies: Pick<Reply, "answers" | "tuned">[], mock: Pick<Mock, "asks" | "knobs">, posts: (Pick<Post, "knobs"> & {
+export declare function replyValues(reply: Pick<Reply, "answers" | "tuned">, design: Pick<Design, "asks">): Record<string, KnobValue>;
+export declare function settledValues(replies: Pick<Reply, "answers" | "tuned">[], design: Pick<Design, "asks" | "knobs">, posts: (Pick<Post, "knobs"> & {
     surfaces?: Post["surfaces"];
 })[]): Record<string, KnobValue>;
 export declare function chosenFills(slots: SlotInfo[], values: Record<string, KnobValue>): Record<string, string>;
 export declare function postForState(posts: Post[], state: string | null): Post | undefined;
-export declare function decisionsFor(mock: Mock, posts: Post[], reply: Pick<Reply, "answers" | "tuned" | "mix">): Decisions | null;
+export declare function decisionsFor(design: Design, posts: Post[], reply: Pick<Reply, "answers" | "tuned" | "borrowed">): Decisions | null;

package/dist/server/decisions.js

@@ -1,6 +1,7 @@
-// What a reply decided, as the screen is built: per state, the look and each
-// slot's chosen fill, with the slots inside a fill listed under it only when
-// that fill was chosen; plus every other knob value the reply set. The agent
+// What a reply decided, as the state is built: per state, the variant and the
+// chosen fill of each part with fills, with the parts inside a fill listed
+// under it only when that fill was chosen; plus every other knob value the
+// reply set. The agent
 // reads "entry → skeleton → rows → shimmer" instead of reassembling it from
 // option ids, and `export` composes the same choice into one screen.
 // Runtime-agnostic (no node imports).
@@ -9,9 +10,9 @@ import { checkKnobValue, knobFor } from "./knobs.js";
 import { inUseVersion, postAtVersion, } from "./types.js";
 // The knob values a reply carries: each chosen option's `set`, then tuning,
 // which wins, as in the viewer's resolveKnobs.
-export function replyValues(reply, mock) {
+export function replyValues(reply, design) {
     const out = {};
-    for (const ask of mock.asks) {
+    for (const ask of design.asks) {
         const answer = reply.answers[ask.id];
         const ids = answer === undefined ? [] : Array.isArray(answer) ? answer : [answer];
         for (const id of ids)
@@ -22,13 +23,13 @@ export function replyValues(reply, mock) {
 // Every value the user has sent, oldest reply first so a later answer or tune
 // replaces an earlier one. Values the knobs declared now can't hold drop out:
 // the agent may have renamed or narrowed a knob since.
-export function settledValues(replies, mock, posts) {
+export function settledValues(replies, design, posts) {
     const all = {};
     for (const r of replies)
-        Object.assign(all, replyValues(r, mock));
+        Object.assign(all, replyValues(r, design));
     const out = {};
     for (const [path, value] of Object.entries(all)) {
-        const config = knobFor(path, mock, posts);
+        const config = knobFor(path, design, posts);
         const checked = config === undefined ? null : checkKnobValue(path, config, value);
         if (checked?.ok)
             out[path] = checked.value;
@@ -54,7 +55,7 @@ export function postForState(posts, state) {
         inState[0];
     return post && (postAtVersion(post, inUseVersion(post)) ?? post);
 }
-function tree(slots, chosen, parent, mix) {
+function tree(slots, chosen, parent, borrowed) {
     const out = {};
     for (const s of slots) {
         const same = parent
@@ -64,23 +65,23 @@ function tree(slots, chosen, parent, mix) {
             continue;
         const fill = chosen[s.part];
         const label = s.fills.find((f) => f.name === fill)?.label;
-        const inner = tree(slots, chosen, { part: s.part, fill }, mix);
+        const inner = tree(slots, chosen, { part: s.part, fill }, borrowed);
         out[s.part] = {
             fill,
             ...(label ? { label } : {}),
-            ...(mix[s.part] ? { from: mix[s.part] } : {}),
-            ...(Object.keys(inner).length ? { slots: inner } : {}),
+            ...(borrowed[s.part] ? { borrowedFrom: borrowed[s.part] } : {}),
+            ...(Object.keys(inner).length ? { parts: inner } : {}),
         };
     }
     return out;
 }
-// Null when the mock has no slots and the reply set no knobs: then the
+// Null when the design has no fills and the reply set no knobs: then the
 // answered asks already say everything.
-export function decisionsFor(mock, posts, reply) {
-    const values = replyValues(reply, mock);
+export function decisionsFor(design, posts, reply) {
+    const values = replyValues(reply, design);
     const states = {};
     const slotPaths = new Set();
-    for (const state of mock.states.length ? mock.states : [null]) {
+    for (const state of design.states.length ? design.states : [null]) {
         const post = postForState(posts, state);
         if (!post)
             continue;
@@ -89,7 +90,7 @@ export function decisionsFor(mock, posts, reply) {
             slotPaths.add(s.part);
         states[state ?? ""] = {
             variant: post.variant,
-            slots: tree(slots, chosenFills(slots, values), null, reply.mix ?? {}),
+            parts: tree(slots, chosenFills(slots, values), null, reply.borrowed ?? {}),
         };
     }
     const knobs = Object.fromEntries(Object.entries(values).filter(([p]) => !slotPaths.has(p)));

package/dist/server/designGuide.d.ts

@@ -1,16 +1,20 @@
-import type { DesignSettings } from "./types.ts";
+import type { DesignSystem } from "./types.ts";
 export declare const GUIDE_TOPICS: readonly ["knobs", "asks", "surfaces", "html", "feedback", "http", "scripts"];
 export type GuideTopic = (typeof GUIDE_TOPICS)[number];
 export declare const isGuideTopic: (id: unknown) => id is GuideTopic;
 export declare const unknownTopicMessage: (topic: string) => string;
-export declare function iconsLine(design: DesignSettings | null): string;
+export declare function iconsLine(designSystem: DesignSystem | null): string;
 /**
  * What the repo's DESIGN.md, DTCG tokens and shadcn components.json say, as
  * init stored them. Empty when the repo has none.
  */
-export declare function designFilesSection(design: DesignSettings | null): string;
+export declare function designFilesSection(designSystem: DesignSystem | null): string;
 /**
- * The project-aware brief. `design` is the stored `design:<project>` settings,
- * or null for a project that never ran `mockpit init`.
+ * The project-aware brief. `designSystem` is the stored `design:<project>` settings,
+ * or null for a project that never ran `mockpit init`; `guidance` is the
+ * layers above core (server/guidance.ts), absent when none is on.
  */
-export declare function renderBriefGuide(design: DesignSettings | null): string;
+export declare function renderBriefGuide(designSystem: DesignSystem | null, guidance?: {
+    line: string;
+    body: string;
+}): string;