@celilo/cli 0.26.1 → 1.0.0

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']);
+  });
+});

package/src/services/consumer-cleanup.ts

@@ -0,0 +1,244 @@
+/**
+ * Telling every provider that one of its consumers is leaving
+ * (openspec/changes/consumer-removal-cleanup).
+ *
+ * A capability is two-sided. The consumer asks, the provider mints something in
+ * its own world — a site block in caddy's Caddyfile, a DNAT rule in a ruleset,
+ * an OIDC client at authentik — and removal only ever touched one side of it.
+ * The FK cascade made that worse rather than better: the registry row
+ * disappeared, so the provider's next converge had no way to learn the thing
+ * had ever existed. The registry went quiet and the machine kept serving.
+ *
+ * This is the generic path that replaces `web-route-cleanup.ts`, which did the
+ * same job for exactly one capability, called by name from core.
+ *
+ * Split plan/execute (Rule 10.4) because the interesting decisions — which
+ * providers, which are skipped and why — are pure, and the part that isn't is
+ * just "run each hook and record what happened".
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilities, modules } from '../db/schema';
+import { type RunNamedHookResult, runNamedHook } from '../hooks/run-named-hook';
+import type { HookLogger } from '../hooks/types';
+import type { ModuleManifest } from '../manifest/schema';
+import { deletePortForwardsForModule } from './port-forwards';
+import { deleteTrustedSourcesForModule } from './trusted-sources';
+
+/**
+ * States in which a module has never resolved a capability and therefore holds
+ * nothing minted on anyone's behalf. Capabilities are registered at IMPORT, not
+ * deploy, so the `capabilities` table routinely names providers that were never
+ * deployed. The same predicate `remove-guard.ts` uses to decide a module is not
+ * a dependent — the guard and the cleanup must keep ONE definition of a live
+ * provider (D8).
+ */
+const PRE_DEPLOY_STATES = new Set(['IMPORTED', 'VALIDATED', 'CONFIGURED']);
+
+export type CleanupSkipReason = 'paused' | 'not-deployed';
+
+export interface CleanupTarget {
+  /** The provider module to notify. */
+  providerId: string;
+  /** Which of its capabilities the departing consumer used — for the log line. */
+  capabilityNames: string[];
+  /** Set when the provider will NOT be notified. */
+  skip?: CleanupSkipReason;
+}
+
+export interface ProviderRow {
+  moduleId: string;
+  capabilityName: string;
+}
+
+export interface ProviderState {
+  moduleId: string;
+  state: string;
+}
+
+/**
+ * Which providers must be told that `consumer` is going away.
+ *
+ * Pure. Sorted by provider id so dispatch order is deterministic and a failure
+ * is reproducible.
+ *
+ * ONE ENTRY PER PROVIDER, not per capability (D1): a provider can hold two
+ * capabilities the same consumer used, and dispatching per capability would run
+ * the same withdrawal twice. But MANY providers per capability (D3) —
+ * `capabilities` has no uniqueness on the name, and `firewall` deliberately has
+ * several rows (an edge provider plus inner layers). Every one is told.
+ *
+ * The provider is never its own consumer: a module that both provides and
+ * requires a capability would otherwise be asked to withdraw its own state as
+ * it is being removed, which its `on_uninstall` already owns.
+ */
+export function planConsumerCleanup(
+  consumer: string,
+  manifest: ModuleManifest,
+  providerRows: ProviderRow[],
+  providerStates: ProviderState[],
+): CleanupTarget[] {
+  // `requires` AND `optional` — the same set `remove-guard.ts` counts as a
+  // dependency edge. A capability consumed optionally still minted state.
+  const consumed = new Set([
+    ...(manifest.requires?.capabilities ?? []).map((c) => c.name),
+    ...(manifest.optional?.capabilities ?? []).map((c) => c.name),
+  ]);
+  if (consumed.size === 0) return [];
+
+  const stateOf = new Map(providerStates.map((s) => [s.moduleId, s.state]));
+  const byProvider = new Map<string, Set<string>>();
+
+  for (const row of providerRows) {
+    if (!consumed.has(row.capabilityName)) continue;
+    if (row.moduleId === consumer) continue;
+    const names = byProvider.get(row.moduleId) ?? new Set<string>();
+    names.add(row.capabilityName);
+    byProvider.set(row.moduleId, names);
+  }
+
+  return [...byProvider.entries()]
+    .map(([providerId, names]): CleanupTarget => {
+      const state = stateOf.get(providerId);
+      const capabilityNames = [...names].sort();
+      if (state === 'PAUSED') return { providerId, capabilityNames, skip: 'paused' };
+      if (state === undefined || PRE_DEPLOY_STATES.has(state)) {
+        return { providerId, capabilityNames, skip: 'not-deployed' };
+      }
+      return { providerId, capabilityNames };
+    })
+    .sort((a, b) => a.providerId.localeCompare(b.providerId));
+}
+
+/** Read the plan's inputs out of the DB. */
+export function loadConsumerCleanupPlan(
+  consumer: string,
+  manifest: ModuleManifest,
+  db: DbClient,
+): CleanupTarget[] {
+  const providerRows = db
+    .select({ moduleId: capabilities.moduleId, capabilityName: capabilities.capabilityName })
+    .from(capabilities)
+    .all();
+  const providerStates = db
+    .select({ moduleId: modules.id, state: modules.state })
+    .from(modules)
+    .all();
+  return planConsumerCleanup(consumer, manifest, providerRows, providerStates);
+}
+
+export interface CleanupFailure {
+  providerId: string;
+  error: string;
+}
+
+export interface ConsumerCleanupResult {
+  notified: string[];
+  skipped: Array<{ providerId: string; reason: CleanupSkipReason }>;
+  failures: CleanupFailure[];
+}
+
+/**
+ * Run the plan. Sequential, deterministic, and it CONTINUES PAST A FAILURE
+ * (D13) — every provider is told even if an earlier one threw. Stopping early
+ * would leave MORE providers holding state for a module that is about to
+ * disappear, which is the failure this exists to fix.
+ *
+ * A failed withdrawal NEVER blocks the removal (D6). The record is an ERRORed
+ * PROVIDER, not a refused removal: the hook is a full converge, so a failure
+ * does not mean "it failed to forget one thing" — the provider may have
+ * re-rendered its state without the departing consumer AND without everything
+ * else. ERROR is the honest label for a provider whose state is now unknown,
+ * and `audit/undeployed-modules.ts` already turns it into a `blocked` finding.
+ * Nothing refuses to USE an ERRORed module, so the provider keeps serving while
+ * carrying the flag.
+ */
+export async function runConsumerCleanup(
+  consumer: string,
+  plan: CleanupTarget[],
+  db: DbClient,
+  logger: HookLogger,
+  /** Injectable hook runner — tests drive the failure and paused paths through it. */
+  runHook: (providerId: string) => Promise<RunNamedHookResult> = (providerId) =>
+    runNamedHook(providerId, 'on_consumer_removed', db, logger, { inputs: { consumer } }),
+): Promise<ConsumerCleanupResult> {
+  const result: ConsumerCleanupResult = { notified: [], skipped: [], failures: [] };
+
+  for (const target of plan) {
+    if (target.skip) {
+      result.skipped.push({ providerId: target.providerId, reason: target.skip });
+      // Reported, not silent (D7/D8). Nothing was attempted, so nothing is
+      // unknown and the provider is NOT marked ERROR.
+      if (target.skip === 'paused') {
+        logger.warn(
+          `${target.providerId} is paused, so it was not told that '${consumer}' is gone — it is still holding whatever it minted for it (${target.capabilityNames.join(', ')}). Unpause and redeploy it to reconcile.`,
+        );
+      }
+      continue;
+    }
+
+    const hookResult = await runHook(target.providerId);
+
+    // A module paused BETWEEN the plan and this dispatch. `runNamedHook` reports
+    // that as success, so taking it at face value would log a withdrawal that
+    // did not happen — which is the silence this whole change exists to end.
+    // The window is small (one CLI process) and the consequence of trusting it
+    // is not, so it is read rather than assumed.
+    if (hookResult.skippedPaused) {
+      result.skipped.push({ providerId: target.providerId, reason: 'paused' });
+      logger.warn(
+        `${target.providerId} was paused while '${consumer}' was being removed, so it was not told — it is still holding whatever it minted for it (${target.capabilityNames.join(', ')}). Unpause and redeploy it to reconcile.`,
+      );
+      continue;
+    }
+
+    if (hookResult.success) {
+      // `notDefined` means the provider declares no such hook — it mints
+      // nothing per consumer, and the dispatch succeeding is the right answer.
+      if (!hookResult.notDefined) {
+        result.notified.push(target.providerId);
+        logger.info(`${target.providerId} withdrew what it held for '${consumer}'`);
+      }
+      continue;
+    }
+
+    const error = hookResult.error ?? 'unknown error';
+    result.failures.push({ providerId: target.providerId, error });
+    markProviderErrored(target.providerId, consumer, error, db);
+    logger.warn(
+      `${target.providerId} failed to withdraw what it held for '${consumer}' and is now marked ERROR: ${error}`,
+    );
+  }
+
+  // The rows, once every provider has converged without them (D4). `web_routes`
+  // dies with the `modules` row via its FK cascade; these two carry a plain
+  // `registered_by` text column and do not.
+  deletePortForwardsForModule(db, consumer);
+  deleteTrustedSourcesForModule(db, consumer);
+
+  return result;
+}
+
+/**
+ * Mark the PROVIDER — not the module being removed — as ERROR, naming the
+ * departing consumer and the raw hook error.
+ *
+ * The consumer is in `errorMessage` because the audit finding is read long
+ * after the removal, by someone with no reason to connect the two.
+ */
+function markProviderErrored(
+  providerId: string,
+  consumer: string,
+  error: string,
+  db: DbClient,
+): void {
+  db.update(modules)
+    .set({
+      state: 'ERROR',
+      errorMessage: `Failed to withdraw state held for removed consumer '${consumer}': ${error}`,
+      updatedAt: new Date(),
+    })
+    .where(eq(modules.id, providerId))
+    .run();
+}

