@penpair/core 0.2.0 → 0.3.1

package/dist/instance/config.js

@@ -17,22 +17,28 @@ export function composeProjectOf(config) {
     return config.composeProject ?? `penpair-${config.instance}`;
 }
 function validateSchemaVersion(value) {
-    if (value && typeof value === "object" && "schemaVersion" in value && value.schemaVersion !== 1)
+    if (value && typeof value === "object" && "schemaVersion" in value && value.schemaVersion !== 1) {
         throw new ConfigError("Unsupported project config schemaVersion; legacy/unversioned and v1 are supported. Use the producer's documented migration for another major version.");
+    }
 }
 export function validateConfig(value) {
     validateSchemaVersion(value);
     const fail = (message) => {
         throw new ConfigError(`${configFileName}: ${message}`);
     };
-    if (typeof value !== "object" || value === null || Array.isArray(value))
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return fail("must be a JSON object");
+    }
     const v = value;
     validateFile(v.file);
     validateBackup(v.backup);
     if (v.connection !== undefined) {
-        if (!v.connection || typeof v.connection !== "object" || Array.isArray(v.connection) || Object.keys(v.connection).some(k => k !== "credential"))
+        if (!v.connection ||
+            typeof v.connection !== "object" ||
+            Array.isArray(v.connection) ||
+            Object.keys(v.connection).some((k) => k !== "credential")) {
             throw new ConfigError("connection requires only a credential reference");
+        }
         try {
             validateCredentialReference(v.connection.credential);
         }
@@ -48,48 +54,77 @@ export function validateConfig(value) {
             throw new ConfigError(String(error.message));
         }
     }
-    if (typeof v.instance !== "string" || !/^[a-z][a-z0-9-]{0,30}$/.test(v.instance))
+    if (typeof v.instance !== "string" || !/^[a-z][a-z0-9-]{0,30}$/.test(v.instance)) {
         fail("instance must be lowercase letters, digits and hyphens, starting with a letter (at most 31 characters)");
-    if (typeof v.penpotVersion !== "string" || !/^\d+\.\d+(\.\d+)?$/.test(v.penpotVersion))
+    }
+    if (typeof v.penpotVersion !== "string" || !/^\d+\.\d+(\.\d+)?$/.test(v.penpotVersion)) {
         fail("penpotVersion must look like 2.18.3");
+    }
     const ports = v.ports;
