@celilo/cli 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1109.0",
     "@aws-sdk/lib-storage": "^3.1101.0",
-    "@celilo/capabilities": "^2.1.0",
+    "@celilo/capabilities": "^2.2.0",
     "@celilo/cli-display": "^0.2.0",
     "@celilo/core": "^0.9.0",
     "@celilo/event-bus": "^0.6.0",

package/src/hooks/types.ts

@@ -6,70 +6,22 @@
  * (e.g., container_created triggers web automation for API key creation).
  */
 
-import type { DeployedSystem } from '@celilo/capabilities';
+import type { HookDefinition, HookResult as ModuleHookResult } from '@celilo/capabilities';
 
 /**
- * Hook definition from module manifest.
+ * `HookDefinition`, `HookLogger` and `HookContext` are re-exported from
+ * `@celilo/capabilities`, which owns them. All three were declared a second
+ * time here and the `HookLogger` copy said so in its own comment ("kept in
+ * sync") — a duplicate that announces it needs syncing is one that will
+ * eventually not be.
  *
- * Inputs and outputs are no longer carried by the manifest — they live in the
- * contract registry (see `apps/celilo/src/manifest/contracts/v1.ts`),
- * keyed by the manifest's `celilo_contract` version. The executor resolves
- * the signature at runtime.
+ * A second declaration of a shared shape does not fail loudly when it drifts:
+ * both sides keep compiling and the two meanings diverge silently. `HookName`
+ * was the same duplication and HAD already drifted — it was missing
+ * `reconcile_routes`, so caddy's reconcile hook was a hook the celilo side of
+ * the codebase did not believe in (celilo#821).
  */
-export interface HookDefinition {
-  /** Path to hook script relative to module directory */
-  script: string;
-  /** Total timeout in milliseconds (default: 60000) */
-  timeout?: number;
-  /** If true, hook needs interactive terminal (no FuelGauge wrapping) */
-  interactive?: boolean;
-}
-
-/**
- * Logger interface provided to hook scripts.
- *
- * Mirrors `HookLogger` in `@celilo/capabilities/types` — kept in sync so
- * concrete loggers we build here (createGaugeLogger, createConsoleLogger,
- * createCapturingLogger) satisfy both the in-process consumers and the
- * cross-package contract used by `wrapWithLogging`.
- */
-export interface HookLogger {
-  info(message: string): void;
-  warn(message: string): void;
-  error(message: string): void;
-  success(message: string): void;
-  /** Begin a logical span. Subsequent log calls nest under it visually. */
-  beginStep?(name: string): void;
-  /** End the current span (success). */
-  endStep?(name: string): void;
-  /** End the current span (failure) with an error message. */
-  failStep?(name: string, error: string): void;
-}
-
-/**
- * Context passed to hook scripts
- */
-export interface HookContext {
-  /** Module configuration values */
-  config: Record<string, unknown>;
-  /** Module secret values (decrypted) */
-  secrets: Record<string, string>;
-  /**
-   * The 0..N systems this module has deployed onto (openspec/specs/module-systems-addressing/spec.md).
-   * Always an array — no singular convenience, so the 0/1/N reality stays visible.
-   */
-  systems: DeployedSystem[];
-  /** Logger for reporting progress */
-  logger: HookLogger;
-  /** Run in debug mode (e.g., Playwright headless: false) */
-  debug: boolean;
-  /** Directory for saving screenshots on failure */
-  screenshotDir: string;
-  /** Capability function interfaces from provider modules (e.g., context.capabilities.dns_registrar) */
-  capabilities: Record<string, unknown>;
-  /** Dynamic inputs specified in manifest (e.g., vps_ip) */
-  [key: string]: unknown;
-}
+export type { HookDefinition, HookLogger, HookContext } from '@celilo/capabilities';
 
 /**
  * Surfaced by `invokeHook` when a capability call inside the hook threw
@@ -85,21 +37,15 @@ export interface MissingProviderInputDetails {
 }
 
 /**
- * Result returned from hook execution
+ * Result returned from hook execution.
+ *
+ * The shape a module's hook produces is `@celilo/capabilities`' `HookResult`;
+ * this adds the one field only the framework sets. A module never writes
+ * `missingProviderInput` — the executor sets it when a capability call throws
+ * `MissingProviderInputError` — so it belongs on the framework's view of the
+ * result rather than in the module-facing contract.
  */
