@penpair/core 0.1.0 → 0.1.2

package/dist/cli.js

@@ -1,456 +1,3 @@
 #!/usr/bin/env node
-import { writeFile, readFile } from "node:fs/promises";
-import { parseArgs } from "node:util";
-import { connect, executeCode } from "./client.js";
-import { redactEndpoint, resolveEndpoint } from "./endpoint.js";
-import { PenpairError } from "./errors.js";
-import { exportShapePng } from "./export.js";
-import { exportBaselines } from "./baselines.js";
-import { archiveOperation, runOnPage, runOperation } from "./operation.js";
-import { formatDeepReport, runDeepCheck } from "./deep-check.js";
-import { probe } from "./probe.js";
-import { installSkills, listBundledSkills } from "./skills.js";
-import { checkProjectSnippets, loadProjectSnippets } from "./project-snippets.js";
-import { builtInRegistry, coerceParams, RegistryError } from "./registry.js";
-import { runSnippet } from "./snippet.js";
-import { audit, pages, tokensDump, tree } from "./snippets/read.js";
-import { diffEffective, effectiveValues } from "./tokens-diff.js";
-import { ConfigError, isExternal, loadConfig, requireLocal } from "./instance/config.js";
-import { init } from "./instance/init.js";
-import { ConnectError, connectProject, keyFileCheck } from "./instance/connect.js";
-import { hostedOrigin, setup } from "./instance/setup.js";
-import { askHidden, askLine, openInBrowser } from "./instance/tty.js";
-import { backup, doctor, down, restore, status, up, verifyBackup } from "./docker/lifecycle.js";
-import { assertEndpointIsInstance, doctorExternal, LifecycleError } from "./instance/connection.js";
-import { nodeRunner } from "./instance/runner.js";
-import { version } from "./index.js";
-const usage = `penpair ${version}
-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
-  penpair setup --docker                               Penpot on this computer in Docker
-  penpair connect [--replace]                          only the connection: takes your personal key without showing it, waits for the editor
-                                                       (a pipe works too: pbpaste | penpair connect)
-Read-only:
-  penpair probe                                        what the connected Penpot and its MCP offer, and the limits
-  penpair probe --deep --write                         also tries layout, tokens, components, swap, clone and export on a temporary
-                                                       board it removes again (it touches the open file, so --write is required)
-  (in a project with an instance every command below acts on that instance only; --any-instance overrides)
-  penpair pages                                        the file, its revision, pages and their sizes
-  penpair tree --page <name> [--depth 3] [--prefix <text>]
-  penpair audit --page <name> --prefix <frame name start> [--steps 0,2,4,8] [--ignore <name starts>]
-  penpair tokens dump                                  token sets and themes as JSON
-  penpair tokens diff <before.json> <after.json> --theme <name>
-  penpair export <shapeId> <out.png> [--page <name>] [--scale 1]
-An instance (one Penpot per project, configured in penpair.config.json):
-  penpair init [--instance <name>] [--port 9001] [--gitignore]   set up the config, the compose file and the secrets
-  penpair init --external <origin>                     use a Penpot someone else runs (a team server or https://design.penpot.app); no Docker
-  penpair up | down | status                           start, stop (data stays) and look at the containers
-  penpair doctor [--json]                              what is up, what is not, and what to do about it (--json for scripts and agents)
-  penpair backup                                       database and assets, with checksums and counts
-  penpair backup verify <dir>                          restore into a throwaway database and compare
-  penpair restore <dir> --yes                          replace the instance's data with a backup (safety backup first)
-Skills (the rules an AI agent follows, shipped with penpair):
-  penpair skills                                       list them
-  penpair skills install [--to .skills] [--only <name>] [--force]   copy them into the project and make them discoverable
-Snippets (the built-in ones and the project's own, listed under "snippets" in penpair.config.json):
-  penpair snippets                                     what can be run, with its parameters
-  penpair snippets check                               validate the project's snippets without a connection
-  penpair run <name> [--param key=value ...] [--apply] run one; a snippet that changes things only looks unless --apply
-Hand a page's design to a check (Reflection or any image comparison):
-  penpair baselines [--apply] [--update]               export the frames listed under "baselines" in penpair.config.json as approved images,
-                                                       a manifest and ready-made Reflection cases. Looks first; --apply writes new images;
-                                                       --update also replaces images whose design changed (approving the new design)
-Changes in a Penpot file (inspect first; nothing is written without --apply):
-  penpair archive --page <name> --name <archive board> --keep <prefixes> --parts <prefixes> [--x 9000] [--apply]
-  penpair --version`;
-const list = (value) => (value ?? "").split(",").map((v) => v.trim()).filter(Boolean);
-async function main(argv) {
-    const { values, positionals } = parseArgs({
-        args: argv,
-        allowPositionals: true,
-        options: {
-            page: { type: "string" },
-            depth: { type: "string" },
-            prefix: { type: "string" },
-            steps: { type: "string" },
-            ignore: { type: "string" },
-            theme: { type: "string" },
-            scale: { type: "string" },
-            name: { type: "string" },
-            keep: { type: "string" },
-            parts: { type: "string" },
-            x: { type: "string" },
-            apply: { type: "boolean" },
-            instance: { type: "string" },
-            external: { type: "string" },
-            port: { type: "string" },
-            gitignore: { type: "boolean" },
-            yes: { type: "boolean" },
-            "any-instance": { type: "boolean" },
-            web: { type: "boolean" },
-            docker: { type: "boolean" },
-            replace: { type: "boolean" },
-            update: { type: "boolean" },
-            json: { type: "boolean" },
-            deep: { type: "boolean" },
-            force: { type: "boolean" },
-            to: { type: "string" },
-            only: { type: "string", multiple: true },
-            write: { type: "boolean" },
-            param: { type: "string", multiple: true },
-            version: { type: "boolean" },
-            help: { type: "boolean" },
-        },
-    });
-    const [command, ...rest] = positionals;
-    if (values.version) {
-        console.log(version);
-        return 0;
-    }
-    if (!command || values.help) {
-        console.log(usage);
-        return 0;
-    }
-    if (command === "tokens" && rest[0] === "diff") {
-        const [, beforeFile, afterFile] = rest;
-        if (!beforeFile || !afterFile || !values.theme)
-            throw new Error("usage: penpair tokens diff <before.json> <after.json> --theme <name>");
-        const load = async (file) => JSON.parse(await readFile(file, "utf8"));
-        const diff = diffEffective(effectiveValues(await load(beforeFile), values.theme), effectiveValues(await load(afterFile), values.theme));
-        console.log(JSON.stringify(diff, null, 2));
-        return diff.added.length + diff.removed.length + diff.changed.length === 0 ? 0 : 2;
-    }
-    const root = process.cwd();
-    const log = (message) => console.error(`… ${message}`);
-    /** What `doctor` needs to look for the editor and plugin, or nothing when no endpoint is set yet. */
-    async function mcpProbeFor() {
-        try {
-            const endpoint = await resolveEndpoint();
-            return {
-                origin: endpoint.description.origin,
-                connect: async () => {
-                    const client = await connect(endpoint);
-                    try {
-                        const { result } = await executeCode(client, "return { file: penpot.currentFile.name };", { retries: 0 });
-                        return { file: String(result.file ?? "?") };
-                    }
-                    finally {
-                        await client.close();
-                    }
-                },
-            };
-        }
-        catch {
-            return undefined;
-        }
-    }
-    async function registryFor() {
-        const registry = builtInRegistry();
-        let snippets;
-        try {
-            snippets = (await loadConfig(root)).snippets;
-        }
-        catch {
-            // not a penpair project: only the built-in snippets
-        }
-        const report = await loadProjectSnippets(root, snippets, registry);
-        return { registry, problems: report.problems, files: report.files };
-    }
-    const connectIo = () => ({
-        say: (line) => console.log(line),
-        askHidden,
-        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-        openFile: async (url) => {
-            const endpoint = await resolveEndpoint({ environment: { PENPAIR_MCP_URL: url }, envFiles: [] });
-            try {
-                const client = await connect(endpoint);
-                try {
-                    const { result } = await executeCode(client, "return { file: penpot.currentFile.name, pages: penpot.currentFile.pages.map((p) => p.name) };", { retries: 0 });
-                    const read = result;
-                    return { file: String(read.file ?? "?"), pages: read.pages ?? [] };
-                }
-                finally {
-                    await client.close();
-                }
-            }
-            catch (error) {
-                throw new Error(redactEndpoint(String(error.message ?? error), endpoint));
-            }
-        },
-    });
-    if (command === "setup" || command === "connect") {
-        if (command === "connect") {
-            const project = await loadConfig(root);
-            await connectProject(root, project, connectIo(), { replace: values.replace === true });
-            console.log("Next: `penpair doctor`, then `penpair skills install` if you have not yet.");
-            return 0;
-        }
-        let where;
-        if (values.docker)
-            where = { type: "docker" };
-        else if (values.web || values.external)
-            where = { type: "web", origin: values.external ?? hostedOrigin };
-        await setup(root, { ...connectIo(), ask: (question, fallback) => askLine(question, fallback), openBrowser: openInBrowser }, {
-            where,
-            instance: values.instance,
-            port: values.port ? Number(values.port) : undefined,
-            runner: nodeRunner,
-            log,
-            installSkills: async () => {
-                const report = await installSkills({ root });
-                console.log(`Installed ${report.installed.length} rule file(s) in .skills/ (${report.unchanged.length} already there). Add these rows to your AGENTS.md skills table:\n${report.agentsRows.join("\n")}`);
-            },
-        });
-        return 0;
-    }
-    if (command === "skills") {
-        if (rest[0] === "install") {
-            const report = await installSkills({ root, to: values.to, only: values.only, force: values.force });
-            for (const file of report.installed)
-                console.log(`wrote     ${file}`);
-            for (const file of report.kept)
-                console.log(`kept      ${file} (differs from the shipped one; --force replaces it, except the project-owned files)`);
-            for (const link of report.linked)
-                console.log(`linked    ${link}`);
-            console.log(`${report.unchanged.length} file(s) already up to date`);
-            console.log("\nAdd to your AGENTS.md skills table:\n" + report.agentsRows.join("\n"));
-            console.log("\nThen fill in references/project-facts.md in penpot-design: it is yours and is never replaced.");
-            return 0;
-        }
-        for (const name of await listBundledSkills())
-            console.log(name);
-        return 0;
-    }
-    if (command === "snippets") {
-        const { registry, problems, files } = await registryFor();
-        if (rest[0] === "check") {
-            const found = [...problems, ...checkProjectSnippets(registry)];
-            const project = registry.list().filter((entry) => entry.source === "project");
-            console.log(`${project.length} project snippet(s) from ${files.length} file(s)`);
-            for (const problem of found)
-                console.log(`FAIL ${problem}`);
-            if (found.length === 0)
-                console.log("ok   every snippet is valid plugin code and small enough");
-            return found.length === 0 ? 0 : 1;
-        }
-        for (const entry of registry.list()) {
-            console.log(`${entry.name.padEnd(14)} ${entry.kind === "write" ? "changes " : "reads   "} ${entry.source === "project" ? "[project] " : ""}${entry.description}`);
-            for (const p of entry.params)
-                console.log(`${"".padEnd(14)}   --param ${p.name}=<${p.type}>${p.required ? " (required)" : p.default !== undefined ? ` (default ${JSON.stringify(p.default)})` : ""}${p.description ? ` ${p.description}` : ""}`);
-        }
-        for (const problem of problems)
-            console.error(`warning: ${problem}`);
-        return 0;
-    }
-    if (command === "init") {
-        const result = await init(root, { instance: values.instance, port: values.port ? Number(values.port) : undefined, gitignore: values.gitignore, external: values.external });
-        if (isExternal(result.config)) {
-            console.log(`${result.createdConfig ? "created" : "kept"} penpair.config.json (external Penpot at ${result.config.profile.origin})`);
-            console.log("next: penpair connect   (takes your personal key without showing it, then waits for the editor)");
-            return 0;
-        }
-        console.log(`${result.createdConfig ? "created" : "kept"} penpair.config.json (instance ${result.config.instance}, Penpot ${result.config.penpotVersion}, port ${result.config.ports.frontend})`);
-        console.log(`wrote ${result.config.directory}/docker-compose.yaml; secrets ${result.createdSecrets ? "generated" : "kept"} in ${result.config.directory}/.env`);
-        if (!result.gitignoreAdded)
-            console.log(`keep ${result.config.directory}/ out of git (add it to .gitignore, or run init with --gitignore)`);
-        console.log("next: penpair up, then penpair connect");
-        return 0;
-    }
-    /** Prints the checks one per line, or as JSON for scripts and agents. The key file check is added to both kinds of project. */
-    async function report(checks, mcp) {
-        const keyCheck = await keyFileCheck(root, nodeRunner);
-        const all = keyCheck ? [...checks, keyCheck] : checks;
-        const ok = all.every((check) => check.ok);
-        if (values.json) {
-            console.log(JSON.stringify({ ok, mcpConfigured: Boolean(mcp), checks: all }, null, 2));
-            return ok ? 0 : 1;
-        }
-        for (const check of all)
-            console.log(`${check.ok ? "ok  " : "FAIL"} ${check.check}: ${check.detail}${"remedy" in check && check.remedy ? `\n       → ${check.remedy}` : ""}`);
-        if (!mcp)
-            console.log("skip editor and plugin: no key yet. Run `penpair connect`.");
-        return ok ? 0 : 1;
-    }
-    const lifecycle = new Set(["up", "down", "status", "doctor", "backup", "restore"]);
-    if (lifecycle.has(command)) {
-        const project = await loadConfig(root);
-        if (isExternal(project) && command !== "doctor")
-            requireLocal(project);
-        if (isExternal(project)) {
-            const mcp = await mcpProbeFor();
-            return report(await doctorExternal(project, { mcp }), mcp);
-        }
-        const c = { root, config: requireLocal(project), runner: nodeRunner, log };
-        if (command === "up") {
-            const result = await up(c);
-            console.log(result.ready ? `Penpot is up at ${result.url}. Create an account and open a file, then run \`penpair connect\`.` : `The containers started but ${result.url} does not answer yet. Run \`penpair status\`.`);
-            return result.ready ? 0 : 1;
-        }
-        if (command === "down") {
-            await down(c);
-            console.log("stopped; the data volumes are kept");
-            return 0;
-        }
-        if (command === "status") {
-            const state = await status(c);
-            for (const s of state.services)
-                console.log(`${s.state.padEnd(10)} ${s.service}${s.health ? ` (${s.health})` : ""}`);
-            console.log(`${state.frontendReachable ? "answers" : "does not answer"} at ${state.url}; backend ${state.backendReady ? "ready" : "not ready"}`);
-            return state.frontendReachable && state.backendReady ? 0 : 1;
-        }
-        if (command === "doctor") {
-            const mcp = await mcpProbeFor();
-            return report(await doctor(c, { mcp }), mcp);
-        }
-        if (command === "backup") {
-            if (rest[0] === "verify") {
-                if (!rest[1])
-                    throw new Error("usage: penpair backup verify <backup directory>");
-                const result = await verifyBackup(c, rest[1]);
-                for (const check of result.checks)
-                    console.log(`${check.ok ? "ok  " : "FAIL"} ${check.check}: ${check.detail}`);
-                return result.ok ? 0 : 1;
-            }
-            const result = await backup(c);
-            console.log(`backup in ${result.directory} (${result.manifest.counts.files} files, ${result.manifest.counts.storageObjects} assets). It holds account data: never commit it.`);
-            return 0;
-        }
-        if (command === "restore") {
-            if (!rest[0])
-                throw new Error("usage: penpair restore <backup directory> --yes");
-            const result = await restore(c, rest[0], { yes: values.yes === true });
-            for (const check of result.checks)
-                console.log(`${check.ok ? "ok  " : "FAIL"} ${check.check}: ${check.detail}`);
-            if (result.safetyBackup)
-                console.log(`safety backup of the previous data: ${result.safetyBackup}`);
-            return result.ok ? 0 : 1;
-        }
-    }
-    const endpoint = await resolveEndpoint();
-    // In a project with an instance, act only on that instance unless told otherwise.
-    if (!values["any-instance"]) {
-        let projectConfig;
-        try {
-            projectConfig = await loadConfig(root);
-        }
-        catch {
-            // not a penpair project: any endpoint will do
-        }
-        if (projectConfig)
-            assertEndpointIsInstance(endpoint.description, projectConfig);
-    }
-    if (command === "probe") {
-        if (values.deep && !values.write)
-            throw new Error("probe --deep creates a temporary board, a token set and two components in the open file and removes them again. Run it on a scratch file, with --write to confirm.");
-        console.log(JSON.stringify(await probe(endpoint, () => connect(endpoint)), null, 2));
-        if (values.deep) {
-            const client = await connect(endpoint);
-            try {
-                const report = await runDeepCheck(client, { onWait: (m) => console.error(`… ${m}`) });
-                console.log(`\n${formatDeepReport(report)}`);
-                return report.ok ? 0 : 1;
-            }
-            finally {
-                await client.close();
-            }
-        }
-        return 0;
-    }
-    const client = await connect(endpoint);
-    const options = { onWait: (m) => console.error(`… ${m}`), onStep: (m) => console.error(`… ${m}`) };
-    try {
-        if (command === "run") {
-            const [name] = rest;
-            if (!name)
-                throw new Error("usage: penpair run <snippet> [--param key=value ...] [--apply]");
-            const { registry, problems } = await registryFor();
-            for (const problem of problems)
-                console.error(`warning: ${problem}`);
-            const raw = {};
-            for (const pair of values.param ?? []) {
-                const at = pair.indexOf("=");
-                if (at < 1)
-                    throw new RegistryError(`--param needs key=value, got ${JSON.stringify(pair)}`);
-                const key = pair.slice(0, at);
-                const value = pair.slice(at + 1);
-                const earlier = raw[key];
-                raw[key] = earlier === undefined ? value : [...(Array.isArray(earlier) ? earlier : [earlier]), value];
-            }
-            const entry = registry.get(name);
-            const result = await registry.run(client, name, coerceParams(entry.params, raw), { ...options, apply: values.apply === true });
-            console.log(JSON.stringify(result, null, 2));
-            if (entry.kind === "write" && !values.apply)
-                console.error("Nothing was written. Run again with --apply to do it.");
-            return result.phase === "applied" && !result.verified ? 1 : 0;
-        }
-        if (command === "baselines") {
-            const config = (await loadConfig(root)).baselines;
-            if (!config)
-                throw new Error('penpair.config.json has no "baselines" block. Add {"page": "<page>", "root": "tests/baselines", "frames": [{"frame": "<frame name>", "id": "<file name>", "route": "<route>"}]}; see docs/guide.md.');
-            const report = await exportBaselines(client, root, config, { ...options, apply: values.apply === true, update: values.update === true });
-            for (const r of report.results)
-                console.log(`${r.status.padEnd(9)} ${r.id.padEnd(28)} ${r.frame}${r.imageWidth ? ` (${r.imageWidth}x${r.imageHeight})` : ""}${r.written ? "  written" : ""}`);
-            for (const file of report.wrote)
-                console.log(`wrote     ${file}`);
-            const changed = report.results.filter((r) => r.status === "changed" && !r.written);
-            if (!values.apply)
-                console.error("Nothing was written. Run again with --apply to write new images.");
-            if (changed.length > 0)
-                console.error(`${changed.length} design(s) differ from the image in the folder. That is a change of the approved design: review it in Penpot, then run again with --apply --update to approve it.`);
-            if (report.results.some((r) => r.status === "missing" || r.status === "unstable"))
-                return 1;
-            return changed.length > 0 ? 2 : 0;
-        }
-        if (command === "pages")
-            console.log(JSON.stringify(await runSnippet(client, pages(), options), null, 2));
-        else if (command === "tree") {
-            if (!values.page)
-                throw new Error("--page is required");
-            const record = await runOnPage(client, tree({ page: values.page, depth: values.depth ? Number(values.depth) : 3, namePrefix: values.prefix }), values.page, options);
-            console.log((record.lines ?? []).join("\n"));
-        }
-        else if (command === "audit") {
-            if (!values.page || !values.prefix)
-                throw new Error("--page and --prefix are required");
-            const steps = values.steps ? values.steps.split(",").map(Number) : undefined;
-            const record = await runOnPage(client, audit({ page: values.page, framePrefix: values.prefix, spacingSteps: steps, ignoreUnbound: list(values.ignore) }), values.page, options);
-            console.log(JSON.stringify(record.frames, null, 2));
-        }
-        else if (command === "tokens" && rest[0] === "dump") {
-            const { ok: _ok, readOnly: _readOnly, ...dump } = await runSnippet(client, tokensDump(), options);
-            console.log(JSON.stringify(dump, null, 2));
-        }
-        else if (command === "export") {
-            const [shapeId, out] = rest;
-            if (!shapeId || !out)
-                throw new Error("usage: penpair export <shapeId> <out.png> [--page <name>] [--scale 1]");
-            const result = await exportShapePng(client, shapeId, { ...options, page: values.page, scale: values.scale ? Number(values.scale) : 1 });
-            await writeFile(out, result.png);
-            console.log(`saved ${out} (${result.png.length} bytes, ${result.stable ? "stable" : "not confirmed stable"} after ${result.exports} exports)`);
-        }
-        else if (command === "archive") {
-            if (!values.page || !values.name)
-                throw new Error("--page and --name are required");
-            const report = await runOperation(client, archiveOperation, { page: values.page, archiveName: values.name, keepPrefixes: list(values.keep), partPrefixes: list(values.parts), x: values.x ? Number(values.x) : 9000 }, { ...options, apply: values.apply === true });
-            console.log(JSON.stringify(report, null, 2));
-            if (report.phase === "inspected")
-                console.error("Nothing was written. Run again with --apply to do it.");
-            return report.phase === "applied" && !report.verified ? 1 : 0;
-        }
-        else {
-            console.log(usage);
-            return 1;
-        }
-        return 0;
-    }
-    finally {
-        await client.close();
-    }
-}
-main(process.argv.slice(2)).then((code) => {
-    process.exitCode = code;
-}, (error) => {
-    console.error(error instanceof PenpairError ? error.message : error instanceof ConfigError || error instanceof ConnectError || error instanceof LifecycleError || error instanceof RegistryError ? `penpair: ${error.message}` : `penpair: ${String(error?.message ?? error)}`);
-    process.exitCode = 1;
-});
+import { runCli } from "./cli-main.js";
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/docker-profile.d.ts

