@penpair/core 0.1.3 → 0.3.0

package/dist/baselines.js

@@ -1,24 +1,29 @@
-import { createHash } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { matchingApproval } from "./approvals.js";
+import { pngSize } from "./png.js";
+export { pngSize } from "./png.js";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
 import path from "node:path";
+import { baselineCoverage } from "./baseline-coverage.js";
+import { resolveProjectOutput } from "./project-input.js";
+import { validateBaselines } from "./baselines-config.js";
+import { version } from "./version.js";
+import { atomicWriteFile } from "./atomic-output.js";
+import { observationHash } from "./journal.js";
 import { exportShapePng } from "./export.js";
 import { runOnPage } from "./operation.js";
 import { frames } from "./snippets/read.js";
 export * from "./baselines-config.js";
 const sha = (buffer) => createHash("sha256").update(buffer).digest("hex");
-/** Pixel size from a PNG's header (the IHDR chunk), or nothing when the bytes are not a PNG. */
-export function pngSize(buffer) {
-    const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-    if (buffer.length < 24 || !buffer.subarray(0, 8).equals(signature) || buffer.subarray(12, 16).toString("ascii") !== "IHDR")
-        return undefined;
-    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
-}
 async function readIfExists(file) {
     try {
         return await readFile(file);
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
     }
 }
 /**
@@ -27,64 +32,331 @@ async function readIfExists(file) {
  * the design never silently becomes the new reference.
  */
 export async function exportBaselines(client, projectRoot, config, options = {}) {
-    const listing = await runOnPage(client, frames({ page: config.page }), config.page, options);
-    const found = listing.frames ?? [];
+    if (options.forceReason !== undefined &&
+        (!options.update ||
+            !options.apply ||
+            !options.forceReason.trim() ||
+            options.forceReason.length > 2000)) {
+        throw new Error("A nonempty force reason requires apply and update");
+    }
+    config = structuredClone(config);
+    validateBaselines(config, (message) => {
+        throw new Error(message);
+    });
+    const listing = await runOnPage(client, frames({
+        page: config.page,
+    }), config.page, options);
+    if (listing.ok !== true ||
+        typeof listing.fileId !== "string" ||
+        !listing.fileId ||
+        typeof listing.pageId !== "string" ||
+        !listing.pageId ||
+        !Number.isInteger(listing.revn) ||
+        !Array.isArray(listing.frames)) {
+        throw new Error("Baseline listing lacks file/page/revision evidence");
+    }
+    const found = listing.frames;
     const results = [];
     const wrote = [];
-    const folder = path.join(projectRoot, config.root);
+    const folder = await resolveProjectOutput(projectRoot, config.root);
+    const manifestPath = await resolveProjectOutput(projectRoot, path.join(config.root, "penpair-baselines.json"));
+    const previousBytes = await readIfExists(manifestPath);
+    const previous = previousBytes
+        ? JSON.parse(previousBytes.toString("utf8"))
+        : undefined;
+    if (previous &&
+        ((previous.schemaVersion !== undefined && previous.schemaVersion !== 2) ||
+            !Array.isArray(previous.frames))) {
+        throw new Error("Existing baseline manifest is invalid; preserve and inspect it");
+    }
+    const runId = randomUUID();
+    const generation = `captures/${runId}`;
+    const captures = new Map();
     for (const wanted of config.frames) {
-        const file = `${wanted.id}.png`;
+        options.signal?.throwIfAborted();
+        const old = previous?.frames?.find((entry) => entry.id === wanted.id);
+        const file = old?.file ?? `${wanted.id}.png`;
+        if (path.isAbsolute(file) || file.split(/[\\/]/).includes("..")) {
+            throw new Error("Existing baseline path leaves its folder");
+        }
         const matches = found.filter((f) => f.name === wanted.frame);
-        if (matches.length === 0) {
-            results.push({ id: wanted.id, frame: wanted.frame, file, status: "missing", written: false });
+        if (!matches.length) {
+            results.push({
+                ...(wanted.case
+                    ? {
+                        case: wanted.case,
+                    }
+                    : {}),
+                id: wanted.id,
+                frame: wanted.frame,
+                file,
+                status: "missing",
+                written: false,
+            });
             continue;
         }
-        if (matches.length > 1)
+        if (matches.length > 1) {
             throw new Error(`more than one top-level frame on ${config.page} is named ${JSON.stringify(wanted.frame)}; rename one so the design reference is unambiguous`);
+        }
         const frame = matches[0];
         options.onStep?.(`exporting ${wanted.frame}`);
-        const exported = await exportShapePng(client, frame.id, { ...options, page: config.page, stable: true });
-        const base = { id: wanted.id, frame: wanted.frame, frameId: frame.id, width: frame.width, height: frame.height, file };
+        const exported = await exportShapePng(client, frame.id, {
+            ...options,
+            page: config.page,
+            stable: true,
+        });
+        const base = {
+            ...(wanted.case
+                ? {
+                    case: wanted.case,
+                }
+                : {}),
+            id: wanted.id,
+            frame: wanted.frame,
+            frameId: frame.id,
+            width: frame.width,
+            height: frame.height,
+            file,
+        };
+        if (exported.capture.fileId !== listing.fileId ||
+            exported.capture.pageId !== listing.pageId ||
+            exported.capture.revision !== listing.revn) {
+            throw new Error("Baseline source changed during capture; nothing was published");
+        }
         if (!exported.stable) {
-            results.push({ ...base, status: "unstable", written: false });
+            results.push({
+                ...base,
+                status: "unstable",
+                written: false,
+            });
+            continue;
+        }
+        if (!pngSize(exported.png)) {
+            throw new Error("Baseline export is not a PNG with dimensions");
+        }
+        const existing = await readIfExists(await resolveProjectOutput(projectRoot, path.join(config.root, file)));
+        if (old &&
+            (!existing ||
+                old.sha256 !== sha(existing) ||
+                (old.approved && old.approved.sha256 !== old.sha256))) {
+            throw new Error("Approved baseline bytes no longer match their manifest; inspect before replacing");
+        }
+        const captured = {
+            ...(wanted.case
+                ? {
+                    case: wanted.case,
+                }
+                : {}),
+            layout: exported.layout,
+            ...exported.capture,
+            sha256: sha(exported.png),
+            capturedAt: new Date().toISOString(),
+            toolVersion: version,
+            file: `${generation}/${wanted.id}.png`,
+        };
+        const caseProblems = [];
+        if (wanted.case) {
+            const viewport = wanted.case.viewport;
+            const size = pngSize(exported.png);
+            if (!exported.capture.designSize ||
+                exported.capture.designSize.width !== viewport.width ||
+                exported.capture.designSize.height !== viewport.height) {
+                caseProblems.push("Observed frame dimensions do not match the declared viewport");
+            }
+            if (size.width !== Math.round(viewport.width * exported.capture.scale) ||
+                size.height !== Math.round(viewport.height * exported.capture.scale)) {
+                caseProblems.push("PNG dimensions do not match declared viewport and capture scale");
+            }
+            if (wanted.case.activeThemeIds &&
+                (!exported.capture.activeThemeIds ||
+                    observationHash([
+                        ...wanted.case.activeThemeIds,
+                    ].sort()) !==
+                        observationHash([
+                            ...exported.capture.activeThemeIds,
+                        ].sort()))) {
+                caseProblems.push("Active native theme IDs do not match the capture assertion");
+            }
+        }
+        if (caseProblems.length) {
+            results.push({
+                ...base,
+                status: "case-mismatch",
+                written: false,
+                captured,
+                approved: old?.approved,
+                sha256: old?.sha256,
+                problems: caseProblems,
+            });
             continue;
         }
-        const target = path.join(folder, file);
-        const existing = await readIfExists(target);
-        const status = existing === undefined ? "new" : sha(existing) === sha(exported.png) ? "same" : "changed";
-        let written = false;
-        if (options.apply && (status === "new" || (status === "changed" && options.update))) {
-            await mkdir(folder, { recursive: true });
-            await writeFile(target, exported.png);
-            written = true;
-            wrote.push(path.join(config.root, file));
-        }
-        // A new image that was not written (a look, without --apply) is described by the export; a changed one that was not updated by what is on disk.
-        const onDisk = written || status === "same" || status === "new" ? exported.png : existing;
-        const size = pngSize(onDisk);
-        results.push({ ...base, status, written, sha256: sha(onDisk), bytes: onDisk.length, imageWidth: size?.width, imageHeight: size?.height });
+        const oldCase = old?.approved && "case" in old.approved ? old.approved.case : undefined;
+        const status = !existing
+            ? "new"
+            : sha(existing) === captured.sha256 &&
+                observationHash(oldCase ?? null) === observationHash(wanted.case ?? null) &&
+                (!old?.approved ||
+                    "legacy" in old.approved ||
+                    (old.approved.fileId === captured.fileId &&
+                        old.approved.pageId === captured.pageId &&
+                        old.approved.frameId === captured.frameId))
+                ? "same"
+                : "changed";
+        const promoteWaiver = status === "same" &&
+            old?.approved &&
+            "approval" in old.approved &&
+            old.approved.approval?.kind === "forced-reference" &&
+            options.update === true;
+        if ((status === "changed" || promoteWaiver) && options.update && options.apply) {
+            const record = await matchingApproval(projectRoot, exported.capture, captured.sha256, wanted.case);
+            if (record) {
+                captured.approval = {
+                    kind: "owner-words",
+                    id: record.id,
+                    recordHash: record.hash,
+                };
+            }
+            else if (options.forceReason) {
+                captured.approval = {
+                    kind: "forced-reference",
+                    reason: options.forceReason,
+                };
+            }
+            else {
+                throw new Error("Changed baseline requires matching exact-artifact owner words (penpair approve), or an explicit --force-reason waiver; previous artifacts preserved");
+            }
+        }
+        const approve = status === "new" ||
+            (status === "changed" && options.update === true) ||
+            Boolean(promoteWaiver);
+        const approved = approve
+            ? captured
+            : (old?.approved ?? {
+                legacy: true,
+                sha256: sha(existing),
+            });
+        const image = approve ? exported.png : existing;
+        const size = pngSize(image);
+        results.push({
+            ...base,
+            file: approve && options.apply ? captured.file : file,
+            status,
+            written: false,
+            captured,
+            approved: options.apply || !approve ? approved : undefined,
+            sha256: sha(image),
+            bytes: image.length,
+            imageWidth: size?.width,
+            imageHeight: size?.height,
+        });
+        captures.set(wanted.id, exported.png);
+    }
+    const after = await runOnPage(client, frames({
+        page: config.page,
+    }), config.page, options);
+    const source = (value) => ({
+        fileId: value.fileId,
+        pageId: value.pageId,
+        revision: value.revn,
+        frames: value.frames,
+    });
+    if (observationHash(source(listing)) !== observationHash(source(after))) {
+        throw new Error("Baseline source changed before publication; previous artifacts were preserved");
     }
-    if (options.apply) {
-        const onDisk = results.filter((r) => r.status !== "missing" && r.status !== "unstable" && (r.written || r.status === "same" || r.status === "changed"));
-        if (onDisk.length > 0) {
-            await mkdir(folder, { recursive: true });
-            const manifest = path.join(folder, "penpair-baselines.json");
-            await writeFile(manifest, `${JSON.stringify(manifestOf(config, listing, onDisk), null, 2)}\n`);
-            wrote.push(path.join(config.root, "penpair-baselines.json"));
-            const cases = path.join(folder, "reflection-cases.json");
-            await writeFile(cases, `${JSON.stringify(reflectionCases(config, onDisk), null, 2)}\n`);
-            wrote.push(path.join(config.root, "reflection-cases.json"));
+    const complete = results.length === config.frames.length &&
+        results.every((result) => result.status !== "missing" &&
+            result.status !== "unstable" &&
+            result.status !== "case-mismatch");
+    if (options.apply && complete) {
+        const evidence = JSON.stringify({
+            config,
+            results,
+            forceReason: options.forceReason,
+        });
+        if (options.redact && options.redact(evidence) !== evidence) {
+            throw new Error("Baseline evidence requires credential redaction; previous artifacts preserved");
+        }
+        options.signal?.throwIfAborted();
+        options.onStep?.("publishing complete capture");
+        options.signal?.throwIfAborted();
+        const captureFolder = await resolveProjectOutput(projectRoot, path.join(config.root, "captures"));
+        await mkdir(captureFolder, {
+            recursive: true,
+        });
+        const staged = path.join(folder, `.stage-${runId}`);
+        await mkdir(staged);
+        try {
+            for (const [id, bytes] of captures) {
+                options.signal?.throwIfAborted();
+                await atomicWriteFile(path.join(staged, `${id}.png`), bytes);
+                options.onStep?.(`staging ${id}`);
+            }
+            const cases = reflectionCases(config, results);
+            await writeFile(path.join(staged, "reflection-cases.json"), `${JSON.stringify({
+                ...cases,
+                captureId: runId,
+            }, null, 2)}\n`, {
+                flag: "wx",
+            });
+            options.signal?.throwIfAborted();
+            await rename(staged, path.join(captureFolder, runId));
+            // Immutable generation first. The canonical manifest is the commit point and is published last.
+            await atomicWriteFile(path.join(folder, "reflection-cases.json"), `${JSON.stringify({
+                ...cases,
+                captureId: runId,
+            }, null, 2)}\n`, {
+                replace: true,
+            });
+            options.signal?.throwIfAborted();
+            for (const result of results) {
+                result.written =
+                    result.file === result.captured?.file &&
+                        (result.status === "new" || options.update === true);
+            }
+            const manifest = {
+                schemaVersion: 2,
+                complete: true,
+                captureId: runId,
+                penpotFile: listing.file,
+                fileId: listing.fileId,
+                page: config.page,
+                pageId: listing.pageId,
+                coverage: baselineCoverage(config, results),
+                capturedRevision: listing.revn,
+                casesFile: `${generation}/reflection-cases.json`,
+                note: "Capture provenance and approved provenance are separate. Changed references require exact-artifact owner words or a recorded forced-reference waiver.",
+                frames: results,
+            };
+            await atomicWriteFile(path.join(folder, "penpair-baselines.json"), `${JSON.stringify(manifest, null, 2)}\n`, {
+                replace: true,
+            });
+            for (const result of results) {
+                result.written =
+                    result.file === result.captured?.file &&
+                        (result.status === "new" || options.update === true);
+                if (result.written) {
+                    wrote.push(path.join(config.root, result.file));
+                }
+            }
+            wrote.push(path.join(config.root, "reflection-cases.json"), path.join(config.root, "penpair-baselines.json"));
+        }
+        finally {
+            await rm(staged, {
+                recursive: true,
+                force: true,
+            });
         }
     }
-    return { page: config.page, penpotFile: String(listing.file ?? ""), revn: Number(listing.revn ?? 0), results, wrote };
-}
-function manifestOf(config, listing, results) {
     return {
-        note: "Written by `penpair baselines`. The images are the approved design for each frame; change one only on purpose (`penpair baselines --apply --update`).",
-        penpotFile: listing.file,
+        coverage: baselineCoverage(config, results),
+        complete,
+        fileId: listing.fileId,
+        pageId: listing.pageId,
         page: config.page,
-        revn: listing.revn,
-        frames: results.map((r) => ({ id: r.id, frame: r.frame, frameId: r.frameId, width: r.imageWidth, height: r.imageHeight, file: r.file, sha256: r.sha256, bytes: r.bytes })),
+        penpotFile: String(listing.file),
+        revn: Number(listing.revn),
+        results,
+        wrote,
     };
 }
 /**
@@ -93,23 +365,53 @@ function manifestOf(config, listing, results) {
  * Review-only (`strict: false`): a difference is shown to a person, not failed.
  */
 export function reflectionCases(config, results) {
-    const routes = {};
+    const routes = Object.create(null);
     const visualSmoke = [];
+    const pendingCases = [];
     for (const wanted of config.frames) {
         const result = results.find((r) => r.id === wanted.id);
-        if (!wanted.route || !result || result.imageWidth === undefined || result.imageHeight === undefined)
+        if (!wanted.route ||
+            !result ||
+            result.imageWidth === undefined ||
+            result.imageHeight === undefined) {
+            continue;
+        }
+        if (wanted.case) {
+            const approvedCase = result.approved && "case" in result.approved ? result.approved.case : undefined;
+            pendingCases.push({
+                id: wanted.id,
+                route: wanted.route,
+                case: approvedCase ?? wanted.case,
+                baseline: result.file,
+                ref: `penpair:${wanted.id}`,
+                approvedProvenance: result.approved ?? null,
+                captured: result.captured ?? null,
+                approvedMetadata: Boolean(approvedCase && observationHash(approvedCase) === observationHash(wanted.case)),
+                reason: "Explicit theme/state/fixture/font setup requires an implementation provider mapping",
+                browserVerification: "not-run",
+            });
             continue;
-        const viewport = { name: `design-${result.imageWidth}x${result.imageHeight}`, width: result.imageWidth, height: result.imageHeight };
-        const entry = (routes[wanted.route] ??= { viewports: [] });
-        if (!entry.viewports.some((v) => v.name === viewport.name))
+        }
+        const viewport = {
+            name: `design-${result.imageWidth}x${result.imageHeight}`,
+            width: result.imageWidth,
+            height: result.imageHeight,
+        };
+        const entry = (routes[wanted.route] ??= {
+            viewports: [],
+        });
+        if (!entry.viewports.some((v) => v.name === viewport.name)) {
             entry.viewports.push(viewport);
+        }
         visualSmoke.push({
             id: wanted.id,
             route: wanted.route,
             viewport: viewport.name,
             baselineRoot: config.root,
-            baseline: `${wanted.id}.png`,
-            threshold: { maxDiffPixelRatio: config.threshold ?? 0.05 },
+            baseline: result.file,
+            threshold: {
+                maxDiffPixelRatio: config.threshold ?? 0.05,
+            },
             strict: false,
             ref: `penpair:${wanted.id}`,
         });
@@ -118,5 +420,6 @@ export function reflectionCases(config, results) {
         note: "Generated by `penpair baselines`. Add each route's viewports to that route in your Reflection config and spread `visualSmoke` into the browser contract; baselineRoot is relative to the Reflection config's folder.",
         routes,
         visualSmoke,
+        pendingCases,
     };
 }

package/dist/cli-arguments.d.ts

@@ -0,0 +1,7 @@
+import { parseArgs, type ParseArgsConfig } from "node:util";
+export declare class CommandArgumentError extends Error {
+    readonly code = "invalid-arguments";
+    readonly remedy = "Use the command's supported flags and required values; see penpair --help.";
+}
+/** Suggestions are explanatory only; never reinterpret a supplied option. */
+export declare function parseCommandArgs<T extends ParseArgsConfig>(config: T): ReturnType<typeof parseArgs<T>>;

package/dist/cli-arguments.js

@@ -0,0 +1,47 @@
+import { parseArgs } from "node:util";
+export class CommandArgumentError extends Error {
+    code = "invalid-arguments";
+    remedy = "Use the command's supported flags and required values; see penpair --help.";
+}
+function distance(a, b) {
+    let previous = Array.from({
+        length: b.length + 1,
+    }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [
+            i,
+        ];
+        for (let j = 1; j <= b.length; j++) {
+            next[j] = Math.min(next[j - 1] + 1, previous[j] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = next;
+    }
+    return previous[b.length];
+}
+/** Suggestions are explanatory only; never reinterpret a supplied option. */
+export function parseCommandArgs(config) {
+    try {
+        return parseArgs(config);
+    }
+    catch (error) {
+        const value = error;
+        if (!value.code?.startsWith("ERR_PARSE_ARGS")) {
+            throw error;
+        }
+        const unknown = /Unknown option ['"]--([^'"]+)['"]/.exec(value.message ?? "")?.[1];
+        let hint = "";
+        if (unknown && unknown.length <= 100) {
+            const candidates = Object.keys(config.options ?? {})
+                .map((name) => ({
+                name,
+                distance: distance(unknown.toLowerCase(), name.toLowerCase()),
+            }))
+                .sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name));
+            const best = candidates[0];
+            if (best && best.distance <= Math.max(2, Math.ceil(unknown.length / 2))) {
+                hint = ` Did you mean --${best.name}?`;
+            }
+        }
+        throw new CommandArgumentError((value.message ?? "Invalid command arguments") + hint);
+    }
+}

package/dist/cli-main.d.ts

@@ -1,10 +1,22 @@
+import { type CommandResult } from "./command-result.js";
+import { type ProjectConfig } from "./instance/config.js";
 import { type Adapter } from "./adapters.js";
 import { type LocalProfile } from "./local-profile.js";
 export interface CliOptions {
+    /** Explicit request-scoped project root; never changes the process working directory. */
+    root?: string;
+    /** Refuse unrelated global client endpoint fallback (used by the stdio server). */
+    projectEndpointOnly?: boolean;
+    /** Immutable server target: every loaded project configuration must still match. */
+    pinnedConfig?: ProjectConfig;
+    strictFileGuard?: boolean;
     /** Adapters already loaded (the command loads the project's own from penpair.config.json). */
     adapters?: Adapter[];
+    configuredAdapters?: string[];
     /** A way to run Penpot on this computer, from a package that provides one (`@penpair/docker`). Without it those commands explain where they come from. */
     local?: LocalProfile;
 }
-/** Runs the command line and returns the exit code. The `penpair` command calls it with nothing extra; a package that adds a way to run Penpot calls it with its profile. */
+export declare function runCommand(argv: string[], options?: CliOptions & {
+    signal?: AbortSignal;
+}): Promise<CommandResult>;
 export declare function runCli(argv: string[], options?: CliOptions): Promise<number>;