@penpair/core 0.1.2 → 0.2.0

package/dist/mcp-server.js

@@ -0,0 +1,102 @@
+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), 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, 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,42 @@
+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,15 @@
+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;

package/dist/operation.js

@@ -1,7 +1,14 @@
+import { waitForStableLayout } from "./layout.js";
+import { commandSleep } from "./command-result.js";
 import { runSnippet } from "./snippet.js";
 import { switchPage } from "./snippets/read.js";
 import { archiveApply, archiveInspect, archiveReadback } from "./snippets/archive.js";
-const defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+import { PenpairError } from "./errors.js";
+import { UncertainExecutionError } from "./client.js";
+import { observationHash, readJournalTarget, runJournaledSteps } from "./journal.js";
+import { guardRevision, writeCoordinator } from "./coordination.js";
+import { guardFile } from "./file-guard.js";
+const defaultSleep = commandSleep;
 /** Runs a snippet; if the editor shows another page, opens the right one, waits, and tries once more. */
 export async function runOnPage(client, s, page, { settleMs = 3_000, sleep = defaultSleep, onStep, ...execute } = {}) {
     const first = await runSnippet(client, s, execute);
@@ -16,33 +23,107 @@ export async function runOnPage(client, s, page, { settleMs = 3_000, sleep = def
     return second;
 }
 export async function runOperation(client, operation, params, options = {}) {
-    const { settleMs = 10_000, sleep = defaultSleep, onStep } = options;
+    if (options.settleMs !== undefined && (!Number.isFinite(options.settleMs) || options.settleMs < 0 || options.settleMs > 30000))
+        throw new Error("Minimum settle delay must be from 0 to 30000 ms");
+    if (options.apply && options.journal)
+        return journaledOperation(client, operation, params, options);
+    const { settleMs = 0, sleep = defaultSleep, onStep } = options;
     const page = operation.page(params);
     onStep?.(`${operation.name}: inspecting`);
-    const inspect = await runOnPage(client, operation.inspect(params), page, options);
+    const inspect = await runOnPage(client, operation.inspect(params), page, { ...options, effect: "read" });
+    if (inspect.ok !== true)
+        throw new PenpairError("tool-failed", `${operation.name}: inspect did not return an explicit ok result; nothing was applied`);
     if (!options.apply)
-        return { operation: operation.name, phase: "inspected", inspect, problems: [], verified: false };
+        return { operation: operation.name, outcome: "inspected", phase: "inspected", inspect, problems: [], verified: false };
     onStep?.(`${operation.name}: writing once`);
-    const apply = await runOnPage(client, operation.apply(params), page, options);
-    onStep?.(`${operation.name}: waiting ${Math.round(settleMs / 1000)} s before reading back`);
-    await sleep(settleMs);
-    const readback = await runOnPage(client, operation.readback(params), page, options);
-    const problems = operation.verify({ inspect, apply, readback });
-    return { operation: operation.name, phase: "applied", inspect, apply, readback, problems, verified: problems.length === 0 };
+    const apply = await runOnPage(client, operation.apply(params, inspect), page, { ...options, effect: "write" });
+    if (apply.ok !== true)
+        throw new UncertainExecutionError(String(apply.execution?.runId ?? "unknown"), `${operation.name}: apply returned no explicit acknowledgment`);
+    if (settleMs > 0)
+        await sleep(settleMs);
+    let layout;
+    let readback;
+    let problems;
+    try {
+        layout = await settleOperation(client, options);
+        readback = await runOnPage(client, operation.readback(params), page, { ...options, effect: "read" });
+        problems = verificationProblems(operation, { inspect, apply, readback });
+    }
+    catch (error) {
+        problems = [`Independent verification failed: ${error instanceof Error ? error.message : String(error)}`];
+    }
+    return { layout, operation: operation.name, phase: "applied", outcome: problems.length === 0 ? "verified" : "failed", inspect, apply, readback, problems, verified: problems.length === 0 };
+}
+function verificationProblems(operation, results) {
+    const { readback } = results;
+    const observations = Object.keys(readback).filter((key) => !["ok", "readOnly", "execution", "problems"].includes(key));
+    if (Array.isArray(readback.problems) && readback.problems.length > 0 && readback.problems.every((problem) => typeof problem === "string"))
+        return readback.problems;
+    if (readback.ok !== true || observations.length === 0)
+        return ["Readback did not provide explicit observations of the resulting state"];
+    const result = operation.verify(results);
+    return Array.isArray(result) && result.every((problem) => typeof problem === "string") ? result : ["Verifier must return a list of problems"];
+}
+async function settleOperation(client, options) {
+    if (options.layout === false)
+        return undefined;
+    options.onStep?.("waiting for bounded layout completion");
+    const layout = await waitForStableLayout(client, { sleep: options.sleep, ...options.layout });
+    if (!layout.stable)
+        throw new PenpairError("incomplete-output", `Layout did not settle: ${layout.reason ?? "unknown reason"}`);
+    return layout;
+}
+async function journaledOperation(client, operation, params, options) {
+    const page = operation.page(params);
+    await runOnPage(client, operation.inspect(params), page, { ...options, effect: "read" });
+    await settleOperation(client, options);
+    const initialTarget = await readJournalTarget(client);
+    const guarded = guardFile(client, { id: initialTarget.fileId });
+    const observe = async () => {
+        const inspection = await runOnPage(guarded, operation.inspect(params), page, { ...options, effect: "read" });
+        const layout = await settleOperation(guarded, options);
+        const readback = await runOnPage(guarded, operation.readback(params), page, { ...options, effect: "read" });
+        if (inspection.ok !== true || readback.ok !== true)
+            throw new Error("Operation inspection/readback did not acknowledge its observations");
+        return { inspection, readback, layout };
+    };
+    const verify = (current, before, result) => verificationProblems(operation, { inspect: before.inspection, apply: result ?? { ok: true, reconciled: true }, readback: current.readback }).length === 0;
+    const record = await runJournaledSteps([{ key: "apply", label: operation.name,
+            signature: [operation.inspect(params).code, operation.apply(params).code, operation.readback(params).code, operation.verify.toString(), operation.reconcile?.toString(), settleOperation.toString(), waitForStableLayout.toString()].join("\n"),
+            inspect: observe,
+            apply: async (current, target) => {
+                const result = await runOnPage(guardRevision(guarded, target), operation.apply(params, current.inspection), page, { ...options, effect: "write" });
+                if (result.ok !== true)
+                    throw new Error("Apply returned no explicit acknowledgment");
+                await (options.sleep ?? defaultSleep)(options.settleMs ?? 0);
+                return result;
+            }, verify,
+            reconcile: (before, current, result) => {
+                if (verify(current, before, result))
+                    return "complete";
+                if (operation.reconcile)
+                    return operation.reconcile({ before: before.inspection, current: current.inspection, readback: current.readback });
+                return observationHash(before.inspection, true) === observationHash(current.inspection, true) ? "pending" : "conflict";
+            },
+        }], { ...options.journal, coordinate: writeCoordinator(guarded, { root: options.journal.root, operation: operation.name, forceLock: options.journal.forceLock, warn: options.onStep }), operation: operation.name, input: { params, layout: options.layout ?? {}, minimumWaitMs: options.settleMs ?? 0 }, payload: { params }, target: () => readJournalTarget(guarded), onStep: options.onStep ?? options.journal.onStep, redact: options.redact ?? options.journal.redact });
+    const saved = record.steps[0];
+    return { layout: saved.after.layout, operation: operation.name, phase: "applied", outcome: record.redacted ? "failed" : "verified", ...(record.redacted ? { redacted: true, complete: false } : {}), inspect: saved.before.inspection, apply: saved.result, readback: saved.after.readback, problems: record.redacted ? ["Journal evidence required credential redaction; completeness cannot be confirmed"] : [], verified: !record.redacted, journal: { runId: record.runId, state: record.state } };
 }
 /** Nests the frames that are not part of the live work into one archive board. Frames keep their names, ids and component links. */
 export const archiveOperation = {
     name: "archive",
     page: (params) => params.page,
     inspect: archiveInspect,
-    apply: archiveApply,
+    apply: (params, inspected) => archiveApply({ ...params, expectedPlan: inspected?.plan, expectedArchiveId: inspected?.archiveId }),
     readback: archiveReadback,
     verify({ inspect, apply, readback }) {
         const problems = [];
+        if (!Number.isInteger(inspect.willMove) || Number(inspect.willMove) < 0 || !Array.isArray(inspect.plan) || !Array.isArray(readback.insideIds) || !Array.isArray(readback.loose))
+            return ["Archive verification is missing movement counts or the independent loose-frame listing"];
         const expected = Number(inspect.willMove ?? 0);
         const archive = readback.archive;
-        if (expected > 0 && Number(apply.moved ?? 0) !== expected)
-            problems.push(`moved ${apply.moved} frames, expected ${expected}`);
+        if (inspect.plan.length !== expected || inspect.plan.some((shape) => !shape.id || !readback.insideIds.includes(shape.id)))
+            problems.push("the inspected frames are not all in the archive");
         if (expected > 0 && !archive)
             problems.push("the archive board is not on the page");
         if (archive && archive.children < expected)
@@ -52,4 +133,23 @@ export const archiveOperation = {
             problems.push(`${loose.length} frames are still loose on the page: ${loose.slice(0, 3).join(", ")}`);
         return problems;
     },
+    reconcile({ before, current, readback }) {
+        if (!Array.isArray(before.plan) || !Array.isArray(current.plan) || !Array.isArray(readback.insideIds))
+            return "conflict";
+        if (observationHash(before, true) === observationHash(current, true))
+            return "pending";
+        const original = before.plan;
+        const remaining = current.plan;
+        const intended = new Map(original.map((shape) => [shape.id, shape]));
+        if (remaining.some((shape) => !intended.has(shape.id) || observationHash(shape) !== observationHash(intended.get(shape.id))))
+            return "conflict";
+        const accounted = new Set([...remaining.map((shape) => shape.id), ...readback.insideIds]);
+        if (original.some((shape) => !accounted.has(shape.id)))
+            return "conflict";
+        if (remaining.length > 0 && (!before.archiveId || before.archiveId !== current.archiveId))
+            return "conflict";
+        if (Array.isArray(before.insideIds) && before.insideIds.some((id) => !readback.insideIds.includes(id)))
+            return "conflict";
+        return remaining.length === 0 ? "complete" : "pending";
+    },
 };

package/dist/png.d.ts

@@ -0,0 +1,5 @@
+/** Pixel size from a PNG's header (the IHDR chunk), or nothing when the bytes are not a PNG. */
+export declare function pngSize(buffer: Buffer): {
+    width: number;
+    height: number;
+} | undefined;

package/dist/png.js

@@ -0,0 +1,7 @@
+/** Pixel size from a PNG's header (the IHDR chunk), or nothing when the bytes are not a PNG. */
+export function pngSize(buffer) {
+    const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    if (buffer.length < 24 || !buffer.subarray(0, 8).equals(signature) || buffer.subarray(12, 16).toString("ascii") !== "IHDR")
+        return undefined;
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}

package/dist/portable-tokens.d.ts

@@ -0,0 +1,22 @@
+/** Deliberately bounded subset of the published DTCG 2025.10 format; no Penpot arithmetic or native writes. */
+export interface PortableToken {
+    path: string[];
+    type: string;
+    value: unknown;
+    description?: string;
+    extensions?: unknown;
+}
+export interface PortableTokens {
+    schemaVersion: 1;
+    kind: "portable-tokens";
+    format: "dtcg-2025.10-subset";
+    tokens: PortableToken[];
+    groups: Record<string, {
+        type?: string;
+        description?: string;
+        extensions?: unknown;
+    }>;
+    losses: string[];
+}
+export declare function importDtcg(raw: unknown): PortableTokens;
+export declare function exportDtcg(raw: unknown): Record<string, unknown>;

package/dist/portable-tokens.js

@@ -0,0 +1,134 @@
+const types = ["color", "dimension", "number", "fontFamily", "fontWeight", "typography"];
+const isObject = (v) => Boolean(v && typeof v === "object" && !Array.isArray(v));
+const aliasPath = (v) => typeof v === "string" && /^\{[^{}]+\}$/.test(v) ? v.slice(1, -1) : undefined;
+function fail(message) { throw new Error("Portable token subset: " + message); }
+export function importDtcg(raw) {
+    if (!isObject(raw) || JSON.stringify(raw).length > 8 * 1024 * 1024)
+        fail("input must be a bounded JSON object");
+    let groupCount = 0;
+    const tokens = [], groups = Object.create(null);
+    const visit = (node, path, inherited) => {
+        if (path.length > 32 || tokens.length > 10000)
+            fail("depth/token budget exceeded");
+        for (const key of Object.keys(node))
+            if (key.startsWith("$") && !["$value", "$type", "$description", "$extensions"].includes(key))
+                fail(`unsupported metadata/reference ${key}`);
+        const type = typeof node.$type === "string" ? node.$type : inherited;
+        if (node.$type !== undefined && (typeof node.$type !== "string" || !types.includes(node.$type)))
+            fail("type must be a string");
+        if (node.$description !== undefined && typeof node.$description !== "string")
+            fail("description must be a string");
+        if (node.$extensions !== undefined && !isObject(node.$extensions))
+            fail("extensions must be an object");
+        if ("$value" in node) {
+            if (!path.length || !type || !types.includes(type) || Object.keys(node).some(k => !k.startsWith("$")))
+                fail("unsupported token type or mixed token/group");
+            tokens.push({ path, type, value: structuredClone(node.$value), ...(node.$description !== undefined ? { description: node.$description } : {}), ...(node.$extensions !== undefined ? { extensions: structuredClone(node.$extensions) } : {}) });
+            return;
+        }
+        if (++groupCount > 10000)
+            fail("group budget exceeded");
+        groups[path.join(".")] = { ...(node.$type ? { type: String(node.$type) } : {}), ...(node.$description !== undefined ? { description: node.$description } : {}), ...(node.$extensions !== undefined ? { extensions: structuredClone(node.$extensions) } : {}) };
+        for (const [key, value] of Object.entries(node)) {
+            if (key.startsWith("$"))
+                continue;
+            if (!key || /[.{}\x00-\x1f]/.test(key) || !isObject(value))
+                fail("invalid token/group path");
+            visit(value, [...path, key], type);
+        }
+    };
+    visit(raw, []);
+    if (!tokens.length || tokens.length > 10000)
+        fail("requires 1–10000 tokens");
+    const portable = { schemaVersion: 1, kind: "portable-tokens", format: "dtcg-2025.10-subset", tokens: tokens.sort((a, b) => a.path.join(".").localeCompare(b.path.join("."))), groups, losses: [] };
+    validatePortableValues(portable);
+    return portable;
+}
+function validatePortableValues(document) {
+    const byPath = new Map(document.tokens.map(t => [t.path.join("."), t])), resolved = new Map();
+    if (byPath.size !== document.tokens.length)
+        fail("duplicate token path");
+    const resolveToken = (name, expected, chain) => {
+        const token = byPath.get(name);
+        if (!token || token.type !== expected)
+            fail(`missing/type-mismatched alias ${name}`);
+        if (chain.includes(name))
+            fail("alias cycle: " + [...chain, name].join(" -> "));
+        if (chain.length > 64)
+            fail("alias depth exceeds 64");
+        if (resolved.has(name))
+            return resolved.get(name);
+        const value = validateValue(token.type, token.value, [...chain, name]);
+        resolved.set(name, value);
+        return value;
+    };
+    const validateValue = (type, value, chain) => {
+        const ref = aliasPath(value);
+        if (ref !== undefined)
+            return resolveToken(ref, type, chain);
+        if (isObject(value) && "$ref" in value)
+            fail("JSON Pointer property references are outside this subset");
+        if (type === "number" && (typeof value !== "number" || !Number.isFinite(value)))
+            fail("number must be finite");
+        if (type === "fontWeight" && (typeof value !== "number" || !Number.isFinite(value) || value < 1 || value > 1000))
+            fail("fontWeight supports numeric 1–1000 only");
+        if (type === "fontFamily" && !(typeof value === "string" && value.length > 0 || Array.isArray(value) && value.length > 0 && value.length <= 100 && value.every(v => typeof v === "string" && v.length > 0)))
+            fail("fontFamily must be a name or ordered names");
+        if (type === "dimension" && (!isObject(value) || Object.keys(value).some(k => !["value", "unit"].includes(k)) || typeof value.value !== "number" || !Number.isFinite(value.value) || !["px", "rem"].includes(String(value.unit))))
+            fail("dimension supports explicit finite px/rem values");
+        if (type === "color" && (!isObject(value) || Object.keys(value).some(k => !["colorSpace", "components", "alpha", "hex"].includes(k)) || !["srgb", "display-p3"].includes(String(value.colorSpace)) || !Array.isArray(value.components) || value.components.length !== 3 || value.components.some(c => typeof c !== "number" || !Number.isFinite(c) || c < 0 || c > 1) || value.alpha !== undefined && (typeof value.alpha !== "number" || !Number.isFinite(value.alpha) || value.alpha < 0 || value.alpha > 1) || value.hex !== undefined && (typeof value.hex !== "string" || !/^#[0-9a-f]{6}$/i.test(value.hex))))
+            fail("color supports finite srgb/display-p3 components in 0..1 and optional alpha/hex");
+        if (type === "typography") {
+            if (!isObject(value) || Object.keys(value).some(k => !["fontFamily", "fontSize", "fontWeight", "letterSpacing", "lineHeight"].includes(k)))
+                fail("typography property outside subset");
+            const fields = { fontFamily: "fontFamily", fontSize: "dimension", fontWeight: "fontWeight", letterSpacing: "dimension", lineHeight: "number" };
+            const result = {};
+            for (const [key, expected] of Object.entries(fields))
+                result[key] = validateValue(expected, value[key], chain);
+            if (Number(result.lineHeight) <= 0)
+                fail("lineHeight must be positive");
+            return result;
+        }
+        if (!types.includes(type))
+            fail("unsupported type " + type);
+        return value;
+    };
+    for (const token of document.tokens)
+        resolveToken(token.path.join("."), token.type, []);
+}
+export function exportDtcg(raw) {
+    const v = raw;
+    if (!v || JSON.stringify(v).length > 8 * 1024 * 1024 || v.schemaVersion !== 1 || v.kind !== "portable-tokens" || v.format !== "dtcg-2025.10-subset" || !Array.isArray(v.tokens) || !v.tokens.length || v.tokens.length > 10000 || !isObject(v.groups) || !Array.isArray(v.losses) || v.losses.length)
+        fail("unsupported/incomplete portable schema; use import-tokens on a supported document");
+    const root = Object.create(null);
+    const group = (path) => { let current = root; for (const key of path) {
+        if (!key || key.startsWith("$") || /[.{}\x00-\x1f]/.test(key))
+            fail("invalid path");
+        const next = current[key];
+        if (next !== undefined && (!isObject(next) || "$value" in next))
+            fail("group/token collision");
+        current = (current[key] ??= Object.create(null));
+    } return current; };
+    for (const [key, metadata] of Object.entries(v.groups)) {
+        if (!isObject(metadata) || Object.keys(metadata).some(k => !["type", "description", "extensions"].includes(k)))
+            fail("invalid group metadata");
+        const target = group(key ? key.split(".") : []);
+        if (metadata.type !== undefined)
+            target.$type = metadata.type;
+        if (metadata.description !== undefined)
+            target.$description = metadata.description;
+        if (metadata.extensions !== undefined)
+            target.$extensions = metadata.extensions;
+    }
+    for (const token of v.tokens) {
+        if (!token || !Array.isArray(token.path) || !token.path.length || token.path.length > 32 || token.path.some(p => typeof p !== "string"))
+            fail("invalid token path");
+        const target = group(token.path.slice(0, -1)), key = token.path.at(-1);
+        if (!key || key.startsWith("$") || /[.{}\x00-\x1f]/.test(key) || key in target)
+            fail("token/group collision");
+        target[key] = { $type: token.type, $value: structuredClone(token.value), ...(token.description !== undefined ? { $description: token.description } : {}), ...(token.extensions !== undefined ? { $extensions: structuredClone(token.extensions) } : {}) };
+    }
+    // Re-import validates metadata and aliases; export never silently drops unsupported native formulas/units.
+    importDtcg(root);
+    return root;
+}

package/dist/probe.d.ts

@@ -1,11 +1,15 @@
 import { type Endpoint } from "./endpoint.js";
 import { type PenpotToolClient } from "./client.js";
+import { validateFileIntegrity } from "./native-api.js";
 export interface ProbeOptions {
+    integrity?: boolean;
     /** Request sizes in KB to try; the first refused one marks the limit. */
     requestSizesKb?: number[];
     responseSizesKb?: number[];
 }
 export interface ProbeReport {
+    integrity?: Awaited<ReturnType<typeof validateFileIntegrity>>;
+    schemaVersion: 1;
     endpoint: Endpoint["description"];
     /** Tool names the server offers; absent when the server cannot list them. */
     tools?: string[];
@@ -13,9 +17,9 @@ export interface ProbeReport {
     requestLimit: Record<string, string>;
     responseLimit: Record<string, string>;
 }
-export declare const capabilityCode = "\nconst f = penpot.currentFile, page = penpot.currentPage, lib = penpot.library.local;\nconst shape = page.root.children.find((c) => c.width < 400 && c.height < 400) || page.root.children[0];\nlet exported = null;\nif (shape) { try { const b = await shape.export({ type: \"png\", scale: 1 }); exported = b.length; } catch (e) { exported = \"error: \" + String(e && e.message || e).slice(0, 80); } }\nreturn {\n  file: f ? f.name : null, revn: f ? f.revn : null, penpotApi: typeof penpot.version === \"string\" ? penpot.version : null, pages: f ? f.pages.length : null, currentPage: page ? page.name : null,\n  apis: { tokens: typeof lib.tokens, tokenSets: lib.tokens ? lib.tokens.sets.length : null, themes: lib.tokens ? lib.tokens.themes.length : null, components: lib.components.length,\n    uploadMediaData: typeof penpot.uploadMediaData, createBoard: typeof penpot.createBoard, openPage: typeof penpot.openPage, fileExport: typeof (f && f.export) },\n  shapeApis: shape ? { swapComponent: typeof shape.swapComponent, applyToken: typeof shape.applyToken, flex: typeof shape.addFlexLayout, exportSmallShape: exported } : \"not checked: the page has no shape; open a file with at least one shape to check these\",\n};";
+export declare const capabilityCode = "\nconst f = penpot.currentFile, page = penpot.currentPage, lib = penpot.library.local;\nconst shape = page.root.children.find((c) => c.width < 400 && c.height < 400) || page.root.children[0];\nlet exported = null;\nif (shape) { try { const b = await shape.export({ type: \"png\", scale: 1 }); exported = b.length; } catch (e) { exported = \"error: \" + String(e && e.message || e).slice(0, 80); } }\nreturn {\n  schemaVersion: 1, observedAt: new Date().toISOString(), fileId: f ? f.id : null, pageId: page ? page.id : null,\n  file: f ? f.name : null, revn: f ? f.revn : null, penpotApi: typeof penpot.version === \"string\" ? penpot.version : null, pages: f ? f.pages.length : null, currentPage: page ? page.name : null,\n  apis: { tokens: typeof lib.tokens, tokenSets: lib.tokens ? lib.tokens.sets.length : null, themes: lib.tokens ? lib.tokens.themes.length : null, components: lib.components.length,\n    uploadMediaData: typeof penpot.uploadMediaData, createBoard: typeof penpot.createBoard, openPage: typeof penpot.openPage, fileExport: typeof (f && f.export),\n    layoutWait: typeof penpot.waitForLayoutUpdate, fileValidate: typeof (f && f.validate), saveVersion: typeof (f && f.saveVersion), findVersions: typeof (f && f.findVersions), generateMarkup: typeof penpot.generateMarkup, generateStyle: typeof penpot.generateStyle, generateFontFaces: typeof penpot.generateFontFaces },\n  shapeApis: shape ? { swapComponent: typeof shape.swapComponent, applyToken: typeof shape.applyToken, flex: typeof shape.addFlexLayout, exportSmallShape: exported } : \"not checked: the page has no shape; open a file with at least one shape to check these\",\n};";
 /**
  * What a connected Penpot and its MCP offer, and the limits scripts rely on. Read-only: nothing is written in Penpot.
  * `connect` returns a fresh client each time, because a refused oversized request can end the connection.
  */
-export declare function probe(endpoint: Endpoint, connect: () => Promise<PenpotToolClient>, { requestSizesKb, responseSizesKb }?: ProbeOptions): Promise<ProbeReport>;
+export declare function probe(endpoint: Endpoint, connect: () => Promise<PenpotToolClient>, { requestSizesKb, responseSizesKb, integrity }?: ProbeOptions): Promise<ProbeReport>;