@penpair/core 0.1.3 → 0.3.0

package/dist/run-file.js

@@ -0,0 +1,199 @@
+import { open, realpath } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { maxSnippetBytes } from "./client.js";
+import { resolveProjectInput } from "./project-input.js";
+import { compiles, requirePage, snippet } from "./snippet.js";
+import { normalize } from "./registry.js";
+import { runOnPage, runOperation } from "./operation.js";
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+async function sourceFile(root, entry) {
+    if (!/\.m?js$/.test(entry)) {
+        throw new Error("Plugin bodies must be .js or .mjs files; host imports and TypeScript transpilation are not performed");
+    }
+    const target = await resolveProjectInput(root, entry);
+    const handle = await open(target, "r");
+    let body;
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxSnippetBytes) {
+            throw new Error("Script file exceeds the 90 KB input bound or is not a regular file");
+        }
+        body = (await handle.readFile("utf8")).replace(/^\uFEFF/, "");
+    }
+    finally {
+        await handle.close();
+    }
+    if (body.includes("\0")) {
+        throw new Error("Plugin script contains a NUL character");
+    }
+    const header = body.trimStart().split(/\r?\n/)[0]?.trim();
+    const declaration = header === "// penpair: read" ? "read" : header === "// penpair: write" ? "write" : "unknown";
+    // The idempotency assertion must be in the initial comment block, before executable source.
+    const comments = [];
+    for (const line of body.trimStart().split(/\r?\n/)) {
+        if (!line.trim().startsWith("//")) {
+            break;
+        }
+        comments.push(line.trim());
+    }
+    return {
+        file: path
+            .relative(await realpath(root), target)
+            .split(path.sep)
+            .join("/"),
+        sha256: digest(body),
+        body,
+        declaration,
+        idempotent: comments.includes("// penpair: idempotent"),
+    };
+}
+function checked(value) {
+    const error = compiles(value.code);
+    if (error) {
+        throw new Error(`${value.name}: invalid plugin body: ${error}`);
+    }
+    return value;
+}
+/** Reads and compiles explicitly selected files without importing project modules on the host. */
+export async function prepareFileScript(root, file, options = {}) {
+    const includes = options.include ?? [];
+    if (includes.length > 20 || new Set(includes).size !== includes.length) {
+        throw new Error("Use at most 20 distinct ordered includes");
+    }
+    const params = options.params ?? {};
+    if (Object.keys(params).length > 100 ||
+        Object.keys(params).some((key) => !/^[A-Za-z][A-Za-z0-9]*$/.test(key))) {
+        throw new Error("Use at most 100 named parameters (letters followed by letters/digits)");
+    }
+    if (options.page && Object.hasOwn(params, "page")) {
+        throw new Error("--page owns CFG.page; do not also pass --param page");
+    }
+    if (Object.hasOwn(params, "inspection")) {
+        throw new Error("CFG.inspection is reserved for the independently captured write inspection");
+    }
+    const helpers = [];
+    for (const include of includes) {
+        const virtual = options.virtualIncludes?.[include];
+        const helper = virtual === undefined
+            ? await sourceFile(root, include)
+            : {
+                file: include,
+                body: virtual,
+                sha256: digest(virtual),
+                declaration: virtual.startsWith("// penpair: read\n") ? "read" : "unknown",
+                idempotent: false,
+            };
+        if (helper.declaration !== "read") {
+            throw new Error(`Include ${include} must declare // penpair: read for its top-level inclusion effects`);
+        }
+        helpers.push(helper);
+    }
+    const main = await sourceFile(root, file);
+    const prelude = helpers.map((helper) => `// Included helper\n${helper.body}\n`).join("\n");
+    const cfg = {
+        ...params,
+        ...(options.page
+            ? {
+                page: options.page,
+            }
+            : {}),
+    };
+    const build = (label, body, effect, inspected) => checked(snippet(label, `${requirePage}\n${prelude}\n${body}`, {
+        ...cfg,
+        ...(effect === "write"
+            ? {
+                inspection: inspected ?? null,
+            }
+            : {}),
+    }, effect));
+    if (main.declaration === "read") {
+        if (options.inspect || options.readback) {
+            throw new Error("Read scripts do not take write inspect/readback phases");
+        }
+        return {
+            kind: "read",
+            source: [
+                ...helpers,
+                main,
+            ].map(({ file, sha256 }) => ({
+                file,
+                sha256,
+            })),
+            params: cfg,
+            page: options.page,
+            read: build("run-file-read", main.body, "read"),
+        };
+    }
+    if (main.declaration !== "write" || !main.idempotent || !options.inspect || !options.readback) {
+        throw new Error("Write script execution requires // penpair: write, // penpair: idempotent, and explicit --inspect/--readback files. Declarations are trusted code contracts, not a sandbox.");
+    }
+    const inspect = await sourceFile(root, options.inspect);
+    const readback = await sourceFile(root, options.readback);
+    if (inspect.declaration !== "read" || readback.declaration !== "read") {
+        throw new Error("Inspection and readback files must declare // penpair: read");
+    }
+    // Reuse the registry's positive evidence verifier; never equate an acknowledgment with a verified write.
+    const normalized = normalize({
+        name: "run-file",
+        description: "Explicitly selected reviewed file operation",
+        kind: "write",
+        inspect: inspect.body,
+        apply: main.body,
+        readback: readback.body,
+    }, "project");
+    const operation = {
+        ...normalized.operation,
+        page: () => options.page,
+        inspect: () => build("run-file-inspect", inspect.body, "read"),
+        apply: (_params, inspected) => build("run-file-apply", main.body, "write", inspected),
+        readback: () => build("run-file-readback", readback.body, "read"),
+    };
+    operation.inspect({});
+    operation.apply({});
+    operation.readback({});
+    return {
+        kind: "write",
+        source: [
+            ...helpers,
+            main,
+            inspect,
+            readback,
+        ].map(({ file, sha256 }) => ({
+            file,
+            sha256,
+        })),
+        params: cfg,
+        page: options.page,
+        operation,
+    };
+}
+export async function runFileScript(client, prepared, options = {}) {
+    if (prepared.kind === "read") {
+        if (options.apply || options.journal) {
+            throw new Error("Read files do not accept apply or write recovery options");
+        }
+        const result = await runOnPage(client, prepared.read, prepared.page, {
+            ...options,
+            effect: "read",
+            retries: 0,
+        });
+        if (result.ok !== true) {
+            throw new Error("Read script returned no explicit ok acknowledgment");
+        }
+        return {
+            phase: "read",
+            kind: "declared-read",
+            source: prepared.source,
+            data: result,
+        };
+    }
+    const report = await runOperation(client, prepared.operation, {
+        parameters: prepared.params,
+        sourceFiles: prepared.source,
+    }, options);
+    return {
+        ...report,
+        source: prepared.source,
+    };
+}

