@penpair/core 0.3.7 → 0.4.0

package/dist/design-commands/release-command.js

@@ -0,0 +1,239 @@
+import path from "node:path";
+import { mkdir } from "node:fs/promises";
+import { parseCommandArgs, CommandArgumentError } from "../cli-arguments.js";
+import { atomicWriteFile } from "../atomic-output.js";
+import { readProjectBytes } from "../bounded-file.js";
+import { resolveProjectOutput } from "../project-input.js";
+import { createArtifactReview } from "../maps/index.js";
+import { planRelease, assembleRelease, verifyRelease, finalizeRelease, checkRelease, releaseContext, releaseDesignHash, readDesignRelease, writeDesignRelease, } from "../design-releases/index.js";
+const releaseUsage = "design-release plan|assemble|verify|finalize|check|context --from FILE [--out FILE]";
+async function readReleaseJson(context, file) {
+    return JSON.parse((await readProjectBytes(context.root, file, 16 * 1024 * 1024)).toString("utf8"));
+}
+async function writeReleaseOutput(context, file, data) {
+    const encoded = JSON.stringify(data, null, 2) + "\n";
+    if (context.redact(encoded) !== encoded) {
+        throw new Error("Release output requires credential redaction; no artifact was published");
+    }
+    const output = await resolveProjectOutput(context.root, file);
+    await mkdir(path.dirname(output), {
+        recursive: true,
+    });
+    await atomicWriteFile(output, encoded);
+}
+function validateReceiptInput(raw) {
+    if (!Array.isArray(raw) || raw.length > 100) {
+        throw new CommandArgumentError("--receipts must contain an array of at most 100 explicit sourceId/targetFrameId pairs");
+    }
+    return raw.map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new CommandArgumentError("Every transfer receipt needs sourceId and targetFrameId");
+        }
+        const record = entry;
+        if (typeof record.sourceId !== "string" ||
+            !record.sourceId ||
+            typeof record.targetFrameId !== "string" ||
+            !record.targetFrameId ||
+            Object.keys(record).some((key) => key !== "sourceId" && key !== "targetFrameId")) {
+            throw new CommandArgumentError("Every transfer receipt needs only sourceId and targetFrameId");
+        }
+        return {
+            sourceId: record.sourceId,
+            targetFrameId: record.targetFrameId,
+        };
+    });
+}
+/** CLI entrypoint: local planning stays offline and all live work uses a strictly pinned connection. */
+export async function runDesignReleaseCommand(args, context) {
+    const parsed = parseCommandArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            from: {
+                type: "string",
+            },
+            out: {
+                type: "string",
+            },
+            receipts: {
+                type: "string",
+            },
+            apply: {
+                type: "boolean",
+            },
+            live: {
+                type: "boolean",
+            },
+            draft: {
+                type: "boolean",
+            },
+            resume: {
+                type: "string",
+            },
+            by: {
+                type: "string",
+            },
+            note: {
+                type: "string",
+            },
+            json: {
+                type: "boolean",
+            },
+            help: {
+                type: "boolean",
+            },
+        },
+    });
+    const { values, positionals } = parsed;
+    const [action] = positionals;
+    const allowed = {
+        plan: [],
+        assemble: [
+            "apply",
+            "resume",
+        ],
+        verify: [
+            "receipts",
+        ],
+        finalize: [
+            "apply",
+            "resume",
+            "by",
+            "note",
+        ],
+        check: [
+            "live",
+        ],
+        context: [
+            "draft",
+        ],
+    };
+    if (values.help) {
+        context.output.log(releaseUsage);
+        return 0;
+    }
+    if (!action || !Object.hasOwn(allowed, action) || positionals.length !== 1 || !values.from) {
+        throw new CommandArgumentError(releaseUsage);
+    }
+    const acceptedFlags = new Set([
+        "from",
+        "out",
+        "json",
+        ...allowed[action],
+    ]);
+    for (const flag of Object.keys(values)) {
+        if (!acceptedFlags.has(flag)) {
+            throw new CommandArgumentError(`--${flag} is not supported by design-release ${action}`);
+        }
+    }
+    if (values.resume && !values.apply) {
+        throw new CommandArgumentError("--resume requires --apply");
+    }
+    if (action === "finalize" &&
+        ((values.apply && (!values.by?.trim() || !values.note?.trim())) ||
+            (!values.apply && (values.by || values.note)))) {
+        throw new CommandArgumentError("Finalization previews by default; --apply requires --by and --note with the owner's exact words");
+    }
+    if (action === "plan") {
+        const planned = await planRelease(context.root, await readReleaseJson(context, values.from), {
+            redact: context.redact,
+        });
+        if (values.out) {
+            await writeDesignRelease(context.root, values.out, planned, {
+                redact: context.redact,
+            });
+        }
+        context.output.result(planned);
+        context.output.log(JSON.stringify(planned, null, 2));
+        return 0;
+    }
+    const release = await readDesignRelease(context.root, values.from);
+    const options = {
+        apply: values.apply === true,
+        resume: !!values.resume,
+        runId: values.resume,
+        pointerPath: values.out ?? values.from,
+        redact: (value) => context.redact(value),
+        onStep: (message) => context.output.error(`… ${message}`),
+    };
+    if (action === "assemble") {
+        const assembled = await context.withPenpot((client) => assembleRelease(client, context.root, release, options));
+        if (values.apply) {
+            await writeDesignRelease(context.root, values.out ?? values.from, assembled, {
+                redact: context.redact,
+            });
+        }
+        else if (values.out) {
+            await writeReleaseOutput(context, values.out, assembled);
+        }
+        context.output.result(assembled);
+        context.output.log(JSON.stringify(assembled, null, 2));
+        return assembled.status === "final" || assembled.status === "verified" ? 0 : 3;
+    }
+    if (action === "verify") {
+        if (!values.receipts) {
+            throw new CommandArgumentError("design-release verify requires --receipts FILE with explicit source/target frame IDs");
+        }
+        const receipts = validateReceiptInput(await readReleaseJson(context, values.receipts));
+        const verified = await context.withPenpot((client) => verifyRelease(client, context.root, release, receipts, options));
+        await writeDesignRelease(context.root, values.out ?? values.from, verified, {
+            redact: context.redact,
+        });
+        context.output.result(verified);
+        context.output.log(JSON.stringify(verified, null, 2));
+        return verified.status === "verified" ? 0 : 3;
+    }
+    if (action === "finalize") {
+        if (!values.apply) {
+            const checked = await checkRelease(undefined, context.root, release);
+            const preview = {
+                ...checked,
+                recorded: false,
+                artifactHash: releaseDesignHash(release),
+                requiresLiveVerification: true,
+            };
+            if (values.out) {
+                await writeReleaseOutput(context, values.out, preview);
+            }
+            context.output.result(preview);
+            context.output.log(JSON.stringify(preview, null, 2));
+            return checked.valid ? 0 : 3;
+        }
+        const review = createArtifactReview({
+            artifactKind: "design-release",
+            artifactId: release.id,
+            artifactHash: releaseDesignHash(release),
+            by: values.by,
+            note: values.note,
+        });
+        const finalized = await context.withPenpot((client) => finalizeRelease(client, context.root, release, review, options));
+        context.output.result(finalized);
+        context.output.log(JSON.stringify(finalized, null, 2));
+        return finalized.status === "final" ? 0 : 3;
+    }
+    if (action === "check") {
+        const checked = values.live
+            ? await context.withPenpot((client) => checkRelease(client, context.root, release))
+            : await checkRelease(undefined, context.root, release);
+        if (values.out) {
+            await writeReleaseOutput(context, values.out, checked);
+        }
+        context.output.result(checked);
+        context.output.log(JSON.stringify(checked, null, 2));
+        return checked.valid
+            ? 0
+            : checked.reasons.some((reason) => /changed|differ|drift/i.test(reason))
+                ? 2
+                : 3;
+    }
+    if (release.status !== "final" && !values.draft) {
+        throw new CommandArgumentError("Release context requires a finalized release; use --draft to inspect explicitly unapproved context");
+    }
+    const generated = await releaseContext(context.root, release);
+    if (values.out) {
+        await writeReleaseOutput(context, values.out, generated);
+    }
+    context.output.result(generated);
+    context.output.log(JSON.stringify(generated, null, 2));
+    return generated.ready ? 0 : 3;
+}

