@penpair/core 0.1.3 → 0.2.0

package/dist/journal.js

@@ -0,0 +1,260 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { redactEndpoint } from "./endpoint.js";
+import { ensureGitignoreEntry } from "./instance/gitignore.js";
+import { version } from "./version.js";
+import { runSnippet, snippet } from "./snippet.js";
+export async function readJournalTarget(client) {
+    const result = await runSnippet(client, snippet("journal-target", "return { ok: true, fileId: penpot.currentFile.id, revision: penpot.currentFile.revn };", {}, "read"));
+    if (result.ok !== true || typeof result.fileId !== "string" || !result.fileId || !Number.isInteger(result.revision))
+        throw new Error("Journal target identity/revision was not observed");
+    return { fileId: result.fileId, revision: Number(result.revision) };
+}
+/** Stable JSON hashing; observation comparisons may explicitly ignore transport execution metadata. */
+export function observationHash(value, ignoreExecution = false) {
+    const canonical = (entry) => {
+        if (Array.isArray(entry))
+            return entry.map(canonical);
+        if (typeof entry !== "object" || entry === null)
+            return entry;
+        return Object.fromEntries(Object.entries(entry).filter(([key]) => !ignoreExecution || key !== "execution").sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => [key, canonical(child)]));
+    };
+    return createHash("sha256").update(JSON.stringify(canonical(value)) ?? "null").digest("hex");
+}
+function validateRunId(runId) {
+    if (!/^[a-zA-Z0-9-]{1,100}$/.test(runId))
+        throw new Error("Run ID must contain only letters, digits and hyphens (at most 100)");
+}
+async function folder(root, create) {
+    if (create)
+        await ensureGitignoreEntry(root, ".penpair", { directory: true, comment: "penpair: private local operations and recovery evidence" });
+    let current = root;
+    for (const segment of [".penpair", "runs"]) {
+        current = path.join(current, segment);
+        try {
+            const info = await lstat(current);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error("Operation journal directories must be real directories inside this project");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (create)
+                await mkdir(current, { mode: 0o700 });
+        }
+    }
+    return current;
+}
+export async function readJournal(root, runId) {
+    validateRunId(runId);
+    const file = path.join(await folder(root, false), `${runId}.json`);
+    const info = await lstat(file);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error("Operation journal must be a regular local file");
+    const record = JSON.parse(await readFile(file, "utf8"));
+    if (record.schemaVersion !== 1 || record.runId !== runId || typeof record.operation !== "string" || !Array.isArray(record.steps) || !record.target || typeof record.target.fileId !== "string")
+        throw new Error("Operation journal is invalid or uses an unsupported schema");
+    return record;
+}
+export async function listJournals(root) {
+    let files;
+    try {
+        files = await readdir(await folder(root, false));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const records = await Promise.all(files.filter((name) => /^[a-zA-Z0-9-]+\.json$/.test(name)).map((name) => readJournal(root, name.slice(0, -5))));
+    return records.map(({ runId, operation, state, target, updatedAt }) => ({ runId, operation, state, target, updatedAt })).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+export class JournalRunError extends Error {
+    runId;
+    outcome;
+    constructor(runId, outcome, message) {
+        super(`Run ${runId} is ${outcome}: ${message}. Inspect \`penpair runs ${runId}\` before explicitly resuming.`);
+        this.runId = runId;
+        this.outcome = outcome;
+    }
+}
+/** Each started phase is persisted before its write. Resume must inspect and reconcile actual state, never replay blindly. */
+export async function runJournaledSteps(steps, options) {
+    if (options.requireCheckpoint && !options.checkpoint)
+        throw new Error("A required checkpoint needs a checkpoint provider");
+    const runId = options.runId ?? randomUUID();
+    validateRunId(runId);
+    const redact = (text) => redactEndpoint(options.redact?.(text) ?? text);
+    const directory = await folder(options.root, true);
+    const destination = path.join(directory, `${runId}.json`);
+    const target = await options.target();
+    if (!target || typeof target.fileId !== "string" || !target.fileId)
+        throw new Error("Operation journal requires an observed file ID");
+    const inputHash = observationHash({ input: options.input, requireCheckpoint: options.requireCheckpoint === true, checkpointRequested: Boolean(options.checkpoint) });
+    const planHash = observationHash({ steps: steps.map(({ key, signature }) => ({ key, signature })), finalVerifier: options.finalVerify?.toString() });
+    if (new Set(steps.map((step) => step.key)).size !== steps.length)
+        throw new Error("Journal step keys must be unique");
+    let record;
+    if (options.resume) {
+        if (!options.runId)
+            throw new Error("Resume requires the original run ID");
+        record = await readJournal(options.root, runId);
+        if (record.redacted)
+            throw new Error("This journal required redaction and cannot be automatically resumed; inspect and make a fresh plan");
+        if (record.engineVersion !== version || record.operation !== options.operation || record.inputHash !== inputHash || record.planHash !== planHash || record.target.fileId !== target.fileId || record.steps.length !== steps.length)
+            throw new Error("Resume target, inputs, step implementation or engine version changed; no write was replayed");
+    }
+    else {
+        const before = [];
+        for (const step of steps)
+            before.push(step.initial === undefined ? await step.inspect() : step.initial);
+        const observed = await options.target();
+        if (observed.fileId !== target.fileId || (target.revision !== undefined && observed.revision !== target.revision))
+            throw new Error("File changed while planning; inspect again before starting a run");
+        const now = new Date().toISOString();
+        record = { schemaVersion: 1, engineVersion: version, runId, operation: options.operation, inputHash, planHash, payload: options.payload, target, state: "planned", createdAt: now, updatedAt: now, redacted: false, steps: steps.map((step, index) => ({ key: step.key, label: step.label, state: "pending", before: before[index] })) };
+    }
+    const persist = async (create = false) => {
+        record.updatedAt = new Date().toISOString();
+        const sanitize = (value) => {
+            if (typeof value === "string")
+                return redact(value);
+            if (Array.isArray(value))
+                return value.map(sanitize);
+            if (value && typeof value === "object")
+                return Object.fromEntries(Object.entries(value).map(([key, entry]) => [redact(key), sanitize(entry)]));
+            return value;
+        };
+        const serialize = () => JSON.stringify(sanitize(record), null, 2);
+        if (serialize() !== JSON.stringify(record, null, 2))
+            record.redacted = true;
+        const temporary = path.join(directory, `.${runId}-${randomUUID()}.tmp`);
+        await writeFile(temporary, `${serialize()}\n`, { flag: "wx", mode: 0o600 });
+        try {
+            if (create)
+                await link(temporary, destination);
+            else
+                await rename(temporary, destination);
+        }
+        finally {
+            await unlink(temporary).catch((error) => { if (error.code !== "ENOENT")
+                throw error; });
+        }
+    };
+    if (!options.resume)
+        await persist(true);
+    options.onStep?.(`operation run ${runId}`);
+    const assertTarget = async () => {
+        const actual = await options.target();
+        if (actual.fileId !== record.target.fileId)
+            throw new Error("The operation target file changed");
+        return actual;
+    };
+    let lease;
+    try {
+        lease = await options.coordinate?.(runId, target);
+        if (options.checkpoint && record.steps.every((step) => step.state === "pending") && record.checkpoint === undefined) {
+            record.state = "running";
+            await persist();
+            await assertTarget();
+            const checkpoint = await options.checkpoint(runId);
+            if (checkpoint.supported !== false && checkpoint.report?.verified !== true)
+                throw new Error("Checkpoint did not provide verified recovery evidence");
+            if (!checkpoint.supported && options.requireCheckpoint) {
+                record.state = "failed";
+                throw new Error("Required checkpoint API is unavailable; no operation step was applied");
+            }
+            record.checkpoint = checkpoint;
+            await persist();
+        }
+        for (let index = 0; index < steps.length; index++) {
+            const step = steps[index];
+            const saved = record.steps[index];
+            await lease?.check();
+            const beforeInspection = await assertTarget();
+            const current = await step.inspect();
+            const afterInspection = await assertTarget();
+            if (beforeInspection.revision !== afterInspection.revision) {
+                record.state = "conflict";
+                throw new Error("File revision changed during step inspection");
+            }
+            if (saved.state === "completed") {
+                if (!step.verify(current, saved.before, saved.result)) {
+                    record.state = "conflict";
+                    throw new Error(`Previously completed step ${step.label} no longer matches`);
+                }
+                continue;
+            }
+            const reconciliation = step.reconcile(saved.before, current, saved.result);
+            if (reconciliation === "conflict") {
+                record.state = "conflict";
+                throw new Error(`External or unexplained changes conflict with ${step.label}`);
+            }
+            if (reconciliation === "complete") {
+                if (!step.verify(current, saved.before, saved.result)) {
+                    record.state = "conflict";
+                    throw new Error(`Reconciliation lacks verification for ${step.label}`);
+                }
+                saved.state = "completed";
+                saved.after = current;
+                await persist();
+                continue;
+            }
+            saved.state = "started";
+            saved.targetBefore = afterInspection;
+            record.state = "running";
+            await persist();
+            options.onStep?.(step.label);
+            try {
+                const beforeApply = await assertTarget();
+                if (beforeApply.revision !== afterInspection.revision) {
+                    saved.state = "pending";
+                    record.state = "conflict";
+                    throw new Error("File revision changed after inspection; no step was replayed");
+                }
+                saved.result = await step.apply(current, beforeApply);
+                const after = await step.inspect();
+                saved.after = after;
+                if (!step.verify(after, saved.before, saved.result)) {
+                    saved.state = "failed";
+                    record.state = "failed";
+                    throw new Error(`Independent verification failed for ${step.label}`);
+                }
+                saved.targetAfter = await assertTarget();
+                saved.state = "completed";
+                await persist();
+            }
+            catch (error) {
+                if (saved.state === "started") {
+                    saved.state = "uncertain";
+                    record.state = "uncertain";
+                }
+                saved.error = redact(error instanceof Error ? error.message : String(error));
+                throw error;
+            }
+        }
+        if (options.finalVerify && !await options.finalVerify()) {
+            record.state = "failed";
+            throw new Error("Final operation verification failed");
+        }
+        record.state = "verified";
+        delete record.error;
+        await persist();
+        return readJournal(options.root, runId);
+    }
+    catch (error) {
+        record.error = redact(error instanceof Error ? error.message : String(error));
+        if (record.state === "planned" || record.state === "running")
+            record.state = "uncertain";
+        try {
+            await persist();
+        }
+        catch { /* The pre-write started marker remains the recovery authority when a later local save fails. */ }
+        throw new JournalRunError(runId, record.state, redact(error instanceof Error ? error.message : String(error)));
+    }
+    finally {
+        if (lease)
+            await lease.release().catch((error) => options.onStep?.(`Writer marker release needs inspection: ${redact(error instanceof Error ? error.message : String(error))}`));
+    }
+}

package/dist/kit-smoke.d.ts

@@ -0,0 +1,31 @@
+import type { PenpotToolClient } from "./client.js";
+import { type Operation, type OperationOptions } from "./operation.js";
+interface KitProbeParams {
+    tag: string;
+}
+export declare const kitSmokeOperation: Operation<KitProbeParams>;
+/** Opt-in scratch operation; uses existing active typed tokens and removes only its directly owned temporary root. */
+export declare function runKitSmoke(client: PenpotToolClient, root: string, options?: OperationOptions): Promise<import("./operation.js").OperationReport | {
+    preview: {
+        path: string;
+        bytes: number;
+        sha256: string;
+        visualApproval: boolean;
+    };
+    complete?: boolean;
+    redacted?: boolean;
+    layout?: import("./layout.js").LayoutResult;
+    journal?: {
+        runId: string;
+        state: string;
+    };
+    outcome: "inspected" | "verified" | "failed";
+    operation: string;
+    phase: "inspected" | "applied";
+    inspect: import("./snippet.js").SnippetResult;
+    apply?: import("./snippet.js").SnippetResult;
+    readback?: import("./snippet.js").SnippetResult;
+    problems: string[];
+    verified: boolean;
+}>;
+export {};

package/dist/kit-smoke.js

@@ -0,0 +1,83 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { kit } from "./kit.js";
+import { runOperation } from "./operation.js";
+import { snippet } from "./snippet.js";
+import { observationHash } from "./journal.js";
+import { atomicWriteFile } from "./atomic-output.js";
+import { resolveProjectOutput } from "./project-input.js";
+const snapshotBody = `
+const state=()=>{
+ const f=penpot.currentFile,p=penpot.currentPage,c=penpot.library.local.tokens,structure=[],stack=[p.root],seen=new Set();
+ while(stack.length){if(structure.length>=10000)throw new Error("Kit probe exceeds 10000 shapes");const shape=stack.pop();if(!shape.id||seen.has(shape.id)||![shape.x,shape.y,shape.width,shape.height].every(Number.isFinite))throw new Error("Incomplete kit-probe geometry");seen.add(shape.id);structure.push([shape.id,shape.type,shape.name||"",shape.x,shape.y,shape.width,shape.height,shape.tokens||{},shape.type==="text"?shape.characters:null]);for(const child of shape.children||[])stack.push(child);}
+ let count=0;const tokens=c.sets.map(set=>({id:set.id,name:set.name,active:!!set.active,tokens:set.active?set.tokens.map(token=>{if(++count>10000)throw new Error("Kit-probe token budget exceeded");return {name:token.name,type:token.type,value:token.value};}):[]}));
+ const themes=c.themes.map(theme=>({id:theme.id,group:theme.group,name:theme.name,active:!!theme.active}));
+ const result={fileId:f.id,pageId:p.id,structure,tokens,themes};if(JSON.stringify(result).length>30000)throw new Error("Kit probe needs a smaller scratch page/token context");return result;
+};`;
+export const kitSmokeOperation = {
+    name: "kit-smoke", page: () => undefined,
+    inspect: params => snippet("kit-smoke-inspect", `${snapshotBody}
+const current=state(),effective=new Map();for(const set of penpot.library.local.tokens.sets)if(set.active)for(const token of set.tokens)effective.set(token.name,token);
+const pick=type=>{const names=[...effective.values()].filter(token=>token.type===type).map(token=>token.name).sort();if(!names.length)throw new Error("Kit probe needs an active "+type+" token on its scratch file");return names[0];};
+if(penpot.currentPage.root.children.some(shape=>shape.name===CFG.tag))throw new Error("A prior kit-probe root needs inspection before another run");
+return {ok:true,readOnly:true,state:current,selected:{color:pick("color"),typo:pick("typography"),space:pick("spacing"),radius:pick("borderRadius")}};`, params, "read"),
+    apply: (params, inspected) => snippet("kit-smoke-apply", `${kit()}
+${snapshotBody}
+if(!CFG.expected||JSON.stringify(state())!==JSON.stringify(CFG.expected))throw new Error("Kit-probe source changed before mutation");
+let root=null,result={ok:true,built:false};
+try{
+ root=penpot.createBoard();root.name=CFG.tag;root.fills=[];root.x=200000;root.resize(300,180);
+ const card=pp.recipe("hello-card",root,{box:{name:"Hello card",w:240,gap:CFG.selected.space,pad:[CFG.selected.space,CFG.selected.space,CFG.selected.space,CFG.selected.space],stroke:CFG.selected.color,radius:CFG.selected.radius},text:{typo:CFG.selected.typo,color:CFG.selected.color},label:"Hello, card"});
+ const settled=await pp.flush({root});if(!settled.layout.stable)throw new Error("Kit did not settle");
+ const label=card.children.find(shape=>shape.type==="text");if(!label)throw new Error("Kit text was not observed");
+ const actual={text:label.characters,typography:(label.tokens||{}).typography,color:(label.tokens||{}).fill,space:(card.tokens||{}).rowGap,radius:(card.tokens||{}).borderRadiusTopLeft};
+ const first=await root.export({type:"png",scale:1});const layout=await pp.settle(root);if(!layout.stable)throw new Error("Kit export layout did not settle");const second=await root.export({type:"png",scale:1});
+ if(!first||!second||!second.length||second.length>2097152||first.length!==second.length||Array.from(first).some((value,index)=>value!==second[index]))throw new Error("Kit preview did not produce bounded matching renders");
+ let binary="";for(let index=0;index<second.length;index+=8192)binary+=String.fromCharCode.apply(null,second.subarray(index,index+8192));
+ result={ok:true,built:true,actual,geometry:{width:card.width,height:card.height},previewBase64:btoa(binary),previewLength:second.length,capture:{fileId:penpot.currentFile.id,pageId:penpot.currentPage.id,frameId:root.id,revision:penpot.currentFile.revn,penpotApiVersion:typeof penpot.version==="string"?penpot.version:null},layout:settled.layout};
+}catch(error){result.error=String(error&&error.message||error);}
+finally{if(root)try{root.remove();}catch(error){result.cleanupError=String(error&&error.message||error);}}
+return result;`, { ...params, expected: inspected?.state ?? null, selected: inspected?.selected ?? null }, "write"),
+    readback: () => snippet("kit-smoke-readback", `${snapshotBody}\nreturn {ok:true,readOnly:true,state:state()};`, {}, "read"),
+    verify({ inspect, apply, readback }) {
+        const selected = inspect.selected;
+        const problems = [];
+        if (!selected || apply.built !== true || apply.error || apply.cleanupError)
+            problems.push(`Kit example failed: ${apply.error ?? apply.cleanupError ?? "no observed build"}`);
+        if (!selected || observationHash(apply.actual) !== observationHash({ text: "Hello, card", typography: selected.typo, color: selected.color, space: selected.space, radius: selected.radius }))
+            problems.push("Kit example lacks matching independent text/binding observations");
+        const geometry = apply.geometry;
+        if (!geometry || typeof geometry.width !== "number" || !Number.isFinite(geometry.width) || geometry.width <= 0 || typeof geometry.height !== "number" || !Number.isFinite(geometry.height) || geometry.height <= 0)
+            problems.push("Kit example has no finite positive geometry");
+        if (!inspect.state || !readback.state || observationHash(inspect.state) !== observationHash(readback.state))
+            problems.push("Kit cleanup did not independently preserve the original page and token selection");
+        if (typeof apply.previewBase64 !== "string" || !Number.isInteger(apply.previewLength) || Number(apply.previewLength) < 1)
+            problems.push("Kit example has no stable preview evidence");
+        return problems;
+    },
+};
+/** Opt-in scratch operation; uses existing active typed tokens and removes only its directly owned temporary root. */
+export async function runKitSmoke(client, root, options = {}) {
+    const runId = options.journal?.runId ?? randomUUID();
+    const report = await runOperation(client, kitSmokeOperation, { tag: `_penpair-kit-${runId}` }, { ...options, journal: options.apply ? { ...options.journal, root, runId } : undefined });
+    const encoded = report.apply?.previewBase64;
+    if (report.apply)
+        delete report.apply.previewBase64;
+    if (!report.verified || !report.apply)
+        return report;
+    if (typeof encoded !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded))
+        throw new Error("Kit preview encoding is invalid");
+    const bytes = Buffer.from(encoded, "base64");
+    if (bytes.length !== report.apply.previewLength || bytes.length > 2097152)
+        throw new Error("Kit preview byte evidence is invalid");
+    const destination = await resolveProjectOutput(root, `.penpair/probes/kit-${runId}.png`);
+    await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+    const existing = await readFile(destination).catch((error) => { if (error.code !== "ENOENT")
+        throw error; return undefined; });
+    if (existing && !existing.equals(bytes))
+        throw new Error("Existing kit preview differs; previous evidence was preserved");
+    if (!existing)
+        await atomicWriteFile(destination, bytes, { mode: 0o600 });
+    return { ...report, preview: { path: destination, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex"), visualApproval: false } };
+}

package/dist/kit-source.d.ts

@@ -0,0 +1,2 @@
+/** Plain plugin-sandbox JavaScript. Inclusion defines helpers without touching the document. */
+export declare const coreKitSource: string;