@celilo/cli 0.1.5 → 0.1.7

package/src/services/audit/services-reachable.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test';
+import { auditServicesReachable } from './services-reachable';
+
+describe('auditServicesReachable', () => {
+  test('no findings when every service is reachable', async () => {
+    const result = await auditServicesReachable({
+      results: [
+        {
+          serviceId: 'home-proxmox',
+          name: 'Home Proxmox',
+          providerName: 'proxmox',
+          reachable: true,
+        },
+        { serviceId: 'do', name: 'DigitalOcean', providerName: 'digitalocean', reachable: true },
+      ],
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('drift finding per unreachable service', async () => {
+    const result = await auditServicesReachable({
+      results: [
+        {
+          serviceId: 'home-proxmox',
+          name: 'Home Proxmox',
+          providerName: 'proxmox',
+          reachable: false,
+          message: 'Connection refused',
+        },
+      ],
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      category: 'services_reachable',
+      severity: 'drift',
+      code: 'service_unreachable',
+      subject: 'home-proxmox',
+      actionable: false,
+    });
+    expect(result[0].message).toContain('Home Proxmox');
+    expect(result[0].details).toContain('Connection refused');
+    expect(result[0].remediation).toContain('celilo service set-credentials home-proxmox');
+  });
+
+  test('mixed report — only failures produce findings', async () => {
+    const result = await auditServicesReachable({
+      results: [
+        { serviceId: 'good', name: 'Good', providerName: 'proxmox', reachable: true },
+        {
+          serviceId: 'bad',
+          name: 'Bad',
+          providerName: 'proxmox',
+          reachable: false,
+          message: 'oops',
+        },
+      ],
+    });
+    expect(result.map((f) => f.subject)).toEqual(['bad']);
+  });
+});

package/src/services/audit/services-reachable.ts

@@ -0,0 +1,64 @@
+/**
+ * Services-reachable check.
+ *
+ * For each container service, attempts a low-cost API ping
+ * (Proxmox `/version`, DigitalOcean `/v2/account`). Catches:
+ *
+ * - Service host down or behind a firewall.
+ * - API token revoked or expired.
+ * - Wrong endpoint URL.
+ *
+ * Severity is `drift` rather than `blocked` — a deploy can still
+ * succeed if the operator restarts the service or fixes the
+ * network before retrying. Surfacing here just gives the user
+ * earlier signal than a deploy-time timeout.
+ *
+ * Like `services_credentials`, the audit consumes pre-computed
+ * results so it stays unit-testable without hitting a real API.
+ */
+
+import type { DriftFinding } from './types';
+
+export interface ServiceReachableResult {
+  /** User-facing kebab-case service ID. */
+  serviceId: string;
+  /** Display name for the finding message. */
+  name: string;
+  providerName: string;
+  /** True if the API ping succeeded. */
+  reachable: boolean;
+  /** Short description of failure when `!reachable`. */
+  message?: string;
+}
+
+export interface ServicesReachableAuditDeps {
+  results: ServiceReachableResult[];
+}
+
+export async function auditServicesReachable(
+  deps: ServicesReachableAuditDeps,
+): Promise<DriftFinding[]> {
+  const findings: DriftFinding[] = [];
+
+  for (const r of deps.results) {
+    if (r.reachable) continue;
+
+    findings.push({
+      category: 'services_reachable',
+      severity: 'drift',
+      code: 'service_unreachable',
+      message: `${r.name} (${r.providerName}): API unreachable`,
+      details: r.message,
+      remediation: [
+        'Verify the service host is up and the API endpoint is',
+        'correct. If the API token was rotated, re-set it:',
+        `  celilo service set-credentials ${r.serviceId}`,
+      ].join('\n'),
+      // Diagnostic / interactive — no one-shot fix.
+      actionable: false,
+      subject: r.serviceId,
+    });
+  }
+
+  return findings;
+}

package/src/services/audit/terraform-plan.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from 'bun:test';
+import { type TerraformPlanRunner, auditTerraformPlan, parsePlanSummary } from './terraform-plan';
+
+describe('parsePlanSummary', () => {
+  test('parses a typical Plan summary line', () => {
+    const stdout = `
+Terraform will perform the following actions:
+...
+Plan: 2 to add, 1 to change, 3 to destroy.
+`;
+    expect(parsePlanSummary(stdout)).toEqual({ add: 2, change: 1, destroy: 3 });
+  });
+
+  test('treats "No changes." as zero plan', () => {
+    expect(parsePlanSummary('No changes. Your infrastructure matches the configuration.')).toEqual({
+      add: 0,
+      change: 0,
+      destroy: 0,
+    });
+  });
+
+  test('strips ANSI color codes', () => {
+    const stdout = 'Plan: 1 to add, 0 to change, 0 to destroy.';
+    expect(parsePlanSummary(stdout)).toEqual({ add: 1, change: 0, destroy: 0 });
+  });
+
+  test('returns null when no recognized pattern is present', () => {
+    expect(parsePlanSummary('something went sideways')).toBeNull();
+  });
+});
+
+describe('auditTerraformPlan', () => {
+  const noChange: TerraformPlanRunner = async () => ({
+    exitCode: 0,
+    stdout: 'No changes. Your infrastructure matches the configuration.',
+    stderr: '',
+  });
+
+  test('skips modules without a terraform dir', async () => {
+    const result = await auditTerraformPlan({
+      modules: [{ id: 'caddy', terraformDir: null }],
+      run: noChange,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('no finding when plan is empty', async () => {
+    const result = await auditTerraformPlan({
+      modules: [{ id: 'caddy', terraformDir: '/tf/caddy' }],
+      run: noChange,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('drift finding for additive plan (no destroys)', async () => {
+    const run: TerraformPlanRunner = async () => ({
+      exitCode: 2,
+      stdout: 'Plan: 1 to add, 0 to change, 0 to destroy.',
+      stderr: '',
+    });
+    const result = await auditTerraformPlan({
+      modules: [{ id: 'caddy', terraformDir: '/tf/caddy' }],
+      run,
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      severity: 'drift',
+      code: 'terraform_plan_pending',
+      subject: 'caddy',
+    });
+    expect(result[0].message).toContain('+1 ~0');
+  });
+
+  test('blocked finding for destructive plan', async () => {
+    const run: TerraformPlanRunner = async () => ({
+      exitCode: 2,
+      stdout: 'Plan: 0 to add, 1 to change, 2 to destroy.',
+      stderr: '',
+    });
+    const result = await auditTerraformPlan({
+      modules: [{ id: 'caddy', terraformDir: '/tf/caddy' }],
+      run,
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      severity: 'blocked',
+      code: 'terraform_plan_destructive',
+    });
+    expect(result[0].message).toContain('would destroy 2 resources');
+    expect(result[0].remediation).toContain('--allow-destructive');
+  });
+
+  test('drift finding when terraform plan command fails', async () => {
+    const run: TerraformPlanRunner = async () => ({
+      exitCode: 1,
+      stdout: '',
+      stderr: 'Error: provider authentication failed',
+    });
+    const result = await auditTerraformPlan({
+      modules: [{ id: 'caddy', terraformDir: '/tf/caddy' }],
+      run,
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      severity: 'drift',
+      code: 'terraform_plan_failed',
+    });
+    expect(result[0].details).toContain('provider authentication failed');
+  });
+
+  test('singular wording for exactly one destroy', async () => {
+    const run: TerraformPlanRunner = async () => ({
+      exitCode: 2,
+      stdout: 'Plan: 0 to add, 0 to change, 1 to destroy.',
+      stderr: '',
+    });
+    const result = await auditTerraformPlan({
+      modules: [{ id: 'caddy', terraformDir: '/tf/caddy' }],
+      run,
+    });
+    expect(result[0].message).toContain('would destroy 1 resource (');
+    expect(result[0].message).not.toContain('1 resources');
+  });
+});

package/src/services/audit/terraform-plan.ts

@@ -0,0 +1,153 @@
+/**
+ * Terraform plan drift check.
+ *
+ * For each installed module that has a generated terraform directory,
+ * run `terraform plan -detailed-exitcode -no-color` and parse the
+ * summary line ("Plan: 1 to add, 0 to change, 2 to destroy."). A plan
+ * that includes destructive operations (delete/replace) produces a
+ * `blocked` finding — `system update` would otherwise silently let
+ * Terraform delete an LXC the user didn't expect to lose. A
+ * non-destructive plan (additions / in-place changes only) produces
+ * a `drift` finding.
+ *
+ * The shell runner is injectable so unit tests assert on parsing
+ * logic without invoking the real `terraform` binary.
+ */
+
+import type { DriftFinding } from './types';
+
+export interface TerraformPlanModule {
+  id: string;
+  /** Path to the module's generated terraform dir, or null if not yet generated. */
+  terraformDir: string | null;
+  /**
+   * Provider credentials to inject as `TF_VAR_*` env vars. Empty
+   * for machine-pool deployments; populated from container-service
+   * credentials for Proxmox/DigitalOcean modules. Mirrors what
+   * `module deploy` injects so the audit's plan check sees the same
+   * world the deployer would.
+   */
+  envVars?: Record<string, string>;
+}
+
+export interface TerraformPlanRunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export type TerraformPlanRunner = (
+  terraformDir: string,
+  envVars?: Record<string, string>,
+) => Promise<TerraformPlanRunResult>;
+
+export interface TerraformPlanAuditDeps {
+  modules: TerraformPlanModule[];
+  run: TerraformPlanRunner;
+}
+
+/**
+ * Parses the typical "Plan: N to add, M to change, K to destroy."
+ * line in `terraform plan` output. Returns null if no Plan: line is
+ * found (e.g., empty plan, or Terraform output format changed).
+ */
+export interface PlanSummary {
+  add: number;
+  change: number;
+  destroy: number;
+}
+
+// Built from a string at runtime so biome's "control character in
+// regex literal" rule doesn't flag the embedded ESC byte. ANSI CSI
+// sequences are `ESC [ params m`.
+const ANSI_COLOR_RE = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-9;]*m`, 'g');
+
+export function parsePlanSummary(stdout: string): PlanSummary | null {
+  // Terraform may colorize even with -no-color in some setups; strip ANSI defensively.
+  const stripped = stdout.replace(ANSI_COLOR_RE, '');
+  const match = stripped.match(
+    /Plan:\s+(\d+)\s+to\s+add,\s+(\d+)\s+to\s+change,\s+(\d+)\s+to\s+destroy\b/,
+  );
+  if (!match) {
+    // Empty plan — terraform sometimes prints "No changes." instead.
+    if (/No changes\.|Your infrastructure matches the configuration/.test(stripped)) {
+      return { add: 0, change: 0, destroy: 0 };
+    }
+    return null;
+  }
+  return {
+    add: Number.parseInt(match[1], 10),
+    change: Number.parseInt(match[2], 10),
+    destroy: Number.parseInt(match[3], 10),
+  };
+}
+
+export async function auditTerraformPlan(deps: TerraformPlanAuditDeps): Promise<DriftFinding[]> {
+  const findings: DriftFinding[] = [];
+
+  for (const m of deps.modules) {
+    if (m.terraformDir === null) continue;
+
+    const result = await deps.run(m.terraformDir, m.envVars);
+
+    // Exit code 0 = no changes; 2 = changes pending; anything else = error
+    if (result.exitCode !== 0 && result.exitCode !== 2) {
+      findings.push({
+        category: 'terraform_plan',
+        severity: 'drift',
+        code: 'terraform_plan_failed',
+        message: `${m.id}: terraform plan failed (exit ${result.exitCode})`,
+        details: (result.stderr || result.stdout).slice(0, 500),
+        remediation: [
+          'Inspect the error above, then re-run terraform plan in',
+          m.terraformDir,
+          'to debug. Common causes: missing provider credentials,',
+          'broken state, expired tokens.',
+        ].join('\n'),
+        // Investigatory; no single celilo command resolves it.
+        actionable: false,
+        subject: m.id,
+      });
+      continue;
+    }
+
+    const summary = parsePlanSummary(result.stdout);
+    if (!summary || (summary.add === 0 && summary.change === 0 && summary.destroy === 0)) {
+      // Plan is empty or unparseable-but-non-error — no drift.
+      continue;
+    }
+
+    if (summary.destroy > 0) {
+      findings.push({
+        category: 'terraform_plan',
+        severity: 'blocked',
+        code: 'terraform_plan_destructive',
+        message: `${m.id}: terraform plan would destroy ${summary.destroy} resource${summary.destroy === 1 ? '' : 's'} (+${summary.add} ~${summary.change})`,
+        remediation: [
+          'Review the plan carefully. If the destruction is intended,',
+          'run:',
+          '  celilo system update --allow-destructive',
+          'Otherwise investigate why the plan wants to destroy',
+          'resources before proceeding.',
+        ].join('\n'),
+        // The opt-in flag and review step make this a deliberately
+        // non-one-click finding — surfacing the modal would let users
+        // accidentally fire a destructive update.
+        actionable: false,
+        subject: m.id,
+      });
+    } else {
+      findings.push({
+        category: 'terraform_plan',
+        severity: 'drift',
+        code: 'terraform_plan_pending',
+        message: `${m.id}: terraform plan has +${summary.add} ~${summary.change} changes pending`,
+        remediation: `celilo module deploy ${m.id}`,
+        actionable: true,
+        subject: m.id,
+      });
+    }
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,36 @@
+import { describe, expect, test } from 'bun:test';
+import { type DriftFinding, computeVerdict } from './types';
+
+const drift: DriftFinding = {
+  category: 'module_versions',
+  severity: 'drift',
+  code: 'module_version_drift',
+  message: 'caddy: 1.2.0 → 1.3.0 available',
+  subject: 'caddy',
+};
+
+const blocked: DriftFinding = {
+  category: 'capability_abi',
+  severity: 'blocked',
+  code: 'capability_abi_mismatch',
+  message: 'lunacycle requires public_web@2 but caddy provides 1',
+  subject: 'lunacycle',
+};
+
+describe('computeVerdict', () => {
+  test('READY when no findings', () => {
+    expect(computeVerdict([])).toBe('READY');
+  });
+
+  test('DRIFT when only drift-severity findings', () => {
+    expect(computeVerdict([drift, { ...drift, subject: 'iptables' }])).toBe('DRIFT');
+  });
+
+  test('BLOCKED when any finding is blocked', () => {
+    expect(computeVerdict([drift, blocked])).toBe('BLOCKED');
+  });
+
+  test('BLOCKED takes precedence regardless of order', () => {
+    expect(computeVerdict([blocked, drift])).toBe('BLOCKED');
+  });
+});

package/src/services/audit/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Types for the system-wide drift audit (CELILO_UPDATE D6).
+ *
+ * `runAudit` returns a `SystemAuditReport` aggregating findings from
+ * each drift category. Each finding has a category (one of
+ * `DriftCategory`), a severity (`drift` or `blocked`), a stable
+ * machine-readable code, and a human-readable message + suggested
+ * remediation.
+ *
+ * The overall verdict is computed from the findings:
+ * - any `blocked` finding → BLOCKED
+ * - any `drift` finding (no blocked) → DRIFT
+ * - no findings → READY
+ */
+
+export type DriftCategory =
+  | 'cli_version'
+  | 'schema'
+  | 'capability_abi'
+  | 'terraform_plan'
+  | 'module_versions'
+  | 'module_configs'
+  | 'health'
+  | 'backups'
+  | 'undeployed_modules'
+  | 'unconfigured_modules'
+  | 'services_credentials'
+  | 'secrets_decryptable'
+  | 'services_reachable'
+  | 'machines_reachable';
+
+export type DriftSeverity = 'drift' | 'blocked';
+
+export type AuditVerdict = 'READY' | 'DRIFT' | 'BLOCKED';
+
+/**
+ * A single drift finding produced by a category check.
+ *
+ * - `category`: which check produced this
+ * - `severity`: whether it gates `system update` or just informs
+ * - `code`: stable machine-readable identifier (e.g. `module_version_drift`),
+ *   intended for `--json` consumers
+ * - `message`: short, human-readable description
+ * - `details`: optional multi-line elaboration (e.g. release messages
+ *   between two versions, or step-by-step guidance for non-actionable
+ *   findings)
+ * - `remediation`: suggested next action — either a runnable
+ *   `celilo …` command (when `actionable: true`) or human-facing
+ *   guidance prose (when `actionable: false`)
+ * - `actionable`: when `true`, `remediation` is a runnable
+ *   `celilo …` command and the TUI surfaces a one-keypress
+ *   "Remediate" modal. When `false`, `remediation` is descriptive
+ *   guidance and the modal is suppressed (the user has to do code
+ *   work, edit a config file, or run something outside celilo).
+ *   Default is `false` — conservative, since a non-runnable
+ *   remediation surfaced as runnable would crash on submit.
+ * - `subject`: the entity the finding is about — usually a module ID,
+ *   capability name, or `'system'`. Lets the UI group findings.
+ */
+export interface DriftFinding {
+  category: DriftCategory;
+  severity: DriftSeverity;
+  code: string;
+  message: string;
+  details?: string;
+  remediation?: string;
+  actionable?: boolean;
+  subject: string;
+}
+
+/**
+ * The aggregated report. Stable JSON shape — do not break consumers.
+ *
+ * `version` is bumped on incompatible schema changes to this object.
+ */
+export interface SystemAuditReport {
+  version: 1;
+  verdict: AuditVerdict;
+  generatedAt: string; // ISO-8601 UTC
+  findings: DriftFinding[];
+}
+
+/**
+ * Compute the overall verdict from a set of findings.
+ */
+export function computeVerdict(findings: DriftFinding[]): AuditVerdict {
+  if (findings.some((f) => f.severity === 'blocked')) return 'BLOCKED';
+  if (findings.length > 0) return 'DRIFT';
+  return 'READY';
+}

package/src/services/audit/unconfigured-modules.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test';
+import { auditUnconfiguredModules } from './unconfigured-modules';
+
+describe('auditUnconfiguredModules', () => {
+  test('flags IMPORTED module with zero config rows', async () => {
+    const result = await auditUnconfiguredModules({
+      modules: [{ id: 'authentik', state: 'IMPORTED', configCount: 0 }],
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      category: 'unconfigured_modules',
+      severity: 'drift',
+      code: 'module_unconfigured',
+      actionable: false,
+      subject: 'authentik',
+    });
+    expect(result[0].details).toContain('celilo module config get authentik');
+  });
+
+  test('skips module with at least one config row', async () => {
+    const result = await auditUnconfiguredModules({
+      modules: [{ id: 'authentik', state: 'IMPORTED', configCount: 3 }],
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('skips deployed modules even with zero config rows', async () => {
+    const result = await auditUnconfiguredModules({
+      modules: [
+        { id: 'caddy', state: 'INSTALLED', configCount: 0 },
+        { id: 'iptables', state: 'VERIFIED', configCount: 0 },
+      ],
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('mixed report — only flags qualifying modules', async () => {
+    const result = await auditUnconfiguredModules({
+      modules: [
+        { id: 'caddy', state: 'INSTALLED', configCount: 0 }, // skip — deployed
+        { id: 'authentik', state: 'IMPORTED', configCount: 0 }, // flag
+        { id: 'iptables', state: 'IMPORTED', configCount: 5 }, // skip — has configs
+        { id: 'lunacycle', state: 'VALIDATED', configCount: 0 }, // flag
+      ],
+    });
+    expect(result.map((f) => f.subject).sort()).toEqual(['authentik', 'lunacycle']);
+  });
+});

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

@@ -0,0 +1,71 @@
+/**
+ * Unconfigured-modules check.
+ *
+ * Modules that are imported (or further along the lifecycle) but
+ * have *zero* config rows in the DB — i.e. the user has never run
+ * the configuration interview. Even if all of the module's required
+ * config has defaults, never having gone through the interview is a
+ * useful signal: it means the user hasn't reviewed what's there.
+ *
+ * Reported per-module rather than rolled into `module_configs`
+ * findings so the user sees "X has never been configured" as a
+ * single category, not as N individual missing-required findings.
+ *
+ * `INSTALLED` and `VERIFIED` modules are skipped — they were
+ * configured at deploy time, even if rows have since been deleted.
+ * This check is for *new* imports that haven't been touched yet.
+ */
+
+import type { DriftFinding } from './types';
+
+export interface UnconfiguredModule {
+  id: string;
+  /** Lifecycle state from the modules table (IMPORTED, VALIDATED, …). */
+  state: string;
+  /** Total number of config rows recorded for this module. */
+  configCount: number;
+}
+
+export interface UnconfiguredModulesAuditDeps {
+  modules: UnconfiguredModule[];
+}
+
+const ALREADY_DEPLOYED = new Set(['INSTALLED', 'VERIFIED']);
+
+export async function auditUnconfiguredModules(
+  deps: UnconfiguredModulesAuditDeps,
+): Promise<DriftFinding[]> {
+  const findings: DriftFinding[] = [];
+
+  for (const m of deps.modules) {
+    if (ALREADY_DEPLOYED.has(m.state)) continue;
+    if (m.configCount > 0) continue;
+
+    findings.push({
+      category: 'unconfigured_modules',
+      severity: 'drift',
+      code: 'module_unconfigured',
+      message: `${m.id}: never configured (no config rows in DB)`,
+      details: [
+        'Module was imported but the configuration interview has not',
+        'been run. Defaults will apply for any unset values when you',
+        'deploy, but reviewing what knobs exist first is recommended.',
+        '',
+        'To review:',
+        `  celilo module config get ${m.id}`,
+        '',
+        'To set values manually:',
+        `  celilo module config set ${m.id} <key> <value>`,
+        '',
+        'Or just run `module deploy` — it triggers the interview',
+        'automatically if required values are missing.',
+      ].join('\n'),
+      // Not a one-shot — there's no single celilo command to "configure"
+      // a module. Surfacing the modal would mislead.
+      actionable: false,
+      subject: m.id,
+    });
+  }
+
+  return findings;
+}