@penpair/core 0.3.7 → 0.4.1

package/dist/cli-main.js

@@ -1,5 +1,7 @@
 import { auditDesignRules } from "./audit-rules.js";
 import { projectStatus, projectFileUrl, openProject } from "./project-status.js";
+import { wakeBrowserTarget } from "./browser-wake.js";
+import { pluginHealthFromError } from "./plugin-health.js";
 import { artifactSchemas, migrateProjectConfig } from "./formats.js";
 import { importDtcg, exportDtcg } from "./portable-tokens.js";
 import { captureStructuralSnapshot, writeStructuralSnapshot, readStructuralSnapshot, diffStructuralSnapshots, renderStructuralDiff, } from "./structure-snapshot.js";
@@ -23,7 +25,8 @@ import { resolveProjectOutput } from "./project-input.js";
 import { mkdir } from "node:fs/promises";
 import { captureShots, exportShapeByName, findShapesByName } from "./shots.js";
 import { exportShapePng } from "./export.js";
-import { exportBaselines } from "./baselines.js";
+import { exportBaselines, resolveBaselineImageFormat } from "./baselines.js";
+import { encodeBaselineImage } from "./image-codec.js";
 import { archiveOperation, runOnPage, runOperation } from "./operation.js";
 import { formatDeepReport, runDeepCheck } from "./deep-check.js";
 import { probe } from "./probe.js";
@@ -43,7 +46,7 @@ import { askHidden, askLine, openInBrowser } from "./instance/tty.js";
 import { validateSkillAgent } from "./skill-hosts.js";
 import { loadAdapters, readRawConfig, reservedCommands, } from "./adapters.js";
 import { requireLocalProfile } from "./local-profile.js";
-import { assertEndpointIsInstance, doctorExternal, LifecycleError, } from "./instance/connection.js";
+import { assertEndpointIsInstance, doctorExternal, doctorEditor, frontendUrl, LifecycleError, } from "./instance/connection.js";
 import { nodeRunner } from "./instance/runner.js";
 import { version } from "./version.js";
 import { guardFile } from "./file-guard.js";
