mockpit 0.0.0-stage → 1.0.0

package/dist/server/postSurfaces.js

@@ -0,0 +1,407 @@
+import { z } from "zod";
+import { isKnownKit, KIT_IDS } from "./kits.js";
+import { isSurfaceKind } from "./types.js";
+const MERMAID_PARSE_NEXT_STEPS = [
+    "Correct the Mermaid syntax described by parserMessage, then retry the request.",
+    'Keep the diagram declaration on the first non-comment line (for example, "flowchart TD").',
+    "Reduce the diagram to a minimal valid form, then add statements back until the failing line is isolated.",
+];
+const requiredString = (name) => z.string({
+    required_error: `requires string "${name}"`,
+    invalid_type_error: `requires string "${name}"`,
+});
+const optionalLooseString = z.preprocess((v) => (typeof v === "string" ? v : undefined), z.string().optional());
+const looseLayout = z.preprocess((v) => (v === "unified" || v === "split" ? v : undefined), z.enum(["unified", "split"]).optional());
+const optionalLooseNumber = z.preprocess((v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined), z.number().optional());
+const strictDiffFile = z.object({
+    filename: requiredString("filename"),
+    before: z.string({
+        required_error: 'requires string "before" and "after"',
+        invalid_type_error: 'requires string "before" and "after"',
+    }),
+    after: z.string({
+        required_error: 'requires string "before" and "after"',
+        invalid_type_error: 'requires string "before" and "after"',
+    }),
+    language: z.string().optional(),
+});
+const looseDiffFile = z
+    .object({
+    filename: z.string(),
+    before: z.unknown().optional(),
+    after: z.unknown().optional(),
+    language: optionalLooseString,
+})
+    .transform(({ filename, before, after, language }) => ({
+    filename,
+    before: String(before ?? ""),
+    after: String(after ?? ""),
+    ...(language && { language }),
+}));
+const filteredArray = (schema) => z.preprocess((raw) => {
+    if (!Array.isArray(raw))
+        return raw;
+    return raw.flatMap((item) => {
+        const parsed = schema.safeParse(item);
+        return parsed.success ? [parsed.data] : [];
+    });
+}, z.array(schema));
+// `kits` opts an html surface into style/behavior bundles (kits.ts) or the
+// project's own kits. The ids are checked after the parse (checkKits), since
+// which ids exist depends on the project being written to.
+const strictHtmlSurface = z.object({
+    kind: z.literal("html"),
+    html: requiredString("html"),
+    kits: z.array(z.string()).optional(),
+});
+const looseHtmlSurface = z
+    .object({
+    kind: z.literal("html"),
+    html: requiredString("html"),
+    kits: z.unknown().optional(),
+})
+    .transform((p) => ({
+    kind: "html",
+    html: p.html,
+    ...(Array.isArray(p.kits) ? { kits: p.kits.filter((k) => typeof k === "string") } : {}),
+}));
+// Strict mode rejects an unknown id with the valid set, so a CLI/REST typo is a
+// clean 400; loose mode filters unknown ids out rather than dropping the whole
+// surface, and omits the field when none remain so a junk `kits` never lingers
+// as an empty key.
+function checkKits(surface, path, scope) {
+    if (surface.kind !== "html" || surface.kits === undefined)
+        return { surface, errors: [] };
+    const own = scope.projectKits ?? [];
+    const known = (id) => isKnownKit(id) || own.includes(id);
+    const errors = surface.kits.flatMap((id, i) => known(id)
+        ? []
+        : [
+            {
+                code: "invalid_surface",
+                requestPath: `${path}.kits.${i}`,
+                message: `unknown kit "${id}" — known: ${[...KIT_IDS, ...own].join(", ")}`,
+            },
+        ]);
+    const kits = surface.kits.filter(known);
+    const { kits: _drop, ...rest } = surface;
+    return { surface: kits.length > 0 ? { ...rest, kits } : rest, errors };
+}
+const strictMarkdownSurface = z.object({
+    kind: z.literal("markdown"),
+    markdown: requiredString("markdown"),
+});
+// Loose mode drops a blank markdown surface rather than publishing an empty card.
+const looseMarkdownSurface = z
+    .object({ kind: z.literal("markdown"), markdown: z.string() })
+    .refine((p) => p.markdown.trim().length > 0, {
+    message: 'markdown surface requires non-empty "markdown"',
+});
+const strictMermaidSurface = z.object({
+    kind: z.literal("mermaid"),
+    mermaid: requiredString("mermaid"),
+});
+// Loose mode drops a blank mermaid surface rather than publishing an empty card.
+const looseMermaidSurface = z
+    .object({ kind: z.literal("mermaid"), mermaid: z.string() })
+    .refine((p) => p.mermaid.trim().length > 0, {
+    message: 'mermaid surface requires non-empty "mermaid"',
+});
+const strictDiffSurface = z
+    .object({
+    kind: z.literal("diff"),
+    patch: z.string().optional(),
+    files: z.array(strictDiffFile).optional(),
+    layout: z.enum(["unified", "split"]).optional(),
+})
+    .refine((p) => !!p.patch || (p.files?.length ?? 0) > 0, {
+    message: 'diff surface requires string "patch" or non-empty "files"',
+});
+const looseDiffSurface = z
+    .object({
+    kind: z.literal("diff"),
+    patch: optionalLooseString,
+    files: filteredArray(looseDiffFile).optional(),
+    layout: looseLayout,
+})
+    .refine((p) => !!p.patch || (p.files?.length ?? 0) > 0, {
+    message: 'diff surface requires string "patch" or non-empty "files"',
+});
+const strictImageSurface = z.object({
+    kind: z.literal("image"),
+    assetId: requiredString("assetId"),
+    alt: z.string().optional(),
+    caption: z.string().optional(),
+});
+const looseImageSurface = z.object({
+    kind: z.literal("image"),
+    assetId: z.string(),
+    alt: optionalLooseString,
+    caption: optionalLooseString,
+});
+const strictTerminalSurface = z.object({
+    kind: z.literal("terminal"),
+    text: requiredString("text"),
+    cols: z.number().optional(),
+    title: z.string().optional(),
+});
+const looseTerminalSurface = z.object({
+    kind: z.literal("terminal"),
+    text: z.string(),
+    cols: optionalLooseNumber,
+    title: optionalLooseString,
+});
+// A json surface carries a pre-parsed JSON value (`data: unknown`). Strict mode
+// rejects a missing `data` key (null is valid — it's a JSON value); loose mode
+// drops the surface if `data` is absent. The transform fixes zod's inference:
+// z.unknown() marks the key optional, but data is always present after the
+// refine, so the output type must be { kind: "json"; data: unknown }.
+const strictJsonSurface = z
+    .object({
+    kind: z.literal("json"),
+    data: z.unknown(),
+})
+    .refine((p) => p.data !== undefined, {
+    message: 'json surface requires "data"',
+})
+    .transform((p) => ({ kind: "json", data: p.data }));
+const looseJsonSurface = z
+    .object({
+    kind: z.literal("json"),
+    data: z.unknown(),
+})
+    .refine((p) => p.data !== undefined, {
+    message: 'json surface requires "data"',
+})
+    .transform((p) => ({ kind: "json", data: p.data }));
+const strictCodeSurface = z.object({
+    kind: z.literal("code"),
+    code: requiredString("code"),
+    language: z.string().optional(),
+    title: z.string().optional(),
+    lineStart: z.number().int().min(1).optional(),
+});
+const looseCodeSurface = z.object({
+    kind: z.literal("code"),
+    code: z.string(),
+    language: optionalLooseString,
+    title: optionalLooseString,
+    lineStart: optionalLooseNumber,
+});
+const looseSurfaceSchema = z.union([
+    looseHtmlSurface,
+    looseMarkdownSurface,
+    looseMermaidSurface,
+    looseDiffSurface,
+    looseImageSurface,
+    looseTerminalSurface,
+    looseJsonSurface,
+    looseCodeSurface,
+]);
+const strictSurfaceSchemas = {
+    html: strictHtmlSurface,
+    markdown: strictMarkdownSurface,
+    mermaid: strictMermaidSurface,
+    diff: strictDiffSurface,
+    image: strictImageSurface,
+    terminal: strictTerminalSurface,
+    json: strictJsonSurface,
+    code: strictCodeSurface,
+};
+// Runtime surface parser shared by REST and MCP. REST uses strict mode to
+// reject malformed input before it reaches storage; MCP uses tolerant mode so
+// slightly-off tool calls still publish whatever valid surfaces they contain.
+// Async because mermaid validation awaits the parser (@mermaid-js/parser).
+async function parseSurfaceList(raw, opts = {}) {
+    if (!Array.isArray(raw)) {
+        return surfaceResult([], [{ code: "invalid_surface", requestPath: "surfaces", message: "must be an array" }]);
+    }
+    if (opts.strict === true) {
+        const results = await Promise.all(raw.map((surface, i) => parseStrictSurface(surface, i, opts)));
+        return surfaceResult(results.flatMap((r) => (r.surface ? [r.surface] : [])), results.flatMap((r) => r.errors));
+    }
+    const surfaces = [];
+    for (const [index, surface] of raw.entries()) {
+        const parsed = looseSurfaceSchema.safeParse(surface);
+        if (!parsed.success)
+            continue;
+        const { surface: kept } = checkKits(parsed.data, `surfaces[${index}]`, opts);
+        if ((await validateSemantics(kept, `surfaces[${index}]`)).length === 0)
+            surfaces.push(kept);
+    }
+    return surfaceResult(surfaces, []);
+}
+function surfaceResult(surfaces, errors) {
+    return { surfaces, parts: surfaces, errors };
+}
+export const coerceSurfaces = (raw, scope = {}) => parseSurfaceList(raw, scope).then((r) => r.surfaces);
+/** Strictly validates surfaces before a native API write reaches persistence. */
+export async function validateSurfaces(raw, scope = {}) {
+    const result = await parseSurfaceList(raw, { ...scope, strict: true });
+    return result.errors.length > 0
+        ? {
+            ok: false,
+            error: result.errors.map((issue) => `${issue.requestPath}: ${issue.message}`).join("; "),
+            code: "surface_validation_failed",
+            issues: result.errors,
+        }
+        : { ok: true, surfaces: result.surfaces, parts: result.surfaces };
+}
+// Renderability checks that run after the structural zod parse succeeds. Strict
+// mode reports these as 400s; loose mode (MCP) drops the surface. Runtime-agnostic:
+// the parsers used here are the same ones richRender.ts runs server-side (JS
+// regex engine, no DOM/WASM), so this is safe on the Worker DO too. The mermaid
+// parser (@mermaid-js/parser, the official extraction) covers the 15
+// Langium-migrated diagram types; types still on Jison (flowchart, sequence,
+// class, state, er, gantt, …) are not yet in that package, so we skip
+// validation for them — the viewer's existing graceful fallback handles any
+// render failure. No `node:` imports, no DOM usage on the parse path.
+//
+// Both parsers are imported lazily, at their point of use in validateSemantics
+// below — see the note there.
+// Takes the parsers rather than importing them, so the caller can load the module
+// OUTSIDE its try/catch — see the mermaid branch below for why that matters.
+function diffPatchHasContent(patch, { processFile, parsePatchFiles }) {
+    let files = 0;
+    for (const parsed of parsePatchFiles(patch))
+        files += parsed.files.length;
+    if (files > 0)
+        return true;
+    const fd = processFile(patch);
+    return !!(fd && (fd.name || fd.hunks?.length));
+}
+// Extract the diagram type keyword from mermaid source (the first non-empty,
+// non-comment line's first word). The official parser's `parse(diagramType,
+// text)` takes this as a separate parameter.
+function mermaidDiagramType(src) {
+    for (const line of src.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("%%") || trimmed.startsWith("#"))
+            continue;
+        return trimmed.split(/\s+/)[0] ?? null;
+    }
+    return null;
+}
+// The two parsers load at their point of use, not at module load. Together they
+// are ~51 MB of RSS and ~210 ms of import time (`npm run bench:all`, process
+// suite), and they are only reachable when someone publishes a diff or a mermaid
+// surface — a static import made every server pay that at boot to validate content
+// it may never receive. The runtime's module cache makes later publishes cheap,
+// and @pierre/diffs is shared with richRender.ts, so a workspace that renders
+// diffs loads it once for both.
+//
+// This is the other half of app.ts's lazy richRender import: leaving either half
+// static keeps the whole dependency graph resident and neither one saves anything.
+async function validateSemantics(surface, surfaceRequestPath) {
+    if (surface.kind === "diff" && surface.patch) {
+        const diffParsers = await import("@pierre/diffs");
+        try {
+            if (!diffPatchHasContent(surface.patch, diffParsers))
+                return [
+                    {
+                        code: "invalid_surface",
+                        requestPath: `${surfaceRequestPath}.patch`,
+                        message: "did not parse to any file — expected a unified/git patch with --- /+++ headers and @@ hunks",
+                    },
+                ];
+        }
+        catch (e) {
+            return [
+                {
+                    code: "invalid_surface",
+                    requestPath: `${surfaceRequestPath}.patch`,
+                    message: "failed to parse: " + (e instanceof Error ? e.message : "error"),
+                },
+            ];
+        }
+    }
+    if (surface.kind === "mermaid") {
+        const diagramType = mermaidDiagramType(surface.mermaid);
+        if (!diagramType) {
+            return [
+                {
+                    code: "invalid_mermaid_syntax",
+                    requestPath: `${surfaceRequestPath}.mermaid`,
+                    message: 'has no diagram type (first line should be e.g. "flowchart TD")',
+                    diagramType: null,
+                    parserMessage: "No Mermaid diagram type was found.",
+                    nextSteps: MERMAID_PARSE_NEXT_STEPS,
+                },
+            ];
+        }
+        // Outside the try: the catch below turns a throw into "your mermaid is
+        // invalid", which would be a wrong answer (and a 400 instead of a 500) if what
+        // actually failed was loading the parser.
+        const { parse: parseMermaid } = await import("@mermaid-js/parser");
+        try {
+            await parseMermaid(diagramType, surface.mermaid);
+        }
+        catch (e) {
+            // Unsupported diagram types (flowchart, sequence, etc. — still on Jison)
+            // skip validation; the viewer's graceful fallback handles render failures.
+            if (e instanceof Error && /unknown diagram type/i.test(e.message))
+                return [];
+            const parserMessage = e instanceof Error ? e.message : "parse error";
+            const summary = parserMessage.split("\n")[0] ?? "parse error";
+            return [
+                {
+                    code: "invalid_mermaid_syntax",
+                    requestPath: `${surfaceRequestPath}.mermaid`,
+                    message: `failed to parse: ${summary}`,
+                    diagramType,
+                    parserMessage,
+                    nextSteps: MERMAID_PARSE_NEXT_STEPS,
+                },
+            ];
+        }
+    }
+    return [];
+}
+async function parseStrictSurface(raw, index, scope) {
+    const surfaceRequestPath = `surfaces[${index}]`;
+    if (!raw || typeof raw !== "object")
+        return {
+            surface: null,
+            errors: [
+                { code: "invalid_surface", requestPath: surfaceRequestPath, message: "must be an object" },
+            ],
+        };
+    const kind = raw.kind;
+    const schema = schemaForKind(kind);
+    if (!schema) {
+        return {
+            surface: null,
+            errors: [
+                {
+                    code: "invalid_surface",
+                    requestPath: surfaceRequestPath,
+                    message: "unknown surface kind",
+                },
+            ],
+        };
+    }
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success) {
+        return { surface: null, errors: formatZodErrors(parsed.error, surfaceRequestPath) };
+    }
+    const kits = checkKits(parsed.data, surfaceRequestPath, scope);
+    if (kits.errors.length > 0)
+        return { surface: null, errors: kits.errors };
+    const semantic = await validateSemantics(kits.surface, surfaceRequestPath);
+    return semantic.length > 0
+        ? { surface: null, errors: semantic }
+        : { surface: kits.surface, errors: [] };
+}
+function schemaForKind(kind) {
+    return isSurfaceKind(kind) ? strictSurfaceSchemas[kind] : null;
+}
+function formatZodErrors(error, requestPathPrefix = "surfaces") {
+    return error.issues.map((issue) => {
+        const suffix = issue.path.length > 0 ? `.${issue.path.join(".")}` : "";
+        return {
+            code: "invalid_surface",
+            requestPath: `${requestPathPrefix}${suffix}`,
+            message: issue.message,
+        };
+    });
+}

