@penpair/core 0.3.7 → 0.4.1

package/dist/maps/types.d.ts

@@ -0,0 +1,206 @@
+export type MapKind = "journey-map" | "integration-map";
+export type MapOrigin = "observed" | "proposed" | "owner-decision" | "unknown";
+export type MapIcon = "screen" | "action" | "decision" | "data" | "service" | "code" | "check" | "link";
+export interface MapSource {
+    id: string;
+    kind: "inspection" | "baseline" | "code" | "contract" | "other";
+    sha256: string;
+    path?: string;
+    fileId?: string;
+    pageId?: string;
+    frameId?: string;
+    revision?: number;
+}
+export interface MapNode {
+    id: string;
+    label: string;
+    summary?: string;
+    description?: string;
+    icon?: MapIcon;
+    kind: string;
+    origin: MapOrigin;
+    requirementIds?: string[];
+    sourceIds?: string[];
+}
+export interface MapEdge {
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+    origin: MapOrigin;
+    requirementIds?: string[];
+}
+export interface MapRequirement {
+    id: string;
+    text: string;
+    origin: MapOrigin;
+    sourceIds?: string[];
+}
+export interface MapFinding {
+    id: string;
+    message: string;
+    severity: "blocking" | "warning" | "info";
+    status: "open" | "resolved";
+    resolution?: string;
+}
+export interface MapContract {
+    schemaVersion: 1;
+    kind: MapKind;
+    id: string;
+    title: string;
+    goal: string;
+    summary?: string;
+    description?: string;
+    sources: MapSource[];
+    nodes: MapNode[];
+    edges: MapEdge[];
+    requirements: MapRequirement[];
+    findings: MapFinding[];
+    journey?: {
+        path: string;
+        sha256: string;
+    };
+    presentation?: {
+        fontFamily: string;
+    };
+}
+export interface JourneyMap extends MapContract {
+    kind: "journey-map";
+}
+export interface IntegrationMap extends MapContract {
+    kind: "integration-map";
+}
+export interface ArtifactReview {
+    schemaVersion: 1;
+    kind: "artifact-review";
+    id: string;
+    artifactKind: MapKind | "design-release" | "design-evidence";
+    artifactId: string;
+    artifactHash: string;
+    by: string;
+    note: string;
+    recordedAt: string;
+    artifacts?: Array<{
+        path: string;
+        sha256: string;
+    }>;
+    hash: string;
+}
+export interface MapProposal {
+    schemaVersion: 1;
+    kind: "map-proposal";
+    baseHash: string;
+    proposedHash: string;
+    proposedMap: MapContract;
+    reason: string;
+    hash: string;
+}
+export interface MapDrawingNode extends MapNode {
+    cardTitle: string;
+    cardSummary?: string;
+    annotationId?: string;
+    detail?: MapDetailTarget;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MapDrawingEdge extends MapEdge {
+    labelBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+export interface MapDetailTarget {
+    sourceId: string;
+    path: string;
+    sha256: string;
+    fileId: string;
+    pageId: string;
+    frameId: string;
+    mapId: string;
+    contractHash: string;
+}
+export interface MapDetailContext {
+    nodeId: string;
+    sourceId: string;
+    path: string;
+    sha256: string;
+    fileId: string;
+    pageId: string;
+    frameId: string;
+    mapId?: string;
+    mapHash?: string;
+    ready: boolean;
+    review: "separate-artifact";
+    contents: "not-inlined";
+}
+export interface MapDrawingPlan {
+    schemaVersion: 1;
+    kind: "map-drawing-plan";
+    mapKind: MapKind;
+    mapId: string;
+    mapHash: string;
+    title: string;
+    goal: string;
+    summary?: string;
+    description?: string;
+    headerSummary?: string;
+    header: {
+        titleBox: MapDrawingBox;
+        summaryBox?: MapDrawingBox;
+        legendY: number;
+        height: number;
+    };
+    annotations: MapDrawingAnnotation[];
+    fontFamily: string;
+    width: number;
+    height: number;
+    nodes: MapDrawingNode[];
+    edges: MapDrawingEdge[];
+    complete: boolean;
+    reasons: string[];
+}
+export interface MapDrawingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MapDrawingAnnotation extends MapDrawingBox {
+    id: string;
+    nodeId?: string;
+    title: string;
+    goal?: string;
+    summary?: string;
+    description?: string;
+}
+export interface MapContext {
+    schemaVersion: 1;
+    kind: "map-context";
+    mapKind: MapKind;
+    mapId: string;
+    mapHash: string;
+    title: string;
+    goal: string;
+    summary?: string;
+    description?: string;
+    reviewed: boolean;
+    ready: boolean;
+    freshness: "matches-supplied-inputs" | "stale" | "unassessed";
+    reasons: string[];
+    nodes: MapNode[];
+    edges: MapEdge[];
+    requirements: MapRequirement[];
+    findings: MapFinding[];
+    sources: MapSource[];
+    truncated: boolean;
+    details: MapDetailContext[];
+    implementation: "not-assessed";
+}

package/dist/maps/types.js

@@ -0,0 +1 @@
+export {};

package/dist/maps/validation.d.ts

@@ -0,0 +1,10 @@
+import type { MapContract, MapNode } from "./types.js";
+export declare const maxMapBytes: number;
+export declare function mapObject(value: unknown, label: string, keys: string[]): Record<string, unknown>;
+export declare function mapText(value: unknown, label: string, maxLength?: number): string;
+export declare function mapId(value: unknown, label: string): string;
+export declare function mapHash(value: unknown, label: string): string;
+export declare function mapPath(value: unknown, label: string): string;
+export declare function validateMapContract(raw: unknown): MapContract;
+export declare function hashMapContract(raw: unknown): string;
+export declare function validateMapDetail(parent: Pick<MapContract, "kind" | "id" | "sources">, node: Pick<MapNode, "id" | "sourceIds" | "requirementIds">, raw: unknown): MapContract;

package/dist/maps/validation.js

@@ -0,0 +1,375 @@
+import path from "node:path";
+import { observationHash } from "../journal.js";
+export const maxMapBytes = 16 * 1024 * 1024;
+export function mapObject(value, label, keys) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    const object = value;
+    if (Object.keys(object).some((key) => !keys.includes(key))) {
+        throw new Error(`${label} contains an unsupported field`);
+    }
+    return object;
+}
+export function mapText(value, label, maxLength = 2000) {
+    if (typeof value !== "string" ||
+        !value.trim() ||
+        value.length > maxLength ||
+        value.includes("\0")) {
+        throw new Error(`${label} requires nonempty text of at most ${maxLength} characters`);
+    }
+    return value;
+}
+export function mapId(value, label) {
+    if (typeof value !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value)) {
+        throw new Error(`${label} requires a stable logical ID`);
+    }
+    return value;
+}
+export function mapHash(value, label) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+        throw new Error(`${label} requires a SHA-256 hash`);
+    }
+    return value;
+}
+export function mapPath(value, label) {
+    const entry = mapText(value, label, 2000);
+    if (path.isAbsolute(entry) || /^[a-zA-Z]:/.test(entry) || entry.split(/[\\/]/).includes("..")) {
+        throw new Error(`${label} must stay inside the project`);
+    }
+    return entry;
+}
+function mapOrigin(value) {
+    if (value !== "observed" &&
+        value !== "proposed" &&
+        value !== "owner-decision" &&
+        value !== "unknown") {
+        throw new Error("Map origin must distinguish observed, proposed, owner-decision or unknown");
+    }
+    return value;
+}
+function mapList(value, label, maximum) {
+    if (!Array.isArray(value) || value.length > maximum) {
+        throw new Error(`${label} must contain at most ${maximum} entries`);
+    }
+    return value;
+}
+function references(value, label) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const entries = mapList(value, label, 1000).map((entry) => mapId(entry, label));
+    if (new Set(entries).size !== entries.length) {
+        throw new Error(`${label} contains duplicate references`);
+    }
+    return entries.sort();
+}
+function optionalReferences(object, key) {
+    const value = references(object[key], key);
+    return value === undefined
+        ? {}
+        : {
+            [key]: value,
+        };
+}
+function validateSource(raw) {
+    const source = mapObject(raw, "Map source", [
+        "id",
+        "kind",
+        "sha256",
+        "path",
+        "fileId",
+        "pageId",
+        "frameId",
+        "revision",
+    ]);
+    if (typeof source.kind !== "string" ||
+        ![
+            "inspection",
+            "baseline",
+            "code",
+            "contract",
+            "other",
+        ].includes(source.kind)) {
+        throw new Error("Unsupported map source kind");
+    }
+    const result = {
+        id: mapId(source.id, "Source ID"),
+        kind: source.kind,
+        sha256: mapHash(source.sha256, "Source hash"),
+    };
+    if (source.path !== undefined) {
+        result.path = mapPath(source.path, "Source path");
+    }
+    for (const key of [
+        "fileId",
+        "pageId",
+        "frameId",
+    ]) {
+        if (source[key] !== undefined) {
+            result[key] = mapText(source[key], key, 200);
+        }
+    }
+    if (source.revision !== undefined) {
+        if (!Number.isSafeInteger(source.revision) || Number(source.revision) < 0) {
+            throw new Error("Source revision must be a nonnegative safe integer");
+        }
+        result.revision = Number(source.revision);
+    }
+    return result;
+}
+function validateNode(raw) {
+    const node = mapObject(raw, "Map node", [
+        "id",
+        "label",
+        "summary",
+        "description",
+        "icon",
+        "kind",
+        "origin",
+        "requirementIds",
+        "sourceIds",
+    ]);
+    const result = {
+        id: mapId(node.id, "Node ID"),
+        label: mapText(node.label, "Node label"),
+        kind: mapId(node.kind, "Node kind"),
+        origin: mapOrigin(node.origin),
+        ...optionalReferences(node, "requirementIds"),
+        ...optionalReferences(node, "sourceIds"),
+    };
+    if (node.summary !== undefined) {
+        result.summary = mapText(node.summary, "Node summary", 240);
+    }
+    if (node.description !== undefined) {
+        result.description = mapText(node.description, "Node description", 4000);
+    }
+    if (node.icon !== undefined) {
+        if (typeof node.icon !== "string" ||
+            ![
+                "screen",
+                "action",
+                "decision",
+                "data",
+                "service",
+                "code",
+                "check",
+                "link",
+            ].includes(node.icon)) {
+            throw new Error("Node icon requires a supported semantic icon");
+        }
+        result.icon = node.icon;
+    }
+    return result;
+}
+function validateEdge(raw) {
+    const edge = mapObject(raw, "Map edge", [
+        "id",
+        "from",
+        "to",
+        "label",
+        "origin",
+        "requirementIds",
+    ]);
+    return {
+        id: mapId(edge.id, "Edge ID"),
+        from: mapId(edge.from, "Edge source"),
+        to: mapId(edge.to, "Edge target"),
+        label: mapText(edge.label, "Edge label"),
+        origin: mapOrigin(edge.origin),
+        ...optionalReferences(edge, "requirementIds"),
+    };
+}
+function validateRequirement(raw) {
+    const requirement = mapObject(raw, "Map requirement", [
+        "id",
+        "text",
+        "origin",
+        "sourceIds",
+    ]);
+    return {
+        id: mapId(requirement.id, "Requirement ID"),
+        text: mapText(requirement.text, "Requirement text", 8000),
+        origin: mapOrigin(requirement.origin),
+        ...optionalReferences(requirement, "sourceIds"),
+    };
+}
+function validateFinding(raw) {
+    const finding = mapObject(raw, "Map finding", [
+        "id",
+        "message",
+        "severity",
+        "status",
+        "resolution",
+    ]);
+    if (typeof finding.severity !== "string" ||
+        ![
+            "blocking",
+            "warning",
+            "info",
+        ].includes(finding.severity) ||
+        (finding.status !== "open" && finding.status !== "resolved")) {
+        throw new Error("Map findings require explicit severity and open/resolved status");
+    }
+    const result = {
+        id: mapId(finding.id, "Finding ID"),
+        message: mapText(finding.message, "Finding message", 8000),
+        severity: finding.severity,
+        status: finding.status,
+    };
+    if (finding.resolution !== undefined) {
+        result.resolution = mapText(finding.resolution, "Finding resolution", 8000);
+    }
+    if (result.status === "resolved" && !result.resolution) {
+        throw new Error("A resolved finding requires an explicit resolution");
+    }
+    return result;
+}
+function uniqueSorted(entries, label) {
+    if (new Set(entries.map((entry) => entry.id)).size !== entries.length) {
+        throw new Error(`Duplicate ${label} ID`);
+    }
+    return entries.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+}
+function validateReferences(contract) {
+    const nodeIds = new Set(contract.nodes.map((node) => node.id));
+    const sourceIds = new Set(contract.sources.map((source) => source.id));
+    const requirementIds = new Set(contract.requirements.map((requirement) => requirement.id));
+    for (const edge of contract.edges) {
+        if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) {
+            throw new Error(`Edge ${edge.id} refers to a missing node`);
+        }
+    }
+    for (const item of [
+        ...contract.nodes,
+        ...contract.edges,
+    ]) {
+        if ((item.requirementIds ?? []).some((id) => !requirementIds.has(id))) {
+            throw new Error(`${item.id} refers to a missing requirement`);
+        }
+    }
+    for (const item of [
+        ...contract.nodes,
+        ...contract.requirements,
+    ]) {
+        if ((item.sourceIds ?? []).some((id) => !sourceIds.has(id))) {
+            throw new Error(`${item.id} refers to a missing source`);
+        }
+        if (item.origin === "observed" && !item.sourceIds?.length) {
+            throw new Error(`Observed ${item.id} requires an explicit source reference`);
+        }
+    }
+    const details = contract.nodes.filter((node) => node.kind === "detail-link");
+    if (details.length > 64) {
+        throw new Error("A map supports at most 64 explicit direct detail links");
+    }
+    for (const node of details) {
+        const source = contract.sources.find((entry) => entry.id === node.sourceIds?.[0]);
+        if (node.sourceIds?.length !== 1 ||
+            !node.requirementIds?.length ||
+            !source ||
+            source.kind !== "contract" ||
+            !source.path ||
+            !source.fileId ||
+            !source.pageId ||
+            !source.frameId) {
+            throw new Error("Detail links require one contract source with path, raw SHA, file/page/frame IDs and explicit mapped requirements");
+        }
+    }
+    if (details.length &&
+        new Set(contract.sources.flatMap((source) => source.fileId
+            ? [
+                source.fileId,
+            ]
+            : [])).size > 1) {
+        throw new Error("Linked native detail boards must belong to the same pinned file");
+    }
+}
+export function validateMapContract(raw) {
+    const encoded = JSON.stringify(raw);
+    if (!encoded || Buffer.byteLength(encoded) > maxMapBytes) {
+        throw new Error("Map contract exceeds the 16 MiB byte budget");
+    }
+    const object = mapObject(raw, "Map contract", [
+        "schemaVersion",
+        "kind",
+        "id",
+        "title",
+        "goal",
+        "summary",
+        "description",
+        "sources",
+        "nodes",
+        "edges",
+        "requirements",
+        "findings",
+        "journey",
+        "presentation",
+    ]);
+    if (object.schemaVersion !== 1 ||
+        (object.kind !== "journey-map" && object.kind !== "integration-map")) {
+        throw new Error("Unsupported map schema or kind");
+    }
+    const contract = {
+        schemaVersion: 1,
+        kind: object.kind,
+        id: mapId(object.id, "Map ID"),
+        title: mapText(object.title, "Map title", 200),
+        goal: mapText(object.goal, "Map goal", 8000),
+        sources: uniqueSorted(mapList(object.sources, "Map sources", 1000).map(validateSource), "source"),
+        nodes: uniqueSorted(mapList(object.nodes, "Map nodes", 1000).map(validateNode), "node"),
+        edges: uniqueSorted(mapList(object.edges, "Map edges", 2000).map(validateEdge), "edge"),
+        requirements: uniqueSorted(mapList(object.requirements, "Map requirements", 1000).map(validateRequirement), "requirement"),
+        findings: uniqueSorted(mapList(object.findings, "Map findings", 2000).map(validateFinding), "finding"),
+    };
+    if (!contract.nodes.length) {
+        throw new Error("A map requires at least one explicit node");
+    }
+    if (object.summary !== undefined) {
+        contract.summary = mapText(object.summary, "Map summary", 240);
+    }
+    if (object.description !== undefined) {
+        contract.description = mapText(object.description, "Map description", 8000);
+    }
+    if (object.journey !== undefined) {
+        if (contract.kind !== "integration-map") {
+            throw new Error("Only an integration map may reference a journey contract");
+        }
+        const journey = mapObject(object.journey, "Journey reference", [
+            "path",
+            "sha256",
+        ]);
+        contract.journey = {
+            path: mapPath(journey.path, "Journey path"),
+            sha256: mapHash(journey.sha256, "Journey hash"),
+        };
+    }
+    if (object.presentation !== undefined) {
+        const presentation = mapObject(object.presentation, "Map presentation", [
+            "fontFamily",
+        ]);
+        contract.presentation = {
+            fontFamily: mapText(presentation.fontFamily, "Map font", 200),
+        };
+    }
+    validateReferences(contract);
+    return contract;
+}
+export function hashMapContract(raw) {
+    return observationHash(validateMapContract(raw));
+}
+export function validateMapDetail(parent, node, raw) {
+    const detail = validateMapContract(raw);
+    if (detail.kind !== parent.kind || detail.id === parent.id) {
+        throw new Error("A detail must reference a different contract of the same map kind");
+    }
+    const required = new Set(detail.requirements.map((requirement) => requirement.id));
+    if ((node.requirementIds ?? []).some((id) => !required.has(id))) {
+        throw new Error(`Linked detail omits a requirement assigned to ${node.id}`);
+    }
+    const source = parent.sources.find((entry) => entry.id === node.sourceIds?.[0]);
+    if (source && detail.sources.some((entry) => entry.fileId && entry.fileId !== source.fileId)) {
+        throw new Error("Linked detail sources belong to a different pinned native file");
+    }
+    return detail;
+}

