@celilo/cli 0.27.0 → 1.1.0

package/src/manifest/contracts/v1.ts

@@ -22,6 +22,8 @@
  * change and requires a v2.0 contract.
  */
 
+import type { HookName } from '@celilo/capabilities';
+
 /**
  * Per-input/output metadata.
  *
@@ -47,8 +49,21 @@ export interface ContractHookSignature {
  * Full contract for a version: a map of canonical hook name → signature.
  * Only hook names listed here are valid; declaring a hook not in this map is
  * a manifest validation error.
+ *
+ * Keyed by `HookName` rather than `string` (celilo#821). That single change is
+ * what turns this table from a fourth hand-maintained list into a derivation:
+ * a name added to `HOOK_NAMES` without an entry here is a type error, and an
+ * entry here for a name that is not a hook is one too. It was `Record<string,
+ * …>`, which is why the drift went unnoticed for months.
+ *
+ * `on_upstream_publish` is named explicitly because it is NOT a `HookName` — an
+ * array of build-bus match rules rather than an invokable hook. It has a
+ * signature here because the executor passes its payload as env vars and the
+ * contract is where that is written down.
  */
-export type ContractHooks = Record<string, ContractHookSignature>;
+export type ContractHooks = Record<HookName, ContractHookSignature> & {
+  on_upstream_publish: ContractHookSignature;
+};
 
 /**
  * Contract v1.0 — current canonical hook signatures.
@@ -70,6 +85,23 @@ export const V1_HOOKS: ContractHooks = {
     inputs: {},
     outputs: {},
   },
+  /**
+   * A module that CONSUMED one of this module's capabilities is being removed.
+   * The provider withdraws whatever it minted on that consumer's behalf
+   * (openspec/changes/consumer-removal-cleanup, D1).
+   *
+   * `consumer` is the only input and there are no outputs. Deliberately NOT
+   * accompanied by the list of capabilities the consumer used: a provider that
+   * cannot answer "what do I hold for this module" without being told has a
+   * different defect — the consumer's id was never recorded at the point of the
+   * call — and telling it at removal time only papers over that.
+   */
+  on_consumer_removed: {
+    inputs: {
+      consumer: { required: true },
+    },
+    outputs: {},
+  },
   health_check: {
     inputs: {},
     outputs: {},

package/src/manifest/schema.ts

@@ -1,3 +1,4 @@
+import type { HookName } from '@celilo/capabilities';
 import { z } from 'zod';
 import { NETWORK_ZONES } from '../db/schema';
 import {
@@ -332,6 +333,52 @@ export const UpstreamPublishHookSchema = z.object({
   timeout: z.number().positive().optional(),
 });
 
+/**
+ * The manifest schema for every invokable lifecycle hook, derived from the one
+ * list (celilo#821).
+ *
+ * `satisfies Record<HookName, …>` is doing the enforcement, in both directions:
+ * a name in `HOOK_NAMES` with no entry here is a type error, and an entry here
+ * that is not a `HookName` is a type error too. That is why this is a literal
+ * rather than something built with `Object.fromEntries` — a computed object
+ * would widen the keys to `string` and take `ModuleManifest['hooks']` down with
+ * it, trading one silent drift for another.
+ *
+ * Per-hook prose lives in `contracts/v1.ts`, which documents the same names.
+ * Two copies of that commentary is how they came to disagree.
+ */
+const LIFECYCLE_HOOK_SCHEMAS = {
+  container_created: LifecycleHookSchema.optional(),
+  on_install: LifecycleHookSchema.optional(),
+  on_uninstall: LifecycleHookSchema.optional(),
+  on_consumer_removed: LifecycleHookSchema.optional(),
+  health_check: HealthCheckHookSchema.optional().describe(
+    "Health check hook. `interval` is the module's SUGGESTED monitoring cadence; the operator's monitor row is the effective schedule and always wins.",
+  ),
+  validate_config: LifecycleHookSchema.optional(),
+  on_backup: LifecycleHookSchema.optional(),
+  on_backup_analyze: LifecycleHookSchema.optional(),
+  on_restore: LifecycleHookSchema.optional(),
+  on_system_event: LifecycleHookSchema.optional(),
+  reconcile_routes: LifecycleHookSchema.optional(),
+  refresh_registrations: LifecycleHookSchema.optional(),
+  reassert_dhcp_dns: LifecycleHookSchema.optional(),
+  reconcile_clients: LifecycleHookSchema.optional(),
+} satisfies Record<HookName, z.ZodTypeAny>;
+
+/**
+ * What `manifest.hooks` accepts: every lifecycle hook, plus
+ * `on_upstream_publish`, which is deliberately not a `HookName` — an ARRAY of
+ * build-bus match rules dispatched by the receiver daemon rather than a hook
+ * `runNamedHook` can invoke. It is spread in here rather than living in
+ * `LIFECYCLE_HOOK_SCHEMAS` so the `satisfies` above stays exact.
+ * See [[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4.
+ */
+const HOOK_SCHEMAS = {
+  ...LIFECYCLE_HOOK_SCHEMAS,
+  on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
+};
+
 /**
  * Machine resource recommendations
  * Module declares recommended machine resources (CPU, memory, disk, storage)
@@ -626,64 +673,7 @@ export const ModuleManifestSchema = z
       })
       .optional(),
 
-    hooks: z
-      .object({
-        container_created: LifecycleHookSchema.optional(),
-        on_install: LifecycleHookSchema.optional(),
-        on_uninstall: LifecycleHookSchema.optional(),
-        health_check: HealthCheckHookSchema.optional().describe(
-          "Health check hook. `interval` is the module's SUGGESTED monitoring cadence; the operator's monitor row is the effective schedule and always wins.",
-        ),
-        validate_config: LifecycleHookSchema.optional(),
-        on_backup: LifecycleHookSchema.optional(),
-        on_backup_analyze: LifecycleHookSchema.optional(),
-        on_restore: LifecycleHookSchema.optional(),
-        /**
-         * Per-system lifecycle hook. A dns_internal provider declares this
-         * to (de)register a single host's A records when celilo's bridge
-         * delivers a system.created/destroyed event. Inputs (hostname,
-         * target_ip, op) come from the contract — see contracts/v1.ts and
-         * [[openspec/specs/internal-dns-split-horizon/spec.md]] D5.
-         */
-        on_system_event: LifecycleHookSchema.optional(),
-        /**
-         * Reconcile the provider's running config from a celilo registry on a
-         * change event. The caddy `public_web` provider declares this to
-         * re-render its Caddyfile from web_routes when a consumer registers or
-         * unregisters a route (ISS-0035). See
-         * [[openspec/specs/public-web-provider-reconcile/spec.md]].
-         */
-        reconcile_routes: LifecycleHookSchema.optional(),
-        /**
-         * Periodic re-assertion of a dns_registrar provider's registered
-         * records. The framework injects the provider's dns_registrations
-         * ledger rows as the `registrations` input; the hook re-sends each
-         * one to the underlying DNS API and fails loudly if any cannot be
-         * re-asserted. Providers subscribe it to a `timer.tick.*` event.
-         * Part of the dns_registrar capability contract — see
-         * designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md (B3).
-         */
-        refresh_registrations: LifecycleHookSchema.optional(),
-        /**
-         * Periodic re-assertion of the resolver a dns_internal provider
-         * hands out over DHCP. Some routers regenerate that value from
-         * their own upstream list on a timer, silently undoing what
-         * on_install set. The hook reads the device before writing, so a
-         * quiet minute costs one query. Subscribe it to `timer.tick.1m` —
-         * the tick interval IS the worst-case window in which a renewing
-         * client can be handed the wrong resolver. See celilo#739.
-         */
-        reassert_dhcp_dns: LifecycleHookSchema.optional(),
-        reconcile_clients: LifecycleHookSchema.optional(),
-        /**
-         * Build-bus upstream publish hooks. Array (a module can react
-         * to multiple upstream packages with different actions). See
-         * [[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4.
-         */
-        on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
-      })
-      .strict()
-      .optional(),
+    hooks: z.object(HOOK_SCHEMAS).strict().optional(),
 
     build: z
       .object({

package/src/services/audit/undeployed-modules.ts

@@ -19,6 +19,17 @@ export interface UndeployedModule {
   id: string;
   /** Lifecycle state from the modules table (IMPORTED, VALIDATED, …). */
   state: string;
+  /**
+   * Why it is in ERROR, verbatim from the modules table.
+   *
+   * Surfaced because the headline used to be the hardcoded "previous deploy
+   * failed", and that became a FALSE statement once a provider could be marked
+   * ERROR for failing to withdraw a removed consumer's state
+   * (openspec/changes/consumer-removal-cleanup, D6) — no deploy was involved,
+   * and the operator reading the finding has no other way to learn which
+   * consumer it was.
+   */
+  errorMessage?: string | null;
 }
 
 export interface UndeployedModulesAuditDeps {
@@ -40,11 +51,17 @@ export async function auditUndeployedModules(
     if (TRANSIENT_STATES.has(m.state)) continue;
 
     if (m.state === 'ERROR') {
+      const reason = m.errorMessage?.trim();
       findings.push({
         category: 'undeployed_modules',
         severity: 'blocked',
         code: 'module_in_error_state',
-        message: `${m.id}: previous deploy failed (state: ERROR)`,
+        // The recorded reason when there is one. A module reaches ERROR from
+        // more than one place now, and naming the wrong cause sends the
+        // operator to the wrong evidence.
+        message: reason
+          ? `${m.id}: ${reason} (state: ERROR)`
+          : `${m.id}: previous deploy failed (state: ERROR)`,
         details:
           'Investigate the prior failure (check `celilo module status` and the' +
           ' module logs) before retrying — re-deploying without diagnosing the' +

package/src/services/consumer-cleanup.test.ts

@@ -0,0 +1,347 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { DbClient } from '../db/client';
+import type { ModuleManifest } from '../manifest/schema';
+import { setupTestDatabase } from '../test-utils/setup-test-db';
+import {
+  type CleanupTarget,
+  type ProviderRow,
+  type ProviderState,
+  planConsumerCleanup,
+  runConsumerCleanup,
+} from './consumer-cleanup';
+
+/**
+ * The pure half of the removal dispatch
+ * (openspec/changes/consumer-removal-cleanup). Which providers get told, and
+ * which are skipped and why, is all decided here — so it is all assertable
+ * without a database, a hook runner, or a deployed anything.
+ */
+
+function manifest(input: { requires?: string[]; optional?: string[] }): ModuleManifest {
+  return {
+    requires: { capabilities: (input.requires ?? []).map((name) => ({ name, version: '1.0.0' })) },
+    optional: { capabilities: (input.optional ?? []).map((name) => ({ name, version: '1.0.0' })) },
+  } as unknown as ModuleManifest;
+}
+
+const deployed = (...ids: string[]): ProviderState[] =>
+  ids.map((moduleId) => ({ moduleId, state: 'VERIFIED' }));
+
+const provides = (...pairs: Array<[string, string]>): ProviderRow[] =>
+  pairs.map(([moduleId, capabilityName]) => ({ moduleId, capabilityName }));
+
+describe('planConsumerCleanup', () => {
+  it('collects providers of BOTH requires and optional capabilities', () => {
+    // The same set `remove-guard.ts` counts as a dependency edge. A capability
+    // consumed optionally still had state minted for it — `technitium` consumes
+    // `dhcp_server` under `optional:`, and the two definitions disagreeing has
+    // already been silently harmful once.
+    const plan = planConsumerCleanup(
+      'consumer',
+      manifest({ requires: ['public_web'], optional: ['firewall'] }),
+      provides(['caddy', 'public_web'], ['iptables', 'firewall']),
+      deployed('caddy', 'iptables'),
+    );
+
+    expect(plan.map((t) => t.providerId)).toEqual(['caddy', 'iptables']);
+  });
+
+  it('tells EVERY provider of one capability (the chained-firewall case)', () => {
+    // `capabilities` has no uniqueness on the name: `firewall` deliberately has
+    // several rows, an edge provider plus inner layers, and each holds its own
+    // rules for the departing consumer (D3).
+    const plan = planConsumerCleanup(
+      'consumer',
+      manifest({ requires: ['firewall'] }),
+      provides(['iptables', 'firewall'], ['greenwave', 'firewall']),
+      deployed('iptables', 'greenwave'),
+    );
+
+    expect(plan.map((t) => t.providerId)).toEqual(['greenwave', 'iptables']);
+  });
+
+  it('tells a provider of two consumed capabilities exactly ONCE', () => {
+    // Dispatching per capability would run the same withdrawal twice (D1) — the
+    // hook is a full converge, so the second run is at best wasted and at worst
+    // re-applies a ruleset over a half-applied one.
+    const plan = planConsumerCleanup(
+      'consumer',
+      manifest({ requires: ['source_forge', 'registry_publish'] }),
+      provides(['forgejo', 'source_forge'], ['forgejo', 'registry_publish']),
+      deployed('forgejo'),
+    );
+
+    expect(plan).toHaveLength(1);
+    expect(plan[0].providerId).toBe('forgejo');
+    expect(plan[0].capabilityNames).toEqual(['registry_publish', 'source_forge']);
+  });
+
+  it('sorts by provider id, so dispatch order is deterministic', () => {
+    const plan = planConsumerCleanup(
+      'consumer',
+      manifest({ requires: ['firewall'] }),
+      provides(['zebra', 'firewall'], ['axon', 'firewall'], ['iptables', 'firewall']),
+      deployed('zebra', 'axon', 'iptables'),
+    );
+
+    expect(plan.map((t) => t.providerId)).toEqual(['axon', 'iptables', 'zebra']);
+  });
+
+  it('marks a PAUSED provider skipped rather than dispatching to it', () => {
+    // A paused module does not run non-lifecycle hooks (D7). Recording the skip
+    // is what lets the caller say WHICH provider is still holding state.
+    const plan = planConsumerCleanup(
+      'consumer',
+      manifest({ requires: ['public_web'] }),
+      provides(['caddy', 'public_web']),
+      [{ moduleId: 'caddy', state: 'PAUSED' }],
+    );
+
+    expect(plan).toEqual([
+      { providerId: 'caddy', capabilityNames: ['public_web'], skip: 'paused' },
+    ]);
+  });
+
+  it('marks a never-deployed provider skipped', () => {
+    // Capabilities are registered at IMPORT, so the table routinely names
+    // providers that have never resolved anything and hold nothing (D8).
+    for (const state of ['IMPORTED', 'VALIDATED', 'CONFIGURED']) {
+      const plan = planConsumerCleanup(
+        'consumer',
+        manifest({ requires: ['public_web'] }),
+        provides(['caddy', 'public_web']),
+        [{ moduleId: 'caddy', state }],
+      );
+      expect(plan[0].skip).toBe('not-deployed');
+    }
+  });
+
+  it('skips a provider with no module row at all rather than dispatching blind', () => {
+    const plan = planConsumerCleanup(
+      'consumer',
+      manifest({ requires: ['public_web'] }),
+      provides(['caddy', 'public_web']),
+      [],
+    );
+
+    expect(plan[0].skip).toBe('not-deployed');
+  });
+
+  it('is empty for a module that consumes nothing', () => {
+    expect(
+      planConsumerCleanup(
+        'consumer',
+        manifest({}),
+        provides(['caddy', 'public_web']),
+        deployed('caddy'),
+      ),
+    ).toEqual([]);
+  });
+
+  it('never asks the departing module to withdraw its own state', () => {
+    // A module can both provide and require a capability. Its own `on_uninstall`
+    // owns its teardown; being handed itself as a provider would run a converge
+    // on a module that is mid-removal.
+    const plan = planConsumerCleanup(
+      'caddy',
+      manifest({ requires: ['firewall'] }),
+      provides(['caddy', 'firewall'], ['iptables', 'firewall']),
+      deployed('caddy', 'iptables'),
+    );
+
+    expect(plan.map((t) => t.providerId)).toEqual(['iptables']);
+  });
+
+  it('ignores providers of capabilities the consumer never declared', () => {
+    const plan = planConsumerCleanup(
+      'consumer',
+      manifest({ requires: ['public_web'] }),
+      provides(['caddy', 'public_web'], ['namecheap', 'dns_registrar']),
+      deployed('caddy', 'namecheap'),
+    );
+
+    expect(plan.map((t) => t.providerId)).toEqual(['caddy']);
+  });
+});
+
+describe('runConsumerCleanup — the paused skip is reported, not silent', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'cc-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabase(dbPath);
+  });
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  /**
+   * Asserted here rather than through the CLI: `module remove`'s output is
+   * clack-formatted and its stderr is discarded by the integration harness, so
+   * a substring match there would prove nothing about the message. This is the
+   * layer where the text actually exists.
+   */
+  it('warns, naming the provider AND the consumer whose state it keeps (D7)', async () => {
+    const messages: string[] = [];
+    const logger = {
+      info: () => {},
+      warn: (m: string) => messages.push(m),
+      error: () => {},
+      success: () => {},
+    };
+
+    const result = await runConsumerCleanup(
+      'departing',
+      [{ providerId: 'caddy', capabilityNames: ['public_web'], skip: 'paused' }],
+      db,
+      logger,
+    );
+
+    expect(result.skipped).toEqual([{ providerId: 'caddy', reason: 'paused' }]);
+    expect(result.failures).toEqual([]);
+    expect(messages).toHaveLength(1);
+    expect(messages[0]).toContain('caddy');
+    expect(messages[0]).toContain('departing');
+    expect(messages[0]).toContain('public_web');
+  });
+
+  it('says nothing about a provider that was never deployed', async () => {
+    // Unlike a pause, this is not a state an operator chose and can undo — the
+    // provider holds nothing, so there is nothing to report.
+    const messages: string[] = [];
+    const logger = {
+      info: () => {},
+      warn: (m: string) => messages.push(m),
+      error: () => {},
+      success: () => {},
+    };
+
+    const result = await runConsumerCleanup(
+      'departing',
+      [{ providerId: 'caddy', capabilityNames: ['public_web'], skip: 'not-deployed' }],
+      db,
+      logger,
+    );
+
+    expect(result.skipped).toEqual([{ providerId: 'caddy', reason: 'not-deployed' }]);
+    expect(messages).toEqual([]);
+  });
+});
+
+describe('runConsumerCleanup — dispatch', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'ccd-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabase(dbPath);
+  });
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const capture = () => {
+    const warnings: string[] = [];
+    return {
+      warnings,
+      logger: {
+        info: () => {},
+        warn: (m: string) => warnings.push(m),
+        error: () => {},
+        success: () => {},
+      },
+    };
+  };
+
+  const target = (providerId: string): CleanupTarget => ({
+    providerId,
+    capabilityNames: ['firewall'],
+  });
+
+  /**
+   * `runNamedHook` reports a paused module as SUCCESS. Taking that at face value
+   * would log a withdrawal that never happened — the silence this change exists
+   * to end — so the flag is read rather than assumed. Reachable when a module is
+   * paused between the plan and this dispatch.
+   */
+  it('a provider paused between plan and dispatch is skipped, not counted as withdrawn', async () => {
+    const { warnings, logger } = capture();
+
+    const result = await runConsumerCleanup(
+      'departing',
+      [target('iptables')],
+      db,
+      logger,
+      async () => ({
+        success: true,
+        outputs: {},
+        duration: 0,
+        skippedPaused: true,
+      }),
+    );
+
+    expect(result.notified).toEqual([]);
+    expect(result.skipped).toEqual([{ providerId: 'iptables', reason: 'paused' }]);
+    expect(result.failures).toEqual([]);
+    expect(warnings[0]).toContain('iptables');
+    expect(warnings[0]).toContain('departing');
+  });
+
+  it('a provider with no such hook is not reported as having withdrawn anything', async () => {
+    const { logger } = capture();
+
+    const result = await runConsumerCleanup(
+      'departing',
+      [target('namecheap')],
+      db,
+      logger,
+      async () => ({
+        success: true,
+        outputs: {},
+        duration: 0,
+        notDefined: true,
+      }),
+    );
+
+    // It mints nothing per consumer, so succeeding IS the right answer — but it
+    // did not withdraw anything, and must not claim to.
+    expect(result.notified).toEqual([]);
+    expect(result.failures).toEqual([]);
+  });
+
+  it('continues past a failure, and records it on the failing provider only (D13)', async () => {
+    const { logger } = capture();
+    const told: string[] = [];
+
+    const result = await runConsumerCleanup(
+      'departing',
+      [target('axon'), target('iptables')],
+      db,
+      logger,
+      async (providerId) => {
+        told.push(providerId);
+        return providerId === 'axon'
+          ? { success: false, outputs: {}, duration: 0, error: 'router said no' }
+          : { success: true, outputs: {}, duration: 0 };
+      },
+    );
+
+    // Both were told, in plan order — stopping early would leave MORE providers
+    // holding state for a module about to disappear.
+    expect(told).toEqual(['axon', 'iptables']);
+    expect(result.failures).toEqual([{ providerId: 'axon', error: 'router said no' }]);
+    expect(result.notified).toEqual(['iptables']);
+  });
+});