@penpair/core 0.2.0 → 0.3.1

package/dist/coordination.js

@@ -1,3 +1,4 @@
+import { inheritPageSession } from "./page-session.js";
 import { createHash, randomUUID } from "node:crypto";
 import { hostname, userInfo } from "node:os";
 import { lstat, mkdir, open, readFile, unlink } from "node:fs/promises";
@@ -8,22 +9,43 @@ import { maxSnippetBytes } from "./client.js";
 import { PenpairError } from "./errors.js";
 /** Exclusive only within this checkout. Shared file markers below are advisory, not compare-and-swap. */
 async function localLease(root, fileId, runId, force) {
-    await ensureGitignoreEntry(root, ".penpair", { directory: true, comment: "penpair: private local operation evidence" });
+    await ensureGitignoreEntry(root, ".penpair", {
+        directory: true,
+        comment: "penpair: private local operation evidence",
+    });
     const parent = path.join(root, ".penpair");
-    await mkdir(parent, { mode: 0o700 }).catch((error) => { if (error.code !== "EEXIST")
-        throw error; });
+    await mkdir(parent, {
+        mode: 0o700,
+    }).catch((error) => {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+    });
     const parentInfo = await lstat(parent);
-    if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink())
+    if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink()) {
         throw new Error("Write locks require a real local directory");
+    }
     const directory = path.join(parent, "locks");
-    await mkdir(directory, { mode: 0o700 }).catch((error) => { if (error.code !== "EEXIST")
-        throw error; });
+    await mkdir(directory, {
+        mode: 0o700,
+    }).catch((error) => {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+    });
     const info = await lstat(directory);
-    if (!info.isDirectory() || info.isSymbolicLink())
+    if (!info.isDirectory() || info.isSymbolicLink()) {
         throw new Error("Write locks require a real local directory");
+    }
     const destination = path.join(directory, `${createHash("sha256").update(fileId).digest("hex")}.json`);
     const token = randomUUID();
