@penpair/core 0.2.0 → 0.3.0

package/dist/skills.js

@@ -1,25 +1,37 @@
 import { atomicWriteFile } from "./atomic-output.js";
 import { resolveProjectOutput } from "./project-input.js";
-import { planSkillInstructions, applySkillInstructions } from "./skill-instructions.js";
+import { planSkillInstructions, applySkillInstructions, } from "./skill-instructions.js";
 import { lstat, mkdir, readdir, readFile, symlink } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 /** The skills shipped inside the package (`skills/` next to `dist/`). */
 export const bundledSkillsDirectory = () => path.join(path.dirname(fileURLToPath(import.meta.url)), "../skills");
 /** Files a project fills in. They are written once and never replaced, not even with --force. */
-const projectOwned = new Set(["references/project-facts.md", "PROJECT.md"]);
+const projectOwned = new Set([
+    "references/project-facts.md",
+    "PROJECT.md",
+]);
 export async function listBundledSkills(directory = bundledSkillsDirectory()) {
-    const entries = await readdir(directory, { withFileTypes: true });
-    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    const entries = await readdir(directory, {
+        withFileTypes: true,
+    });
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
 }
 async function filesUnder(directory, prefix = "") {
     const out = [];
-    for (const entry of await readdir(path.join(directory, prefix), { withFileTypes: true })) {
+    for (const entry of await readdir(path.join(directory, prefix), {
+        withFileTypes: true,
+    })) {
         const relative = path.posix.join(prefix, entry.name);
-        if (entry.isDirectory())
+        if (entry.isDirectory()) {
             out.push(...(await filesUnder(directory, relative)));
-        else
+        }
+        else {
             out.push(relative);
+        }
     }
     return out.sort();
 }
@@ -28,8 +40,9 @@ async function readIfExists(file) {
         return await readFile(file, "utf8");
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return undefined;
+        }
         throw error;
     }
 }
@@ -39,8 +52,9 @@ async function exists(file) {
         return true;
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (error.code === "ENOENT") {
             return false;
+        }
         throw error;
     }
 }