@@ -0,0 +1,114 @@
+import { type InstanceConfig, type ProjectConfig } from "./instance/config.js";
+import type { Check, DoctorCheck, DoctorOptions } from "./instance/connection.js";
+import type { Runner } from "./instance/runner.js";
+/**
+ * Running Penpot in Docker on this computer is one way to run it, and it lives in its own package, `@penpair/docker`, so a project
+ * that uses Penpot on the web carries none of it. This file is the whole contract between the two: the core knows these types and
+ * loads the package only when a project's profile or a command needs it. The package implements `DockerProfile`.
+ */
+/** What a Docker action needs to know about the project. Injectable so it can be tested without Docker. */
+export interface DockerContext {
+    root: string;
+    config: InstanceConfig;
+    runner: Runner;
+    log?: (message: string) => void;
+    sleep?: (milliseconds: number) => Promise<void>;
+    fetch?: typeof fetch;
+    now?: () => Date;
+}
+export interface ServiceState {
+    service: string;
+    state: string;
+    health: string;
+}
+export interface Counts {
+    files: number;
+    profiles: number;
+    teams: number;
+    storageObjects: number;
+    fileRevisions: {
+        id: string;
+        name: string;
+        revn: number;
+    }[];
+}
+export interface BackupManifest {
+    instance: string;
+    penpotVersion: string;
+    createdAt: string;
+    label?: string;
+    files: {
+        db: {
+            name: string;
+            sha256: string;
+            bytes: number;
+        };
+        assets: {
+            name: string;
+            sha256: string;
+            bytes: number;
+        };
+    };
+    counts: Counts;
+    note: string;
+}
+export interface RestoreOptions {
+    /** Restoring replaces the instance's data; it only runs when this is true. */
+    yes: boolean;
+    /** Skip the safety backup of the current data. */
+    skipSafetyBackup?: boolean;
+}
+export interface InitOptions {
+    instance?: string;
+    port?: number;
+    mailPort?: number;
+    penpotVersion?: string;
+    directory?: string;
+    composeProject?: string;
+    /** Use a Penpot someone else runs (a team server or the hosted service) instead of starting one: its origin, such as https://design.penpot.app. */
+    external?: string;
+    /** Add the instance directory and the key file to .gitignore. */
+    gitignore?: boolean;
+    isFree?: (port: number) => Promise<boolean>;
+}
+export interface InitResult {
+    config: ProjectConfig;
+    createdConfig: boolean;
+    createdSecrets: boolean;
+    files: string[];
+    gitignoreAdded: boolean;
+}
+export interface DockerProfile {
+    /** Throws a plain-language ConfigError when Docker is not running. */
+    preflight(runner: Runner): Promise<void>;
+    /** Writes the config when missing, the compose file and the secrets (never replaced). */
+    init(root: string, options: InitOptions): Promise<InitResult>;
+    up(c: DockerContext): Promise<{
+        url: string;
+        ready: boolean;
+    }>;
+    down(c: DockerContext): Promise<void>;
+    status(c: DockerContext): Promise<{
+        services: ServiceState[];
+        frontendReachable: boolean;
+        backendReady: boolean;
+        url: string;
+    }>;
+    doctor(c: DockerContext, options?: DoctorOptions): Promise<DoctorCheck[]>;
+    backup(c: DockerContext, label?: string): Promise<{
+        directory: string;
+        manifest: BackupManifest;
+    }>;
+    verifyBackup(c: DockerContext, directory: string): Promise<{
+        ok: boolean;
+        checks: Check[];
+    }>;
+    restore(c: DockerContext, directory: string, options: RestoreOptions): Promise<{
+        ok: boolean;
+        checks: Check[];
+        safetyBackup?: string;
+    }>;
+}
+export declare const dockerPackage = "@penpair/docker";
+/** Loads `@penpair/docker`, or says in plain words how to get it. The specifier is a variable so the core never depends on the package. */
+export declare function loadDockerProfile(importer?: (name: string) => Promise<unknown>): Promise<DockerProfile>;

