@penpair/core 0.2.0 → 0.3.0

package/dist/design-spec.js

@@ -4,132 +4,272 @@ 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 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)
+    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)
+    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))
+        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))
+        }
+        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))
+        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)
+            }
+        }
+        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)
+    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)
+    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)
+        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)
+        }
+        if (n.parentId === null) {
             roots++;
-        else if (typeof n.parentId !== "string" || !byId.has(n.parentId))
+        }
+        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)
+            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)
+        if (n.parentId !== null &&
+            (byId.get(n.parentId)?.childIds)[Number(n.index)] !== n.id) {
             throw new Error("Unlinked design node");
+        }
     }
-    if (roots !== 1)
+    if (roots !== 1) {
         throw new Error("Design capture must have one root");
-    const seen = new Set(), stack = [nodes.find(n => n.parentId === null)];
+    }
+    const seen = new Set();
+    const stack = [
+        nodes.find((n) => n.parentId === null),
+    ];
     while (stack.length) {
         const n = stack.pop();
-        if (seen.has(n.id))
+        if (seen.has(n.id)) {
             throw new Error("Design hierarchy cycle");
+        }
         seen.add(n.id);
-        stack.push(...n.childIds.map(id => byId.get(id)));
+        stack.push(...n.childIds.map((id) => byId.get(id)));
     }
-    if (seen.size !== nodes.length)
+    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 }) };
+    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);
+    const capture = validateDesignInspection(raw);
+    const 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 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);
+        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))
+        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 };
+            const match = matches[0];
+            const 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];
+            const descendants = new Set();
+            const pending = [
+                ...n.childIds,
+            ];
             while (pending.length) {
-                if (--traversalBudget < 0)
+                if (--traversalBudget < 0) {
                     throw new Error("Component override traversal budget exceeded");
-                const id = pending.pop(), row = byId.get(id);
+                }
+                const id = pending.pop();
+                const 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")
+                if (!descendants.has(id) || typeof text?.characters !== "string") {
                     unknowns.push(`unresolved-text-prop:${prop}`);
-                else
+                }
+                else {
                     props[prop] = text.characters;
+                }
             }
-            hint = { codeComponent: match.codeComponent, props };
+            hint = {
+                codeComponent: match.codeComponent,
+                props,
+            };
         }
-        else if (source)
+        else if (source) {
             unknowns.push("unmapped-component");
-        return { id: String(n.id), evidence: structuredClone(n), hint, unknowns };
+        }
+        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."] };
+    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) };
+    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" };
+    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)
+    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 });
+    await mkdir(path.dirname(target), {
+        recursive: true,
+    });
+    await atomicWriteFile(target, markdown, {
+        replace: true,
+    });
 }

package/dist/endpoint.js

@@ -3,7 +3,9 @@ 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 {
@@ -12,17 +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, strict = false) {
     try {
         return await readFile(file, "utf8");
     }
     catch (error) {
-        if (strict && error.code !== "ENOENT")
+        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;
     }
@@ -31,19 +42,22 @@ async function readOptional(file, strict = false) {
 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;
@@ -59,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;
 }
@@ -71,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 {
@@ -94,51 +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");
+    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())
+    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)
+        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"))
+        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, true);
-        if (text === undefined)
+        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)
+    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. */
@@ -147,28 +198,45 @@ export function redactEndpoint(text, endpoint) {
     if (endpoint) {
         const parsed = new URL(endpoint.url);
         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))
+        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);
+    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)
+        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))
+                    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))
+                    }
+                    if (clean.startsWith(suffix)) {
                         clean = "[redacted]" + clean.slice(suffix.length);
+                    }
                 }
             }
+        }
         return clean;
     };
 }