pinnace 0.0.0 → 0.2.0

package/dist/cli/run.js

@@ -0,0 +1,731 @@
+/**
+ * The CLI dispatch surface, separated from the executable shebang entry
+ * (bin.ts) so it is unit-testable without spawning a process. It is a THIN
+ * wrapper: it parses/validates args, resolves config (arg > env > file), calls
+ * the core, and formats the result. ALL behaviour lives in the core (CONTEXT.md
+ * `core vs cli`); nothing here re-implements domain logic.
+ *
+ * The client-facing verbs (provision, deploy, install-ci, status, derive) and
+ * the config/env layer dispatch through an injectable {@link RunContext} seam:
+ *  - {@link RunContext.deps} are the core functions each verb calls (defaults to
+ *    the real core; tests inject stubs to assert dispatch + resolved args),
+ *  - {@link RunContext.env} + {@link RunContext.loadConfigFile} are the env and
+ *    `pinnace.json` layers (defaults read the real `process.env` + file; tests
+ *    inject in-memory values so the operator's real environment/config is never
+ *    read or mutated — mirroring the `NodeCommandOps` injectable-ops pattern in
+ *    node-commands and the explicit-`env` resolver in config-resolution).
+ *
+ * The on-box `pinnace node <verb>` and the `pinnace site <verb>` namespaces,
+ * the `promote` verb, dispatch through the SAME {@link RunContext}/
+ * {@link ClientDeps} seam (they are NOT a forked dispatch idiom): the on-box
+ * `node` verbs assemble a {@link NodeCommandContext} from the box env
+ * (`/etc/pinnace-node.env`, exported into `process.env` by the systemd timer's
+ * `EnvironmentFile`) and call the core `runNodeCommand`; `site`/`promote`
+ * assemble a per-host {@link KuboRpcClient} from the resolved config and call
+ * the site / promote core.
+ */
+import { readFileSync } from 'node:fs';
+import { name } from '../index.js';
+import { NODE_VERBS, runNodeCommand as coreRunNodeCommand, } from '../node/node-commands.js';
+import { SITE_VERBS, listSites as coreListSites, removeSite as coreRemoveSite, addSite as coreAddSite, } from '../site/site-management.js';
+import { makeStatusOp } from '../status/status-report.js';
+import { promoteReplicaToPublisher as corePromoteReplicaToPublisher, } from '../publisher/record-sequence.js';
+import { deriveIpnsKey as coreDeriveIpnsKey, } from '../derive/ipns-key-derivation.js';
+import { KuboRpcClient } from '../rpc/kubo-rpc-client.js';
+import { provision as coreProvision, } from '../provision/cloud-init.js';
+import { deploy as coreDeploy, } from '../deploy/deploy.js';
+import { emitCi as coreEmitCi, } from '../ci/ci-emit.js';
+import { statusReport as coreStatusReport, } from '../status/status-report.js';
+import { deriveIpnsId as coreDeriveIpnsId, } from '../derive/ipns-key-derivation.js';
+import { resolveConfig, resolveMasterSecret, resolveHostToken, MissingHostTokenError, } from '../config/config-resolution.js';
+/** The real core, used when a caller does not inject stubs. */
+const DEFAULT_DEPS = {
+    provision: coreProvision,
+    deploy: coreDeploy,
+    emitCi: coreEmitCi,
+    statusReport: coreStatusReport,
+    deriveIpnsId: coreDeriveIpnsId,
+    runNodeCommand: coreRunNodeCommand,
+    listSites: coreListSites,
+    removeSite: coreRemoveSite,
+    addSite: coreAddSite,
+    deriveIpnsKey: coreDeriveIpnsKey,
+    promoteReplicaToPublisher: corePromoteReplicaToPublisher,
+};
+/**
+ * Load a config file.
+ *
+ * With NO explicit path (`--config` absent), read `./pinnace.json` if present;
+ * its ABSENCE (or an unreadable/invalid default file) stays a benign empty
+ * config, because a config file is optional.
+ *
+ * With an EXPLICIT `path` (the operator typed `--config <path>`), the file MUST
+ * exist and parse: a missing / unreadable / invalid-JSON named path THROWS
+ * (naming the path) so the caller fails loud rather than silently emptying the
+ * config — an operator who named a file has claimed it exists.
+ */
+function defaultLoadConfigFile(path) {
+    if (path === undefined) {
+        try {
+            return JSON.parse(readFileSync('pinnace.json', 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (cause) {
+        throw new ConfigLoadError(path, 'read', cause);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new ConfigLoadError(path, 'parse', cause);
+    }
+}
+/**
+ * An explicitly-named `--config <path>` could not be read or parsed. Names the
+ * path so `run()` can emit a loud, operator-actionable error (exit 1) instead
+ * of silently resolving to an empty config.
+ */
+export class ConfigLoadError extends Error {
+    path;
+    kind;
+    constructor(path, kind, cause) {
+        const detail = kind === 'read' ? 'read' : 'parse';
+        super(`failed to ${detail} config file '${path}'`, { cause });
+        this.path = path;
+        this.kind = kind;
+        this.name = 'ConfigLoadError';
+    }
+}
+/**
+ * Fill in the run context defaults (real env/file/core/console) once, loading
+ * the config from `configPath` (the operator's explicit `--config`, or
+ * `undefined` for the `./pinnace.json` default) through the loader seam.
+ */
+function resolveContext(context, configPath) {
+    return {
+        env: context.env ?? process.env,
+        file: (context.loadConfigFile ?? defaultLoadConfigFile)(configPath),
+        deps: context.deps ?? DEFAULT_DEPS,
+        out: context.out ?? ((line) => console.log(line)),
+        err: context.err ?? ((line) => console.error(line)),
+    };
+}
+/**
+ * Dispatch a pinnace CLI invocation. Returns the process exit code.
+ *
+ * Routes the client verbs (provision/deploy/install-ci/status/derive), the
+ * on-box `node` namespace, and the `site` namespace. A missing command is a
+ * benign no-op (exit 0); an UNKNOWN command is loud (exit 1) so the surface is
+ * an explicit allow-list, not a silent catch-all.
+ *
+ * A GLOBAL `--config <path>` flag may appear BEFORE the command; it is consumed
+ * here (stripped from the per-verb argv) and threaded into config loading via
+ * the {@link RunContext.loadConfigFile} seam. With no `--config`, the default
+ * `./pinnace.json` is read and its absence is benign; an explicitly-named path
+ * that is missing/unreadable/invalid JSON fails loud (names the path, exit 1).
+ */
+export async function run(argv, context = {}) {
+    const { configPath, rest: postGlobal } = takeConfigFlag(argv);
+    const err = context.err ?? ((line) => console.error(line));
+    let rc;
+    try {
+        rc = resolveContext(context, configPath);
+    }
+    catch (cause) {
+        // A loud, path-named failure only ever comes from an EXPLICIT --config;
+        // the default loader swallows an absent ./pinnace.json into an empty config.
+        if (cause instanceof ConfigLoadError) {
+            err(`${name()}: ${cause.message}`);
+            return 1;
+        }
+        throw cause;
+    }
+    const [command, ...rest] = postGlobal;
+    if (command === undefined) {
+        rc.out(`${name()}: no command given`);
+        return 0;
+    }
+    if (command === 'version' || command === '--version' || command === '-v') {
+        rc.out(name());
+        return 0;
+    }
+    if (command === 'node') {
+        return runNodeCli(rest, rc);
+    }
+    if (command === 'site') {
+        return runSiteCli(rest, rc);
+    }
+    if (command === 'provision') {
+        return runProvision(rest, rc);
+    }
+    if (command === 'deploy') {
+        return runDeploy(rest, rc);
+    }
+    if (command === 'install-ci') {
+        return runInstallCi(rest, rc);
+    }
+    if (command === 'status') {
+        return runStatus(rest, rc);
+    }
+    if (command === 'derive' || command === 'ipns-id') {
+        return runDerive(rest, rc);
+    }
+    if (command === 'promote') {
+        return runPromote(rest, rc);
+    }
+    rc.err(`${name()}: unknown command '${command}'`);
+    return 1;
+}
+// ---------------------------------------------------------------------------
+// Minimal arg parsing (flags + positionals). Kept tiny + local: the CLI is a
+// parse/format layer, so a full arg-parsing dependency would be over-weight.
+// ---------------------------------------------------------------------------
+/**
+ * Split the GLOBAL `--config <path>` flag off the front of the argv.
+ *
+ * `--config` is a global (not a per-verb) flag: it may precede the command and
+ * MUST be stripped before the argv reaches a verb parser, or a per-verb parser
+ * would mis-read `--config`/its path as one of its own flags/positionals. This
+ * scans the WHOLE argv (so `--config` before the command is found) and removes
+ * the flag and its value, returning the chosen path (`undefined` if absent).
+ * Only the last `--config` wins if repeated. A trailing `--config` with no
+ * value yields an empty path, which the loader then fails loud on.
+ */
+function takeConfigFlag(argv) {
+    const rest = [];
+    let configPath;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--config') {
+            const next = argv[i + 1];
+            configPath = next !== undefined && !next.startsWith('--') ? next : '';
+            if (next !== undefined && !next.startsWith('--'))
+                i++;
+            continue;
+        }
+        rest.push(argv[i]);
+    }
+    return { configPath, rest };
+}
+/**
+ * Parse `--flag value` pairs and positionals. Flags are long-form only
+ * (`--host hetzner`); a `--flag` at the end with no value is treated as `''`.
+ * Positionals are everything that is not a flag or a flag value.
+ */
+function parseArgs(argv) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith('--')) {
+            const key = token.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = '';
+            }
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { flags, positionals };
+}
+// ---------------------------------------------------------------------------
+// Client verbs — each: parse/validate -> resolve config -> call core -> format.
+// ---------------------------------------------------------------------------
+/**
+ * `provision --host <h> --api-domain <d> --acme-email <e> --bearer-token <t>
+ * --role <r> [--pinnace-version <v>] [--node-major <n>] [--kubo-version <v>]
+ * [...]` -> core {@link ClientDeps.provision}. Purely arg-driven (provisioning
+ * inputs are per-box and not stored in `pinnace.json`); prints the generated
+ * cloud-init to stdout. The pinned pinnace/Node/Kubo versions default to the
+ * generator's named knobs and are overridable per-box via these flags.
+ */
+function runProvision(argv, rc) {
+    const { flags } = parseArgs(argv);
+    const host = flags['host'];
+    const apiDomain = flags['api-domain'];
+    const acmeEmail = flags['acme-email'];
+    const bearerToken = flags['bearer-token'];
+    const role = flags['role'];
+    const missing = missingFlags({
+        host,
+        'api-domain': apiDomain,
+        'acme-email': acmeEmail,
+        'bearer-token': bearerToken,
+        role,
+    });
+    if (missing.length > 0) {
+        rc.err(`pinnace provision: missing required flag(s): ${missing.join(', ')}`);
+        return 1;
+    }
+    if (role !== 'publisher' && role !== 'replica') {
+        rc.err(`pinnace provision: --role must be 'publisher' or 'replica'`);
+        return 1;
+    }
+    const input = {
+        host: host,
+        apiDomain,
+        acmeEmail,
+        bearerToken,
+        role: role,
+    };
+    if (flags['dashboard-domain'])
+        input.dashboardDomain = flags['dashboard-domain'];
+    if (flags['publisher-endpoint'])
+        input.publisherEndpoint = flags['publisher-endpoint'];
+    if (flags['kubo-version'])
+        input.kuboVersion = flags['kubo-version'];
+    if (flags['pinnace-version'])
+        input.pinnaceVersion = flags['pinnace-version'];
+    if (flags['node-major'])
+        input.nodeMajor = flags['node-major'];
+    const result = rc.deps.provision(input);
+    rc.out(result.cloudInit.contents);
+    return 0;
+}
+/**
+ * `deploy [--mode <m>] <dir> <id>` -> core {@link ClientDeps.deploy}. Resolves
+ * every configured host into a {@link DeployTarget} (each host's OWN token
+ * resolved env-only, LAZILY, via {@link resolveHostToken} — CLI > env, no file),
+ * and the site's `mode` from the matching `pinnace.json` site entry (overridable
+ * with `--mode`). A host with no resolvable token FAILS LOUD naming its exact
+ * env var. Prints the resulting CID / per-node breakdown.
+ */
+async function runDeploy(argv, rc) {
+    const { flags, positionals } = parseArgs(argv);
+    const [dir, siteId] = positionals;
+    if (!dir || !siteId) {
+        rc.err('pinnace deploy: usage: pinnace deploy [--mode ipfs|ipns] <dir> <id>');
+        return 1;
+    }
+    const cli = cliOverridesFromFlags(flags);
+    const cfg = resolveConfig({ file: rc.file, env: rc.env, cli });
+    // The site's mode: --mode arg > matching site entry (config precedence).
+    const siteEntry = cfg.sites.find((s) => s.id === siteId);
+    const mode = flags['mode'] ?? siteEntry?.mode;
+    if (mode !== 'ipfs' && mode !== 'ipns') {
+        rc.err(`pinnace deploy: mode for '${siteId}' is unset or invalid; pass --mode ipfs|ipns or add the site to pinnace.json`);
+        return 1;
+    }
+    if (cfg.hosts.length === 0) {
+        rc.err('pinnace deploy: no hosts configured (add hosts to pinnace.json)');
+        return 1;
+    }
+    // Resolve each host's token env-only (LAZY: only the hosts this deploy uses).
+    // A missing token is a loud named error, never a silent "" / downstream 401.
+    let targets;
+    try {
+        targets = cfg.hosts.map((h) => ({
+            baseUrl: h.endpoint,
+            token: resolveHostToken({ hostName: h.name, env: rc.env, cli }),
+            role: h.role,
+        }));
+    }
+    catch (error) {
+        if (error instanceof MissingHostTokenError) {
+            rc.err(`pinnace deploy: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    const input = { sourceDir: dir, id: siteId, mode, targets };
+    const result = await rc.deps.deploy(input);
+    rc.out(`cid: ${result.cid}`);
+    for (const ok of result.ok) {
+        rc.out(`  ok  ${ok.baseUrl}${ok.published && ok.ipns ? ` (ipns ${ok.ipns})` : ''}`);
+    }
+    for (const failure of result.failed) {
+        rc.err(`  FAIL ${failure.baseUrl}: ${failure.error.message}`);
+    }
+    return result.success ? 0 : 1;
+}
+/**
+ * `install-ci --system <s> --build-command <c> --output-dir <d> [--branch <b>]
+ * [--node-version <v>]` -> core {@link ClientDeps.emitCi}. Prints the workflow
+ * path/contents and reports the secrets/vars the operator must set.
+ */
+function runInstallCi(argv, rc) {
+    const { flags } = parseArgs(argv);
+    const system = flags['system'];
+    const buildCommand = flags['build-command'];
+    const outputDir = flags['output-dir'];
+    const missing = missingFlags({
+        system,
+        'build-command': buildCommand,
+        'output-dir': outputDir,
+    });
+    if (missing.length > 0) {
+        rc.err(`pinnace install-ci: missing required flag(s): ${missing.join(', ')}`);
+        return 1;
+    }
+    const input = {
+        system: system,
+        buildCommand,
+        outputDir,
+    };
+    if (flags['branch'])
+        input.branch = flags['branch'];
+    if (flags['node-version'])
+        input.nodeVersion = flags['node-version'];
+    const emitted = rc.deps.emitCi(input);
+    rc.out(`workflow: ${emitted.workflow.path}`);
+    rc.out(emitted.workflow.contents);
+    if (emitted.secrets.length > 0) {
+        rc.out('Required secrets (Settings -> Secrets):');
+        for (const s of emitted.secrets)
+            rc.out(`  ${s.name} — ${s.description}`);
+    }
+    if (emitted.vars.length > 0) {
+        rc.out('Required variables (Settings -> Variables):');
+        for (const v of emitted.vars)
+            rc.out(`  ${v.name} — ${v.description}`);
+    }
+    return 0;
+}
+/**
+ * `status` -> core {@link ClientDeps.statusReport}, once per configured host
+ * (each node reports its OWN sites). Builds each node's Kubo client from the
+ * resolved endpoint + token and prints the per-site report.
+ */
+async function runStatus(argv, rc) {
+    const { flags } = parseArgs(argv);
+    const cli = cliOverridesFromFlags(flags);
+    const cfg = resolveConfig({ file: rc.file, env: rc.env, cli });
+    if (cfg.hosts.length === 0) {
+        rc.err('pinnace status: no hosts configured (add hosts to pinnace.json)');
+        return 1;
+    }
+    for (const host of cfg.hosts) {
+        let token;
+        try {
+            // Env-only token, resolved LAZILY per host actually used (see deploy).
+            token = resolveHostToken({ hostName: host.name, env: rc.env, cli });
+        }
+        catch (error) {
+            if (error instanceof MissingHostTokenError) {
+                rc.err(`pinnace status: ${error.message}`);
+                return 1;
+            }
+            throw error;
+        }
+        const client = new KuboRpcClient({ baseUrl: host.endpoint, token });
+        const report = await rc.deps.statusReport({ client });
+        rc.out(`${host.name} (${host.endpoint}) peer ${report.peerId}`);
+        for (const site of report.sites) {
+            rc.out(`  ${site.id}: cid ${site.cid}${site.ipns ? ` ipns ${site.ipns}` : ''} announced=${site.announced} gatewayServes=${site.gatewayServes}`);
+        }
+    }
+    return 0;
+}
+/**
+ * `derive <id>` (a.k.a. `ipns-id`) -> core {@link ClientDeps.deriveIpnsId}.
+ * Prints the site's `k51...` IPNS id from the master + the site's single `id`
+ * (the KDF input), with NO deploy (user story 22). The master is env-ONLY (via
+ * {@link resolveMasterSecret}); the `id` is either the positional argument
+ * verbatim or, if it names a `pinnace.json` site entry, that entry's `id` (they
+ * are the same value — one identifier). Fails loudly if the master is unset.
+ */
+function runDerive(argv, rc) {
+    const { positionals } = parseArgs(argv);
+    const [siteId] = positionals;
+    if (!siteId) {
+        rc.err('pinnace derive: usage: pinnace derive <id>');
+        return 1;
+    }
+    const master = resolveMasterSecret({ env: rc.env });
+    if (!master) {
+        rc.err('pinnace derive: master secret not set — export PINNACE_MASTER (env-only; never read from pinnace.json)');
+        return 1;
+    }
+    // The single `id` IS the KDF input. The positional is the id directly; a
+    // matching site entry carries the same value (no separate keyId to look up).
+    const cfg = resolveConfig({ file: rc.file, env: rc.env, cli: {} });
+    const id = cfg.sites.find((s) => s.id === siteId)?.id ?? siteId;
+    const printed = rc.deps.deriveIpnsId({ master, keyId: id });
+    rc.out(printed);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Shared helpers.
+// ---------------------------------------------------------------------------
+/** Return the keys whose value is falsy (missing required flags), in order. */
+function missingFlags(required) {
+    return Object.entries(required)
+        .filter(([, value]) => !value)
+        .map(([key]) => `--${key}`);
+}
+/**
+ * Build the {@link CliOverrides} the config resolver understands from parsed
+ * flags. `--gateways a,b` overrides the gateway list; per-host token/endpoint
+ * overrides use the `--host-token.<name>` / `--host-endpoint.<name>` form.
+ */
+function cliOverridesFromFlags(flags) {
+    const cli = {};
+    const hostToken = {};
+    const hostEndpoint = {};
+    for (const [key, value] of Object.entries(flags)) {
+        if (key.startsWith('host-token.'))
+            hostToken[key.slice('host-token.'.length)] = value;
+        else if (key.startsWith('host-endpoint.'))
+            hostEndpoint[key.slice('host-endpoint.'.length)] = value;
+    }
+    if (Object.keys(hostToken).length > 0)
+        cli.hostToken = hostToken;
+    if (Object.keys(hostEndpoint).length > 0)
+        cli.hostEndpoint = hostEndpoint;
+    if (flags['gateways'])
+        cli.gateways = flags['gateways']
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    return cli;
+}
+/**
+ * `pinnace site <verb> [args] [--host <name>]` -> the site core
+ * ({@link ClientDeps.listSites}/{@link ClientDeps.removeSite}/
+ * {@link ClientDeps.addSite}). Assembles a per-host {@link KuboRpcClient} from
+ * the resolved config (endpoint) + the host's env-only token, then dispatches:
+ *   - `list`            -> listSites({client})
+ *   - `remove <id>`     -> removeSite({client, id})
+ *   - `add <id> <cid>`  -> addSite({client, id, cid})
+ * The `--host <name>` selects which configured node to act on; it may be
+ * omitted only when the config has exactly one host (see {@link selectHost}).
+ */
+async function runSiteCli(argv, rc) {
+    const { flags, positionals } = parseArgs(argv);
+    const [verb, ...verbArgs] = positionals;
+    if (!verb) {
+        rc.err(`pinnace site: expected a verb (${SITE_VERBS.join(', ')})`);
+        return 1;
+    }
+    if (!SITE_VERBS.includes(verb)) {
+        rc.err(`pinnace site: unknown verb '${verb}'; expected one of ${SITE_VERBS.join(', ')}`);
+        return 1;
+    }
+    const cli = cliOverridesFromFlags(flags);
+    const cfg = resolveConfig({ file: rc.file, env: rc.env, cli });
+    const client = buildHostClient('pinnace site', flags['host'], cfg, rc, cli);
+    if (!client)
+        return 1; // buildHostClient already emitted the loud error.
+    if (verb === 'list') {
+        const sites = await rc.deps.listSites({ client });
+        for (const site of sites) {
+            rc.out(`${site.id}: cid ${site.cid}${site.ipns ? ` ipns ${site.ipns}` : ''}`);
+        }
+        return 0;
+    }
+    if (verb === 'remove') {
+        const [id] = verbArgs;
+        if (!id) {
+            rc.err('pinnace site remove: usage: pinnace site remove <id> [--host <name>]');
+            return 1;
+        }
+        const result = await rc.deps.removeSite({ client, id });
+        rc.out(`removed ${result.id}${result.cid ? ` (cid ${result.cid}, unpinned=${result.unpinned})` : ''}`);
+        return 0;
+    }
+    // verb === 'add'
+    const [id, cid] = verbArgs;
+    if (!id || !cid) {
+        rc.err('pinnace site add: usage: pinnace site add <id> <cid> [--host <name>]');
+        return 1;
+    }
+    const result = await rc.deps.addSite({ client, id, cid });
+    rc.out(`added ${result.id} -> ${result.cid}`);
+    return 0;
+}
+/**
+ * `pinnace node <verb>` -> the on-box command core ({@link
+ * ClientDeps.runNodeCommand}). This is the load-bearing on-box wiring: the verb
+ * runs ON a provisioned box (invoked by the systemd timer, whose
+ * `EnvironmentFile=/etc/pinnace-node.env` exports the box config into the
+ * environment {@link RunContext.env} reads). It assembles a
+ * {@link NodeCommandContext} from that env — a LOCAL Kubo client (127.0.0.1:5001
+ * + `RPC_BEARER_TOKEN`), the box `role` (`NODE_ROLE`), and the on-box paths
+ * (`RECORDS_DIR`/`CACHE_DIR`/`DASHBOARD_DIR`/`SITES_DIR`), the replica
+ * `PUBLISHER_ENDPOINT`, and the `WARM_GATEWAYS` list — and injects the OWNED
+ * `status` op ({@link makeStatusOp}, the real per-site announce/gateway report)
+ * so the production status path is not the thin default stub. It then invokes
+ * the core (NOT a validate-and-return-0). A live run proved that without this
+ * the `republish`/`mirror` timers are no-ops. The token is env-only and its
+ * absence is a LOUD, named error (never a silent empty bearer / 401).
+ */
+async function runNodeCli(argv, rc) {
+    const [verb] = argv;
+    if (!verb) {
+        rc.err(`pinnace node: expected a verb (${NODE_VERBS.join(', ')})`);
+        return 1;
+    }
+    if (!NODE_VERBS.includes(verb)) {
+        rc.err(`pinnace node: unknown verb '${verb}'; expected one of ${NODE_VERBS.join(', ')}`);
+        return 1;
+    }
+    const env = rc.env;
+    const token = env['RPC_BEARER_TOKEN'];
+    if (!token) {
+        rc.err('pinnace node: RPC_BEARER_TOKEN not set — the on-box bearer is env-only ' +
+            '(read from /etc/pinnace-node.env); never a silent empty token');
+        return 1;
+    }
+    const role = env['NODE_ROLE'];
+    if (role !== 'publisher' && role !== 'replica') {
+        rc.err("pinnace node: NODE_ROLE must be 'publisher' or 'replica' " +
+            '(read from /etc/pinnace-node.env)');
+        return 1;
+    }
+    // The box's OWN daemon: the local Kubo RPC on 127.0.0.1:5001 (Caddy fronts it
+    // for external clients, but the on-box agent speaks to it directly).
+    const client = new KuboRpcClient({
+        baseUrl: 'http://127.0.0.1:5001',
+        token,
+    });
+    const ctx = {
+        client,
+        role,
+        // The production status path uses the OWNED status op (real announce +
+        // gateway report), not the thin defaultStatus stand-in.
+        ops: { status: makeStatusOp() },
+    };
+    if (env['SITES_DIR'])
+        ctx.sitesDir = env['SITES_DIR'];
+    if (env['RECORDS_DIR'])
+        ctx.recordsDir = env['RECORDS_DIR'];
+    if (env['CACHE_DIR'])
+        ctx.cacheDir = env['CACHE_DIR'];
+    if (env['DASHBOARD_DIR'])
+        ctx.dashboardDir = env['DASHBOARD_DIR'];
+    if (env['PUBLISHER_ENDPOINT'])
+        ctx.publisherEndpoint = env['PUBLISHER_ENDPOINT'];
+    const gateways = splitWarmGateways(env['WARM_GATEWAYS']);
+    if (gateways.length > 0)
+        ctx.gateways = gateways;
+    const result = await rc.deps.runNodeCommand(verb, ctx);
+    if (result.skipped) {
+        rc.out(`pinnace node ${verb}: skipped (${result.skippedReason})`);
+        return 0;
+    }
+    for (const site of result.sites) {
+        rc.out(`  ${site.id}${site.cid ? ` cid ${site.cid}` : ''}${site.status ? ` (${site.status})` : ''}`);
+    }
+    return 0;
+}
+/**
+ * `pinnace promote <id> [--host <name>]` -> {@link
+ * ClientDeps.promoteReplicaToPublisher} (spec user story 14). Derives the
+ * per-site key from the env-only master + the site `id` (the KDF input,
+ * {@link ClientDeps.deriveIpnsKey}), assembles the chosen host's client, and
+ * promotes it: import the key + flip the role to publisher, recovering the name
+ * within the record's validity window without content downtime. The master is
+ * env-ONLY (never from `pinnace.json`); its absence is a LOUD error.
+ */
+async function runPromote(argv, rc) {
+    const { flags, positionals } = parseArgs(argv);
+    const [siteId] = positionals;
+    if (!siteId) {
+        rc.err('pinnace promote: usage: pinnace promote <id> [--host <name>]');
+        return 1;
+    }
+    const master = resolveMasterSecret({ env: rc.env });
+    if (!master) {
+        rc.err('pinnace promote: master secret not set — export PINNACE_MASTER (env-only; never read from pinnace.json)');
+        return 1;
+    }
+    const cli = cliOverridesFromFlags(flags);
+    const cfg = resolveConfig({ file: rc.file, env: rc.env, cli });
+    const host = pickHost('pinnace promote', flags['host'], cfg, rc);
+    if (!host)
+        return 1;
+    const client = clientForHost('pinnace promote', host, rc, cli);
+    if (!client)
+        return 1;
+    // The single `id` IS the KDF input (no separate keyId), matching `derive`.
+    const id = cfg.sites.find((s) => s.id === siteId)?.id ?? siteId;
+    const derived = rc.deps.deriveIpnsKey({ master, keyId: id });
+    const result = await rc.deps.promoteReplicaToPublisher({
+        client,
+        currentRole: host.role,
+        keyName: id,
+        derived,
+    });
+    rc.out(`promoted ${result.keyName} to ${result.role}${result.ipns ? ` (ipns ${result.ipns})` : ''}`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Host selection + client assembly (shared by site + promote).
+// ---------------------------------------------------------------------------
+/**
+ * Pick the configured host to act on. `--host <name>` selects it by name; it
+ * may be omitted ONLY when the config has exactly one host (the unambiguous
+ * case). Zero hosts, an unknown name, or an omitted name with several hosts is
+ * a LOUD, specific error (returns undefined after emitting it).
+ */
+function pickHost(prefix, hostName, cfg, rc) {
+    if (cfg.hosts.length === 0) {
+        rc.err(`${prefix}: no hosts configured (add hosts to pinnace.json)`);
+        return undefined;
+    }
+    if (hostName) {
+        const match = cfg.hosts.find((h) => h.name === hostName);
+        if (!match) {
+            rc.err(`${prefix}: unknown host '${hostName}'; configured hosts: ${cfg.hosts
+                .map((h) => h.name)
+                .join(', ')}`);
+            return undefined;
+        }
+        return match;
+    }
+    if (cfg.hosts.length > 1) {
+        rc.err(`${prefix}: multiple hosts configured; pass --host <name> (one of ${cfg.hosts
+            .map((h) => h.name)
+            .join(', ')})`);
+        return undefined;
+    }
+    return cfg.hosts[0];
+}
+/**
+ * Build a {@link KuboRpcClient} for a chosen host, resolving its bearer token
+ * env-only (CLI > env, no file). A missing token is a LOUD, named error
+ * (returns undefined after emitting it).
+ */
+function clientForHost(prefix, host, rc, cli) {
+    let token;
+    try {
+        token = resolveHostToken({ hostName: host.name, env: rc.env, cli });
+    }
+    catch (error) {
+        if (error instanceof MissingHostTokenError) {
+            rc.err(`${prefix}: ${error.message}`);
+            return undefined;
+        }
+        throw error;
+    }
+    return new KuboRpcClient({ baseUrl: host.endpoint, token });
+}
+/** Pick a host AND build its client in one step (the common site path). */
+function buildHostClient(prefix, hostName, cfg, rc, cli) {
+    const host = pickHost(prefix, hostName, cfg, rc);
+    if (!host)
+        return undefined;
+    return clientForHost(prefix, host, rc, cli);
+}
+/** Split the space-separated `WARM_GATEWAYS` env value into a template list. */
+function splitWarmGateways(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/\s+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+//# sourceMappingURL=run.js.map