@penpair/core 0.1.3 → 0.2.0

package/dist/coordination.js

@@ -0,0 +1,122 @@
+import { createHash, randomUUID } from "node:crypto";
+import { hostname, userInfo } from "node:os";
+import { lstat, mkdir, open, readFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import { ensureGitignoreEntry } from "./instance/gitignore.js";
+import { runSnippet, snippet } from "./snippet.js";
+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" });
+    const parent = path.join(root, ".penpair");
+    await mkdir(parent, { mode: 0o700 }).catch((error) => { if (error.code !== "EEXIST")
+        throw error; });
+    const parentInfo = await lstat(parent);
+    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; });
+    const info = await lstat(directory);
+    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 create = async () => {
+        const handle = await open(destination, "wx", 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(entry));
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    try {
+        await create();
+    }
+    catch (error) {
+        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) {
+            try {
+                process.kill(previous.pid, 0);
+                running = true;
+            }
+            catch (failure) {
+                if (failure.code !== "ESRCH")
+                    running = true;
+            }
+        }
+        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)
+            await unlink(destination);
+    };
+}
+const readMarker = `const f = penpot.currentFile;
+if (typeof f.getSharedPluginData !== "function" || typeof f.setSharedPluginData !== "function") return { ok: true, supported: false };
+const raw = f.getSharedPluginData("penpair", "writer");
+let marker = null;
+if (raw) { try { marker = JSON.parse(raw); } catch { return { ok: false, message: "Malformed shared writer marker; inspect before overriding" }; } }
+`;
+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 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"));
+            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 };
+            }
+            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)
+                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)
+                    throw new Error("Shared writer marker was lost or expired; stop and coordinate before resuming");
+            };
+            await check();
+            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"));
+                    }
+                    finally {
+                        await releaseLocal();
+                    }
+                } };
+        }
+        catch (error) {
+            await releaseLocal();
+            throw error;
+        }
+    };
+}
+/** 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")
+                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)
+                throw new PenpairError("snippet-too-large", "Snippet including revision guard exceeds 90 KB");
+            return client.callTool(name, { ...args, code }, options);
+        } };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,21 @@
+export type CredentialReference = {
+    type: "file";
+    path: string;
+} | {
+    type: "keychain";
+    service: string;
+    account: string;
+};
+export declare function validateCredentialReference(raw: unknown): CredentialReference;
+type KeychainRead = (command: string, args: string[], options: {
+    timeout: number;
+    maxBuffer: number;
+    encoding: "utf8";
+}) => Promise<string>;
+/** Resolve only at connection time. No URL, key, child stderr or command error object enters diagnostics. */
+export declare function readCredential(reference: CredentialReference, options: {
+    root: string;
+    platform?: string;
+    keychainRead?: KeychainRead;
+}): Promise<string>;
+export {};

package/dist/credentials.js

@@ -0,0 +1,61 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+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))
+        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))
+            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)))
+            throw new Error("Invalid keychain service/account reference");
+    }
+    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 normalize = (raw) => {
+    const value = raw.trim();
+    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;
+    if (ref.type === "keychain") {
+        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" }));
+        }
+        catch {
+            throw new PenpairError("endpoint-unconfigured", "OS credential lookup failed, timed out, or returned invalid output; inspect access in the OS credential UI");
+        }
+    }
+    let handle;
+    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)
+            throw new Error("not a bounded regular file");
+        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)
+            throw new Error("credential file byte budget exceeded");
+        return normalize(buffer.subarray(0, read.bytesRead).toString("utf8"));
+    }
+    catch {
+        throw new PenpairError("endpoint-unconfigured", "Credential file must be a readable owner-private regular file (0600 on POSIX), not a symlink, with one bounded MCP URL line");
+    }
+    finally {
+        await handle?.close();
+    }
+}

package/dist/deep-check.js

