@penpair/core 0.2.0 → 0.3.0

package/dist/run-file.js

@@ -8,93 +8,192 @@ import { normalize } from "./registry.js";
 import { runOnPage, runOperation } from "./operation.js";
 const digest = (value) => createHash("sha256").update(value).digest("hex");
 async function sourceFile(root, entry) {
-    if (!/\.m?js$/.test(entry))
+    if (!/\.m?js$/.test(entry)) {
         throw new Error("Plugin bodies must be .js or .mjs files; host imports and TypeScript transpilation are not performed");
+    }
     const target = await resolveProjectInput(root, entry);
     const handle = await open(target, "r");
     let body;
     try {
         const info = await handle.stat();
-        if (!info.isFile() || info.size > maxSnippetBytes)
+        if (!info.isFile() || info.size > maxSnippetBytes) {
             throw new Error("Script file exceeds the 90 KB input bound or is not a regular file");
+        }
         body = (await handle.readFile("utf8")).replace(/^\uFEFF/, "");
     }
     finally {
         await handle.close();
     }
-    if (body.includes("\0"))
+    if (body.includes("\0")) {
         throw new Error("Plugin script contains a NUL character");
+    }
     const header = body.trimStart().split(/\r?\n/)[0]?.trim();
     const declaration = header === "// penpair: read" ? "read" : header === "// penpair: write" ? "write" : "unknown";
     // The idempotency assertion must be in the initial comment block, before executable source.
     const comments = [];
     for (const line of body.trimStart().split(/\r?\n/)) {
-        if (!line.trim().startsWith("//"))
+        if (!line.trim().startsWith("//")) {
             break;
+        }
         comments.push(line.trim());
     }
-    return { file: path.relative(await realpath(root), target).split(path.sep).join("/"), sha256: digest(body), body, declaration, idempotent: comments.includes("// penpair: idempotent") };
+    return {
+        file: path
+            .relative(await realpath(root), target)
+            .split(path.sep)
+            .join("/"),
+        sha256: digest(body),
+        body,
+        declaration,
+        idempotent: comments.includes("// penpair: idempotent"),
+    };
 }
 function checked(value) {
     const error = compiles(value.code);
-    if (error)
+    if (error) {
         throw new Error(`${value.name}: invalid plugin body: ${error}`);
+    }
     return value;
 }
 /** Reads and compiles explicitly selected files without importing project modules on the host. */
 export async function prepareFileScript(root, file, options = {}) {
     const includes = options.include ?? [];
-    if (includes.length > 20 || new Set(includes).size !== includes.length)
+    if (includes.length > 20 || new Set(includes).size !== includes.length) {
         throw new Error("Use at most 20 distinct ordered includes");
+    }
     const params = options.params ?? {};
-    if (Object.keys(params).length > 100 || Object.keys(params).some(key => !/^[A-Za-z][A-Za-z0-9]*$/.test(key)))
+    if (Object.keys(params).length > 100 ||
+        Object.keys(params).some((key) => !/^[A-Za-z][A-Za-z0-9]*$/.test(key))) {
         throw new Error("Use at most 100 named parameters (letters followed by letters/digits)");
-    if (options.page && Object.hasOwn(params, "page"))
+    }
+    if (options.page && Object.hasOwn(params, "page")) {
         throw new Error("--page owns CFG.page; do not also pass --param page");
-    if (Object.hasOwn(params, "inspection"))
+    }
+    if (Object.hasOwn(params, "inspection")) {
         throw new Error("CFG.inspection is reserved for the independently captured write inspection");
+    }
     const helpers = [];
     for (const include of includes) {
         const virtual = options.virtualIncludes?.[include];
-        const helper = virtual === undefined ? await sourceFile(root, include) : { file: include, body: virtual, sha256: digest(virtual), declaration: virtual.startsWith("// penpair: read\n") ? "read" : "unknown", idempotent: false };
-        if (helper.declaration !== "read")
+        const helper = virtual === undefined
+            ? await sourceFile(root, include)
+            : {
+                file: include,
+                body: virtual,
+                sha256: digest(virtual),
+                declaration: virtual.startsWith("// penpair: read\n") ? "read" : "unknown",
+                idempotent: false,
+            };
+        if (helper.declaration !== "read") {
             throw new Error(`Include ${include} must declare // penpair: read for its top-level inclusion effects`);
+        }
         helpers.push(helper);
     }
     const main = await sourceFile(root, file);
-    const prelude = helpers.map(helper => `// Included helper\n${helper.body}\n`).join("\n");
-    const cfg = { ...params, ...(options.page ? { page: options.page } : {}) };
-    const build = (label, body, effect, inspected) => checked(snippet(label, `${requirePage}\n${prelude}\n${body}`, { ...cfg, ...(effect === "write" ? { inspection: inspected ?? null } : {}) }, effect));
+    const prelude = helpers.map((helper) => `// Included helper\n${helper.body}\n`).join("\n");
+    const cfg = {
+        ...params,
+        ...(options.page
+            ? {
+                page: options.page,
+            }
+            : {}),
+    };
+    const build = (label, body, effect, inspected) => checked(snippet(label, `${requirePage}\n${prelude}\n${body}`, {
+        ...cfg,
+        ...(effect === "write"
+            ? {
+                inspection: inspected ?? null,
+            }
+            : {}),
+    }, effect));
     if (main.declaration === "read") {
-        if (options.inspect || options.readback)
+        if (options.inspect || options.readback) {
             throw new Error("Read scripts do not take write inspect/readback phases");
-        return { kind: "read", source: [...helpers, main].map(({ file, sha256 }) => ({ file, sha256 })), params: cfg, page: options.page, read: build("run-file-read", main.body, "read") };
+        }
+        return {
+            kind: "read",
+            source: [
+                ...helpers,
+                main,
+            ].map(({ file, sha256 }) => ({
+                file,
+                sha256,
+            })),
+            params: cfg,
+            page: options.page,
+            read: build("run-file-read", main.body, "read"),
+        };
     }
-    if (main.declaration !== "write" || !main.idempotent || !options.inspect || !options.readback)
+    if (main.declaration !== "write" || !main.idempotent || !options.inspect || !options.readback) {
         throw new Error("Write script execution requires // penpair: write, // penpair: idempotent, and explicit --inspect/--readback files. Declarations are trusted code contracts, not a sandbox.");
-    const inspect = await sourceFile(root, options.inspect), readback = await sourceFile(root, options.readback);
-    if (inspect.declaration !== "read" || readback.declaration !== "read")
+    }
+    const inspect = await sourceFile(root, options.inspect);
+    const readback = await sourceFile(root, options.readback);
+    if (inspect.declaration !== "read" || readback.declaration !== "read") {
         throw new Error("Inspection and readback files must declare // penpair: read");
+    }
     // Reuse the registry's positive evidence verifier; never equate an acknowledgment with a verified write.
-    const normalized = normalize({ name: "run-file", description: "Explicitly selected reviewed file operation", kind: "write", inspect: inspect.body, apply: main.body, readback: readback.body }, "project");
-    const operation = { ...normalized.operation, page: () => options.page,
+    const normalized = normalize({
+        name: "run-file",
+        description: "Explicitly selected reviewed file operation",
+        kind: "write",
+        inspect: inspect.body,
+        apply: main.body,
+        readback: readback.body,
+    }, "project");
+    const operation = {
+        ...normalized.operation,
+        page: () => options.page,
         inspect: () => build("run-file-inspect", inspect.body, "read"),
         apply: (_params, inspected) => build("run-file-apply", main.body, "write", inspected),
-        readback: () => build("run-file-readback", readback.body, "read"), };
+        readback: () => build("run-file-readback", readback.body, "read"),
+    };
     operation.inspect({});
     operation.apply({});
     operation.readback({});
-    return { kind: "write", source: [...helpers, main, inspect, readback].map(({ file, sha256 }) => ({ file, sha256 })), params: cfg, page: options.page, operation };
+    return {
+        kind: "write",
+        source: [
+            ...helpers,
+            main,
+            inspect,
+            readback,
+        ].map(({ file, sha256 }) => ({
+            file,
+            sha256,
+        })),
+        params: cfg,
+        page: options.page,
+        operation,
+    };
 }
 export async function runFileScript(client, prepared, options = {}) {
     if (prepared.kind === "read") {
-        if (options.apply || options.journal)
+        if (options.apply || options.journal) {
             throw new Error("Read files do not accept apply or write recovery options");
-        const result = await runOnPage(client, prepared.read, prepared.page, { ...options, effect: "read", retries: 0 });
-        if (result.ok !== true)
+        }
+        const result = await runOnPage(client, prepared.read, prepared.page, {
+            ...options,
+            effect: "read",
+            retries: 0,
+        });
+        if (result.ok !== true) {
             throw new Error("Read script returned no explicit ok acknowledgment");
-        return { phase: "read", kind: "declared-read", source: prepared.source, data: result };
+        }
+        return {
+            phase: "read",
+            kind: "declared-read",
+            source: prepared.source,
+            data: result,
+        };
     }
-    const report = await runOperation(client, prepared.operation, { parameters: prepared.params, sourceFiles: prepared.source }, options);
-    return { ...report, source: prepared.source };
+    const report = await runOperation(client, prepared.operation, {
+        parameters: prepared.params,
+        sourceFiles: prepared.source,
+    }, options);
+    return {
+        ...report,
+        source: prepared.source,
+    };
 }

