@penpair/core 0.1.3 → 0.3.0

package/dist/credentials.js

@@ -0,0 +1,105 @@
+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);
+    const 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);
+        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 {
+        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,26 +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)).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)).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 } : {}),
+        ...(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) {
     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");
 }

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,275 @@
+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();
+    const 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);
+    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 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];
+            const props = {
+                ...match.props,
+            };
+            // Restrict overrides to descendants of this instance, not similarly named text elsewhere in the page.
+            const descendants = new Set();
+            const pending = [
+                ...n.childIds,
+            ];
+            while (pending.length) {
+                if (--traversalBudget < 0) {
+                    throw new Error("Component override traversal budget exceeded");
+                }
+                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") {
+                    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;