-    const entry = { token, runId, pid: process.pid, host: hostname(), createdAt: new Date().toISOString() };
+    const entry = {
+        token,
+        runId,
+        pid: process.pid,
+        host: hostname(),
+        createdAt: new Date().toISOString(),
+    };
     const create = async () => {
         const handle = await open(destination, "wx", 0o600);
         try {
@@ -37,8 +59,9 @@ async function localLease(root, fileId, runId, force) {
         await create();
     }
     catch (error) {
-        if (error.code !== "EEXIST")
+        if (error.code !== "EEXIST") {
             throw error;
+        }
         const previous = JSON.parse(await readFile(destination, "utf8"));
         let running = false;
         if (previous.host === hostname() && Number.isInteger(previous.pid) && previous.pid > 0) {
@@ -47,20 +70,23 @@ async function localLease(root, fileId, runId, force) {
                 running = true;
             }
             catch (failure) {
-                if (failure.code !== "ESRCH")
+                if (failure.code !== "ESRCH") {
                     running = true;
+                }
             }
         }
-        if (!force || running)
+        if (!force || running) {
             throw new Error(`Local writer ${previous.runId} holds this file. ${running ? "Its process is still running; wait for it to finish." : "Inspect its journal, then use --force-lock to remove the abandoned local lock."}`);
+        }
         // Explicit owner override only. Simultaneous force operations are not an exclusion guarantee.
         await unlink(destination);
         await create();
     }
     return async () => {
         const current = JSON.parse(await readFile(destination, "utf8"));
-        if (current.token === token)
+        if (current.token === token) {
             await unlink(destination);
+        }
     };
 }
 const readMarker = `const f = penpot.currentFile;
@@ -72,36 +98,62 @@ if (raw) { try { marker = JSON.parse(raw); } catch { return { ok: false, message
 export function writeCoordinator(client, options) {
     return async (runId, target) => {
         const releaseLocal = await localLease(options.root, target.fileId, runId, options.forceLock === true);
-        const marker = { schemaVersion: 1, token: randomUUID(), runId, operation: options.operation, owner: userInfo().username, createdAt: Date.now(), expiresAt: Date.now() + 15 * 60_000 };
-        const params = { marker, fileId: target.fileId, force: options.forceLock === true };
+        const marker = {
+            schemaVersion: 1,
+            token: randomUUID(),
+            runId,
+            operation: options.operation,
+            owner: userInfo().username,
+            createdAt: Date.now(),
+            expiresAt: Date.now() + 15 * 60_000,
+        };
+        const params = {
+            marker,
+            fileId: target.fileId,
+            force: options.forceLock === true,
+        };
         const targetGuard = 'if (penpot.currentFile.id !== CFG.fileId) return { ok:false, message:"Writer marker target changed" };';
         try {
-            const before = await runSnippet(client, snippet("writer-inspect", targetGuard + readMarker + 'return { ok:true, supported:true, marker };', params, "read"));
+            const before = await runSnippet(client, snippet("writer-inspect", targetGuard + readMarker + "return { ok:true, supported:true, marker };", params, "read"));
             if (before.supported === false) {
                 options.warn?.("Shared writer markers unavailable; local checkout lock only. Coordinate with colleagues before writing.");
-                return { check: async () => undefined, release: releaseLocal };
+                return {
+                    check: async () => undefined,
+                    release: releaseLocal,
+                };
             }
-            const acquired = await runSnippet(client, snippet("writer-acquire", targetGuard + readMarker + `
+            const acquired = await runSnippet(client, snippet("writer-acquire", targetGuard +
+                readMarker +
+                `
 if (marker && marker.token !== CFG.marker.token && (!Number.isFinite(marker.expiresAt) || marker.expiresAt > Date.now()) && !CFG.force)
   return { ok:false, message:"Another writer is running " + String(marker.operation) + " (run " + String(marker.runId) + "). Coordinate before --force-lock." };
 f.setSharedPluginData("penpair", "writer", JSON.stringify(CFG.marker));
 return { ok:true, supported:true };`, params, "write"));
-            if (acquired.supported !== true)
+            if (acquired.supported !== true) {
                 throw new Error("Writer marker capability changed during acquisition");
+            }
             const check = async () => {
-                const observed = await runSnippet(client, snippet("writer-check", targetGuard + readMarker + 'return { ok:true, supported:true, owned: !!marker && marker.token === CFG.marker.token && marker.expiresAt > Date.now() };', params, "read"));
-                if (observed.supported !== true || observed.owned !== true)
+                const observed = await runSnippet(client, snippet("writer-check", targetGuard +
+                    readMarker +
+                    "return { ok:true, supported:true, owned: !!marker && marker.token === CFG.marker.token && marker.expiresAt > Date.now() };", params, "read"));
+                if (observed.supported !== true || observed.owned !== true) {
                     throw new Error("Shared writer marker was lost or expired; stop and coordinate before resuming");
+                }
             };
             await check();
-            return { check, release: async () => {
+            return {
+                check,
+                release: async () => {
                     try {
-                        await runSnippet(client, snippet("writer-release", targetGuard + readMarker + 'if (marker && marker.token === CFG.marker.token) f.setSharedPluginData("penpair", "writer", ""); return { ok:true };', params, "write"));
+                        await runSnippet(client, snippet("writer-release", targetGuard +
+                            readMarker +
+                            'if (marker && marker.token === CFG.marker.token) f.setSharedPluginData("penpair", "writer", ""); return { ok:true };', params, "write"));
                     }
                     finally {
                         await releaseLocal();
                     }
-                } };
+                },
+            };
         }
         catch (error) {
             await releaseLocal();
@@ -111,12 +163,22 @@ return { ok:true, supported:true };`, params, "write"));
 }
 /** Revision precondition is checked inside the delivered mutation, after all guard calls. It is not a server CAS. */
 export function guardRevision(client, target) {
-    return { ...client, close: () => client.close(), async callTool(name, args, options) {
-            if (name !== "execute_code" || typeof args.code !== "string")
+    return inheritPageSession({
+        ...client,
+        close: () => client.close(),
+        async callTool(name, args, options) {
+            if (name !== "execute_code" || typeof args.code !== "string") {
                 throw new Error("Revision guards require execute_code");
-            const code = `{ if (penpot.currentFile.id !== ${JSON.stringify(target.fileId)} || penpot.currentFile.revn !== ${JSON.stringify(target.revision)}) return {ok:false, message:"File revision changed before mutation; inspect again"}; }\n` + args.code;
-            if (Buffer.byteLength(code) > maxSnippetBytes)
+            }
+            const code = `{ if (penpot.currentFile.id !== ${JSON.stringify(target.fileId)} || penpot.currentFile.revn !== ${JSON.stringify(target.revision)}) return {ok:false, message:"File revision changed before mutation; inspect again"}; }\n` +
+                args.code;
+            if (Buffer.byteLength(code) > maxSnippetBytes) {
                 throw new PenpairError("snippet-too-large", "Snippet including revision guard exceeds 90 KB");
-            return client.callTool(name, { ...args, code }, options);
-        } };
+            }
+            return client.callTool(name, {
+                ...args,
+                code,
+            }, options);
+        },
+    }, client);
 }

package/dist/credentials.js

@@ -4,36 +4,74 @@ import { open } from "node:fs/promises";
 import path from "node:path";
 import { PenpairError } from "./errors.js";
 export function validateCredentialReference(raw) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error("Credential reference must be a file or keychain object");
+    }
     const v = raw;
     if (v.type === "file") {
-        if (Object.keys(v).some(k => !["type", "path"].includes(k)) || typeof v.path !== "string" || !v.path.trim() || v.path.length > 4096 || /[\x00-\x1f]/.test(v.path))
+        if (Object.keys(v).some((k) => ![
+            "type",
+            "path",
+        ].includes(k)) ||
+            typeof v.path !== "string" ||
+            !v.path.trim() ||
+            v.path.length > 4096 ||
+            /[\x00-\x1f]/.test(v.path)) {
             throw new Error("Invalid credential file reference");
+        }
     }
     else if (v.type === "keychain") {
-        if (Object.keys(v).some(k => !["type", "service", "account"].includes(k)) || [v.service, v.account].some(s => typeof s !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._ /:@-]{0,199}$/.test(s)))
+        if (Object.keys(v).some((k) => ![
+            "type",
+            "service",
+            "account",
+        ].includes(k)) ||
+            [
+                v.service,
+                v.account,
+            ].some((s) => typeof s !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._ /:@-]{0,199}$/.test(s))) {
             throw new Error("Invalid keychain service/account reference");
+        }
     }
-    else
+    else {
         throw new Error("Only file and macOS keychain credential references are supported; arbitrary command providers are deferred");
+    }
     return structuredClone(v);
 }
-const keychainRead = (command, args, options) => new Promise((resolve, reject) => execFile(command, args, { ...options, killSignal: "SIGKILL" }, (error, stdout) => error ? reject(new Error("Credential provider unavailable or access denied")) : resolve(stdout)));
+const keychainRead = (command, args, options) => new Promise((resolve, reject) => execFile(command, args, {
+    ...options,
+    killSignal: "SIGKILL",
+}, (error, stdout) => error
+    ? reject(new Error("Credential provider unavailable or access denied"))
+    : resolve(stdout)));
 const normalize = (raw) => {
     const value = raw.trim();
-    if (!value || Buffer.byteLength(value) > 8192 || /[\r\n\x00]/.test(value))
+    if (!value || Buffer.byteLength(value) > 8192 || /[\r\n\x00]/.test(value)) {
         throw new PenpairError("endpoint-invalid", "Credential provider must return one bounded MCP URL line");
+    }
     return value;
 };
 /** Resolve only at connection time. No URL, key, child stderr or command error object enters diagnostics. */
 export async function readCredential(reference, options) {
-    const ref = validateCredentialReference(reference), platform = options.platform ?? process.platform;
+    const ref = validateCredentialReference(reference);
+    const platform = options.platform ?? process.platform;
     if (ref.type === "keychain") {
-        if (platform !== "darwin")
+        if (platform !== "darwin") {
             throw new PenpairError("endpoint-unconfigured", "macOS Keychain references require macOS; configure a private credential file on this platform");
+        }
         try {
-            return normalize(await (options.keychainRead ?? keychainRead)("/usr/bin/security", ["find-generic-password", "-s", ref.service, "-a", ref.account, "-w"], { timeout: 5000, maxBuffer: 16384, encoding: "utf8" }));
+            return normalize(await (options.keychainRead ?? keychainRead)("/usr/bin/security", [
+                "find-generic-password",
+                "-s",
+                ref.service,
+                "-a",
+                ref.account,
+                "-w",
+            ], {
+                timeout: 5000,
+                maxBuffer: 16384,
+                encoding: "utf8",
+            }));
         }
         catch {
             throw new PenpairError("endpoint-unconfigured", "OS credential lookup failed, timed out, or returned invalid output; inspect access in the OS credential UI");
@@ -43,13 +81,19 @@ export async function readCredential(reference, options) {
     try {
         handle = await open(path.resolve(options.root, ref.path), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
         const info = await handle.stat();
-        if (!info.isFile() || info.size > 16384)
+        if (!info.isFile() || info.size > 16384) {
             throw new Error("not a bounded regular file");
-        if (platform !== "win32" && ((info.mode & 0o077) !== 0 || typeof process.getuid === "function" && info.uid !== process.getuid()))
+        }
+        if (platform !== "win32" &&
+            ((info.mode & 0o077) !== 0 ||
+                (typeof process.getuid === "function" && info.uid !== process.getuid()))) {
             throw new Error("not private to current owner");
-        const buffer = Buffer.alloc(16385), read = await handle.read(buffer, 0, buffer.length, 0);
-        if (read.bytesRead > 16384)
+        }
+        const buffer = Buffer.alloc(16385);
+        const read = await handle.read(buffer, 0, buffer.length, 0);
+        if (read.bytesRead > 16384) {
             throw new Error("credential file byte budget exceeded");
+        }
         return normalize(buffer.subarray(0, read.bytesRead).toString("utf8"));
     }
     catch {

package/dist/deep-check.js

@@ -68,30 +68,74 @@ for (const c of penpot.library.local.components) if (c.name.startsWith(tag)) lef
 return { ok: true, readOnly: true, left };`;
 export async function runDeepCheck(client, options = {}) {
     const tag = `penpair-deep-${randomBytes(3).toString("hex")}`;
-    const first = (await executeCode(client, wrap(deepCheckBody, { tag }), { ...options, effect: "write" })).result;
-    if (first.ok === false)
+    const first = (await executeCode(client, wrap(deepCheckBody, {
+        tag,
+    }), {
+        ...options,
+        effect: "write",
+    })).result;
+    if (first.ok === false) {
         throw new Error(`the deep check could not run: ${first.message ?? "unknown error"}`);
+    }
     await new Promise((resolve) => setTimeout(resolve, options.settleMs ?? 3_000));
-    const second = (await executeCode(client, wrap(deepLeftoversBody, { tag }), { ...options, effect: "read" })).result;
-    const steps = Array.isArray(first.steps) ? [...first.steps] : [];
-    const required = ["create board", "flex layout and children", "text content", "token set, token and binding", "component and swap", "clone", "export png"];
+    const second = (await executeCode(client, wrap(deepLeftoversBody, {
+        tag,
+    }), {
+        ...options,
+        effect: "read",
+    })).result;
+    const steps = Array.isArray(first.steps)
+        ? [
+            ...first.steps,
+        ]
+        : [];
+    const required = [
+        "create board",
+        "flex layout and children",
+        "text content",
+        "token set, token and binding",
+        "component and swap",
+        "clone",
+        "export png",
+    ];
     const complete = required.every((name) => steps.some((step) => step.step === name && step.ok === true));
-    if (!complete)
-        steps.push({ step: "complete evidence", ok: false, ms: 0, detail: "Required deep-check observations are missing or failed" });
-    const leftovers = Array.isArray(second.left) ? second.left : ["cleanup readback was missing; inspect the scratch file"];
+    if (!complete) {
+        steps.push({
+            step: "complete evidence",
+            ok: false,
+            ms: 0,
+            detail: "Required deep-check observations are missing or failed",
+        });
+    }
+    const leftovers = Array.isArray(second.left)
+        ? second.left
+        : [
+            "cleanup readback was missing; inspect the scratch file",
+        ];
     return {
         tag,
-        ...(first.penpotVersion ? { penpotVersion: first.penpotVersion } : {}),
+        ...(first.penpotVersion
+            ? {
+                penpotVersion: first.penpotVersion,
+            }
+            : {}),
         steps,
         cleanup: first.cleanup ?? [],
         leftovers,
-        ok: first.ok === true && second.ok === true && complete && steps.every((s) => s.ok === true) && leftovers.length === 0,
+        ok: first.ok === true &&
+            second.ok === true &&
+            complete &&
+            steps.every((s) => s.ok === true) &&
+            leftovers.length === 0,
     };
 }
 export function formatDeepReport(report) {
     const lines = report.steps.map((s) => `${s.ok ? "ok  " : "FAIL"} ${s.step} (${s.ms} ms)${s.detail ? `: ${s.detail}` : ""}`);
-    lines.push(report.leftovers.length === 0 ? "ok   clean-up: nothing left in the file" : `FAIL clean-up: left in the file, remove by hand: ${report.leftovers.join(", ")}`);
-    if (report.penpotVersion)
+    lines.push(report.leftovers.length === 0
+        ? "ok   clean-up: nothing left in the file"
+        : `FAIL clean-up: left in the file, remove by hand: ${report.leftovers.join(", ")}`);
+    if (report.penpotVersion) {
         lines.push(`Penpot ${report.penpotVersion}`);
+    }
     return lines.join("\n");
 }