@serfab/cadre-host 0.10.0 → 0.12.0

package/src/auth/types.ts

@@ -1,99 +1,99 @@
-/**
- * Trust-circle types for cadre-host.
- *
- * The trust circle is the set of devices (peers) authorised to participate
- * in the host's cadre. Membership is stored canonically in the cadre control
- * network's `CadrePeer` table (via cadre-core). This module layers two pieces
- * of *host-local* state on top:
- *
- *   - **Labels**: human-readable names ("Mom's phone") assigned by the host
- *     admin. Display-only; loss just shows the bare peer ID.
- *   - **Pending invites**: tokens that have been issued but not yet redeemed.
- *     Operational state — lives on the issuing node, doesn't replicate.
- *
- * Both live in `<rootDir>/trust-circle.json`, written atomically.
- */
-
-/** An authorised member of the trust circle (matches a `CadrePeer` row). */
-export interface TrustCircleMember {
-  /** libp2p peer ID. */
-  peerId: string;
-  /** Display label assigned by the host admin. */
-  label: string;
-  /** ISO timestamp when the peer was added. */
-  addedAt: string;
-  /** True if this row represents the host's own cadre node (self-enrolment). */
-  self?: boolean;
-}
-
-/** An invite that has been issued but not yet redeemed. */
-export interface PendingInvite {
-  /** Random token (base64url) used to match the redemption. */
-  token: string;
-  /** Display label that will be assigned to the redeemer on success. */
-  label: string;
-  /** ISO timestamp when the invite was issued. */
-  createdAt: string;
-  /** Optional ISO expiration timestamp. */
-  expiresAt?: string;
-}
-
-/** On-disk shape of `trust-circle.json`. */
-export interface TrustCircleFile {
-  version: 1;
-  /** keyed by peer ID. */
-  members: Record<string, Omit<TrustCircleMember, 'peerId'>>;
-  /** keyed by token. */
-  pendingInvites: Record<string, Omit<PendingInvite, 'token'>>;
-}
-
-/** Snapshot returned to the management UI. */
-export interface TrustCircleSnapshot {
-  members: TrustCircleMember[];
-  pending: PendingInvite[];
-}
-
-/**
- * Typed HTTP handlers exposed to `cadre-host-local-ui` for Fastify wiring.
- *
- * Handlers take typed objects and either return typed results or throw a
- * `TrustCircleError` whose `.code` the UI ticket maps to an HTTP status:
- *
- *   - `not_found`   → 404 (unknown token / unknown peer)
- *   - `expired`     → 410 (invite past expiresAt)
- *   - `already_redeemed` → 409 (token was used and is gone)
- *   - `node_unavailable` → 503 (owner node admin channel down/not ready)
- *   - default       → 500
- */
-export interface TrustCircleHandlers {
-  postInvite(body: { label: string; ttlMs?: number }): Promise<{
-    encodedInvite: string;
-    token: string;
-    expiresAt?: string;
-  }>;
-  deleteInvite(token: string): Promise<void>;
-  deleteMember(peerId: string): Promise<void>;
-  listTrustCircle(): Promise<TrustCircleSnapshot>;
-}
-
-/** Error codes thrown by TrustCircleService. */
-export type TrustCircleErrorCode =
-  | 'not_found'
-  | 'expired'
-  | 'already_redeemed'
-  | 'invalid_label'
-  | 'invalid_token'
-  | 'storage_error'
-  /** The owner node's admin channel is unreachable / not ready. */
-  | 'node_unavailable';
-
-/** Typed error carrying a stable `code` for HTTP mapping. */
-export class TrustCircleError extends Error {
-  readonly code: TrustCircleErrorCode;
-
-  constructor(code: TrustCircleErrorCode, message: string) {
-    super(message);
-    this.name = 'TrustCircleError';
-    this.code = code;
-  }
-}
+/**
+ * Trust-circle types for cadre-host.
+ *
+ * The trust circle is the set of devices (peers) authorised to participate
+ * in the host's cadre. Membership is stored canonically in the cadre control
+ * network's `CadrePeer` table (via cadre-core). This module layers two pieces
+ * of *host-local* state on top:
+ *
+ *   - **Labels**: human-readable names ("Mom's phone") assigned by the host
+ *     admin. Display-only; loss just shows the bare peer ID.
+ *   - **Pending invites**: tokens that have been issued but not yet redeemed.
+ *     Operational state — lives on the issuing node, doesn't replicate.
+ *
+ * Both live in `<rootDir>/trust-circle.json`, written atomically.
+ */
+
+/** An authorised member of the trust circle (matches a `CadrePeer` row). */
+export interface TrustCircleMember {
+  /** libp2p peer ID. */
+  peerId: string;
+  /** Display label assigned by the host admin. */
+  label: string;
+  /** ISO timestamp when the peer was added. */
+  addedAt: string;
+  /** True if this row represents the host's own cadre node (self-enrolment). */
+  self?: boolean;
+}
+
+/** An invite that has been issued but not yet redeemed. */
+export interface PendingInvite {
+  /** Random token (base64url) used to match the redemption. */
+  token: string;
+  /** Display label that will be assigned to the redeemer on success. */
+  label: string;
+  /** ISO timestamp when the invite was issued. */
+  createdAt: string;
+  /** Optional ISO expiration timestamp. */
+  expiresAt?: string;
+}
+
+/** On-disk shape of `trust-circle.json`. */
+export interface TrustCircleFile {
+  version: 1;
+  /** keyed by peer ID. */
+  members: Record<string, Omit<TrustCircleMember, 'peerId'>>;
+  /** keyed by token. */
+  pendingInvites: Record<string, Omit<PendingInvite, 'token'>>;
+}
+
+/** Snapshot returned to the management UI. */
+export interface TrustCircleSnapshot {
+  members: TrustCircleMember[];
+  pending: PendingInvite[];
+}
+
+/**
+ * Typed HTTP handlers exposed to `cadre-host-local-ui` for Fastify wiring.
+ *
+ * Handlers take typed objects and either return typed results or throw a
+ * `TrustCircleError` whose `.code` the UI ticket maps to an HTTP status:
+ *
+ *   - `not_found`   → 404 (unknown token / unknown peer)
+ *   - `expired`     → 410 (invite past expiresAt)
+ *   - `already_redeemed` → 409 (token was used and is gone)
+ *   - `node_unavailable` → 503 (owner node admin channel down/not ready)
+ *   - default       → 500
+ */
+export interface TrustCircleHandlers {
+  postInvite(body: { label: string; ttlMs?: number }): Promise<{
+    encodedInvite: string;
+    token: string;
+    expiresAt?: string;
+  }>;
+  deleteInvite(token: string): Promise<void>;
+  deleteMember(peerId: string): Promise<void>;
+  listTrustCircle(): Promise<TrustCircleSnapshot>;
+}
+
+/** Error codes thrown by TrustCircleService. */
+export type TrustCircleErrorCode =
+  | 'not_found'
+  | 'expired'
+  | 'already_redeemed'
+  | 'invalid_label'
+  | 'invalid_token'
+  | 'storage_error'
+  /** The owner node's admin channel is unreachable / not ready. */
+  | 'node_unavailable';
+
+/** Typed error carrying a stable `code` for HTTP mapping. */
+export class TrustCircleError extends Error {
+  readonly code: TrustCircleErrorCode;
+
+  constructor(code: TrustCircleErrorCode, message: string) {
+    super(message);
+    this.name = 'TrustCircleError';
+    this.code = code;
+  }
+}

