@joewinke/jatui 0.37.0 → 0.38.0

package/dist/artifact-blocks/contractBlocks.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The jat provider contract's block-level surface (jat
+ * docs/artifacts/provider-contract.md), read into the renderer's own blocks.
+ *
+ *   - P10 `decision` block: the contract's decision card
+ *     `{ question, options: [string | { letter?, label, detail? }],
+ *     recommended?, context? }`. The renderer stores it as its NATIVE decision
+ *     callout (variant `decision`, one option per letter, the context as the
+ *     body), so every surface that already reads decision callouts — the
+ *     page, the desk, the dock, the census, the Finish review panel — serves
+ *     a contract card with no second renderer. The translation runs at
+ *     publish; the stored spec is the callout.
+ *   - P11 per-block task links (mos-4tgfj): a block may carry its OWN jat
+ *     `taskId`, and a decision block that also carries one may name the
+ *     jat-decision it mirrors (`decisionId`). A finished review answers each
+ *     linked block on that block's task (feedbackReview.ts → F13).
+ *
+ * Pure and isomorphic: the service and the MCP publish tool both call it.
+ */
+import { z } from "zod";
+import type { BlockInstance, BlocksSpec, BlockValidationError } from "./types";
+/**
+ * P11: a block `taskId` matches the P6 shape, and a `decisionId` only rides
+ * a decision block that also carries a `taskId`. Anything else is an error
+ * (the publish answers 422 and stores nothing).
+ */
+export declare function blockLinkErrors(b: BlockInstance): BlockValidationError[];
+/** A linked block's task (and mirrored decision), keyed by block id. */
+interface BlockTaskLink {
+    taskId: string;
+    decisionId: string | null;
+}
+/**
+ * F13: block id → its own linked task, for the blocks of a STORED spec that
+ * carry a valid one (untrusted jsonb: anything malformed is skipped, never
+ * answered).
+ */
+export declare function blockTasksOf(spec: unknown): Map<string, BlockTaskLink>;
+export declare const decisionMetaSchema: z.ZodArray<z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodString;
+    href: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+        success: "success";
+        neutral: "neutral";
+    }>>;
+}, z.core.$strip>>;
+/** Sections' markdown shares the callout body's 20,000-character budget. */
+export declare const DECISION_BODY_BUDGET = 20000;
+export declare const decisionSectionsSchema: z.ZodArray<z.ZodObject<{
+    heading: z.ZodString;
+    markdown: z.ZodString;
+    open: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+export declare const decisionPrimaryActionSchema: z.ZodObject<{
+    label: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+export declare const blockGroupSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    quiet: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const decisionTitleSchema: z.ZodString;
+/**
+ * The optional NEEDS YOU fields of one card, each validated alone: a
+ * well-formed field passes through (parsed, so trims apply), a malformed
+ * one is DROPPED and named in `warnings` — never a refused publish
+ * (PARAMS-SPEC §1 "drop (not refuse)").
+ */
+export declare function decisionExtras(params: Record<string, unknown>): {
+    extras: Record<string, unknown>;
+    warnings: Array<[string, string]>;
+};
+/**
+ * Read a publish's spec through the contract: every `decision` block becomes
+ * a decision callout (its id, owner, taskId and decisionId kept), and the
+ * malformed ones come back as errors. A malformed OPTIONAL card field
+ * (title, meta, sections, primaryAction, group) is dropped and comes back
+ * as a warning — the publish still succeeds. Blocks of every other type
+ * pass through untouched, so this is idempotent on an already-native spec.
+ */
+export declare function normalizeContractBlocks(spec: BlocksSpec): {
+    spec: BlocksSpec;
+    errors: BlockValidationError[];
+    warnings: BlockValidationError[];
+};
+export {};

package/dist/artifact-blocks/contractBlocks.js

@@ -0,0 +1,279 @@
+/**
+ * The jat provider contract's block-level surface (jat
+ * docs/artifacts/provider-contract.md), read into the renderer's own blocks.
+ *
+ *   - P10 `decision` block: the contract's decision card
+ *     `{ question, options: [string | { letter?, label, detail? }],
+ *     recommended?, context? }`. The renderer stores it as its NATIVE decision
+ *     callout (variant `decision`, one option per letter, the context as the
+ *     body), so every surface that already reads decision callouts — the
+ *     page, the desk, the dock, the census, the Finish review panel — serves
+ *     a contract card with no second renderer. The translation runs at
+ *     publish; the stored spec is the callout.
+ *   - P11 per-block task links (mos-4tgfj): a block may carry its OWN jat
+ *     `taskId`, and a decision block that also carries one may name the
+ *     jat-decision it mirrors (`decisionId`). A finished review answers each
+ *     linked block on that block's task (feedbackReview.ts → F13).
+ *
+ * Pure and isomorphic: the service and the MCP publish tool both call it.
+ */
+import { z } from "zod";
+import { linkUrlSchema } from "./params";
+/** Contract P6 shape: project key, dash, base-36 id, optional `.N` children. */
+const BLOCK_TASK_ID_RE = /^[a-z0-9][a-z0-9_-]*-[a-z0-9]+(\.[0-9]+)*$/;
+const MAX_BLOCK_TASK_ID = 64;
+/** Contract P11: a jat-decision id. */
+const DECISION_ID_RE = /^dec-[A-Za-z0-9_-]{1,64}$/;
+const LETTER_RE = /^[A-Z]$/;
+const MAX_OPTIONS = 26;
+const MAX_LABEL = 120;
+const MAX_DETAIL = 300;
+const MAX_QUESTION = 500;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Is this block a decision card (the contract type, or the native callout)? */
+function isDecisionInstance(b) {
+    return (b.type === "decision" ||
+        (b.type === "callout" && isObj(b.params) && b.params.variant === "decision"));
+}
+/**
+ * P11: a block `taskId` matches the P6 shape, and a `decisionId` only rides
+ * a decision block that also carries a `taskId`. Anything else is an error
+ * (the publish answers 422 and stores nothing).
+ */
+export function blockLinkErrors(b) {
+    const errors = [];
+    const at = (path, message) => errors.push({ blockId: String(b.id), type: b.type, path, message });
+    if (b.taskId !== undefined) {
+        if (typeof b.taskId !== "string" ||
+            b.taskId.length > MAX_BLOCK_TASK_ID ||
+            !BLOCK_TASK_ID_RE.test(b.taskId))
+            at("taskId", "taskId must be a jat task id (e.g. mos-9unv1, jat-abc.3)");
+    }
+    if (b.decisionId !== undefined) {
+        if (!isDecisionInstance(b))
+            at("decisionId", "decisionId belongs on a decision block");
+        else if (typeof b.taskId !== "string")
+            at("decisionId", "decisionId needs the block's own taskId");
+        else if (typeof b.decisionId !== "string" ||
+            !DECISION_ID_RE.test(b.decisionId))
+            at("decisionId", "decisionId must look like dec-<id>");
+    }
+    return errors;
+}
+/**
+ * F13: block id → its own linked task, for the blocks of a STORED spec that
+ * carry a valid one (untrusted jsonb: anything malformed is skipped, never
+ * answered).
+ */
+export function blockTasksOf(spec) {
+    const out = new Map();
+    const blocks = isObj(spec) && Array.isArray(spec.blocks) ? spec.blocks : [];
+    for (const b of blocks) {
+        if (!isObj(b) || typeof b.id !== "string")
+            continue;
+        if (typeof b.taskId !== "string" ||
+            b.taskId.length > MAX_BLOCK_TASK_ID ||
+            !BLOCK_TASK_ID_RE.test(b.taskId))
+            continue;
+        const decisionId = typeof b.decisionId === "string" &&
+            DECISION_ID_RE.test(b.decisionId) &&
+            isDecisionInstance({ type: String(b.type), params: b.params })
+            ? b.decisionId
+            : null;
+        out.set(b.id, { taskId: b.taskId, decisionId });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// The NEEDS YOU card fields (PARAMS-SPEC §1, jat-j49id → jatui-vsuzi)
+// ---------------------------------------------------------------------------
+//
+// Additive and optional: a decision card may carry a topic `title`, a
+// compact `meta` row, collapsed markdown `sections`, a `primaryAction`
+// link button and the `group` it belongs to. None of them is answerable —
+// links navigate, they never post a verdict. Exported so the callout block
+// validates its params with the SAME limits the normalizer enforces.
+const META_TONES = ["neutral", "info", "success", "warning", "error"];
+export const decisionMetaSchema = z
+    .array(z.object({
+    label: z.string().trim().min(1).max(24),
+    value: z.string().trim().min(1).max(80),
+    href: linkUrlSchema.optional(),
+    title: z.string().max(120).optional(),
+    tone: z.enum(META_TONES).optional(),
+}))
+    .max(8);
+/** Sections' markdown shares the callout body's 20,000-character budget. */
+export const DECISION_BODY_BUDGET = 20_000;
+export const decisionSectionsSchema = z
+    .array(z.object({
+    heading: z.string().trim().min(1).max(60),
+    markdown: z.string().max(DECISION_BODY_BUDGET),
+    open: z.boolean().optional(),
+}))
+    .max(8)
+    .refine((list) => list.reduce((n, s) => n + s.markdown.length, 0) <= DECISION_BODY_BUDGET, `sections share a ${DECISION_BODY_BUDGET}-character budget`);
+export const decisionPrimaryActionSchema = z.object({
+    label: z.string().trim().min(1).max(60),
+    url: linkUrlSchema,
+});
+export const blockGroupSchema = z.object({
+    key: z.string().regex(/^[a-z0-9-]{1,32}$/, "group key must be [a-z0-9-]{1,32}"),
+    label: z.string().trim().min(1).max(60),
+    quiet: z.boolean().optional(),
+});
+export const decisionTitleSchema = z.string().trim().min(1).max(120);
+const DECISION_EXTRAS = {
+    title: decisionTitleSchema,
+    meta: decisionMetaSchema,
+    sections: decisionSectionsSchema,
+    primaryAction: decisionPrimaryActionSchema,
+    group: blockGroupSchema,
+};
+/**
+ * The optional NEEDS YOU fields of one card, each validated alone: a
+ * well-formed field passes through (parsed, so trims apply), a malformed
+ * one is DROPPED and named in `warnings` — never a refused publish
+ * (PARAMS-SPEC §1 "drop (not refuse)").
+ */
+export function decisionExtras(params) {
+    const extras = {};
+    const warnings = [];
+    for (const [key, schema] of Object.entries(DECISION_EXTRAS)) {
+        if (params[key] === undefined)
+            continue;
+        const r = schema.safeParse(params[key]);
+        if (r.success)
+            extras[key] = r.data;
+        else {
+            const issue = r.error.issues[0];
+            const at = issue?.path.length ? `.${issue.path.join(".")}` : "";
+            warnings.push([
+                `${key}${at}`,
+                `dropped: ${issue?.message ?? "malformed"}`,
+            ]);
+        }
+    }
+    return { extras, warnings };
+}
+/**
+ * One contract decision card → the decision callout params, or the list of
+ * reasons it is not a card (P10). Letters default to A, B, C… by position;
+ * each becomes the callout option id (lower-cased), so a saved pick maps back
+ * to its letter.
+ */
+function decisionToCallout(params) {
+    const errors = [];
+    if (!isObj(params))
+        return { ok: false, errors: [["", "params must be an object"]] };
+    const q = typeof params.question === "string"
+        ? params.question.trim()
+        : typeof params.title === "string"
+            ? params.title.trim()
+            : "";
+    if (!q)
+        errors.push(["question", "a decision needs a question"]);
+    else if (q.length > MAX_QUESTION)
+        errors.push([
+            "question",
+            `question must be ${MAX_QUESTION} characters or fewer`,
+        ]);
+    const raw = Array.isArray(params.options) ? params.options : null;
+    if (!raw || raw.length < 2 || raw.length > MAX_OPTIONS)
+        errors.push(["options", `a decision needs 2-${MAX_OPTIONS} options`]);
+    const options = [];
+    const seen = new Set();
+    for (const [i, o] of (raw ?? []).entries()) {
+        const label = typeof o === "string"
+            ? o.trim()
+            : isObj(o) && typeof o.label === "string"
+                ? o.label.trim()
+                : "";
+        const letter = isObj(o) && o.letter !== undefined
+            ? o.letter
+            : String.fromCharCode(65 + i);
+        const detail = isObj(o) && typeof o.detail === "string" ? o.detail.trim() : "";
+        if (!label)
+            errors.push([`options.${i}`, "an option needs a label"]);
+        else if (label.length > MAX_LABEL)
+            errors.push([
+                `options.${i}.label`,
+                `label must be ${MAX_LABEL} characters or fewer`,
+            ]);
+        if (typeof letter !== "string" || !LETTER_RE.test(letter))
+            errors.push([`options.${i}.letter`, "letter must be one capital A-Z"]);
+        else if (seen.has(letter))
+            errors.push([`options.${i}.letter`, `letter ${letter} is used twice`]);
+        else
+            seen.add(letter);
+        if (detail.length > MAX_DETAIL)
+            errors.push([
+                `options.${i}.detail`,
+                `detail must be ${MAX_DETAIL} characters or fewer`,
+            ]);
+        if (typeof letter === "string" && LETTER_RE.test(letter))
+            options.push({
+                id: letter.toLowerCase(),
+                letter,
+                label,
+                ...(detail ? { detail } : {}),
+            });
+    }
+    if (params.recommended !== undefined && !seen.has(String(params.recommended)))
+        errors.push([
+            "recommended",
+            "recommended must be one of the card's letters",
+        ]);
+    if (params.context !== undefined && typeof params.context !== "string")
+        errors.push(["context", "context must be markdown text"]);
+    if (errors.length)
+        return { ok: false, errors };
+    const { extras, warnings } = decisionExtras(params);
+    return {
+        ok: true,
+        warnings,
+        params: {
+            // The topic `title` (the card's `question` stays the ask itself).
+            ...extras,
+            variant: "decision",
+            question: q,
+            options,
+            ...(typeof params.recommended === "string"
+                ? { recommended: params.recommended }
+                : {}),
+            ...(typeof params.context === "string" && params.context.trim()
+                ? { body: params.context }
+                : {}),
+        },
+    };
+}
+/**
+ * Read a publish's spec through the contract: every `decision` block becomes
+ * a decision callout (its id, owner, taskId and decisionId kept), and the
+ * malformed ones come back as errors. A malformed OPTIONAL card field
+ * (title, meta, sections, primaryAction, group) is dropped and comes back
+ * as a warning — the publish still succeeds. Blocks of every other type
+ * pass through untouched, so this is idempotent on an already-native spec.
+ */
+export function normalizeContractBlocks(spec) {
+    const errors = [];
+    const warnings = [];
+    if (!Array.isArray(spec?.blocks))
+        return { spec, errors, warnings };
+    let changed = false;
+    const blocks = spec.blocks.map((b) => {
+        if (!isObj(b) || b.type !== "decision")
+            return b;
+        const r = decisionToCallout(b.params);
+        if (!r.ok) {
+            for (const [path, message] of r.errors)
+                errors.push({ blockId: String(b.id), type: "decision", path, message });
+            return b;
+        }
+        for (const [path, message] of r.warnings)
+            warnings.push({ blockId: String(b.id), type: "decision", path, message });
+        changed = true;
+        return { ...b, type: "callout", params: r.params };
+    });
+    return { spec: changed ? { ...spec, blocks } : spec, errors, warnings };
+}

package/dist/artifact-blocks/history.d.ts

@@ -0,0 +1,140 @@
+/**
+ * History scrubber model (mos-p9m3g, living artifacts phase 4).
+ *
+ * "What did this page look like yesterday at 9am?" A blocks page has two
+ * clocks, and the state at any instant is one reading of each:
+ *
+ *   LAYOUT  the artifact_versions row live at that instant (the highest
+ *           version created at or before it);
+ *   DATA    the artifact_data_history snapshot live at that instant (the
+ *           newest recorded at or before it — migration 20272490000210
+ *           captures every change of artifacts.data by trigger).
+ *
+ * This module is PURE (no db, no fetch): the history route resolves an
+ * instant with it on the server, and HistoryScrubber builds its timeline and
+ * diffs with it in the browser.
+ *
+ * Diffs are SHAPE-AWARE but never shape-dependent: a stats-shaped value
+ * (`cards[]` with label + numeric value) diffs as KPI deltas, a table-shaped
+ * value (`rows[]`) diffs as added / removed / changed rows, and anything
+ * else diffs as its changed numeric and text leaves. Data is untrusted: every
+ * reader here tolerates any JSON and caps what it reports.
+ */
+/** Mirrors the trigger's prune rule in drizzle/20272490000210 — keep both in
+ * step. The scrubber names where the trail ends with these. */
+export declare const HISTORY_RETENTION: {
+    readonly maxSnapshots: 500;
+    readonly maxAgeDays: 30;
+    readonly maxBytes: number;
+};
+/** A layout version, as the history route lists it. */
+export interface HistoryVersion {
+    version: number;
+    /** ISO timestamp. */
+    createdAt: string;
+    kind: "html" | "blocks";
+    changeNote: string | null;
+}
+/** A data snapshot, as the history route lists it (no payload). */
+export interface HistorySnapshot {
+    id: string;
+    /** ISO timestamp — when artifacts.data BECAME this value. */
+    at: string;
+    bytes: number;
+    /** The layout version live when the data changed (context only). */
+    version: number | null;
+}
+/** One stop on the scrubber: a layout publish or a data change. */
+export interface TimelinePoint {
+    kind: "version" | "data";
+    /** ISO timestamp. */
+    at: string;
+    /** Epoch ms of `at` (sort key). */
+    ms: number;
+    version?: number;
+    snapshotId?: string;
+}
+/** What the page showed at one instant: which layout + which data. */
+export interface PageStateRef {
+    /** Null before the first version (cannot happen for a real artifact). */
+    version: number | null;
+    /** Null when no snapshot exists at or before the instant. */
+    snapshotId: string | null;
+    /** When that snapshot's data took effect. */
+    dataAt: string | null;
+}
+/**
+ * Merge versions and snapshots into one chronological list (oldest first).
+ * Entries with an unparseable timestamp are dropped — a point the scrubber
+ * cannot place is a point it cannot honestly show. At equal instants a
+ * version sorts before a data change (a republish then a data push in the
+ * same second reads in that order).
+ */
+export declare function buildTimeline(versions: readonly HistoryVersion[], snapshots: readonly HistorySnapshot[]): TimelinePoint[];
+/**
+ * The page state live at `atMs`: the newest version created at or before it
+ * and the newest snapshot recorded at or before it. Before the first
+ * snapshot, snapshotId is null — the page showed its inline params (or the
+ * trail was pruned; the caller says which via `trailStart`).
+ */
+export declare function stateAt(versions: readonly HistoryVersion[], snapshots: readonly HistorySnapshot[], atMs: number): PageStateRef;
+/** The oldest instant the trail can answer for, or null with no snapshots. */
+export declare function trailStart(snapshots: readonly HistorySnapshot[]): string | null;
+export interface KpiDelta {
+    label: string;
+    then: number | null;
+    now: number | null;
+    /** now - then; null when either side is missing. */
+    delta: number | null;
+    /** delta / |then| (0.042 = +4.2%); null when then is 0 or missing. */
+    pct: number | null;
+}
+export interface RowChange {
+    key: string;
+    /** Columns whose cell differs (changed rows only). */
+    fields: string[];
+}
+export interface LeafChange {
+    path: string;
+    then: string | number | boolean | null | undefined;
+    now: string | number | boolean | null | undefined;
+    delta: number | null;
+}
+export type KeyDiff = {
+    key: string;
+    status: "added" | "removed" | "same";
+} | {
+    key: string;
+    status: "changed";
+    shape: "kpi";
+    kpis: KpiDelta[];
+} | {
+    key: string;
+    status: "changed";
+    shape: "table";
+    added: RowChange[];
+    removed: RowChange[];
+    changed: RowChange[];
+    /** Rows beyond MAX_DIFF_ENTRIES across the three lists. */
+    truncated: number;
+} | {
+    key: string;
+    status: "changed";
+    shape: "value";
+    leaves: LeafChange[];
+    truncated: number;
+};
+export interface DataDiff {
+    keys: KeyDiff[];
+    /** Count of keys whose status is not "same". */
+    changedKeys: number;
+}
+/**
+ * Diff two live-data blobs key by key (`then` → `now`). Keys are reported in
+ * `now`'s order, then keys only `then` had. A non-object side reads as {}.
+ */
+export declare function diffData(then: unknown, now: unknown): DataDiff;
+/** "+4.2%", "−1,203", "0" — a signed delta for display (U+2212 minus). */
+export declare function formatDelta(delta: number, pct?: number | null): string;
+/** Parse a `?at=` query value: ISO-8601 or epoch ms. NaN when neither. */
+export declare function parseInstant(raw: string | null): number;