@@ -68,20 +68,24 @@ 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)).result;
+    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)).result;
-    const steps = first.steps ?? [];
-    const leftovers = second.left ?? [];
+    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"];
     return {
         tag,
         ...(first.penpotVersion ? { penpotVersion: first.penpotVersion } : {}),
         steps,
         cleanup: first.cleanup ?? [],
         leftovers,
-        ok: steps.every((s) => s.ok) && leftovers.length === 0,
+        ok: first.ok === true && second.ok === true && complete && steps.every((s) => s.ok === true) && leftovers.length === 0,
     };
 }
 export function formatDeepReport(report) {

package/dist/design-spec.d.ts

@@ -0,0 +1,55 @@
+import type { InspectionDocument } from "./inspection.js";
+export interface ComponentMapEntry {
+    libraryId: string;
+    componentId: string;
+    codeComponent: string;
+    props?: Record<string, string | number | boolean | null>;
+    textProps?: Record<string, string>;
+}
+export interface ComponentMap {
+    schemaVersion: 1;
+    components: ComponentMapEntry[];
+}
+export interface DesignSpec {
+    schemaVersion: 1;
+    kind: "design-spec";
+    source: {
+        fileId: string;
+        pageId: string;
+        revision: number;
+        frameId: string;
+        sha256: string;
+    };
+    mappingHash: string;
+    nodes: Array<{
+        id: string;
+        evidence: Record<string, unknown>;
+        hint: {
+            codeComponent: string;
+            props: Record<string, unknown>;
+        } | null;
+        unknowns: string[];
+    }>;
+    unknowns: string[];
+}
+export declare const emptyComponentMap: ComponentMap;
+export declare function readDesignJson(root: string, file: string, maxBytes?: number): Promise<unknown>;
+export declare function validateComponentMap(raw: unknown): ComponentMap;
+/** A complete single-root tree is required; no missing descendant may quietly disappear from the handoff. */
+export declare function validateDesignInspection(raw: unknown): InspectionDocument & {
+    nodes: Record<string, unknown>[];
+};
+export declare function designSource(inspection: InspectionDocument): {
+    fileId: string;
+    pageId: string;
+    revision: number;
+    frameId: string;
+    sha256: string;
+};
+export declare function buildDesignSpec(raw: InspectionDocument, mapping?: ComponentMap): DesignSpec;
+export declare function renderDesignSpec(spec: DesignSpec): string;
+export declare function checkDesignSpec(markdown: string, inspection: InspectionDocument, mapping?: ComponentMap): {
+    current: boolean;
+    reason: string;
+};
+export declare function writeDesignSpec(root: string, out: string, markdown: string, redact?: (text: string) => string): Promise<void>;

package/dist/design-spec.js

@@ -0,0 +1,135 @@
+import { mkdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { designDataBlock, resolveProjectInput, resolveProjectOutput } from "./project-input.js";
+import { atomicWriteFile } from "./atomic-output.js";
+import { observationHash } from "./journal.js";
+export const emptyComponentMap = { schemaVersion: 1, components: [] };
+export async function readDesignJson(root, file, maxBytes = 16 * 1024 * 1024) {
+    const input = await resolveProjectInput(root, file);
+    if ((await stat(input)).size > maxBytes)
+        throw new Error("Design artifact exceeds the input byte budget");
+    return JSON.parse(await readFile(input, "utf8"));
+}
+export function validateComponentMap(raw) {
+    const v = raw;
+    if (!v || v.schemaVersion !== 1 || !Array.isArray(v.components) || v.components.length > 1000)
+        throw new Error("Unsupported component-map schema");
+    const seen = new Set();
+    for (const c of v.components) {
+        if (!c || typeof c.libraryId !== "string" || !c.libraryId || typeof c.componentId !== "string" || !c.componentId || !/^[A-Z][A-Za-z0-9]*(?:\.[A-Z][A-Za-z0-9]*)*$/.test(c.codeComponent))
+            throw new Error("Mappings require explicit library/component IDs and an identifier codeComponent");
+        const id = JSON.stringify([c.libraryId, c.componentId]);
+        if (seen.has(id))
+            throw new Error("Ambiguous component mapping");
+        seen.add(id);
+        for (const [key, value] of Object.entries(c.props ?? {}))
+            if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(key) || !["string", "number", "boolean"].includes(typeof value) && value !== null || typeof value === "number" && !Number.isFinite(value))
+                throw new Error("Mapping props must be literal scalar data");
+        for (const [key, value] of Object.entries(c.textProps ?? {}))
+            if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(key) || typeof value !== "string" || !value)
+                throw new Error("textProps map prop names to explicit descendant node IDs");
+    }
+    return structuredClone(v);
+}
+/** A complete single-root tree is required; no missing descendant may quietly disappear from the handoff. */
+export function validateDesignInspection(raw) {
+    const v = raw;
+    if (!v || v.schemaVersion !== 1 || v.kind !== "shape-inspection" || v.complete !== true || v.redacted === true || typeof v.fileId !== "string" || !v.fileId || typeof v.pageId !== "string" || !v.pageId || !Number.isInteger(v.revision) || !Array.isArray(v.nodes) || !v.nodes.length || v.nodes.length > 50000 || !Array.isArray(v.reasons) || v.reasons.length)
+        throw new Error("A complete unredacted schema-1 shape inspection is required");
+    const nodes = v.nodes;
+    const byId = new Map(nodes.map(n => [n.id, n]));
+    if (byId.size !== nodes.length)
+        throw new Error("Duplicate design node identity");
+    let roots = 0;
+    for (const n of nodes) {
+        if (typeof n.id !== "string" || !n.id || !Array.isArray(n.childIds) || n.childIds.length !== n.childrenTotal || !Number.isInteger(n.index) || Number(n.index) < 0)
+            throw new Error("Invalid design node identity/hierarchy");
+        if (n.parentId === null)
+            roots++;
+        else if (typeof n.parentId !== "string" || !byId.has(n.parentId))
+            throw new Error("Missing design parent");
+        for (const [index, childId] of n.childIds.entries()) {
+            const child = byId.get(childId);
+            if (!child || child.parentId !== n.id || child.index !== index)
+                throw new Error("Incomplete or inconsistent design hierarchy");
+        }
+        if (n.parentId !== null && (byId.get(n.parentId)?.childIds)[Number(n.index)] !== n.id)
+            throw new Error("Unlinked design node");
+    }
+    if (roots !== 1)
+        throw new Error("Design capture must have one root");
+    const seen = new Set(), stack = [nodes.find(n => n.parentId === null)];
+    while (stack.length) {
+        const n = stack.pop();
+        if (seen.has(n.id))
+            throw new Error("Design hierarchy cycle");
+        seen.add(n.id);
+        stack.push(...n.childIds.map(id => byId.get(id)));
+    }
+    if (seen.size !== nodes.length)
+        throw new Error("Disconnected design nodes");
+    return v;
+}
+export function designSource(inspection) {
+    const v = validateDesignInspection(inspection);
+    const nodes = [...v.nodes].sort((a, b) => String(a.id).localeCompare(String(b.id), "en"));
+    return { fileId: v.fileId, pageId: v.pageId, revision: v.revision, frameId: String(nodes.find(n => n.parentId === null).id), sha256: observationHash({ fileId: v.fileId, pageId: v.pageId, revision: v.revision, scope: v.scope ?? null, nodes }) };
+}
+export function buildDesignSpec(raw, mapping = emptyComponentMap) {
+    const capture = validateDesignInspection(raw), map = validateComponentMap(mapping);
+    let traversalBudget = 1_000_000;
+    const byId = new Map(capture.nodes.map(row => [row.id, row]));
+    const nodes = capture.nodes.map(n => {
+        const source = n.component?.source;
+        const matches = map.components.filter(c => c.libraryId === source?.libraryId && c.componentId === source?.id);
+        let hint = null;
+        const unknowns = Array.isArray(n.unknowns) ? n.unknowns.map(String) : ["inspection-field-availability"];
+        for (const field of ["geometry", "text", "layout", "component", "tokens", "style", "metadata"])
+            if (!(field in n))
+                unknowns.push(`uninspected:${field}`);
+        if (matches.length === 1) {
+            const match = matches[0], props = { ...match.props };
+            // Restrict overrides to descendants of this instance, not similarly named text elsewhere in the page.
+            const descendants = new Set(), pending = [...n.childIds];
+            while (pending.length) {
+                if (--traversalBudget < 0)
+                    throw new Error("Component override traversal budget exceeded");
+                const id = pending.pop(), row = byId.get(id);
+                descendants.add(id);
+                pending.push(...row.childIds);
+            }
+            for (const [prop, id] of Object.entries(match.textProps ?? {})) {
+                const text = byId.get(id)?.text;
+                if (!descendants.has(id) || typeof text?.characters !== "string")
+                    unknowns.push(`unresolved-text-prop:${prop}`);
+                else
+                    props[prop] = text.characters;
+            }
+            hint = { codeComponent: match.codeComponent, props };
+        }
+        else if (source)
+            unknowns.push("unmapped-component");
+        return { id: String(n.id), evidence: structuredClone(n), hint, unknowns };
+    });
+    return { schemaVersion: 1, kind: "design-spec", source: designSource(capture), mappingHash: observationHash(map), nodes,
+        unknowns: ["Interaction behavior and application state require an explicit implementation contract.", "Accessibility roles, focus order, keyboard behavior and responsive rules are not inferred from appearance.", "Pixel dimensions describe this captured state only; implementation component hints are owner-declared data, not executable JSX."] };
+}
+const sha = (text) => createHash("sha256").update(text).digest("hex");
+export function renderDesignSpec(spec) {
+    const body = "# Derived design handoff\n\nGenerated evidence; review unknowns with the design owner before implementation.\n\n" + designDataBlock(spec);
+    const record = { schemaVersion: 1, kind: "design-spec-record", source: spec.source, mappingHash: spec.mappingHash, bodyHash: sha(body) };
+    return `<!-- penpair-spec:${JSON.stringify(record)} -->\n${body}`;
+}
+export function checkDesignSpec(markdown, inspection, mapping = emptyComponentMap) {
+    // Exact regeneration detects both changed provenance and manual edits, without executing any embedded design content.
+    const current = markdown === renderDesignSpec(buildDesignSpec(inspection, mapping));
+    return { current, reason: current ? "Matches supplied inspection and explicit mappings; live freshness is not assessed offline" : "Source, mapping or generated document changed" };
+}
+export async function writeDesignSpec(root, out, markdown, redact) {
+    if (redact && redact(markdown) !== markdown)
+        throw new Error("Design handoff requires redaction; prior output preserved");
+    const target = await resolveProjectOutput(root, out);
+    await mkdir(path.dirname(target), { recursive: true });
+    await atomicWriteFile(target, markdown, { replace: true });
+}