@@ -54,6 +57,11 @@ import { backupNoteCheck } from "./backup-note.js";
 import { createCheckpoint } from "./native-api.js";
 import { listJournals, readJournal } from "./journal.js";
 const usageHead = `penpair ${version}
+Design agreements and release pages:
+  penpair journey-map check|render|publish|import|accept|approve|context --from FILE
+  penpair integration-map check|render|publish|import|accept|approve|context --from FILE
+  penpair design-release plan|assemble|verify|finalize|check|context --from FILE
+  (publication previews by default; --apply writes Penpot, --write records local acceptance/review)
 Start here (guided, plain language; safe to run again):
   penpair setup                                        asks where your Penpot is (web is the default), sets everything up and checks it
   penpair setup --web [--external <address>]           Penpot on the web: design.penpot.app, or your team's address; no questions about it
@@ -65,6 +73,7 @@ Connect / diagnose:
   penpair config check [--json]                        validate configuration offline
   penpair config schema                               print its JSON Schema
   penpair doctor [--json] [--timeout-ms 5000]           origin, transport, fresh editor read and file pin (1000–30000 ms)
+  penpair wake --debug-port 9222 [--json]              activate the pinned browser tab, then verify the editor; no reload or replay
   penpair status [--adapters]                          observed project health and optional companion readiness
   penpair open [--print]                              open the pinned public file URL, or print it
   penpair probe [--integrity]                          observed APIs and limits
@@ -78,7 +87,7 @@ Build:
   penpair snippets / snippets check                    list or validate configured trusted scripts
   penpair tokens add-set|set|remove|promote             inspect token edits; --apply writes once
   penpair archive --page PAGE --name Archive --keep PREFIX [--apply]
-  (run-file/export/shots accept --layout auto|native|geometry; default auto)
+  (run-file/run/archive/token edits/export/shots accept --layout auto|native|geometry, repeatable --layout-root ID, --layout-max-nodes 1..100000)
   (journaled writes accept --resume RUN_ID --apply, --checkpoint and --trace)
 Inspect / spec:
   penpair pages                                       file identity, revision and pages
@@ -202,6 +211,12 @@ async function main(argv, cli) {
             case: {
                 type: "string",
             },
+            format: {
+                type: "string",
+            },
+            "migrate-format": {
+                type: "boolean",
+            },
             "force-reason": {
                 type: "string",
             },
@@ -223,9 +238,19 @@ async function main(argv, cli) {
             "timeout-ms": {
                 type: "string",
             },
+            "debug-port": {
+                type: "string",
+            },
             layout: {
                 type: "string",
             },
+            "layout-root": {
+                type: "string",
+                multiple: true,
+            },
+            "layout-max-nodes": {
+                type: "string",
+            },
             page: {
                 type: "string",
             },
@@ -420,6 +445,11 @@ async function main(argv, cli) {
         "max-total-bytes",
         "capture-timeout-ms",
     ];
+    const layoutFlags = [
+        "layout",
+        "layout-root",
+        "layout-max-nodes",
+    ];
     const flags = {
         formats: [
             "out",
@@ -436,6 +466,7 @@ async function main(argv, cli) {
             "by",
             "case",
             "write",
+            "format",
         ],
         spec: [
             "from",
@@ -473,6 +504,7 @@ async function main(argv, cli) {
                     "theme",
                 ]
                 : [
+                    ...layoutFlags,
                     "type",
                     "value",
                     "description",
@@ -486,16 +518,17 @@ async function main(argv, cli) {
             "page",
             "scale",
             "name",
-            "layout",
+            ...layoutFlags,
         ],
         shots: [
             "page",
             "prefix",
             "out",
             "scale",
-            "layout",
+            ...layoutFlags,
         ],
         archive: [
+            ...layoutFlags,
             "page",
             "name",
             "keep",
@@ -514,7 +547,7 @@ async function main(argv, cli) {
             "include",
         ],
         "run-file": [
-            "layout",
+            ...layoutFlags,
             "include",
             "inspect",
             "readback",
@@ -527,6 +560,7 @@ async function main(argv, cli) {
             "trace",
         ],
         run: [
+            ...layoutFlags,
             "builtins-only",
             "param",
             "apply",
@@ -539,6 +573,8 @@ async function main(argv, cli) {
             "apply",
             "update",
             "force-reason",
+            "format",
+            "migrate-format",
         ],
         probe: [
             "deep",
@@ -579,6 +615,10 @@ async function main(argv, cli) {
         doctor: [
             "timeout-ms",
         ],
+        wake: [
+            "debug-port",
+            "timeout-ms",
+        ],
         up: [],
         down: [],
         open: [
@@ -629,6 +669,12 @@ async function main(argv, cli) {
             throw new Error(`--${key} is not supported by ${command || "this command"}`);
         }
     }
+    if (values.format && values.format !== "png" && values.format !== "webp") {
+        throw new CommandArgumentError("--format must be png or webp");
+    }
+    if (values["migrate-format"] && (!values.format || (values.apply && !values.update))) {
+        throw new CommandArgumentError("--migrate-format requires --format; applying it requires --update");
+    }
     for (const [key, min, max, integer] of [
         [
             "depth",
@@ -689,12 +735,31 @@ async function main(argv, cli) {
         ].includes(values.layout)) {
         throw new CommandArgumentError("--layout must be auto, native or geometry");
     }
-    if (command === "doctor" &&
+    if (values["layout-max-nodes"] !== undefined &&
+        (!/^\d+$/.test(values["layout-max-nodes"]) ||
+            Number(values["layout-max-nodes"]) < 1 ||
+            Number(values["layout-max-nodes"]) > 100000)) {
+        throw new CommandArgumentError("--layout-max-nodes must be an integer from 1 to 100000");
+    }
+    if (values["layout-root"] &&
+        (values["layout-root"].some((id) => !id.trim()) ||
+            new Set(values["layout-root"]).size !== values["layout-root"].length)) {
+        throw new CommandArgumentError("--layout-root must name distinct nonempty shape IDs");
+    }
+    if ((command === "doctor" || command === "wake") &&
         values["timeout-ms"] !== undefined &&
         (!/^\d+$/.test(values["timeout-ms"]) ||
             Number(values["timeout-ms"]) < 1000 ||
             Number(values["timeout-ms"]) > 30000)) {
-        throw new CommandArgumentError("doctor --timeout-ms must be an integer from 1000 to 30000");
+        throw new CommandArgumentError(`${command} --timeout-ms must be an integer from 1000 to 30000`);
+    }
+    if (command === "wake" &&
+        (rest.length ||
+            !values["debug-port"] ||
+            !/^\d+$/.test(values["debug-port"]) ||
+            Number(values["debug-port"]) < 1 ||
+            Number(values["debug-port"]) > 65535)) {
+        throw new CommandArgumentError("wake requires --debug-port with an integer from 1 to 65535");
     }
     let tokenEdit;
     if (command === "tokens" &&
@@ -1337,7 +1402,11 @@ async function main(argv, cli) {
                     {
                         check: "editor and plugin",
                         ok: false,
-                        detail: "No resolved project credential/connection; editor identity was not observed",
+                        detail: "No resolved project credential/connection; editor identity was not observed; heartbeat age unavailable; keep-alive unknown",
+                        evidence: {
+                            heartbeat: "unknown",
+                            pluginHealth: pluginHealthFromError(undefined),
+                        },
                         remedy: "Configure the private credential source, connect the intended editor, then rerun doctor.",
                     },
                 ]
@@ -1371,6 +1440,57 @@ async function main(argv, cli) {
         }
         return ok ? 0 : 1;
     }
+    if (command === "wake") {
+        const config = await loadCommandConfig(root);
+        if (!config.file?.id) {
+            throw new CommandArgumentError("Pin the owner-confirmed file before waking its browser tab");
+        }
+        const mcp = await mcpProbeFor();
+        if (!mcp) {
+            throw new Error("Configure the project's MCP connection before waking and verifying its tab");
+        }
+        assertEndpointIsInstance({
+            origin: mcp.origin,
+            source: "project connection",
+        }, config);
+        const timeoutMs = Number(values["timeout-ms"] ?? 5000);
+        const started = Date.now();
+        const activation = await wakeBrowserTarget({
+            origin: isExternal(config) ? config.profile.origin : frontendUrl(config),
+            allowLoopbackAlias: !isExternal(config),
+            fileId: config.file.id,
+            port: Number(values["debug-port"]),
+            timeoutMs,
+            signal: commandSignal(),
+        });
+        const remaining = timeoutMs - (Date.now() - started);
+        const checks = remaining > 0
+            ? await doctorEditor(config, {
+                mcp,
+                timeoutMs: remaining,
+            })
+            : [
+                {
+                    check: "editor and plugin",
+                    ok: false,
+                    detail: "Tab activation exhausted the verification deadline",
+                },
+            ];
+        const ready = checks.length > 0 && checks.every((check) => check.ok);
+        output.result({
+            ...activation,
+            ready,
+            checks,
+        });
+        if (!values.json) {
+            output.log("Browser activation acknowledged; sustained keep-alive: none. No write was replayed.");
+            for (const check of checks) {
+                output.log(`${check.ok ? "ok  " : "FAIL"} ${check.check}: ${check.detail}`);
+            }
+            output.log("Reconcile any uncertain run independently before explicitly resuming it.");
+        }
+        return ready ? 0 : 1;
+    }
     if (command === "open") {
         if (rest.length) {
             throw new CommandArgumentError("open accepts only --print for a URL preview");
@@ -1662,10 +1782,24 @@ async function main(argv, cli) {
     const client = await guarded();
     commandRedactor(endpointRedactor(endpoint));
     const options = {
-        ...(values.layout
+        ...(values.layout || values["layout-root"] || values["layout-max-nodes"]
             ? {
                 layout: {
-                    strategy: values.layout,
+                    ...(values.layout
+                        ? {
+                            strategy: values.layout,
+                        }
+                        : {}),
+                    ...(values["layout-root"]
+                        ? {
+                            shapeIds: values["layout-root"],
+                        }
+                        : {}),
+                    ...(values["layout-max-nodes"]
+                        ? {
+                            maxNodes: Number(values["layout-max-nodes"]),
+                        }
+                        : {}),
                 },
             }
             : {}),
@@ -1786,6 +1920,8 @@ async function main(argv, cli) {
                 apply: values.apply === true,
                 update: values.update === true,
                 forceReason: values["force-reason"],
+                format: values.format,
+                migrateFormat: values["migrate-format"],
             });
             output.result(report);
             for (const r of report.results) {
@@ -1908,6 +2044,7 @@ async function main(argv, cli) {
                 throw new CommandArgumentError("approve --page PAGE --frame ID [--case CASE_ID] previews evidence; --write requires --note exact-owner-words and --by identity");
             }
             let intent;
+            let imageFormat = values.format ?? "webp";
             if (values.case) {
                 const baseline = projectConfig?.baselines;
                 const wanted = baseline?.frames.find((f) => f.id === values.case);
@@ -1926,6 +2063,9 @@ async function main(argv, cli) {
                     }
                 }
                 intent = wanted.case;
+                imageFormat = values.format
+                    ? values.format
+                    : await resolveBaselineImageFormat(root, baseline, wanted.id);
             }
             const captured = await exportShapePng(client, values.frame, {
                 ...options,
@@ -1935,17 +2075,21 @@ async function main(argv, cli) {
             if (!captured.stable) {
                 throw new Error("Approval export did not stabilize");
             }
-            const sha256 = artifactSha(captured.png);
+            const approvalImage = await encodeBaselineImage(captured.png, imageFormat);
+            const sha256 = artifactSha(approvalImage);
             const report = values.write
                 ? await recordApproval(root, captured, {
                     note: values.note,
                     by: values.by,
-                }, intent, endpointRedactor(endpoint))
+                }, intent, endpointRedactor(endpoint), {
+                    format: imageFormat,
+                })
                 : {
                     schemaVersion: 1,
                     kind: "approval-candidate",
                     capture: captured.capture,
                     sha256,
+                    imageFormat,
                     fingerprint: approvalFingerprint(captured.capture, sha256, intent),
                     recorded: false,
                 };
@@ -2148,6 +2292,36 @@ async function runAdapterCommand(command, root, args) {
 async function runCliInternal(argv, options = {}) {
     try {
         const root = projectRoot();
+        if (argv[0] === "journey-map" ||
+            argv[0] === "integration-map" ||
+            argv[0] === "design-release") {
+            const { runDesignCommand } = await import("./design-commands/index.js");
+            let designRedactor = (text) => redactEndpoint(text);
+            return await runDesignCommand(argv[0], argv.slice(1), {
+                root,
+                output,
+                redact: (text) => designRedactor(text),
+                async withPenpot(work) {
+                    const config = await loadCommandConfig(root);
+                    if (!config.file?.id) {
+                        throw new Error("Live design commands require an explicitly pinned Penpot file");
+                    }
+                    const endpoint = await projectEndpoint(root);
+                    designRedactor = endpointRedactor(endpoint);
+                    commandRedactor(endpointRedactor(endpoint));
+                    assertEndpointIsInstance(endpoint.description, config);
+                    const client = guardFile(await connect(endpoint), config.file, {
+                        mode: "strict",
+                    });
+                    try {
+                        return await work(client);
+                    }
+                    finally {
+                        await client.close();
+                    }
+                },
+            });
+        }
         if (argv[0] === "onboard") {
             if (argv.slice(1).some((arg) => arg !== "--json")) {
                 throw new Error("usage: penpair onboard [--json]");
@@ -2330,15 +2504,16 @@ async function runCliBound(argv, options = {}) {
         ...argv,
     ];
     const timeoutAt = args.indexOf("--timeout-ms");
+    const boundedDiagnosis = args[0] === "doctor" || args[0] === "wake";
     let invalidTimeout = false;
     if (timeoutAt !== -1) {
         const milliseconds = Number(args[timeoutAt + 1]);
         invalidTimeout =
             !Number.isInteger(milliseconds) ||
-                milliseconds < (args[0] === "doctor" ? 1000 : 1) ||
-                milliseconds > (args[0] === "doctor" ? 30000 : 1_800_000) ||
+                milliseconds < (boundedDiagnosis ? 1000 : 1) ||
+                milliseconds > (boundedDiagnosis ? 30000 : 1_800_000) ||
                 args.indexOf("--timeout-ms", timeoutAt + 1) !== -1;
-        if (args[0] !== "doctor") {
+        if (!boundedDiagnosis) {
             args.splice(timeoutAt, 2);
         }
         if (!invalidTimeout) {
@@ -2365,8 +2540,8 @@ async function runCliBound(argv, options = {}) {
     try {
         if (invalidTimeout) {
             const result = await collectCommand(args[0] ?? "help", async () => {
-                throw new Error(args[0] === "doctor"
-                    ? "doctor --timeout-ms must be one integer from 1000 to 30000"
+                throw new Error(boundedDiagnosis
+                    ? `${args[0]} --timeout-ms must be one integer from 1000 to 30000`
                     : "--timeout-ms must be one integer from 1 to 1800000");
             });
             if (json) {

package/dist/design-commands/context.d.ts

@@ -0,0 +1,9 @@
+import type { CommandOutput } from "../command-result.js";
+import type { PenpotToolClient } from "../client.js";
+/** Project-owned artifact commands can work offline; a live operation opens a strictly pinned connection. */
+export interface DesignCommandContext {
+    root: string;
+    output: CommandOutput;
+    redact(value: string): string;
+    withPenpot<T>(work: (client: PenpotToolClient) => Promise<T>): Promise<T>;
+}

package/dist/design-commands/context.js

@@ -0,0 +1 @@
+export {};

package/dist/design-commands/index.d.ts

@@ -0,0 +1,3 @@
+import type { DesignCommandContext } from "./context.js";
+export type { DesignCommandContext } from "./context.js";
+export declare function runDesignCommand(family: "journey-map" | "integration-map" | "design-release", args: string[], context: DesignCommandContext): Promise<number>;

package/dist/design-commands/index.js

@@ -0,0 +1,7 @@
+import { runMapCommand } from "./map-command.js";
+import { runDesignReleaseCommand } from "./release-command.js";
+export async function runDesignCommand(family, args, context) {
+    return family === "design-release"
+        ? runDesignReleaseCommand(args, context)
+        : runMapCommand(family, args, context);
+}

package/dist/design-commands/map-command.d.ts

@@ -0,0 +1,4 @@
+import type { MapKind } from "../maps/types.js";
+import type { DesignCommandContext } from "./context.js";
+/** Explicit local artifact actions remain offline; native publication is preview-only until --apply. */
+export declare function runMapCommand(kind: MapKind, args: string[], context: DesignCommandContext): Promise<number>;