@penpair/core 0.1.2 → 0.2.0

package/dist/instance/config-schema.d.ts

@@ -0,0 +1,422 @@
+/** Editor hints for the core settings. Adapter-owned properties remain open; `config check` also checks semantic constraints. */
+export declare const projectConfigSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "penpair project configuration";
+    readonly type: "object";
+    readonly required: readonly ["instance"];
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: 1;
+        };
+        readonly connection: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["credential"];
+            readonly properties: {
+                readonly credential: {
+                    readonly oneOf: readonly [{
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["type", "path"];
+                        readonly properties: {
+                            readonly type: {
+                                readonly const: "file";
+                            };
+                            readonly path: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                    }, {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["type", "service", "account"];
+                        readonly properties: {
+                            readonly type: {
+                                readonly const: "keychain";
+                            };
+                            readonly service: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly account: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                    }];
+                };
+            };
+        };
+        readonly audit: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly contrast: {
+                    readonly type: "boolean";
+                };
+                readonly library: {
+                    readonly type: "boolean";
+                };
+                readonly touchTargets: {
+                    readonly type: "boolean";
+                };
+                readonly names: {
+                    readonly type: "boolean";
+                };
+                readonly blankText: {
+                    readonly type: "boolean";
+                };
+                readonly interactiveIds: {
+                    readonly type: "array";
+                    readonly maxItems: 1000;
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly allowBlank: {
+                    readonly type: "array";
+                    readonly maxItems: 1000;
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly nameSegments: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly maximum: 10;
+                };
+                readonly suppressions: {
+                    readonly type: "array";
+                    readonly maxItems: 1000;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["rule", "nodeId", "reason"];
+                        readonly properties: {
+                            readonly rule: {
+                                readonly enum: readonly ["contrast", "library", "touch-target", "names", "blank-text"];
+                            };
+                            readonly nodeId: {
+                                readonly type: "string";
+                            };
+                            readonly reason: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly backup: {
+            readonly type: "object";
+            readonly required: readonly ["noteFile", "remindAfterDays"];
+            readonly properties: {
+                readonly noteFile: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly pattern: "^(?![/\\\\])(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$)).+$";
+                };
+                readonly remindAfterDays: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                };
+            };
+        };
+        readonly file: {
+            readonly type: "object";
+            readonly required: readonly ["id"];
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly pattern: "\\S";
+                };
+                readonly name: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly instance: {
+            readonly type: "string";
+            readonly pattern: "^[a-z][a-z0-9-]{0,30}$";
+        };
+        readonly snippets: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly pattern: "^(?![/\\\\])(?![A-Za-z]:[/\\\\])(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$)).+$";
+            };
+        };
+        readonly adapters: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly baselines: {
+            readonly type: "object";
+            readonly required: readonly ["page", "root", "frames"];
+            readonly properties: {
+                readonly page: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly root: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly pattern: "^(?![/\\\\])(?![A-Za-z]:[/\\\\])(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$)).+$";
+                };
+                readonly coverage: {
+                    readonly type: "object";
+                    readonly required: readonly ["required"];
+                    readonly properties: {
+                        readonly required: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly maxItems: 1000;
+                            readonly items: {
+                                readonly type: "object";
+                                readonly required: readonly ["route", "viewport", "theme", "state", "fixture"];
+                                readonly additionalProperties: false;
+                                readonly properties: {
+                                    readonly viewport: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["width", "height"];
+                                        readonly additionalProperties: false;
+                                        readonly properties: {
+                                            readonly width: {
+                                                readonly type: "integer";
+                                                readonly minimum: 1;
+                                                readonly maximum: 16384;
+                                            };
+                                            readonly height: {
+                                                readonly type: "integer";
+                                                readonly minimum: 1;
+                                                readonly maximum: 16384;
+                                            };
+                                        };
+                                    };
+                                    readonly theme: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly state: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly fixture: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly route: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                            };
+                        };
+                        readonly unsupported: {
+                            readonly type: "array";
+                            readonly maxItems: 1000;
+                            readonly items: {
+                                readonly required: readonly ["route", "viewport", "theme", "state", "fixture", "reason"];
+                                readonly properties: {
+                                    readonly reason: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly viewport: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["width", "height"];
+                                        readonly additionalProperties: false;
+                                        readonly properties: {
+                                            readonly width: {
+                                                readonly type: "integer";
+                                                readonly minimum: 1;
+                                                readonly maximum: 16384;
+                                            };
+                                            readonly height: {
+                                                readonly type: "integer";
+                                                readonly minimum: 1;
+                                                readonly maximum: 16384;
+                                            };
+                                        };
+                                    };
+                                    readonly theme: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly state: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly fixture: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly route: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                            };
+                        };
+                    };
+                };
+                readonly threshold: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                    readonly maximum: 1;
+                };
+                readonly frames: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: 1000;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["frame", "id"];
+                        readonly dependentRequired: {
+                            readonly case: readonly ["route"];
+                        };
+                        readonly properties: {
+                            readonly frame: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly id: {
+                                readonly type: "string";
+                                readonly pattern: "^[a-z0-9][a-z0-9_-]{0,63}$";
+                            };
+                            readonly route: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly case: {
+                                readonly type: "object";
+                                readonly required: readonly ["viewport", "theme", "state", "fixture"];
+                                readonly additionalProperties: false;
+                                readonly properties: {
+                                    readonly fonts: {
+                                        readonly type: "array";
+                                        readonly maxItems: 100;
+                                        readonly uniqueItems: true;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly activeThemeIds: {
+                                        readonly type: "array";
+                                        readonly maxItems: 100;
+                                        readonly uniqueItems: true;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly viewport: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["width", "height"];
+                                        readonly additionalProperties: false;
+                                        readonly properties: {
+                                            readonly width: {
+                                                readonly type: "integer";
+                                                readonly minimum: 1;
+                                                readonly maximum: 16384;
+                                            };
+                                            readonly height: {
+                                                readonly type: "integer";
+                                                readonly minimum: 1;
+                                                readonly maximum: 16384;
+                                            };
+                                        };
+                                    };
+                                    readonly theme: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly state: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                    readonly fixture: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly maxLength: 200;
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    readonly oneOf: readonly [{
+        readonly required: readonly ["profile"];
+        readonly properties: {
+            readonly profile: {
+                readonly type: "object";
+                readonly required: readonly ["type", "origin"];
+                readonly properties: {
+                    readonly type: {
+                        readonly const: "external";
+                    };
+                    readonly origin: {
+                        readonly type: "string";
+                        readonly pattern: "^https?://[^/?#]+$";
+                    };
+                };
+            };
+        };
+    }, {
+        readonly required: readonly ["penpotVersion", "ports", "directory"];
+        readonly not: {
+            readonly required: readonly ["profile"];
+        };
+        readonly properties: {
+            readonly penpotVersion: {
+                readonly type: "string";
+                readonly pattern: "^\\d+\\.\\d+(\\.\\d+)?$";
+            };
+            readonly ports: {
+                readonly type: "object";
+                readonly required: readonly ["frontend", "mail"];
+                readonly properties: {
+                    readonly frontend: {
+                        readonly type: "integer";
+                        readonly minimum: 1024;
+                        readonly maximum: 65535;
+                    };
+                    readonly mail: {
+                        readonly type: "integer";
+                        readonly minimum: 1024;
+                        readonly maximum: 65535;
+                    };
+                };
+            };
+            readonly directory: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly pattern: "^(?!/).+$";
+            };
+            readonly composeProject: {
+                readonly type: "string";
+                readonly pattern: "^[a-z0-9][a-z0-9_-]*$";
+            };
+        };
+    }];
+};

package/dist/instance/config-schema.js

@@ -0,0 +1,76 @@
+const viewportSchema = { type: "object", required: ["width", "height"], additionalProperties: false, properties: { width: { type: "integer", minimum: 1, maximum: 16384 }, height: { type: "integer", minimum: 1, maximum: 16384 } } };
+const caseFields = { viewport: viewportSchema, theme: { type: "string", minLength: 1, maxLength: 200 }, state: { type: "string", minLength: 1, maxLength: 200 }, fixture: { type: "string", minLength: 1, maxLength: 200 } };
+const baselineCaseSchema = { type: "object", required: ["viewport", "theme", "state", "fixture"], additionalProperties: false, properties: { ...caseFields, fonts: { type: "array", maxItems: 100, uniqueItems: true, items: { type: "string", minLength: 1 } }, activeThemeIds: { type: "array", maxItems: 100, uniqueItems: true, items: { type: "string", minLength: 1 } } } };
+const requiredCaseSchema = { type: "object", required: ["route", "viewport", "theme", "state", "fixture"], additionalProperties: false, properties: { route: { type: "string", minLength: 1 }, ...caseFields } };
+/** Editor hints for the core settings. Adapter-owned properties remain open; `config check` also checks semantic constraints. */
+export const projectConfigSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "penpair project configuration",
+    type: "object",
+    required: ["instance"],
+    properties: {
+        schemaVersion: { const: 1 },
+        connection: { type: "object", additionalProperties: false, required: ["credential"], properties: { credential: { oneOf: [
+                        { type: "object", additionalProperties: false, required: ["type", "path"], properties: { type: { const: "file" }, path: { type: "string", minLength: 1 } } },
+                        { type: "object", additionalProperties: false, required: ["type", "service", "account"], properties: { type: { const: "keychain" }, service: { type: "string", minLength: 1 }, account: { type: "string", minLength: 1 } } },
+                    ] } } },
+        audit: { type: "object", additionalProperties: false, properties: {
+                contrast: { type: "boolean" }, library: { type: "boolean" }, touchTargets: { type: "boolean" }, names: { type: "boolean" }, blankText: { type: "boolean" },
+                interactiveIds: { type: "array", maxItems: 1000, items: { type: "string" } }, allowBlank: { type: "array", maxItems: 1000, items: { type: "string" } }, nameSegments: { type: "integer", minimum: 1, maximum: 10 },
+                suppressions: { type: "array", maxItems: 1000, items: { type: "object", required: ["rule", "nodeId", "reason"], properties: { rule: { enum: ["contrast", "library", "touch-target", "names", "blank-text"] }, nodeId: { type: "string" }, reason: { type: "string", minLength: 1 } } } },
+            } },
+        backup: { type: "object", required: ["noteFile", "remindAfterDays"], properties: { noteFile: { type: "string", minLength: 1, pattern: "^(?![/\\\\])(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$)).+$" }, remindAfterDays: { type: "integer", minimum: 1 } } },
+        file: { type: "object", required: ["id"], properties: { id: { type: "string", minLength: 1, pattern: "\\S" }, name: { type: "string" } } },
+        instance: { type: "string", pattern: "^[a-z][a-z0-9-]{0,30}$" },
+        snippets: { type: "array", items: { type: "string", minLength: 1, pattern: "^(?![/\\\\])(?![A-Za-z]:[/\\\\])(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$)).+$" } },
+        adapters: { type: "array", items: { type: "string", minLength: 1 } },
+        baselines: {
+            type: "object", required: ["page", "root", "frames"],
+            properties: {
+                page: { type: "string", minLength: 1 },
+                root: { type: "string", minLength: 1, pattern: "^(?![/\\\\])(?![A-Za-z]:[/\\\\])(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$)).+$" },
+                coverage: { type: "object", required: ["required"], properties: { required: { type: "array", minItems: 1, maxItems: 1000, items: requiredCaseSchema }, unsupported: { type: "array", maxItems: 1000, items: { ...requiredCaseSchema, required: [...requiredCaseSchema.required, "reason"], properties: { ...requiredCaseSchema.properties, reason: { type: "string", minLength: 1 } } } } } },
+                threshold: { type: "number", minimum: 0, maximum: 1 },
+                frames: {
+                    type: "array", minItems: 1, maxItems: 1000,
+                    items: {
+                        type: "object", required: ["frame", "id"], dependentRequired: { case: ["route"] },
+                        properties: {
+                            frame: { type: "string", minLength: 1 },
+                            id: { type: "string", pattern: "^[a-z0-9][a-z0-9_-]{0,63}$" },
+                            route: { type: "string", minLength: 1 },
+                            case: baselineCaseSchema,
+                        },
+                    },
+                },
+            },
+        },
+    },
+    oneOf: [
+        {
+            required: ["profile"],
+            properties: {
+                profile: {
+                    type: "object", required: ["type", "origin"],
+                    properties: { type: { const: "external" }, origin: { type: "string", pattern: "^https?://[^/?#]+$" } },
+                },
+            },
+        },
+        {
+            required: ["penpotVersion", "ports", "directory"],
+            not: { required: ["profile"] },
+            properties: {
+                penpotVersion: { type: "string", pattern: "^\\d+\\.\\d+(\\.\\d+)?$" },
+                ports: {
+                    type: "object", required: ["frontend", "mail"],
+                    properties: {
+                        frontend: { type: "integer", minimum: 1024, maximum: 65535 },
+                        mail: { type: "integer", minimum: 1024, maximum: 65535 },
+                    },
+                },
+                directory: { type: "string", minLength: 1, pattern: "^(?!/).+$" },
+                composeProject: { type: "string", pattern: "^[a-z0-9][a-z0-9_-]*$" },
+            },
+        },
+    ],
+};

package/dist/instance/config.d.ts

@@ -1,6 +1,23 @@
+import { type CredentialReference } from "../credentials.js";
+import { type AuditRules } from "../audit-rules.js";
 import { type BaselinesConfig } from "../baselines-config.js";
 /** What a project keeps in `penpair.config.json`: no secrets, so it can be committed. */
+export interface ProjectFile {
+    id: string;
+    name?: string;
+}
+export interface BackupReminder {
+    noteFile: string;
+    remindAfterDays: number;
+}
 export interface InstanceConfig {
+    schemaVersion?: 1;
+    audit?: AuditRules;
+    connection?: {
+        credential: CredentialReference;
+    };
+    file?: ProjectFile;
+    backup?: BackupReminder;
     /** Short name; it becomes part of the compose project, so containers and volumes of two instances never collide. */
     instance: string;
     /** Pinned Penpot image version. Run the smoke test before changing it. */
@@ -22,6 +39,13 @@ export interface InstanceConfig {
 }
 /** A project that uses a Penpot someone else runs (a team server or the hosted service): no Docker here, only the connection. */
 export interface ExternalConfig {
+    schemaVersion?: 1;
+    audit?: AuditRules;
+    connection?: {
+        credential: CredentialReference;
+    };
+    file?: ProjectFile;
+    backup?: BackupReminder;
     instance: string;
     profile: {
         type: "external";
@@ -36,6 +60,8 @@ export declare const isExternal: (config: ProjectConfig) => config is ExternalCo
 export declare const configFileName = "penpair.config.json";
 export declare const testedPenpotVersion = "2.18.3";
 export declare class ConfigError extends Error {
+    readonly code: "missing" | "unreadable" | "invalid-json" | "invalid-config";
+    constructor(message: string, code?: "missing" | "unreadable" | "invalid-json" | "invalid-config");
 }
 export declare function composeProjectOf(config: InstanceConfig): string;
 export declare function validateConfig(value: unknown): InstanceConfig;
@@ -43,6 +69,9 @@ export declare function validateConfig(value: unknown): InstanceConfig;
 export declare function validateProjectConfig(value: unknown): ProjectConfig;
 /** The config of a project that runs its own Penpot; anything else cannot start, stop or back up containers. */
 export declare function requireLocal(config: ProjectConfig): InstanceConfig;
+/** Missing is optional; unreadable, malformed or invalid project files always stop the caller. */
+export declare function readProjectConfig(root: string): Promise<Record<string, unknown> | undefined>;
+export declare function loadOptionalConfig(root: string): Promise<ProjectConfig | undefined>;
 export declare function loadConfig(root: string): Promise<ProjectConfig>;
 export declare const instancePaths: (root: string, config: InstanceConfig) => {
     directory: string;