package/dist/endpoint.d.ts

@@ -1,4 +1,5 @@
-export type EndpointSource = "env" | "env-file" | "codex-config" | "claude-config";
+import { type CredentialReference } from "./credentials.js";
+export type EndpointSource = "credential-file" | "keychain" | "env" | "env-file" | "codex-config" | "claude-config";
 export interface EndpointDescription {
     source: EndpointSource;
     origin: string;
@@ -19,6 +20,10 @@ export interface ResolveOptions {
     variableNames?: string[];
     /** The MCP server name looked up in the Codex and Claude Code configuration. */
     serverName?: string;
+    /** Long-lived project tools may disable unrelated global client configuration fallback. */
+    globalConfig?: boolean;
+    credential?: CredentialReference;
+    credentialRoot?: string;
 }
 /** Reads one `NAME=value` line from env-file text: optional `export`, optional quotes, `#` comments; an empty value counts as unset. */
 export declare function parseEnvFileValue(text: string, name: string): string | undefined;
@@ -34,3 +39,5 @@ export declare function parseClaudeServerUrl(json: string, serverName?: string):
 export declare function resolveEndpoint(options?: ResolveOptions): Promise<Endpoint>;
 /** Removes the endpoint URL, its query string and any userToken parameter from text that may be persisted. */
 export declare function redactEndpoint(text: string, endpoint?: Endpoint): string;
+/** Known endpoint redaction with optional boundary fragments for serialized inspection chunks. */
+export declare function endpointRedactor(endpoint: Endpoint, fragments?: boolean): (text: string) => string;

package/dist/endpoint.js

@@ -1,3 +1,4 @@
+import { readCredential } from "./credentials.js";
 import { readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -15,11 +16,13 @@ function describe(url, source) {
         throw new PenpairError("endpoint-invalid", `The ${source} Penpot endpoint must use http or https`);
     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;
     }
@@ -93,13 +96,31 @@ export async function resolveEndpoint(options = {}) {
     const names = options.variableNames ?? defaultVariableNames;
     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)
             return describe(explicit, "env");
     }
     for (const file of envFiles) {
-        const text = await readOptional(file);
+        const text = await readOptional(file, true);
         if (text === undefined)
             continue;
         for (const name of names) {
@@ -108,6 +129,8 @@ export async function resolveEndpoint(options = {}) {
                 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)
@@ -123,8 +146,29 @@ 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), 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;