@penpair/core 0.1.2 → 0.2.0

package/dist/instance/config.js

@@ -1,21 +1,53 @@
-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;
+    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))
@@ -46,10 +78,33 @@ export function validateConfig(value) {
 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?.type !== "external")
+    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}`);
     };
@@ -73,28 +128,64 @@ export function validateProjectConfig(value) {
         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))
         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 {
@@ -78,18 +79,24 @@ 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 = {}) {
@@ -123,7 +130,26 @@ 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;
@@ -134,7 +160,9 @@ export async function connectProject(root, config, io, options = {}) {
             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.)");
+            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;
     }
@@ -153,6 +181,19 @@ export async function connectProject(root, config, io, options = {}) {
     const editor = await waitForEditor(url, io, options.wait);
     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 };
 }

package/dist/instance/connection.d.ts

@@ -9,8 +9,21 @@ export interface Check {
 }
 export declare const frontendUrl: (config: InstanceConfig) => string;
 export interface DoctorCheck extends Check {
+    warning?: boolean;
     remedy?: string;
+    file?: {
+        expected: ProjectConfig["file"] | null;
+        actual: {
+            id?: string;
+            name: string;
+        };
+        ok: boolean;
+    };
 }
+export declare function fileIdentityCheck(config: ProjectConfig, actual: {
+    file: string;
+    fileId?: string;
+}): DoctorCheck;
 /**
  * A command that acts on a Penpot file must act on this project's instance. A key left in the agent's global configuration
  * (or any other key) can point at a different instance and silently drive the wrong file, so a mismatch is refused.
@@ -25,6 +38,7 @@ export interface DoctorOptions {
         origin: string;
         connect: () => Promise<{
             file: string;
+            fileId?: string;
         }>;
     };
 }

package/dist/instance/connection.js

@@ -3,6 +3,14 @@ import { isExternal } from "./config.js";
 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 },
+    };
+}
 /**
  * A command that acts on a Penpot file must act on this project's instance. A key left in the agent's global configuration
  * (or any other key) can point at a different instance and silently drive the wrong file, so a mismatch is refused.
@@ -56,11 +64,14 @@ export async function doctorExternal(config, options = {}) {
         return out;
     }
     try {
-        const { file } = await options.mcp.connect();
+        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.");
+        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.");
     }
     return out;
 }

package/dist/instance/init.js

@@ -18,7 +18,7 @@ export async function init(root, options = {}, deps = {}) {
         existing = await loadConfig(root);
     }
     catch (error) {
-        if (!(error instanceof ConfigError) || !/No penpair\.config\.json/.test(error.message))
+        if (!(error instanceof ConfigError) || error.code !== "missing")
             throw error;
     }
     if (existing && isExternal(existing))

package/dist/instance/setup.js

@@ -25,7 +25,7 @@ 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) || !/No penpair\.config\.json/.test(error.message))
+        if (!(error instanceof ConfigError) || error.code !== "missing")
             throw error;
     }
     if (!config) {

package/dist/instance/tty.js

@@ -60,5 +60,7 @@ 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];
-    await nodeRunner.run(command, args);
+    const result = await nodeRunner.run(command, args);
+    if (result.code !== 0)
+        throw new Error("Browser launch failed; open the configured public Penpot address manually.");
 }

package/dist/journal.d.ts

@@ -0,0 +1,77 @@
+import type { WriteLease } from "./coordination.js";
+import type { PenpotToolClient } from "./client.js";
+export interface JournalTarget {
+    fileId: string;
+    revision?: number;
+}
+export declare function readJournalTarget(client: PenpotToolClient): Promise<JournalTarget>;
+export interface JournalStep<T> {
+    key: string;
+    label: string;
+    /** Source/signature identifying the implementation of this step, not only its display name. */
+    signature: string;
+    initial?: T;
+    inspect(): Promise<T>;
+    apply(current: T, target: JournalTarget): Promise<unknown>;
+    verify(current: T, before: T, result?: unknown): boolean;
+    reconcile(before: T, current: T, result?: unknown): "complete" | "pending" | "conflict";
+}
+export interface OperationJournal {
+    schemaVersion: 1;
+    engineVersion: string;
+    runId: string;
+    operation: string;
+    inputHash: string;
+    planHash: string;
+    payload?: unknown;
+    target: JournalTarget;
+    state: "planned" | "running" | "uncertain" | "failed" | "conflict" | "verified";
+    createdAt: string;
+    updatedAt: string;
+    redacted: boolean;
+    checkpoint?: unknown;
+    error?: string;
+    steps: {
+        key: string;
+        label: string;
+        state: "pending" | "started" | "completed" | "uncertain" | "failed";
+        before: unknown;
+        after?: unknown;
+        targetBefore?: JournalTarget;
+        targetAfter?: JournalTarget;
+        result?: unknown;
+        error?: string;
+    }[];
+}
+export interface JournalOptions {
+    root: string;
+    forceLock?: boolean;
+    coordinate?(runId: string, target: JournalTarget): Promise<WriteLease>;
+    operation: string;
+    input: unknown;
+    payload?: unknown;
+    runId?: string;
+    resume?: boolean;
+    target(): Promise<JournalTarget>;
+    checkpoint?(runId: string): Promise<{
+        supported: boolean;
+        report?: {
+            verified: boolean;
+        };
+    }>;
+    requireCheckpoint?: boolean;
+    finalVerify?(): Promise<boolean>;
+    redact?(text: string): string;
+    onStep?(message: string): void;
+}
+/** Stable JSON hashing; observation comparisons may explicitly ignore transport execution metadata. */
+export declare function observationHash(value: unknown, ignoreExecution?: boolean): string;
+export declare function readJournal(root: string, runId: string): Promise<OperationJournal>;
+export declare function listJournals(root: string): Promise<Pick<OperationJournal, "runId" | "operation" | "state" | "target" | "updatedAt">[]>;
+export declare class JournalRunError extends Error {
+    readonly runId: string;
+    readonly outcome: OperationJournal["state"];
+    constructor(runId: string, outcome: OperationJournal["state"], message: string);
+}
+/** Each started phase is persisted before its write. Resume must inspect and reconcile actual state, never replay blindly. */
+export declare function runJournaledSteps<T>(steps: JournalStep<T>[], options: JournalOptions): Promise<OperationJournal>;