@penpair/core 0.1.3 → 0.3.0

package/dist/instance/config.js

@@ -1,60 +1,151 @@
-import { readFile } from "node:fs/promises";
+import { validateCredentialReference } from "../credentials.js";
+import { validateAuditRules } from "../audit-rules.js";
+import { lstat, readFile } from "node:fs/promises";
 import path from "node:path";
 import { validateBaselines } from "../baselines-config.js";
 export const isExternal = (config) => "profile" in config && config.profile?.type === "external";
 export const configFileName = "penpair.config.json";
 export const testedPenpotVersion = "2.18.3";
 export class ConfigError extends Error {
+    code;
+    constructor(message, code = "invalid-config") {
+        super(message);
+        this.code = code;
+    }
 }
 export function composeProjectOf(config) {
     return config.composeProject ?? `penpair-${config.instance}`;
 }
+function validateSchemaVersion(value) {
+    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)
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return fail("must be a JSON object");
+    }
     const v = value;
-    if (typeof v.instance !== "string" || !/^[a-z][a-z0-9-]{0,30}$/.test(v.instance))
+    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")) {
+            throw new ConfigError("connection requires only a credential reference");
+        }
+        try {
+            validateCredentialReference(v.connection.credential);
+        }
+        catch (error) {
+            throw new ConfigError(String(error.message));
+        }
+    }
+    if (v.audit !== undefined) {
+        try {
+            validateAuditRules(v.audit);
+        }
+        catch (error) {
+            throw new ConfigError(String(error.message));
+        }
+    }
+    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) {
-    const profile = typeof value === "object" && value !== null ? value.profile : undefined;
-    if (profile?.type !== "external")
+    validateSchemaVersion(value);
+    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") {
+        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")) {
+            throw new ConfigError("connection requires only a credential reference");
+        }
+        try {
+            validateCredentialReference(v.connection.credential);
+        }
+        catch (error) {
+            throw new ConfigError(String(error.message));
+        }
+    }
+    if (v.audit !== undefined) {
+        try {
+            validateAuditRules(v.audit);
+        }
+        catch (error) {
+            throw new ConfigError(String(error.message));
+        }
+    }
     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 {
@@ -63,38 +154,109 @@ 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) {
+        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")) {
+        throw new ConfigError(`${configFileName}: file must have a nonempty id and an optional name`);
+    }
+}
+function validateBackup(value) {
+    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) {
+        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;
 }
