@penpair/core 0.2.0 → 0.3.0

package/dist/instance/connection.js

@@ -1,14 +1,34 @@
-import { isExternal } from "./config.js";
+import { randomUUID } from "node:crypto";
+import { commandSignal, withCommandSignal } from "../command-result.js";
+import { redactEndpoint } from "../endpoint.js";
+import { isExternal, } from "./config.js";
 /** What Penpot itself, the connection and the checks need, whichever way Penpot is run. Nothing here knows about Docker. */
 export class LifecycleError extends Error {
 }
 export const frontendUrl = (config) => `http://127.0.0.1:${config.ports.frontend}`;
 export function fileIdentityCheck(config, actual) {
     const ok = !config.file || config.file.id === actual.fileId;
-    return { check: "file identity", ok,
-        detail: config.file ? `expected ${config.file.name ?? config.file.id} (${config.file.id}); connected ${actual.file} (${actual.fileId ?? "unknown id"})` : "No file ID pinned; run penpair connect --pin-file",
-        ...(!ok ? { remedy: "Open the project's expected design file and reconnect its MCP plugin." } : {}),
-        file: { expected: config.file ?? null, actual: { id: actual.fileId, name: actual.file }, ok },
+    return {
+        check: "file identity",
+        ok,
+        layer: "file-pin",
+        observedAt: new Date().toISOString(),
+        detail: config.file
+            ? `expected ${config.file.name ?? config.file.id} (${config.file.id}); connected ${actual.file} (${actual.fileId ?? "unknown id"})`
+            : "No file ID pinned; run penpair connect --pin-file",
+        ...(!ok
+            ? {
+                remedy: "Open the project's expected design file and reconnect its MCP plugin.",
+            }
+            : {}),
+        file: {
+            expected: config.file ?? null,
+            actual: {
+                id: actual.fileId,
+                name: actual.file,
+            },
+            ok,
+        },
     };
 }
 /**
@@ -17,13 +37,15 @@ export function fileIdentityCheck(config, actual) {
  */
 export function assertEndpointIsInstance(endpoint, config) {
     if (isExternal(config)) {
-        if (sameOrigin(endpoint.origin, config.profile.origin))
+        if (sameOrigin(endpoint.origin, config.profile.origin)) {
             return;
+        }
         throw new LifecycleError(`The MCP endpoint (from ${endpoint.source}) points at ${endpoint.origin}, but this project uses ${config.profile.origin}. ` +
             "Put that Penpot's MCP URL (Account, Integrations, MCP Server) in this project's .env.local as PENPAIR_MCP_URL, or run again with --any-instance if the other one is what you mean.");
     }
-    if (endpointIsInstance(endpoint.origin, config))
+    if (endpointIsInstance(endpoint.origin, config)) {
         return;
+    }
     throw new LifecycleError(`The MCP endpoint (from ${endpoint.source}) points at ${endpoint.origin}, but this project's instance is ${frontendUrl(config)}. ` +
         "Put this instance's MCP URL (Account, Integrations, MCP Server) in this project's .env.local as PENPAIR_MCP_URL, or run again with --any-instance if the other instance is what you mean.");
 }
@@ -35,11 +57,139 @@ const sameOrigin = (a, b) => {
         return false;
     }
 };