-export interface HookResult {
-  success: boolean;
-  outputs: Record<string, unknown>;
-  error?: string;
-  /**
-   * Every file the hook wrote to its per-run artifact directory.
-   * All of them, not just the newest image: a screenshot without the
-   * DOM and the observed requests is the least useful third of a
-   * post-mortem.
-   */
-  artifactPaths?: string[];
-  /** Duration in milliseconds */
-  duration: number;
+export interface HookResult extends ModuleHookResult {
   /**
    * Set when the hook failed because a capability call needs the
    * framework to extend another module's config. Mutually exclusive

package/src/manifest/contracts/v1.ts

@@ -261,6 +261,41 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * Report what a tunnel/interface is ACTUALLY carrying, diffed against what
+   * celilo's config says it should carry.
+   *
+   * Deliberately a read of the live thing rather than of celilo's own record.
+   * celilo#928 was exactly a divergence between the two — a device present in
+   * config, rendered as active by a UI, and absent from the interface — and
+   * diagnosing it needed a screenshot and a root SSH because nothing celilo
+   * offered could tell the two apart. A hook that reported the record would
+   * have reproduced the misleading signal rather than exposing it.
+   *
+   * No structured outputs: it reports through the logger, so an operator and an
+   * agent read the same thing.
+   */
+  list_peers: {
+    inputs: {},
+    outputs: {},
+  },
+  /**
+   * Re-assert a module's desired peer set onto the thing carrying it, on a
+   * timer, without an operator.
+   *
+   * The counterpart to applying on change: apply-on-change bounds latency, this
+   * bounds how long ANY divergence can persist — including drift nobody
+   * predicted (a hand-edit on the box, an apply that failed, a record written
+   * before the applying code existed). celilo#934, where the module could
+   * already SEE the drift in `health_check` and had nowhere to act on it.
+   *
+   * A converge that changes nothing must be silent, so the log stays a record
+   * of things happening.
+   */
+  reconcile_peers: {
+    inputs: {},
+    outputs: {},
+  },
   /**
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,

package/src/manifest/schema.ts

@@ -364,6 +364,8 @@ const LIFECYCLE_HOOK_SCHEMAS = {
   refresh_registrations: LifecycleHookSchema.optional(),
   reassert_dhcp_dns: LifecycleHookSchema.optional(),
   reconcile_clients: LifecycleHookSchema.optional(),
+  list_peers: LifecycleHookSchema.optional(),
+  reconcile_peers: LifecycleHookSchema.optional(),
 } satisfies Record<HookName, z.ZodTypeAny>;
 
 /**

package/src/policy/module-business-baseline.ts

@@ -11,6 +11,19 @@
  * refer to that document's sections 1-4 — read the row before changing a line
  * here.
  *
+ * **Every debt entry names the issue tracking its removal.** The audit is a
+ * ruling; the issues are the work. If you are here because the gate went red,
+ * the issue in the entry's `why` is where the fix belongs:
+ *
+ *   #937  the hardcoded well-known registry + its duplicate zone table
+ *   #938  the loader's capName branches, CAPABILITY_MODULE_MAP, isFirewallModule
+ *   #939  the four provider-domain tables
+ *   #940  the Caddyfile generator + interface classification in the shared package
+ *   #941  core shelling iptables-save
+ *   #943  the three capability-named CLI verbs
+ *   #944  core shelling wg pubkey
+ *   #945  three core primitives gated on one capability (generalise, don't move)
+ *
  * Two kinds of entry live here and they must not be confused:
  *
  *   - **Debt** — the default. It is here because it is wrong and not yet fixed.
@@ -25,6 +38,9 @@
  * each belongs to. Scan A asserts the tagged set EQUALS this map — not that it
  * is empty. These four exist today (audit T1, T2, T3, T6) and Phase 1 migrates
  * nothing; an assertion that core holds none would be red the day it landed.
+ *
+ * Tracked by #939. Migrating them keeps the ownership CLAIM in core — dropping
+ * it is the mistake that made `dns_registration_consumers` necessary (#626).
  */
 export const CAPABILITY_OWNED_TABLES: Readonly<Record<string, string>> = {
   web_routes: 'public_web',
@@ -68,25 +84,25 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dhcp_server',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dns_internal',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dns_registrar',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'public_web',
     count: 1,
-    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2',
+    why: 'X1 — hardcoded canonical hostnames, required zones and literal ports; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/cli/commands/notify-config.ts',
@@ -98,91 +114,91 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'apps/celilo/src/cli/commands/token.ts',
     capability: 'idp',
     count: 1,
-    why: 'X7 — a top-level CLI verb backed by the idp capability; Phase 5',
+    why: 'X7 — a top-level CLI verb backed by the idp capability; Phase 5 (#943)',
   },
   {
     file: 'apps/celilo/src/cli/completion.ts',
     capability: 'firewall',
     count: 3,
-    why: 'X6 — tab completion for the capability-named CLI verbs; falls out with X6',
+    why: 'X6 — tab completion for the capability-named CLI verbs; falls out with X6 (#943)',
   },
   {
     file: 'apps/celilo/src/cli/index.ts',
     capability: 'firewall',
     count: 2,
-    why: 'X5/X6/X7 — the command tree wiring the capability-named CLI verbs; Phase 5',
+    why: 'X5/X6/X7 — the command tree wiring the capability-named CLI verbs; Phase 5 (#943)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'control_plane_vpn',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'dhcp_server',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'dns_internal',
     count: 3,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'dns_registrar',
     count: 4,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'external_web',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'firewall',
     count: 12,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'idp',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'notification',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'private_web',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'public_web',
     count: 8,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'registry_publish',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/hooks/capability-loader.ts',
     capability: 'source_forge',
     count: 1,
-    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3',
+    why: 'L1-L12 — core branches on the capability NAME; becomes a provider declaration in Phase 3 (#938)',
   },
   {
     file: 'apps/celilo/src/manifest/validate.ts',
@@ -212,49 +228,49 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'apps/celilo/src/services/dns-provider-backfill.ts',
     capability: 'dns_internal',
     count: 2,
-    why: 'S3 — the generic event-replay half is core; the dns_internal gate is not',
+    why: 'S3 — the generic event-replay half is core; the dns_internal gate is not (#945)',
   },
   {
     file: 'apps/celilo/src/services/firewall-reach.ts',
     capability: 'firewall',
     count: 1,
-    why: 'S8 — core shells iptables-save at a remote box and parses the output',
+    why: 'S8 — core shells iptables-save at a remote box and parses the output (#941)',
   },
   {
     file: 'apps/celilo/src/services/infrastructure-selector.ts',
     capability: 'firewall',
     count: 1,
-    why: 'S15 — isFirewallModule hardcodes a placement rule the manifest should declare',
+    why: 'S15 — isFirewallModule hardcodes a placement rule the manifest should declare (#938)',
   },
   {
     file: 'apps/celilo/src/services/module-deploy.ts',
     capability: 'firewall',
     count: 2,
-    why: "S16 — two more copies of S15's decision; fixing S15 removes all three",
+    why: "S16 — two more copies of S15's decision; fixing S15 removes all three (#938)",
   },
   {
     file: 'apps/celilo/src/services/public-web-republish.ts',
     capability: 'public_web',
     count: 1,
-    why: "S2 — encodes caddy's redeploy behaviour; generalise to a provider-declared re-assert signal",
+    why: "S2 — encodes caddy's redeploy behaviour; generalise to a provider-declared re-assert signal (#945)",
   },
   {
     file: 'apps/celilo/src/services/zone-policy.ts',
     capability: 'public_web',
     count: 1,
-    why: 'S13 — ZONE_REQUIREMENTS, a second hand-maintained copy of well-known.ts; Phase 2',
+    why: 'S13 — ZONE_REQUIREMENTS, a second hand-maintained copy of well-known.ts; Phase 2 (#937)',
   },
   {
     file: 'apps/celilo/src/templates/generator.ts',
     capability: 'dns_internal',
     count: 1,
-    why: 'X4 — declaration-driven and the model for the rest; only the error string names the capability',
+    why: 'X4 — declaration-driven and the model for the rest; only the error string names the capability (#945)',
   },
   {
     file: 'apps/celilo/src/variables/context.ts',
     capability: 'dns_internal',
     count: 1,
-    why: 'X3 — reaches capabilitiesMap.dns_internal by name; should read a declared field (X4 is the model)',
+    why: 'X3 — reaches capabilitiesMap.dns_internal by name; should read a declared field (X4 is the model) (#945)',
   },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
@@ -344,13 +360,13 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     file: 'packages/capabilities/src/public-web.ts',
     capability: 'public_web',
     count: 1,
-    why: "X8 — generateCaddyfile renders caddy's complete config from the shared package; Phase 5",
+    why: "X8 — generateCaddyfile renders caddy's complete config from the shared package; Phase 5 (#940)",
   },
   {
     file: 'packages/capabilities/src/utils.ts',
     capability: 'public_web',
     count: 3,
-    why: 'X8 — shared helpers that name the capability they serve; moves with X8 in Phase 5',
+    why: 'X8 — shared helpers that name the capability they serve; moves with X8 in Phase 5 (#940)',
   },
 ];
 