package/dist/server/public.d.ts

@@ -0,0 +1,5 @@
+export { createApp, type AppOptions, type AuthenticateHook, type FeedEvent } from "./app.js";
+export { SqlStore } from "./sqlStore.js";
+export { createSqliteStorage } from "./sqliteStorage.js";
+export type { SurfaceValidationFailure, SurfaceValidationIssue, SurfaceValidationResult, } from "./postSurfaces.js";
+export type * from "./types.js";

package/dist/server/public.js

@@ -0,0 +1,5 @@
+// Stable public server-core entrypoint for integrations that reuse mockpit's
+// HTTP/SSE/MCP app without depending on the package's internal dist layout.
+export { createApp } from "./app.js";
+export { SqlStore } from "./sqlStore.js";
+export { createSqliteStorage } from "./sqliteStorage.js";

package/dist/server/push.d.ts

@@ -0,0 +1,45 @@
+import type { Store } from "./types.ts";
+export interface PushSubscription {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+export interface Hook {
+    id: string;
+    url: string;
+    events: HookEvent[];
+}
+export type HookEvent = "ask" | "publish" | "decision";
+export interface NotifyPayload {
+    event: HookEvent;
+    project: string;
+    slug: string;
+    variant: string;
+    version: number;
+    text: string;
+    url: string;
+}
+interface Jwk {
+    kty?: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    d?: string;
+    ext?: boolean;
+    key_ops?: string[];
+}
+interface VapidKeys {
+    publicKey: string;
+    privateJwk: Jwk;
+}
+export declare function vapidKeys(store: Store): Promise<VapidKeys>;
+export declare function listSubscriptions(store: Store): Promise<PushSubscription[]>;
+export declare function isPushSubscription(value: unknown): value is PushSubscription;
+export declare function addSubscription(store: Store, sub: PushSubscription): Promise<void>;
+export declare function listHooks(store: Store): Promise<Hook[]>;
+export declare function addHook(store: Store, hook: Hook): Promise<Hook>;
+export declare function removeHook(store: Store, id: string): Promise<boolean>;
+export declare function notify(store: Store, payload: NotifyPayload): Promise<void>;
+export {};