@penpair/core 0.1.3 → 0.3.0

package/dist/endpoint.js

@@ -1,8 +1,11 @@
+import { readCredential } from "./credentials.js";
 import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { PenpairError } from "./errors.js";
-export const defaultVariableNames = ["PENPAIR_MCP_URL"];
+export const defaultVariableNames = [
+    "PENPAIR_MCP_URL",
+];
 function describe(url, source) {
     let parsed;
     try {
@@ -11,15 +14,26 @@ function describe(url, source) {
     catch {
         throw new PenpairError("endpoint-invalid", `The ${source} Penpot endpoint is not a valid URL`);
     }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
         throw new PenpairError("endpoint-invalid", `The ${source} Penpot endpoint must use http or https`);
-    return { url, description: { source, origin: parsed.origin, pathname: parsed.pathname } };
+    }
+    return {
+        url,
+        description: {
+            source,
+            origin: parsed.origin,
+            pathname: parsed.pathname,
+        },
+    };
 }
-async function readOptional(file) {
+async function readOptional(file, strict = false) {
     try {
         return await readFile(file, "utf8");
     }
-    catch {
+    catch (error) {
+        if (strict && error.code !== "ENOENT") {
+            throw new PenpairError("endpoint-unconfigured", "Project connection source cannot be read; repair its storage before resolving credentials");
+        }
         // An unreadable file is treated as absent; the error would otherwise expose a local path layout.
         return undefined;
     }
@@ -28,19 +42,22 @@ async function readOptional(file) {
 export function parseEnvFileValue(text, name) {
     for (const rawLine of text.split(/\r?\n/)) {
         const line = rawLine.trim();
-        if (line === "" || line.startsWith("#"))
+        if (line === "" || line.startsWith("#")) {
             continue;
+        }
         const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
-        if (!match || match[1] !== name)
+        if (!match || match[1] !== name) {
             continue;
+        }
         let value = (match[2] ?? "").trim();
         const quote = value[0];
         if ((quote === '"' || quote === "'") && value.length > 1) {
             const end = value.indexOf(quote, 1);
             value = end === -1 ? value.slice(1) : value.slice(1, end);
         }
-        else
+        else {
             value = value.replace(/\s+#.*$/, "");
+        }
         return value.length > 0 ? value : undefined;
     }
     return undefined;
@@ -56,11 +73,13 @@ export function parseCodexServerUrl(toml, serverName = "penpot") {
             inServer = header.test(line);
             continue;
         }
-        if (!inServer)
+        if (!inServer) {
             continue;
+        }
         const match = /^url\s*=\s*(?:"((?:[^"\\]|\\.)*)"|'([^']*)')\s*(?:#.*)?$/.exec(line);
-        if (match)
+        if (match) {
             return (match[1] ?? match[2])?.replace(/\\(["\\])/g, "$1");
+        }
     }
     return undefined;
 }
@@ -68,14 +87,20 @@ export function parseCodexServerUrl(toml, serverName = "penpot") {
 export function parseClaudeServerUrl(json, serverName = "penpot") {
     try {
         const value = JSON.parse(json);
-        if (typeof value !== "object" || value === null || !("mcpServers" in value))
+        if (typeof value !== "object" || value === null || !("mcpServers" in value)) {
             return undefined;
+        }
         const servers = value.mcpServers;
-        if (typeof servers !== "object" || servers === null || !(serverName in servers))
+        if (typeof servers !== "object" || servers === null || !(serverName in servers)) {
             return undefined;
+        }
         const server = servers[serverName];
-        if (typeof server !== "object" || server === null || !("url" in server) || typeof server.url !== "string")
+        if (typeof server !== "object" ||
+            server === null ||
+            !("url" in server) ||
+            typeof server.url !== "string") {
             return undefined;
+        }
         return server.url;
     }
     catch {
@@ -91,31 +116,80 @@ export async function resolveEndpoint(options = {}) {
     const environment = options.environment ?? process.env;
     const home = options.home ?? os.homedir();
     const names = options.variableNames ?? defaultVariableNames;
-    const envFiles = options.envFiles ?? (environment === process.env ? [path.join(process.cwd(), ".env.local")] : []);
+    const envFiles = options.envFiles ??
+        (environment === process.env
+            ? [
+                path.join(process.cwd(), ".env.local"),
+            ]
+            : []);
     const serverName = options.serverName ?? "penpot";
+    if (options.credential) {
+        return describe(await readCredential(options.credential, {
+            root: options.credentialRoot ?? process.cwd(),
+        }), options.credential.type === "file" ? "credential-file" : "keychain");
+    }
+    const providerFile = environment.PENPAIR_MCP_URL_FILE?.trim();
+    if (providerFile) {
+        return describe(await readCredential({
+            type: "file",
+            path: providerFile,
+        }, {
+            root: options.credentialRoot ?? process.cwd(),
+        }), "credential-file");
+    }
+    if (environment.PENPAIR_MCP_URL_COMMAND?.trim()) {
+        throw new PenpairError("endpoint-invalid", "Arbitrary credential commands are not enabled; use a private file or OS credential reference");
+    }
+    // Explicit file references outrank legacy URL/global sources and fail closed when unreadable.
+    for (const file of envFiles) {
+        const text = await readOptional(file, true);
+        if (text === undefined) {
+            continue;
+        }
+        const provider = parseEnvFileValue(text, "PENPAIR_MCP_URL_FILE");
+        if (provider) {
+            return describe(await readCredential({
+                type: "file",
+                path: provider,
+            }, {
+                root: path.dirname(file),
+            }), "credential-file");
+        }
+        if (parseEnvFileValue(text, "PENPAIR_MCP_URL_COMMAND")) {
+            throw new PenpairError("endpoint-invalid", "Arbitrary credential commands are not enabled; use a private file or OS credential reference");
+        }
+    }
     for (const name of names) {
         const explicit = environment[name]?.trim();
-        if (explicit)
+        if (explicit) {
             return describe(explicit, "env");
+        }
     }
     for (const file of envFiles) {
-        const text = await readOptional(file);
-        if (text === undefined)
+        const text = await readOptional(file, true);
+        if (text === undefined) {
             continue;
+        }
         for (const name of names) {
             const fromFile = parseEnvFileValue(text, name);
-            if (fromFile)
+            if (fromFile) {
                 return describe(fromFile, "env-file");
+            }
         }
     }
+    if (options.globalConfig === false) {
+        throw new PenpairError("endpoint-unconfigured", "No project Penpot endpoint in the environment or configured project env file; global client fallback is disabled");
+    }
     const codex = await readOptional(path.join(home, ".codex/config.toml"));
     const fromCodex = codex === undefined ? undefined : parseCodexServerUrl(codex, serverName);
-    if (fromCodex)
+    if (fromCodex) {
         return describe(fromCodex, "codex-config");
+    }
     const claude = await readOptional(path.join(home, ".claude.json"));
     const fromClaude = claude === undefined ? undefined : parseClaudeServerUrl(claude, serverName);
-    if (fromClaude)
+    if (fromClaude) {
         return describe(fromClaude, "claude-config");
+    }
     throw new PenpairError("endpoint-unconfigured", `No Penpot MCP endpoint: ${names.join(" or ")} is unset (environment and .env.local) and no '${serverName}' MCP server is configured for Codex or Claude Code`);
 }
 /** Removes the endpoint URL, its query string and any userToken parameter from text that may be persisted. */
@@ -123,8 +197,46 @@ export function redactEndpoint(text, endpoint) {
     let redacted = text;
     if (endpoint) {
         const parsed = new URL(endpoint.url);
-        for (const secret of [endpoint.url, parsed.search, parsed.search.slice(1)].filter((value) => value.length > 1))
+        const key = parsed.searchParams.get("userToken") ?? "";
+        for (const secret of [
+            endpoint.url,
+            parsed.search,
+            parsed.search.slice(1),
+            key,
+            encodeURIComponent(key),
+        ].filter((value) => value.length > 1)) {
             redacted = redacted.split(secret).join("[redacted]");
+        }
     }
     return redacted.replace(/userToken=[^\s&"'<>]+/gi, "userToken=[redacted]");
 }
+/** Known endpoint redaction with optional boundary fragments for serialized inspection chunks. */
+export function endpointRedactor(endpoint, fragments = false) {
+    const key = new URL(endpoint.url).searchParams.get("userToken") ?? "";
+    const variants = [
+        ...new Set([
+            key,
+            encodeURIComponent(key),
+            JSON.stringify(key).slice(1, -1),
+        ]),
+    ].filter((value) => value.length > 1);
+    return (text) => {
+        let clean = redactEndpoint(text, endpoint);
+        if (fragments) {
+            for (const value of variants) {
+                const minimum = Math.min(8, Math.ceil(value.length / 2));
+                for (let size = value.length - 1; size >= minimum; size--) {
+                    const prefix = value.slice(0, size);
+                    const suffix = value.slice(-size);
+                    if (clean.endsWith(prefix)) {
+                        clean = clean.slice(0, -prefix.length) + "[redacted]";
+                    }
+                    if (clean.startsWith(suffix)) {
+                        clean = "[redacted]" + clean.slice(suffix.length);
+                    }
+                }
+            }
+        }
+        return clean;
+    };
+}

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
-export type PenpairErrorCode = "endpoint-unconfigured" | "endpoint-invalid" | "mcp-unavailable" | "auth-rejected" | "plugin-disconnected" | "plugin-suspended" | "tool-failed" | "snippet-too-large";
+export type PenpairErrorCode = "stale-inspection" | "incomplete-output" | "write-uncertain" | "file-mismatch" | "endpoint-unconfigured" | "endpoint-invalid" | "mcp-unavailable" | "auth-rejected" | "plugin-disconnected" | "plugin-suspended" | "tool-failed" | "snippet-too-large";
+export declare const errorRemedies: Readonly<Record<PenpairErrorCode, string>>;
 export declare class PenpairError extends Error {
     readonly code: PenpairErrorCode;
     readonly remedy: string;

package/dist/errors.js

@@ -1,5 +1,9 @@
 // Every failure tells the person running the command what to do next. Remedies never contain credentials.
-const remedies = {
+export const errorRemedies = Object.freeze({
+    "stale-inspection": "The file, revision, query or inspected content changed. Discard the old cursor/chunks and start a fresh capture.",
+    "incomplete-output": "Required output is missing, truncated or unstable. Narrow the scope or resolve the capture problem before accepting it as complete.",
+    "write-uncertain": "Do not replay this write blindly. Inspect the intended file independently and reconcile what already changed before explicitly resuming.",
+    "file-mismatch": "Open the project's pinned design file and reconnect its MCP plugin. Use --any-file only when you intend to act on another file.",
     "endpoint-unconfigured": "Set PENPAIR_MCP_URL in the shell or in a git-ignored .env.local to the MCP URL from Penpot (Account, Integrations, MCP Server; do not regenerate the key), or configure an MCP server named 'penpot' for Codex or Claude Code.",
     "endpoint-invalid": "The configured MCP URL must be a complete http or https URL.",
     "mcp-unavailable": "Start the Penpot instance and check the MCP URL. Run `penpair probe` to see what answers.",
@@ -8,14 +12,14 @@ const remedies = {
     "plugin-suspended": "The browser put the Penpot tab to sleep. Bring it to the foreground and keep it visible while a command runs. A suspended-tab error does not mean nothing was written: read the page before running a write again.",
     "tool-failed": "Penpot's tool reported a failure; the message above says what.",
     "snippet-too-large": "Split the snippet. Penpot's proxy refuses request bodies of about 110 KB, so snippets stay under 90 KB.",
-};
+});
 export class PenpairError extends Error {
     code;
     remedy;
     constructor(code, message) {
-        super(`${message}\n→ ${remedies[code]}`);
+        super(`${message}\n→ ${errorRemedies[code]}`);
         this.name = "PenpairError";
         this.code = code;
-        this.remedy = remedies[code];
+        this.remedy = errorRemedies[code];
     }
 }

package/dist/export.d.ts

@@ -1,3 +1,4 @@
+import { type LayoutResult } from "./layout.js";
 import { Buffer } from "node:buffer";
 import type { PenpotToolClient } from "./client.js";
 import { type OperationOptions } from "./operation.js";
@@ -11,7 +12,24 @@ export interface ExportOptions extends OperationOptions {
     stable?: boolean;
     maxExports?: number;
 }
+export interface CaptureIdentity {
+    fileId: string;
+    pageId: string;
+    frameId: string;
+    revision: number;
+    designSize?: {
+        width: number;
+        height: number;
+    };
+    activeThemeIds?: string[] | null;
+    scale: number;
+    penpotApiVersion: string | null;
+    renderEnvironment: string | null;
+    activeThemes: string[];
+}
 export interface ExportResult {
+    layout?: LayoutResult;
+    capture: CaptureIdentity;
     png: Buffer;
     /** Whether two consecutive exports were byte-identical. Always false when `stable` is off. */
     stable: boolean;

package/dist/export.js

@@ -1,3 +1,7 @@
+import { withPageSession } from "./page-session.js";
+import { waitForStableLayout } from "./layout.js";
+import { PenpairError } from "./errors.js";
+import { commandSleep } from "./command-result.js";
 import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
 import { snippet, requirePage } from "./snippet.js";
@@ -5,36 +9,135 @@ import { runOnPage } from "./operation.js";
 const exportSnippet = (shapeId, scale, page) => snippet("export", `${requirePage}
 const s = penpot.currentPage.getShapeById(CFG.id);
 if (!s) return { ok: false, message: "no shape " + CFG.id + " on " + penpot.currentPage.name };
+const active = (penpot.library?.local?.tokens?.themes || []).filter(t=>t.active);
+const capture = {designSize:{width:s.width,height:s.height},activeThemeIds:active.every(t=>typeof t.id==="string"&&t.id)?active.map(t=>t.id).sort():null,fileId:penpot.currentFile.id, pageId:penpot.currentPage.id, frameId:s.id, revision:penpot.currentFile.revn, scale:CFG.scale,
+  penpotApiVersion:typeof penpot.version === "string" ? penpot.version : null,
+  renderEnvironment:typeof navigator !== "undefined" ? navigator.userAgent : null,
+  activeThemes:(penpot.library?.local?.tokens?.themes || []).filter(t=>t.active).map(t=>t.group+"/"+t.name).sort()};
+const geometry = JSON.stringify([s.x,s.y,s.width,s.height]);
 const bytes = await s.export({ type: "png", scale: CFG.scale });
+const afterShape = penpot.currentPage.getShapeById(CFG.id);
+if (penpot.currentFile.id !== capture.fileId || penpot.currentPage.id !== capture.pageId || penpot.currentFile.revn !== capture.revision || !afterShape || afterShape.id !== capture.frameId || JSON.stringify([afterShape.x,afterShape.y,afterShape.width,afterShape.height]) !== geometry)
+ return {ok:false, message:"Export source changed during capture"};
 let bin = ""; for (let i = 0; i < bytes.length; i += 8192) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
-return { ok: true, base64: btoa(bin), length: bytes.length };`, { id: shapeId, scale, page });
-const defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+return { ok: true, base64: btoa(bin), length: bytes.length, capture };`, {
+    id: shapeId,
+    scale,
+    page,
+}, "read");
+const defaultSleep = commandSleep;
 /** Exports one shape as PNG. A first call can fail once and then work; this retries, and by default waits for a stable render. */
 export async function exportShapePng(client, shapeId, options = {}) {
-    const { page, scale = 1, attempts = 3, stable = true, maxExports = 4, sleep = defaultSleep } = options;
+    return withPageSession(client, () => exportInSession(client, shapeId, options));
+}
+async function exportInSession(client, shapeId, options) {
+    const { page, scale = 1, attempts = 3, stable = true, maxExports = 4, sleep = defaultSleep, } = options;
+    if (!Number.isFinite(scale) ||
+        scale <= 0 ||
+        scale > 8 ||
+        !Number.isInteger(attempts) ||
+        attempts < 1 ||
+        attempts > 10 ||
+        !Number.isInteger(maxExports) ||
+        maxExports < (stable ? 2 : 1) ||
+        maxExports > 20) {
+        throw new Error("Invalid export scale/attempt limits");
+    }
     const once = async () => {
         for (let attempt = 1;; attempt++) {
             try {
                 const record = await runOnPage(client, exportSnippet(shapeId, scale, page), page, options);
-                return Buffer.from(String(record.base64), "base64");
+                const capture = record.capture;
+                if (!capture ||
+                    typeof capture.fileId !== "string" ||
+                    !capture.fileId ||
+                    typeof capture.pageId !== "string" ||
+                    !capture.pageId ||
+                    capture.frameId !== shapeId ||
+                    !Number.isInteger(capture.revision) ||
+                    capture.scale !== scale ||
+                    !Array.isArray(capture.activeThemes)) {
+                    throw new Error("Export did not return target provenance");
+                }
+                if (capture.designSize &&
+                    ![
+                        capture.designSize.width,
+                        capture.designSize.height,
+                    ].every((value) => Number.isFinite(value) && value >= 0)) {
+                    throw new Error("Export has malformed design dimensions");
+                }
+                if (capture.activeThemeIds !== undefined &&
+                    capture.activeThemeIds !== null &&
+                    (!Array.isArray(capture.activeThemeIds) ||
+                        capture.activeThemeIds.some((id) => typeof id !== "string" || !id) ||
+                        new Set(capture.activeThemeIds).size !== capture.activeThemeIds.length)) {
+                    throw new Error("Export has malformed active theme identity");
+                }
+                if (typeof record.base64 !== "string" ||
+                    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(record.base64)) {
+                    throw new Error("Invalid export byte encoding");
+                }
+                const png = Buffer.from(record.base64, "base64");
+                if (!png.length || png.length !== record.length) {
+                    throw new Error("Export byte length does not match its evidence");
+                }
+                return {
+                    png,
+                    capture,
+                };
             }
             catch (error) {
-                if (attempt >= attempts)
+                if (attempt >= attempts) {
                     throw error;
+                }
                 await sleep(5_000);
             }
         }
     };
     let previous = await once();
-    if (!stable)
-        return { png: previous, stable: false, exports: 1 };
+    let layout;
+    if (options.layout !== false) {
+        layout = await waitForStableLayout(client, {
+            shapeId,
+            sleep,
+            ...options.layout,
+        });
+        if (!layout.stable) {
+            throw new PenpairError("incomplete-output", `Layout did not settle before export: ${layout.reason ?? "unknown reason"}`);
+        }
+    }
+    if (!stable) {
+        return {
+            layout,
+            ...previous,
+            stable: false,
+            exports: 1,
+        };
+    }
     const hash = (buffer) => createHash("sha256").update(buffer).digest("hex");
     for (let count = 2; count <= maxExports; count++) {
         await sleep(2_000);
         const next = await once();
-        if (hash(next) === hash(previous))
-            return { png: next, stable: true, exports: count };
+        const identity = ({ designSize: _size, ...value }) => value;
+        if (JSON.stringify(identity(next.capture)) !== JSON.stringify(identity(previous.capture))) {
+            throw new Error("Export identity, revision or render environment changed between captures");
+        }
+        if (JSON.stringify(next.capture.designSize ?? null) ===
+            JSON.stringify(previous.capture.designSize ?? null) &&
+            hash(next.png) === hash(previous.png)) {
+            return {
+                layout,
+                ...next,
+                stable: true,
+                exports: count,
+            };
+        }
         previous = next;
     }
-    return { png: previous, stable: false, exports: maxExports };
+    return {
+        layout,
+        ...previous,
+        stable: false,
+        exports: maxExports,
+    };
 }

package/dist/file-archive.d.ts

@@ -0,0 +1,16 @@
+import type { PenpotToolClient } from "./client.js";
+export type FileArchive = {
+    status: "exported";
+    bytes: Buffer;
+    fileId: string;
+    revn: number;
+    sha256: string;
+    restoreVerified: false;
+} | {
+    status: "unsupported" | "failed" | "too-large" | "changed";
+    message: string;
+};
+/** Full-fidelity recovery is established by import/readback, not by receiving archive bytes. */
+export declare function exportFileArchive(client: PenpotToolClient, options?: {
+    maxBytes?: number;
+}): Promise<FileArchive>;

package/dist/file-archive.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { runSnippet, snippet } from "./snippet.js";
+import { redactEndpoint } from "./endpoint.js";
+/** Full-fidelity recovery is established by import/readback, not by receiving archive bytes. */
+export async function exportFileArchive(client, options = {}) {
+    const maxBytes = options.maxBytes ?? 512 * 1024;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > 16 * 1024 * 1024) {
+        throw new Error("Archive budget must be positive and at most 16 MiB");
+    }
+    const result = await runSnippet(client, snippet("file-archive", `
+const file = penpot.currentFile, fileId = file.id, revn = file.revn;
+if (typeof file.export !== "function") return { ok: true, status: "unsupported", message: "File export is unavailable; use Penpot's File export menu" };
+let bytes;
+try { bytes = await file.export("penpot", "all"); }
+catch (error) { return { ok: true, status: "failed", message: "Archive export failed: " + String(error && error.message || error) + ". Use the manual export route." }; }
+if (penpot.currentFile.id !== fileId || penpot.currentFile.revn !== revn) return { ok: true, status: "changed", message: "The file changed during export; archive was not accepted" };
+if (!bytes || !Number.isSafeInteger(bytes.length) || bytes.length === 0) return { ok: true, status: "failed", message: "File export returned no archive bytes" };
+if (bytes.length > CFG.maxBytes) return { ok: true, status: "too-large", message: "Archive exceeds the configured response budget; export it manually" };
+let binary = "";
+for (let i = 0; i < bytes.length; i += 8192) binary += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
+return { ok: true, status: "exported", fileId, revn, length: bytes.length, base64: btoa(binary) };`, {
+        maxBytes,
+    }, "read"));
+    if (result.status !== "exported") {
+        if (![
+            "unsupported",
+            "failed",
+            "too-large",
+            "changed",
+        ].includes(String(result.status)) ||
+            typeof result.message !== "string") {
+            throw new Error("Archive response contained no valid outcome");
+        }
+        return {
+            status: result.status,
+            message: redactEndpoint(result.message),
+        };
+    }
+    if (result.ok !== true ||
+        typeof result.fileId !== "string" ||
+        !Number.isInteger(result.revn) ||
+        typeof result.base64 !== "string" ||
+        !/^[A-Za-z0-9+/]*={0,2}$/.test(result.base64)) {
+        throw new Error("Archive response contained incomplete metadata");
+    }
+    const bytes = Buffer.from(result.base64, "base64");
+    if (bytes.length === 0 || bytes.length > maxBytes || bytes.length !== result.length) {
+        throw new Error("Archive response was empty, truncated or over budget");
+    }
+    return {
+        status: "exported",
+        bytes,
+        fileId: result.fileId,
+        revn: Number(result.revn),
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        restoreVerified: false,
+    };
+}

package/dist/file-guard.d.ts

@@ -0,0 +1,8 @@
+import { type PenpotToolClient } from "./client.js";
+import type { ProjectFile } from "./instance/config.js";
+/** A guard in the delivered execution closes the gap between a connection check and a later batch. */
+export declare function guardFile(client: PenpotToolClient, expected: ProjectFile | undefined, options?: {
+    mode?: "strict" | "warn";
+    anyFile?: boolean;
+    warn?: (message: string) => void;
+}): PenpotToolClient;

package/dist/file-guard.js

@@ -0,0 +1,58 @@
+import { inheritPageSession } from "./page-session.js";
+import { executionEnvelope, maxSnippetBytes } from "./client.js";
+import { PenpairError } from "./errors.js";
+/** A guard in the delivered execution closes the gap between a connection check and a later batch. */
+export function guardFile(client, expected, options = {}) {
+    if (!expected || options.anyFile) {
+        options.warn?.(options.anyFile
+            ? "--any-file overrides the project's file guard for this run."
+            : "No file ID is pinned. Run `penpair connect --pin-file` to protect this project's file.");
+        return client;
+    }
+    const warningPrefix = "penpair-file-warning: ";
+    return inheritPageSession({
+        ...client,
+        close: () => client.close(),
+        ...(client.listTools
+            ? {
+                listTools: () => client.listTools(),
+            }
+            : {}),
+        async callTool(name, args, callOptions) {
+            if (name !== "execute_code" || typeof args.code !== "string") {
+                throw new PenpairError("file-mismatch", "The file guard only permits guarded execute_code calls.");
+            }
+            const guard = `{ const __penpairExpectedFile = ${JSON.stringify(expected)};
+const __penpairActualFile = penpot.currentFile;
+if (!__penpairActualFile || __penpairActualFile.id !== __penpairExpectedFile.id) {
+  const message = "Expected file " + (__penpairExpectedFile.name || __penpairExpectedFile.id) + " (" + __penpairExpectedFile.id + "), connected to " + (__penpairActualFile ? __penpairActualFile.name + " (" + __penpairActualFile.id + ")" : "no file") + ". Open the expected file and reconnect, or explicitly use --any-file.";
+  ${options.mode === "warn" ? `console.warn(${JSON.stringify(warningPrefix)} + message);` : "return { ok: false, fileMismatch: true, message };"}
+} }
+`;
+            const code = guard + args.code;
+            if (Buffer.byteLength(code, "utf8") > maxSnippetBytes) {
+                throw new PenpairError("snippet-too-large", "The snippet including its file guard exceeds 90 KB");
+            }
+            const outcome = await client.callTool(name, {
+                ...args,
+                code,
+            }, callOptions);
+            const envelope = executionEnvelope(outcome);
+            const result = envelope?.result;
+            if (typeof result === "object" &&
+                result !== null &&
+                "fileMismatch" in result &&
+                result.fileMismatch === true) {
+                throw new PenpairError("file-mismatch", String("message" in result ? result.message : "The connected file changed"));
+            }
+            if (typeof envelope?.log === "string") {
+                for (const line of envelope.log.split("\n")) {
+                    if (line.includes(warningPrefix)) {
+                        options.warn?.(line.slice(line.indexOf(warningPrefix) + warningPrefix.length));
+                    }
+                }
+            }
+            return outcome;
+        },
+    }, client);
+}

package/dist/formats.d.ts

@@ -0,0 +1,4 @@
+/** Public envelope schemas; runtime validators additionally enforce hashes, identities, hierarchy and budgets. */
+export declare const artifactSchemas: Record<string, unknown>;
+/** Legacy unversioned config is v1; preserve every extension block and require explicit new output for persistence. */
+export declare function migrateProjectConfig(raw: unknown): Record<string, unknown>;