package/src/services/infrastructure-selector.test.ts

@@ -100,7 +100,6 @@ describe('infrastructure-selector', () => {
         hardware: { cpu_cores: 4, memory_mb: 4096, disk_gb: 128 },
         role: 'host',
         interfaces: [],
-        assignedModuleIds: [],
       });
 
       const result = await selectInfrastructure(module);
@@ -143,7 +142,6 @@ describe('infrastructure-selector', () => {
         hardware: { cpu_cores: 4, memory_mb: 4096, disk_gb: 128 },
         role: 'host',
         interfaces: [],
-        assignedModuleIds: [],
       });
 
       const result = await selectInfrastructure(module);
@@ -308,7 +306,6 @@ describe('infrastructure-selector', () => {
         hardware: { cpu_cores: 1, memory_mb: 4096, disk_gb: 128 },
         role: 'host',
         interfaces: [],
-        assignedModuleIds: [],
       });
 
       // Should throw InfrastructureError with resource details
@@ -350,7 +347,6 @@ describe('infrastructure-selector', () => {
         hardware: { cpu_cores: 4, memory_mb: 1024, disk_gb: 128 },
         role: 'host',
         interfaces: [],
-        assignedModuleIds: [],
       });
 
       await expect(selectInfrastructure(module)).rejects.toThrow(InfrastructureError);
@@ -390,7 +386,6 @@ describe('infrastructure-selector', () => {
         hardware: { cpu_cores: 4, memory_mb: 4096, disk_gb: 10 },
         role: 'host',
         interfaces: [],
-        assignedModuleIds: [],
       });
 
       await expect(selectInfrastructure(module)).rejects.toThrow(InfrastructureError);
@@ -430,7 +425,6 @@ describe('infrastructure-selector', () => {
         hardware: { cpu_cores: 8, memory_mb: 16384, disk_gb: 256 },
         role: 'host',
         interfaces: [],
-        assignedModuleIds: [],
       });
 
       const result = await selectInfrastructure(module);
@@ -473,7 +467,6 @@ describe('infrastructure-selector', () => {
         hardware: { cpu_cores: 4, memory_mb: 4096, disk_gb: 128 },
         role: 'host',
         interfaces: [],
-        assignedModuleIds: [],
       });
 
       const result = await selectInfrastructure(module);