@penpair/core 0.1.0 → 0.1.2

package/dist/cli-main.js

@@ -0,0 +1,507 @@
+import { writeFile, readFile } from "node:fs/promises";
+import path from "node:path";
+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 { loadAdapters, readRawConfig, reservedCommands } from "./adapters.js";
+import { requireLocalProfile } from "./local-profile.js";
+import { assertEndpointIsInstance, doctorExternal, LifecycleError } from "./instance/connection.js";
+import { nodeRunner } from "./instance/runner.js";
+import { version } from "./version.js";
+const usageHead = `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
+@@SETUP@@  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]
+@@INSTANCE@@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 usageLocalInstance = `An instance on this computer (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 up | down | status                           start, stop (data stays) and look at the containers
+  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)
+`;
+const usageNoLocalInstance = `Penpot on this computer is not part of this install; it comes with the package @penpair/docker.
+`;
+const usageConnection = `Connecting to a Penpot (one project, configured in penpair.config.json):
+  penpair init --external <origin>                     use a Penpot someone else runs (a team server or https://design.penpot.app)
+  penpair doctor [--json]                              what is up, what is not, and what to do about it (--json for scripts and agents)
+`;
+const usage = (hasLocal, adapters = []) => usageHead.replace("@@INSTANCE@@", usageConnection + (hasLocal ? usageLocalInstance : usageNoLocalInstance)).replace("@@SETUP@@", hasLocal ? "  penpair setup --docker                               Penpot on this computer in Docker\n" : "") + adapterUsage(adapters);
+/** The commands that adapters from penpair.config.json add, after the core's own. */
+const adapterUsage = (adapters) => adapters.length === 0 ? "" : `\nAdapters (listed under "adapters" in penpair.config.json):\n${adapters.flatMap((a) => a.commands.flatMap((c) => c.usage.map((line) => `  ${line}`))).join("\n")}\n`;
+const list = (value) => (value ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+async function main(argv, cli) {
+    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(Boolean(cli.local), cli.adapters));
+        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,
+            local: cli.local,
+            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"));
+            for (const old of report.legacy)
+                console.log(`\nnote ${old.folder} is the old name of ${old.renamedTo}. ${old.carriedFacts ? "Your project-facts.md was copied to the new folder. " : ""}Delete the old folder and its links (.agents/skills/${path.posix.basename(old.folder)}, .claude/skills/${path.posix.basename(old.folder)}) and update its row in your AGENTS.md.`);
+            console.log("\nThen fill in references/project-facts.md in penpair-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 }, { local: cli.local });
+        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 local = requireLocalProfile(cli.local);
+        const c = { root, config: requireLocal(project), runner: nodeRunner, log };
+        if (command === "up") {
+            const result = await local.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 local.down(c);
+            console.log("stopped; the data volumes are kept");
+            return 0;
+        }
+        if (command === "status") {
+            const state = await local.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 local.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 local.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 local.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 local.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(Boolean(cli.local), cli.adapters));
+            return 1;
+        }
+        return 0;
+    }
+    finally {
+        await client.close();
+    }
+}
+/** Runs one command of an adapter with a context that can reach the project's Penpot. */
+async function runAdapterCommand(command, root, args) {
+    const config = await loadConfig(root);
+    const rawConfig = await readRawConfig(root);
+    const context = {
+        root,
+        config,
+        rawConfig,
+        log: (message) => console.error(`… ${message}`),
+        async withPenpot(work) {
+            const endpoint = await resolveEndpoint();
+            assertEndpointIsInstance(endpoint.description, config);
+            const client = await connect(endpoint);
+            try {
+                return await work(client);
+            }
+            finally {
+                await client.close();
+            }
+        },
+    };
+    return command.run(context, args);
+}
+/** Runs the command line and returns the exit code. The `penpair` command calls it with nothing extra; a package that adds a way to run Penpot calls it with its profile. */
+export async function runCli(argv, options = {}) {
+    try {
+        const root = process.cwd();
+        const raw = await readRawConfig(root);
+        const specifiers = Array.isArray(raw.adapters) ? raw.adapters.filter((entry) => typeof entry === "string") : [];
+        const loaded = options.adapters ? { adapters: options.adapters, problems: [] } : specifiers.length > 0 ? await loadAdapters(root, specifiers) : { adapters: [], problems: [] };
+        const [first] = argv;
+        const adapterCommand = loaded.adapters.flatMap((adapter) => adapter.commands).find((command) => command.name === first);
+        if (adapterCommand)
+            return await runAdapterCommand(adapterCommand, root, argv.slice(1));
+        const builtIn = reservedCommands.includes(first ?? "");
+        if (loaded.problems.length > 0 && (!builtIn || argv.includes("--help")))
+            for (const problem of loaded.problems)
+                console.error(`warning: ${problem}`);
+        return await main(argv, { ...options, adapters: loaded.adapters });
+    }
+    catch (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)}`);
+        return 1;
+    }
+}