package/src/bin/__tests__/cli-reference.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Drift guard for the README's `## CLI reference` section.
+ *
+ * The section is hand-maintained prose, one `### ` heading per command, and
+ * nothing used to check it against the commander program in `../host.ts` — so
+ * the whole `cadre-host push` group shipped undocumented. This test compares
+ * the two in both directions.
+ *
+ * Scope is deliberately narrow: **presence of a heading only**. A heading's
+ * command path must name a real command, and every leaf command must have a
+ * heading. The flag list inside a heading is *not* validated — doing so would
+ * turn a wording tweak into a red build for no correctness gain.
+ *
+ * NOTE: a heading advertising a flag the CLI no longer accepts therefore slips
+ * through; if that drift is ever observed in practice, compare the bracketed
+ * tokens against `cmd.options` rather than widening the parse.
+ *
+ * NOTE: every `### ` heading inside the section must be a command reference —
+ * the malformed-heading assertion is a hard failure, not a skip. Explanatory
+ * prose belongs in the section preamble or under a different `## ` section.
+ *
+ * Importing `../host.js` is inert: its module scope only builds the commander
+ * tree and reads `package.json` for `.version()`. Nothing spawns, binds, or
+ * exits until an action fires, and `parseAsync()` is gated behind an
+ * entry-point check. The counter-guard for that gate is
+ * `src/__tests__/cli.smoke.test.ts`, which spawns `dist/bin/host.js --help` as
+ * a child process — run `yarn workspace @serfab/cadre-host build:server`
+ * before the suite so it checks the current source.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { describe, it, expect } from 'vitest';
+import type { Command } from 'commander';
+
+import { program } from '../host.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, '..', '..', '..');
+const readmePath = resolve(packageRoot, 'README.md');
+const packageJsonPath = resolve(packageRoot, 'package.json');
+
+/** Commander's implicit `help [command]` is never documented in the README. */
+const IMPLICIT_HELP = 'help';
+
+interface CommandNode {
+  /** Space-joined path below `cadre-host`, e.g. `push fcm`, `nat ddns set`. */
+  path: string;
+  /** True when the command is a *visible leaf* — no subcommands, not hidden. */
+  requiresHeading: boolean;
+}
+
+/**
+ * Walk the commander tree, collecting every command's path.
+ *
+ * `visible` tracks whether the command is reachable in `--help` output:
+ * a `.hidden()` command (or anything under one) is *allowed* a README heading
+ * but never *required* to have one, so hiding a command doesn't force a doc
+ * edit in the same commit.
+ */
+function collectCommands(cmd: Command, prefix: string[] = [], visible = true): CommandNode[] {
+  const visibleChildren = new Set(cmd.createHelp().visibleCommands(cmd));
+  const out: CommandNode[] = [];
+  for (const child of cmd.commands) {
+    if (child.name() === IMPLICIT_HELP) continue;
+    const path = [...prefix, child.name()];
+    const childVisible = visible && visibleChildren.has(child);
+    const subcommands = child.commands.filter((c) => c.name() !== IMPLICIT_HELP);
+    out.push({ path: path.join(' '), requiresHeading: subcommands.length === 0 && childVisible });
+    out.push(...collectCommands(child, path, childVisible));
+  }
+  return out;
+}
+
+interface ReadmeHeading {
+  /** The raw `### ` line, for failure messages. */
+  line: string;
+  /** Space-joined command path below `cadre-host`, or null when unparseable. */
+  path: string | null;
+}
+
+/**
+ * Slice the README between `## CLI reference` and the next `## ` heading, and
+ * return every `### ` heading found there.
+ *
+ * Throws when the section is missing rather than returning an empty list — an
+ * absent or renamed section must fail loudly, not pass vacuously.
+ */
+function readCliReferenceHeadings(): ReadmeHeading[] {
+  // Split on /\r?\n/ — this repo is developed on Windows and a bare \n split
+  // leaves a \r glued to the end of every heading.
+  const lines = readFileSync(readmePath, 'utf8').split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === '## CLI reference');
+  if (start === -1) {
+    throw new Error(`No "## CLI reference" heading in ${readmePath} — was the section renamed or removed?`);
+  }
+  // The section ends at the next `## ` heading. Anchor on `^## ` rather than a
+  // literal title: the following heading contains backticks today.
+  const rest = lines.slice(start + 1);
+  const relativeEnd = rest.findIndex((l) => /^## /.test(l));
+  const section = relativeEnd === -1 ? rest : rest.slice(0, relativeEnd);
+
+  return section.filter((l) => l.startsWith('### ')).map((line) => ({ line, path: parseHeading(line) }));
+}
+
+/**
+ * Extract the command path from a heading of the shape
+ * ``### `cadre-host <path...> [flags]` ``.
+ *
+ * Returns null when the heading doesn't match — malformed headings are
+ * reported as a failure, never silently skipped, because silent skipping is
+ * exactly how the section rots.
+ */
+function parseHeading(line: string): string | null {
+  const code = /^###\s+`([^`]+)`\s*$/.exec(line)?.[1];
+  if (!code) return null;
+  const tokens = code.trim().split(/\s+/);
+  if (tokens[0] !== 'cadre-host') return null;
+  const path: string[] = [];
+  for (const token of tokens.slice(1)) {
+    if (token.startsWith('<') || token.startsWith('[') || token.startsWith('-')) break;
+    path.push(token);
+  }
+  return path.length > 0 ? path.join(' ') : null;
+}
+
+describe('README CLI reference matches the commander tree', () => {
+  const commands = collectCommands(program);
+  const headings = readCliReferenceHeadings();
+  const documented = new Set(headings.map((h) => h.path).filter((p): p is string => p !== null));
+
+  it('has a heading for every leaf command', () => {
+    const missing = commands
+      .filter((c) => c.requiresHeading && !documented.has(c.path))
+      .map((c) => `cadre-host ${c.path}`);
+    expect(
+      missing,
+      `Commands with no "### " heading under "## CLI reference" in ${readmePath}:\n  ${missing.join('\n  ')}`,
+    ).toEqual([]);
+  });
+
+  it('has no heading for a command that does not exist', () => {
+    const known = new Set(commands.map((c) => c.path));
+    const ghosts = [...documented].filter((p) => !known.has(p)).map((p) => `cadre-host ${p}`);
+    expect(
+      ghosts,
+      `Headings under "## CLI reference" in ${readmePath} naming commands the CLI does not accept:\n  ${ghosts.join('\n  ')}`,
+    ).toEqual([]);
+  });
+
+  it('has no malformed headings in the section', () => {
+    const malformed = headings.filter((h) => h.path === null).map((h) => h.line);
+    expect(
+      malformed,
+      'Headings under "## CLI reference" must have the shape "### `cadre-host <path...> [flags]`":\n  ' +
+        malformed.join('\n  '),
+    ).toEqual([]);
+  });
+});
+
+describe('CLI version', () => {
+  it('reports the version from package.json', () => {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { version: string };
+    expect(program.version()).toBe(pkg.version);
+  });
+});