@penpair/core 0.1.3 → 0.3.0

package/dist/project-status.js

@@ -0,0 +1,188 @@
+import { onboardingChecklist } from "./onboard.js";
+import { snippet, runSnippet } from "./snippet.js";
+import { installSkills } from "./skills.js";
+import { readBaselineCoverage } from "./baseline-coverage.js";
+import { redactEndpoint } from "./endpoint.js";
+export const projectFileUrl = (config) => {
+    const url = onboardingChecklist(config).fileUrl;
+    if (!url) {
+        throw new Error("Pin the owner-confirmed file before opening it");
+    }
+    return url;
+};
+export async function openProject(config, open) {
+    const url = projectFileUrl(config);
+    await open(url);
+    return url;
+}
+export async function projectStatus(root, config, options = {}) {
+    const origin = onboardingChecklist(config).origin;
+    const lines = [];
+    const safe = (error) => (options.redact ?? redactEndpoint)(String(error.message));
+    let reachable = false;
+    try {
+        reachable = await (options.reachable ??
+            (async (origin) => (await fetch(origin, {
+                redirect: "manual",
+                signal: AbortSignal.timeout(5000),
+            })).status < 500))(origin);
+    }
+    catch { }
+    lines.push({
+        id: "deployment",
+        label: "Penpot",
+        state: reachable ? "ok" : "failed",
+        detail: reachable ? `${origin} answers` : `${origin} is unavailable`,
+    });
+    lines.push({
+        id: "file-pin",
+        label: "File pin",
+        state: config.file ? "ok" : "unknown",
+        detail: config.file ? (config.file.name ?? config.file.id) : "No owner-confirmed file pin",
+    });
+    let connection = null;
+    if (options.connection) {
+        let client;
+        try {
+            client = await options.connection();
+            const observation = await runSnippet(client, snippet("project-status", `return {ok:true,fileId:penpot.currentFile.id,file:penpot.currentFile.name,revision:penpot.currentFile.revn,pages:penpot.currentFile.pages.map(p=>({id:p.id,name:p.name})),apiVersion:typeof penpot.version==="string"?penpot.version:null,capabilities:{tokens:!!penpot.library?.local?.tokens,fonts:!!penpot.fonts,nativeLayout:typeof penpot.currentPage.root.waitForLayoutUpdate==="function"}};`, {}, "read"));
+            if (!config.file ||
+                observation.fileId !== config.file.id ||
+                !Array.isArray(observation.pages) ||
+                !Number.isInteger(observation.revision)) {
+                throw new Error("Status did not observe the configured file identity/revision");
+            }
+            const { execution: _execution, ...data } = observation;
+            connection = data;
+            lines.push({
+                id: "connection",
+                label: "Editor and plugin",
+                state: "ok",
+                detail: `Pinned file connected; ${observation.pages.length} pages`,
+            });
+        }
+        catch (error) {
+            lines.push({
+                id: "connection",
+                label: "Editor and plugin",
+                state: "failed",
+                detail: safe(error),
+            });
+        }
+        finally {
+            await client?.close();
+        }
+    }
+    else {
+        lines.push({
+            id: "connection",
+            label: "Editor and plugin",
+            state: "unknown",
+            detail: "No resolved project connection",
+        });
+    }
+    try {
+        const skills = await installSkills({
+            root,
+            dryRun: true,
+        });
+        lines.push({
+            id: "skills",
+            label: "Skills",
+            state: skills.wouldInstall?.length || skills.wouldLink?.length || skills.kept.length
+                ? "warning"
+                : "ok",
+            detail: `${skills.wouldInstall?.length ?? 0} missing/update candidates; ${skills.kept.length} locally edited files preserved; discovery is not verified`,
+        });
+    }
+    catch (error) {
+        lines.push({
+            id: "skills",
+            label: "Skills",
+            state: "unknown",
+            detail: safe(error),
+        });
+    }
+    let coverage = null;
+    if (config.baselines) {
+        try {
+            const found = await readBaselineCoverage(root, config.baselines, config.file?.id);
+            coverage = found;
+            lines.push({
+                id: "baselines",
+                label: "Baselines",
+                state: found.designCasesComplete ? "ok" : "warning",
+                detail: found.configured
+                    ? "See explicit case coverage"
+                    : "No complete rich coverage matrix declared",
+            });
+        }
+        catch (error) {
+            lines.push({
+                id: "baselines",
+                label: "Baselines",
+                state: "failed",
+                detail: safe(error),
+            });
+        }
+    }
+    else {
+        lines.push({
+            id: "baselines",
+            label: "Baselines",
+            state: "unknown",
+            detail: "No baseline configuration",
+        });
+    }
+    if (options.adapterStatus) {
+        try {
+            const adapterLines = await options.adapterStatus();
+            if (!Array.isArray(adapterLines) ||
+                adapterLines.length > 100 ||
+                adapterLines.some((l) => !l ||
+                    typeof l.id !== "string" ||
+                    typeof l.label !== "string" ||
+                    typeof l.detail !== "string" ||
+                    ![
+                        "ok",
+                        "warning",
+                        "failed",
+                        "unknown",
+                    ].includes(l.state))) {
+                throw new Error("Invalid adapter status lines");
+            }
+            lines.push(...adapterLines);
+        }
+        catch (error) {
+            lines.push({
+                id: "adapters",
+                label: "Adapters",
+                state: "failed",
+                detail: safe(error),
+            });
+        }
+    }
+    else if (config.adapters?.length) {
+        lines.push({
+            id: "adapters",
+            label: "Adapters",
+            state: "unknown",
+            detail: "Not loaded; --adapters explicitly executes trusted status hooks",
+        });
+    }
+    const complete = lines.every((l) => l.state !== "unknown");
+    const ok = complete && lines.every((l) => l.state === "ok");
+    return {
+        schemaVersion: 1,
+        kind: "project-status",
+        project: config.instance,
+        origin,
+        fileUrl: config.file ? projectFileUrl(config) : null,
+        connection,
+        coverage,
+        lines,
+        complete,
+        ok,
+        visualApproval: false,
+    };
+}

