@penpair/core 0.1.1 → 0.1.2

package/dist/adapters.d.ts

@@ -0,0 +1,49 @@
+import type { PenpotToolClient } from "./client.js";
+import { type ProjectConfig } from "./instance/config.js";
+/**
+ * An adapter is a package that teaches penpair about one library or tool (a component library's tokens, a checker) by adding
+ * commands. A project lists the adapters it uses under `adapters` in penpair.config.json; the core loads them by name from the
+ * project and knows nothing about any of them. An adapter keeps its own settings in its own block of the same file.
+ */
+export interface AdapterContext {
+    /** The project's folder. */
+    root: string;
+    /** The project's validated configuration. */
+    config: ProjectConfig;
+    /** The whole penpair.config.json as written, for the adapter's own block. */
+    rawConfig: Record<string, unknown>;
+    log(message: string): void;
+    /**
+     * Connects to the project's Penpot and runs `work` with the connection, closing it afterwards. The endpoint must belong to this
+     * project's Penpot, as for every command. Not called by commands that work offline.
+     */
+    withPenpot<T>(work: (client: PenpotToolClient) => Promise<T>): Promise<T>;
+}
+export interface AdapterCommand {
+    /** The word after `penpair`, for example `hello`. It must not be a command the core already has. */
+    name: string;
+    /** One line for `penpair --help`. */
+    summary: string;
+    /** Lines of usage for `penpair --help`. */
+    usage: string[];
+    /** Runs with the arguments after the command's name; returns the exit code. The adapter parses its own flags. */
+    run(context: AdapterContext, args: string[]): Promise<number>;
+}
+export interface Adapter {
+    name: string;
+    commands: AdapterCommand[];
+}
+/** Declares an adapter. Returns the definition unchanged, so a module can `export default defineAdapter({...})` with types checked. */
+export declare const defineAdapter: <T extends Adapter>(adapter: T) => T;
+/** The commands of the core itself; an adapter cannot take one of these names. */
+export declare const reservedCommands: readonly ["probe", "pages", "tree", "audit", "tokens", "export", "archive", "snippets", "run", "skills", "init", "setup", "connect", "up", "down", "status", "doctor", "backup", "restore", "baselines"];
+export interface LoadedAdapters {
+    adapters: Adapter[];
+    problems: string[];
+}
+export type AdapterImporter = (specifier: string, root: string) => Promise<unknown>;
+/** Resolves an adapter the way the project would: a relative path from the project's folder, or a package installed in the project. */
+export declare const importFromProject: AdapterImporter;
+export declare function loadAdapters(root: string, specifiers: string[] | undefined, importer?: AdapterImporter): Promise<LoadedAdapters>;
+/** The whole penpair.config.json as written (an adapter's own settings live in it). Empty when there is no file. */
+export declare function readRawConfig(root: string): Promise<Record<string, unknown>>;

package/dist/adapters.js

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

package/dist/cli-main.d.ts

@@ -1,5 +1,8 @@
+import { type Adapter } from "./adapters.js";
 import { type LocalProfile } from "./local-profile.js";
 export interface CliOptions {
+    /** Adapters already loaded (the command loads the project's own from penpair.config.json). */
+    adapters?: Adapter[];
     /** A way to run Penpot on this computer, from a package that provides one (`@penpair/docker`). Without it those commands explain where they come from. */
     local?: LocalProfile;
 }

package/dist/cli-main.js

@@ -1,4 +1,5 @@
 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";
@@ -19,6 +20,7 @@ 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";
@@ -67,7 +69,9 @@ const usageConnection = `Connecting to a Penpot (one project, configured in penp
   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) => usageHead.replace("@@INSTANCE@@", usageConnection + (hasLocal ? usageLocalInstance : usageNoLocalInstance)).replace("@@SETUP@@", hasLocal ? "  penpair setup --docker                               Penpot on this computer in Docker\n" : "");
+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({
@@ -113,7 +117,7 @@ async function main(argv, cli) {
         return 0;
     }
     if (!command || values.help) {
-        console.log(usage(Boolean(cli.local)));
+        console.log(usage(Boolean(cli.local), cli.adapters));
         return 0;
     }
     if (command === "tokens" && rest[0] === "diff") {
@@ -220,7 +224,9 @@ async function main(argv, cli) {
                 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.");
+            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())
@@ -445,7 +451,7 @@ async function main(argv, cli) {
             return report.phase === "applied" && !report.verified ? 1 : 0;
         }
         else {
-            console.log(usage(Boolean(cli.local)));
+            console.log(usage(Boolean(cli.local), cli.adapters));
             return 1;
         }
         return 0;
@@ -454,10 +460,45 @@ async function main(argv, cli) {
         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 {
-        return await main(argv, options);
+        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)}`);

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { version } from "./version.js";
+export * from "./adapters.js";
 export * from "./baselines.js";
 export { runCli } from "./cli-main.js";
 export * from "./client.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { version } from "./version.js";