-    for (const key of ["frontend", "mail"]) {
+    for (const key of [
+        "frontend",
+        "mail",
+    ]) {
         const port = ports?.[key];
-        if (typeof port !== "number" || !Number.isInteger(port) || port < 1024 || port > 65535)
+        if (typeof port !== "number" || !Number.isInteger(port) || port < 1024 || port > 65535) {
             fail(`ports.${key} must be a port number from 1024 to 65535`);
+        }
     }
-    if (ports.frontend === ports.mail)
+    if (ports.frontend === ports.mail) {
         fail("ports.frontend and ports.mail must differ");
-    if (typeof v.directory !== "string" || v.directory.length === 0 || path.isAbsolute(v.directory))
+    }
+    if (typeof v.directory !== "string" || v.directory.length === 0 || path.isAbsolute(v.directory)) {
         fail("directory must be a relative path");
-    if (v.composeProject !== undefined && (typeof v.composeProject !== "string" || !/^[a-z0-9][a-z0-9_-]*$/.test(v.composeProject)))
+    }
+    if (v.composeProject !== undefined &&
+        (typeof v.composeProject !== "string" || !/^[a-z0-9][a-z0-9_-]*$/.test(v.composeProject))) {
         fail("composeProject must be a valid compose project name");
+    }
     if (v.snippets !== undefined) {
-        const ok = Array.isArray(v.snippets) && v.snippets.every((entry) => typeof entry === "string" && entry.length > 0 && !path.isAbsolute(entry) && !entry.split(/[\\/]/).includes(".."));
-        if (!ok)
+        const ok = Array.isArray(v.snippets) &&
+            v.snippets.every((entry) => typeof entry === "string" &&
+                entry.length > 0 &&
+                !path.isAbsolute(entry) &&
+                !entry.split(/[\\/]/).includes(".."));
+        if (!ok) {
             fail("snippets must be a list of relative paths that stay inside the project");
+        }
     }
-    if (v.baselines !== undefined)
+    if (v.baselines !== undefined) {
         validateBaselines(v.baselines, fail);
-    if (v.adapters !== undefined && !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0)))
+    }
+    if (v.adapters !== undefined &&
+        !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0))) {
         fail("adapters must be a list of package names or relative paths");
+    }
     return v;
 }
 const instanceNamePattern = /^[a-z][a-z0-9-]{0,30}$/;
 /** Accepts either kind of project config: a local Docker instance or an external Penpot. */
 export function validateProjectConfig(value) {
     validateSchemaVersion(value);
-    const profile = typeof value === "object" && value !== null ? value.profile : undefined;
-    if (profile === undefined)
+    const profile = typeof value === "object" && value !== null
+        ? value.profile
+        : undefined;
+    if (profile === undefined) {
         return validateConfig(value);
-    if (typeof profile !== "object" || profile === null || Array.isArray(profile) || profile.type !== "external")
+    }
+    if (typeof profile !== "object" ||
+        profile === null ||
+        Array.isArray(profile) ||
+        profile.type !== "external") {
         throw new ConfigError(`${configFileName}: profile.type must be external; omit profile for an instance on this computer`);
+    }
     const v = value;
     validateFile(v.file);
     validateBackup(v.backup);
     if (v.connection !== undefined) {
-        if (!v.connection || typeof v.connection !== "object" || Array.isArray(v.connection) || Object.keys(v.connection).some(k => k !== "credential"))
+        if (!v.connection ||
+            typeof v.connection !== "object" ||
+            Array.isArray(v.connection) ||
+            Object.keys(v.connection).some((k) => k !== "credential")) {
             throw new ConfigError("connection requires only a credential reference");
+        }
         try {
             validateCredentialReference(v.connection.credential);
         }
@@ -108,8 +143,9 @@ export function validateProjectConfig(value) {
     const fail = (message) => {
         throw new ConfigError(`${configFileName}: ${message}`);
     };
-    if (typeof v.instance !== "string" || !instanceNamePattern.test(v.instance))
+    if (typeof v.instance !== "string" || !instanceNamePattern.test(v.instance)) {
         fail("instance must be lowercase letters, digits and hyphens, starting with a letter");
+    }
     const origin = v.profile.origin;
     let parsed;
     try {
@@ -118,34 +154,67 @@ export function validateProjectConfig(value) {
     catch {
         parsed = undefined;
     }
-    if (!parsed || !["http:", "https:"].includes(parsed.protocol) || parsed.origin !== origin)
+    if (!parsed ||
+        ![
+            "http:",
+            "https:",
+        ].includes(parsed.protocol) ||
+        parsed.origin !== origin) {
         fail("profile.origin must be an http or https origin such as https://design.penpot.app (no path)");
-    if (v.snippets !== undefined && !(Array.isArray(v.snippets) && v.snippets.every((entry) => typeof entry === "string" && entry.length > 0 && !path.isAbsolute(entry) && !entry.split(/[\\/]/).includes(".."))))
+    }
+    if (v.snippets !== undefined &&
+        !(Array.isArray(v.snippets) &&
+            v.snippets.every((entry) => typeof entry === "string" &&
+                entry.length > 0 &&
+                !path.isAbsolute(entry) &&
+                !entry.split(/[\\/]/).includes("..")))) {
         fail("snippets must be a list of relative paths that stay inside the project");
-    if (v.baselines !== undefined)
+    }
+    if (v.baselines !== undefined) {
         validateBaselines(v.baselines, fail);
-    if (v.adapters !== undefined && !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0)))
+    }
+    if (v.adapters !== undefined &&
+        !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0))) {
         fail("adapters must be a list of package names or relative paths");
+    }
     return v;
 }
 function validateFile(value) {
-    if (value === undefined)
+    if (value === undefined) {
         return;
+    }
     const file = value;
-    if (typeof file !== "object" || file === null || Array.isArray(file) || typeof file.id !== "string" || !file.id.trim() || (file.name !== undefined && typeof file.name !== "string"))
+    if (typeof file !== "object" ||
+        file === null ||
+        Array.isArray(file) ||
+        typeof file.id !== "string" ||
+        !file.id.trim() ||
+        (file.name !== undefined && typeof file.name !== "string")) {
         throw new ConfigError(`${configFileName}: file must have a nonempty id and an optional name`);
+    }
 }
 function validateBackup(value) {
-    if (value === undefined)
+    if (value === undefined) {
         return;
+    }
     const backup = value;
-    if (!backup || typeof backup !== "object" || Array.isArray(backup) || typeof backup.noteFile !== "string" || !backup.noteFile || path.isAbsolute(backup.noteFile) || backup.noteFile.split(/[\\/]/).includes("..") || !Number.isSafeInteger(backup.remindAfterDays) || backup.remindAfterDays <= 0)
+    if (!backup ||
+        typeof backup !== "object" ||
+        Array.isArray(backup) ||
+        typeof backup.noteFile !== "string" ||
+        !backup.noteFile ||
+        path.isAbsolute(backup.noteFile) ||
+        backup.noteFile.split(/[\\/]/).includes("..") ||
+        !Number.isSafeInteger(backup.remindAfterDays) ||
+        backup.remindAfterDays <= 0) {
         throw new ConfigError(`${configFileName}: backup needs an in-project relative noteFile and positive integer remindAfterDays`);
+    }
 }
 /** The config of a project that runs its own Penpot; anything else cannot start, stop or back up containers. */
 export function requireLocal(config) {
-    if (isExternal(config))
+    if (isExternal(config)) {
         throw new ConfigError(`This project uses a Penpot that someone else runs (${config.profile.origin}). \`up\`, \`down\`, \`status\`, \`backup\` and \`restore\` only apply to a Penpot that penpair starts for you; use Penpot's own version history and export for this one.`);
+    }
     return config;
 }
 /** Missing is optional; unreadable, malformed or invalid project files always stop the caller. */
