@penpair/core 0.3.7 → 0.4.1

package/dist/design-releases/snippets.js

@@ -0,0 +1,89 @@
+import { snippet } from "../snippet.js";
+const inspectBody = `
+if (penpot.currentFile.id !== CFG.fileId) throw new Error("Pinned release file changed");
+const read = page => {
+  if (!page.root || typeof page.root.getSharedPluginData !== "function") throw new Error("Release ownership metadata API unavailable");
+  const raw = page.root.getSharedPluginData("penpair","design-release");
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { throw new Error("Malformed release ownership metadata"); }
+};
+const owned = penpot.currentFile.pages.filter(page => { const meta = read(page); return meta && meta.ownerKey === CFG.ownerKey; });
+if (owned.length > 1) throw new Error("Duplicate release page ownership");
+const named = penpot.currentFile.pages.filter(page => page.name === CFG.name);
+const page = owned[0] || null;
+if (named.some(candidate => !page || candidate.id !== page.id)) throw new Error("Release page name belongs to an unrelated page");
+if (CFG.pageId && (!page || page.id !== CFG.pageId)) throw new Error("Pinned release page identity changed");
+const marker = page ? read(page) : null;
+if (marker && (marker.schemaVersion !== 1 || marker.owner !== "penpair" || marker.releaseId !== CFG.releaseId || marker.productVersion !== CFG.productVersion)) throw new Error("Release ownership marker changed");
+let overview = null;
+if (page) {
+ const children = Array.isArray(page.root.children) ? page.root.children : [];
+ if (children.length > 20000) throw new Error("Release page traversal limit exceeded");
+ const boards = children.filter(shape => typeof shape.getSharedPluginData === "function" && shape.getSharedPluginData("penpair","release-overview") === CFG.ownerKey);
+ if (boards.length > 1) throw new Error("Duplicate release overview ownership");
+ overview = boards[0] || null;
+}
+const observation = {pageId:page ? page.id : null,overviewFrameId:overview ? overview.id : null,marker};
+`;
+function configuration(release) {
+    return {
+        fileId: release.fileId,
+        releaseId: release.id,
+        productVersion: release.productVersion,
+        ownerKey: release.target.ownerKey,
+        name: release.target.name,
+        pageId: release.target.pageId,
+    };
+}
+export function inspectReleaseSnippet(release) {
+    return snippet("design-release-inspect", `${inspectBody}\nreturn {ok:true,...observation};`, configuration(release), "read");
+}
+export function assembleReleaseSnippet(release) {
+    return snippet("design-release-assemble", `${inspectBody}
+if (marker && marker.status !== "draft") throw new Error("Finalized release page is immutable to assembly");
+if (typeof penpot.createPage !== "function" || typeof penpot.openPage !== "function" || typeof penpot.createBoard !== "function" || typeof penpot.createText !== "function") throw new Error("Native release assembly API unavailable");
+const matchingFonts=Array.isArray(penpot.fonts.all)?penpot.fonts.all.filter(font=>font.name==="Inter"):[];
+if(matchingFonts.length!==1)throw new Error("Inter font unavailable or ambiguous");
+const font=matchingFonts[0];
+const variants = font && Array.isArray(font.variants) ? font.variants.filter(variant => String(variant.fontWeight) === "400" && (variant.fontStyle || "normal") === "normal") : [];
+if (!font || typeof font.applyToText !== "function" || variants.length !== 1) throw new Error("Inter regular font unavailable or ambiguous");
+let target = page;
+if (!target) { target = penpot.createPage(); target.name = CFG.name; }
+await penpot.openPage(target);
+if (penpot.currentPage.id !== target.id || penpot.currentFile.id !== CFG.fileId) throw new Error("New release page did not become active");
+if (typeof target.root.setSharedPluginData !== "function") throw new Error("Release ownership write API unavailable");
+target.root.setSharedPluginData("penpair","design-release",JSON.stringify({schemaVersion:1,owner:"penpair",releaseId:CFG.releaseId,productVersion:CFG.productVersion,ownerKey:CFG.ownerKey,status:"draft"}));
+if (!overview) {
+ if (target.root.children.length) throw new Error("Unexplained shapes on interrupted release page; inspect before resuming");
+ overview = penpot.createBoard(); overview.name = "Release overview"; overview.resize(1200,800); overview.x=0; overview.y=0; overview.fills=[{fillColor:"#FFFFFF",fillOpacity:1}];
+ overview.setSharedPluginData("penpair","release-overview",CFG.ownerKey);
+ const text=penpot.createText(CFG.summary); font.applyToText(text,variants[0]); text.fontSize=20; text.resize(1100,700); text.growType="auto-height"; text.x=40;text.y=40;text.fills=[{fillColor:"#172033",fillOpacity:1}]; overview.appendChild(text);
+}
+return {ok:true,pageId:target.id,overviewFrameId:overview.id};`, {
+        ...configuration(release),
+        summary: [
+            release.title,
+            `Product ${release.productVersion}`,
+            "Journey and integration contracts",
+            ...release.contracts.map((contract) => `${contract.kind}: ${contract.id}`),
+            "Native screen transfer uses explicit source-to-target frame ID receipts; no source image approval is reused. Review the release record for current design status.",
+            ...release.sources.map((source) => source.label.slice(0, 200)),
+        ].join("\n"),
+    }, "write");
+}
+export function finalizeReleaseSnippet(release, bundleHash, reviewHash) {
+    return snippet("design-release-finalize", `${inspectBody}
+if (!page || !overview) throw new Error("Owned release page or overview is missing");
+if (marker.status === "released") {
+ if (marker.bundleHash !== CFG.bundleHash || marker.reviewHash !== CFG.reviewHash) throw new Error("Release version already finalized with different evidence");
+ return {ok:true,marker};
+}
+if (marker.status !== "draft") throw new Error("Release marker is unsupported");
+await penpot.openPage(page);
+page.root.setSharedPluginData("penpair","design-release",JSON.stringify({...marker,status:"released",bundleHash:CFG.bundleHash,reviewHash:CFG.reviewHash}));
+return {ok:true};`, {
+        ...configuration(release),
+        bundleHash,
+        reviewHash,
+    }, "write");
+}