package/dist/docker-profile.js

@@ -0,0 +1,18 @@
+import { ConfigError } from "./instance/config.js";
+export const dockerPackage = "@penpair/docker";
+/** Loads `@penpair/docker`, or says in plain words how to get it. The specifier is a variable so the core never depends on the package. */
+export async function loadDockerProfile(importer = (name) => import(name)) {
+    let loaded;
+    try {
+        loaded = (await importer(dockerPackage));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND")
+            throw new ConfigError("Running Penpot in Docker on this computer is a separate package that is not installed here. Install it with `npm i -D @penpair/docker`, or for a one-off run `npx -p @penpair/core -p @penpair/docker penpair <command>`. Penpot on the web needs nothing extra.");
+        throw error;
+    }
+    if (!loaded.dockerProfile)
+        throw new ConfigError(`${dockerPackage} is installed but does not export a Docker profile; update it to match this version of @penpair/core.`);
+    return loaded.dockerProfile;
+}

package/dist/index.d.ts

@@ -1,7 +1,10 @@
-export declare const version = "0.1.0";
+export { version } from "./version.js";
+export * from "./adapters.js";
 export * from "./baselines.js";
+export { runCli } from "./cli-main.js";
 export * from "./client.js";
 export * from "./deep-check.js";
+export * from "./local-profile.js";
 export * from "./endpoint.js";
 export * from "./errors.js";
 export * from "./export.js";
