@penpair/core 0.1.3 → 0.3.0

package/dist/adapters.d.ts

@@ -1,3 +1,5 @@
+import type { BuildKit } from "./kit.js";
+import type { CommandOutput } from "./command-result.js";
 import type { PenpotToolClient } from "./client.js";
 import { type ProjectConfig } from "./instance/config.js";
 /**
@@ -6,6 +8,9 @@ import { type ProjectConfig } from "./instance/config.js";
  * project and knows nothing about any of them. An adapter keeps its own settings in its own block of the same file.
  */
 export interface AdapterContext {
+    output?: CommandOutput;
+    /** Removes this connection's credentials before recovery evidence is persisted or reported. */
+    redact?(text: string): string;
     /** The project's folder. */
     root: string;
     /** The project's validated configuration. */
@@ -29,14 +34,24 @@ export interface AdapterCommand {
     /** Runs with the arguments after the command's name; returns the exit code. The adapter parses its own flags. */
     run(context: AdapterContext, args: string[]): Promise<number>;
 }
+export interface AdapterStatusLine {
+    id: string;
+    label: string;
+    state: "ok" | "warning" | "failed" | "unknown";
+    detail: string;
+}
 export interface Adapter {
     name: string;
     commands: AdapterCommand[];
+    /** Executed only by an explicit status --adapters request; trusted project code. */
+    status?(context: AdapterContext): Promise<AdapterStatusLine[]>;
+    /** Explicit opt-in plugin-source includes. Built-in commands do not load these unless requested. */
+    kits?: BuildKit[];
 }
 /** 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 ["probe", "pages", "tree", "audit", "tokens", "export", "archive", "snippets", "run", "skills", "init", "setup", "connect", "up", "down", "status", "doctor", "backup", "restore", "baselines"];
+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 interface LoadedAdapters {
     adapters: Adapter[];
     problems: string[];

package/dist/adapters.js

@@ -1,26 +1,66 @@
-import { readFile } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { configFileName } from "./instance/config.js";
+import { readProjectConfig } from "./instance/config.js";
 /** Declares an adapter. Returns the definition unchanged, so a module can `export default defineAdapter({...})` with types checked. */
 export const defineAdapter = (adapter) => adapter;
 /** The commands of the core itself; an adapter cannot take one of these names. */
 export const reservedCommands = [
-    "probe", "pages", "tree", "audit", "tokens", "export", "archive", "snippets", "run", "skills", "init", "setup", "connect",
-    "up", "down", "status", "doctor", "backup", "restore", "baselines",
+    "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",
 ];
 /** Resolves an adapter the way the project would: a relative path from the project's folder, or a package installed in the project. */
 export const importFromProject = async (specifier, root) => {
     let file;
-    if (specifier.startsWith(".") || path.isAbsolute(specifier))
-        file = path.resolve(root, specifier);
+    if (specifier.startsWith(".") || path.isAbsolute(specifier)) {
+        file = await resolveProjectInput(root, specifier);
+    }
     else {
+        if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+(?:\/[a-z0-9._-]+)*$/i.test(specifier) ||
+            specifier.split("/").includes("..")) {
+            throw new Error("Adapter must name an installed package or a relative project module");
+        }
         try {
             file = createRequire(path.join(root, "package.json")).resolve(specifier);
         }
         catch {
-            const error = Object.assign(new Error(`${specifier} is not installed in this project`), { code: "ERR_MODULE_NOT_FOUND" });
+            const error = Object.assign(new Error(`${specifier} is not installed in this project`), {
+                code: "ERR_MODULE_NOT_FOUND",
+            });
             throw error;
         }
     }
@@ -48,24 +88,27 @@ export async function loadAdapters(root, specifiers, importer = importFromProjec
             continue;
         }
         for (const command of adapter.commands) {
-            if (reservedCommands.includes(command.name))
+            if (reservedCommands.includes(command.name)) {
                 problems.push(`adapter ${specifier}: the command "${command.name}" is one the core already has`);
-            else if (taken.has(command.name))
+            }
+            else if (taken.has(command.name)) {
                 problems.push(`adapter ${specifier}: the command "${command.name}" is already provided by ${taken.get(command.name)}`);
-            else
+            }
+            else {
                 taken.set(command.name, adapter.name);
+            }
         }
-        adapters.push({ ...adapter, commands: adapter.commands.filter((c) => taken.get(c.name) === adapter.name) });
+        adapters.push({
+            ...adapter,
+            commands: adapter.commands.filter((c) => taken.get(c.name) === adapter.name),
+        });
     }