package/dist/shots.d.ts

@@ -0,0 +1,43 @@
+import type { PenpotToolClient } from "./client.js";
+import { type ExportOptions, type CaptureIdentity } from "./export.js";
+import type { LayoutResult } from "./layout.js";
+export interface ShapeMatch {
+    id: string;
+    name: string;
+    type: string;
+}
+export interface ShapeLookup {
+    fileId: string;
+    pageId: string;
+    revision: number;
+    matches: ShapeMatch[];
+}
+/** Exact names across the selected page. A match never silently resolves an ambiguity. */
+export declare function findShapesByName(client: PenpotToolClient, name: string, page: string, options?: ExportOptions): Promise<ShapeLookup>;
+export declare function exportShapeByName(client: PenpotToolClient, name: string, page: string, options?: ExportOptions): Promise<import("./export.js").ExportResult>;
+export interface ShotsReport {
+    schemaVersion: 1;
+    complete: boolean;
+    fileId: string;
+    pageId: string;
+    revision: number;
+    captures: {
+        name: string;
+        file: string;
+        sha256: string;
+        capture: CaptureIdentity;
+        layout?: LayoutResult;
+        width: number;
+        height: number;
+    }[];
+    wrote: string[];
+    reason?: string;
+}
+/** Ad-hoc captures use immutable generations, but never carry baseline approval records. */
+export declare function captureShots(client: PenpotToolClient, root: string, params: {
+    page: string;
+    prefix?: string;
+    out?: string;
+}, options?: ExportOptions & {
+    signal?: AbortSignal;
+}): Promise<ShotsReport>;