-export async function loadConfig(root) {
+/** Missing is optional; unreadable, malformed or invalid project files always stop the caller. */
+export async function readProjectConfig(root) {
     let text;
     try {
         text = await readFile(path.join(root, configFileName), "utf8");
     }
-    catch {
-        throw new ConfigError(`No ${configFileName} here. Run \`penpair init\` first.`);
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            try {
+                await lstat(path.join(root, configFileName));
+            }
+            catch (statError) {
+                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");
     }
+    let parsed;
     try {
-        return validateProjectConfig(JSON.parse(text));
+        parsed = JSON.parse(text);
     }
-    catch (error) {
-        if (error instanceof ConfigError)
-            throw error;
-        throw new ConfigError(`${configFileName} is not valid JSON`);
+    catch {
+        throw new ConfigError(`${configFileName} is not valid JSON. Fix its JSON syntax, then run \`penpair config check\`.`, "invalid-json");
     }
+    validateProjectConfig(parsed);
+    return parsed;
+}
+export async function loadOptionalConfig(root) {
+    const raw = await readProjectConfig(root);
+    return raw === undefined ? undefined : validateProjectConfig(raw);
+}
+export async function loadConfig(root) {
+    const config = await loadOptionalConfig(root);
+    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) => {
     const directory = path.join(root, config.directory);

package/dist/instance/connect.d.ts

@@ -1,4 +1,4 @@
-import { type ProjectConfig } from "./config.js";
+import { type ProjectConfig, type ProjectFile } from "./config.js";
 import type { Runner } from "./runner.js";
 export declare class ConnectError extends Error {
 }
@@ -11,8 +11,11 @@ export interface ConnectIo {
     /** Looks for the editor tab and the plugin; throws until both are there. */
     openFile(url: string): Promise<{
         file: string;
+        fileId?: string;
         pages: string[];
     }>;
+    /** Optional for noninteractive hosts; a positive answer pins local config, never changes the design. */
+    confirmFile?(file: ProjectFile): Promise<boolean>;
 }
 export declare const keyVariable = "PENPAIR_MCP_URL";
 /** What was pasted, cleaned: surrounding quotes, a `PENPAIR_MCP_URL=` prefix and whitespace are tolerated. Never echoes the text in an error. */
@@ -33,6 +36,7 @@ export declare function readKeyFile(root: string): Promise<string | undefined>;
 export declare function keyFileCheck(root: string, runner: Runner): Promise<{
     check: string;
     ok: boolean;
+    warning?: boolean;
     detail: string;
     remedy?: string;
 } | undefined>;
@@ -45,12 +49,15 @@ export interface WaitOptions {
 /** Waits for the editor tab and the plugin, saying in plain words what to do, until `timeoutMs` has passed. */
 export declare function waitForEditor(url: string, io: ConnectIo, options?: WaitOptions): Promise<{
     file: string;
+    fileId?: string;
     pages: string[];
 } | undefined>;
 export interface ConnectResult {
     keyWritten: boolean;
     file?: string;
     pages?: string[];
+    fileId?: string;
+    filePinned?: boolean;
 }
 /**
  * The connection step: take the personal key without showing it, check that it belongs to this project's Penpot, store it in
@@ -60,4 +67,6 @@ export declare function connectProject(root: string, config: ProjectConfig, io:
     replace?: boolean;
     pasted?: string;
     wait?: WaitOptions;
+    anyFile?: boolean;
+    environment?: NodeJS.ProcessEnv;
 }): Promise<ConnectResult>;

package/dist/instance/connect.js

@@ -1,7 +1,8 @@
-import { chmod, readFile, writeFile } from "node:fs/promises";
+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 { isExternal } 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 {
@@ -11,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);
@@ -22,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) {
@@ -42,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");
@@ -56,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 {
@@ -78,18 +96,68 @@ export async function readKeyFile(root) {
 }
 /** Warns when .env.local exists but git would commit it. Asks git itself, so global ignore rules count. */
 export async function keyFileCheck(root, runner) {
+    let info;
     try {
-        await readFile(path.join(root, ".env.local"), "utf8");
+        info = await stat(path.join(root, ".env.local"));
     }
     catch {
         return undefined;
     }
-    const result = await runner.run("git", ["-C", root, "check-ignore", "-q", ".env.local"]);
-    if (result.code === 0)
-        return { check: "key file", ok: true, detail: ".env.local is kept out of git" };
-    if (result.code === 1)
-        return { check: "key file", ok: false, detail: ".env.local holds your personal key and git would commit it", remedy: "Add .env.local to .gitignore (penpair connect does it for you)." };
-    return { check: "key file", ok: true, detail: ".env.local exists; this folder is not a git repository" };
+    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 = {}) {
@@ -105,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;
@@ -123,7 +196,40 @@ export async function waitForEditor(url, io, options = {}) {
  * a git-ignored file, then wait for the editor and plugin and read the file's pages once. Safe to run again.
  */
 export async function connectProject(root, config, io, options = {}) {
-    let url = options.replace ? undefined : await readKeyFile(root);
+    const environment = options.environment ?? process.env;
+    let reference = config.connection?.credential;
+    if (!reference) {
+        let text = "";
+        try {
+            text = await readFile(path.join(root, ".env.local"), "utf8");
+        }
+        catch (error) {
+            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")) {
+            throw new ConnectError("Arbitrary credential commands are not enabled; configure a file or OS reference");
+        }
+    }
+    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 keyWritten = false;
     if (url) {
         let origin;
@@ -133,14 +239,22 @@ export async function connectProject(root, config, io, options = {}) {
         catch {
             origin = undefined;
         }
-        if (origin && belongsToProject(origin, config))
-            io.say("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 (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 {
             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.`);
@@ -151,8 +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) {
+        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,
+        }))) {
+        const raw = await readProjectConfig(root);
+        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`);
+        filePinned = true;
+        io.say("Pinned the design file ID in penpair.config.json. Commit that file for your team.");
+    }
+    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 };
+    return {
+        keyWritten,
+        file: editor.file,
+        pages: editor.pages,
+        fileId: editor.fileId,
+        filePinned,
+    };
 }