-    return { adapters, problems };
+    return {
+        adapters,
+        problems,
+    };
 }
 /** The whole penpair.config.json as written (an adapter's own settings live in it). Empty when there is no file. */
 export async function readRawConfig(root) {
-    try {
-        const parsed = JSON.parse(await readFile(path.join(root, configFileName), "utf8"));
-        return typeof parsed === "object" && parsed !== null ? parsed : {};
-    }
-    catch {
-        return {};
-    }
+    return (await readProjectConfig(root)) ?? {};
 }

package/dist/approvals.d.ts

@@ -0,0 +1,32 @@
+import type { CaptureIdentity, ExportResult } from "./export.js";
+import { type BaselineCase } from "./baselines-config.js";
+export interface ApprovalRecord {
+    schemaVersion: 1;
+    id: string;
+    kind: "owner-words";
+    recordedAt: string;
+    by: string;
+    note: string;
+    capture: CaptureIdentity;
+    case?: BaselineCase;
+    sha256: string;
+    image: string;
+    fingerprint: string;
+    hash: string;
+}
+export interface ApprovalFile {
+    schemaVersion: 1;
+    kind: "design-approvals";
+    records: ApprovalRecord[];
+}
+export declare const approvalFile = "design/approvals.json";
+export declare const artifactSha: (bytes: Buffer) => string;
+export declare function approvalFingerprint(capture: CaptureIdentity, sha256: string, intent?: BaselineCase): string;
+export declare function validateApprovals(raw: unknown): ApprovalFile;
+export declare function readApprovals(root: string): Promise<ApprovalFile>;
+/** Records supplied owner words; hashes detect accidental changes, not identity or consent. */
+export declare function recordApproval(root: string, exported: ExportResult, words: {
+    note: string;
+    by: string;
+}, intent?: BaselineCase, redact?: (text: string) => string): Promise<ApprovalRecord>;
+export declare function matchingApproval(root: string, capture: CaptureIdentity, sha256: string, intent?: BaselineCase): Promise<ApprovalRecord | undefined>;

package/dist/approvals.js