package/dist/shots.js

@@ -12,8 +12,9 @@ import { pngSize } from "./baselines.js";
 import { observationHash } from "./journal.js";
 /** Exact names across the selected page. A match never silently resolves an ambiguity. */
 export async function findShapesByName(client, name, page, options = {}) {
-    if (!name || !page)
+    if (!name || !page) {
         throw new Error("Name lookup requires an exact name and explicit page");
+    }
     const result = await runOnPage(client, snippet("find-shape-name", `${requirePage}
 const matches = [], stack = [...penpot.currentPage.root.children]; let visited = 0;
 while (stack.length && visited < 10000) {
@@ -21,54 +22,127 @@ while (stack.length && visited < 10000) {
   if (shape.name === CFG.name) matches.push({id:shape.id,name:shape.name,type:shape.type});
   for (const child of shape.children || []) stack.push(child);
 }
-return {ok:true,fileId:penpot.currentFile.id,pageId:penpot.currentPage.id,revision:penpot.currentFile.revn,matches,truncated:stack.length>0};`, { name, page }, "read"), page, options);
-    if (result.truncated)
+return {ok:true,fileId:penpot.currentFile.id,pageId:penpot.currentPage.id,revision:penpot.currentFile.revn,matches,truncated:stack.length>0};`, {
+        name,
+        page,
+    }, "read"), page, options);
+    if (result.truncated) {
         throw new PenpairError("incomplete-output", "Shape name search exceeded 10000 nodes; narrow the page");
-    if (result.ok !== true || typeof result.truncated !== "boolean" || typeof result.fileId !== "string" || !result.fileId || typeof result.pageId !== "string" || !result.pageId || !Number.isInteger(result.revision) || !Array.isArray(result.matches) || result.matches.some((match) => !match || typeof match.id !== "string" || typeof match.name !== "string" || typeof match.type !== "string"))
+    }
+    if (result.ok !== true ||
+        typeof result.truncated !== "boolean" ||
+        typeof result.fileId !== "string" ||
+        !result.fileId ||
+        typeof result.pageId !== "string" ||
+        !result.pageId ||
+        !Number.isInteger(result.revision) ||
+        !Array.isArray(result.matches) ||
+        result.matches.some((match) => !match ||
+            typeof match.id !== "string" ||
+            typeof match.name !== "string" ||
+            typeof match.type !== "string")) {
         throw new Error("Shape search returned incomplete identity evidence");
+    }
     return result;
 }
 export async function exportShapeByName(client, name, page, options = {}) {
     const lookup = await findShapesByName(client, name, page, options);
-    if (lookup.matches.length !== 1)
+    if (lookup.matches.length !== 1) {
         throw new Error(`Exact name ${JSON.stringify(name)} matched ${lookup.matches.length} shapes on ${JSON.stringify(page)}. Candidates: ${JSON.stringify(lookup.matches.slice(0, 20))}. Use an ID for an ambiguous name.`);
-    const result = await exportShapePng(client, lookup.matches[0].id, { ...options, page });
-    if (result.capture.fileId !== lookup.fileId || result.capture.pageId !== lookup.pageId || result.capture.revision !== lookup.revision)
+    }
+    const result = await exportShapePng(client, lookup.matches[0].id, {
+        ...options,
+        page,
+    });
+    if (result.capture.fileId !== lookup.fileId ||
+        result.capture.pageId !== lookup.pageId ||
+        result.capture.revision !== lookup.revision) {
         throw new Error("Named export source changed after lookup; no output was published");
+    }
     return result;
 }
 /** Ad-hoc captures use immutable generations, but never carry baseline approval records. */
 export async function captureShots(client, root, params, options = {}) {
-    const listing = await runOnPage(client, frames({ page: params.page }), params.page, options);
-    if (typeof listing.fileId !== "string" || typeof listing.pageId !== "string" || !Number.isInteger(listing.revn) || !Array.isArray(listing.frames))
+    const listing = await runOnPage(client, frames({
+        page: params.page,
+    }), params.page, options);
+    if (typeof listing.fileId !== "string" ||
+        typeof listing.pageId !== "string" ||
+        !Number.isInteger(listing.revn) ||
+        !Array.isArray(listing.frames)) {
         throw new Error("Shots listing lacks identity/revision evidence");
+    }
     const selected = listing.frames.filter((frame) => !params.prefix || frame.name.startsWith(params.prefix));
-    const report = { schemaVersion: 1, complete: false, fileId: listing.fileId, pageId: listing.pageId, revision: Number(listing.revn), captures: [], wrote: [] };
-    if (!selected.length || selected.length > 100)
-        return { ...report, reason: !selected.length ? "No matching top-level frames" : "More than 100 frames; narrow the prefix" };
+    const report = {
+        schemaVersion: 1,
+        complete: false,
+        fileId: listing.fileId,
+        pageId: listing.pageId,
+        revision: Number(listing.revn),
+        captures: [],
+        wrote: [],
+    };
+    if (!selected.length || selected.length > 100) {
+        return {
+            ...report,
+            reason: !selected.length
+                ? "No matching top-level frames"
+                : "More than 100 frames; narrow the prefix",
+        };
+    }
     const folder = await resolveProjectOutput(root, params.out ?? "design/shots");
-    const runId = randomUUID(), generation = `captures/${runId}`;
+    const runId = randomUUID();
+    const generation = `captures/${runId}`;
     const images = [];
     for (const [index, frame] of selected.entries()) {
         options.signal?.throwIfAborted();
         options.onStep?.(`exporting ${JSON.stringify(frame.name)}`);
-        const result = await exportShapePng(client, frame.id, { ...options, page: params.page, stable: true });
-        if (!result.stable)
-            return { ...report, reason: "A frame did not stabilize; no output was published" };
-        if (result.capture.fileId !== report.fileId || result.capture.pageId !== report.pageId || result.capture.revision !== report.revision)
+        const result = await exportShapePng(client, frame.id, {
+            ...options,
+            page: params.page,
+            stable: true,
+        });
+        if (!result.stable) {
+            return {
+                ...report,
+                reason: "A frame did not stabilize; no output was published",
+            };
+        }
+        if (result.capture.fileId !== report.fileId ||
+            result.capture.pageId !== report.pageId ||
+            result.capture.revision !== report.revision) {
             throw new Error("Shots source changed during capture; no output was published");
+        }
         const size = pngSize(result.png);
-        if (!size || size.width <= 0 || size.height <= 0)
+        if (!size || size.width <= 0 || size.height <= 0) {
             throw new Error("Shot export is missing valid PNG dimensions");
-        report.captures.push({ layout: result.layout, ...size, name: frame.name, file: `${generation}/shot-${String(index + 1).padStart(4, "0")}.png`, sha256: createHash("sha256").update(result.png).digest("hex"), capture: result.capture });
+        }
+        report.captures.push({
+            layout: result.layout,
+            ...size,
+            name: frame.name,
+            file: `${generation}/shot-${String(index + 1).padStart(4, "0")}.png`,
+            sha256: createHash("sha256").update(result.png).digest("hex"),
+            capture: result.capture,
+        });
         images.push(result.png);
     }
-    const after = await runOnPage(client, frames({ page: params.page }), params.page, options);
-    const identity = (entry) => ({ fileId: entry.fileId, pageId: entry.pageId, revision: entry.revn, frames: entry.frames });
-    if (observationHash(identity(listing)) !== observationHash(identity(after)))
+    const after = await runOnPage(client, frames({
+        page: params.page,
+    }), params.page, options);
+    const identity = (entry) => ({
+        fileId: entry.fileId,
+        pageId: entry.pageId,
+        revision: entry.revn,
+        frames: entry.frames,
+    });
+    if (observationHash(identity(listing)) !== observationHash(identity(after))) {
         throw new Error("Shots source changed before publication; previous output was preserved");
+    }
     options.signal?.throwIfAborted();
-    await mkdir(path.join(folder, "captures"), { recursive: true });
+    await mkdir(path.join(folder, "captures"), {
+        recursive: true,
+    });
     const staged = path.join(folder, `.stage-${runId}`);
     await mkdir(staged);
     try {
@@ -80,11 +154,19 @@ export async function captureShots(client, root, params, options = {}) {
         await rename(staged, path.join(folder, generation));
         options.signal?.throwIfAborted();
         report.complete = true;
-        report.wrote = [...report.captures.map((entry) => entry.file), "penpair-shots.json"];
-        await atomicWriteFile(path.join(folder, "penpair-shots.json"), `${JSON.stringify(report, null, 2)}\n`, { replace: true });
+        report.wrote = [
+            ...report.captures.map((entry) => entry.file),
+            "penpair-shots.json",
+        ];
+        await atomicWriteFile(path.join(folder, "penpair-shots.json"), `${JSON.stringify(report, null, 2)}\n`, {
+            replace: true,
+        });
         return report;
     }
     finally {
-        await rm(staged, { recursive: true, force: true });
+        await rm(staged, {
+            recursive: true,
+            force: true,
+        });
     }
 }

package/dist/skill-instructions.js

@@ -2,15 +2,17 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { resolveProjectOutput } from "./project-input.js";
 import { atomicWriteFile } from "./atomic-output.js";
-const start = "<!-- penpair:skills:start -->", end = "<!-- penpair:skills:end -->";
+const start = "<!-- penpair:skills:start -->";
+const end = "<!-- penpair:skills:end -->";
 async function exists(file) {
     try {
         await lstat(file);
         return true;
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return false;
+        }
         throw error;
     }
 }
@@ -18,11 +20,23 @@ export async function planSkillInstructions(root, rows, destination) {
     let selected = destination;
     if (!selected) {
         const candidates = [];
-        for (const name of ["AGENTS.md", "CLAUDE.md"])
-            if (await exists(path.join(root, name)))
+        for (const name of [
+            "AGENTS.md",
+            "CLAUDE.md",
+        ]) {
+            if (await exists(path.join(root, name))) {
                 candidates.push(name);
-        if (candidates.length !== 1)
-            return { report: { path: null, status: candidates.length ? "choice-required" : "not-selected", diff: "" } };
+            }
+        }
+        if (candidates.length !== 1) {
+            return {
+                report: {
+                    path: null,
+                    status: candidates.length ? "choice-required" : "not-selected",
+                    diff: "",
+                },
+            };
+        }
         selected = candidates[0];
     }
     const canonicalRoot = await realpath(root);
@@ -32,44 +46,99 @@ export async function planSkillInstructions(root, rows, destination) {
         before = await readFile(file, "utf8");
     }
     catch (error) {
-        if (error.code !== "ENOENT")
+        if (error.code !== "ENOENT") {
             throw error;
+        }
     }
     const text = before ?? "";
-    const starts = text.split(start).length - 1, ends = text.split(end).length - 1;
-    if (starts !== ends || starts > 1 || starts === 1 && text.indexOf(start) > text.indexOf(end))
+    const starts = text.split(start).length - 1;
+    const ends = text.split(end).length - 1;
+    if (starts !== ends || starts > 1 || (starts === 1 && text.indexOf(start) > text.indexOf(end))) {
         throw new Error("Malformed penpair skills markers; repair them before installation (no instruction text was changed)");
+    }
     const newline = text.includes("\r\n") ? "\r\n" : "\n";
     const relativeRows = rows.map((row) => row.replace(/\]\(([^)]+)\)/g, (_match, target) => {
-        const relative = path.relative(path.dirname(file), path.resolve(canonicalRoot, decodeURIComponent(target))).split(path.sep).join("/");
-        const link = relative.split("/").map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`)).join("/");
+        const relative = path
+            .relative(path.dirname(file), path.resolve(canonicalRoot, decodeURIComponent(target)))
+            .split(path.sep)
+            .join("/");
+        const link = relative
+            .split("/")
+            .map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`))
+            .join("/");
         return `](${link})`;
     }));
-    const block = [start, "| Skill | Purpose |", "| --- | --- |", ...relativeRows, end].join(newline);
+    const block = [
+        start,
+        "| Skill | Purpose |",
+        "| --- | --- |",
+        ...relativeRows,
+        end,
+    ].join(newline);
     let after;
-    if (starts === 1)
+    if (starts === 1) {
         after = text.slice(0, text.indexOf(start)) + block + text.slice(text.indexOf(end) + end.length);
-    else
-        after = text + (text ? text.endsWith(newline) ? newline : newline + newline : "") + "## Penpair skills" + newline + newline + block + newline;
+    }
+    else {
+        after =
+            text +
+                (text ? (text.endsWith(newline) ? newline : newline + newline) : "") +
+                "## Penpair skills" +
+                newline +
+                newline +
+                block +
+                newline;
+    }
     const changed = text !== after;
     // Diff only the owned region, never repeat unrelated instruction content in reports.
     const oldBlock = starts ? text.slice(text.indexOf(start), text.indexOf(end) + end.length) : "";
-    const diff = changed ? [`--- ${file}`, `+++ ${file}`, "@@ penpair-owned skills block @@", ...oldBlock.split(/\r?\n/).filter(Boolean).map((line) => `-${line}`), ...(starts ? block : "## Penpair skills" + newline + newline + block).split(/\r?\n/).map((line) => `+${line}`)].join("\n") : "";
-    return { before, after, mode: before === undefined ? 0o644 : (await lstat(file)).mode & 0o777, report: { path: file, status: changed ? "preview" : "unchanged", diff } };
+    const diff = changed
+        ? [
+            `--- ${file}`,
+            `+++ ${file}`,
+            "@@ penpair-owned skills block @@",
+            ...oldBlock
+                .split(/\r?\n/)
+                .filter(Boolean)
+                .map((line) => `-${line}`),
+            ...(starts ? block : "## Penpair skills" + newline + newline + block)
+                .split(/\r?\n/)
+                .map((line) => `+${line}`),
+        ].join("\n")
+        : "";
+    return {
+        before,
+        after,
+        mode: before === undefined ? 0o644 : (await lstat(file)).mode & 0o777,
+        report: {
+            path: file,
+            status: changed ? "preview" : "unchanged",
+            diff,
+        },
+    };
 }
 export async function applySkillInstructions(plan) {
-    if (plan.report.status !== "preview" || !plan.report.path || plan.after === undefined)
+    if (plan.report.status !== "preview" || !plan.report.path || plan.after === undefined) {
         return plan.report;
+    }
     let current;
     try {
         current = await readFile(plan.report.path, "utf8");
     }
     catch (error) {
-        if (error.code !== "ENOENT")
+        if (error.code !== "ENOENT") {
             throw error;
+        }
     }
-    if (current !== plan.before)
+    if (current !== plan.before) {
         throw new Error("Instruction file changed after planning; nothing was overwritten");
-    await atomicWriteFile(plan.report.path, plan.after, { replace: plan.before !== undefined, mode: plan.mode });
-    return { ...plan.report, status: "written" };
+    }
+    await atomicWriteFile(plan.report.path, plan.after, {
+        replace: plan.before !== undefined,
+        mode: plan.mode,
+    });
+    return {
+        ...plan.report,
+        status: "written",
+    };
 }