+/** Readiness is a bounded fresh execution, separate from a reachable origin and connected transport. */
+export async function doctorEditor(config, options) {
+    if (!options.mcp) {
+        return [];
+    }
+    const started = Date.now();
+    const out = [];
+    const challenge = randomUUID();
+    const timeoutMs = options.timeoutMs ?? 5000;
+    let connected = false;
+    let finished = false;
+    const transport = () => {
+        if (!finished && !connected) {
+            connected = true;
+            out.push({
+                check: "MCP transport",
+                layer: "transport",
+                ok: true,
+                detail: "Connected to MCP transport",
+                observedAt: new Date().toISOString(),
+                durationMs: Date.now() - started,
+            });
+        }
+    };
+    try {
+        const actual = await doctorDeadline(timeoutMs, (signal) => options.mcp.connect({
+            challenge,
+            signal,
+            timeoutMs,
+            onTransport: transport,
+        }));
+        if (!connected) {
+            throw new Error("MCP transport readiness was not independently observed");
+        }
+        if (actual.challenge !== challenge ||
+            typeof actual.fileId !== "string" ||
+            !actual.fileId ||
+            typeof actual.pageId !== "string" ||
+            !actual.pageId ||
+            typeof actual.file !== "string" ||
+            !actual.file ||
+            actual.file === "?") {
+            throw new Error("Fresh execution challenge or file/page identity did not match; editor readiness is unproven");
+        }
+        out.push({
+            check: "editor and plugin",
+            layer: "execution",
+            ok: true,
+            detail: `Fresh read from file "${actual.file}"`,
+            observedAt: new Date().toISOString(),
+            durationMs: Date.now() - started,
+            evidence: {
+                challenge,
+                pageId: actual.pageId,
+                ...(typeof actual.apiVersion === "string" && actual.apiVersion
+                    ? {
+                        apiVersion: actual.apiVersion,
+                    }
+                    : {}),
+                heartbeat: "unknown",
+            },
+        });
+        out.push(fileIdentityCheck(config, actual));
+    }
+    catch (error) {
+        if (!connected) {
+            out.push({
+                check: "MCP transport",
+                layer: "transport",
+                ok: false,
+                detail: "Transport connection not confirmed",
+                observedAt: new Date().toISOString(),
+                durationMs: Date.now() - started,
+            });
+        }
+        out.push({
+            check: "editor and plugin",
+            layer: "execution",
+            ok: false,
+            detail: redactEndpoint(error instanceof Error ? error.message : String(error)),
+            observedAt: new Date().toISOString(),
+            durationMs: Date.now() - started,
+            remedy: "Open the intended file, connect the MCP plugin and keep the editor responsive; rerun doctor for a fresh read.",
+        });
+    }
+    finished = true;
+    return out;
+}
+async function doctorDeadline(timeoutMs, work) {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) {
+        throw new Error("Invalid doctor budget");
+    }
+    const controller = new AbortController();
+    const signal = AbortSignal.any([
+        controller.signal,
+        ...(commandSignal()
+            ? [
+                commandSignal(),
+            ]
+            : []),
+    ]);
+    let timer;
+    let abort = () => undefined;
+    const interrupted = new Promise((_resolve, reject) => {
+        abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, {
+            once: true,
+        });
+        timer = setTimeout(() => controller.abort(new Error("Doctor deadline exceeded; no fresh editor execution was confirmed")), timeoutMs);
+    });
+    try {
+        signal.throwIfAborted();
+        return await withCommandSignal(signal, () => Promise.race([
+            work(signal),
+            interrupted,
+        ]));
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        signal.removeEventListener("abort", abort);
+    }
+}
 /** Whether a configured MCP origin is this instance's frontend. */
 export function endpointIsInstance(origin, config) {
     try {
         const url = new URL(origin);
-        return ["localhost", "127.0.0.1"].includes(url.hostname) && Number(url.port || (url.protocol === "https:" ? 443 : 80)) === config.ports.frontend;
+        return ([
+            "localhost",
+            "127.0.0.1",
+        ].includes(url.hostname) &&
+            Number(url.port || (url.protocol === "https:" ? 443 : 80)) === config.ports.frontend);
     }
     catch {
         return false;
@@ -48,30 +198,53 @@ export function endpointIsInstance(origin, config) {
 /** The checks that make sense for a Penpot someone else runs: it answers, the key is for it, the editor and plugin are connected. */
 export async function doctorExternal(config, options = {}) {
     const out = [];
-    const add = (check, ok, detail, remedy) => void out.push({ check, ok, detail, ...(remedy && !ok ? { remedy } : {}) });
+    const add = (check, ok, detail, remedy) => void out.push({
+        check,
+        ok,
+        detail,
+        ...(remedy && !ok
+            ? {
+                remedy,
+            }
+            : {}),
+    });
+    const started = Date.now();
+    const timeoutMs = options.timeoutMs ?? 5000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 30000) {
+        throw new Error("doctor --timeout-ms must be an integer from 1000 to 30000");
+    }
     let reachable = false;
     try {
-        reachable = (await (options.fetch ?? fetch)(config.profile.origin, { redirect: "manual" })).status < 500;
+        reachable =
+            (await doctorDeadline(timeoutMs, (signal) => (options.fetch ?? fetch)(config.profile.origin, {
+                redirect: "manual",
+                signal,
+            }))).status < 500;
     }
     catch {
         reachable = false;
     }
     add("penpot", reachable, reachable ? `${config.profile.origin} answers` : `${config.profile.origin} does not answer`, "Check the address and your network, then try again.");
-    if (!options.mcp)
+    Object.assign(out[0], {
+        layer: "origin",
+        observedAt: new Date().toISOString(),
+        durationMs: Date.now() - started,
+    });
+    if (!options.mcp) {
         return out;
+    }
     if (!sameOrigin(options.mcp.origin, config.profile.origin)) {
-        add("editor and plugin", false, `the MCP endpoint points at ${options.mcp.origin}, which is not ${config.profile.origin}`, "Put this Penpot's MCP URL (Account, Integrations, MCP Server) in this project's .env.local as PENPAIR_MCP_URL.");
+        add("editor and plugin", false, `the MCP endpoint points at ${options.mcp.origin}, which is not ${config.profile.origin}`, "Configure this project's intended Penpot endpoint.");
         return out;
     }
-    try {
-        const actual = await options.mcp.connect();
-        const { file } = actual;
-        add("editor and plugin", true, `connected to file "${file}"`);
-        if (config.file)
-            out.push(fileIdentityCheck(config, actual));
-    }
-    catch (error) {
-        add("editor and plugin", false, String(error.message).split("\n")[0] ?? "not connected", "Open a file in Penpot, choose File, MCP Server, Connect, and keep the tab visible in a separate window if needed.");
+    const remaining = timeoutMs - (Date.now() - started);
+    if (remaining <= 0) {
+        add("editor and plugin", false, "Doctor deadline exhausted during origin check; execution unproven");
+        return out;
     }
+    out.push(...(await doctorEditor(config, {
+        ...options,
+        timeoutMs: remaining,
+    })));
     return out;
 }

package/dist/instance/gitignore.js

@@ -10,10 +10,13 @@ export async function ensureGitignoreEntry(root, entry, options) {
     catch {
         // no .gitignore yet
     }
-    if (text.split(/\r?\n/).some((line) => line.trim() === entry || line.trim() === `${entry}/`))
+    if (text.split(/\r?\n/).some((line) => line.trim() === entry || line.trim() === `${entry}/`)) {
         return false;
+    }
     await appendFile(file, `${text.length > 0 && !text.endsWith("\n") ? "\n" : ""}# ${options.comment}\n${entry}${options.directory ? "/" : ""}\n`);
     return true;
 }
 /** The MCP key goes in .env.local; whoever writes it makes sure git never sees it. */
-export const ensureKeyFileIgnored = (root) => ensureGitignoreEntry(root, ".env.local", { comment: "penpair: your personal Penpot MCP key" });
+export const ensureKeyFileIgnored = (root) => ensureGitignoreEntry(root, ".env.local", {
+    comment: "penpair: your personal Penpot MCP key",
+});

package/dist/instance/init.js

@@ -1,11 +1,16 @@
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { requireLocalProfile } from "../local-profile.js";
-import { configFileName, ConfigError, isExternal, loadConfig, validateProjectConfig } from "./config.js";
+import { configFileName, ConfigError, isExternal, loadConfig, validateProjectConfig, } from "./config.js";
 import { ensureKeyFileIgnored } from "./gitignore.js";
 /** A short, valid instance name from the folder's name; "design" when nothing usable is left. */
 export function defaultInstanceName(root) {
-    const name = path.basename(path.resolve(root)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^[^a-z]+/, "").slice(0, 31);
+    const name = path
+        .basename(path.resolve(root))
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 31);
     return name.length > 0 ? name : "design";
 }
 /**
@@ -18,15 +23,35 @@ export async function init(root, options = {}, deps = {}) {
         existing = await loadConfig(root);
     }
     catch (error) {
-        if (!(error instanceof ConfigError) || error.code !== "missing")
+        if (!(error instanceof ConfigError) || error.code !== "missing") {
             throw error;
+        }
+    }
+    if (existing && isExternal(existing)) {
+        return {
+            config: existing,
+            createdConfig: false,
+            createdSecrets: false,
+            files: [],
+            gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false,
+        };
     }
-    if (existing && isExternal(existing))
-        return { config: existing, createdConfig: false, createdSecrets: false, files: [], gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false };
     if (!existing && options.external) {
-        const config = validateProjectConfig({ instance: options.instance ?? defaultInstanceName(root), profile: { type: "external", origin: options.external } });
+        const config = validateProjectConfig({
+            instance: options.instance ?? defaultInstanceName(root),
+            profile: {
+                type: "external",
+                origin: options.external,
+            },
+        });
         await writeFile(path.join(root, configFileName), `${JSON.stringify(config, null, 2)}\n`);
-        return { config, createdConfig: true, createdSecrets: false, files: [], gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false };
+        return {
+            config,
+            createdConfig: true,
+            createdSecrets: false,
+            files: [],
+            gitignoreAdded: options.gitignore ? await ensureKeyFileIgnored(root) : false,
+        };
     }
     return requireLocalProfile(deps.local).init(root, options);
 }

package/dist/instance/runner.js

@@ -3,34 +3,56 @@ import { createReadStream, createWriteStream } from "node:fs";
 import { once } from "node:events";
 export const nodeRunner = {
     async run(command, args, options = {}) {
-        const child = spawn(command, args, { stdio: [options.input !== undefined || options.inFile ? "pipe" : "ignore", "pipe", "pipe"] });
+        const child = spawn(command, args, {
+            stdio: [
+                options.input !== undefined || options.inFile ? "pipe" : "ignore",
+                "pipe",
+                "pipe",
+            ],
+        });
         const { stdout: out, stderr: err } = child;
-        if (!out || !err)
+        if (!out || !err) {
             throw new Error("the command has no output streams");
+        }
         let stdout = "";
         let stderr = "";
         const writing = options.outFile ? createWriteStream(options.outFile) : undefined;
         // Registered at once: the file can finish closing before the child does, and a missed event would hang forever.
-        const written = writing ? new Promise((resolve) => writing.once("close", () => resolve())) : undefined;
-        if (writing)
+        const written = writing
+            ? new Promise((resolve) => writing.once("close", () => resolve()))
+            : undefined;
+        if (writing) {
             out.pipe(writing);
-        else
+        }
+        else {
             out.on("data", (chunk) => (stdout += chunk.toString("utf8")));
+        }
         err.on("data", (chunk) => (stderr += chunk.toString("utf8")));
-        if (options.inFile && child.stdin)
+        if (options.inFile && child.stdin) {
             createReadStream(options.inFile).pipe(child.stdin);
-        else if (options.input !== undefined && child.stdin)
+        }
+        else if (options.input !== undefined && child.stdin) {
             child.stdin.end(options.input);
+        }
         try {
             const [code] = (await once(child, "close"));
-            if (written)
+            if (written) {
                 await written;
-            return { code: code ?? 1, stdout, stderr };
+            }
+            return {
+                code: code ?? 1,
+                stdout,
+                stderr,
+            };
         }
         catch (error) {
             // The command could not start at all (not installed, not executable).
             writing?.destroy();
-            return { code: 127, stdout, stderr: String(error.message) };
+            return {
+                code: 127,
+                stdout,
+                stderr: String(error.message),
+            };
         }
     },
 };

package/dist/instance/setup.js

@@ -1,17 +1,25 @@
 import { ConfigError, isExternal, loadConfig, requireLocal } from "./config.js";
-import { connectProject, penpotAddress } from "./connect.js";
+import { connectProject, penpotAddress, } from "./connect.js";
 import { init } from "./init.js";
 import { requireLocalProfile } from "../local-profile.js";
 export const hostedOrigin = "https://design.penpot.app";
 async function chooseWhere(io, hasLocal) {
     io.say("Where is your Penpot?");
     io.say("  1  On the web: design.penpot.app (free account) or your team's own Penpot. Nothing to install. (recommended)");
-    io.say(hasLocal ? "  2  On this computer, in Docker. Works offline; needs Docker Desktop and a 2 GB download." : "  2  On this computer, in Docker. Needs the @penpair/docker package, which this install does not include.");
+    io.say(hasLocal
+        ? "  2  On this computer, in Docker. Works offline; needs Docker Desktop and a 2 GB download."
+        : "  2  On this computer, in Docker. Needs the @penpair/docker package, which this install does not include.");
     const answer = (await io.ask("Press Enter for 1, or type 2: ", "1")).trim();
-    if (answer === "2")
-        return { type: "docker" };
+    if (answer === "2") {
+        return {
+            type: "docker",
+        };
+    }
     const origin = (await io.ask(`Penpot address (Enter for ${hostedOrigin}): `, hostedOrigin)).trim();
-    return { type: "web", origin };
+    return {
+        type: "web",
+        origin,
+    };
 }
 /**
  * One guided path from nothing to "the assistant can read my Penpot file": choose where Penpot is, write the config, start
@@ -25,32 +33,57 @@ export async function setup(root, io, options) {
         io.say(`This folder is already set up for ${isExternal(config) ? `Penpot at ${config.profile.origin}` : `Penpot on this computer (port ${config.ports.frontend})`}. Continuing from there.`);
     }
     catch (error) {
-        if (!(error instanceof ConfigError) || error.code !== "missing")
+        if (!(error instanceof ConfigError) || error.code !== "missing") {
             throw error;
+        }
     }
     if (!config) {
         const where = options.where ?? (await chooseWhere(io, Boolean(options.local)));
-        const made = await init(root, { gitignore: true, instance: options.instance, port: options.port, ...(where.type === "web" ? { external: where.origin } : {}) }, { local: options.local });
+        const made = await init(root, {
+            gitignore: true,
+            instance: options.instance,
+            port: options.port,
+            ...(where.type === "web"
+                ? {
+                    external: where.origin,
+                }
+                : {}),
+        }, {
+            local: options.local,
+        });
         config = made.config;
         io.say(`Wrote penpair.config.json (${where.type === "web" ? `Penpot at ${where.origin}` : "Penpot on this computer"}). Commit that file; it holds no secrets.`);
     }
     if (!isExternal(config)) {
         const local = requireLocalProfile(options.local);
         await local.preflight(options.runner);
-        const c = { root, config: requireLocal(config), runner: options.runner, log: options.log ?? (() => undefined) };
+        const c = {
+            root,
+            config: requireLocal(config),
+            runner: options.runner,
+            log: options.log ?? (() => undefined),
+        };
         io.say("Starting Penpot. The first time it downloads about 2 GB and can take several minutes.");
         const started = await local.up(c);
-        if (!started.ready)
+        if (!started.ready) {
             throw new ConfigError(`Penpot started but ${started.url} does not answer yet. Wait a minute and run \`penpair setup\` again.`);
+        }
         io.say("Penpot is running. Create your account on its start page (no email confirmation is needed), then create a design file.");
     }
-    else
+    else {
         io.say("In Penpot: log in, then create a project and a design file for this work if you have none.");
+    }
     await io.openBrowser(penpotAddress(config)).catch(() => undefined);
-    const connect = await connectProject(root, config, io, { wait: options.wait });
+    const connect = await connectProject(root, config, io, {
+        wait: options.wait,
+    });
     io.say("Everything answers. Last: the rules your assistant follows.");
-    if (options.installSkills)
+    if (options.installSkills) {
         await options.installSkills();
+    }
     io.say("Done. Try `penpair pages`, or tell your assistant to read the penpair-design skill and start.");
-    return { config, connect };
+    return {
+        config,
+        connect,
+    };
 }

package/dist/instance/tty.js

@@ -3,14 +3,16 @@ import { nodeRunner } from "./runner.js";
 /** Reads everything piped into standard input (for `pbpaste | penpair connect`, where a key never appears in a command line). */
 async function readPiped() {
     let text = "";
-    for await (const chunk of process.stdin)
+    for await (const chunk of process.stdin) {
         text += String(chunk);
+    }
     return text.trim();
 }
 /** Asks for a secret without echoing it. With no terminal (a pipe), the whole input is the answer. */
 export async function askHidden(question) {
-    if (!process.stdin.isTTY)
+    if (!process.stdin.isTTY) {
         return readPiped();
+    }
     process.stderr.write(question);
     const stdin = process.stdin;
     stdin.setRawMode(true);
@@ -31,10 +33,12 @@ export async function askHidden(question) {
                     resolve(value.trim());
                     return;
                 }
-                if (char === "\u007f" || char === "\b")
+                if (char === "\u007f" || char === "\b") {
                     value = value.slice(0, -1);
-                else
+                }
+                else {
                     value += char;
+                }
             }
         };
         const cleanup = () => {
@@ -47,9 +51,13 @@ export async function askHidden(question) {
 }
 /** One visible line of input; the fallback is taken on an empty answer or when there is no terminal. */
 export async function askLine(question, fallback) {
-    if (!process.stdin.isTTY)
+    if (!process.stdin.isTTY) {
         return fallback;
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
     try {
         return await new Promise((resolve) => rl.question(question, (answer) => resolve(answer.trim() || fallback)));
     }
@@ -59,8 +67,18 @@ export async function askLine(question, fallback) {
 }
 export async function openInBrowser(url) {
     const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const args = process.platform === "win32"
+        ? [
+            "/c",
+            "start",
+            "",
+            url,
+        ]
+        : [
+            url,
+        ];
     const result = await nodeRunner.run(command, args);
-    if (result.code !== 0)
+    if (result.code !== 0) {
         throw new Error("Browser launch failed; open the configured public Penpot address manually.");
+    }
 }

package/dist/journal.d.ts

@@ -16,6 +16,13 @@ export interface JournalStep<T> {
     verify(current: T, before: T, result?: unknown): boolean;
     reconcile(before: T, current: T, result?: unknown): "complete" | "pending" | "conflict";
 }
+export interface JournalTraceEvent {
+    event: "lease-acquire-start" | "lease-acquired" | "lease-check" | "inspection-start" | "inspection-end" | "revision-observed" | "lease-release-start" | "lease-released" | "lease-release-failed";
+    at: string;
+    elapsedMs: number;
+    step?: number;
+    target?: JournalTarget;
+}
 export interface OperationJournal {
     schemaVersion: 1;
     engineVersion: string;
@@ -29,6 +36,7 @@ export interface OperationJournal {
     createdAt: string;
     updatedAt: string;
     redacted: boolean;
+    trace?: JournalTraceEvent[];
     checkpoint?: unknown;
     error?: string;
     steps: {
@@ -62,6 +70,8 @@ export interface JournalOptions {
     requireCheckpoint?: boolean;
     finalVerify?(): Promise<boolean>;
     redact?(text: string): string;
+    trace?: boolean;
+    onTrace?(event: JournalTraceEvent): void;
     onStep?(message: string): void;
 }
 /** Stable JSON hashing; observation comparisons may explicitly ignore transport execution metadata. */