@penpair/core 0.1.3 → 0.3.0

package/dist/formats.js

@@ -0,0 +1,229 @@
+import { projectConfigSchema } from "./instance/config-schema.js";
+import { validateProjectConfig } from "./instance/config.js";
+import { commandResultSchema } from "./command-result.js";
+const string = {
+    type: "string",
+};
+const array = {
+    type: "array",
+};
+const schema = (name, version, kind, properties, required = Object.keys(properties)) => ({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: `urn:penpair:schema:v${version}:${name}`,
+    title: `${name} v${version}`,
+    type: "object",
+    required: [
+        "schemaVersion",
+        ...(kind
+            ? [
+                "kind",
+            ]
+            : []),
+        ...required,
+    ],
+    properties: {
+        schemaVersion: {
+            const: version,
+        },
+        ...(kind
+            ? {
+                kind: {
+                    const: kind,
+                },
+            }
+            : {}),
+        ...properties,
+    },
+    additionalProperties: true,
+});
+/** Public envelope schemas; runtime validators additionally enforce hashes, identities, hierarchy and budgets. */
+export const artifactSchemas = {
+    "project-config": {
+        ...projectConfigSchema,
+        $id: "urn:penpair:schema:v1:project-config",
+    },
+    "command-result": {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        $id: "urn:penpair:schema:v1:command-result",
+        ...commandResultSchema,
+    },
+    inspection: schema("inspection", 1, undefined, {
+        kind: {
+            enum: [
+                "shape-inspection",
+                "token-inspection",
+            ],
+        },
+        fileId: string,
+        pageId: {
+            type: [
+                "string",
+                "null",
+            ],
+        },
+        revision: {
+            type: "integer",
+            minimum: 0,
+        },
+        complete: {
+            type: "boolean",
+        },
+        counts: {
+            type: "object",
+        },
+        reasons: array,
+        producer: {
+            type: "object",
+        },
+    }),
+    "component-map": schema("component-map", 1, undefined, {
+        components: {
+            type: "array",
+            maxItems: 1000,
+            items: {
+                type: "object",
+                required: [
+                    "libraryId",
+                    "componentId",
+                    "codeComponent",
+                ],
+                properties: {
+                    libraryId: string,
+                    componentId: string,
+                    codeComponent: string,
+                    props: {
+                        type: "object",
+                    },
+                    textProps: {
+                        type: "object",
+                        additionalProperties: string,
+                    },
+                },
+            },
+        },
+    }),
+    "design-spec": schema("design-spec", 1, "design-spec", {
+        source: {
+            type: "object",
+        },
+        mappingHash: string,
+        nodes: array,
+        unknowns: array,
+    }),
+    approvals: schema("approvals", 1, "design-approvals", {
+        records: {
+            type: "array",
+            maxItems: 10000,
+        },
+    }),
+    "structural-manifest": schema("structural-manifest", 1, "structural-snapshot-manifest", {
+        fileId: string,
+        revision: {
+            type: "integer",
+        },
+        producer: string,
+        fidelity: {
+            const: "review-only",
+        },
+        pages: {
+            type: "array",
+            minItems: 1,
+            maxItems: 100,
+        },
+        tokens: {
+            type: "object",
+        },
+        hash: string,
+    }),
+    "baseline-manifest": schema("baseline-manifest", 2, undefined, {
+        complete: {
+            type: "boolean",
+        },
+        fileId: string,
+        pageId: string,
+        captureId: string,
+        frames: {
+            type: "array",
+            maxItems: 1000,
+        },
+    }),
+    "projected-theme-preview": schema("projected-theme-preview", 1, "projected-theme-preview", {
+        sourceHash: string,
+        theme: {
+            type: "object",
+        },
+        sets: array,
+        resolved: array,
+        unknowns: array,
+        complete: {
+            type: "boolean",
+        },
+        nativeBindings: {
+            const: false,
+        },
+    }),
+    "portable-tokens": schema("portable-tokens", 1, "portable-tokens", {
+        format: {
+            const: "dtcg-2025.10-subset",
+        },
+        tokens: {
+            type: "array",
+            minItems: 1,
+            maxItems: 10000,
+            items: {
+                type: "object",
+                required: [
+                    "path",
+                    "type",
+                    "value",
+                ],
+                properties: {
+                    path: {
+                        type: "array",
+                        minItems: 1,
+                        maxItems: 32,
+                        items: string,
+                    },
+                    type: {
+                        enum: [
+                            "color",
+                            "dimension",
+                            "number",
+                            "fontFamily",
+                            "fontWeight",
+                            "typography",
+                        ],
+                    },
+                    value: {},
+                    description: string,
+                    extensions: {
+                        type: "object",
+                    },
+                },
+            },
+        },
+        groups: {
+            type: "object",
+        },
+        losses: {
+            type: "array",
+            maxItems: 0,
+        },
+    }),
+};
+/** Legacy unversioned config is v1; preserve every extension block and require explicit new output for persistence. */
+export function migrateProjectConfig(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("Config migration requires a JSON object");
+    }
+    const v = raw;
+    if (v.schemaVersion !== undefined && v.schemaVersion !== 1) {
+        throw new Error("Unsupported project config major version; use the producer's documented migration before opening it");
+    }
+    const migrated = {
+        ...structuredClone(v),
+        schemaVersion: 1,
+    };
+    validateProjectConfig(migrated);
+    return migrated;
+}