+export * from "./adapters.js";
 export * from "./baselines.js";
 export { runCli } from "./cli-main.js";
 export * from "./client.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;

package/dist/instance/config.js

@@ -39,6 +39,8 @@ export function validateConfig(value) {
     }
     if (v.baselines !== undefined)
         validateBaselines(v.baselines, fail);
+    if (v.adapters !== undefined && !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0)))
+        fail("adapters must be a list of package names or relative paths");
     return v;
 }
 const instanceNamePattern = /^[a-z][a-z0-9-]{0,30}$/;
@@ -67,6 +69,8 @@ export function validateProjectConfig(value) {
         fail("snippets must be a list of relative paths that stay inside the project");
     if (v.baselines !== undefined)
         validateBaselines(v.baselines, fail);
+    if (v.adapters !== undefined && !(Array.isArray(v.adapters) && v.adapters.every((e) => typeof e === "string" && e.length > 0)))
+        fail("adapters must be a list of package names or relative paths");
     return v;
 }
 /** The config of a project that runs its own Penpot; anything else cannot start, stop or back up containers. */

package/dist/instance/setup.js

@@ -51,6 +51,6 @@ export async function setup(root, io, options) {
     io.say("Everything answers. Last: the rules your assistant follows.");
     if (options.installSkills)
         await options.installSkills();
-    io.say("Done. Try `penpair pages`, or tell your assistant to read the penpot-design skill and start.");
+    io.say("Done. Try `penpair pages`, or tell your assistant to read the penpair-design skill and start.");
     return { config, connect };
 }

package/dist/skills.d.ts

@@ -20,6 +20,8 @@ export interface InstallOptions {
     /** For tests. */
     source?: string;
 }
+/** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
+export declare const renamedSkills: Record<string, string>;
 export interface InstallReport {
     installed: string[];
     unchanged: string[];
@@ -28,5 +30,11 @@ export interface InstallReport {
     linked: string[];
     /** One line per skill for the project's AGENTS.md. */
     agentsRows: string[];
+    /** Folders of skills that were renamed and are still in the project, and whether their project-facts file was carried over. */
+    legacy: {
+        folder: string;
+        renamedTo: string;
+        carriedFacts: boolean;
+    }[];
 }
 export declare function installSkills(options: InstallOptions): Promise<InstallReport>;

package/dist/skills.js

@@ -44,6 +44,8 @@ export async function describeSkill(skillDirectory) {
     const description = /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "";
     return { name, summary: description.split(/(?<=\.)\s/)[0] ?? description };
 }