package/dist/plugin-health.d.ts

@@ -0,0 +1,13 @@
+export interface PluginHealth {
+    state: "responsive" | "suspended" | "unknown";
+    heartbeatAgeMs: number | null;
+    heartbeatSource: "upstream-error" | "unavailable";
+    keepAlive: {
+        method: "unknown";
+        verified: false;
+    };
+}
+/** Fresh execution proves responsiveness, not the plugin's heartbeat time or browser policy. */
+export declare function responsivePluginHealth(): PluginHealth;
+/** Upstream error text is the only heartbeat telemetry exposed by the current connection. */
+export declare function pluginHealthFromError(error: unknown): PluginHealth;

package/dist/plugin-health.js

@@ -0,0 +1,39 @@
+function health(state, heartbeatAgeMs) {
+    return {
+        state,
+        heartbeatAgeMs,
+        heartbeatSource: heartbeatAgeMs === null ? "unavailable" : "upstream-error",
+        keepAlive: {
+            method: "unknown",
+            verified: false,
+        },
+    };
+}
+/** Fresh execution proves responsiveness, not the plugin's heartbeat time or browser policy. */
+export function responsivePluginHealth() {
+    return health("responsive", null);
+}
+/** Upstream error text is the only heartbeat telemetry exposed by the current connection. */
+export function pluginHealthFromError(error) {
+    const message = error instanceof Error
+        ? error.message.slice(0, 8192)
+        : typeof error === "string"
+            ? error.slice(0, 8192)
+            : "";
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+    const suspended = code === "plugin-suspended" || /\bsuspended\b|\bno heartbeat\b/i.test(message);
+    if (!suspended) {
+        return health("unknown", null);
+    }
+    const duration = /\bno heartbeat\s+for\s+([^\s,)]+?)\s*(milliseconds?|ms|seconds?|s)\b/i.exec(message);
+    if (!duration || !/^\d+(?:\.\d+)?$/.test(duration[1])) {
+        return health("suspended", null);
+    }
+    const value = Number(duration[1]);
+    const heartbeatAgeMs = value * (/^(?:ms|milliseconds?)$/i.test(duration[2]) ? 1 : 1000);
+    return health("suspended", Number.isFinite(heartbeatAgeMs) &&
+        heartbeatAgeMs >= 0 &&
+        heartbeatAgeMs <= Number.MAX_SAFE_INTEGER
+        ? heartbeatAgeMs
+        : null);
+}

package/dist/skill-routing.js

@@ -1,4 +1,8 @@
 const tasksBySkill = {
+    "penpair-journey-map": "Map user journeys, decisions and recovery paths in Penpot",
+    "penpair-integration-map": "Connect reviewed journeys to routes, components and data responsibilities",
+    "penpair-diagrams": "Draw or reconcile editable native Penpot diagrams",
+    "penpair-design-release": "Assemble and review a release/<version> design page",
     "penpair-setup": "Install Penpair or repair a Penpot connection",
     "penpair-design": "Inspect, edit, audit or export a Penpot file",
     "penpair-recipes": "Build a Penpot screen or derive a state variant from an approved frame",

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export declare const version = "0.3.7";
+export declare const version = "0.4.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export const version = "0.3.7";
+export const version = "0.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/core",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "description": "Design together. Build together. The library and engine behind penpair: connect AI agents and people to a Penpot design file, safely. Install @penpair/web or @penpair/docker for the command.",
   "license": "MIT",
   "repository": {
@@ -45,6 +45,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.0",
     "acorn": "8.19.0",
+    "sharp": "0.35.5",
     "yaml": "2.9.1"
   },
   "scripts": {