@@ -0,0 +1,213 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteFile } from "./atomic-output.js";
+import { observationHash } from "./journal.js";
+import { resolveProjectInput, resolveProjectOutput } from "./project-input.js";
+import { validateBaselineCase } from "./baselines-config.js";
+import { pngSize } from "./png.js";
+export const approvalFile = "design/approvals.json";
+export const artifactSha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+export function approvalFingerprint(capture, sha256, intent) {
+    if (!capture ||
+        typeof capture.fileId !== "string" ||
+        !capture.fileId ||
+        typeof capture.pageId !== "string" ||
+        !capture.pageId ||
+        typeof capture.frameId !== "string" ||
+        !capture.frameId ||
+        !Number.isInteger(capture.revision) ||
+        !Number.isFinite(capture.scale) ||
+        capture.scale <= 0 ||
+        !/^[a-f0-9]{64}$/.test(sha256)) {
+        throw new Error("Approval requires exact capture identity, revision, scale and SHA-256");
+    }
+    if (intent) {
+        validateBaselineCase(intent, (message) => {
+            throw new Error(message);
+        });
+    }
+    return observationHash({
+        capture,
+        sha256,
+        case: intent ?? null,
+    });
+}
+export function validateApprovals(raw) {
+    const v = raw;
+    if (!v ||
+        v.schemaVersion !== 1 ||
+        v.kind !== "design-approvals" ||
+        !Array.isArray(v.records) ||
+        v.records.length > 10000) {
+        throw new Error("Unsupported approval document");
+    }
+    const ids = new Set();
+    for (const r of v.records) {
+        if (!r ||
+            r.schemaVersion !== 1 ||
+            r.kind !== "owner-words" ||
+            typeof r.id !== "string" ||
+            !r.id ||
+            ids.has(r.id) ||
+            typeof r.note !== "string" ||
+            !r.note.trim() ||
+            r.note.length > 4000 ||
+            typeof r.by !== "string" ||
+            !r.by.trim() ||
+            r.by.length > 200 ||
+            !Number.isFinite(Date.parse(r.recordedAt)) ||
+            typeof r.image !== "string" ||
+            !r.image) {
+            throw new Error("Malformed owner approval record");
+        }
+        ids.add(r.id);
+        const { hash, ...body } = r;
+        if (hash !== observationHash(body) ||
+            r.fingerprint !== approvalFingerprint(r.capture, r.sha256, r.case)) {
+            throw new Error("Approval evidence hash mismatch");
+        }
+    }
+    return v;
+}
+export async function readApprovals(root) {
+    try {
+        const file = await resolveProjectInput(root, approvalFile);
+        if ((await stat(file)).size > 16 * 1024 * 1024) {
+            throw new Error("Approval file exceeds 16 MiB");
+        }
+        return validateApprovals(JSON.parse(await readFile(file, "utf8")));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                schemaVersion: 1,
+                kind: "design-approvals",
+                records: [],
+            };
+        }
+        throw error;
+    }
+}
+/** Records supplied owner words; hashes detect accidental changes, not identity or consent. */
+export async function recordApproval(root, exported, words, intent, redact) {
+    exported = {
+        ...exported,
+        capture: structuredClone(exported.capture),
+        png: Buffer.from(exported.png),
+    };
+    intent = intent ? structuredClone(intent) : undefined;
+    words = {
+        ...words,
+    };
+    if (!exported.stable || !pngSize(exported.png)) {
+        throw new Error("Approval requires a stable independently exported PNG");
+    }
+    if (typeof words.note !== "string" ||
+        !words.note.trim() ||
+        words.note.length > 4000 ||
+        typeof words.by !== "string" ||
+        !words.by.trim() ||
+        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 fingerprint = approvalFingerprint(exported.capture, sha256, intent);
+    if (intent &&
+        (!exported.capture.designSize ||
+            exported.capture.designSize.width !== intent.viewport.width ||
+            exported.capture.designSize.height !== intent.viewport.height ||
+            (intent.activeThemeIds &&
+                observationHash([
+                    ...(exported.capture.activeThemeIds ?? []),
+                ].sort()) !==
+                    observationHash([
+                        ...intent.activeThemeIds,
+                    ].sort())))) {
+        throw new Error("Approval case assertions do not match observed capture");
+    }
+    const body = {
+        schemaVersion: 1,
+        id: randomUUID(),
+        kind: "owner-words",
+        recordedAt: new Date().toISOString(),
+        by: words.by,
+        note: words.note,
+        capture: exported.capture,
+        ...(intent
+            ? {
+                case: intent,
+            }
+            : {}),
+        sha256,
+        image: `design/approvals/${sha256}.png`,
+        fingerprint,
+    };
+    const record = {
+        ...body,
+        hash: observationHash(body),
+    };
+    const serialized = JSON.stringify(record);
+    if (redact && redact(serialized) !== serialized) {
+        throw new Error("Approval requires credential redaction; no record was written");
+    }
+    const file = await resolveProjectOutput(root, approvalFile);
+    await mkdir(path.dirname(file), {
+        recursive: true,
+    });
+    const lock = await open(file + ".lock", "wx", 0o600);
+    try {
+        const previous = await readApprovals(root);
+        if (previous.records.length >= 10000) {
+            throw new Error("Approval document record limit reached");
+        }
+        const image = await resolveProjectOutput(root, record.image);
+        await mkdir(path.dirname(image), {
+            recursive: true,
+        });
+        try {
+            await atomicWriteFile(image, exported.png);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST" ||
+                artifactSha(await readFile(image)) !== sha256) {
+                throw error;
+            }
+        }
+        const next = JSON.stringify({
+            ...previous,
+            records: [
+                ...previous.records,
+                record,
+            ],
+        }, null, 2) + "\n";
+        if (Buffer.byteLength(next) > 16 * 1024 * 1024) {
+            throw new Error("Approval document byte limit reached");
+        }
+        await atomicWriteFile(file, next, {
+            replace: true,
+        });
+        return record;
+    }
+    finally {
+        await lock.close();
+        await unlink(file + ".lock");
+    }
+}
+export async function matchingApproval(root, capture, sha256, intent) {
+    const fingerprint = approvalFingerprint(capture, sha256, intent);
+    const record = [
+        ...(await readApprovals(root)).records,
+    ]
+        .reverse()
+        .find((r) => r.fingerprint === fingerprint);
+    if (!record) {
+        return undefined;
+    }
+    const image = await resolveProjectInput(root, record.image);
+    if ((await stat(image)).size > 64 * 1024 * 1024 ||
+        artifactSha(await readFile(image)) !== sha256) {
+        throw new Error("Approved image bytes changed");
+    }
+    return record;
+}