package/dist/index.d.ts

@@ -1,9 +1,16 @@
 export { version } from "./version.js";
 export * from "./adapters.js";
 export * from "./baselines.js";
-export { runCli } from "./cli-main.js";
+export { runCommand, runCli } from "./cli-main.js";
 export * from "./client.js";
+export { guardFile } from "./file-guard.js";
 export * from "./deep-check.js";
+export { runLiveSmoke } from "./live-smoke.js";
+export * from "./layout.js";
+export * from "./native-api.js";
+export * from "./file-archive.js";
+export { backupNoteCheck } from "./backup-note.js";
+export * from "./journal.js";
 export * from "./local-profile.js";
 export * from "./endpoint.js";
 export * from "./errors.js";
@@ -18,8 +25,34 @@ export * from "./snippets/archive.js";
 export * from "./snippets/read.js";
 export * from "./tokens-diff.js";
 export * from "./instance/config.js";
+export { projectConfigSchema } from "./instance/config-schema.js";
 export * from "./instance/connection.js";
 export * from "./instance/gitignore.js";
 export { defaultInstanceName, init } from "./instance/init.js";
 export type { InitOptions, InitResult } from "./instance/init.js";
 export * from "./instance/runner.js";
+export { writeCoordinator, guardRevision, type WriteLease, type CoordinationOptions, } from "./coordination.js";
+export { onboardingChecklist } from "./onboard.js";
+export { atomicWriteFile } from "./atomic-output.js";
+export { commandSleep, withCleanupDeadline, commandResultSchema, collectCommand, commandOutput, type CommandResult, type CommandFailure, type CommandOutput, } from "./command-result.js";
+export { resolveProjectInput, resolveProjectOutput, designDataBlock } from "./project-input.js";
+export { planSkillInstructions, applySkillInstructions, type InstructionReport, } from "./skill-instructions.js";
+export { parseCommandArgs, CommandArgumentError } from "./cli-arguments.js";
+export { findShapesByName, exportShapeByName, captureShots, type ShapeLookup, type ShapeMatch, type ShotsReport, } from "./shots.js";
+export * from "./inspection.js";
+export { tokenTypes, validateEditableToken, validateTokenEdit, planTokenEdit, tokenEditOperation, type EditableToken, type TokenEdit, type TokenEditState, type TokenEditPlan, } from "./token-edit.js";
+export { ensureGitignoreEntry } from "./instance/gitignore.js";
+export { prepareFileScript, runFileScript, type FileScriptOptions, type PreparedFileScript, } from "./run-file.js";
+export { kit, coreKit, checkKits, loadKits, type BuildKit, type RecipeInfo } from "./kit.js";
+export { runKitSmoke, kitSmokeOperation } from "./kit-smoke.js";
+export { baselineCoverage, readBaselineCoverage, designCaseKey, type BaselineCoverage, type CoverageRow, } from "./baseline-coverage.js";
+export * from "./design-spec.js";
+export * from "./mcp-server.js";
+export * from "./approvals.js";
+export * from "./structure-snapshot.js";
+export * from "./portable-tokens.js";
+export * from "./formats.js";
+export * from "./project-status.js";
+export * from "./audit-rules.js";
+export * from "./credentials.js";
+export * from "./token-projection.js";

package/dist/index.js

@@ -1,9 +1,16 @@
 export { version } from "./version.js";
 export * from "./adapters.js";
 export * from "./baselines.js";
-export { runCli } from "./cli-main.js";
+export { runCommand, runCli } from "./cli-main.js";
 export * from "./client.js";
+export { guardFile } from "./file-guard.js";
 export * from "./deep-check.js";
+export { runLiveSmoke } from "./live-smoke.js";
+export * from "./layout.js";
+export * from "./native-api.js";
+export * from "./file-archive.js";
+export { backupNoteCheck } from "./backup-note.js";
+export * from "./journal.js";
 export * from "./local-profile.js";
 export * from "./endpoint.js";
 export * from "./errors.js";
@@ -18,7 +25,33 @@ export * from "./snippets/archive.js";
 export * from "./snippets/read.js";
 export * from "./tokens-diff.js";
 export * from "./instance/config.js";
+export { projectConfigSchema } from "./instance/config-schema.js";
 export * from "./instance/connection.js";
 export * from "./instance/gitignore.js";
 export { defaultInstanceName, init } from "./instance/init.js";
 export * from "./instance/runner.js";
