@penpair/core 0.1.3 → 0.3.0

package/dist/operation.js

@@ -1,55 +1,365 @@
+import { waitForStableLayout } from "./layout.js";
+import { commandSleep } from "./command-result.js";
 import { runSnippet } from "./snippet.js";
-import { switchPage } from "./snippets/read.js";
-import { archiveApply, archiveInspect, archiveReadback } from "./snippets/archive.js";
-const defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
-/** Runs a snippet; if the editor shows another page, opens the right one, waits, and tries once more. */
-export async function runOnPage(client, s, page, { settleMs = 3_000, sleep = defaultSleep, onStep, ...execute } = {}) {
-    const first = await runSnippet(client, s, execute);
-    if (!first.wrongPage || !page)
-        return first;
-    onStep?.(`opening page ${page}`);
-    await runSnippet(client, switchPage(page), execute);
-    await sleep(settleMs);
-    const second = await runSnippet(client, s, execute);
-    if (second.wrongPage)
-        throw new Error(`${s.name}: the editor still shows another page than ${page}`);
-    return second;
+import { withPageSession, pinPageSnippet, selectPage, rememberPage } from "./page-session.js";
+import { archiveApply, archiveInspect, archiveReadback, } from "./snippets/archive.js";
+import { PenpairError } from "./errors.js";
+import { UncertainExecutionError } from "./client.js";
+import { observationHash, readJournalTarget, runJournaledSteps, } from "./journal.js";
+import { guardRevision, writeCoordinator } from "./coordination.js";
+import { guardFile } from "./file-guard.js";
+const defaultSleep = commandSleep;
+/** Runs once on the expected page; page transitions require independently observed IDs. */
+export async function runOnPage(client, s, page, { settleMs: _settleMs, sleep = defaultSleep, onStep, ...execute } = {}) {
+    return withPageSession(client, async () => {
+        const started = Date.now();
+        const remaining = () => ({
+            ...execute,
+            ...(execute.timeoutMs
+                ? {
+                    timeoutMs: Math.max(1, execute.timeoutMs - (Date.now() - started)),
+                }
+                : {}),
+        });
+        const first = await runSnippet(client, pinPageSnippet(client, s), remaining());
+        if (!first.wrongPage || !page) {
+            if (typeof first.fileId === "string" && typeof first.pageId === "string") {
+                rememberPage(client, {
+                    fileId: first.fileId,
+                    pageId: first.pageId,
+                });
+            }
+            return first;
+        }
+        onStep?.(`opening page ${page}`);
+        await selectPage(client, {
+            name: page,
+        }, {
+            ...remaining(),
+            sleep,
+        });
+        const second = await runSnippet(client, pinPageSnippet(client, s), remaining());
+        if (second.wrongPage) {
+            throw new Error(`${s.name}: the editor still shows another page than ${page}`);
+        }
+        return second;
+    });
 }
 export async function runOperation(client, operation, params, options = {}) {
-    const { settleMs = 10_000, sleep = defaultSleep, onStep } = options;
+    return withPageSession(client, () => runOperationInSession(client, operation, params, options));
+}
+async function runOperationInSession(client, operation, params, options) {
+    if (options.settleMs !== undefined &&
+        (!Number.isFinite(options.settleMs) || options.settleMs < 0 || options.settleMs > 30000)) {
+        throw new Error("Minimum settle delay must be from 0 to 30000 ms");
+    }
+    if (options.apply && options.journal) {
+        return journaledOperation(client, operation, params, options);
+    }
+    const { settleMs = 0, sleep = defaultSleep, onStep } = options;
     const page = operation.page(params);
     onStep?.(`${operation.name}: inspecting`);
-    const inspect = await runOnPage(client, operation.inspect(params), page, options);
-    if (!options.apply)
-        return { operation: operation.name, phase: "inspected", inspect, problems: [], verified: false };
+    const inspect = await runOnPage(client, operation.inspect(params), page, {
+        ...options,
+        effect: "read",
+    });
+    if (inspect.ok !== true) {
+        throw new PenpairError("tool-failed", `${operation.name}: inspect did not return an explicit ok result; nothing was applied`);
+    }
+    if (!options.apply) {
+        return {
+            operation: operation.name,
+            outcome: "inspected",
+            phase: "inspected",
+            inspect,
+            problems: [],
+            verified: false,
+        };
+    }
     onStep?.(`${operation.name}: writing once`);
-    const apply = await runOnPage(client, operation.apply(params), page, options);
-    onStep?.(`${operation.name}: waiting ${Math.round(settleMs / 1000)} s before reading back`);
-    await sleep(settleMs);
-    const readback = await runOnPage(client, operation.readback(params), page, options);
-    const problems = operation.verify({ inspect, apply, readback });
-    return { operation: operation.name, phase: "applied", inspect, apply, readback, problems, verified: problems.length === 0 };
+    const apply = await runOnPage(client, operation.apply(params, inspect), page, {
+        ...options,
+        effect: "write",
+    });
+    if (apply.ok !== true) {
+        throw new UncertainExecutionError(String(apply.execution?.runId ?? "unknown"), `${operation.name}: apply returned no explicit acknowledgment`);
+    }
+    if (settleMs > 0) {
+        await sleep(settleMs);
+    }
+    let layout;
+    let readback;
+    let problems;
+    try {
+        layout = await settleOperation(client, options);
+        readback = await runOnPage(client, operation.readback(params), page, {
+            ...options,
+            effect: "read",
+        });
+        problems = verificationProblems(operation, {
+            inspect,
+            apply,
+            readback,
+        });
+    }
+    catch (error) {
+        problems = [
+            `Independent verification failed: ${error instanceof Error ? error.message : String(error)}`,
+        ];
+    }
+    return {
+        layout,
+        operation: operation.name,
+        phase: "applied",
+        outcome: problems.length === 0 ? "verified" : "failed",
+        inspect,
+        apply,
+        readback,
+        problems,
+        verified: problems.length === 0,
+    };
+}
+function verificationProblems(operation, results) {
+    const { readback } = results;
+    const observations = Object.keys(readback).filter((key) => ![
+        "ok",
+        "readOnly",
+        "execution",
+        "problems",
+    ].includes(key));
+    if (Array.isArray(readback.problems) &&
+        readback.problems.length > 0 &&
+        readback.problems.every((problem) => typeof problem === "string")) {
+        return readback.problems;
+    }
+    if (readback.ok !== true || observations.length === 0) {
+        return [
+            "Readback did not provide explicit observations of the resulting state",
+        ];
+    }
+    const result = operation.verify(results);
+    return Array.isArray(result) && result.every((problem) => typeof problem === "string")
+        ? result
+        : [
+            "Verifier must return a list of problems",
+        ];
+}
+async function settleOperation(client, options) {
+    if (options.layout === false) {
+        return undefined;
+    }
+    options.onStep?.("waiting for bounded layout completion");
+    const layout = await waitForStableLayout(client, {
+        sleep: options.sleep,
+        ...options.layout,
+    });
+    if (!layout.stable) {
+        throw new PenpairError("incomplete-output", `Layout did not settle: ${layout.reason ?? "unknown reason"}`);
+    }
+    return layout;
+}
+async function journaledOperation(client, operation, params, options) {
+    const page = operation.page(params);
+    await runOnPage(client, operation.inspect(params), page, {
+        ...options,
+        effect: "read",
+    });
+    await settleOperation(client, options);
+    const initialTarget = await readJournalTarget(client);
+    const guarded = guardFile(client, {
+        id: initialTarget.fileId,
+    });
+    const observe = async () => {
+        const inspection = await runOnPage(guarded, operation.inspect(params), page, {
+            ...options,
+            effect: "read",
+        });
+        const layout = await settleOperation(guarded, options);
+        const readback = await runOnPage(guarded, operation.readback(params), page, {
+            ...options,
+            effect: "read",
+        });
+        if (inspection.ok !== true || readback.ok !== true) {
+            throw new Error("Operation inspection/readback did not acknowledge its observations");
+        }
+        return {
+            inspection,
+            readback,
+            layout,
+        };
+    };
+    const verify = (current, before, result) => verificationProblems(operation, {
+        inspect: before.inspection,
+        apply: result ?? {
+            ok: true,
+            reconciled: true,
+        },
+        readback: current.readback,
+    }).length === 0;
+    const record = await runJournaledSteps([
+        {
+            key: "apply",
+            label: operation.name,
+            signature: [
+                operation.inspect(params).code,
+                operation.apply(params).code,
+                operation.readback(params).code,
+                operation.verify.toString(),
+                operation.reconcile?.toString(),
+                settleOperation.toString(),
+                waitForStableLayout.toString(),
+            ].join("\n"),
+            inspect: observe,
+            apply: async (current, target) => {
+                const result = await runOnPage(guardRevision(guarded, target), operation.apply(params, current.inspection), page, {
+                    ...options,
+                    effect: "write",
+                });
+                if (result.ok !== true) {
+                    throw new Error("Apply returned no explicit acknowledgment");
+                }
+                await (options.sleep ?? defaultSleep)(options.settleMs ?? 0);
+                return result;
+            },
+            verify,
+            reconcile: (before, current, result) => {
+                if (verify(current, before, result)) {
+                    return "complete";
+                }
+                if (operation.reconcile) {
+                    return operation.reconcile({
+                        before: before.inspection,
+                        current: current.inspection,
+                        readback: current.readback,
+                    });
+                }
+                return observationHash(before.inspection, true) ===
+                    observationHash(current.inspection, true)
+                    ? "pending"
+                    : "conflict";
+            },
+        },
+    ], {
+        ...options.journal,
+        coordinate: writeCoordinator(guarded, {
+            root: options.journal.root,
+            operation: operation.name,
+            forceLock: options.journal.forceLock,
+            warn: options.onStep,
+        }),
+        operation: operation.name,
+        input: {
+            params,
+            layout: options.layout ?? {},
+            minimumWaitMs: options.settleMs ?? 0,
+        },
+        payload: {
+            params,
+        },
+        target: () => readJournalTarget(guarded),
+        onStep: options.onStep ?? options.journal.onStep,
+        redact: options.redact ?? options.journal.redact,
+    });
+    const saved = record.steps[0];
+    return {
+        layout: saved.after.layout,
+        operation: operation.name,
+        phase: "applied",
+        outcome: record.redacted ? "failed" : "verified",
+        ...(record.redacted
+            ? {
+                redacted: true,
+                complete: false,
+            }
+            : {}),
+        inspect: saved.before.inspection,
+        apply: saved.result,
+        readback: saved.after.readback,
+        problems: record.redacted
+            ? [
+                "Journal evidence required credential redaction; completeness cannot be confirmed",
+            ]
+            : [],
+        verified: !record.redacted,
+        journal: {
+            runId: record.runId,
+            state: record.state,
+        },
+    };
 }
 /** Nests the frames that are not part of the live work into one archive board. Frames keep their names, ids and component links. */
 export const archiveOperation = {
     name: "archive",
     page: (params) => params.page,
     inspect: archiveInspect,
-    apply: archiveApply,
+    apply: (params, inspected) => archiveApply({
+        ...params,
+        expectedPlan: inspected?.plan,
+        expectedArchiveId: inspected?.archiveId,
+    }),
     readback: archiveReadback,
     verify({ inspect, apply, readback }) {
         const problems = [];
+        if (!Number.isInteger(inspect.willMove) ||
+            Number(inspect.willMove) < 0 ||
+            !Array.isArray(inspect.plan) ||
+            !Array.isArray(readback.insideIds) ||
+            !Array.isArray(readback.loose)) {
+            return [
+                "Archive verification is missing movement counts or the independent loose-frame listing",
+            ];
+        }
         const expected = Number(inspect.willMove ?? 0);
         const archive = readback.archive;
-        if (expected > 0 && Number(apply.moved ?? 0) !== expected)
-            problems.push(`moved ${apply.moved} frames, expected ${expected}`);
-        if (expected > 0 && !archive)
+        if (inspect.plan.length !== expected ||
+            inspect.plan.some((shape) => !shape.id || !readback.insideIds.includes(shape.id))) {
+            problems.push("the inspected frames are not all in the archive");
+        }
+        if (expected > 0 && !archive) {
             problems.push("the archive board is not on the page");
-        if (archive && archive.children < expected)
+        }
+        if (archive && archive.children < expected) {
             problems.push(`the archive holds ${archive.children} frames, expected at least ${expected}`);
+        }
         const loose = readback.loose ?? [];
-        if (loose.length > 0)
+        if (loose.length > 0) {
             problems.push(`${loose.length} frames are still loose on the page: ${loose.slice(0, 3).join(", ")}`);
+        }
         return problems;
     },
+    reconcile({ before, current, readback }) {
+        if (!Array.isArray(before.plan) ||
+            !Array.isArray(current.plan) ||
+            !Array.isArray(readback.insideIds)) {
+            return "conflict";
+        }
+        if (observationHash(before, true) === observationHash(current, true)) {
+            return "pending";
+        }
+        const original = before.plan;
+        const remaining = current.plan;
+        const intended = new Map(original.map((shape) => [
+            shape.id,
+            shape,
+        ]));
+        if (remaining.some((shape) => !intended.has(shape.id) ||
+            observationHash(shape) !== observationHash(intended.get(shape.id)))) {
+            return "conflict";
+        }
+        const accounted = new Set([
+            ...remaining.map((shape) => shape.id),
+            ...readback.insideIds,
+        ]);
+        if (original.some((shape) => !accounted.has(shape.id))) {
+            return "conflict";
+        }
+        if (remaining.length > 0 && (!before.archiveId || before.archiveId !== current.archiveId)) {
+            return "conflict";
+        }
+        if (Array.isArray(before.insideIds) &&
+            before.insideIds.some((id) => !readback.insideIds.includes(id))) {
+            return "conflict";
+        }
+        return remaining.length === 0 ? "complete" : "pending";
+    },
 };

package/dist/page-session.d.ts

@@ -0,0 +1,23 @@
+import type { ExecuteOptions, PenpotToolClient } from "./client.js";
+import { type Snippet } from "./snippet.js";
+interface PageIdentity {
+    fileId: string;
+    pageId: string;
+}
+export declare function inheritPageSession<T extends PenpotToolClient>(derived: T, base: PenpotToolClient): T;
+/** Nested collection steps share one session; independent callers on the same client queue. */
+export declare function withPageSession<T>(client: PenpotToolClient, work: () => Promise<T>): Promise<T>;
+export declare function rememberPage(client: PenpotToolClient, identity: PageIdentity): void;
+export declare function pinPageSnippet(client: PenpotToolClient, source: Snippet): Snippet;
+export declare function observePage(client: PenpotToolClient, options?: ExecuteOptions): Promise<PageIdentity>;
+export interface PageSwitchOptions extends ExecuteOptions {
+    sleep?: (ms: number) => Promise<void>;
+    pageSwitchTimeoutMs?: number;
+    onStep?: (message: string) => void;
+}
+export declare function selectPage(client: PenpotToolClient, target: {
+    name: string;
+} | {
+    id: string;
+}, options?: PageSwitchOptions): Promise<PageIdentity>;
+export {};

package/dist/page-session.js

@@ -0,0 +1,142 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { commandSignal, commandSleep } from "./command-result.js";
+import { runSnippet, snippet } from "./snippet.js";
+const owners = new WeakMap();
+const owner = (client) => owners.get(client) ?? client;
+export function inheritPageSession(derived, base) {
+    owners.set(derived, owner(base));
+    return derived;
+}
+const active = new AsyncLocalStorage();
+const queues = new WeakMap();
+/** Nested collection steps share one session; independent callers on the same client queue. */
+export async function withPageSession(client, work) {
+    client = owner(client);
+    if (active.getStore()?.client === client) {
+        return work();
+    }
+    const previous = queues.get(client) ?? Promise.resolve();
+    let release;
+    const gate = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = previous.catch(() => undefined).then(() => gate);
+    queues.set(client, tail);
+    const signal = commandSignal();
+    let onAbort;
+    try {
+        await new Promise((resolve, reject) => {
+            onAbort = () => reject(signal?.reason);
+            signal?.addEventListener("abort", onAbort, {
+                once: true,
+            });
+            if (signal?.aborted) {
+                onAbort();
+            }
+            previous.then(resolve, reject);
+        });
+        signal?.throwIfAborted();
+        return await active.run({
+            client,
+        }, work);
+    }
+    finally {
+        if (onAbort) {
+            signal?.removeEventListener("abort", onAbort);
+        }
+        release();
+        // A cancelled waiter still follows its predecessor; removing it early would open a parallel queue.
+        void tail.then(() => {
+            if (queues.get(client) === tail) {
+                queues.delete(client);
+            }
+        });
+    }
+}
+export function rememberPage(client, identity) {
+    const session = active.getStore();
+    if (session?.client === owner(client)) {
+        session.expected = identity;
+    }
+}
+export function pinPageSnippet(client, source) {
+    const session = active.getStore();
+    if (session?.client !== owner(client) || !session.expected) {
+        return source;
+    }
+    const expected = JSON.stringify(session.expected);
+    return {
+        ...source,
+        code: `{ const expected = ${expected}; if (penpot.currentFile.id !== expected.fileId || penpot.currentPage.id !== expected.pageId) return {ok:false,message:"Unexpected external navigation during page session"}; }\n${source.code}`,
+    };
+}
+export async function observePage(client, options = {}) {
+    const result = await runSnippet(client, pinPageSnippet(client, snippet("page-state", "return {ok:true,fileId:penpot.currentFile.id,pageId:penpot.currentPage.id};", {}, "read")), {
+        ...options,
+        effect: "read",
+        retries: 0,
+    });
+    if (typeof result.fileId !== "string" ||
+        !result.fileId ||
+        typeof result.pageId !== "string" ||
+        !result.pageId) {
+        throw new Error("Page identity was not observed");
+    }
+    return {
+        fileId: result.fileId,
+        pageId: result.pageId,
+    };
+}
+export async function selectPage(client, target, options = {}) {
+    const timeout = Math.min(options.pageSwitchTimeoutMs ?? 5000, options.timeoutMs ?? 5000);
+    if (!Number.isFinite(timeout) || timeout < 1 || timeout > 30000) {
+        throw new Error("Invalid page switch budget");
+    }
+    const deadline = Date.now() + timeout;
+    const execute = () => ({
+        ...options,
+        retries: 0,
+        effect: "read",
+        timeoutMs: Math.max(1, deadline - Date.now()),
+    });
+    const resolved = await runSnippet(client, pinPageSnippet(client, snippet("select-page", `
+const matches = penpot.currentFile.pages.filter(p => CFG.id ? p.id === CFG.id : p.name === CFG.name);
+if (matches.length !== 1) return {ok:false,message:"Page selection is missing or ambiguous"};
+const target = matches[0], fileId = penpot.currentFile.id, previousPageId = penpot.currentPage.id;
+if (target.id !== previousPageId) penpot.openPage(target);
+return {ok:true,fileId,pageId:target.id,previousPageId};`, target, "read")), execute());
+    if (typeof resolved.fileId !== "string" ||
+        typeof resolved.pageId !== "string" ||
+        typeof resolved.previousPageId !== "string") {
+        throw new Error("Page selection returned no identity evidence");
+    }
+    const expected = {
+        fileId: resolved.fileId,
+        pageId: resolved.pageId,
+    };
+    let observed = resolved.previousPageId;
+    for (let count = 0; count <= Math.ceil(timeout / 100); count++) {
+        commandSignal()?.throwIfAborted();
+        // During a requested transition either the old or selected page is legitimate.
+        const current = await runSnippet(client, snippet("page-switch-observation", "return {ok:true,fileId:penpot.currentFile.id,pageId:penpot.currentPage.id};", {}, "read"), execute());
+        if (current.fileId !== expected.fileId) {
+            throw new Error("File changed during page switch");
+        }
+        observed = String(current.pageId);
+        if (Date.now() >= deadline) {
+            break;
+        }
+        if (observed === expected.pageId) {
+            rememberPage(client, expected);
+            return expected;
+        }
+        if (observed !== resolved.previousPageId) {
+            throw new Error(`Unexpected external navigation during page switch: expected ${expected.pageId}, observed ${observed}`);
+        }
+        if (Date.now() >= deadline) {
+            break;
+        }
+        await (options.sleep ?? commandSleep)(Math.min(100, Math.max(0, deadline - Date.now())));
+    }
+    throw new Error(`Page switch timed out: expected ${expected.pageId}, observed ${observed}, stage=observe-page`);
+}

package/dist/png.d.ts

@@ -0,0 +1,5 @@
+/** Pixel size from a PNG's header (the IHDR chunk), or nothing when the bytes are not a PNG. */
+export declare function pngSize(buffer: Buffer): {
+    width: number;
+    height: number;
+} | undefined;

package/dist/png.js

@@ -0,0 +1,22 @@
+/** 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),
+    };
+}

package/dist/portable-tokens.d.ts

@@ -0,0 +1,22 @@
+/** Deliberately bounded subset of the published DTCG 2025.10 format; no Penpot arithmetic or native writes. */
+export interface PortableToken {
+    path: string[];
+    type: string;
+    value: unknown;
+    description?: string;
+    extensions?: unknown;
+}
+export interface PortableTokens {
+    schemaVersion: 1;
+    kind: "portable-tokens";
+    format: "dtcg-2025.10-subset";
+    tokens: PortableToken[];
+    groups: Record<string, {
+        type?: string;
+        description?: string;
+        extensions?: unknown;
+    }>;
+    losses: string[];
+}
+export declare function importDtcg(raw: unknown): PortableTokens;
+export declare function exportDtcg(raw: unknown): Record<string, unknown>;