+/** Skills that changed name. Installing the new one leaves the old folder behind, which `installSkills` then reports. */
+export const renamedSkills = { "penpot-design": "penpair-design" };
 export async function installSkills(options) {
     const source = options.source ?? bundledSkillsDirectory();
     const to = options.to ?? ".skills";
@@ -52,7 +54,7 @@ export async function installSkills(options) {
     for (const name of chosen)
         if (!names.includes(name))
             throw new Error(`no skill named ${name}; shipped: ${names.join(", ")}`);
-    const report = { installed: [], unchanged: [], kept: [], linked: [], agentsRows: [] };
+    const report = { installed: [], unchanged: [], kept: [], linked: [], agentsRows: [], legacy: [] };
     for (const name of chosen) {
         const from = path.join(source, name);
         for (const file of await filesUnder(from)) {
@@ -87,5 +89,18 @@ export async function installSkills(options) {
         const { summary } = await describeSkill(from);
         report.agentsRows.push(`| [${name}](${path.posix.join(to, name, "SKILL.md")}) | ${summary} |`);
     }
+    for (const [oldName, newName] of Object.entries(renamedSkills)) {
+        if (!chosen.includes(newName) || !(await exists(path.join(options.root, to, oldName))))
+            continue;
+        // The project-facts file is the project's own work: carry it over when the new copy is still the empty template.
+        const oldFacts = await readIfExists(path.join(options.root, to, oldName, "references/project-facts.md"));
+        const newFactsFile = path.join(options.root, to, newName, "references/project-facts.md");
+        const template = await readIfExists(path.join(source, newName, "references/project-facts.md"));
+        const current = await readIfExists(newFactsFile);
+        const carriedFacts = oldFacts !== undefined && oldFacts !== template && current === template;
+        if (carriedFacts)
+            await writeFile(newFactsFile, oldFacts);
+        report.legacy.push({ folder: path.posix.join(to, oldName), renamedTo: newName, carriedFacts });
+    }
     return report;
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export declare const version = "0.1.1";
+export declare const version = "0.1.2";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Kept in its own file so that the command line and the library entry can both read it without importing each other. Equals package.json (a test checks). */
-export const version = "0.1.1";
+export const version = "0.1.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Design together. Build together. The library and engine behind penpair: connect AI agents and people to a Penpot design file, safely. Install @penpair/web or @penpair/docker for the command.",
   "license": "MIT",
   "repository": {
@@ -20,8 +20,8 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },

package/skills/design-judgment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-judgment
-description: Decide how a screen is structured, filled and judged before it is built. Use when designing or redesigning a page or flow (list, detail, queue, dashboard, admin), choosing a composition or density, deciding what fills a card or panel, defining loading, empty and error states, mapping status or feedback to components, comparing layout options, or critiquing a design or a rendered screen. Do not use for writing to Penpot (penpot-design) or for picking and verifying components of a specific library.
+description: Decide how a screen is structured, filled and judged before it is built. Use when designing or redesigning a page or flow (list, detail, queue, dashboard, admin), choosing a composition or density, deciding what fills a card or panel, defining loading, empty and error states, mapping status or feedback to components, comparing layout options, or critiquing a design or a rendered screen. Do not use for writing to Penpot (penpair-design) or for picking and verifying components of a specific library.
 metadata:
   version: "0.1.0"
   scope: design reasoning

package/skills/{penpot-design → penpair-design}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: penpot-design
+name: penpair-design
 description: Work in a Penpot file through penpair: inspect, build, change, audit, export and archive frames and components, bind every value to a token, keep layout as flat auto-layout, and run Penpot as one instance per project. Use when creating, editing, inspecting or exporting anything in Penpot, adding or binding tokens, writing a project snippet, setting up or checking a Penpot instance, or diagnosing a plugin or connection error. Do not use for deciding how a screen should be structured (design-judgment).
 metadata:
   version: "0.1.0"
@@ -8,7 +8,7 @@ metadata:
 compatibility: A running Penpot (local Docker, a team server or the hosted service) with the plugin connected in a visible editor tab, Node 22, penpair installed.
 ---
 
-# penpot-design
+# penpair-design
 
 Penpot is the authority for the design; the code adapts to the frames. The project's component library defines what exists: a component, token or layout the library has wins, and only what it lacks becomes a project-specific component or token.
 

package/skills/{penpot-design → penpair-design}/references/penpot-plugin-gotchas.md

@@ -43,6 +43,8 @@ Each one cost real time. They are written as the behaviour to use. Penpot 2.18.3
 - **Exports can fail once and then work, and can be stale right after a write or a page switch.** Export again, and compare two in a row.
 - The MCP key is personal, one per account, shown once. A key for another instance silently drives another file; penpair refuses it unless told otherwise.
 - A snippet receives data only through its parameters; it cannot read repository files.
+- **Token values can be changed in place** (`token.value = ...`, `token.description = ...`), and `token.remove()`, `set.remove()`, `theme.addSet(set)`, `theme.removeSet(set)` and `theme.remove()` all work. **Not for a typography token:** creating one normalises it (`fontFamilies: "Inter"` becomes `fontFamily: ["Inter"]`), but assigning a new value stores the object as given, un-normalised. Remove the token and add it again, and compare typography values in their normalised form. (Checked on Penpot 2.18.4, hosted.)
+- A new token set is inactive and a set's `resolvedValue` is null until a theme activates it; a file with no active theme resolves no tokens at all.
 
 ## Rendering differences to design for
 

package/skills/penpair-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: penpair-setup
-description: Set up penpair in a project and connect it to a Penpot, on the web (the default) or in Docker on this computer. Use when a project has no penpair.config.json, when `penpair doctor` reports a failure, when the user asks to install, start, connect, repair or move their Penpot connection, or when an agent is told "set up penpair". Do not use for editing a Penpot file (penpot-design) or deciding how a screen looks (design-judgment).
+description: Set up penpair in a project and connect it to a Penpot, on the web (the default) or in Docker on this computer. Use when a project has no penpair.config.json, when `penpair doctor` reports a failure, when the user asks to install, start, connect, repair or move their Penpot connection, or when an agent is told "set up penpair". Do not use for editing a Penpot file (penpair-design) or deciding how a screen looks (design-judgment).
 metadata:
   version: "0.1.0"
   scope: setup and connection
@@ -39,7 +39,7 @@ The MCP key is the person's password to their Penpot. Keep it out of chat, logs,
    | editor and plugin: not connected or suspended | The tab is asleep or the plugin is not connected. Do step 4.4 again; keep the tab in front. |
    | key file: git would commit it | Add `.env.local` to `.gitignore`; `penpair connect` does it. |
 
-6. **Install the rules.** Run `npx @penpair/web skills install`, add the printed rows to the project's agent guide, then fill in `.skills/penpot-design/references/project-facts.md` with the person (the Penpot file, token sets, naming, who approves). Done when that file has no `<...>` placeholders left.
+6. **Install the rules.** Run `npx @penpair/web skills install`, add the printed rows to the project's agent guide, then fill in `.skills/penpair-design/references/project-facts.md` with the person (the Penpot file, token sets, naming, who approves). Done when that file has no `<...>` placeholders left.
 
 ## Moving between web and Docker