pinnace 0.1.0 → 0.3.0

package/src/cli/run.ts

@@ -15,14 +15,48 @@
  *    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 are
- * validated here for surface coherence (one CLI), but their full dispatch is
- * wired by their own tasks (node-agent-commands, site-management).
+ * 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, type NodeVerb} from '../node/node-commands.js';
-import {SITE_VERBS, type SiteVerb} from '../site/site-management.js';
+import {
+	NODE_VERBS,
+	runNodeCommand as coreRunNodeCommand,
+	type NodeVerb,
+	type NodeCommandContext,
+	type NodeCommandResult,
+} from '../node/node-commands.js';
+import {
+	SITE_VERBS,
+	listSites as coreListSites,
+	removeSite as coreRemoveSite,
+	addSite as coreAddSite,
+	type SiteVerb,
+	type ListSitesInput,
+	type SiteListing,
+	type RemoveSiteInput,
+	type RemoveSiteResult,
+	type AddSiteInput,
+	type AddSiteResult,
+} from '../site/site-management.js';
+import {makeStatusOp} from '../status/status-report.js';
+import {
+	promoteReplicaToPublisher as corePromoteReplicaToPublisher,
+	type PromoteReplicaInput,
+	type PromoteReplicaResult,
+} from '../publisher/record-sequence.js';
+import {
+	deriveIpnsKey as coreDeriveIpnsKey,
+	type DeriveIpnsInput as DeriveIpnsKeyInput,
+	type DerivedIpnsKey,
+} from '../derive/ipns-key-derivation.js';
 import {KuboRpcClient} from '../rpc/kubo-rpc-client.js';
 import {
 	provision as coreProvision,
@@ -81,6 +115,23 @@ export interface ClientDeps {
 	statusReport(input: StatusReportInput): Promise<StatusReport>;
 	/** `derive` -> the master + site `id` -> IPNS id derivation (no deploy). */
 	deriveIpnsId(input: DeriveIpnsInput): string;
+	/** `node <verb>` -> the on-box command runner (context assembled by the CLI). */
+	runNodeCommand(
+		verb: NodeVerb,
+		ctx: NodeCommandContext,
+	): Promise<NodeCommandResult>;
+	/** `site list` -> enumerate the node's MFS sites. */
+	listSites(input: ListSitesInput): Promise<SiteListing[]>;
+	/** `site remove` -> drop an MFS site + unpin its content. */
+	removeSite(input: RemoveSiteInput): Promise<RemoveSiteResult>;
+	/** `site add` -> place an already-imported CID into MFS as a site. */
+	addSite(input: AddSiteInput): Promise<AddSiteResult>;
+	/** `promote` -> derive the per-site key material from the master + `id`. */
+	deriveIpnsKey(input: DeriveIpnsKeyInput): DerivedIpnsKey;
+	/** `promote` -> import the key + flip the node's role to publisher (story 14). */
+	promoteReplicaToPublisher(
+		input: PromoteReplicaInput,
+	): Promise<PromoteReplicaResult>;
 }
 
 /** The real core, used when a caller does not inject stubs. */
@@ -90,6 +141,12 @@ const DEFAULT_DEPS: ClientDeps = {
 	emitCi: coreEmitCi,
 	statusReport: coreStatusReport,
 	deriveIpnsId: coreDeriveIpnsId,
+	runNodeCommand: coreRunNodeCommand,
+	listSites: coreListSites,
+	removeSite: coreRemoveSite,
+	addSite: coreAddSite,
+	deriveIpnsKey: coreDeriveIpnsKey,
+	promoteReplicaToPublisher: corePromoteReplicaToPublisher,
 };
 
 /**
@@ -263,6 +320,9 @@ export async function run(
 	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;
@@ -340,9 +400,11 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
 
 /**
  * `provision --host <h> --api-domain <d> --acme-email <e> --bearer-token <t>
- * --role <r> [...]` -> 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.
+ * --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: readonly string[], rc: ResolvedRunContext): number {
 	const {flags} = parseArgs(argv);
@@ -380,6 +442,9 @@ function runProvision(argv: readonly string[], rc: ResolvedRunContext): number {
 		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);
@@ -611,14 +676,22 @@ function cliOverridesFromFlags(flags: Record<string, string>): CliOverrides {
 }
 
 /**
- * Parse `pinnace site <verb>` and validate the verb. The full context (Kubo
- * client from config-resolution, the site name / CID args) is assembled by the
- * CLI wiring in the site-management task; this thin router validates the verb
- * belongs to the `site` namespace. The three verbs (list/remove/add) are
- * implemented in `../site/site-management.ts`.
+ * `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}).
  */
-function runSiteCli(argv: readonly string[], rc: ResolvedRunContext): number {
-	const [verb] = argv;
+async function runSiteCli(
+	argv: readonly string[],
+	rc: ResolvedRunContext,
+): Promise<number> {
+	const {flags, positionals} = parseArgs(argv);
+	const [verb, ...verbArgs] = positionals;
 	if (!verb) {
 		rc.err(`pinnace site: expected a verb (${SITE_VERBS.join(', ')})`);
 		return 1;
@@ -629,16 +702,68 @@ function runSiteCli(argv: readonly string[], rc: ResolvedRunContext): number {
 		);
 		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;
 }
 
 /**
- * Parse `pinnace node <verb>` and validate the verb. The full on-box context
- * (local Kubo client, role, on-box paths) is assembled by the cloud-init /
- * config-resolution wiring in the node-agent-commands task; this thin router
- * only validates the verb belongs to the `node` namespace.
+ * `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).
  */
-function runNodeCli(argv: readonly string[], rc: ResolvedRunContext): number {
+async function runNodeCli(
+	argv: readonly string[],
+	rc: ResolvedRunContext,
+): Promise<number> {
 	const [verb] = argv;
 	if (!verb) {
 		rc.err(`pinnace node: expected a verb (${NODE_VERBS.join(', ')})`);
@@ -650,5 +775,196 @@ function runNodeCli(argv: readonly string[], rc: ResolvedRunContext): number {
 		);
 		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: NodeCommandContext = {
+		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 as NodeVerb, 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: readonly string[],
+	rc: ResolvedRunContext,
+): Promise<number> {
+	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: string,
+	hostName: string | undefined,
+	cfg: {hosts: Array<{name: string; endpoint: string; role: HostRole}>},
+	rc: ResolvedRunContext,
+): {name: string; endpoint: string; role: HostRole} | undefined {
+	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: string,
+	host: {name: string; endpoint: string},
+	rc: ResolvedRunContext,
+	cli: CliOverrides,
+): KuboRpcClient | undefined {
+	let token: string;
+	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: string,
+	hostName: string | undefined,
+	cfg: {hosts: Array<{name: string; endpoint: string; role: HostRole}>},
+	rc: ResolvedRunContext,
+	cli: CliOverrides,
+): KuboRpcClient | undefined {
+	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: string | undefined): string[] {
+	if (!value) return [];
+	return value
+		.split(/\s+/)
+		.map((s) => s.trim())
+		.filter(Boolean);
+}

package/src/cli/startup.ts

@@ -0,0 +1,59 @@
+/**
+ * The `pinnace` CLI STARTUP shim: the thin process-entry glue that runs BEFORE
+ * the pure {@link run} dispatch. Its whole job is to make the env-only secrets
+ * model (CONTEXT.md `master key` / `token`) ergonomic for EVERY user, including
+ * a global `npm install -g pinnace`, by loading `.env` / `.env.local` from the
+ * cwd into `process.env` at startup, so no `pnpm ldenv` dev wrapper is needed.
+ *
+ * WHY a shim (and not inside {@link run}): `run(argv, {env})` is pure and
+ * hermetically unit-tested with an INJECTED `env` record; it must never read a
+ * real `.env` / touch a real cwd. So the ONE impure, filesystem-touching step
+ * (`ldenv`'s {@link loadEnv}) lives HERE, in the bin/startup layer, in front of
+ * `run()`. Config resolution + {@link resolveMasterSecret} read `process.env`,
+ * so `loadEnv()` must have mutated it BEFORE `run()` runs.
+ *
+ * PRECEDENCE (preserved, not changed). `loadEnv()` reads `.env` then
+ * `.env.local` (local overriding default) and MUTATES `process.env`, but it
+ * does NOT override a value ALREADY set in `process.env`. So dotenv slots in
+ * BELOW an explicitly-exported env var and ABOVE `pinnace.json`, keeping the
+ * documented "env > file" rule intact. The effective chain becomes:
+ * **CLI arg > exported `process.env` > `.env.local` > `.env` > `pinnace.json`**.
+ * The master + host tokens stay env-only: `.env.local` is merely a FILE SOURCE
+ * for those env vars, never a `pinnace.json` field.
+ *
+ * The `loadEnv` call is injected (defaulting to the real `ldenv` one) purely so
+ * the shim is unit-testable; production always uses the real `ldenv.loadEnv`,
+ * which is cwd-based only (never a global/home location), silent, and only
+ * AUGMENTS env — an already-exported value is left untouched.
+ */
+import {loadEnv} from 'ldenv';
+import {run} from './run.js';
+
+/** Injectable seams for the startup shim (defaulted to the real ones). */
+export interface StartupOptions {
+	/**
+	 * Load `.env` / `.env.local` from the cwd into `process.env`. Defaults to
+	 * `ldenv`'s `loadEnv` (reads `.env` then `.env.local`, local overriding,
+	 * never overriding an already-exported value). Injected only for tests.
+	 */
+	loadDotEnv?: () => void;
+}
+
+/**
+ * The CLI startup entry: load the cwd's `.env` / `.env.local` into
+ * `process.env` (so a global install gets the env-only secrets), THEN dispatch
+ * `run()` over the process argv. Returns the process exit code.
+ *
+ * This is what the `pinnace` bin calls. It keeps the `loadEnv()` side effect
+ * out of the pure `run()` path so `run(argv, {env})` stays hermetic.
+ */
+export async function main(
+	argv: readonly string[] = process.argv.slice(2),
+	options: StartupOptions = {},
+): Promise<number> {
+	const loadDotEnv = options.loadDotEnv ?? (() => void loadEnv());
+	// Load the cwd's dotenv files BEFORE run() reads process.env. This only
+	// augments process.env; an already-exported value still wins.
+	loadDotEnv();
+	return run(argv);
+}

package/src/node/node-commands.ts

@@ -313,11 +313,15 @@ async function defaultWarm(
 }
 
 /**
- * Default `status`. Reuses the `status-report` core logic (injected via
- * {@link NodeCommandContext.ops}.status; this default is a thin stand-in until
- * that task lands) and writes the resulting report as `status.json` under the
- * box's dashboard directory ONLY. Reporting per-site CID / IPNS id happens in
- * the reused core; this wrapper just persists it where the dashboard reads.
+ * Default `status` — a thin stand-in used ONLY when no `status` op is injected.
+ * The PRODUCTION on-box path (`pinnace node status`, wired in cli/run.ts's
+ * `runNodeCli`) injects the OWNED `status` op ({@link makeStatusOp} from
+ * status-report) via {@link NodeCommandContext.ops}.status, which is the real
+ * per-site CID/IPNS/announce/gateway report. This default remains as the
+ * seam's safe fallback (e.g. a direct `runNodeCommand` call that does not want
+ * the live external checks / a hermetic test that injects its own op), so a
+ * bare call still reports current CID + IPNS id without reaching the network.
+ * The dashboard write is done by the command layer ({@link runNodeCommand}).
  */
 async function defaultStatus(
 	ctx: NodeCommandContext,