package/dist/design-releases/artifact-paths.d.ts

@@ -0,0 +1,6 @@
+import type { ReleaseArtifactRef } from "./types.js";
+export declare const maximumArtifactBytes: number;
+export declare function hashBytes(data: string | Uint8Array): string;
+export declare function artifactPath(root: string, relative: string, createParents?: boolean): Promise<string>;
+export declare function readArtifact(root: string, reference: ReleaseArtifactRef, maximum?: number): Promise<Buffer>;
+export declare function saveArtifact(root: string, relative: string, bytes: string | Uint8Array, redact?: (text: string) => string): Promise<ReleaseArtifactRef>;

package/dist/design-releases/artifact-paths.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteFile } from "../atomic-output.js";
+import { readProjectBytes } from "../bounded-file.js";
+export const maximumArtifactBytes = 16 * 1024 * 1024;
+export function hashBytes(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export async function artifactPath(root, relative, createParents = false) {
+    if (typeof relative !== "string" ||
+        !relative ||
+        relative.length > 1024 ||
+        path.isAbsolute(relative) ||
+        relative.includes("\\") ||
+        relative.includes("\0") ||
+        relative.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new Error("Release artifact path must be a bounded project-relative path without traversal");
+    }
+    let current = await realpath(root);
+    const segments = relative.split("/");
+    for (const [index, segment] of segments.entries()) {
+        current = path.join(current, segment);
+        const parent = index < segments.length - 1;
+        try {
+            if (parent && createParents) {
+                await mkdir(current, {
+                    recursive: false,
+                }).catch((error) => {
+                    if (error.code !== "EEXIST") {
+                        throw error;
+                    }
+                });
+            }
+            const info = await lstat(current);
+            if (info.isSymbolicLink() || (parent ? !info.isDirectory() : !info.isFile())) {
+                throw new Error("Release artifact paths must use real directories and regular files");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || (parent && createParents)) {
+                throw error;
+            }
+            if (parent && !createParents) {
+                return path.join(current, ...segments.slice(index + 1));
+            }
+        }
+    }
+    return current;
+}
+export async function readArtifact(root, reference, maximum = maximumArtifactBytes) {
+    await artifactPath(root, reference.path);
+    const bytes = await readProjectBytes(root, reference.path, maximum);
+    if (bytes.length > maximum || hashBytes(bytes) !== reference.sha256) {
+        throw new Error(`Release artifact hash mismatch: ${reference.path}`);
+    }
+    return bytes;
+}
+export async function saveArtifact(root, relative, bytes, redact) {
+    const text = typeof bytes === "string" ? bytes : Buffer.from(bytes).toString("utf8");
+    if (redact && redact(text) !== text) {
+        throw new Error("Release evidence contains protected data and cannot be persisted");
+    }
+    const destination = await artifactPath(root, relative, true);
+    const sha256 = hashBytes(bytes);
+    try {
+        await atomicWriteFile(destination, bytes);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        const actual = await readProjectBytes(root, relative, Math.max(bytes.length, 1));
+        if (hashBytes(actual) !== sha256) {
+            throw new Error("Immutable release artifact already exists with different bytes");
+        }
+    }
+    return {
+        path: relative,
+        sha256,
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { PenpotToolClient } from "../client.js";
+import type { DesignRelease, ReleaseOptions } from "./types.js";
+export declare function assembleRelease(client: PenpotToolClient, root: string, raw: DesignRelease, options?: ReleaseOptions): Promise<DesignRelease>;

package/dist/design-releases/assemble.js

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+import { exportShapePng } from "../export.js";
+import { runJournaledSteps, readJournalTarget, observationHash, readJournal } from "../journal.js";
+import { withPageSession, rememberPage } from "../page-session.js";
+import { runSnippet } from "../snippet.js";
+import { assembleReleaseMaps } from "../map-penpot/index.js";
+import { saveArtifact } from "./artifact-paths.js";
+import { decodedPixels, inspectionContentHash } from "./fidelity.js";
+import { assertSourceUnchanged, captureReleaseScreen, observeRelease, releaseClient, } from "./live.js";
+import { readReleaseContract, assertReleaseContracts } from "./store.js";
+import { assembleReleaseSnippet } from "./snippets.js";
+import { validateDesignRelease } from "./validation.js";
+export async function assembleRelease(client, root, raw, options = {}) {
+    const release = validateDesignRelease(raw);
+    const encoded = JSON.stringify(release);
+    if (options.redact && options.redact(encoded) !== encoded) {
+        throw new Error("Protected data in release record; no native writes applied");
+    }
+    if (release.status === "final" || release.status === "verified") {
+        throw new Error("Verified or finalized design releases cannot be reassembled");
+    }
+    await assertReleaseContracts(root, release.contracts, false, undefined, release.fileId);
+    const contracts = await Promise.all(release.contracts.map((reference) => readReleaseContract(root, reference)));
+    for (const contract of contracts) {
+        const encoded = JSON.stringify(contract);
+        if (options.redact && options.redact(encoded) !== encoded) {
+            throw new Error("Protected data in release map contract; no native writes applied");
+        }
+    }
+    client = releaseClient(client, release);
+    return withPageSession(client, async () => {
+        for (const source of release.sources) {
+            await assertSourceUnchanged(client, root, release, source);
+        }
+        const initial = await observeRelease(client, release);
+        if (initial.marker && initial.marker.status !== "draft") {
+            throw new Error("Release version is already finalized remotely");
+        }
+        if (!options.apply) {
+            return release;
+        }
+        const runId = options.runId ?? randomUUID();
+        const complete = (value) => Boolean(value.pageId &&
+            value.overviewFrameId &&
+            value.marker?.status === "draft" &&
+            value.marker.ownerKey === release.target.ownerKey);
+        await runJournaledSteps([
+            {
+                key: "page-and-overview",
+                label: "Create owned release page and draft overview",
+                signature: assembleReleaseSnippet(release).code,
+                initial,
+                inspect: () => observeRelease(client, release),
+                apply: async () => {
+                    const result = await runSnippet(client, assembleReleaseSnippet(release), {
+                        retries: 0,
+                        effect: "write",
+                    });
+                    if (typeof result.pageId !== "string") {
+                        throw new Error("Assembly did not return page identity");
+                    }
+                    rememberPage(client, {
+                        fileId: release.fileId,
+                        pageId: result.pageId,
+                    });
+                    return result;
+                },
+                verify: complete,
+                reconcile: (_before, current) => complete(current)
+                    ? "complete"
+                    : current.marker && current.marker.status !== "draft"
+                        ? "conflict"
+                        : "pending",
+            },
+        ], {
+            root,
+            runId,
+            resume: options.resume,
+            operation: "design-release-assemble",
+            input: {
+                id: release.id,
+                version: release.productVersion,
+                ownerKey: release.target.ownerKey,
+            },
+            target: () => readJournalTarget(client),
+            onStep: options.onStep,
+            redact: options.redact,
+        });
+        const observed = await observeRelease(client, release);
+        if (!complete(observed)) {
+            throw new Error("Independent release page readback failed");
+        }
+        const assembled = {
+            ...release,
+            status: "awaiting-copy",
+            target: {
+                ...release.target,
+                pageId: observed.pageId,
+                overviewFrameId: observed.overviewFrameId,
+            },
+        };
+        const journals = {};
+        for (const [index, contract] of contracts.entries()) {
+            const mapRunId = `map-${observationHash({
+                runId,
+                index,
+            }).slice(0, 48)}`;
+            let resume = false;
+            if (options.resume) {
+                try {
+                    await readJournal(root, mapRunId);
+                    resume = true;
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        throw error;
+                    }
+                }
+            }
+            journals[`${contract.kind}:${contract.id}`] = {
+                runId: mapRunId,
+                resume,
+            };
+        }
+        const maps = await assembleReleaseMaps(client, root, {
+            fileId: release.fileId,
+            pageId: observed.pageId,
+        }, contracts, {
+            ...options.exportOptions,
+            apply: true,
+            journals,
+            redact: options.redact,
+            origin: {
+                x: 0,
+                y: 1000,
+            },
+            onStep: options.onStep,
+        });
+        for (const map of maps) {
+            const { projection, image, report } = map.publication;
+            if (!report.verified || !projection.boardId || !image?.stable) {
+                throw new Error("Native release map publication is incomplete");
+            }
+            const prefix = `design/releases/${release.productVersion}/evidence/maps/${map.mapKind}-${map.mapId}`;
+            assembled.maps = assembled.maps.filter((item) => item.kind !== map.mapKind || item.id !== map.mapId);
+            assembled.maps.push({
+                kind: map.mapKind,
+                id: map.mapId,
+                boardId: projection.boardId,
+                contractHash: map.contractHash,
+                projection: await saveArtifact(root, `${prefix}-${projection.fingerprint}.json`, `${JSON.stringify(projection, null, 2)}\n`, options.redact),
+                render: await saveArtifact(root, `${prefix}-${observationHash(image.capture)}.png`, image.png, options.redact),
+            });
+        }
+        const overview = await captureReleaseScreen(client, release.fileId, observed.pageId, observed.overviewFrameId);
+        const image = await exportShapePng(client, observed.overviewFrameId, {
+            ...options.exportOptions,
+            stable: true,
+        });
+        if (!image.stable ||
+            image.capture.fileId !== release.fileId ||
+            image.capture.pageId !== observed.pageId) {
+            throw new Error("Release overview render did not stabilize");
+        }
+        const pixels = await decodedPixels(image.png);
+        assembled.overview = {
+            contentHash: inspectionContentHash(overview),
+            decodedPixelsHash: pixels.hash,
+            render: await saveArtifact(root, `design/releases/${release.productVersion}/evidence/overview-${pixels.hash}.png`, image.png, options.redact),
+        };
+        for (const source of release.sources) {
+            await assertSourceUnchanged(client, root, release, source);
+        }
+        return validateDesignRelease(assembled);
+    });
+}

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

@@ -0,0 +1,16 @@
+import type { PenpotToolClient } from "../client.js";
+import type { DesignRelease, ReleaseArtifactRef, ReleaseCheck, ReleaseOptions } from "./types.js";
+export interface ReleaseBundle {
+    schemaVersion: 1;
+    kind: "approved-design-release";
+    designHash: string;
+    release: DesignRelease;
+    review: DesignRelease["reviews"][number];
+    artifacts: Array<{
+        original: ReleaseArtifactRef;
+        snapshot: ReleaseArtifactRef;
+    }>;
+}
+export declare function releaseReferences(release: DesignRelease): ReleaseArtifactRef[];
+export declare function readReleaseBundle(root: string, release: DesignRelease): Promise<ReleaseBundle>;
+export declare function checkRelease(client: PenpotToolClient | undefined, root: string, raw: DesignRelease, options?: ReleaseOptions): Promise<ReleaseCheck>;