@celilo/cli 0.1.5 → 0.1.7

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

@@ -0,0 +1,204 @@
+/**
+ * Capability ABI compatibility check (CELILO_UPDATE D4).
+ *
+ * For each installed module, compares the version it claims for each
+ * capability (in `provides` / `requires`) against:
+ *   - the framework's runtime registry (`CAPABILITY_CONTRACT_VERSIONS`),
+ *     for providers
+ *   - the actually-deployed provider's claimed version, for consumers
+ *
+ * Mismatches produce `blocked` findings with concrete remediation
+ * (rebuild the provider, upgrade the consumer, etc.).
+ */
+
+import {
+  CAPABILITY_CONTRACT_VERSIONS,
+  type KnownCapabilityName,
+  compareConsumerToProvider,
+  compareProviderToRuntime,
+} from '@celilo/capabilities';
+import type {
+  CapabilityProvider,
+  CapabilityRequirement,
+  ModuleManifest,
+} from '../../manifest/schema';
+import type { DriftFinding } from './types';
+
+export interface InstalledCapabilityModule {
+  id: string;
+  manifest: ModuleManifest;
+}
+
+export interface CapabilityAbiAuditDeps {
+  modules: InstalledCapabilityModule[];
+  /** Override the framework registry — for tests. Defaults to `CAPABILITY_CONTRACT_VERSIONS`. */
+  contractVersions?: Record<string, string>;
+}
+
+function isKnownCapability(name: string): name is KnownCapabilityName {
+  return name in CAPABILITY_CONTRACT_VERSIONS;
+}
+
+interface ProviderClaim {
+  capability: string;
+  version: string;
+  moduleId: string;
+}
+
+function collectProviders(modules: InstalledCapabilityModule[]): Map<string, ProviderClaim> {
+  // capability name → { module that provides it, version it claims }.
+  // If multiple modules provide the same capability, the first one wins
+  // for the audit's consumer-vs-provider check; the framework's
+  // capability-loader handles real provider selection elsewhere.
+  const map = new Map<string, ProviderClaim>();
+  for (const m of modules) {
+    const provides: CapabilityProvider[] = m.manifest.provides?.capabilities ?? [];
+    for (const p of provides) {
+      if (!map.has(p.name)) {
+        map.set(p.name, { capability: p.name, version: p.version, moduleId: m.id });
+      }
+    }
+  }
+  return map;
+}
+
+export async function auditCapabilityAbi(deps: CapabilityAbiAuditDeps): Promise<DriftFinding[]> {
+  const findings: DriftFinding[] = [];
+  const contractVersions = deps.contractVersions ?? CAPABILITY_CONTRACT_VERSIONS;
+  const providers = collectProviders(deps.modules);
+
+  // 1. Provider checks: each `provides[X].version` must match the
+  //    framework's runtime registry (within compareProviderToRuntime's rules).
+  for (const m of deps.modules) {
+    const provides: CapabilityProvider[] = m.manifest.provides?.capabilities ?? [];
+    for (const p of provides) {
+      if (!isKnownCapability(p.name)) {
+        // Capability isn't registered in the framework — that's fine
+        // (third-party / well-known-extension scenario).
+        continue;
+      }
+      const runtimeVersion = contractVersions[p.name];
+      const result = compareProviderToRuntime(p.version, runtimeVersion);
+      if (result.compatible) continue;
+
+      const isFrameworkBehind = result.reason === 'major_mismatch_higher';
+      const details = isFrameworkBehind
+        ? [
+            'ABI = Application Binary Interface — the contract between',
+            'the celilo framework and a module for a given capability',
+            '(method names, argument shapes, return values).',
+            '',
+            `${m.id} expects ${p.name}@${p.version} but the running`,
+            `framework only ships ${p.name}@${runtimeVersion}.`,
+            '',
+            'To fix:',
+            '  1. Upgrade celilo:  bun update -g @celilo/cli',
+            '     (or `git pull && bun install` in this repo)',
+            '  2. Re-run system audit',
+            '',
+            'This is a code-level mismatch — there is no single CLI',
+            'command that can resolve it.',
+          ].join('\n')
+        : [
+            'ABI = Application Binary Interface — the contract between',
+            'the celilo framework and a module for a given capability',
+            '(method names, argument shapes, return values).',
+            '',
+            `${m.id} was built against ${p.name}@${p.version} but the`,
+            `framework now expects ${p.name}@${runtimeVersion}.`,
+            '',
+            'To fix:',
+            `  1. cd modules/${m.id}`,
+            '  2. Update the @celilo/capabilities dep to match the runtime',
+            '  3. bun run build',
+            '  4. Republish (or reinstall locally with `module import`)',
+            '  5. Re-run system audit',
+            '',
+            'This is a code-level mismatch — there is no single CLI',
+            'command that can resolve it.',
+          ].join('\n');
+
+      findings.push({
+        category: 'capability_abi',
+        severity: 'blocked',
+        code: 'capability_abi_provider_mismatch',
+        message: `${m.id} provides ${p.name}@${p.version} but framework runtime expects ${runtimeVersion}`,
+        details,
+        actionable: false,
+        subject: m.id,
+      });
+    }
+  }
+
+  // 2. Consumer checks: each `requires[X].version` must be satisfied by
+  //    the actual provider's `provides[X].version`.
+  for (const m of deps.modules) {
+    const requires: CapabilityRequirement[] = m.manifest.requires?.capabilities ?? [];
+    const optional: CapabilityRequirement[] = m.manifest.optional?.capabilities ?? [];
+
+    for (const need of [...requires, ...optional]) {
+      const provider = providers.get(need.name);
+      if (!provider) {
+        // No installed provider for this capability — that's a deploy-time
+        // concern, not an ABI concern. The deploy preflight handles missing
+        // providers; we skip here.
+        continue;
+      }
+      const result = compareConsumerToProvider(need.version, provider.version);
+      if (result.compatible) continue;
+
+      const providerTooOld = result.reason === 'caller_minor_too_old';
+      const details = providerTooOld
+        ? [
+            'ABI = Application Binary Interface — the contract between',
+            'modules for a given capability (method names, argument',
+            'shapes, return values).',
+            '',
+            `${m.id} requires ${need.name}@${need.version} but the`,
+            `installed provider ${provider.moduleId} only offers`,
+            `${provider.version}.`,
+            '',
+            'To fix:',
+            `  1. Upgrade ${provider.moduleId} to a version that provides`,
+            `     ${need.name}@${need.version} or newer (compatible major)`,
+            '  2. Re-run system audit',
+            '',
+            'This is a code-level mismatch — there is no single CLI',
+            'command that can resolve it.',
+          ].join('\n')
+        : [
+            'ABI = Application Binary Interface — the contract between',
+            'modules for a given capability (method names, argument',
+            'shapes, return values).',
+            '',
+            `${m.id} was built against ${need.name}@${need.version} but`,
+            `${provider.moduleId} now provides ${provider.version} on a`,
+            'different major. The interface has changed in an',
+            'incompatible way.',
+            '',
+            'To fix:',
+            `  1. cd modules/${m.id}`,
+            `  2. Update its requires entry for ${need.name} to match`,
+            `     ${provider.moduleId}'s major (${provider.version})`,
+            '  3. Adjust the module code if the interface changed',
+            '  4. bun run build && republish',
+            '  5. Re-run system audit',
+            '',
+            'This is a code-level mismatch — there is no single CLI',
+            'command that can resolve it.',
+          ].join('\n');
+
+      findings.push({
+        category: 'capability_abi',
+        severity: 'blocked',
+        code: 'capability_abi_consumer_mismatch',
+        message: `${m.id} requires ${need.name}@${need.version} but ${provider.moduleId} provides ${provider.version}`,
+        details,
+        actionable: false,
+        subject: m.id,
+      });
+    }
+  }
+
+  return findings;
+}