@@ -161,8 +230,9 @@ export async function readProjectConfig(root) {
                 await lstat(path.join(root, configFileName));
             }
             catch (statError) {
-                if (statError.code === "ENOENT")
+                if (statError.code === "ENOENT") {
                     return undefined;
+                }
             }
         }
         throw new ConfigError(`Cannot read ${configFileName}${code ? ` (${code})` : ""}. Check that it is a readable file and fix its permissions.`, "unreadable");
@@ -183,8 +253,9 @@ export async function loadOptionalConfig(root) {
 }
 export async function loadConfig(root) {
     const config = await loadOptionalConfig(root);
-    if (config === undefined)
+    if (config === undefined) {
         throw new ConfigError(`No ${configFileName} here. Run \`penpair init\` first. For config-free inspection, use a read command with --standalone.`, "missing");
+    }
     return config;
 }
 export const instancePaths = (root, config) => {

package/dist/instance/connect.js

@@ -2,7 +2,7 @@ import { readCredential } from "../credentials.js";
 import { chmod, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { parseEnvFileValue } from "../endpoint.js";
-import { configFileName, isExternal, readProjectConfig } from "./config.js";
+import { configFileName, isExternal, readProjectConfig, } from "./config.js";
 import { ensureKeyFileIgnored } from "./gitignore.js";
 import { endpointIsInstance } from "./connection.js";
 export class ConnectError extends Error {
@@ -12,10 +12,13 @@ export const keyVariable = "PENPAIR_MCP_URL";
 export function parseMcpAddress(pasted) {
     let text = pasted.trim();
     const assignment = /^(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=\s*(.*)$/.exec(text);
-    if (assignment)
+    if (assignment) {
         text = (assignment[1] ?? "").trim();
-    if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))
+    }
+    if ((text.startsWith('"') && text.endsWith('"')) ||
+        (text.startsWith("'") && text.endsWith("'"))) {
         text = text.slice(1, -1).trim();
+    }
     let parsed;
     try {
         parsed = new URL(text);
@@ -23,13 +26,19 @@ export function parseMcpAddress(pasted) {
     catch {
         throw new ConnectError("That does not look like an address. Copy the whole line Penpot shows under Account, Integrations, MCP Server; it starts with https:// (or http:// for Penpot on your computer).");
     }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
         throw new ConnectError("The address must start with https:// or http://.");
-    if (!parsed.pathname.includes("/mcp"))
+    }
+    if (!parsed.pathname.includes("/mcp")) {
         throw new ConnectError("That address has no /mcp part. Copy the MCP Server address, not the address of the Penpot page.");
-    if (!parsed.searchParams.get("userToken"))
+    }
+    if (!parsed.searchParams.get("userToken")) {
         throw new ConnectError("That address has no key (userToken=...). Copy the full address from Account, Integrations, MCP Server.");
-    return { url: text, origin: parsed.origin };
+    }
+    return {
+        url: text,
+        origin: parsed.origin,
+    };
 }
 /** Whether an MCP address belongs to the Penpot this project is configured for. */
 export function belongsToProject(origin, config) {
@@ -43,7 +52,7 @@ export function belongsToProject(origin, config) {
     }
     return endpointIsInstance(origin, config);
 }
-export const penpotAddress = (config) => (isExternal(config) ? config.profile.origin : `http://127.0.0.1:${config.ports.frontend}`);
+export const penpotAddress = (config) => isExternal(config) ? config.profile.origin : `http://127.0.0.1:${config.ports.frontend}`;
 /** Writes (or replaces) the key line in .env.local, readable by the owner only, and makes sure git ignores the file. */
 export async function writeKeyFile(root, url) {
     const file = path.join(root, ".env.local");
@@ -57,17 +66,25 @@ export async function writeKeyFile(root, url) {
     const line = `${keyVariable}=${url}`;
     const lines = (text ?? "").split(/\r?\n/);
     const at = lines.findIndex((l) => new RegExp(`^\\s*(?:export\\s+)?${keyVariable}\\s*=`).test(l));
-    if (at >= 0)
+    if (at >= 0) {
         lines[at] = line;
-    else
+    }
+    else {
         lines.push(line);
-    while (lines.length > 0 && lines[lines.length - 1] === "")
+    }
+    while (lines.length > 0 && lines[lines.length - 1] === "") {
         lines.pop();
-    await writeFile(file, `${lines.join("\n")}\n`, { mode: 0o600 });
+    }
+    await writeFile(file, `${lines.join("\n")}\n`, {
+        mode: 0o600,
+    });
     await chmod(file, 0o600);
     // Ignored before anything else can happen: a key in an unignored file is one `git add .` from public.
     const ignoreAdded = await ensureKeyFileIgnored(root);
-    return { created: text === undefined, ignoreAdded };
+    return {
+        created: text === undefined,
+        ignoreAdded,
+    };
 }
 export async function readKeyFile(root) {
     try {
@@ -86,17 +103,61 @@ export async function keyFileCheck(root, runner) {
     catch {
         return undefined;
     }
-    if (process.platform !== "win32" && (info.mode & 0o077) !== 0)
-        return { check: "key file", ok: false, detail: ".env.local is group/world-readable", remedy: "Make the private connection file owner-readable only (0600) and verify repository exclusion." };
-    const ignored = await runner.run("git", ["-C", root, "check-ignore", "-q", ".env.local"]);
-    if (ignored.code === 1)
-        return { check: "key file", ok: false, detail: ".env.local is tracked or not ignored", remedy: "Keep .env.local out of Git with .gitignore; if already tracked, coordinate removal and key rotation with the owner." };
-    if (ignored.code !== 0)
-        return { check: "key file", ok: true, detail: ".env.local exists; this folder is not a git repository" };
-    const history = await runner.run("git", ["-C", root, "log", "--all", "-n", "1", "--format=%H", "--", ".env.local"]);
-    if (history.code === 0 && history.stdout.trim())
-        return { check: "key file", ok: true, warning: true, detail: ".env.local is ignored now but appears in Git history", remedy: "Rotate any exposed key through the provider UI; let the owner decide whether history remediation is needed. No historical file contents were read." };
-    return { check: "key file", ok: true, detail: ".env.local is private and kept out of git" };
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+        return {
+            check: "key file",
+            ok: false,
+            detail: ".env.local is group/world-readable",
+            remedy: "Make the private connection file owner-readable only (0600) and verify repository exclusion.",
+        };
+    }
+    const ignored = await runner.run("git", [
+        "-C",
+        root,
+        "check-ignore",
+        "-q",
+        ".env.local",
+    ]);
+    if (ignored.code === 1) {
+        return {
+            check: "key file",
+            ok: false,
+            detail: ".env.local is tracked or not ignored",
+            remedy: "Keep .env.local out of Git with .gitignore; if already tracked, coordinate removal and key rotation with the owner.",
+        };
+    }
+    if (ignored.code !== 0) {
+        return {
+            check: "key file",
+            ok: true,
+            detail: ".env.local exists; this folder is not a git repository",
+        };
+    }
+    const history = await runner.run("git", [
+        "-C",
+        root,
+        "log",
+        "--all",
+        "-n",
+        "1",
+        "--format=%H",
+        "--",
+        ".env.local",
+    ]);
+    if (history.code === 0 && history.stdout.trim()) {
+        return {
+            check: "key file",
+            ok: true,
+            warning: true,
+            detail: ".env.local is ignored now but appears in Git history",
+            remedy: "Rotate any exposed key through the provider UI; let the owner decide whether history remediation is needed. No historical file contents were read.",
+        };
+    }
+    return {
+        check: "key file",
+        ok: true,
+        detail: ".env.local is private and kept out of git",
+    };
 }
 /** Waits for the editor tab and the plugin, saying in plain words what to do, until `timeoutMs` has passed. */
 export async function waitForEditor(url, io, options = {}) {
@@ -112,13 +173,18 @@ export async function waitForEditor(url, io, options = {}) {
         catch (error) {
             if (sinceReminder >= remind) {
                 const message = String(error.message ?? error);
-                const reason = /suspended|heartbeat/i.test(message) ? "the Penpot tab is asleep or the plugin is not connected" : /refused|ECONN|fetch failed|not found/i.test(message) ? "Penpot does not answer yet" : "the editor is not connected yet";
+                const reason = /suspended|heartbeat/i.test(message)
+                    ? "the Penpot tab is asleep or the plugin is not connected"
+                    : /refused|ECONN|fetch failed|not found/i.test(message)
+                        ? "Penpot does not answer yet"
+                        : "the editor is not connected yet";
                 io.say(`Waiting for Penpot (${reason}).`);
                 io.say("  In your browser: open a design file, choose File, then MCP Server, then Connect, and keep that tab in front.");
                 sinceReminder = 0;
             }
-            if (waited >= timeout)
+            if (waited >= timeout) {
                 return undefined;
+            }
             await io.sleep(interval);
             waited += interval;
             sinceReminder += interval;
@@ -138,18 +204,32 @@ export async function connectProject(root, config, io, options = {}) {
             text = await readFile(path.join(root, ".env.local"), "utf8");
         }
         catch (error) {
-            if (error.code !== "ENOENT")
+            if (error.code !== "ENOENT") {
                 throw new ConnectError("Project connection file could not be read");
+            }
         }
         const file = environment.PENPAIR_MCP_URL_FILE?.trim() || parseEnvFileValue(text, "PENPAIR_MCP_URL_FILE");
-        if (file)
-            reference = { type: "file", path: file };
-        else if (environment.PENPAIR_MCP_URL_COMMAND || parseEnvFileValue(text, "PENPAIR_MCP_URL_COMMAND"))
+        if (file) {
+            reference = {
+                type: "file",
+                path: file,
+            };
+        }
+        else if (environment.PENPAIR_MCP_URL_COMMAND ||
+            parseEnvFileValue(text, "PENPAIR_MCP_URL_COMMAND")) {
             throw new ConnectError("Arbitrary credential commands are not enabled; configure a file or OS reference");
+        }
     }
-    if (reference && options.replace)
+    if (reference && options.replace) {
         throw new ConnectError("Rotate the configured credential in its private storage, then reconnect; --replace is for the legacy pasted-URL flow");
-    let url = reference ? await readCredential(reference, { root }) : options.replace ? undefined : await readKeyFile(root);
+    }
+    let url = reference
+        ? await readCredential(reference, {
+            root,
+        })
+        : options.replace
+            ? undefined
+            : await readKeyFile(root);
     let keyWritten = false;
     if (url) {
         let origin;
@@ -159,16 +239,22 @@ export async function connectProject(root, config, io, options = {}) {
         catch {
             origin = undefined;
         }
-        if (origin && belongsToProject(origin, config))
-            io.say(reference ? "Using the configured private credential reference; its output stays private." : "The key in .env.local belongs to this Penpot, so I will use it. (Run `penpair connect --replace` to paste a new one.)");
-        else if (reference)
+        if (origin && belongsToProject(origin, config)) {
+            io.say(reference
+                ? "Using the configured private credential reference; its output stays private."
+                : "The key in .env.local belongs to this Penpot, so I will use it. (Run `penpair connect --replace` to paste a new one.)");
+        }
+        else if (reference) {
             throw new ConnectError("Configured credential reference belongs to another or invalid Penpot origin; no fallback was used");
-        else
+        }
+        else {
             url = undefined;
+        }
     }
     if (!url) {
         io.say(`Open ${penpotAddress(config)}, log in, then go to Account, Integrations, MCP Server and switch it on. Copy the address it shows.`);
-        const pasted = options.pasted ?? (await io.askHidden("Paste the address here and press Enter (nothing is shown as you paste): "));
+        const pasted = options.pasted ??
+            (await io.askHidden("Paste the address here and press Enter (nothing is shown as you paste): "));
         const parsed = parseMcpAddress(pasted);
         if (!belongsToProject(parsed.origin, config)) {
             throw new ConnectError(`That address belongs to ${parsed.origin}, but this project uses ${penpotAddress(config)}. Copy the address from that Penpot instead.`);
@@ -179,21 +265,42 @@ export async function connectProject(root, config, io, options = {}) {
         io.say(`Saved to .env.local${written.ignoreAdded ? " and added it to .gitignore" : ""}. It is only readable by you; never share it.`);
     }
     const editor = await waitForEditor(url, io, options.wait);
-    if (!editor)
+    if (!editor) {
         throw new ConnectError("I did not see the editor within five minutes. Open a design file in Penpot, choose File, MCP Server, Connect, keep the tab in front, then run `penpair connect` again.");
-    if (config.file && config.file.id !== editor.fileId && !options.anyFile)
+    }
+    if (config.file && config.file.id !== editor.fileId && !options.anyFile) {
         throw new ConnectError(`Expected file "${config.file.name ?? config.file.id}" (${config.file.id}), connected to "${editor.file}" (${editor.fileId ?? "unknown id"}). Open the expected file and reconnect.`);
+    }
     let filePinned = false;
-    if (!config.file && editor.fileId && await io.confirmFile?.({ id: editor.fileId, name: editor.file })) {
+    if (!config.file &&
+        editor.fileId &&
+        (await io.confirmFile?.({
+            id: editor.fileId,
+            name: editor.file,
+        }))) {
         const raw = await readProjectConfig(root);
-        if (!raw || raw.file)
+        if (!raw || raw.file) {
             throw new ConnectError("The project configuration changed while connecting. Inspect it and connect again; no file pin was replaced.");
-        await writeFile(path.join(root, configFileName), `${JSON.stringify({ ...raw, file: { id: editor.fileId, name: editor.file } }, null, 2)}\n`);
+        }
+        await writeFile(path.join(root, configFileName), `${JSON.stringify({
+            ...raw,
+            file: {
+                id: editor.fileId,
+                name: editor.file,
+            },
+        }, null, 2)}\n`);
         filePinned = true;
         io.say("Pinned the design file ID in penpair.config.json. Commit that file for your team.");
     }
-    if (!config.file && !filePinned)
+    if (!config.file && !filePinned) {
         io.say("No file ID is pinned yet. Run `penpair connect --pin-file` to protect against a different file being open.");
+    }
     io.say(`Connected to the file "${editor.file}" (${editor.pages.length} page${editor.pages.length === 1 ? "" : "s"}: ${editor.pages.slice(0, 6).join(", ")}${editor.pages.length > 6 ? ", ..." : ""}).`);
-    return { keyWritten, file: editor.file, pages: editor.pages, fileId: editor.fileId, filePinned };
+    return {
+        keyWritten,
+        file: editor.file,
+        pages: editor.pages,
+        fileId: editor.fileId,
+        filePinned,
+    };
 }

package/dist/instance/connection.d.ts

@@ -10,6 +10,15 @@ export interface Check {
 export declare const frontendUrl: (config: InstanceConfig) => string;
 export interface DoctorCheck extends Check {
     warning?: boolean;
+    layer?: "origin" | "transport" | "execution" | "file-pin";
+    observedAt?: string;
+    durationMs?: number;
+    evidence?: {
+        challenge?: string;
+        pageId?: string;
+        apiVersion?: string;
+        heartbeat?: "unknown";
+    };
     remedy?: string;
     file?: {
         expected: ProjectConfig["file"] | null;
@@ -32,16 +41,28 @@ export declare function assertEndpointIsInstance(endpoint: {
     source: string;
     origin: string;
 }, config: ProjectConfig): void;
+export interface DoctorObservation {
+    file: string;
+    fileId?: string;
+    pageId?: string;
+    challenge?: string;
+    apiVersion?: string;
+}
+export interface DoctorProbeRequest {
+    challenge: string;
+    signal: AbortSignal;
+    timeoutMs: number;
+    onTransport: () => void;
+}
 export interface DoctorOptions {
-    /** Looks for the editor tab and the plugin through the MCP. `origin` is where the endpoint points, so a key for another instance is noticed. */
+    timeoutMs?: number;
     mcp?: {
         origin: string;
-        connect: () => Promise<{
-            file: string;
-            fileId?: string;
-        }>;
+        connect: (request?: DoctorProbeRequest) => Promise<DoctorObservation>;
     };
 }
+/** Readiness is a bounded fresh execution, separate from a reachable origin and connected transport. */
+export declare function doctorEditor(config: ProjectConfig, options: DoctorOptions): Promise<DoctorCheck[]>;
 /** Whether a configured MCP origin is this instance's frontend. */
 export declare function endpointIsInstance(origin: string, config: InstanceConfig): boolean;
 /** The checks that make sense for a Penpot someone else runs: it answers, the key is for it, the editor and plugin are connected. */