@penpair/core 0.1.3 → 0.3.0

package/dist/local-profile.js

@@ -2,7 +2,8 @@ import { ConfigError } from "./instance/config.js";
 /** The commands that run Penpot on this computer exist only when a package provides a profile for them. */
 export const needsLocalProfile = "Running Penpot on this computer is not part of this install. It comes with `@penpair/docker`: install it with `npm i -D @penpair/docker` and run `npx penpair …` (or, once, `npx @penpair/docker <command>`). Penpot on the web needs nothing extra.";
 export function requireLocalProfile(local) {
-    if (!local)
+    if (!local) {
         throw new ConfigError(needsLocalProfile);
+    }
     return local;
 }

package/dist/mcp-server.d.ts

@@ -0,0 +1,12 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type CliOptions } from "./cli-main.js";
+export interface McpOptions {
+    root: string;
+    allowWrites?: boolean;
+    cli?: CliOptions;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+/** Long-lived server with an immutable explicit root and no process.chdir or raw-code tool. */
+export declare function createMcpServer(options: McpOptions): Promise<Server>;
+export declare function serveMcp(options: McpOptions): Promise<Server>;

package/dist/mcp-server.js

@@ -0,0 +1,415 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { runCommand } from "./cli-main.js";
+import { loadConfig } from "./instance/config.js";
+import { resolveProjectOutput } from "./project-input.js";
+import { collectCommand } from "./command-result.js";
+import { version } from "./version.js";
+const string = {
+    type: "string",
+    minLength: 1,
+    maxLength: 1000,
+};
+const integer = (max) => ({
+    type: "integer",
+    minimum: 0,
+    maximum: max,
+});
+const definitions = [
+    {
+        name: "pages",
+        description: "List pages in the pinned project file",
+        properties: {},
+        required: [],
+        command: () => [
+            "pages",
+        ],
+    },
+    {
+        name: "tree",
+        description: "Bounded tree preview; omitted nodes are explicit",
+        properties: {
+            page: string,
+            depth: integer(100),
+        },
+        required: [
+            "page",
+        ],
+        command: (a) => [
+            "tree",
+            "--page",
+            String(a.page),
+            "--depth",
+            String(a.depth ?? 5),
+        ],
+    },
+    {
+        name: "audit",
+        description: "Inspect layout/token findings with documented heuristic limits",
+        properties: {
+            page: string,
+        },
+        required: [
+            "page",
+        ],
+        command: (a) => [
+            "audit",
+            "--page",
+            String(a.page),
+        ],
+    },
+    {
+        name: "inspect",
+        description: "One bounded structured inspection chunk; use returned cursor for continuation",
+        properties: {
+            page: string,
+            id: string,
+            cursor: string,
+        },
+        required: [
+            "page",
+            "id",
+        ],
+        command: (a) => [
+            "inspect",
+            String(a.id),
+            "--page",
+            String(a.page),
+            ...(a.cursor
+                ? [
+                    "--cursor",
+                    String(a.cursor),
+                ]
+                : []),
+        ],
+    },
+    {
+        name: "tokens_dump",
+        description: "Bounded token capture; completeness is explicit",
+        properties: {},
+        required: [],
+        command: () => [
+            "tokens",
+            "dump",
+            "--max-total-bytes",
+            "131072",
+        ],
+    },
+    {
+        name: "run_status",
+        description: "Inspect an explicit local recovery journal",
+        properties: {
+            id: string,
+        },
+        required: [
+            "id",
+        ],
+        command: (a) => [
+            "runs",
+            String(a.id),
+        ],
+    },
+    {
+        name: "baselines_status",
+        description: "Offline coverage/evidence status; no capture or approval",
+        properties: {},
+        required: [],
+        command: () => [
+            "baselines",
+            "coverage",
+        ],
+    },
+    {
+        name: "project_status",
+        description: "Project health with explicit unknowns; no adapter imports",
+        properties: {},
+        required: [],
+        command: () => [
+            "status",
+        ],
+    },
+    {
+        name: "doctor",
+        description: "Project connection/file identity diagnostics",
+        properties: {},
+        required: [],
+        command: () => [
+            "doctor",
+        ],
+    },
+    {
+        name: "design_spec",
+        description: "Derived handoff for an exact frame ID; unknown semantics remain explicit",
+        properties: {
+            page: string,
+            id: string,
+        },
+        required: [
+            "page",
+            "id",
+        ],
+        command: (a) => [
+            "spec",
+            "--page",
+            String(a.page),
+            "--frame",
+            String(a.id),
+        ],
+    },
+    {
+        name: "export",
+        description: "Capture stable PNG to a relative path inside the project; creates a local file",
+        properties: {
+            page: string,
+            id: string,
+            out: string,
+        },
+        required: [
+            "page",
+            "id",
+            "out",
+        ],
+        command: (a) => [
+            "export",
+            String(a.id),
+            String(a.out),
+            "--page",
+            String(a.page),
+        ],
+        localWrite: true,
+    },
+    {
+        name: "run_registered",
+        description: "Execute a trusted registered operation: inspect by default, explicit apply and recovery for writes. Not a sandbox.",
+        properties: {
+            name: string,
+            params: {
+                type: "object",
+                additionalProperties: {
+                    type: "string",
+                    maxLength: 4000,
+                },
+                maxProperties: 100,
+            },
+            apply: {
+                type: "boolean",
+                default: false,
+            },
+            resume: string,
+            checkpoint: {
+                type: "boolean",
+                default: false,
+            },
+        },
+        required: [
+            "name",
+        ],
+        write: true,
+        command: (a) => [
+            "run",
+            String(a.name),
+            ...Object.entries(a.params ?? {}).flatMap(([k, v]) => [
+                "--param",
+                `${k}=${v}`,
+            ]),
+            ...(a.apply
+                ? [
+                    "--apply",
+                ]
+                : []),
+            ...(a.resume
+                ? [
+                    "--resume",
+                    String(a.resume),
+                ]
+                : []),
+            ...(a.checkpoint
+                ? [
+                    "--checkpoint",
+                ]
+                : []),
+        ],
+    },
+];
+function validate(def, raw) {
+    if (raw === undefined) {
+        raw = {};
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("Tool arguments must be an object");
+    }
+    const a = raw;
+    for (const key of def.required) {
+        if (!(key in a)) {
+            throw new Error(`Missing ${key}`);
+        }
+    }
+    for (const [key, value] of Object.entries(a)) {
+        const schema = def.properties[key];
+        if (!schema) {
+            throw new Error(`Unexpected tool argument ${key}`);
+        }
+        if (schema.type === "string" &&
+            (typeof value !== "string" ||
+                !value ||
+                value.startsWith("-") ||
+                value.length > (schema.maxLength ?? 1000) ||
+                /[\x00-\x1f]/.test(value))) {
+            throw new Error(`Invalid ${key}`);
+        }
+        if (schema.type === "boolean" && typeof value !== "boolean") {
+            throw new Error(`Invalid ${key}`);
+        }
+        if (schema.type === "integer" &&
+            (!Number.isInteger(value) || Number(value) < 0 || Number(value) > schema.maximum)) {
+            throw new Error(`Invalid ${key}`);
+        }
+        if (key === "params" &&
+            (!value ||
+                typeof value !== "object" ||
+                Array.isArray(value) ||
+                Object.keys(value).length > 100 ||
+                Object.entries(value).some(([k, v]) => !/^[a-zA-Z][\w-]{0,100}$/.test(k) || typeof v !== "string" || v.length > 4000))) {
+            throw new Error("Invalid registered parameters");
+        }
+    }
+    if ((a.resume || a.checkpoint) && !a.apply) {
+        throw new Error("Explicit resume requires apply");
+    }
+    return a;
+}
+/** Long-lived server with an immutable explicit root and no process.chdir or raw-code tool. */
+export async function createMcpServer(options) {
+    if (!path.isAbsolute(options.root)) {
+        throw new Error("MCP project root must be absolute");
+    }
+    const root = await realpath(options.root);
+    const config = await loadConfig(root);
+    if (!config.file?.id) {
+        throw new Error("MCP server requires a configured owner-confirmed file pin");
+    }
+    const pinned = {
+        instance: config.instance,
+        fileId: config.file.id,
+        profile: JSON.stringify("profile" in config ? config.profile : null),
+    };
+    const timeout = options.timeoutMs ?? 60000;
+    const limit = options.maxOutputBytes ?? 256 * 1024;
+    if (!Number.isInteger(timeout) ||
+        timeout < 1 ||
+        timeout > 300000 ||
+        !Number.isInteger(limit) ||
+        limit < 1024 ||
+        limit > 1024 * 1024) {
+        throw new Error("Invalid MCP budgets");
+    }
+    const available = definitions.filter((d) => !d.write || options.allowWrites);
+    const server = new Server({
+        name: "penpair",
+        version,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    const tools = available.map((d) => ({
+        name: d.name,
+        description: d.description,
+        inputSchema: {
+            type: "object",
+            properties: d.properties,
+            required: d.required,
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: !d.write && !d.localWrite,
+            destructiveHint: Boolean(d.write || d.localWrite),
+            idempotentHint: !d.write && !d.localWrite,
+            openWorldHint: true,
+        },
+    }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const controller = new AbortController();
+        const abort = () => controller.abort(extra.signal.reason);
+        extra.signal.addEventListener("abort", abort, {
+            once: true,
+        });
+        if (extra.signal.aborted) {
+            abort();
+        }
+        const timer = setTimeout(() => controller.abort(Object.assign(new Error("MCP command deadline exceeded"), {
+            code: "deadline",
+        })), timeout);
+        let result;
+        try {
+            const def = available.find((d) => d.name === request.params.name);
+            if (!def) {
+                throw new Error("Unknown or disabled tool");
+            }
+            const args = validate(def, request.params.arguments);
+            const current = await loadConfig(root);
+            if (current.instance !== pinned.instance ||
+                current.file?.id !== pinned.fileId ||
+                JSON.stringify("profile" in current ? current.profile : null) !== pinned.profile) {
+                throw new Error("Pinned project target changed; restart and explicitly review server configuration");
+            }
+            if (def.localWrite) {
+                args.out = await resolveProjectOutput(root, String(args.out));
+            }
+            result = await runCommand(def.command(args), {
+                ...options.cli,
+                root,
+                projectEndpointOnly: true,
+                pinnedConfig: config,
+                strictFileGuard: true,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            result = await collectCommand(request.params.name, async () => {
+                throw error;
+            });
+        }
+        finally {
+            clearTimeout(timer);
+            extra.signal.removeEventListener("abort", abort);
+        }
+        if (Buffer.byteLength(JSON.stringify(result), "utf8") > limit) {
+            result = {
+                ...result,
+                outcome: result.outcome === "uncertain" ? "uncertain" : "incomplete",
+                exitCode: result.outcome === "uncertain" ? 4 : 3,
+                data: null,
+                messages: [],
+                warnings: [],
+                errors: [],
+                completeness: {
+                    complete: false,
+                    reason: "MCP response byte budget exceeded; use a narrower inspection or the CLI artifact path",
+                },
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result),
+                },
+            ],
+            structuredContent: result,
+            isError: result.exitCode !== 0,
+        };
+    });
+    return server;
+}
+export async function serveMcp(options) {
+    const server = await createMcpServer(options);
+    await server.connect(new StdioServerTransport());
+    return server;
+}

package/dist/native-api.d.ts

@@ -0,0 +1,15 @@
+import type { PenpotToolClient } from "./client.js";
+import { type OperationReport, type OperationOptions } from "./operation.js";
+export declare function validateFileIntegrity(client: PenpotToolClient): Promise<{
+    supported: boolean;
+    valid?: boolean;
+    issues?: unknown[];
+}>;
+/** Version history is a recovery aid, never a substitute for a restored independent backup. */
+export declare function createCheckpoint(client: PenpotToolClient, checkpoint: {
+    label: string;
+    runId: string;
+}, options?: OperationOptions): Promise<{
+    supported: boolean;
+    report?: OperationReport;
+}>;

package/dist/native-api.js

@@ -0,0 +1,78 @@
+import { runOperation } from "./operation.js";
+import { runSnippet, snippet } from "./snippet.js";
+export async function validateFileIntegrity(client) {
+    const result = await runSnippet(client, snippet("file-integrity", `
+if (typeof penpot.currentFile.validate !== "function") return { ok: true, supported: false };
+const issues = penpot.currentFile.validate();
+if (!Array.isArray(issues)) return { ok: false, message: "file.validate returned no issue list" };
+return { ok: true, supported: true, valid: issues.length === 0, issues };`, {}, "read"));
+    if (typeof result.supported !== "boolean") {
+        throw new Error("Integrity check returned no capability result");
+    }
+    if (result.supported &&
+        (!Array.isArray(result.issues) ||
+            typeof result.valid !== "boolean" ||
+            result.valid !== (result.issues.length === 0))) {
+        throw new Error("Integrity check returned incomplete or contradictory observations");
+    }
+    return {
+        supported: result.supported,
+        ...(result.supported
+            ? {
+                valid: result.valid === true,
+                issues: result.issues,
+            }
+            : {}),
+    };
+}
+/** Version history is a recovery aid, never a substitute for a restored independent backup. */
+export async function createCheckpoint(client, checkpoint, options = {}) {
+    if (!checkpoint.label.trim() ||
+        checkpoint.label.length > 120 ||
+        !/^[a-zA-Z0-9-]{1,100}$/.test(checkpoint.runId)) {
+        throw new Error("A checkpoint requires a short label and a stable alphanumeric/hyphen run ID");
+    }
+    const capability = await runSnippet(client, snippet("checkpoint-capability", `return { ok: true, fileId: penpot.currentFile.id, supported: typeof penpot.currentFile.saveVersion === "function" && typeof penpot.currentFile.findVersions === "function" };`, {}, "read"));
+    if (capability.ok !== true ||
+        typeof capability.supported !== "boolean" ||
+        typeof capability.fileId !== "string") {
+        throw new Error("Checkpoint capability returned no target/presence observations");
+    }
+    if (capability.supported !== true) {
+        return {
+            supported: false,
+        };
+    }
+    const params = {
+        label: `penpair/${checkpoint.runId}/${checkpoint.label}`,
+        fileId: capability.fileId,
+    };
+    const guard = 'if (penpot.currentFile.id !== CFG.fileId) return { ok: false, message: "checkpoint file changed" };';
+    const listing = `${guard}
+const versions = (await penpot.currentFile.findVersions()).filter((version) => version.label === CFG.label);
+return { ok: true, fileId: penpot.currentFile.id, versions: versions.map((version) => ({ label: version.label, createdAt: String(version.createdAt) })) };`;
+    const report = await runOperation(client, {
+        name: "checkpoint",
+        page: () => undefined,
+        inspect: () => snippet("checkpoint-inspect", listing, params, "read"),
+        apply: () => snippet("checkpoint-apply", `${guard}
+const versions = (await penpot.currentFile.findVersions()).filter((version) => version.label === CFG.label);
+if (versions.length > 1) return { ok: false, message: "checkpoint label is ambiguous" };
+if (versions.length === 1) return { ok: true, existed: true };
+await penpot.currentFile.saveVersion(CFG.label);
+return { ok: true, created: true };`, params, "write"),
+        readback: () => snippet("checkpoint-readback", listing, params, "read"),
+        verify: ({ readback }) => readback.fileId === params.fileId &&
+            Array.isArray(readback.versions) &&
+            readback.versions.length === 1 &&
+            readback.versions[0]?.label === params.label
+            ? []
+            : [
+                "Checkpoint was not independently found once in the intended file",
+            ],
+    }, undefined, options);
+    return {
+        supported: true,
+        report,
+    };
+}

package/dist/onboard.d.ts

@@ -0,0 +1,10 @@
+import { type ProjectConfig } from "./instance/config.js";
+export declare function onboardingChecklist(config: ProjectConfig): {
+    schemaVersion: 1;
+    project: string;
+    origin: string;
+    file: ProjectConfig["file"] | null;
+    fileUrl: string | null;
+    steps: string[];
+    warnings: string[];
+};

package/dist/onboard.js

@@ -0,0 +1,41 @@
+import { isExternal } from "./instance/config.js";
+export function onboardingChecklist(config) {
+    const origin = isExternal(config)
+        ? config.profile.origin
+        : `http://localhost:${config.ports.frontend}`;
+    const fileUrl = config.file
+        ? `${origin}/#/workspace?file-id=${encodeURIComponent(config.file.id)}`
+        : null;
+    return {
+        schemaVersion: 1,
+        project: config.instance,
+        origin,
+        file: config.file ?? null,
+        fileUrl,
+        steps: [
+            "Clone the project and install its locked dependencies with the repository's package manager.",
+            `Ask the owner to invite your own Penpot account to the shared file at ${origin}.`,
+            "Create your own personal MCP key. Keep it out of chat, commits and command arguments.",
+            "Run the project's penpair connect command; enter your own key in its hidden prompt.",
+            config.file
+                ? `Open ${config.file.name || config.file.id} (${config.file.id}). Use the owner's full editor link if the direct file link needs team context.`
+                : "Ask the owner to pin the shared file with penpair connect --pin-file and commit the pin.",
+            "Open the Penpot MCP plugin and Connect. Keep the editor tab open and awake.",
+            "Run penpair doctor --json, then a read-only penpair pages before proposing writes.",
+            "Coordinate a write window with colleagues. Inspect the plan, apply once, verify independently and review the export.",
+        ],
+        warnings: [
+            ...(!isExternal(config)
+                ? [
+                    "localhost is this computer only. A colleague needs access to a shared reachable deployment; do not share generated instance secrets.",
+                ]
+                : []),
+            ...(!config.file
+                ? [
+                    "No shared file ID is pinned yet.",
+                ]
+                : []),
+            "Writer markers are advisory and do not block human editing or guarantee exclusion across machines.",
+        ],
+    };
+}

package/dist/operation.d.ts

@@ -1,6 +1,8 @@
+import { type LayoutOptions, type LayoutResult } from "./layout.js";
 import type { ExecuteOptions, PenpotToolClient } from "./client.js";
 import { type Snippet, type SnippetResult } from "./snippet.js";
 import { type ArchiveParams } from "./snippets/archive.js";
+import { type JournalOptions } from "./journal.js";
 /**
  * A Penpot change done the safe way: look first, change once, read back independently. `verify` compares the three
  * results and returns what is wrong; an empty list means the change is confirmed.
@@ -10,15 +12,24 @@ export interface Operation<P> {
     /** The page the operation works on, so the runner can open it. */
     page(params: P): string | undefined;
     inspect(params: P): Snippet;
-    apply(params: P): Snippet;
+    apply(params: P, inspected?: SnippetResult): Snippet;
     readback(params: P): Snippet;
     verify(results: {
         inspect: SnippetResult;
         apply: SnippetResult;
         readback: SnippetResult;
     }): string[];
+    /** Explicit reconciliation of a partial write; absent it, only unchanged inputs or independently verified final state may resume. */
+    reconcile?(results: {
+        before: SnippetResult;
+        current: SnippetResult;
+        readback: SnippetResult;
+    }): "complete" | "pending" | "conflict";
 }
 export interface OperationOptions extends ExecuteOptions {
+    /** Explicit opt-out is for callers that provide their own settling evidence. */
+    layout?: false | LayoutOptions;
+    journal?: Omit<JournalOptions, "operation" | "input" | "target">;
     /** Without it only the read-only inspect runs. */
     apply?: boolean;
     /** Wait between the write and the readback: token resolution and layout settle slowly. */
@@ -26,6 +37,14 @@ export interface OperationOptions extends ExecuteOptions {
     onStep?: (message: string) => void;
 }
 export interface OperationReport {
+    complete?: boolean;
+    redacted?: boolean;
+    layout?: LayoutResult;
+    journal?: {
+        runId: string;
+        state: string;
+    };
+    outcome: "inspected" | "verified" | "failed";
     operation: string;
     phase: "inspected" | "applied";
     inspect: SnippetResult;
@@ -34,8 +53,8 @@ export interface OperationReport {
     problems: string[];
     verified: boolean;
 }
-/** Runs a snippet; if the editor shows another page, opens the right one, waits, and tries once more. */
-export declare function runOnPage(client: PenpotToolClient, s: Snippet, page: string | undefined, { settleMs, sleep, onStep, ...execute }?: OperationOptions): Promise<SnippetResult>;
+/** Runs once on the expected page; page transitions require independently observed IDs. */
+export declare function runOnPage(client: PenpotToolClient, s: Snippet, page: string | undefined, { settleMs: _settleMs, sleep, onStep, ...execute }?: OperationOptions): Promise<SnippetResult>;
 export declare function runOperation<P>(client: PenpotToolClient, operation: Operation<P>, params: P, options?: OperationOptions): Promise<OperationReport>;
 /** Nests the frames that are not part of the live work into one archive board. Frames keep their names, ids and component links. */
 export declare const archiveOperation: Operation<ArchiveParams>;