package/src/services/audit/cli-version.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test';
+import { auditCliVersion, compareSemver } from './cli-version';
+
+describe('compareSemver', () => {
+  test.each([
+    ['1.0.0', '1.0.0', 0],
+    ['1.0.0', '1.0.1', -1],
+    ['1.0.1', '1.0.0', 1],
+    ['1.0.0', '2.0.0', -1],
+    ['2.0.0', '1.9.9', 1],
+    ['v1.0.0', '1.0.0', 0],
+    ['1.0.0-beta.1', '1.0.0', 0], // pre-release stripped
+    ['1.0.0+build.42', '1.0.0', 0], // build metadata stripped
+  ])('compareSemver(%s, %s) = %s', (a, b, expected) => {
+    expect(compareSemver(a, b)).toBe(expected);
+  });
+});
+
+describe('auditCliVersion', () => {
+  test('no finding when running version equals latest', async () => {
+    const result = await auditCliVersion({
+      installedVersion: '0.1.5',
+      fetcher: async () => '0.1.5',
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('no finding when running ahead of latest (dev build)', async () => {
+    const result = await auditCliVersion({
+      installedVersion: '0.2.0-dev',
+      fetcher: async () => '0.1.5',
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('drift finding when published is newer', async () => {
+    const result = await auditCliVersion({
+      installedVersion: '0.1.5',
+      fetcher: async () => '0.1.7',
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      category: 'cli_version',
+      severity: 'drift',
+      code: 'cli_version_drift',
+      subject: 'system',
+    });
+    expect(result[0].message).toContain('0.1.5');
+    expect(result[0].message).toContain('0.1.7');
+  });
+
+  test('no finding when fetcher returns null (network failure)', async () => {
+    const result = await auditCliVersion({
+      installedVersion: '0.1.5',
+      fetcher: async () => null,
+    });
+    expect(result).toEqual([]);
+  });
+});

package/src/services/audit/cli-version.ts

@@ -0,0 +1,87 @@
+/**
+ * CLI version drift check.
+ *
+ * Compares the running `@celilo/cli` version against the latest version
+ * on npm. A newer published version produces a single `drift` finding;
+ * a network failure (offline, npm down) produces no finding — we don't
+ * want a transient lookup failure to block `system update`. Instead the
+ * caller logs a debug warning. Schema drift, capability ABI drift, etc.
+ * are the BLOCKED gates; CLI version is informational only.
+ *
+ * `latestVersionFetcher` is injectable so tests don't hit npm.
+ */
+
+import type { DriftFinding } from './types';
+
+export type LatestCliVersionFetcher = () => Promise<string | null>;
+
+/**
+ * Default fetcher — queries the npm registry's metadata endpoint.
+ *
+ * Returns null on any non-2xx or parse failure, so a network blip
+ * doesn't surface as a confusing "drift" finding.
+ */
+export const fetchLatestCliVersion: LatestCliVersionFetcher = async () => {
+  try {
+    const resp = await fetch('https://registry.npmjs.org/@celilo/cli', {
+      signal: AbortSignal.timeout(5_000),
+      headers: { Accept: 'application/json' },
+    });
+    if (!resp.ok) return null;
+    const data = (await resp.json()) as { 'dist-tags'?: { latest?: string } };
+    return data['dist-tags']?.latest ?? null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Strict semver comparison. Returns:
+ *  - `-1` if `a < b`
+ *  - `0`  if `a === b`
+ *  - `1`  if `a > b`
+ *
+ * Doesn't support pre-release tags (`-beta.1` etc.) — we strip
+ * everything after a `-` and compare the numeric portions only.
+ */
+export function compareSemver(a: string, b: string): number {
+  const parse = (v: string): [number, number, number] => {
+    const stripped = v.replace(/^v/, '').split('-')[0].split('+')[0];
+    const parts = stripped.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+  };
+  const [aa, ab, ac] = parse(a);
+  const [ba, bb, bc] = parse(b);
+  if (aa !== ba) return aa < ba ? -1 : 1;
+  if (ab !== bb) return ab < bb ? -1 : 1;
+  if (ac !== bc) return ac < bc ? -1 : 1;
+  return 0;
+}
+
+export interface CliVersionAuditDeps {
+  /** Version of the running CLI, typically read from `package.json`. */
+  installedVersion: string;
+  fetcher?: LatestCliVersionFetcher;
+}
+
+export async function auditCliVersion(deps: CliVersionAuditDeps): Promise<DriftFinding[]> {
+  const fetcher = deps.fetcher ?? fetchLatestCliVersion;
+  const latest = await fetcher();
+  if (!latest) return []; // network failure — silently no finding
+
+  if (compareSemver(deps.installedVersion, latest) >= 0) {
+    return []; // up to date or ahead (dev build)
+  }
+
+  return [
+    {
+      category: 'cli_version',
+      severity: 'drift',
+      code: 'cli_version_drift',
+      message: `@celilo/cli ${deps.installedVersion} → ${latest} available`,
+      remediation: 'celilo system update',
+      actionable: true,
+      subject: 'system',
+    },
+  ];
+}

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

@@ -0,0 +1,84 @@
+import { describe, expect, test } from 'bun:test';
+import type { HealthCheckResult } from '../health-runner';
+import { auditHealth } from './health';
+
+describe('auditHealth', () => {
+  test('no findings when every module is healthy or has no checks', async () => {
+    const results: HealthCheckResult[] = [
+      { moduleId: 'caddy', status: 'healthy', checks: [] },
+      { moduleId: 'iptables', status: 'no-checks', checks: [] },
+    ];
+    expect(await auditHealth({ results })).toEqual([]);
+  });
+
+  test('drift finding for unhealthy module', async () => {
+    const results: HealthCheckResult[] = [
+      {
+        moduleId: 'lunacycle',
+        status: 'unhealthy',
+        checks: [
+          { name: 'service_running', status: 'fail', message: 'Service inactive' },
+          { name: 'api_reachable', status: 'pass', message: 'API responded' },
+        ],
+      },
+    ];
+
+    const result = await auditHealth({ results });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      category: 'health',
+      severity: 'drift',
+      code: 'health_unhealthy',
+      subject: 'lunacycle',
+    });
+    expect(result[0].details).toContain('service_running');
+    expect(result[0].details).not.toContain('api_reachable'); // pass entries excluded
+  });
+
+  test('drift finding for degraded module', async () => {
+    const results: HealthCheckResult[] = [
+      {
+        moduleId: 'caddy',
+        status: 'degraded',
+        checks: [{ name: 'dns_resolution', status: 'warn', message: 'propagation pending' }],
+      },
+    ];
+
+    const result = await auditHealth({ results });
+    expect(result[0].code).toBe('health_degraded');
+  });
+
+  test('error status surfaces with the error message', async () => {
+    const results: HealthCheckResult[] = [
+      {
+        moduleId: 'lunacycle',
+        status: 'error',
+        checks: [],
+        error: 'Hook script not found',
+      },
+    ];
+
+    const result = await auditHealth({ results });
+    expect(result[0].message).toContain('Hook script not found');
+  });
+
+  test('multiple unhealthy modules each produce a finding', async () => {
+    const results: HealthCheckResult[] = [
+      {
+        moduleId: 'a',
+        status: 'unhealthy',
+        checks: [{ name: 'x', status: 'fail', message: 'no' }],
+      },
+      {
+        moduleId: 'b',
+        status: 'degraded',
+        checks: [{ name: 'y', status: 'warn', message: 'meh' }],
+      },
+    ];
+
+    const result = await auditHealth({ results });
+    expect(result).toHaveLength(2);
+    expect(result.map((f) => f.subject).sort()).toEqual(['a', 'b']);
+  });
+});

package/src/services/audit/health.ts

@@ -0,0 +1,43 @@
+/**
+ * Health drift check.
+ *
+ * Wraps the existing health-runner. Health-check failures are
+ * informational (DRIFT, not BLOCKED) — the user might want to update
+ * even if some module is currently unhealthy (an update could fix it).
+ *
+ * The health-runner result is passed in directly so this file stays
+ * pure for testing. The aggregator wires `runAllHealthChecks` to it.
+ */
+
+import type { HealthCheckResult } from '../health-runner';
+import type { DriftFinding } from './types';
+
+export interface HealthAuditDeps {
+  results: HealthCheckResult[];
+}
+
+export async function auditHealth(deps: HealthAuditDeps): Promise<DriftFinding[]> {
+  const findings: DriftFinding[] = [];
+
+  for (const r of deps.results) {
+    if (r.status === 'healthy' || r.status === 'no-checks') continue;
+
+    const failingChecks = r.checks
+      .filter((c) => c.status === 'fail' || c.status === 'warn')
+      .map((c) => `  • ${c.name}: ${c.message}`)
+      .join('\n');
+
+    findings.push({
+      category: 'health',
+      severity: 'drift',
+      code: r.status === 'unhealthy' ? 'health_unhealthy' : `health_${r.status}`,
+      message: `${r.moduleId}: ${r.status}${r.error ? ` — ${r.error}` : ''}`,
+      details: failingChecks || undefined,
+      remediation: `celilo module health ${r.moduleId} --debug`,
+      actionable: true,
+      subject: r.moduleId,
+    });
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,99 @@
+import { describe, expect, test } from 'bun:test';
+import type { DbClient } from '../../db/client';
+import { runAudit } from './index';
+
+const fakeDb = {} as DbClient;
+
+const emptyDeps = {
+  cliVersion: {
+    installedVersion: '0.1.5',
+    fetcher: async () => '0.1.5',
+  },
+  schema: {
+    journal: () => null,
+    applied: () => [],
+    db: fakeDb,
+  },
+  capabilityAbi: { modules: [] },
+  terraformPlan: {
+    modules: [],
+    run: async () => ({ exitCode: 0, stdout: '', stderr: '' }),
+  },
+  moduleVersions: {
+    installed: [],
+    fetcher: async () => ({ latest: null }),
+  },
+  moduleConfigs: { modules: [] },
+  health: { results: [] },
+  backups: { modules: [] },
+  undeployedModules: { modules: [] },
+  unconfiguredModules: { modules: [] },
+  servicesCredentials: { results: [] },
+  secretsDecryptable: { results: [] },
+  servicesReachable: { results: [] },
+  machinesReachable: { results: [] },
+};
+
+describe('runAudit', () => {
+  test('READY when no checks produce findings', async () => {
+    const report = await runAudit({ ...emptyDeps, now: () => new Date('2026-04-25T00:00:00Z') });
+
+    expect(report.version).toBe(1);
+    expect(report.verdict).toBe('READY');
+    expect(report.findings).toEqual([]);
+    expect(report.generatedAt).toBe('2026-04-25T00:00:00.000Z');
+  });
+
+  test('DRIFT when only drift-severity findings', async () => {
+    const report = await runAudit({
+      ...emptyDeps,
+      cliVersion: {
+        installedVersion: '0.1.5',
+        fetcher: async () => '0.1.7',
+      },
+    });
+
+    expect(report.verdict).toBe('DRIFT');
+    expect(report.findings).toHaveLength(1);
+    expect(report.findings[0].category).toBe('cli_version');
+  });
+
+  test('BLOCKED when any blocked finding is present', async () => {
+    const report = await runAudit({
+      ...emptyDeps,
+      schema: {
+        journal: () => ({
+          version: '5',
+          dialect: 'sqlite',
+          entries: [{ idx: 0, tag: '0001_pending', when: 1 }],
+        }),
+        applied: () => [],
+        db: fakeDb,
+      },
+    });
+
+    expect(report.verdict).toBe('BLOCKED');
+    expect(report.findings.some((f) => f.category === 'schema')).toBe(true);
+  });
+
+  test('aggregates findings across all categories', async () => {
+    const report = await runAudit({
+      ...emptyDeps,
+      cliVersion: {
+        installedVersion: '0.1.5',
+        fetcher: async () => '0.1.7',
+      },
+      moduleVersions: {
+        installed: [{ id: 'caddy', version: '1.0.0' }],
+        fetcher: async () => ({ latest: '1.1.0' }),
+      },
+    });
+
+    expect(report.verdict).toBe('DRIFT');
+    expect(report.findings).toHaveLength(2);
+    expect(report.findings.map((f) => f.category).sort()).toEqual([
+      'cli_version',
+      'module_versions',
+    ]);
+  });
+});