@penpair/core 0.1.3 → 0.3.0

package/dist/command-result.js

@@ -0,0 +1,468 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { redactEndpoint } from "./endpoint.js";
+const scope = new AsyncLocalStorage();
+const line = (values) => values.map((value) => (typeof value === "string" ? value : JSON.stringify(value))).join(" ");
+export const commandOutput = {
+    log(...values) {
+        const current = scope.getStore();
+        if (!current) {
+            console.log(...values.map((value) => renderHuman(value)));
+            return;
+        }
+        const message = line(values);
+        try {
+            current.data.push(JSON.parse(message));
+        }
+        catch {
+            current.messages.push(message);
+        }
+    },
+    error(...values) {
+        const current = scope.getStore();
+        if (current) {
+            const message = current.redactors.reduce((text, redact) => redact(text), redactEndpoint(line(values)));
+            if (message !== line(values)) {
+                current.redacted = true;
+            }
+            current.warnings.push(message);
+            console.error(message);
+        }
+        else {
+            console.error(...values.map((value) => renderHuman(value)));
+        }
+    },
+    result(value) {
+        const current = scope.getStore();
+        if (current) {
+            current.authoritative = value;
+        }
+    },
+};
+export function commandRedactor(redact) {
+    (scope.getStore()?.redactors ?? signals.getStore()?.redactors)?.push(redact);
+}
+export function commandFailure(error) {
+    const current = scope.getStore();
+    if (!current) {
+        return;
+    }
+    const value = error;
+    if (current.signal?.aborted &&
+        value?.code !== "write-uncertain" &&
+        value?.outcome !== "uncertain") {
+        const reason = current.signal.reason;
+        current.errors.push({
+            code: reason?.code === "deadline" ? "deadline" : "cancelled",
+            message: reason?.code === "deadline" ? "Command deadline exceeded" : "Command cancelled",
+            remedy: "Inspect any recorded run and current state before starting again.",
+        });
+        return;
+    }
+    current.errors.push({
+        code: typeof value?.code === "string"
+            ? value.code
+            : typeof value?.outcome === "string"
+                ? value.outcome
+                : "command-failed",
+        message: error instanceof Error ? error.message : String(error),
+        remedy: typeof value?.remedy === "string"
+            ? value.remedy
+            : "Inspect the command result and current project state before trying again.",
+        ...(typeof value?.runId === "string"
+            ? {
+                runId: value.runId,
+            }
+            : {}),
+    });
+}
+const signals = new AsyncLocalStorage();
+function redactHuman(text) {
+    return (signals.getStore()?.redactors ?? []).reduce((value, redact) => redact(value), redactEndpoint(text));
+}
+function renderHuman(value) {
+    const clean = (entry) => typeof entry === "string"
+        ? redactHuman(entry)
+        : Array.isArray(entry)
+            ? entry.map(clean)
+            : entry && typeof entry === "object"
+                ? Object.fromEntries(Object.entries(entry).map(([key, child]) => [
+                    redactHuman(key),
+                    clean(child),
+                ]))
+                : entry;
+    if (typeof value !== "string") {
+        return clean(value);
+    }
+    try {
+        return JSON.stringify(clean(JSON.parse(value)), null, 2);
+    }
+    catch {
+        return redactHuman(value);
+    }
+}
+export function withCommandSignal(signal, work) {
+    return signals.run({
+        signal,
+        redactors: [],
+    }, work);
+}
+const cleanupSignals = new AsyncLocalStorage();
+/** Bounded explicit restoration work may finish after the main command is cancelled. */
+export async function withCleanupDeadline(work, milliseconds = 10000) {
+    if (!Number.isInteger(milliseconds) || milliseconds < 1 || milliseconds > 30000) {
+        throw new Error("Cleanup deadline must be from 1 to 30000 ms");
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("Restoration deadline exceeded")), milliseconds);
+    try {
+        return await cleanupSignals.run(controller.signal, work);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function commandSignal() {
+    return cleanupSignals.getStore() ?? scope.getStore()?.signal ?? signals.getStore()?.signal;
+}
+export async function commandSleep(milliseconds) {
+    const signal = commandSignal();
+    try {
+        await wait(milliseconds, undefined, {
+            signal,
+        });
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw signal.reason;
+        }
+        throw error;
+    }
+}
+export class CommandInterruptedError extends Error {
+    code;
+    constructor(code) {
+        super(code === "deadline" ? "Command deadline exceeded" : "Command cancelled");
+        this.code = code;
+    }
+}
+/** Shared service boundary for CLI and future tool surfaces; no stdout or global console interception. */
+export async function collectCommand(command, work, options = {}) {
+    const started = Date.now();
+    const capture = {
+        data: [],
+        messages: [],
+        warnings: [],
+        errors: [],
+        redactors: [],
+        signal: options.signal,
+    };
+    let exitCode;
+    try {
+        exitCode = await scope.run(capture, async () => {
+            options.signal?.throwIfAborted();
+            const code = await work();
+            options.signal?.throwIfAborted();
+            return code;
+        });
+    }
+    catch (error) {
+        await scope.run(capture, async () => commandFailure(error));
+        exitCode = 1;
+    }
+    if (![
+        0,
+        1,
+        2,
+        3,
+        4,
+        124,
+        130,
+    ].includes(exitCode)) {
+        capture.warnings.push("Unsupported extension exit code was normalized to failure");
+        exitCode = 1;
+    }
+    const data = capture.authoritative !== undefined
+        ? capture.authoritative
+        : capture.data.length === 1
+            ? capture.data[0]
+            : capture.data.length
+                ? capture.data
+                : null;
+    const record = data && typeof data === "object" && !Array.isArray(data)
+        ? data
+        : {};
+    const errorCode = capture.errors[0]?.code;
+    const incomplete = record.complete === false || record.truncated === true || errorCode === "incomplete-output";
+    let outcome = exitCode === 0
+        ? "success"
+        : exitCode === 2
+            ? "drift"
+            : exitCode === 3
+                ? "incomplete"
+                : exitCode === 4
+                    ? "uncertain"
+                    : exitCode === 130
+                        ? "cancelled"
+                        : exitCode === 124
+                            ? "deadline"
+                            : "failed";
+    if (errorCode === "write-uncertain" || errorCode === "uncertain") {
+        outcome = "uncertain";
+        exitCode = 4;
+    }
+    else if (errorCode === "cancelled" || errorCode === "deadline") {
+        outcome = errorCode;
+        exitCode = errorCode === "cancelled" ? 130 : 124;
+    }
+    else if (incomplete) {
+        outcome = "incomplete";
+        exitCode = 3;
+    }
+    if (exitCode !== 0 &&
+        !capture.errors.length &&
+        ![
+            "drift",
+            "incomplete",
+        ].includes(outcome)) {
+        capture.errors.push({
+            code: "command-failed",
+            message: "Command checks failed; inspect data and diagnostics.",
+            remedy: "Resolve the reported checks before proceeding.",
+        });
+    }
+    const identity = (record.capture ?? record.target ?? record);
+    const target = typeof identity.fileId === "string"
+        ? {
+            fileId: identity.fileId,
+            ...(typeof identity.pageId === "string"
+                ? {
+                    pageId: identity.pageId,
+                }
+                : {}),
+        }
+        : null;
+    const journal = record.journal;
+    const sanitize = (value) => {
+        if (value === undefined ||
+            typeof value === "function" ||
+            typeof value === "symbol" ||
+            typeof value === "bigint" ||
+            (typeof value === "number" && !Number.isFinite(value))) {
+            return null;
+        }
+        if (typeof value === "string") {
+            return capture.redactors.reduce((text, redact) => redact(text), redactEndpoint(value));
+        }
+        if (Array.isArray(value)) {
+            return value.map(sanitize);
+        }
+        if (value && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+                String(sanitize(key)),
+                sanitize(entry),
+            ]));
+        }
+        return value;
+    };
+    const raw = {
+        schemaVersion: 1,
+        command,
+        outcome,
+        phase: typeof record.phase === "string"
+            ? record.phase
+            : outcome === "uncertain" || outcome === "cancelled" || outcome === "deadline"
+                ? "interrupted"
+                : "finished",
+        exitCode,
+        target,
+        runId: capture.errors.find((error) => error.runId)?.runId ??
+            (typeof journal?.runId === "string" ? journal.runId : null),
+        data,
+        messages: capture.messages,
+        warnings: capture.warnings,
+        errors: capture.errors,
+        completeness: {
+            complete: outcome === "success" || outcome === "drift",
+            ...(incomplete
+                ? {
+                    reason: "Output is truncated or required observations are missing",
+                }
+                : {}),
+        },
+        timings: {
+            startedAt: new Date(started).toISOString(),
+            durationMs: Math.max(0, Date.now() - started),
+        },
+    };
+    const result = sanitize(raw);
+    if (record.redacted === true ||
+        capture.redacted ||
+        JSON.stringify(result) !== JSON.stringify(raw)) {
+        result.redacted = true;
+        result.warnings.push("Sensitive or non-JSON output was redacted; hashes describe original evidence.");
+        if (JSON.stringify(result.data) !== JSON.stringify(data)) {
+            result.completeness = {
+                complete: false,
+                reason: "Displayed data required redaction and is not lossless source evidence",
+            };
+            if (result.outcome === "success" || result.outcome === "drift") {
+                result.outcome = "incomplete";
+                result.exitCode = 3;
+            }
+        }
+    }
+    return result;
+}
+/** Outer transport contract. Command-specific data remains owned by the command service. */
+export const commandResultSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "schemaVersion",
+        "command",
+        "outcome",
+        "phase",
+        "exitCode",
+        "target",
+        "runId",
+        "data",
+        "messages",
+        "warnings",
+        "errors",
+        "completeness",
+        "timings",
+    ],
+    properties: {
+        schemaVersion: {
+            const: 1,
+        },
+        redacted: {
+            type: "boolean",
+        },
+        command: {
+            type: "string",
+        },
+        outcome: {
+            enum: [
+                "success",
+                "drift",
+                "failed",
+                "incomplete",
+                "uncertain",
+                "cancelled",
+                "deadline",
+            ],
+        },
+        phase: {
+            type: "string",
+        },
+        exitCode: {
+            enum: [
+                0,
+                1,
+                2,
+                3,
+                4,
+                124,
+                130,
+            ],
+        },
+        target: {
+            anyOf: [
+                {
+                    type: "null",
+                },
+                {
+                    type: "object",
+                    properties: {
+                        fileId: {
+                            type: "string",
+                        },
+                        pageId: {
+                            type: "string",
+                        },
+                    },
+                    additionalProperties: false,
+                },
+            ],
+        },
+        runId: {
+            type: [
+                "string",
+                "null",
+            ],
+        },
+        data: {},
+        messages: {
+            type: "array",
+            items: {
+                type: "string",
+            },
+        },
+        warnings: {
+            type: "array",
+            items: {
+                type: "string",
+            },
+        },
+        errors: {
+            type: "array",
+            items: {
+                type: "object",
+                required: [
+                    "code",
+                    "message",
+                    "remedy",
+                ],
+                properties: {
+                    code: {
+                        type: "string",
+                    },
+                    message: {
+                        type: "string",
+                    },
+                    remedy: {
+                        type: "string",
+                    },
+                    runId: {
+                        type: "string",
+                    },
+                },
+                additionalProperties: false,
+            },
+        },
+        completeness: {
+            type: "object",
+            required: [
+                "complete",
+            ],
+            properties: {
+                complete: {
+                    type: "boolean",
+                },
+                reason: {
+                    type: "string",
+                },
+            },
+            additionalProperties: false,
+        },
+        timings: {
+            type: "object",
+            required: [
+                "startedAt",
+                "durationMs",
+            ],
+            properties: {
+                startedAt: {
+                    type: "string",
+                },
+                durationMs: {
+                    type: "number",
+                    minimum: 0,
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+};

package/dist/coordination.d.ts

@@ -0,0 +1,15 @@
+import type { PenpotToolClient } from "./client.js";
+import type { JournalTarget } from "./journal.js";
+export interface WriteLease {
+    check(): Promise<void>;
+    release(): Promise<void>;
+}
+export interface CoordinationOptions {
+    root: string;
+    operation: string;
+    forceLock?: boolean;
+    warn?(message: string): void;
+}
+export declare function writeCoordinator(client: PenpotToolClient, options: CoordinationOptions): (runId: string, target: JournalTarget) => Promise<WriteLease>;
+/** Revision precondition is checked inside the delivered mutation, after all guard calls. It is not a server CAS. */
+export declare function guardRevision(client: PenpotToolClient, target: JournalTarget): PenpotToolClient;

package/dist/coordination.js

@@ -0,0 +1,184 @@
+import { inheritPageSession } from "./page-session.js";
+import { createHash, randomUUID } from "node:crypto";
+import { hostname, userInfo } from "node:os";
+import { lstat, mkdir, open, readFile, unlink } from "node:fs/promises";
+import path from "node:path";
+import { ensureGitignoreEntry } from "./instance/gitignore.js";
+import { runSnippet, snippet } from "./snippet.js";
+import { maxSnippetBytes } from "./client.js";
+import { PenpairError } from "./errors.js";
+/** Exclusive only within this checkout. Shared file markers below are advisory, not compare-and-swap. */
+async function localLease(root, fileId, runId, force) {
+    await ensureGitignoreEntry(root, ".penpair", {
+        directory: true,
+        comment: "penpair: private local operation evidence",
+    });
+    const parent = path.join(root, ".penpair");
+    await mkdir(parent, {
+        mode: 0o700,
+    }).catch((error) => {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+    });
+    const parentInfo = await lstat(parent);
+    if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink()) {
+        throw new Error("Write locks require a real local directory");
+    }
+    const directory = path.join(parent, "locks");
+    await mkdir(directory, {
+        mode: 0o700,
+    }).catch((error) => {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+    });
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+        throw new Error("Write locks require a real local directory");
+    }
+    const destination = path.join(directory, `${createHash("sha256").update(fileId).digest("hex")}.json`);
+    const token = randomUUID();
+    const entry = {
+        token,
+        runId,
+        pid: process.pid,
+        host: hostname(),
+        createdAt: new Date().toISOString(),
+    };
+    const create = async () => {
+        const handle = await open(destination, "wx", 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(entry));
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    try {
+        await create();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        const previous = JSON.parse(await readFile(destination, "utf8"));
+        let running = false;
+        if (previous.host === hostname() && Number.isInteger(previous.pid) && previous.pid > 0) {
+            try {
+                process.kill(previous.pid, 0);
+                running = true;
+            }
+            catch (failure) {
+                if (failure.code !== "ESRCH") {
+                    running = true;
+                }
+            }
+        }
+        if (!force || running) {
+            throw new Error(`Local writer ${previous.runId} holds this file. ${running ? "Its process is still running; wait for it to finish." : "Inspect its journal, then use --force-lock to remove the abandoned local lock."}`);
+        }
+        // Explicit owner override only. Simultaneous force operations are not an exclusion guarantee.
+        await unlink(destination);
+        await create();
+    }
+    return async () => {
+        const current = JSON.parse(await readFile(destination, "utf8"));
+        if (current.token === token) {
+            await unlink(destination);
+        }
+    };
+}
+const readMarker = `const f = penpot.currentFile;
+if (typeof f.getSharedPluginData !== "function" || typeof f.setSharedPluginData !== "function") return { ok: true, supported: false };
+const raw = f.getSharedPluginData("penpair", "writer");
+let marker = null;
+if (raw) { try { marker = JSON.parse(raw); } catch { return { ok: false, message: "Malformed shared writer marker; inspect before overriding" }; } }
+`;
+export function writeCoordinator(client, options) {
+    return async (runId, target) => {
+        const releaseLocal = await localLease(options.root, target.fileId, runId, options.forceLock === true);
+        const marker = {
+            schemaVersion: 1,
+            token: randomUUID(),
+            runId,
+            operation: options.operation,
+            owner: userInfo().username,
+            createdAt: Date.now(),
+            expiresAt: Date.now() + 15 * 60_000,
+        };
+        const params = {
+            marker,
+            fileId: target.fileId,
+            force: options.forceLock === true,
+        };
+        const targetGuard = 'if (penpot.currentFile.id !== CFG.fileId) return { ok:false, message:"Writer marker target changed" };';
+        try {
+            const before = await runSnippet(client, snippet("writer-inspect", targetGuard + readMarker + "return { ok:true, supported:true, marker };", params, "read"));
+            if (before.supported === false) {
+                options.warn?.("Shared writer markers unavailable; local checkout lock only. Coordinate with colleagues before writing.");
+                return {
+                    check: async () => undefined,
+                    release: releaseLocal,
+                };
+            }
+            const acquired = await runSnippet(client, snippet("writer-acquire", targetGuard +
+                readMarker +
+                `
+if (marker && marker.token !== CFG.marker.token && (!Number.isFinite(marker.expiresAt) || marker.expiresAt > Date.now()) && !CFG.force)
+  return { ok:false, message:"Another writer is running " + String(marker.operation) + " (run " + String(marker.runId) + "). Coordinate before --force-lock." };
+f.setSharedPluginData("penpair", "writer", JSON.stringify(CFG.marker));
+return { ok:true, supported:true };`, params, "write"));
+            if (acquired.supported !== true) {
+                throw new Error("Writer marker capability changed during acquisition");
+            }
+            const check = async () => {
+                const observed = await runSnippet(client, snippet("writer-check", targetGuard +
+                    readMarker +
+                    "return { ok:true, supported:true, owned: !!marker && marker.token === CFG.marker.token && marker.expiresAt > Date.now() };", params, "read"));
+                if (observed.supported !== true || observed.owned !== true) {
+                    throw new Error("Shared writer marker was lost or expired; stop and coordinate before resuming");
+                }
+            };
+            await check();
+            return {
+                check,
+                release: async () => {
+                    try {
+                        await runSnippet(client, snippet("writer-release", targetGuard +
+                            readMarker +
+                            'if (marker && marker.token === CFG.marker.token) f.setSharedPluginData("penpair", "writer", ""); return { ok:true };', params, "write"));
+                    }
+                    finally {
+                        await releaseLocal();
+                    }
+                },
+            };
+        }
+        catch (error) {
+            await releaseLocal();
+            throw error;
+        }
+    };
+}
+/** Revision precondition is checked inside the delivered mutation, after all guard calls. It is not a server CAS. */
+export function guardRevision(client, target) {
+    return inheritPageSession({
+        ...client,
+        close: () => client.close(),
+        async callTool(name, args, options) {
+            if (name !== "execute_code" || typeof args.code !== "string") {
+                throw new Error("Revision guards require execute_code");
+            }
+            const code = `{ if (penpot.currentFile.id !== ${JSON.stringify(target.fileId)} || penpot.currentFile.revn !== ${JSON.stringify(target.revision)}) return {ok:false, message:"File revision changed before mutation; inspect again"}; }\n` +
+                args.code;
+            if (Buffer.byteLength(code) > maxSnippetBytes) {
+                throw new PenpairError("snippet-too-large", "Snippet including revision guard exceeds 90 KB");
+            }
+            return client.callTool(name, {
+                ...args,
+                code,
+            }, options);
+        },
+    }, client);
+}

package/dist/credentials.d.ts

@@ -0,0 +1,21 @@
+export type CredentialReference = {
+    type: "file";
+    path: string;
+} | {
+    type: "keychain";
+    service: string;
+    account: string;
+};
+export declare function validateCredentialReference(raw: unknown): CredentialReference;
+type KeychainRead = (command: string, args: string[], options: {
+    timeout: number;
+    maxBuffer: number;
+    encoding: "utf8";
+}) => Promise<string>;
+/** Resolve only at connection time. No URL, key, child stderr or command error object enters diagnostics. */
+export declare function readCredential(reference: CredentialReference, options: {
+    root: string;
+    platform?: string;
+    keychainRead?: KeychainRead;
+}): Promise<string>;
+export {};