@celilo/cli 0.3.28 → 0.3.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/cli/commands/module-upgrade.test.ts

@@ -8,6 +8,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
 import { type DbClient, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import { classifyVersionChange, upgradeOne } from './module-upgrade';
@@ -153,4 +154,62 @@ description: fixture
     if (quietResult.status !== 'success') return;
     expect(quietResult.newVersion).toBe('1.0.0');
   });
+
+  // Regression for the namecheap stale-findings problem: the upgrade
+  // path MUST overwrite manifestData with the new manifest — otherwise
+  // any subsequent audit (or any code path that reads from the DB)
+  // sees the OLD manifest's required vars even after the operator
+  // upgraded to a version that removed them. The user hit this on
+  // celilo-mgmt: namecheap@3.1.1+6 dropped the `domains` variable, but
+  // post-upgrade the audit still complained "required config 'domains'
+  // is not set" because the DB's manifestData hadn't been refreshed.
+  test('persists new manifest to modules.manifestData (not just .version)', async () => {
+    // Write a brand-new manifest.yml in srcDir that REMOVES a
+    // variable the old DB record had. After upgrade, the modules
+    // row's manifestData should reflect the removal.
+    writeFileSync(
+      join(srcDir, 'manifest.yml'),
+      `celilo_contract: "1.0"
+id: testmod
+name: Test Module Renamed
+version: 2.0.0
+description: fixture v2
+variables:
+  owns: []
+  imports: []
+`,
+    );
+    // Simulate the DB starting in a state where manifestData has a
+    // `variables.owns` array — the namecheap-3.1.0 → 3.1.1 case.
+    db.update(modules)
+      .set({
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'testmod',
+          name: 'Test Module',
+          version: '1.0.0',
+          variables: { owns: [{ name: 'domains', type: 'array', required: true }], imports: [] },
+        },
+      })
+      .where(eq(modules.id, 'testmod'))
+      .run();
+
+    const result = await upgradeOne(srcDir, db, {}, { quiet: true, displayVersion: '2.0.0+1' });
+    expect(result.status).toBe('success');
+
+    const row = db.select().from(modules).all()[0];
+    // version field updates (this part already worked):
+    expect(row.version).toBe('2.0.0+1');
+    expect(row.name).toBe('Test Module Renamed');
+    // manifestData reflects the NEW manifest — the dropped variable
+    // is gone. This is the regression assertion.
+    const manifest = row.manifestData as {
+      version: string;
+      name: string;
+      variables?: { owns: unknown[] };
+    };
+    expect(manifest.version).toBe('2.0.0');
+    expect(manifest.name).toBe('Test Module Renamed');
+    expect(manifest.variables?.owns ?? []).toEqual([]);
+  });
 });

package/src/cli/commands/system-audit.ts

@@ -189,12 +189,14 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
 
   const installedConfigs = deployedModules.map((m) => ({
     id: m.id,
+    state: m.state,
     manifest: m.manifestData as ModuleManifest,
     configs: configsByModule.get(m.id) ?? {},
   }));
 
   const installedBackupInfo = deployedModules.map((m) => ({
     id: m.id,
+    state: m.state,
     manifest: m.manifestData as ModuleManifest,
     lastSuccessfulBackupAt: latestBackupByModule.get(m.id) ?? null,
   }));
@@ -402,6 +404,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     capabilityAbi: {
       modules: deployedModules.map((m) => ({
         id: m.id,
+        state: m.state,
         manifest: m.manifestData as ModuleManifest,
       })),
     },

package/src/cli/commands/system-update.ts