package/dist/shots.js

@@ -0,0 +1,172 @@
+import { randomUUID, createHash } from "node:crypto";
+import { mkdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { PenpairError } from "./errors.js";
+import { snippet, requirePage } from "./snippet.js";
+import { runOnPage } from "./operation.js";
+import { frames } from "./snippets/read.js";
+import { exportShapePng } from "./export.js";
+import { resolveProjectOutput } from "./project-input.js";
+import { atomicWriteFile } from "./atomic-output.js";
+import { pngSize } from "./baselines.js";
+import { observationHash } from "./journal.js";
+/** Exact names across the selected page. A match never silently resolves an ambiguity. */
+export async function findShapesByName(client, name, page, options = {}) {
+    if (!name || !page) {
+        throw new Error("Name lookup requires an exact name and explicit page");
+    }
+    const result = await runOnPage(client, snippet("find-shape-name", `${requirePage}
+const matches = [], stack = [...penpot.currentPage.root.children]; let visited = 0;
+while (stack.length && visited < 10000) {
+  const shape = stack.pop(); visited++;
+  if (shape.name === CFG.name) matches.push({id:shape.id,name:shape.name,type:shape.type});
+  for (const child of shape.children || []) stack.push(child);
+}
+return {ok:true,fileId:penpot.currentFile.id,pageId:penpot.currentPage.id,revision:penpot.currentFile.revn,matches,truncated:stack.length>0};`, {
+        name,
+        page,
+    }, "read"), page, options);
+    if (result.truncated) {
+        throw new PenpairError("incomplete-output", "Shape name search exceeded 10000 nodes; narrow the page");
+    }
+    if (result.ok !== true ||
+        typeof result.truncated !== "boolean" ||
+        typeof result.fileId !== "string" ||
+        !result.fileId ||
+        typeof result.pageId !== "string" ||
+        !result.pageId ||
+        !Number.isInteger(result.revision) ||
+        !Array.isArray(result.matches) ||
+        result.matches.some((match) => !match ||
+            typeof match.id !== "string" ||
+            typeof match.name !== "string" ||
+            typeof match.type !== "string")) {
+        throw new Error("Shape search returned incomplete identity evidence");
+    }
+    return result;
+}
+export async function exportShapeByName(client, name, page, options = {}) {
+    const lookup = await findShapesByName(client, name, page, options);
+    if (lookup.matches.length !== 1) {
+        throw new Error(`Exact name ${JSON.stringify(name)} matched ${lookup.matches.length} shapes on ${JSON.stringify(page)}. Candidates: ${JSON.stringify(lookup.matches.slice(0, 20))}. Use an ID for an ambiguous name.`);
+    }
+    const result = await exportShapePng(client, lookup.matches[0].id, {
+        ...options,
+        page,
+    });
+    if (result.capture.fileId !== lookup.fileId ||
+        result.capture.pageId !== lookup.pageId ||
+        result.capture.revision !== lookup.revision) {
+        throw new Error("Named export source changed after lookup; no output was published");
+    }
+    return result;
+}
+/** Ad-hoc captures use immutable generations, but never carry baseline approval records. */
+export async function captureShots(client, root, params, options = {}) {
+    const listing = await runOnPage(client, frames({
+        page: params.page,
+    }), params.page, options);
+    if (typeof listing.fileId !== "string" ||
+        typeof listing.pageId !== "string" ||
+        !Number.isInteger(listing.revn) ||
+        !Array.isArray(listing.frames)) {
+        throw new Error("Shots listing lacks identity/revision evidence");
+    }
+    const selected = listing.frames.filter((frame) => !params.prefix || frame.name.startsWith(params.prefix));
+    const report = {
+        schemaVersion: 1,
+        complete: false,
+        fileId: listing.fileId,
+        pageId: listing.pageId,
+        revision: Number(listing.revn),
+        captures: [],
+        wrote: [],
+    };
+    if (!selected.length || selected.length > 100) {
+        return {
+            ...report,
+            reason: !selected.length
+                ? "No matching top-level frames"
+                : "More than 100 frames; narrow the prefix",
+        };
+    }
+    const folder = await resolveProjectOutput(root, params.out ?? "design/shots");
+    const runId = randomUUID();
+    const generation = `captures/${runId}`;
+    const images = [];
+    for (const [index, frame] of selected.entries()) {
+        options.signal?.throwIfAborted();
+        options.onStep?.(`exporting ${JSON.stringify(frame.name)}`);
+        const result = await exportShapePng(client, frame.id, {
+            ...options,
+            page: params.page,
+            stable: true,
+        });
+        if (!result.stable) {
+            return {
+                ...report,
+                reason: "A frame did not stabilize; no output was published",
+            };
+        }
+        if (result.capture.fileId !== report.fileId ||
+            result.capture.pageId !== report.pageId ||
+            result.capture.revision !== report.revision) {
+            throw new Error("Shots source changed during capture; no output was published");
+        }
+        const size = pngSize(result.png);
+        if (!size || size.width <= 0 || size.height <= 0) {
+            throw new Error("Shot export is missing valid PNG dimensions");
+        }
+        report.captures.push({
+            layout: result.layout,
+            ...size,
+            name: frame.name,
+            file: `${generation}/shot-${String(index + 1).padStart(4, "0")}.png`,
+            sha256: createHash("sha256").update(result.png).digest("hex"),
+            capture: result.capture,
+        });
+        images.push(result.png);
+    }
+    const after = await runOnPage(client, frames({
+        page: params.page,
+    }), params.page, options);
+    const identity = (entry) => ({
+        fileId: entry.fileId,
+        pageId: entry.pageId,
+        revision: entry.revn,
+        frames: entry.frames,
+    });
+    if (observationHash(identity(listing)) !== observationHash(identity(after))) {
+        throw new Error("Shots source changed before publication; previous output was preserved");
+    }
+    options.signal?.throwIfAborted();
+    await mkdir(path.join(folder, "captures"), {
+        recursive: true,
+    });
+    const staged = path.join(folder, `.stage-${runId}`);
+    await mkdir(staged);
+    try {
+        for (const [index, bytes] of images.entries()) {
+            options.signal?.throwIfAborted();
+            await atomicWriteFile(path.join(staged, path.basename(report.captures[index].file)), bytes);
+        }
+        options.signal?.throwIfAborted();
+        await rename(staged, path.join(folder, generation));
+        options.signal?.throwIfAborted();
+        report.complete = true;
+        report.wrote = [
+            ...report.captures.map((entry) => entry.file),
+            "penpair-shots.json",
+        ];
+        await atomicWriteFile(path.join(folder, "penpair-shots.json"), `${JSON.stringify(report, null, 2)}\n`, {
+            replace: true,
+        });
+        return report;
+    }
+    finally {
+        await rm(staged, {
+            recursive: true,
+            force: true,
+        });
+    }
+}

package/dist/skill-instructions.d.ts

@@ -0,0 +1,13 @@
+export interface InstructionReport {
+    path: string | null;
+    status: "not-selected" | "choice-required" | "unchanged" | "preview" | "written";
+    diff: string;
+}
+export interface InstructionPlan {
+    report: InstructionReport;
+    before?: string;
+    after?: string;
+    mode?: number;
+}
+export declare function planSkillInstructions(root: string, rows: string[], destination?: string): Promise<InstructionPlan>;
+export declare function applySkillInstructions(plan: InstructionPlan): Promise<InstructionReport>;

package/dist/skill-instructions.js

@@ -0,0 +1,144 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { resolveProjectOutput } from "./project-input.js";
+import { atomicWriteFile } from "./atomic-output.js";
+const start = "<!-- penpair:skills:start -->";
+const end = "<!-- penpair:skills:end -->";
+async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function planSkillInstructions(root, rows, destination) {
+    let selected = destination;
+    if (!selected) {
+        const candidates = [];
+        for (const name of [
+            "AGENTS.md",
+            "CLAUDE.md",
+        ]) {
+            if (await exists(path.join(root, name))) {
+                candidates.push(name);
+            }
+        }
+        if (candidates.length !== 1) {
+            return {
+                report: {
+                    path: null,
+                    status: candidates.length ? "choice-required" : "not-selected",
+                    diff: "",
+                },
+            };
+        }
+        selected = candidates[0];
+    }
+    const canonicalRoot = await realpath(root);
+    const file = await resolveProjectOutput(canonicalRoot, selected);
+    let before;
+    try {
+        before = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    const text = before ?? "";
+    const starts = text.split(start).length - 1;
+    const ends = text.split(end).length - 1;
+    if (starts !== ends || starts > 1 || (starts === 1 && text.indexOf(start) > text.indexOf(end))) {
+        throw new Error("Malformed penpair skills markers; repair them before installation (no instruction text was changed)");
+    }
+    const newline = text.includes("\r\n") ? "\r\n" : "\n";
+    const relativeRows = rows.map((row) => row.replace(/\]\(([^)]+)\)/g, (_match, target) => {
+        const relative = path
+            .relative(path.dirname(file), path.resolve(canonicalRoot, decodeURIComponent(target)))
+            .split(path.sep)
+            .join("/");
+        const link = relative
+            .split("/")
+            .map((part) => encodeURIComponent(part).replace(/[()]/g, (character) => `%${character.charCodeAt(0).toString(16)}`))
+            .join("/");
+        return `](${link})`;
+    }));
+    const block = [
+        start,
+        "| Skill | Purpose |",
+        "| --- | --- |",
+        ...relativeRows,
+        end,
+    ].join(newline);
+    let after;
+    if (starts === 1) {
+        after = text.slice(0, text.indexOf(start)) + block + text.slice(text.indexOf(end) + end.length);
+    }
+    else {
+        after =
+            text +
+                (text ? (text.endsWith(newline) ? newline : newline + newline) : "") +
+                "## Penpair skills" +
+                newline +
+                newline +
+                block +
+                newline;
+    }
+    const changed = text !== after;
+    // Diff only the owned region, never repeat unrelated instruction content in reports.
+    const oldBlock = starts ? text.slice(text.indexOf(start), text.indexOf(end) + end.length) : "";
+    const diff = changed
+        ? [
+            `--- ${file}`,
+            `+++ ${file}`,
+            "@@ penpair-owned skills block @@",
+            ...oldBlock
+                .split(/\r?\n/)
+                .filter(Boolean)
+                .map((line) => `-${line}`),
+            ...(starts ? block : "## Penpair skills" + newline + newline + block)
+                .split(/\r?\n/)
+                .map((line) => `+${line}`),
+        ].join("\n")
+        : "";
+    return {
+        before,
+        after,
+        mode: before === undefined ? 0o644 : (await lstat(file)).mode & 0o777,
+        report: {
+            path: file,
+            status: changed ? "preview" : "unchanged",
+            diff,
+        },
+    };
+}
+export async function applySkillInstructions(plan) {
+    if (plan.report.status !== "preview" || !plan.report.path || plan.after === undefined) {
+        return plan.report;
+    }
+    let current;
+    try {
+        current = await readFile(plan.report.path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    if (current !== plan.before) {
+        throw new Error("Instruction file changed after planning; nothing was overwritten");
+    }
+    await atomicWriteFile(plan.report.path, plan.after, {
+        replace: plan.before !== undefined,
+        mode: plan.mode,
+    });
+    return {
+        ...plan.report,
+        status: "written",
+    };
+}

package/dist/skills.d.ts

@@ -1,3 +1,4 @@
+import { type InstructionReport } from "./skill-instructions.js";
 /** The skills shipped inside the package (`skills/` next to `dist/`). */
 export declare const bundledSkillsDirectory: () => string;
 export declare function listBundledSkills(directory?: string): Promise<string[]>;
@@ -7,6 +8,8 @@ export declare function describeSkill(skillDirectory: string): Promise<{
     summary: string;
 }>;
 export interface InstallOptions {
+    agents?: string;
+    dryRun?: boolean;
     /** The project's root. */
     root: string;
     /** Where the skills go, relative to the root. */
@@ -23,6 +26,10 @@ export interface InstallOptions {
 /** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
 export declare const renamedSkills: Record<string, string>;
 export interface InstallReport {
+    instructions?: InstructionReport;
+    dryRun?: boolean;
+    wouldInstall?: string[];
+    wouldLink?: string[];
     /** The folder the skills went to, relative to the root. */
     to: string;
     installed: string[];