+export { writeCoordinator, guardRevision, } from "./coordination.js";
+export { onboardingChecklist } from "./onboard.js";
+export { atomicWriteFile } from "./atomic-output.js";
+export { commandSleep, withCleanupDeadline, commandResultSchema, collectCommand, commandOutput, } from "./command-result.js";
+export { resolveProjectInput, resolveProjectOutput, designDataBlock } from "./project-input.js";
+export { planSkillInstructions, applySkillInstructions, } from "./skill-instructions.js";
+export { parseCommandArgs, CommandArgumentError } from "./cli-arguments.js";
+export { findShapesByName, exportShapeByName, captureShots, } from "./shots.js";
+export * from "./inspection.js";
+export { tokenTypes, validateEditableToken, validateTokenEdit, planTokenEdit, tokenEditOperation, } from "./token-edit.js";
+export { ensureGitignoreEntry } from "./instance/gitignore.js";
+export { prepareFileScript, runFileScript, } from "./run-file.js";
+export { kit, coreKit, checkKits, loadKits } from "./kit.js";
+export { runKitSmoke, kitSmokeOperation } from "./kit-smoke.js";
+export { baselineCoverage, readBaselineCoverage, designCaseKey, } from "./baseline-coverage.js";
+export * from "./design-spec.js";
+export * from "./mcp-server.js";
+export * from "./approvals.js";
+export * from "./structure-snapshot.js";
+export * from "./portable-tokens.js";
+export * from "./formats.js";
+export * from "./project-status.js";
+export * from "./audit-rules.js";
+export * from "./credentials.js";
+export * from "./token-projection.js";

package/dist/inspection.d.ts

@@ -0,0 +1,106 @@
+import { type ExecutionMetrics, type PenpotToolClient } from "./client.js";
+export declare const inspectionFields: readonly ["geometry", "text", "layout", "component", "tokens", "style", "metadata"];
+export type InspectionField = (typeof inspectionFields)[number];
+export interface InspectionQuery {
+    kind?: "shape" | "tokens";
+    shapeId?: string;
+    page?: string;
+    fields?: InspectionField[];
+    depth?: number;
+    maxNodes?: number;
+    responseBytes?: number;
+    timeBudgetMs?: number;
+    documentBytes?: number;
+    cursor?: string;
+}
+export interface InspectionChunk {
+    schemaVersion: 1;
+    kind: "inspection-chunk";
+    fileId: string;
+    pageId: string | null;
+    revision: number;
+    queryHash: string;
+    digest: string;
+    digestAlgorithm: "cyrb53-change-detector";
+    sourceComplete: boolean;
+    offset: number;
+    nextOffset: number | null;
+    totalCodeUnits: number;
+    chunk: string;
+    nextCursor: string | null;
+    complete: boolean;
+    counts: Record<string, number | null>;
+    observationMs: number;
+    metrics: ExecutionMetrics;
+}
+export interface InspectionDocument {
+    schemaVersion: 1;
+    kind: "shape-inspection" | "token-inspection";
+    fileId: string;
+    pageId: string | null;
+    revision: number;
+    complete: boolean;
+    counts: Record<string, number | null>;
+    reasons: string[];
+    producer: {
+        name: string;
+        version: string;
+    };
+    nodes?: Record<string, unknown>[];
+    sets?: Record<string, unknown>[];
+    themes?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+export interface InspectionMetrics {
+    calls: number;
+    requestSnippetBytes: number;
+    responsePayloadBytes: number;
+    maxRequestSnippetBytes: number;
+    maxResponsePayloadBytes: number;
+    assembledBytes: number;
+    durationMs: number;
+}
+export type InspectionCapture = InspectionDocument & {
+    capturedAt: string;
+    sha256: string;
+    metrics: InspectionMetrics;
+};
+export interface PartialInspection {
+    schemaVersion: 1;
+    kind: "inspection-partial";
+    fileId: string | null;
+    pageId: string | null;
+    complete: false;
+    reason: string;
+    chunks: InspectionChunk[];
+    nextCursor: string | null;
+    metrics: InspectionMetrics;
+}
+export interface CaptureBudget {
+    maxCalls?: number;
+    maxTotalBytes?: number;
+    timeoutMs?: number;
+}
+export declare function validateInspectionQuery(query: InspectionQuery): {
+    queryHash: string;
+    producerVersion: string;
+    kind: "tokens" | "shape";
+    shapeId: string | undefined;
+    page: string | undefined;
+    fields: ("text" | "geometry" | "layout" | "component" | "tokens" | "style" | "metadata")[];
+    depth: number;
+    maxNodes: number;
+    responseBytes: number;
+    timeBudgetMs: number;
+    documentBytes: number;
+};
+export declare function inspectChunk(client: PenpotToolClient, query: InspectionQuery, requestTimeoutMs?: number): Promise<InspectionChunk>;
+/** Validate structural evidence independently of the transport envelope. Unknown API fields remain explicit nulls. */
+export declare function validateInspectionDocument(input: unknown): InspectionDocument;
+export declare function reassembleInspection(chunks: InspectionChunk[]): InspectionDocument;
+export declare function validateCaptureBudget(budget?: CaptureBudget): {
+    maxCalls: number;
+    maxTotalBytes: number;
+    timeoutMs: number;
+};
+export declare function captureInspection(client: PenpotToolClient, query: InspectionQuery, budget?: CaptureBudget): Promise<InspectionCapture | PartialInspection>;