package/dist/design-releases/store.d.ts

@@ -0,0 +1,10 @@
+import { type InspectionCapture } from "../inspection.js";
+import type { MapContract, MapContext } from "../maps/types.js";
+import type { DesignRelease, ReleaseArtifactRef, ReleaseContract, ReleaseOptions } from "./types.js";
+export declare function readDesignRelease(root: string, file: string): Promise<DesignRelease>;
+export declare function writeDesignRelease(root: string, file: string, raw: DesignRelease, options?: ReleaseOptions): Promise<void>;
+export declare function readReleaseInspection(root: string, reference: ReleaseArtifactRef): Promise<InspectionCapture>;
+export declare function readReleaseContract(root: string, reference: ReleaseArtifactRef): Promise<MapContract>;
+export declare function releaseContractContexts(root: string, contracts: ReleaseContract[], reader?: (reference: ReleaseArtifactRef) => Promise<Buffer>, fileId?: string): Promise<MapContext[]>;
+export declare function assertReleaseContracts(root: string, contracts: ReleaseContract[], reviewed?: boolean, reader?: (reference: ReleaseArtifactRef) => Promise<Buffer>, fileId?: string): Promise<void>;
+export declare function planRelease(root: string, raw: unknown, options?: ReleaseOptions): Promise<DesignRelease>;

package/dist/design-releases/store.js