package/dist/registry.d.ts

@@ -27,7 +27,7 @@ export interface ReadDefinition extends DefinitionBase {
 /**
  * A change done the safe way. `inspect` only looks and says what would change; `apply` changes once and must be safe to repeat;
  * `readback` looks again from scratch. `verify` compares them and returns the problems; by default the readback's
- * `problems` array is used (an empty or missing array means nothing is wrong).
+ * `verification.expected` and `verification.actual` must contain matching nonempty observation objects.
  */
 export interface WriteDefinition extends DefinitionBase {
     kind: "write";
@@ -35,6 +35,7 @@ export interface WriteDefinition extends DefinitionBase {
     apply: Body;
     readback: Body;
     verify?: Operation<Params>["verify"];
+    reconcile?: Operation<Params>["reconcile"];
 }
 export type SnippetDefinition = ReadDefinition | WriteDefinition;
 /** Declares a project snippet. Returns the definition unchanged, so a module can `export default defineSnippet({...})` with types checked. */

package/dist/registry.js

@@ -1,4 +1,5 @@
 import { runOperation, runOnPage } from "./operation.js";
+import { isDeepStrictEqual } from "node:util";
 import { compiles, requirePage, snippet } from "./snippet.js";
 import { archiveOperation } from "./operation.js";
 import { audit, pages, tokensDump, tree } from "./snippets/read.js";
@@ -7,44 +8,77 @@ export const defineSnippet = (definition) => definition;
 export class RegistryError extends Error {
 }
 const namePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-const paramTypes = ["string", "number", "boolean", "string[]", "number[]"];
-const bodyOf = (body, params) => (typeof body === "function" ? body(params) : body);
+const paramTypes = [
+    "string",
+    "number",
+    "boolean",
+    "string[]",
+    "number[]",
+];
+const bodyOf = (body, params) => typeof body === "function" ? body(params) : body;
 const pageOf = (page) => page === undefined ? undefined : typeof page === "function" ? page : () => page;
 /** Whatever page the definition names is handed to the snippet as CFG.page, with the guard in front of the body. */
 function pageAware(def, params) {
     const page = pageOf(def.page)?.(params);
-    return page === undefined ? { cfg: params, guard: "" } : { cfg: { ...params, page }, guard: `${requirePage}\n` };
+    return page === undefined
+        ? {
+            cfg: params,
+            guard: "",
+        }
+        : {
+            cfg: {
+                ...params,
+                page,
+            },
+            guard: `${requirePage}\n`,
+        };
 }
 /** Turns a definition into what the registry runs. Throws a RegistryError that says what is wrong with the definition. */
 export function normalize(def, source) {
     const fail = (message) => {
         throw new RegistryError(`snippet ${JSON.stringify(def.name)}: ${message}`);
     };
-    if (typeof def !== "object" || def === null)
+    if (typeof def !== "object" || def === null) {
         return fail("a snippet must be an object");
-    if (typeof def.name !== "string" || !namePattern.test(def.name))
+    }
+    if (typeof def.name !== "string" || !namePattern.test(def.name)) {
         fail("name must be lowercase words joined by hyphens");
-    if (typeof def.description !== "string" || def.description.trim() === "")
+    }
+    if (typeof def.description !== "string" || def.description.trim() === "") {
         fail("a description is required");
+    }
     const params = def.params ?? [];
     const seen = new Set();
     for (const spec of params) {
-        if (!/^[A-Za-z][A-Za-z0-9]*$/.test(spec.name))
+        if (!/^[A-Za-z][A-Za-z0-9]*$/.test(spec.name)) {
             fail(`parameter name ${JSON.stringify(spec.name)} is not valid`);
-        if (!paramTypes.includes(spec.type))
+        }
+        if (!paramTypes.includes(spec.type)) {
             fail(`parameter ${spec.name} has an unknown type ${JSON.stringify(spec.type)}`);
-        if (seen.has(spec.name))
+        }
+        if (seen.has(spec.name)) {
             fail(`parameter ${spec.name} is declared twice`);
+        }
         seen.add(spec.name);
     }
-    const common = { name: def.name, description: def.description, params, source };
+    const common = {
+        name: def.name,
+        description: def.description,
+        params,
+        source,
+    };
     if (def.kind === "read") {
-        if (typeof def.body !== "string" && typeof def.body !== "function")
+        if (typeof def.body !== "string" && typeof def.body !== "function") {
             fail("a read snippet needs a body");
+        }
         return {
             kind: "read",
             ...common,
-            ...(def.page === undefined ? {} : { page: pageOf(def.page) }),
+            ...(def.page === undefined
+                ? {}
+                : {
+                    page: pageOf(def.page),
+                }),
             build(p) {
                 const { cfg, guard } = pageAware(def, p);
                 return snippet(def.name, `${guard}${bodyOf(def.body, p)}`, cfg);
@@ -52,9 +86,15 @@ export function normalize(def, source) {
         };
     }
     if (def.kind === "write") {
-        for (const phase of ["inspect", "apply", "readback"])
-            if (typeof def[phase] !== "string" && typeof def[phase] !== "function")
+        for (const phase of [
+            "inspect",
+            "apply",
+            "readback",
+        ]) {
+            if (typeof def[phase] !== "string" && typeof def[phase] !== "function") {
                 fail(`a write snippet needs ${phase}`);
+            }
+        }
         const phaseSnippet = (phase) => (p) => {
             const { cfg, guard } = pageAware(def, p);
             return snippet(`${def.name}-${phase}`, `${guard}${bodyOf(def[phase], p)}`, cfg);
@@ -68,8 +108,12 @@ export function normalize(def, source) {
                 inspect: phaseSnippet("inspect"),
                 apply: phaseSnippet("apply"),
                 readback: phaseSnippet("readback"),
-                verify: def.verify ??
-                    (({ readback }) => (Array.isArray(readback.problems) ? readback.problems.map(String) : [])),
+                verify: def.verify ?? (({ readback }) => verifyEvidence(readback)),
+                ...(def.reconcile
+                    ? {
+                        reconcile: def.reconcile,
+                    }
+                    : {}),
             },
         };
     }
@@ -78,27 +122,33 @@ export function normalize(def, source) {
 /** Checks that every phase of a snippet is valid plugin code and small enough, using only the declared defaults. No connection needed. */
 export function checkEntry(entry) {
     const sample = {};
-    for (const spec of entry.params)
-        if (spec.default !== undefined)
+    for (const spec of entry.params) {
+        if (spec.default !== undefined) {
             sample[spec.name] = spec.default;
+        }
+    }
     const problems = [];
     const snippets = [];
     try {
-        if (entry.kind === "read")
+        if (entry.kind === "read") {
             snippets.push(entry.build(sample));
-        else
+        }
+        else {
             snippets.push(entry.operation.inspect(sample), entry.operation.apply(sample), entry.operation.readback(sample));
+        }
     }
     catch (error) {
         // A builder may need a real parameter to build at all; then only the rest of the checks apply.
         const message = String(error.message);
-        if (/bytes/.test(message))
+        if (/bytes/.test(message)) {
             problems.push(message);
+        }
     }
     for (const s of snippets) {
         const error = compiles(s.code);
-        if (error)
+        if (error) {
             problems.push(`${s.name}: ${error}`);
+        }
     }
     return problems;
 }
@@ -106,16 +156,22 @@ export function checkEntry(entry) {
 export function coerceParams(specs, raw) {
     const out = {};
     const known = new Set(specs.map((s) => s.name));
-    for (const key of Object.keys(raw))
-        if (!known.has(key))
-            throw new RegistryError(`unknown parameter ${key}; known: ${[...known].join(", ") || "none"}`);
+    for (const key of Object.keys(raw)) {
+        if (!known.has(key)) {
+            throw new RegistryError(`unknown parameter ${key}; known: ${[
+                ...known,
+            ].join(", ") || "none"}`);
+        }
+    }
     for (const spec of specs) {
         const value = raw[spec.name];
         if (value === undefined) {
-            if (spec.default !== undefined)
+            if (spec.default !== undefined) {
                 out[spec.name] = spec.default;
-            else if (spec.required)
+            }
+            else if (spec.required) {
                 throw new RegistryError(`parameter ${spec.name} is required`);
+            }
             continue;
         }
         const text = Array.isArray(value) ? value.join(",") : value;
@@ -125,23 +181,32 @@ export function coerceParams(specs, raw) {
                 break;
             case "number": {
                 const n = Number(text);
-                if (!Number.isFinite(n))
+                if (!Number.isFinite(n)) {
                     throw new RegistryError(`parameter ${spec.name} must be a number`);
+                }
                 out[spec.name] = n;
                 break;
             }
             case "boolean":
-                if (!["true", "false"].includes(text))
+                if (![
+                    "true",
+                    "false",
+                ].includes(text)) {
                     throw new RegistryError(`parameter ${spec.name} must be true or false`);
+                }
                 out[spec.name] = text === "true";
                 break;
             case "string[]":
-                out[spec.name] = text.split(",").map((v) => v.trim()).filter(Boolean);
+                out[spec.name] = text
+                    .split(",")
+                    .map((v) => v.trim())
+                    .filter(Boolean);
                 break;
             case "number[]": {
                 const list = text.split(",").map((v) => Number(v.trim()));
-                if (list.some((n) => !Number.isFinite(n)))
+                if (list.some((n) => !Number.isFinite(n))) {
                     throw new RegistryError(`parameter ${spec.name} must be numbers separated by commas`);
+                }
                 out[spec.name] = list;
                 break;
             }
@@ -149,30 +214,72 @@ export function coerceParams(specs, raw) {
     }
     return out;
 }
+/** An absent error list is not evidence that the intended state exists. */
+function verifyEvidence(readback) {
+    if (readback.problems !== undefined &&
+        (!Array.isArray(readback.problems) ||
+            readback.problems.some((problem) => typeof problem !== "string"))) {
+        return [
+            "Readback problems must be a list of strings",
+        ];
+    }
+    if (Array.isArray(readback.problems) && readback.problems.length > 0) {
+        return readback.problems;
+    }
+    const evidence = readback.verification;
+    const observation = (value) => typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length > 0;
+    if (!evidence || !observation(evidence.expected) || !observation(evidence.actual)) {
+        return [
+            "Readback needs nonempty verification.expected and verification.actual observations, or an explicit verifier",
+        ];
+    }
+    return isDeepStrictEqual(evidence.expected, evidence.actual)
+        ? []
+        : [
+            "Readback observations do not match the expected state",
+        ];
+}
 export class SnippetRegistry {
     entries = new Map();
     register(def, source = "project") {
-        const entry = "build" in def || "operation" in def ? def : normalize(def, source);
-        if (this.entries.has(entry.name))
+        const entry = "build" in def || "operation" in def
+            ? def
+            : normalize(def, source);
+        if (this.entries.has(entry.name)) {
             throw new RegistryError(`snippet ${entry.name} is already registered (${this.entries.get(entry.name).source})`);
+        }
         this.entries.set(entry.name, entry);
         return entry;
     }
     get(name) {
         const entry = this.entries.get(name);
-        if (!entry)
-            throw new RegistryError(`no snippet named ${name}. Known: ${[...this.entries.keys()].sort().join(", ")}`);
+        if (!entry) {
+            throw new RegistryError(`no snippet named ${name}. Known: ${[
+                ...this.entries.keys(),
+            ]
+                .sort()
+                .join(", ")}`);
+        }
         return entry;
     }
     list() {
-        return [...this.entries.values()].sort((a, b) => a.name.localeCompare(b.name));
+        return [
+            ...this.entries.values(),
+        ].sort((a, b) => a.name.localeCompare(b.name));
     }
     /** Runs a snippet by name. A write snippet only looks unless `apply` is set. */
     async run(client, name, params, options = {}) {
         const entry = this.get(name);
-        if (entry.kind === "write")
+        if (entry.kind === "write") {
             return runOperation(client, entry.operation, params, options);
-        const record = await runOnPage(client, entry.build(params), entry.page?.(params), options);
+        }
+        const record = await runOnPage(client, entry.build(params), entry.page?.(params), {
+            ...options,
+            effect: "read",
+        });
         return record;
     }
 }
@@ -182,7 +289,11 @@ const readBuiltIn = (name, description, params, build) => ({
     description,
     params,
     source: "built-in",
-    ...(params.some((p) => p.name === "page") ? { page: (p) => p.page } : {}),
+    ...(params.some((p) => p.name === "page")
+        ? {
+            page: (p) => p.page,
+        }
+        : {}),
     build,
 });
 /** The registry with everything penpair ships. Project snippets are added to it. */
@@ -190,28 +301,88 @@ export function builtInRegistry() {
     const registry = new SnippetRegistry();
     registry.register(readBuiltIn("pages", "The file, its revision, its pages and how many top-level shapes each has.", [], () => pages()), "built-in");
     registry.register(readBuiltIn("tree", "One line per shape: type, name, size, position, layout and sizing, and the text it carries.", [
-        { name: "page", type: "string", required: true, description: "Page to read" },
-        { name: "depth", type: "number", default: 3, description: "How many levels down" },
-        { name: "namePrefix", type: "string", description: "Only top-level shapes whose name starts with this" },
-        { name: "limit", type: "number", default: 400, description: "Stop after this many lines" },
+        {
+            name: "page",
+            type: "string",
+            required: true,
+            description: "Page to read",
+        },
+        {
+            name: "depth",
+            type: "number",
+            default: 3,
+            description: "How many levels down",
+        },
+        {
+            name: "namePrefix",
+            type: "string",
+            description: "Only top-level shapes whose name starts with this",
+        },
+        {
+            name: "limit",
+            type: "number",
+            default: 400,
+            description: "Stop after this many lines",
+        },
     ], (p) => tree(p)), "built-in");
     registry.register(readBuiltIn("audit", "Blank text, colours and strokes not bound to a token, children sticking out of their parent, gaps off the allowed steps.", [
-        { name: "page", type: "string", required: true },
-        { name: "framePrefix", type: "string", required: true, description: "Audit top-level frames whose names start with this" },
-        { name: "spacingSteps", type: "number[]", description: "Allowed gap and padding values; leave out to skip that check" },
-        { name: "ignoreUnbound", type: "string[]", description: "Names (starts) not reported as unbound" },
+        {
+            name: "page",
+            type: "string",
+            required: true,
+        },
+        {
+            name: "framePrefix",
+            type: "string",
+            required: true,
+            description: "Audit top-level frames whose names start with this",
+        },
+        {
+            name: "spacingSteps",
+            type: "number[]",
+            description: "Allowed gap and padding values; leave out to skip that check",
+        },
+        {
+            name: "ignoreUnbound",
+            type: "string[]",
+            description: "Names (starts) not reported as unbound",
+        },
     ], (p) => audit(p)), "built-in");
-    registry.register(readBuiltIn("tokens-dump", "Token sets in order and themes, as JSON.", [], () => tokensDump()), "built-in");
+    registry.register(readBuiltIn("tokens-dump", "Bounded typed token preview; tokens dump captures complete chunked evidence.", [], () => tokensDump()), "built-in");
     registry.register({
         kind: "write",
         name: "archive",
         description: "Nest the frames that are not part of the live work into one archive board. Frames keep names, ids and component links.",
         params: [
-            { name: "page", type: "string", required: true },
-            { name: "archiveName", type: "string", required: true, description: "Name of the archive board" },
-            { name: "keepPrefixes", type: "string[]", default: [], description: "Boards whose names start with one of these stay live" },
-            { name: "partPrefixes", type: "string[]", default: [], description: "Library parts, never archived" },
-            { name: "x", type: "number", default: 9000, description: "Where the archive board is placed" },
+            {
+                name: "page",
+                type: "string",
+                required: true,
+            },
+            {
+                name: "archiveName",
+                type: "string",
+                required: true,
+                description: "Name of the archive board",
+            },
+            {
+                name: "keepPrefixes",
+                type: "string[]",
+                default: [],
+                description: "Boards whose names start with one of these stay live",
+            },
+            {
+                name: "partPrefixes",
+                type: "string[]",
+                default: [],
+                description: "Library parts, never archived",
+            },
+            {
+                name: "x",
+                type: "number",
+                default: 9000,
+                description: "Where the archive board is placed",
+            },
         ],
         source: "built-in",
         operation: archiveOperation,

package/dist/run-file.d.ts

@@ -0,0 +1,26 @@
+import type { PenpotToolClient } from "./client.js";
+import { type Snippet } from "./snippet.js";
+import { type Params, type WriteEntry } from "./registry.js";
+import { type OperationOptions } from "./operation.js";
+export interface FileScriptOptions {
+    include?: string[];
+    page?: string;
+    params?: Params;
+    inspect?: string;
+    readback?: string;
+    virtualIncludes?: Record<string, string>;
+}
+export interface PreparedFileScript {
+    kind: "read" | "write";
+    source: {
+        file: string;
+        sha256: string;
+    }[];
+    params: Params;
+    page?: string;
+    read?: Snippet;
+    operation?: WriteEntry["operation"];
+}
+/** Reads and compiles explicitly selected files without importing project modules on the host. */
+export declare function prepareFileScript(root: string, file: string, options?: FileScriptOptions): Promise<PreparedFileScript>;
+export declare function runFileScript(client: PenpotToolClient, prepared: PreparedFileScript, options?: OperationOptions): Promise<Record<string, unknown>>;