@@ -368,17 +384,17 @@ export const SERVICE_FILENAME_BASELINE: readonly ServiceFilenameRow[] = [
   {
     file: 'apps/celilo/src/services/dns-internal-records.ts',
     capability: 'dns_internal',
-    why: 'S5 — the store for T6; moves with the table in Phase 4',
+    why: 'S5 — the store for T6; moves with the table in Phase 4 (#939)',
   },
   {
     file: 'apps/celilo/src/services/firewall-reach.ts',
     capability: 'firewall',
-    why: 'S8 — core reaching into one provider implementation',
+    why: 'S8 — core reaching into one provider implementation (#941)',
   },
   {
     file: 'apps/celilo/src/services/public-web-republish.ts',
     capability: 'public_web',
-    why: "S2 — named for one provider's redeploy behaviour",
+    why: "S2 — named for one provider's redeploy behaviour (#945)",
   },
 ];
 
@@ -387,18 +403,18 @@ export const PROVIDER_LITERAL_BASELINE: readonly ProviderLiteralRow[] = [
     file: 'apps/celilo/src/secrets/generators.ts',
     literal: 'wg pubkey',
     count: 1,
-    why: 'X11 — core shells `wg pubkey` to derive a key, and tells the operator to brew install wireguard-tools',
+    why: 'X11 — core shells `wg pubkey` to derive a key, and tells the operator to brew install wireguard-tools (#944)',
   },
   {
     file: 'apps/celilo/src/services/firewall-reach.ts',
     literal: 'iptables-save',
     count: 1,
-    why: "S8 — core parses a firewall's live ruleset; implementation-specific, not merely capability-specific",
+    why: "S8 — core parses a firewall's live ruleset; implementation-specific, not merely capability-specific (#941)",
   },
   {
     file: 'packages/capabilities/src/public-web.ts',
     literal: '/srv/www',
     count: 4,
-    why: "X8 — the Caddyfile generator knows caddy's on-disk asset layout",
+    why: "X8 — the Caddyfile generator knows caddy's on-disk asset layout (#940)",
   },
 ];