@@ -0,0 +1,205 @@
+import { open, unlink } from "node:fs/promises";
+import { readProjectBytes } from "../bounded-file.js";
+import { atomicWriteFile } from "../atomic-output.js";
+import { validateInspectionDocument } from "../inspection.js";
+import { observationHash } from "../journal.js";
+import { validateMapContract, hashMapContract } from "../maps/validation.js";
+import { buildMapContext } from "../maps/context.js";
+import { artifactPath, maximumArtifactBytes, readArtifact } from "./artifact-paths.js";
+import { inspectionContentHash, decodedPixels } from "./fidelity.js";
+import { releaseContractGraph, nativeContractId } from "./contract-graph.js";
+import { validateReleasePlan, validateDesignRelease } from "./validation.js";
+export async function readDesignRelease(root, file) {
+    await artifactPath(root, file);
+    return validateDesignRelease(JSON.parse((await readProjectBytes(root, file, maximumArtifactBytes)).toString("utf8")));
+}
+export async function writeDesignRelease(root, file, raw, options = {}) {
+    const release = validateDesignRelease(raw);
+    const serialized = `${JSON.stringify(release, null, 2)}\n`;
+    if (Buffer.byteLength(serialized) > maximumArtifactBytes) {
+        throw new Error("Design release exceeds the 16-MiB artifact budget");
+    }
+    if (options.redact && options.redact(serialized) !== serialized) {
+        throw new Error("Release record contains protected data and cannot be persisted");
+    }
+    const destination = await artifactPath(root, file, true);
+    const lockPath = `${destination}.write-lock`;
+    const lock = await open(lockPath, "wx", 0o600).catch((error) => {
+        if (error.code === "EEXIST") {
+            throw new Error("Release pointer has another writer; inspect or retry after it finishes");
+        }
+        throw error;
+    });
+    try {
+        try {
+            const previous = await readDesignRelease(root, file);
+            if (previous.status === "final" ||
+                previous.id !== release.id ||
+                previous.productVersion !== release.productVersion) {
+                throw new Error("Cannot overwrite a finalized design release or change a draft identity");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        await atomicWriteFile(destination, serialized, {
+            replace: true,
+        });
+    }
+    finally {
+        await lock.close();
+        await unlink(lockPath);
+    }
+}
+export async function readReleaseInspection(root, reference) {
+    const bytes = await readArtifact(root, reference);
+    const value = JSON.parse(bytes.toString("utf8"));
+    validateInspectionDocument(value);
+    if (!value.complete || value.kind !== "shape-inspection") {
+        throw new Error("Release source inspection must be complete shape evidence");
+    }
+    return value;
+}
+export async function readReleaseContract(root, reference) {
+    return validateMapContract(JSON.parse((await readArtifact(root, reference)).toString("utf8")));
+}
+export async function releaseContractContexts(root, contracts, reader = (reference) => readArtifact(root, reference, 64 * 1024 * 1024), fileId) {
+    const maps = await Promise.all(contracts.map(async (reference) => ({
+        reference,
+        map: validateMapContract(JSON.parse((await reader(reference)).toString("utf8"))),
+    })));
+    if (!maps.some((entry) => entry.map.kind === "journey-map") ||
+        !maps.some((entry) => entry.map.kind === "integration-map")) {
+        throw new Error("A design release requires journey and integration contracts");
+    }
+    const graph = releaseContractGraph(maps, fileId);
+    const contexts = new Map();
+    for (const { reference, map } of graph.ordered) {
+        if (reference.kind !== map.kind || reference.id !== map.id) {
+            throw new Error("Release contract identity changed");
+        }
+        const journey = maps.find((entry) => entry.reference.path === map.journey?.path && entry.map.kind === "journey-map");
+        if (map.journey && (!journey || hashMapContract(journey.map) !== map.journey.sha256)) {
+            throw new Error("Integration contract does not reference the exact release journey revision");
+        }
+        const sourceHashes = {};
+        for (const source of map.sources) {
+            if (source.path) {
+                await reader({
+                    path: source.path,
+                    sha256: source.sha256,
+                });
+                sourceHashes[source.id] = source.sha256;
+            }
+        }
+        for (const artifact of reference.review?.artifacts ?? []) {
+            await reader(artifact);
+        }
+        const detailMaps = graph.details.get(nativeContractId(map)) ?? {};
+        const detailReadiness = Object.fromEntries(Object.entries(detailMaps).map(([id, child]) => [
+            id,
+            contexts.get(nativeContractId(child))?.ready === true,
+        ]));
+        const context = buildMapContext(map, {
+            reviews: reference.review
+                ? [
+                    reference.review,
+                ]
+                : [],
+            sourceHashes,
+            detailMaps,
+            detailReadiness,
+            ...(journey
+                ? {
+                    journeyHash: hashMapContract(journey.map),
+                    journeyRequirementIds: journey.map.requirements.map((item) => item.id),
+                }
+                : {}),
+            maxItems: 1000,
+            maxBytes: 128 * 1024,
+        });
+        contexts.set(nativeContractId(map), context);
+    }
+    return graph.ordered.map((entry) => contexts.get(nativeContractId(entry.map)));
+}
+export async function assertReleaseContracts(root, contracts, reviewed = false, reader, fileId) {
+    const contexts = await releaseContractContexts(root, contracts, reader, fileId);
+    if (reviewed) {
+        if (contexts.some((context) => !context.reviewed)) {
+            throw new Error("Release contracts need exact owner reviews of their current revisions, including every detail contract");
+        }
+        const blocked = contexts.find((context) => !context.ready);
+        if (blocked) {
+            throw new Error(`Release contract is not ready: ${blocked.reasons.join("; ")}`);
+        }
+    }
+}
+export async function planRelease(root, raw, options = {}) {
+    const input = validateReleasePlan(raw);
+    const safe = (value) => {
+        const serialized = JSON.stringify(value);
+        if (options.redact && options.redact(serialized) !== serialized) {
+            throw new Error("Protected data in release evidence");
+        }
+    };
+    safe(input);
+    const sources = [];
+    for (const source of input.screens) {
+        const inspection = await readReleaseInspection(root, source.inspection);
+        safe(inspection);
+        if (inspection.fileId !== input.fileId ||
+            inspection.pageId !== source.pageId ||
+            inspection.nodes?.[0]?.id !== source.frameId) {
+            throw new Error("Source screen inspection does not match pinned file/page/frame IDs");
+        }
+        if (source.render) {
+            await decodedPixels(await readArtifact(root, source.render, 64 * 1024 * 1024));
+        }
+        if (source.dependencies) {
+            await readArtifact(root, source.dependencies);
+        }
+        sources.push({
+            ...source,
+            contentHash: inspectionContentHash(inspection),
+        });
+    }
+    const contracts = await Promise.all(input.contracts.map(async (reference) => {
+        const map = await readReleaseContract(root, reference);
+        safe(map);
+        return {
+            ...reference,
+            kind: map.kind,
+            id: map.id,
+        };
+    }));
+    await assertReleaseContracts(root, contracts, false, undefined, input.fileId);
+    return validateDesignRelease({
+        schemaVersion: 1,
+        kind: "design-release",
+        id: input.id,
+        title: input.title,
+        productVersion: input.productVersion,
+        fileId: input.fileId,
+        status: "planned",
+        sources,
+        contracts,
+        target: {
+            name: `release/${input.productVersion}`,
+            ownerKey: observationHash({
+                id: input.id,
+                fileId: input.fileId,
+                productVersion: input.productVersion,
+            }),
+        },
+        maps: [],
+        receipts: [],
+        reviews: [],
+        implementation: {
+            status: "not-assessed",
+            evidence: [],
+        },
+        createdAt: new Date().toISOString(),
+    });
+}

package/dist/design-releases/types.d.ts

@@ -0,0 +1,161 @@
+import type { ArtifactReview, MapKind, MapContext } from "../maps/types.js";
+import type { ExportOptions } from "../export.js";
+export interface ReleaseArtifactRef {
+    path: string;
+    sha256: string;
+}
+export interface ReleaseScreenInput {
+    id: string;
+    label: string;
+    pageId: string;
+    frameId: string;
+    inspection: ReleaseArtifactRef;
+    render?: ReleaseArtifactRef;
+    dependencies?: ReleaseArtifactRef;
+}
+export interface ReleaseSource extends ReleaseScreenInput {
+    contentHash: string;
+}
+export interface ReleaseContractInput extends ReleaseArtifactRef {
+    review?: ArtifactReview;
+}
+export interface ReleaseContract extends ReleaseContractInput {
+    kind: MapKind;
+    id: string;
+}
+export interface DesignReleasePlanInput {
+    schemaVersion: 1;
+    kind: "design-release-plan";
+    id: string;
+    title: string;
+    productVersion: string;
+    fileId: string;
+    screens: ReleaseScreenInput[];
+    contracts: ReleaseContractInput[];
+}
+export interface ReceiptInput {
+    sourceId: string;
+    targetFrameId: string;
+}
+export interface ReleaseReceipt extends ReceiptInput {
+    sourceFrameId: string;
+    targetPageId: string;
+    nodeMap: Record<string, string>;
+    sourceContentHash: string;
+    targetContentHash: string;
+    sourceInspection: ReleaseArtifactRef;
+    targetInspection: ReleaseArtifactRef;
+    originalRender: ReleaseArtifactRef;
+    targetRender: ReleaseArtifactRef;
+    decodedPixelsHash: string;
+    width: number;
+    height: number;
+}
+export interface ReleaseFidelity {
+    schemaVersion: 1;
+    kind: "design-release-fidelity";
+    verifiedAt: string;
+    receiptsHash: string;
+    exactDecodedPixels: true;
+    nativeStructure: true;
+}
+export interface ReleaseMapEvidence {
+    kind: MapKind;
+    id: string;
+    boardId: string;
+    contractHash: string;
+    projection: ReleaseArtifactRef;
+    render: ReleaseArtifactRef;
+}
+export interface ReleaseOverviewEvidence {
+    contentHash: string;
+    render: ReleaseArtifactRef;
+    decodedPixelsHash: string;
+}
+export interface DesignRelease {
+    schemaVersion: 1;
+    kind: "design-release";
+    id: string;
+    title: string;
+    productVersion: string;
+    fileId: string;
+    status: "planned" | "awaiting-copy" | "verified" | "final";
+    sources: ReleaseSource[];
+    contracts: ReleaseContract[];
+    target: {
+        name: string;
+        ownerKey: string;
+        pageId?: string;
+        overviewFrameId?: string;
+    };
+    receipts: ReleaseReceipt[];
+    maps: ReleaseMapEvidence[];
+    overview?: ReleaseOverviewEvidence;
+    fidelity?: ReleaseFidelity;
+    reviews: ArtifactReview[];
+    implementation: {
+        status: "not-assessed" | "in-progress" | "verified";
+        evidence: ReleaseArtifactRef[];
+    };
+    createdAt: string;
+    finalized?: {
+        bundle: ReleaseArtifactRef;
+        markerHash: string;
+        reviewHash: string;
+    };
+}
+export interface ReleaseOptions {
+    apply?: boolean;
+    runId?: string;
+    resume?: boolean;
+    exportOptions?: ExportOptions;
+    onStep?: (message: string) => void;
+    pointerPath?: string;
+    redact?: (text: string) => string;
+}
+export interface ReleaseCheck {
+    valid: boolean;
+    finalized: boolean;
+    live: boolean;
+    designHash: string;
+    reasons: string[];
+    implementation: DesignRelease["implementation"]["status"];
+}
+export interface ReleaseContext {
+    schemaVersion: 1;
+    kind: "release-context";
+    id: string;
+    productVersion: string;
+    designHash: string;
+    finalized: boolean;
+    ready: boolean;
+    reasons: string[];
+    implementation: DesignRelease["implementation"];
+    screens: Array<{
+        id: string;
+        label: string;
+        sourceFrameId: string;
+        targetFrameId: string | null;
+    }>;
+    contracts: ReleaseContract[];
+    mapContexts: MapContext[];
+    mapTargets: Array<{
+        kind: MapKind;
+        id: string;
+        fileId: string;
+        pageId: string;
+        frameId: string;
+        contractHash: string;
+    }>;
+    nextActions: string[];
+    proposedBaselines: {
+        page: string;
+        root: string;
+        format: "webp";
+        frames: Array<{
+            id: string;
+            frameId: string;
+        }>;
+    };
+    truncated: boolean;
+}

package/dist/design-releases/types.js

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

package/dist/design-releases/validation.d.ts

@@ -0,0 +1,6 @@
+import type { DesignRelease, DesignReleasePlanInput, ReleaseArtifactRef } from "./types.js";
+export declare function releaseReference(raw: unknown): ReleaseArtifactRef;
+export declare function validateReleasePlan(raw: unknown): DesignReleasePlanInput;
+export declare function validateDesignRelease(raw: unknown): DesignRelease;
+/** Owner review scopes immutable design evidence; implementation acceptance is independent. */
+export declare function hashDesignRelease(raw: DesignRelease): string;