package/dist/atomic-output.d.ts

@@ -0,0 +1,5 @@
+/** Stage complete bytes beside the destination; publish once. Exclusive mode never replaces an existing file. */
+export declare function atomicWriteFile(destination: string, data: string | Uint8Array, options?: {
+    replace?: boolean;
+    mode?: number;
+}): Promise<void>;

package/dist/atomic-output.js

@@ -0,0 +1,33 @@
+import { randomUUID } from "node:crypto";
+import { link, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+/** Stage complete bytes beside the destination; publish once. Exclusive mode never replaces an existing file. */
+export async function atomicWriteFile(destination, data, options = {}) {
+    const temporary = path.join(path.dirname(destination), `.${path.basename(destination)}-${randomUUID()}.tmp`);
+    const handle = await open(temporary, "wx", options.mode ?? 0o600);
+    try {
+        await handle.writeFile(data);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    await handle.close();
+    try {
+        if (options.replace) {
+            await rename(temporary, destination);
+        }
+        else {
+            await link(temporary, destination);
+        }
+    }
+    finally {
+        await unlink(temporary).catch((error) => {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        });
+    }
+}

package/dist/audit-rules.d.ts

@@ -0,0 +1,60 @@
+import type { InspectionDocument } from "./inspection.js";
+export interface AuditRules {
+    contrast?: boolean;
+    library?: boolean;
+    touchTargets?: boolean;
+    names?: boolean;
+    blankText?: boolean;
+    interactiveIds?: string[];
+    allowBlank?: string[];
+    nameSegments?: number;
+    suppressions?: Array<{
+        rule: string;
+        nodeId: string;
+        reason: string;
+    }>;
+}
+export interface AuditFinding {
+    rule: string;
+    nodeId: string;
+    severity: "warning" | "info";
+    state: "finding" | "unknown";
+    detail: string;
+    evidence?: unknown;
+    suppression?: string;
+}
+export declare function validateAuditRules(raw: unknown): AuditRules;
+/** Opaque sRGB subset only. Alpha/multiple paints/images require a richer compositing model. */
+export declare function opaqueRgb(raw: unknown): number[] | undefined;
+export declare function contrastRatio(a: number[], b: number[]): number;
+export declare function auditDesignRules(raw: InspectionDocument, rawRules: AuditRules, tokenInspection?: InspectionDocument, limit?: number): {
+    schemaVersion: number;
+    kind: string;
+    source: {
+        fileId: string;
+        pageId: string | null;
+        revision: number;
+        hash: string;
+    };
+    advisory: boolean;
+    accessibilityCompliance: string;
+    complete: boolean;
+    totalFindings: number;
+    suppressed: number;
+    findings: AuditFinding[];
+    contrast: {
+        measured: number;
+        unknown: number;
+    };
+    library: {
+        instances: number;
+        knownNodes: number;
+        unknownNodes: number;
+        shareOfKnown: number | null;
+        largestPrimitiveGroups: {
+            id: string;
+            area: number;
+        }[];
+    } | null;
+    assumptions: string[];
+};