@geekity/cms 0.24.0 → 0.26.0

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import type { GeekityConfig } from './config.ts';
-export type Command = 'serve' | 'init' | 'sync' | 'rebuild' | 'resend' | 'user' | 'import' | 'maintenance' | 'strip-metadata' | 'help' | 'version';
+export type Command = 'serve' | 'init' | 'sync' | 'rebuild' | 'resend' | 'user' | 'maintenance' | 'strip-metadata' | 'plugin' | 'help' | 'version';
 export interface ParsedArgs {
     command: Command;
     /** Path to the config file, relative to the working directory, if the user named one. */
@@ -24,8 +24,7 @@ export interface ParsedArgs {
     flags: Readonly<Record<string, string | true>>;
     /**
      * Positional arguments after the command: the directory for `init`, the
-     * subcommand and its arguments for `user` and `import`. Flags are never in
-     * here.
+     * subcommand and its arguments for `user`. Flags are never in here.
      */
     args: readonly string[];
 }

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AASjD,MAAM,MAAM,OAAO,GACf,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,aAAa,GACb,gBAAgB,GAChB,MAAM,GACN,SAAS,CAAC;AAoCd,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,yFAAyF;IACzF,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;OAGG;IACH,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/C;;;;OAIG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AA2FD,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAsH7D;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,aAAa,CAAC,CAyBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW3D;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F;AAyqBD,gEAAgE;AAChE,KAAK,aAAa,GAAG,MAAM,CAAC,cAAc,GAAG;IAC3C,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4CrF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAsBjD,MAAM,MAAM,OAAO,GACf,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,MAAM,GACN,aAAa,GACb,gBAAgB,GAChB,QAAQ,GACR,MAAM,GACN,SAAS,CAAC;AAwBd,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,yFAAyF;IACzF,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;OAGG;IACH,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/C;;;OAGG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAwED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAsH7D;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAAC,aAAa,CAAC,CAyBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW3D;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7F;AAwwBD,gEAAgE;AAChE,KAAK,aAAa,GAAG,MAAM,CAAC,cAAc,GAAG;IAC3C,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4CrF"}

package/dist/cli.js

@@ -7,8 +7,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import cluster from 'node:cluster';
 import { existsSync, realpathSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
@@ -22,9 +22,13 @@ import { databaseFile, discardDatabase } from './cache.js';
 import { resolveConfig } from './config.js';
 import { stripStoredUploads } from './content/metadata/sweep.js';
 import { UPLOAD_DIRECTORY } from './web/assets.js';
-import { importWordPressActor } from './federation/import-wordpress.js';
 import { createCms } from './index.js';
 import { initSite, ownManifest, seedStarterContent } from './init.js';
+import { importPluginFolders, scanPluginFolders } from './plugins/folder.js';
+import { addPlugin, DEFAULT_REGISTRY, installedFolders, parsePackageSpec, removePlugin, requirementNotes, } from './plugins/install.js';
+import { pluginSite, sitePluginRegistry } from './plugins/site.js';
+import { superviseCluster } from './supervisor/primary.js';
+import { processChannel, superviseWorker } from './supervisor/worker.js';
 import { enterMaintenance, leaveMaintenance, maintenanceFile, readMaintenance, } from './maintenance.js';
 /** The commands a site can name on the command line, as opposed to the flags. */
 const COMMANDS = [
@@ -34,29 +38,17 @@ const COMMANDS = [
     'rebuild',
     'resend',
     'user',
-    'import',
     'maintenance',
     'strip-metadata',
+    'plugin',
 ];
 /**
  * The options one command reads out of {@link ParsedArgs.flags}, each of which
  * carries a value.
- *
- * A table rather than a branch per flag, because `import wordpress-actor`
- * takes six of them and a parser with six more near-identical cases in it
- * would be six more places to get the same thing subtly wrong.
  */
-const VALUE_FLAGS = [
-    'actor-id',
-    'wordpress-id',
-    'private-key',
-    'public-key',
-    'keypair',
-    'followers',
-    'until',
-];
+const VALUE_FLAGS = ['until'];
 /** The options that are simply on or off. */
-const SWITCH_FLAGS = ['force', 'all'];
+const SWITCH_FLAGS = ['all'];
 const CONFIG_FILENAMES = ['geekity.config.ts', 'geekity.config.js', 'geekity.config.mjs'];
 const USAGE = `geekity — the Geekity CMS command line
 
@@ -69,9 +61,7 @@ Usage:
   geekity maintenance (on [--until <time>] | off | status) [--config <file>]
   geekity strip-metadata [--config <file>]
   geekity user add <username> [--password <pw>] [--email <address>] [--config <file>]
-  geekity import wordpress-actor <username> --actor-id <url> --wordpress-id <n>
-          (--keypair <file> | --private-key <file> [--public-key <file>])
-          [--followers <url|file|none>] [--force] [--config <file>]
+  geekity plugin (add <package>[@version] | remove <package>) [--config <file>]
 
 Commands:
   serve            Start the CMS (the default when no command is given).
@@ -97,11 +87,13 @@ Commands:
                    as it is.
   user add         Create an admin user, so a site can get its first login
                    without the setup screen.
-  import
-    wordpress-actor
-                   Bring one person across from the WordPress ActivityPub
-                   plugin: their key pair, the actor id their followers hold,
-                   the plugin's numeric actor id, and their followers.
+  plugin add       Install a plugin package's bundle from the npm registry
+                   (npm_config_registry, or registry.npmjs.org) into the
+                   plugins folder, GEEKITY_PLUGINS_DIR. It installs only the
+                   package named, and names any plugin it requires that is
+                   missing. Reload on the Plugins screen loads it.
+  plugin remove    Delete a plugin's folder from the plugins folder. Reload on
+                   the Plugins screen unloads it.
 
 Options:
   --config <file>  Config file to load. Defaults to the first of
@@ -112,36 +104,17 @@ Options:
                    list and in shell history, so prefer being asked.
   --email <addr>   The new user's email address. Optional; it is what a
                    forgotten password is recovered through.
-  --actor-id <url> The actor id WordPress published, query string and all,
-                   for example https://example.com/?author=2
-  --wordpress-id <n>
-                   The WordPress user id, which is the number in the plugin's
-                   paths (/wp-json/activitypub/1.0/actors/<n>/inbox).
-  --keypair <file> The JSON \`wp option get activitypub_keypair_for_<login>
-                   --format=json\` prints: {"private_key": …, "public_key": …}.
-  --private-key <file>
-                   The private key as PEM, instead of --keypair.
-  --public-key <file>
-                   The public key as PEM. Optional, and only checked against
-                   the private half — it is derived, never stored.
-  --followers <url|file|none>
-                   Where the followers come from. Left off, the plugin's own
-                   public followers collection on the actor id's origin.
   --until <time>   With maintenance on: when the site should be back, as an
                    ISO 8601 time such as 2026-09-28T14:00:00Z. It is the
                    Retry-After a client is sent, and the maintenance page
                    says it.
   --all            With resend: every announced post rather than named ones.
-  --force          Import over a key pair the user already has. Do this only
-                   when you are certain the pair being imported is the one the
-                   followers hold: a new key means none of them can verify
-                   this person again.
   -h, --help       Show this help.
   -v, --version    Show the installed version.
 
 Environment overrides:
   GEEKITY_PORT (or PORT), GEEKITY_CONTENT_DIR, GEEKITY_DATA_DIR,
-  GEEKITY_THEMES_DIR, GEEKITY_BASE_URL, GEEKITY_WATCH,
+  GEEKITY_THEMES_DIR, GEEKITY_PLUGINS_DIR, GEEKITY_BASE_URL, GEEKITY_WATCH,
   GEEKITY_MAINTENANCE (on keeps the site in maintenance until a restart)
 `;
 /** Turn `process.argv.slice(2)` into a command, its options and its arguments. */
@@ -354,9 +327,13 @@ function isModuleNotFound(error, candidate) {
 }
 /** Run one command. Resolves with the exit code the process should use. */
 async function main(argv) {
+    const first = leadingWords(argv)[0];
+    if (first !== undefined && !isCommand(first) && !argv.some(isHelpOrVersion)) {
+        return await pluginCommand(argv);
+    }
     const { command, configPath, password, email, flags, args } = parseArgs(argv);
     if (command === 'help') {
-        process.stdout.write(USAGE);
+        process.stdout.write(await usage(configPath));
         return 0;
     }
     if (command === 'version') {
@@ -367,8 +344,6 @@ async function main(argv) {
         return init(args);
     if (command === 'user')
         return userCommand(args, configPath, password, email);
-    if (command === 'import')
-        return importCommand(args, configPath, flags);
     if (command === 'sync')
         return syncCommand(configPath);
     if (command === 'rebuild')
@@ -379,6 +354,8 @@ async function main(argv) {
         return maintenanceCommand(args, configPath, flags);
     if (command === 'strip-metadata')
         return stripMetadataCommand(configPath);
+    if (command === 'plugin')
+        return pluginFolderCommand(args, configPath);
     return serveCommand(configPath);
 }
 /** `geekity init <directory>`: scaffold a new site. */
@@ -649,33 +626,105 @@ const SQLITE_LOCKED = 6;
 /**
  * `geekity serve`: the default. Runs until it is signalled.
  *
+ * This process is a supervisor (TASK-288): it owns the port and runs the CMS
+ * in a `node:cluster` worker that runs this same command, so Reload on the
+ * Plugins screen can boot a new worker beside the old one and a worker that
+ * crashes is respawned, both without restarting the container.
+ *
  * With `seedContent` on, a missing or empty content directory is given the
- * starter site before the CMS opens it, so a new box boots into something to
- * show and the setup screen. It happens here rather than in `createCms` so a
- * site that builds its own server never has content written for it.
+ * starter site before any worker opens it, so a new box boots into something
+ * to show and the setup screen. It happens here rather than in `createCms` so
+ * a site that builds its own server never has content written for it.
  */
 async function serveCommand(configPath) {
-    const config = await loadConfig(process.cwd(), configPath);
-    const resolved = resolveConfig(config);
+    if (cluster.isWorker)
+        return serveWorker(configPath);
+    const resolved = resolveConfig(await loadConfig(process.cwd(), configPath));
     if (resolved.seedContent &&
         (await seedStarterContent({ contentDir: resolved.contentDir, baseUrl: resolved.baseUrl }))) {
         process.stdout.write(`Seeded ${resolved.contentDir} with the starter site\n`);
     }
-    // The access log is on here and off in `createCms`: a server that answers
-    // the internet should be able to say what it answered, while a CMS embedded
-    // in somebody else's app has no business writing to their stdout uninvited.
-    // Named as a config value rather than forced, so `GEEKITY_ACCESS_LOG` still
-    // wins and a site that wrote `accessLog: false` still gets silence.
-    const cms = createCms({ ...config, accessLog: config.accessLog ?? true });
-    const { port } = await cms.serve();
-    process.stdout.write(`Geekity is serving ${cms.config.baseUrl} on port ${String(port)}\n`);
-    for (const signal of ['SIGINT', 'SIGTERM']) {
-        process.once(signal, () => {
-            void cms.close().then(() => process.exit(0));
+    superviseCluster();
+    return 0;
+}
+/**
+ * One worker under the supervisor: the site's config and its plugins folder,
+ * read afresh, so a reload sees what changed. Signals are the supervisor's to
+ * act on; it tells this worker when to close.
+ */
+async function serveWorker(configPath) {
+    const channel = processChannel();
+    for (const signal of ['SIGINT', 'SIGTERM'])
+        process.on(signal, () => undefined);
+    try {
+        const config = await loadConfig(process.cwd(), configPath);
+        const loaded = scanPluginFolders(resolveConfig(config).pluginsDir);
+        const worker = superviseWorker({
+            channel,
+            loaded,
+            exit: (code) => process.exit(code),
+            log: (line) => process.stderr.write(`${line}\n`),
         });
+        // The access log is on here and off in `createCms`: a server that answers
+        // the internet should be able to say what it answered, while a CMS embedded
+        // in somebody else's app has no business writing to their stdout uninvited.
+        // Named as a config value rather than forced, so `GEEKITY_ACCESS_LOG` still
+        // wins and a site that wrote `accessLog: false` still gets silence.
+        const cms = createCms({ ...config, accessLog: config.accessLog ?? true }, { folderPlugins: await importPluginFolders(loaded), supervision: worker.supervision });
+        const { port } = await cms.serve();
+        process.stdout.write(`Geekity is serving ${cms.config.baseUrl} on port ${String(port)}\n`);
+        worker.serving(cms);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        channel.send({ type: 'boot-failed', error: message }, () => process.exit(1));
+    }
+    return 0;
+}
+/**
+ * `geekity plugin add <package>` and `geekity plugin remove <package>`
+ * (decision-33): change the plugins folder, which Reload on the Plugins
+ * screen then loads. Nothing a plugin requires is installed for it.
+ */
+async function pluginFolderCommand(args, configPath) {
+    const [action, spec, ...rest] = args;
+    if ((action !== 'add' && action !== 'remove') || spec === undefined || rest.length > 0) {
+        throw new Error('geekity plugin needs add <package>[@version] or remove <package>.');
+    }
+    const config = resolveConfig(await loadConfig(process.cwd(), configPath));
+    const { pluginsDir } = config;
+    if (pluginsDir === undefined) {
+        throw new Error('geekity plugin needs a plugins folder: set GEEKITY_PLUGINS_DIR, or pluginsDir in the config.');
+    }
+    if (action === 'remove') {
+        const directory = await removePlugin(spec, pluginsDir);
+        process.stdout.write(`Removed ${spec} (${directory}). Reload on the Plugins screen to unload it.\n`);
+        return 0;
     }
+    const registry = firstSet(process.env['npm_config_registry'], process.env['NPM_CONFIG_REGISTRY']) ??
+        DEFAULT_REGISTRY;
+    const { manifest, directory, replaced } = await addPlugin(parsePackageSpec(spec), {
+        pluginsDir,
+        registry,
+    });
+    const installed = new Map([
+        ...config.plugins.map((plugin) => [plugin.name, plugin.version]),
+        ...installedFolders(pluginsDir),
+    ]);
+    const done = replaced === undefined || replaced === manifest.version
+        ? `Added ${manifest.name} ${manifest.version} to ${directory}.`
+        : `Replaced ${manifest.name} ${replaced} with ${manifest.version} in ${directory}.`;
+    process.stdout.write([
+        done,
+        ...requirementNotes(manifest, installed, ownManifest().version),
+        'Reload on the Plugins screen to load it, then enable it there.',
+        '',
+    ].join('\n'));
     return 0;
 }
+function firstSet(...values) {
+    return values.find((value) => value !== undefined && value !== '');
+}
 /**
  * `geekity user add <username>`: create an admin without the setup screen.
  *
@@ -731,174 +780,191 @@ async function userCommand(args, configPath, flagPassword, flagEmail) {
 }
 /** Where the success line points a new admin. Relative, because the host is the site's. */
 const LOGIN_URL = '/admin/login';
+/** One flag as the text it carries, or `undefined` when it was not given. */
+function text(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+}
+function isHelpOrVersion(arg) {
+    return arg === '--help' || arg === '-h' || arg === '--version' || arg === '-v';
+}
+/** The bare words before the first option other than `--config`. */
+function leadingWords(argv) {
+    const words = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--config') {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--config='))
+            continue;
+        if (arg.startsWith('-'))
+            break;
+        words.push(arg);
+    }
+    return words;
+}
+/** `--config <file>` or `--config=<file>`, wherever it is. */
+function configFlag(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--config')
+            return argv[i + 1];
+        if (arg.startsWith('--config='))
+            return arg.slice('--config='.length);
+    }
+    return undefined;
+}
 /**
- * `geekity import wordpress-actor <username>`: the cutover, for one person.
- *
- * Everything the plugin holds that this CMS cannot mint for itself arrives
- * here (decision-14): the RSA pair its followers have cached, the actor id
- * they key the account by, the number its paths are built from, and the
- * followers themselves. It is a command rather than a screen because a stored
- * actor id is identity for the life of the account, and it is idempotent
- * because the cutover is a thing an owner will want to run twice — once before
- * the DNS moves and once after an instance that was down comes back.
+ * Every command the site's available plugins add, from its config and its
+ * plugins folder, longest words first.
+ */
+async function pluginCommands(config) {
+    const folderPlugins = await importPluginFolders(scanPluginFolders(config.pluginsDir));
+    return sitePluginRegistry(config, folderPlugins)
+        .plugins.filter((entry) => entry.problem === undefined)
+        .flatMap((entry) => entry.commands.map((command) => ({ plugin: entry.plugin.name, command })))
+        .sort((a, b) => b.command.words.length - a.command.words.length);
+}
+/**
+ * Run a command a plugin added (decision-33). It needs no enabling: a
+ * migration command runs before the plugin it prepares for is turned on.
  *
- * The database is opened for the reason `user add` opens it: this is a door
- * that can reach `data/users.json` before any server has, so a site upgrading
- * from the version that kept its accounts in SQLite has to be migrated first
- * or the import would write into a file holding nobody.
+ * The database is opened for the reason `user add` opens it: a command can
+ * reach `data/users.json` before any server has, so a site upgrading from the
+ * version that kept its accounts in SQLite is migrated first.
  */
-async function importCommand(args, configPath, flags) {
-    const subcommand = args[0];
-    if (subcommand === undefined) {
-        throw new Error('geekity import <what> needs a subcommand. The only one is: wordpress-actor.');
-    }
-    if (subcommand !== 'wordpress-actor') {
-        throw new Error(`Unknown import subcommand "${subcommand}". The only one is: wordpress-actor.`);
-    }
-    const username = args[1];
-    if (username === undefined) {
-        throw new Error('geekity import wordpress-actor <username> needs the account on this site the ' +
-            "plugin's actor becomes.");
-    }
-    const actorId = text(flags, 'actor-id');
-    if (actorId === undefined) {
-        throw new Error('--actor-id is the id WordPress published this person under, query string and all, ' +
-            'for example --actor-id "https://example.com/?author=2". Its followers key the ' +
-            'account by it, so it is the one thing the import cannot work out for itself.');
-    }
-    if (!isAbsoluteHttpUrl(actorId)) {
-        throw new Error(`--actor-id must be an http or https URL; "${actorId}" is not one.`);
-    }
-    const number = text(flags, 'wordpress-id');
-    if (number === undefined || !/^[1-9][0-9]*$/.test(number)) {
-        throw new Error('--wordpress-id is the WordPress user id, a whole positive number: it is what the ' +
-            "plugin's paths are built from, as in /wp-json/activitypub/1.0/actors/2/inbox.");
-    }
-    const { privateKeyPem, publicKeyPem } = await readKeyPair(flags);
+async function pluginCommand(argv) {
+    const configPath = configFlag(argv);
     const config = resolveConfig(await loadConfig(process.cwd(), configPath));
+    const words = leadingWords(argv);
+    const found = (await pluginCommands(config)).find(({ command }) => command.words.every((word, index) => words[index] === word));
+    if (found === undefined) {
+        throw new Error(`Unknown command "${words[0] ?? ''}". Run geekity --help to see what is available.`);
+    }
+    const { args, options } = parseCommandArgs(withoutConfig(argv).slice(found.command.words.length), found.command);
     const admin = openAdminStore({ dataDir: config.dataDir });
     migrateUsersToFile({ admin, dataDir: config.dataDir });
     try {
-        const report = await importWordPressActor({
-            admin,
-            dataDir: config.dataDir,
-            contentDir: config.contentDir,
-            username,
-            actorId,
-            wordpressActorId: Number(number),
-            privateKeyPem,
-            publicKeyPem,
-            followers: followersSource(flags),
-            force: flags['force'] === true,
+        return await found.command.run({
+            args,
+            options,
+            cwd: process.cwd(),
+            site: pluginSite({ admin, config }),
+            write: (output) => process.stdout.write(output),
         });
-        process.stdout.write(importSummary(report));
-        return 0;
     }
     finally {
         admin.close();
     }
 }
-/**
- * The key pair, from whichever of the two exports the owner had to hand.
- *
- * `--keypair` is the option the current plugin stores — one option holding
- * both halves — and the two PEM files are what `wp user meta get` prints for a
- * site old enough to still be on the legacy meta keys. The README says which
- * command produces which.
- */
-async function readKeyPair(flags) {
-    const keypair = text(flags, 'keypair');
-    const privateKey = text(flags, 'private-key');
-    const publicKey = text(flags, 'public-key');
-    if (keypair !== undefined) {
-        if (privateKey !== undefined) {
-            throw new Error('Pass either --keypair or --private-key, not both.');
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(await readFile(path.resolve(process.cwd(), keypair), 'utf8'));
+function withoutConfig(argv) {
+    const kept = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--config') {
+            i += 1;
+            continue;
         }
-        catch (error) {
-            throw new Error(`${keypair} could not be read as the JSON "wp option get … --format=json" prints: ` +
-                `${error instanceof Error ? error.message : String(error)}`, { cause: error });
-        }
-        const held = parsed;
-        if (typeof held?.private_key !== 'string') {
-            throw new Error(`${keypair} has no "private_key". Check what the export wrote.`);
-        }
-        return {
-            privateKeyPem: held.private_key,
-            publicKeyPem: typeof held.public_key === 'string' ? held.public_key : undefined,
-        };
-    }
-    if (privateKey === undefined) {
-        throw new Error('The key pair is missing: pass --keypair with the JSON WordPress stores, or ' +
-            '--private-key with the PEM. Without it this person could not sign anything, and ' +
-            'every follower holds the public half of the key that signs it.');
-    }
-    return {
-        privateKeyPem: await readFile(path.resolve(process.cwd(), privateKey), 'utf8'),
-        publicKeyPem: publicKey === undefined
-            ? undefined
-            : await readFile(path.resolve(process.cwd(), publicKey), 'utf8'),
-    };
+        if (!arg.startsWith('--config='))
+            kept.push(arg);
+    }
+    return kept;
+}
+/** A plugin command's arguments and options, refusing any option it does not take. */
+function parseCommandArgs(argv, command) {
+    const args = [];
+    const options = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            args.push(arg);
+            continue;
+        }
+        const equals = arg.indexOf('=');
+        const name = equals === -1 ? arg.slice(2) : arg.slice(2, equals);
+        const inline = equals === -1 ? undefined : arg.slice(equals + 1);
+        const option = command.options?.find((entry) => entry.name === name);
+        if (option === undefined) {
+            throw new Error(`Unknown option "--${name}". Run geekity --help to see what is available.`);
+        }
+        if (option.value === undefined) {
+            if (inline !== undefined)
+                throw new Error(`--${name} takes no value.`);
+            options[name] = true;
+            continue;
+        }
+        if (inline !== undefined) {
+            if (inline === '')
+                throw new Error(`--${name} needs a value.`);
+            options[name] = inline;
+            continue;
+        }
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-'))
+            throw new Error(`--${name} needs a value.`);
+        options[name] = value;
+        i += 1;
+    }
+    return { args, options };
 }
 /**
- * What `--followers` means: a URL, a file resolved against the working
- * directory, `none`, or the plugin's own collection when it was left off.
+ * The help, with the commands the site's plugins add. A config that will not
+ * load costs the help its plugin section, not the help itself.
  */
-function followersSource(flags) {
-    const given = text(flags, 'followers');
-    if (given === undefined)
-        return undefined;
-    if (given === 'none')
-        return false;
-    return isAbsoluteHttpUrl(given) ? given : path.resolve(process.cwd(), given);
-}
-/** What the run did, as the operator reads it. */
-function importSummary(report) {
-    const lines = [];
-    const { followers } = report;
-    lines.push(report.changed
-        ? `Imported ${report.username} from ${report.actorId}`
-        : `Nothing to change: ${report.username} is already ${report.actorId}`);
-    lines.push(`  ids         ${report.identity === 'set' ? 'written to' : 'already in'} ` +
-        `data/users.json (WordPress actor ${String(report.wordpressActorId)})`);
-    for (const key of report.keys)
-        lines.push(`  key         ${key.state} ${key.file}`);
-    if (followers.source === undefined) {
-        lines.push('  followers   skipped');
-    }
-    else {
-        lines.push(`  followers   ${count(followers.added.length, 'added', 'added')}, ` +
-            `${String(followers.refreshed.length)} refreshed, ` +
-            `${String(followers.unchanged.length)} unchanged, ` +
-            `${String(followers.failed.length)} could not be fetched ` +
-            `(${followers.source})`);
-        for (const failure of followers.failed) {
-            lines.push(`    skipped   ${failure.actor}: ${failure.reason}`);
-        }
-        if (followers.failed.length > 0) {
-            lines.push('  Those followers were left out. Run this again once their servers answer; ' +
-                'nothing already imported is touched twice.');
-        }
-    }
-    return `${lines.join('\n')}\n`;
-}
-/** One flag as the text it carries, or `undefined` when it was not given. */
-function text(flags, name) {
-    const value = flags[name];
-    return typeof value === 'string' ? value : undefined;
-}
-/** Whether a value is a URL a peer could fetch. */
-function isAbsoluteHttpUrl(value) {
+async function usage(configPath) {
+    let found;
     try {
-        const url = new URL(value);
-        return url.protocol === 'http:' || url.protocol === 'https:';
+        found = await pluginCommands(resolveConfig(await loadConfig(process.cwd(), configPath)));
     }
-    catch {
-        return false;
+    catch (error) {
+        process.stderr.write(`Plugin commands are not listed: ${error instanceof Error ? error.message : String(error)}\n`);
+        return USAGE;
+    }
+    if (found.length === 0)
+        return USAGE;
+    const lines = ['', 'Plugin commands:'];
+    for (const { plugin, command } of found) {
+        const synopsis = wrap(`geekity ${[...command.words, command.usage].join(' ').trim()} [--config <file>]`, USAGE_CONTINUATION);
+        lines.push(`  ${(synopsis[0] ?? '').trimStart()}`, ...synopsis.slice(1));
+        lines.push(...wrap(command.summary, HELP_INDENT), `${HELP_INDENT}From ${plugin}.`);
+        for (const option of command.options ?? []) {
+            const flag = `--${option.name}${option.value === undefined ? '' : ` ${option.value}`}`;
+            const described = wrap(option.description, HELP_INDENT);
+            const head = `    ${flag}`;
+            if (head.length < HELP_INDENT.length - 1 && described[0] !== undefined) {
+                described[0] = `${head.padEnd(HELP_INDENT.length)}${described[0].trimStart()}`;
+                lines.push(...described);
+            }
+            else {
+                lines.push(head, ...described);
+            }
+        }
+    }
+    return `${USAGE}${lines.join('\n')}\n`;
+}
+/** Where the help's descriptions start, as the core commands' do. */
+const HELP_INDENT = ' '.repeat(19);
+/** Where a usage line carries on, as the core commands' do. */
+const USAGE_CONTINUATION = ' '.repeat(10);
+const HELP_WIDTH = 79;
+/** Text wrapped to the help's width, each line indented. */
+function wrap(text, indent) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/).filter((entry) => entry !== '')) {
+        if (line !== '' && indent.length + line.length + 1 + word.length > HELP_WIDTH) {
+            lines.push(`${indent}${line}`);
+            line = word;
+        }
+        else {
+            line = line === '' ? word : `${line} ${word}`;
+        }
     }
+    if (line !== '')
+        lines.push(`${indent}${line}`);
+    return lines;
 }
 /**
  * Ask for a password once, without putting it on the screen.