@@ -386,7 +386,12 @@ function buildOps(registry: RegistryClient, wasDeployed: Set<string>): Orchestra
 function formatResult(result: SystemUpdateResult): string {
   const lines: string[] = [];
   lines.push('');
-  lines.push(`update ${result.updateId} → ${result.ok ? 'OK' : 'FAILED'}`);
+  // The updateId is for audit / journal correlation (see the
+  // `backups` table's updateId FK); operators don't read it during
+  // normal use, only when debugging a specific run via --json or
+  // `celilo backup list`. Surfacing it in human output added noise
+  // without paying for itself.
+  lines.push(`System update ${result.ok ? 'completed' : 'FAILED'}`);
   lines.push(`  audit verdict: ${result.audit.verdict}`);
   lines.push(
     `  self-update: ${result.selfUpdate.performed ? `${result.selfUpdate.from} → ${result.selfUpdate.to}` : `(${result.selfUpdate.reason})`}`,
@@ -523,6 +528,7 @@ export async function handleSystemUpdate(
     capabilityAbi: {
       modules: upgradableModules.map((m) => ({
         id: m.id,
+        state: m.state,
         manifest: m.manifestData as ModuleManifest,
       })),
     },
@@ -546,6 +552,7 @@ export async function handleSystemUpdate(
     moduleConfigs: {
       modules: upgradableModules.map((m) => ({
         id: m.id,
+        state: m.state,
         manifest: m.manifestData as ModuleManifest,
         configs: configsByModule.get(m.id) ?? {},
       })),
@@ -554,6 +561,7 @@ export async function handleSystemUpdate(
     backups: {
       modules: upgradableModules.map((m) => ({
         id: m.id,
+        state: m.state,
         manifest: m.manifestData as ModuleManifest,
         lastSuccessfulBackupAt: latestBackupByModule.get(m.id) ?? null,
       })),
@@ -677,6 +685,21 @@ export async function handleSystemUpdate(
     onlyModule,
   });
 
+  // The audit baked into `result.audit` ran BEFORE the orchestrator
+  // upgraded any modules. Its findings are now stale for whatever
+  // we just upgraded — `module_versions` drift, `module_configs`
+  // referencing the OLD manifest's required vars, `capability_abi`
+  // checking pre-upgrade providers. Re-query the modules table and
+  // re-run the audit so the displayed findings reflect post-upgrade
+  // reality. Only do this on a successful run (a partial-failure
+  // run keeps its original audit so the operator sees what the
+  // orchestrator was reacting to).
+  const successfulModuleSteps = result.modules.filter((m) => m.step === 'done');
+  if (result.ok && successfulModuleSteps.length > 0) {
+    const refreshedAudit = await runAudit(rebuildAuditDepsForRerun(auditDeps, db));
+    result.audit = refreshedAudit;
+  }
+
   if (json) {
     if (result.ok) {
       return { success: true, message: JSON.stringify(result, null, 2), rawOutput: true };
@@ -692,3 +715,84 @@ export async function handleSystemUpdate(
     error: `${formatResult(result)}\n\none or more modules failed; see output above`,
   };
 }
+
+type AuditDeps = Parameters<typeof runAudit>[0];
+
+/**
+ * Build a fresh AuditDeps object whose module-state-dependent
+ * sub-deps are re-queried from the DB. The non-module deps
+ * (cliVersion fetcher, migrations, terraform plan runner, registry
+ * fetcher, etc.) are reused from the original deps because they
+ * don't change during a single system-update run.
+ *
+ * Used by the post-orchestrator re-audit so displayed findings
+ * reflect post-upgrade reality (e.g., a module_versions drift
+ * finding for a module we just upgraded is no longer reported).
+ */
+export function rebuildAuditDepsForRerun(
+  original: AuditDeps,
+  db: ReturnType<typeof getDb>,
+): AuditDeps {
+  const installed = db.select().from(modules).all();
+  const upgradeEligibleStates = new Set(['INSTALLED', 'VERIFIED', 'IMPORTED']);
+  const upgradable = installed.filter((m) => upgradeEligibleStates.has(m.state));
+
+  const allConfigs = db.select().from(moduleConfigsTbl).all();
+  const configsByModule = new Map<string, Record<string, unknown>>();
+  for (const c of allConfigs) {
+    const m = configsByModule.get(c.moduleId) ?? {};
+    m[c.key] = c.valueJson ? JSON.parse(c.valueJson) : c.value;
+    configsByModule.set(c.moduleId, m);
+  }
+
+  // Backup recency is unchanged across an orchestrator run (only
+  // celilo-DB snapshots happen, not per-module backup writes), so
+  // we look up each module's prior lastSuccessfulBackupAt by id
+  // rather than re-querying the backups table.
+  const priorBackupByModule = new Map<string, number | null>();
+  for (const b of original.backups.modules) {
+    priorBackupByModule.set(b.id, b.lastSuccessfulBackupAt);
+  }
+
+  return {
+    ...original,
+    capabilityAbi: {
+      modules: upgradable.map((m) => ({
+        id: m.id,
+        state: m.state,
+        manifest: m.manifestData as ModuleManifest,
+      })),
+    },
+    moduleVersions: {
+      ...original.moduleVersions,
+      installed: upgradable.map((m) => ({ id: m.id, version: m.version })),
+    },
+    moduleConfigs: {
+      modules: upgradable.map((m) => ({
+        id: m.id,
+        state: m.state,
+        manifest: m.manifestData as ModuleManifest,
+        configs: configsByModule.get(m.id) ?? {},
+      })),
+    },
+    backups: {
+      ...original.backups,
+      modules: upgradable.map((m) => ({
+        id: m.id,
+        state: m.state,
+        manifest: m.manifestData as ModuleManifest,
+        lastSuccessfulBackupAt: priorBackupByModule.get(m.id) ?? null,
+      })),
+    },
+    undeployedModules: {
+      modules: installed.map((m) => ({ id: m.id, state: m.state })),
+    },
+    unconfiguredModules: {
+      modules: installed.map((m) => ({
+        id: m.id,
+        state: m.state,
+        configCount: Object.keys(configsByModule.get(m.id) ?? {}).length,
+      })),
+    },
+  };
+}

package/src/services/audit/backups.test.ts

@@ -24,7 +24,10 @@ function makeModule(
     hooks: opts.hasBackupHook ? { on_backup: { script: './backup.ts' } } : {},
     backup: opts.schedule ? { schedule: opts.schedule } : undefined,
   } as unknown as ModuleManifest;
-  return { id, manifest, lastSuccessfulBackupAt: opts.lastSuccessfulBackupAt };
+  // Default to INSTALLED — existing tests assert backup findings
+  // fire, which is the deployed-module behavior. Tests for the
+  // non-deployed-skip behavior override this explicitly.
+  return { id, state: 'INSTALLED', manifest, lastSuccessfulBackupAt: opts.lastSuccessfulBackupAt };
 }
 
 describe('auditBackups', () => {
@@ -230,4 +233,24 @@ describe('auditBackups', () => {
     expect(result).toHaveLength(2);
     expect(result.map((f) => f.subject).sort()).toEqual(['authentik', 'homebridge']);
   });
+
+  // The regression: backups were complaining about IMPORTED modules
+  // having no successful backup. There's no live state on an
+  // IMPORTED module, so there's nothing to back up — skip entirely
+  // rather than emit a misleading finding.
+  test('skips non-deployed (IMPORTED) modules entirely', async () => {
+    const importedModule = {
+      ...makeModule('authentik', {
+        hasBackupHook: true,
+        lastSuccessfulBackupAt: null,
+        schedule: 'daily',
+      }),
+      state: 'IMPORTED',
+    };
+    const result = await auditBackups({
+      modules: [importedModule],
+      now: () => NOW,
+    });
+    expect(result).toEqual([]);
+  });
 });

package/src/services/audit/backups.ts

@@ -20,6 +20,8 @@ import type { DriftFinding } from './types';
 
 export interface InstalledModuleBackupInfo {
   id: string;
+  /** Lifecycle state — non-deployed modules have nothing to back up. */
+  state: string;
   manifest: ModuleManifest;
   /** Most recent successful backup timestamp (ms since epoch), or null. */
   lastSuccessfulBackupAt: number | null;
@@ -87,12 +89,20 @@ function formatAge(ms: number): string {
   return `${mins}m`;
 }
 
+const DEPLOYED_STATES = new Set(['INSTALLED', 'VERIFIED']);
+
 export async function auditBackups(deps: BackupsAuditDeps): Promise<DriftFinding[]> {
   const now = (deps.now ?? Date.now)();
   const findings: DriftFinding[] = [];
 
   for (const m of deps.modules) {
     if (!moduleHasBackupHook(m.manifest)) continue;
+    // Non-deployed modules have no live state to back up. Surfacing
+    // a "no successful backup recorded" finding for an IMPORTED
+    // module is just noise — the operator hasn't deployed yet, so
+    // there's nothing to lose. Skip them entirely from the backup
+    // audit.
+    if (!DEPLOYED_STATES.has(m.state)) continue;
 
     if (m.lastSuccessfulBackupAt === null) {
       findings.push({

package/src/services/audit/capability-abi.test.ts

@@ -23,7 +23,10 @@ function makeModule(
     requires: opts.requires ? { capabilities: opts.requires } : { capabilities: [] },
     optional: opts.optional ? { capabilities: opts.optional } : undefined,
   } as unknown as ModuleManifest;
-  return { id, manifest };
+  // Default INSTALLED so existing assertions keep their `blocked`
+  // semantics. Tests that exercise the IMPORTED-demotion path
+  // override the state explicitly.
+  return { id, state: 'INSTALLED', manifest };
 }
 
 const RUNTIME = {

package/src/services/audit/capability-abi.ts

@@ -26,9 +26,19 @@ import type { DriftFinding } from './types';
 
 export interface InstalledCapabilityModule {
   id: string;
+  /**
+   * Lifecycle state — used to demote ABI mismatches on IMPORTED-but-
+   * not-deployed modules from `blocked` to `todo`. The mismatch is
+   * still real (the operator will hit it at deploy time) but it
+   * doesn't block other module work, and gating system update on it
+   * makes refreshing unrelated modules harder than it should be.
+   */
+  state: string;
   manifest: ModuleManifest;
 }
 
+const DEPLOYED_STATES = new Set(['INSTALLED', 'VERIFIED']);
+
 export interface CapabilityAbiAuditDeps {
   modules: InstalledCapabilityModule[];
   /** Override the framework registry — for tests. Defaults to `CAPABILITY_CONTRACT_VERSIONS`. */
@@ -120,7 +130,11 @@ export async function auditCapabilityAbi(deps: CapabilityAbiAuditDeps): Promise<
 
       findings.push({
         category: 'capability_abi',
-        severity: 'blocked',
+        // Demoted to `todo` for non-deployed modules: the mismatch
+        // matters at deploy time, but blocking system update on it
+        // means the operator can't refresh unrelated modules until
+        // they fix the ABI for a module they haven't deployed yet.
+        severity: DEPLOYED_STATES.has(m.state) ? 'blocked' : 'todo',
         code: 'capability_abi_provider_mismatch',
         message: `${m.id} provides ${p.name}@${p.version} but framework runtime expects ${runtimeVersion}`,
         details,
@@ -190,7 +204,9 @@ export async function auditCapabilityAbi(deps: CapabilityAbiAuditDeps): Promise<
 
       findings.push({
         category: 'capability_abi',
-        severity: 'blocked',
+        // Same demotion as the provider check — non-deployed
+        // modules surface as todos rather than blockers.
+        severity: DEPLOYED_STATES.has(m.state) ? 'blocked' : 'todo',
         code: 'capability_abi_consumer_mismatch',
         message: `${m.id} requires ${need.name}@${need.version} but ${provider.moduleId} provides ${provider.version}`,
         details,

package/src/services/audit/module-configs.test.ts

@@ -24,7 +24,10 @@ function makeModule(
     celilo_contract: '1.0',
     variables: { owns: variables, imports: [] },
   } as unknown as ModuleManifest;
-  return { id, manifest, configs };
+  // Default state INSTALLED so existing tests continue to expect
+  // `blocked` severity. Tests that exercise the IMPORTED path
+  // override the state explicitly.
+  return { id, state: 'INSTALLED', manifest, configs };
 }
 
 describe('auditModuleConfigs', () => {
@@ -128,4 +131,47 @@ describe('auditModuleConfigs', () => {
     expect(result).toHaveLength(1);
     expect(result[0].subject).toBe('caddy');
   });
+
+  // The exact regression the operator hit on celilo-mgmt: required
+  // configs missing on IMPORTED-but-not-yet-deployed modules used to
+  // surface as `blocked`, gating system update entirely. The deploy
+  // interview collects them at deploy time, so they're todos here.
+  test('IMPORTED module with missing required config → todo, not blocked', async () => {
+    const moduleWithImportedState = {
+      ...makeModule('namecheap', [makeVariable({ name: 'domains', required: true })], {}),
+      state: 'IMPORTED',
+    };
+    const result = await auditModuleConfigs({
+      modules: [moduleWithImportedState],
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].severity).toBe('todo');
+    // Remediation also flips: don't tell the operator to manually
+    // `module config set` (the deploy interview is the right path).
+    expect(result[0].remediation).toBe('celilo module deploy namecheap');
+  });
+
+  test('VALIDATED / GENERATING / other pre-deploy states also demote to todo', async () => {
+    const validated = {
+      ...makeModule('foo', [makeVariable({ name: 'x', required: true })], {}),
+      state: 'VALIDATED',
+    };
+    const generating = {
+      ...makeModule('bar', [makeVariable({ name: 'x', required: true })], {}),
+      state: 'GENERATING',
+    };
+    const result = await auditModuleConfigs({ modules: [validated, generating] });
+    expect(result).toHaveLength(2);
+    expect(result.every((f) => f.severity === 'todo')).toBe(true);
+  });
+
+  test('VERIFIED state stays blocked (deployed module)', async () => {
+    const verified = {
+      ...makeModule('caddy', [makeVariable({ name: 'acme_email', required: true })], {}),
+      state: 'VERIFIED',
+    };
+    const result = await auditModuleConfigs({ modules: [verified] });
+    expect(result).toHaveLength(1);
+    expect(result[0].severity).toBe('blocked');
+  });
 });

package/src/services/audit/module-configs.ts

@@ -8,20 +8,30 @@
  * the user.
  *
  * Severity rules:
- * - `required: true` AND no current value AND no `default:` → BLOCKED
- *   (the user has to set it; `system update` would otherwise fail at
- *   deploy time anyway).
- * - All other unset cases → no finding. An optional variable with a
- *   default is by definition fine when unset (the default applies);
- *   a required variable with a default is also fine (the default
- *   resolves the value). Either case as drift would just be noise.
+ * - DEPLOYED module (state=INSTALLED|VERIFIED) with `required: true`
+ *   AND no current value AND no `default:` → BLOCKED. The module is
+ *   live and a config gap is a real divergence: the next deploy
+ *   would fail, capability consumers may be reading the unset value,
+ *   etc.
+ * - NON-DEPLOYED module (IMPORTED, etc.) → TODO. The deploy
+ *   interview will collect required values when the operator
+ *   eventually runs `module deploy`. Telling them to manually
+ *   `module config set` is bad UX — the interview is the canonical
+ *   path. Surfacing as TODO keeps the visibility without escalating
+ *   the verdict.
+ * - Variable has a `default:` (any state) → no finding. The default
+ *   resolves the value.
  */
 
 import type { ModuleManifest, VariableDeclare } from '../../manifest/schema';
 import type { DriftFinding } from './types';
 
+const DEPLOYED_STATES = new Set(['INSTALLED', 'VERIFIED']);
+
 export interface InstalledModuleConfig {
   id: string;
+  /** Lifecycle state from the modules table — drives severity. */
+  state: string;
   manifest: ModuleManifest;
   /** Map of config key → current value (string for primitives, parsed object for complex). */
   configs: Record<string, unknown>;
@@ -37,6 +47,7 @@ function isUnset(value: unknown): boolean {
 
 function ownVariableFindings(
   moduleId: string,
+  state: string,
   variable: VariableDeclare,
   currentValue: unknown,
 ): DriftFinding[] {
@@ -47,23 +58,30 @@ function ownVariableFindings(
   if (!isUnset(currentValue)) return [];
 
   const hasDefault = variable.default !== undefined && variable.default !== null;
+  if (!variable.required || hasDefault) return [];
 
-  if (variable.required && !hasDefault) {
-    return [
-      {
-        category: 'module_configs',
-        severity: 'blocked',
-        code: 'module_config_required_unset',
-        message: `${moduleId}: required config "${variable.name}" is not set`,
-        details: variable.description,
-        remediation: `celilo module config set ${moduleId} ${variable.name} <value>`,
-        actionable: true,
-        subject: moduleId,
-      },
-    ];
-  }
+  // BLOCKED only when the module is currently deployed. For
+  // IMPORTED-and-similar pre-deploy states, the deploy interview
+  // collects this value automatically — surfacing as a blocker
+  // wrongly directs the operator at `module config set` (a manual
+  // workaround) when the right command is `module deploy <id>`.
+  const severity = DEPLOYED_STATES.has(state) ? 'blocked' : 'todo';
+  const remediation = DEPLOYED_STATES.has(state)
+    ? `celilo module config set ${moduleId} ${variable.name} <value>`
+    : `celilo module deploy ${moduleId}`;
 
-  return [];
+  return [
+    {
+      category: 'module_configs',
+      severity,
+      code: 'module_config_required_unset',
+      message: `${moduleId}: required config "${variable.name}" is not set`,
+      details: variable.description,
+      remediation,
+      actionable: true,
+      subject: moduleId,
+    },
+  ];
 }
 
 export async function auditModuleConfigs(deps: ModuleConfigsAuditDeps): Promise<DriftFinding[]> {
@@ -72,7 +90,7 @@ export async function auditModuleConfigs(deps: ModuleConfigsAuditDeps): Promise<
   for (const m of deps.modules) {
     const owned = m.manifest.variables?.owns ?? [];
     for (const variable of owned) {
-      findings.push(...ownVariableFindings(m.id, variable, m.configs[variable.name]));
+      findings.push(...ownVariableFindings(m.id, m.state, variable, m.configs[variable.name]));
     }
   }