@@ -49,17 +63,31 @@ export async function describeSkill(skillDirectory) {
     const text = (await readIfExists(path.join(skillDirectory, "SKILL.md"))) ?? "";
     const name = /^name:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? path.basename(skillDirectory);
     const description = /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
-    return { name, summary: description.split(/(?<=\.)\s/)[0] ?? description };
+    return {
+        name,
+        summary: description.split(/(?<=\.)\s/)[0] ?? description,
+    };
 }
 /** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
-export const renamedSkills = { "penpot-design": "penpair-design" };
+export const renamedSkills = {
+    "penpot-design": "penpair-design",
+};
 /** Where the penpair skills already live in a project as real folders (not links), so a later install goes to the same place. */
 export async function existingSkillsFolder(root) {
-    for (const folder of [".skills", ".claude/skills", ".agents/skills"]) {
-        for (const name of ["penpair-design", "penpair-setup", ...Object.keys(renamedSkills)]) {
+    for (const folder of [
+        ".skills",
+        ".claude/skills",
+        ".agents/skills",
+    ]) {
+        for (const name of [
+            "penpair-design",
+            "penpair-setup",
+            ...Object.keys(renamedSkills),
+        ]) {
             const found = await lstat(path.join(root, folder, name)).catch(() => undefined);
-            if (found?.isDirectory())
+            if (found?.isDirectory()) {
                 return folder;
+            }
         }
     }
     return undefined;
@@ -70,16 +98,38 @@ export async function installSkills(options) {
     await resolveProjectOutput(options.root, to);
     const names = await listBundledSkills(source);
     const chosen = options.only ?? names;
-    for (const name of chosen)
-        if (!names.includes(name))
+    for (const name of chosen) {
+        if (!names.includes(name)) {
             throw new Error(`no skill named ${name}; shipped: ${names.join(", ")}`);
+        }
+    }
     const rows = await Promise.all(chosen.map(async (name) => {
         const { summary } = await describeSkill(path.join(source, name));
-        const link = path.posix.join(to, name, "SKILL.md").split("/").map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`)).join("/");
+        const link = path.posix
+            .join(to, name, "SKILL.md")
+            .split("/")
+            .map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`))
+            .join("/");
         return `| [${name}](${link}) | ${summary.replace(/\|/g, "\\|")} |`;
     }));
     const instructionPlan = await planSkillInstructions(options.root, rows, options.agents);
-    const report = { to, installed: [], unchanged: [], kept: [], linked: [], agentsRows: rows, legacy: [], instructions: instructionPlan.report, ...(options.dryRun ? { dryRun: true, wouldInstall: [], wouldLink: [] } : {}) };
+    const report = {
+        to,
+        installed: [],
+        unchanged: [],
+        kept: [],
+        linked: [],
+        agentsRows: rows,
+        legacy: [],
+        instructions: instructionPlan.report,
+        ...(options.dryRun
+            ? {
+                dryRun: true,
+                wouldInstall: [],
+                wouldLink: [],
+            }
+            : {}),
+    };
     const writes = new Map();
     const links = [];
     for (const name of chosen) {
@@ -89,56 +139,96 @@ export async function installSkills(options) {
             const shipped = await readFile(path.join(from, file), "utf8");
             const present = await readIfExists(target);
             const label = path.posix.join(to, name, file);
-            if (present === shipped)
+            if (present === shipped) {
                 report.unchanged.push(label);
-            else if (present === undefined || options.force && !projectOwned.has(file))
-                writes.set(target, { label, before: present, content: shipped });
-            else
+            }
+            else if (present === undefined || (options.force && !projectOwned.has(file))) {
+                writes.set(target, {
+                    label,
+                    before: present,
+                    content: shipped,
+                });
+            }
+            else {
                 report.kept.push(label);
+            }
         }
-        if (options.links !== false)
-            for (const hub of [".agents/skills", ".claude/skills"]) {
+        if (options.links !== false) {
+            for (const hub of [
+                ".agents/skills",
+                ".claude/skills",
+            ]) {
                 const link = path.join(options.root, hub, name);
-                if (path.resolve(link) === path.resolve(options.root, to, name) || await exists(link))
+                if (path.resolve(link) === path.resolve(options.root, to, name) || (await exists(link))) {
                     continue;
+                }
                 const safe = await resolveProjectOutput(options.root, path.join(hub, name));
                 const target = await resolveProjectOutput(options.root, path.join(to, name));
-                if (safe === target)
+                if (safe === target) {
                     continue;
-                links.push({ file: safe, target: path.relative(path.dirname(safe), target), label: path.posix.join(hub, name) });
+                }
+                links.push({
+                    file: safe,
+                    target: path.relative(path.dirname(safe), target),
+                    label: path.posix.join(hub, name),
+                });
             }
+        }
     }
     for (const [oldName, newName] of Object.entries(renamedSkills)) {
-        if (!chosen.includes(newName) || !(await exists(path.join(options.root, to, oldName))))
+        if (!chosen.includes(newName) || !(await exists(path.join(options.root, to, oldName)))) {
             continue;
+        }
         const oldFacts = await readIfExists(await resolveProjectOutput(options.root, path.join(to, oldName, "references/project-facts.md")));
         const newFactsFile = await resolveProjectOutput(options.root, path.join(to, newName, "references/project-facts.md"));
         const template = await readIfExists(path.join(source, newName, "references/project-facts.md"));
-        const current = writes.get(newFactsFile)?.content ?? await readIfExists(newFactsFile);
+        const current = writes.get(newFactsFile)?.content ?? (await readIfExists(newFactsFile));
         const carriedFacts = oldFacts !== undefined && oldFacts !== template && current === template;
-        if (carriedFacts)
-            writes.set(newFactsFile, { label: path.posix.join(to, newName, "references/project-facts.md"), before: await readIfExists(newFactsFile), content: oldFacts });
-        report.legacy.push({ folder: path.posix.join(to, oldName), renamedTo: newName, carriedFacts: carriedFacts && !options.dryRun });
+        if (carriedFacts) {
+            writes.set(newFactsFile, {
+                label: path.posix.join(to, newName, "references/project-facts.md"),
+                before: await readIfExists(newFactsFile),
+                content: oldFacts,
+            });
+        }
+        report.legacy.push({
+            folder: path.posix.join(to, oldName),
+            renamedTo: newName,
+            carriedFacts: carriedFacts && !options.dryRun,
+        });
     }
     if (options.dryRun) {
-        report.wouldInstall = [...writes.values()].map((write) => write.label);
+        report.wouldInstall = [
+            ...writes.values(),
+        ].map((write) => write.label);
         report.wouldLink = links.map((link) => link.label);
         return report;
     }
     for (const [file, write] of writes) {
-        if (await readIfExists(file) !== write.before)
+        if ((await readIfExists(file)) !== write.before) {
             throw new Error("A skill file changed after planning; nothing overwrote that file");
-        await mkdir(path.dirname(file), { recursive: true });
-        await atomicWriteFile(file, write.content, { replace: write.before !== undefined, mode: write.before === undefined ? 0o644 : (await lstat(file)).mode & 0o777 });
+        }
+        await mkdir(path.dirname(file), {
+            recursive: true,
+        });
+        await atomicWriteFile(file, write.content, {
+            replace: write.before !== undefined,
+            mode: write.before === undefined ? 0o644 : (await lstat(file)).mode & 0o777,
+        });
         report.installed.push(write.label);
     }
     for (const link of links) {
-        await mkdir(path.dirname(link.file), { recursive: true });
+        await mkdir(path.dirname(link.file), {
+            recursive: true,
+        });
         await symlink(link.target, link.file);
         report.linked.push(link.label);
     }
-    if (instructionPlan.report.path)
-        await mkdir(path.dirname(instructionPlan.report.path), { recursive: true });
+    if (instructionPlan.report.path) {
+        await mkdir(path.dirname(instructionPlan.report.path), {
+            recursive: true,
+        });
+    }
     report.instructions = await applySkillInstructions(instructionPlan);
     return report;
 }

package/dist/snippet.js

@@ -1,5 +1,5 @@
 import { Buffer } from "node:buffer";
-import { executeCode, maxSnippetBytes, UncertainExecutionError } from "./client.js";
+import { executeCode, maxSnippetBytes, UncertainExecutionError, } from "./client.js";
 import { PenpairError } from "./errors.js";
 /**
  * Wraps snippet body text for the Penpot editor: the parameters arrive as `CFG`, and any error comes back as
@@ -13,9 +13,14 @@ export const requirePage = `if (CFG.page && penpot.currentFile?.pages?.filter((p
 if (CFG.page && penpot.currentPage.name !== CFG.page) return { ok: false, wrongPage: true, current: penpot.currentPage.name, message: "the editor shows " + penpot.currentPage.name + ", not " + CFG.page };`;
 export function snippet(name, body, params = {}, effect = "unknown") {
     const code = wrap(body, params);
-    if (Buffer.byteLength(code, "utf8") > maxSnippetBytes)
+    if (Buffer.byteLength(code, "utf8") > maxSnippetBytes) {
         throw new PenpairError("snippet-too-large", `Snippet ${name} is ${Buffer.byteLength(code, "utf8")} bytes`);
-    return { name, code, effect };
+    }
+    return {
+        name,
+        code,
+        effect,
+    };
 }
 /** Whether the plugin source is valid JavaScript for an async function. Catches typos without a Penpot connection. */
 export function compiles(code) {
@@ -30,12 +35,27 @@ export function compiles(code) {
 }
 /** Runs a snippet and returns its result record. A snippet that reports `ok: false` throws, except a wrong page, which the caller handles. */
 export async function runSnippet(client, s, options) {
-    const { result, runId, metrics } = await executeCode(client, s.code, { effect: s.effect, ...options });
-    const record = typeof result === "object" && result !== null && !Array.isArray(result) ? result : { value: result };
+    const { result, runId, metrics } = await executeCode(client, s.code, {
+        effect: s.effect,
+        ...options,
+    });
+    const record = typeof result === "object" && result !== null && !Array.isArray(result)
+        ? result
+        : {
+            value: result,
+        };
     if (record.ok === false && !record.wrongPage) {
-        if ((options?.effect ?? s.effect) !== "read")
+        if ((options?.effect ?? s.effect) !== "read") {
             throw new UncertainExecutionError(runId, `${s.name}: ${record.message ?? "failed"}`);
+        }
         throw new PenpairError("tool-failed", `${s.name}: ${record.message ?? "failed"}`);
     }
-    return { ...record, execution: { runId, outcome: "ran", metrics } };
+    return {
+        ...record,
+        execution: {
+            runId,
+            outcome: "ran",
+            metrics,
+        },
+    };
 }

package/dist/snippets/read.js

@@ -10,7 +10,9 @@ export function switchPage(name) {
 if (!target) return { ok: false, message: "no page named " + CFG.name };
 if (penpot.currentPage.id === target.id) return { ok: true, alreadyThere: true };
 penpot.openPage(target);
-return { ok: true, switched: true };`, { name });
+return { ok: true, switched: true };`, {
+        name,
+    });
 }
 /** The top-level frames of a page: id, name and size, so they can be found by name and exported. */
 export function frames(params) {
@@ -20,8 +22,12 @@ return { ok: true, readOnly: true, file: penpot.currentFile.name, fileId: penpot
 }
 /** One line per shape: type, name, size, position on the page, layout and sizing, the text it carries. */
 export function tree(params) {
-    if (params.limit !== undefined && (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1000) || params.depth !== undefined && (!Number.isInteger(params.depth) || params.depth < 0 || params.depth > 100))
+    if ((params.limit !== undefined &&
+        (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1000)) ||
+        (params.depth !== undefined &&
+            (!Number.isInteger(params.depth) || params.depth < 0 || params.depth > 100))) {
         throw new Error("Readable tree budgets require limit 1..1000 and depth 0..100; use inspect for larger structured scopes");
+    }
     return readSnippet("tree", `${requirePage}
 const depth=CFG.depth===undefined?3:CFG.depth,limit=CFG.limit||400,lines=[];
 let depthLimited=false,textLimited=false,labelLimited=false;

package/dist/structure-snapshot.d.ts

@@ -48,8 +48,20 @@ export interface StructuralManifest {
 export declare const structuralJson: (value: unknown) => string;
 export declare function structuralPage(raw: InspectionDocument, name: string): StructuralPage;
 export declare function assembleStructuralSnapshot(pages: StructuralPage[], rawTokens: InspectionDocument): StructuralSnapshot;
+export interface SnapshotProgress {
+    pageId: string;
+    stage: "start" | "complete";
+    elapsedMs: number;
+}
+export declare class SnapshotCaptureError extends Error {
+    readonly progress: SnapshotProgress[];
+    readonly restorationError?: string | undefined;
+    constructor(message: string, progress: SnapshotProgress[], restorationError?: string | undefined);
+}
 export declare function captureStructuralSnapshot(client: PenpotToolClient, options?: ExecuteOptions & {
     signal?: AbortSignal;
+    onStep?: (message: string) => void;
+    onProgress?: (event: SnapshotProgress) => void;
 }): Promise<StructuralSnapshot>;
 export declare function writeStructuralSnapshot(root: string, out: string, snapshot: StructuralSnapshot, redact?: (text: string) => string): Promise<StructuralManifest>;
 export declare function readStructuralSnapshot(root: string, folder: string): Promise<StructuralSnapshot>;