@penpair/core 0.3.6 → 0.4.0

package/dist/adapters.d.ts

@@ -51,7 +51,7 @@ export interface Adapter {
 /** Declares an adapter. Returns the definition unchanged, so a module can `export default defineAdapter({...})` with types checked. */
 export declare const defineAdapter: <T extends Adapter>(adapter: T) => T;
 /** The commands of the core itself; an adapter cannot take one of these names. */
-export declare const reservedCommands: readonly ["formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect", "up", "down", "open", "status", "doctor", "backup", "restore", "baselines", "config", "runs", "onboard", "help"];
+export declare const reservedCommands: readonly ["journey-map", "integration-map", "design-release", "formats", "snapshot", "approve", "mcp", "spec", "inspect", "probe", "pages", "tree", "audit", "tokens", "export", "shots", "archive", "snippets", "run", "run-file", "kit", "recipes", "skills", "init", "setup", "connect", "up", "down", "open", "status", "doctor", "backup", "restore", "baselines", "config", "runs", "onboard", "help"];
 export interface LoadedAdapters {
     adapters: Adapter[];
     problems: string[];

package/dist/adapters.js

@@ -7,6 +7,9 @@ import { readProjectConfig } from "./instance/config.js";
 export const defineAdapter = (adapter) => adapter;
 /** The commands of the core itself; an adapter cannot take one of these names. */
 export const reservedCommands = [
+    "journey-map",
+    "integration-map",
+    "design-release",
     "formats",
     "snapshot",
     "approve",

package/dist/approvals.d.ts

@@ -1,5 +1,6 @@
 import type { CaptureIdentity, ExportResult } from "./export.js";
 import { type BaselineCase } from "./baselines-config.js";
+import type { BaselineImageFormat } from "./image-evidence.js";
 export interface ApprovalRecord {
     schemaVersion: 1;
     id: string;
@@ -28,5 +29,7 @@ export declare function readApprovals(root: string): Promise<ApprovalFile>;
 export declare function recordApproval(root: string, exported: ExportResult, words: {
     note: string;
     by: string;
-}, intent?: BaselineCase, redact?: (text: string) => string): Promise<ApprovalRecord>;
+}, intent?: BaselineCase, redact?: (text: string) => string, options?: {
+    format?: BaselineImageFormat;
+}): Promise<ApprovalRecord>;
 export declare function matchingApproval(root: string, capture: CaptureIdentity, sha256: string, intent?: BaselineCase): Promise<ApprovalRecord | undefined>;

package/dist/approvals.js

@@ -7,6 +7,7 @@ import { observationHash } from "./journal.js";
 import { resolveProjectInput, resolveProjectOutput } from "./project-input.js";
 import { validateBaselineCase } from "./baselines-config.js";
 import { pngSize } from "./png.js";
+import { encodeBaselineImage } from "./image-codec.js";
 export const approvalFile = "design/approvals.json";
 export const artifactSha = (bytes) => createHash("sha256").update(bytes).digest("hex");
 export function approvalFingerprint(capture, sha256, intent) {
@@ -91,7 +92,7 @@ export async function readApprovals(root) {
     }
 }
 /** Records supplied owner words; hashes detect accidental changes, not identity or consent. */
-export async function recordApproval(root, exported, words, intent, redact) {
+export async function recordApproval(root, exported, words, intent, redact, options = {}) {
     exported = {
         ...exported,
         capture: structuredClone(exported.capture),
@@ -113,7 +114,9 @@ export async function recordApproval(root, exported, words, intent, redact) {
         words.by.length > 200) {
         throw new Error("Supply the owner's exact nonempty words and identity; an agent cannot invent approval");
     }
-    const sha256 = artifactSha(exported.png);
+    const format = options.format ?? "png";
+    const imageBytes = await encodeBaselineImage(exported.png, format);
+    const sha256 = artifactSha(imageBytes);
     const fingerprint = approvalFingerprint(exported.capture, sha256, intent);
     if (intent &&
         (!matchesDesignViewport(exported.capture.designSize, intent.viewport) ||
@@ -142,7 +145,7 @@ export async function recordApproval(root, exported, words, intent, redact) {
             }
             : {}),
         sha256,
-        image: `design/approvals/${sha256}.png`,
+        image: `design/approvals/${sha256}.${format}`,
         fingerprint,
     };
     const record = {
@@ -168,7 +171,7 @@ export async function recordApproval(root, exported, words, intent, redact) {
             recursive: true,
         });
         try {
-            await atomicWriteFile(image, exported.png);
+            await atomicWriteFile(image, imageBytes);
         }
         catch (error) {
             if (error.code !== "EEXIST" ||

package/dist/baseline-coverage.js

@@ -2,7 +2,7 @@ import { open } from "node:fs/promises";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { resolveProjectOutput } from "./project-input.js";
-import { pngSize } from "./png.js";
+import { inspectImageEvidence } from "./image-evidence.js";
 import { matchesDesignViewport } from "./design-viewport.js";
 import { validateBaselines, } from "./baselines-config.js";
 import { observationHash } from "./journal.js";
@@ -228,13 +228,13 @@ export async function readBaselineCoverage(root, config, expectedFileId) {
             }
             const target = await resolveProjectOutput(root, path.join(config.root, result.file));
             const bytes = await boundedRead(target, 64 * 1024 * 1024);
-            const size = pngSize(bytes);
+            const size = inspectImageEvidence(bytes);
             if (!size ||
                 size.width < 1 ||
                 size.height < 1 ||
                 createHash("sha256").update(bytes).digest("hex") !== result.approved.sha256 ||
                 result.sha256 !== result.approved.sha256) {
-                throw new Error("Approved PNG bytes do not match their manifest");
+                throw new Error("Approved image bytes do not match their manifest");
             }
             result.imageWidth = size.width;
             result.imageHeight = size.height;

package/dist/baselines-config.d.ts

@@ -1,3 +1,4 @@
+import type { BaselineImageFormat } from "./image-evidence.js";
 /** Declared design intent. It does not switch themes or establish browser behavior. */
 export interface BaselineCase {
     viewport: {
@@ -34,6 +35,8 @@ export interface BaselineFrame {
 }
 /** What `penpair baselines` exports: the frames of one page, as images in a folder of the project. */
 export interface BaselinesConfig {
+    /** Encoding for new references; existing approved formats require explicit migration. */
+    format?: BaselineImageFormat;
     page: string;
     /** Folder for the images, relative to the project. */
     root: string;

package/dist/baselines-config.js

@@ -6,6 +6,9 @@ export function validateBaselines(value, fail) {
         return fail("baselines must be an object");
     }
     const v = value;
+    if (v.format !== undefined && v.format !== "png" && v.format !== "webp") {
+        fail("baselines.format must be png or webp");
+    }
     if (typeof v.page !== "string" || v.page.length === 0) {
         fail("baselines.page must be the name of a page");
     }

package/dist/baselines.d.ts

@@ -1,3 +1,4 @@
+import { type BaselineImageFormat } from "./image-evidence.js";
 export { pngSize } from "./png.js";
 import type { PenpotToolClient } from "./client.js";
 import { type BaselineCoverage } from "./baseline-coverage.js";
@@ -70,6 +71,10 @@ export interface BaselinesReport {
     wrote: string[];
 }
 export interface BaselinesOptions extends ExportOptions {
+    /** Encoding for new references, or the explicit migration target. */
+    format?: BaselineImageFormat;
+    /** Change an existing reference's encoding; apply also requires update and exact-artifact approval. */
+    migrateFormat?: boolean;
     signal?: AbortSignal;
     /** Write images that are new. Without it nothing is written, whatever is found. */
     apply?: boolean;
@@ -78,6 +83,8 @@ export interface BaselinesOptions extends ExportOptions {
     /** Explicit waiver for a changed baseline; retained as a forced reference, never an owner approval. */
     forceReason?: string;
 }
+/** Resolve the exact encoding used by both approval and baseline capture. */
+export declare function resolveBaselineImageFormat(projectRoot: string, config: BaselinesConfig, baselineId: string, options?: Pick<BaselinesOptions, "format" | "migrateFormat">): Promise<BaselineImageFormat>;
 /**
  * Exports the configured frames of a page as images into the project's folder: the approved design that an implementation is
  * checked against. Looks first; writes only with `apply`, and replaces an image that differs only with `update`, so a change of

package/dist/baselines.js

@@ -1,9 +1,11 @@
 import { matchingApproval } from "./approvals.js";
 import { matchesDesignViewport } from "./design-viewport.js";
 import { pngSize } from "./png.js";
+import { encodeBaselineImage } from "./image-codec.js";
+import { inspectImageEvidence } from "./image-evidence.js";
 export { pngSize } from "./png.js";
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { baselineCoverage } from "./baseline-coverage.js";
 import { resolveProjectOutput } from "./project-input.js";
@@ -16,9 +18,16 @@ import { runOnPage } from "./operation.js";
 import { frames } from "./snippets/read.js";
 export * from "./baselines-config.js";
 const sha = (buffer) => createHash("sha256").update(buffer).digest("hex");
-async function readIfExists(file) {
+async function readIfExists(file, maximum = 64 * 1024 * 1024) {
     try {
-        return await readFile(file);
+        if ((await stat(file)).size > maximum) {
+            throw new Error("Baseline artifact exceeds its read budget");
+        }
+        const bytes = await readFile(file);
+        if (bytes.length > maximum) {
+            throw new Error("Baseline artifact exceeds its read budget");
+        }
+        return bytes;
     }
     catch (error) {
         if (error.code === "ENOENT") {
@@ -27,12 +36,72 @@ async function readIfExists(file) {
         throw error;
     }
 }
+async function existingBaseline(projectRoot, config, id, old) {
+    const candidates = old
+        ? [
+            old.file,
+        ]
+        : [
+            `${id}.png`,
+            `${id}.webp`,
+        ];
+    let found = {};
+    for (const file of candidates) {
+        if (typeof file !== "string" || path.isAbsolute(file) || file.split(/[\\/]/).includes("..")) {
+            throw new Error("Existing baseline path leaves its folder");
+        }
+        const bytes = await readIfExists(await resolveProjectOutput(projectRoot, path.join(config.root, file)));
+        if (!bytes) {
+            continue;
+        }
+        if (found.bytes) {
+            throw new Error("Existing baseline candidates are ambiguous; inspect before capture");
+        }
+        found = {
+            file,
+            bytes,
+            format: inspectImageEvidence(bytes).format,
+        };
+    }
+    if (old &&
+        (!found.bytes ||
+            old.sha256 !== sha(found.bytes) ||
+            (old.approved && old.approved.sha256 !== old.sha256))) {
+        throw new Error("Approved baseline bytes no longer match their manifest; inspect before replacing");
+    }
+    return found;
+}
+/** Resolve the exact encoding used by both approval and baseline capture. */
+export async function resolveBaselineImageFormat(projectRoot, config, baselineId, options = {}) {
+    const target = options.format ?? config.format ?? "webp";
+    if (target !== "png" && target !== "webp") {
+        throw new Error("Baseline format must be png or webp");
+    }
+    const manifestPath = await resolveProjectOutput(projectRoot, path.join(config.root, "penpair-baselines.json"));
+    const bytes = await readIfExists(manifestPath, 16 * 1024 * 1024);
+    const previous = bytes ? JSON.parse(bytes.toString("utf8")) : undefined;
+    if (previous &&
+        ((previous.schemaVersion !== undefined && previous.schemaVersion !== 2) ||
+            !Array.isArray(previous.frames) ||
+            previous.frames.length > 1000)) {
+        throw new Error("Existing baseline manifest is invalid; preserve and inspect it");
+    }
+    const old = previous?.frames?.find((entry) => entry.id === baselineId);
+    const existing = await existingBaseline(projectRoot, config, baselineId, old);
+    return existing.format && !options.migrateFormat ? existing.format : target;
+}
 /**
  * Exports the configured frames of a page as images into the project's folder: the approved design that an implementation is
  * checked against. Looks first; writes only with `apply`, and replaces an image that differs only with `update`, so a change of
  * the design never silently becomes the new reference.
  */
 export async function exportBaselines(client, projectRoot, config, options = {}) {
+    if (options.format !== undefined && options.format !== "png" && options.format !== "webp") {
+        throw new Error("Baseline format must be png or webp");
+    }
+    if (options.migrateFormat && options.apply && !options.update) {
+        throw new Error("Applying a baseline format migration requires update");
+    }
     if (options.forceReason !== undefined &&
         (!options.update ||
             !options.apply ||
@@ -65,7 +134,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
     const wrote = [];
     const folder = await resolveProjectOutput(projectRoot, config.root);
     const manifestPath = await resolveProjectOutput(projectRoot, path.join(config.root, "penpair-baselines.json"));
-    const previousBytes = await readIfExists(manifestPath);
+    const previousBytes = await readIfExists(manifestPath, 16 * 1024 * 1024);
     const previous = previousBytes
         ? JSON.parse(previousBytes.toString("utf8"))
         : undefined;
@@ -80,7 +149,13 @@ export async function exportBaselines(client, projectRoot, config, options = {})
     for (const wanted of config.frames) {
         options.signal?.throwIfAborted();
         const old = previous?.frames?.find((entry) => entry.id === wanted.id);
-        const file = old?.file ?? `${wanted.id}.png`;
+        const existingEvidence = await existingBaseline(projectRoot, config, wanted.id, old);
+        const format = existingEvidence.format && !options.migrateFormat
+            ? existingEvidence.format
+            : (options.format ?? config.format ?? "webp");
+        const migrating = Boolean(existingEvidence.format && existingEvidence.format !== format);
+        const existing = existingEvidence.bytes;
+        const file = existingEvidence.file ?? `${wanted.id}.${format}`;
         if (path.isAbsolute(file) || file.split(/[\\/]/).includes("..")) {
             throw new Error("Existing baseline path leaves its folder");
         }
@@ -157,13 +232,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         if (!pngSize(exported.png)) {
             throw new Error("Baseline export is not a PNG with dimensions");
         }
-        const existing = await readIfExists(await resolveProjectOutput(projectRoot, path.join(config.root, file)));
-        if (old &&
-            (!existing ||
-                old.sha256 !== sha(existing) ||
-                (old.approved && old.approved.sha256 !== old.sha256))) {
-            throw new Error("Approved baseline bytes no longer match their manifest; inspect before replacing");
-        }
+        const encoded = await encodeBaselineImage(exported.png, format);
         const captured = {
             ...(wanted.case
                 ? {
@@ -172,10 +241,10 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                 : {}),
             layout: exported.layout,
             ...exported.capture,
-            sha256: sha(exported.png),
+            sha256: sha(encoded),
             capturedAt: new Date().toISOString(),
             toolVersion: version,
-            file: `${generation}/${wanted.id}.png`,
+            file: `${generation}/${wanted.id}.${format}`,
         };
         const caseProblems = [];
         if (wanted.case) {
@@ -237,7 +306,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                     recordHash: record.hash,
                 };
             }
-            else if (options.forceReason) {
+            else if (options.forceReason && !migrating) {
                 captured.approval = {
                     kind: "forced-reference",
                     reason: options.forceReason,
@@ -256,8 +325,8 @@ export async function exportBaselines(client, projectRoot, config, options = {})
                 legacy: true,
                 sha256: sha(existing),
             });
-        const image = approve ? exported.png : existing;
-        const size = pngSize(image);
+        const image = approve ? encoded : existing;
+        const size = inspectImageEvidence(image);
         results.push({
             ...base,
             file: approve && options.apply ? captured.file : file,
@@ -270,7 +339,7 @@ export async function exportBaselines(client, projectRoot, config, options = {})
             imageWidth: size?.width,
             imageHeight: size?.height,
         });
-        captures.set(wanted.id, exported.png);
+        captures.set(`${wanted.id}.${format}`, encoded);
     }
     const after = await runOnPage(client, frames({
         page: config.page,
@@ -311,10 +380,10 @@ export async function exportBaselines(client, projectRoot, config, options = {})
         const staged = path.join(folder, `.stage-${runId}`);
         await mkdir(staged);
         try {
-            for (const [id, bytes] of captures) {
+            for (const [file, bytes] of captures) {
                 options.signal?.throwIfAborted();
-                await atomicWriteFile(path.join(staged, `${id}.png`), bytes);
-                options.onStep?.(`staging ${id}`);
+                await atomicWriteFile(path.join(staged, file), bytes);
+                options.onStep?.(`staging ${path.parse(file).name}`);
             }
             const cases = reflectionCases(config, results);
             await writeFile(path.join(staged, "reflection-cases.json"), `${JSON.stringify({

package/dist/bounded-file.d.ts

@@ -0,0 +1,2 @@
+/** Read a regular project file with an allocation bound even if another process grows it. */
+export declare function readProjectBytes(root: string, file: string, maxBytes: number): Promise<Buffer>;

package/dist/bounded-file.js

@@ -0,0 +1,38 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
+/** Read a regular project file with an allocation bound even if another process grows it. */
+export async function readProjectBytes(root, file, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new Error("A positive file byte budget is required");
+    }
+    const input = await resolveProjectInput(root, file);
+    if (!(await lstat(input)).isFile()) {
+        throw new Error("Artifact input must be a regular file");
+    }
+    const handle = await open(input, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxBytes) {
+            throw new Error("Artifact input is not a regular file within its byte budget");
+        }
+        const chunks = [];
+        let total = 0;
+        while (total <= maxBytes) {
+            const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes + 1 - total));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+            if (bytesRead === 0) {
+                return Buffer.concat(chunks, total);
+            }
+            total += bytesRead;
+            if (total > maxBytes) {
+                throw new Error("Artifact input exceeds its byte budget");
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        throw new Error("Artifact input exceeds its byte budget");
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/cli-main.js

@@ -23,7 +23,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";
@@ -54,6 +55,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
@@ -202,6 +208,12 @@ async function main(argv, cli) {
             case: {
                 type: "string",
             },
+            format: {
+                type: "string",
+            },
+            "migrate-format": {
+                type: "boolean",
+            },
             "force-reason": {
                 type: "string",
             },
@@ -436,6 +448,7 @@ async function main(argv, cli) {
             "by",
             "case",
             "write",
+            "format",
         ],
         spec: [
             "from",
@@ -539,6 +552,8 @@ async function main(argv, cli) {
             "apply",
             "update",
             "force-reason",
+            "format",
+            "migrate-format",
         ],
         probe: [
             "deep",
@@ -629,6 +644,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",
@@ -1786,6 +1807,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 +1931,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 +1950,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 +1962,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 +2179,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]");

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>;