@@ -14,3 +17,9 @@ export * from "./snippet.js";
 export * from "./snippets/archive.js";
 export * from "./snippets/read.js";
 export * from "./tokens-diff.js";
+export * from "./instance/config.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";

package/dist/index.js

@@ -1,7 +1,10 @@
-export const version = "0.1.0";
+export { version } from "./version.js";
+export * from "./adapters.js";
 export * from "./baselines.js";
+export { runCli } from "./cli-main.js";
 export * from "./client.js";
 export * from "./deep-check.js";
+export * from "./local-profile.js";
 export * from "./endpoint.js";
 export * from "./errors.js";
 export * from "./export.js";
@@ -14,3 +17,8 @@ export * from "./snippet.js";
 export * from "./snippets/archive.js";
 export * from "./snippets/read.js";
 export * from "./tokens-diff.js";
+export * from "./instance/config.js";
+export * from "./instance/connection.js";
+export * from "./instance/gitignore.js";
+export { defaultInstanceName, init } from "./instance/init.js";
+export * from "./instance/runner.js";

package/dist/instance/config.d.ts

@@ -17,6 +17,8 @@ export interface InstanceConfig {
     snippets?: string[];
     /** Frames of a page to export as approved reference images for a check (see `penpair baselines`). */
     baselines?: BaselinesConfig;
+    /** Packages (or relative paths) that add commands for a library or tool; each keeps its own settings in its own block of this file. */
+    adapters?: string[];
 }
 /** 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 {
@@ -27,6 +29,7 @@ export interface ExternalConfig {
     };
     snippets?: string[];
     baselines?: BaselinesConfig;
+    adapters?: string[];
 }
 export type ProjectConfig = InstanceConfig | ExternalConfig;
 export declare const isExternal: (config: ProjectConfig) => config is ExternalConfig;