@celilo/cli 0.1.5 → 0.1.7

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

@@ -0,0 +1,233 @@
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../../manifest/schema';
+import { type InstalledModuleBackupInfo, auditBackups } from './backups';
+
+const NOW = new Date('2026-04-25T00:00:00Z').getTime();
+const HOUR = 60 * 60 * 1000;
+const ONE_DAY = 24 * HOUR;
+
+type Schedule = 'hourly' | 'daily' | 'weekly' | 'monthly' | 'manual';
+
+function makeModule(
+  id: string,
+  opts: {
+    hasBackupHook: boolean;
+    lastSuccessfulBackupAt: number | null;
+    schedule?: Schedule;
+  },
+): InstalledModuleBackupInfo {
+  const manifest = {
+    id,
+    name: id,
+    version: '1.0.0',
+    celilo_contract: '1.0',
+    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 };
+}
+
+describe('auditBackups', () => {
+  test('skips modules without an on_backup hook', async () => {
+    const result = await auditBackups({
+      modules: [makeModule('caddy', { hasBackupHook: false, lastSuccessfulBackupAt: null })],
+      now: () => NOW,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('reports missing backup regardless of schedule (still want at least one)', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('lunacycle', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: null,
+          schedule: 'manual',
+        }),
+      ],
+      now: () => NOW,
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      category: 'backups',
+      severity: 'drift',
+      code: 'backup_missing',
+      subject: 'lunacycle',
+    });
+    expect(result[0].message).toContain('manual');
+  });
+
+  test('manual schedule: never flags stale (user-driven cadence)', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('lunacycle', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 365 * ONE_DAY, // 1 year old
+          schedule: 'manual',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('no schedule declared → treated as manual (no stale flag)', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('lunacycle', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 365 * ONE_DAY,
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('daily schedule: 26h-old is stale', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('authentik', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 26 * HOUR,
+          schedule: 'daily',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].code).toBe('backup_stale');
+    expect(result[0].message).toContain('daily');
+  });
+
+  test('daily schedule: 24h-old is fresh (within grace)', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('authentik', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 24 * HOUR,
+          schedule: 'daily',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('hourly schedule: 3h-old is stale', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('chat', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 3 * HOUR,
+          schedule: 'hourly',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].code).toBe('backup_stale');
+  });
+
+  test('weekly schedule: 5d-old is fresh', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('archive', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 5 * ONE_DAY,
+          schedule: 'weekly',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('weekly schedule: 10d-old is stale', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('archive', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 10 * ONE_DAY,
+          schedule: 'weekly',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].code).toBe('backup_stale');
+  });
+
+  test('monthly schedule: 30d-old is fresh', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('cold-store', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 30 * ONE_DAY,
+          schedule: 'monthly',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('monthly schedule: 35d-old is stale', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('cold-store', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 35 * ONE_DAY,
+          schedule: 'monthly',
+        }),
+      ],
+      now: () => NOW,
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].code).toBe('backup_stale');
+  });
+
+  test('staleAfterMs override forces threshold for every module', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('lunacycle', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 2 * ONE_DAY,
+          schedule: 'monthly', // would normally be fresh
+        }),
+      ],
+      staleAfterMs: ONE_DAY,
+      now: () => NOW,
+    });
+    expect(result).toHaveLength(1);
+    expect(result[0].code).toBe('backup_stale');
+  });
+
+  test('mixed report across multiple modules', async () => {
+    const result = await auditBackups({
+      modules: [
+        makeModule('caddy', { hasBackupHook: false, lastSuccessfulBackupAt: null }), // skipped
+        makeModule('lunacycle', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 3 * HOUR,
+          schedule: 'daily',
+        }), // fresh
+        makeModule('authentik', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: null,
+          schedule: 'daily',
+        }), // missing
+        makeModule('homebridge', {
+          hasBackupHook: true,
+          lastSuccessfulBackupAt: NOW - 30 * ONE_DAY,
+          schedule: 'weekly',
+        }), // stale
+      ],
+      now: () => NOW,
+    });
+
+    expect(result).toHaveLength(2);
+    expect(result.map((f) => f.subject).sort()).toEqual(['authentik', 'homebridge']);
+  });
+});

package/src/services/audit/backups.ts

@@ -0,0 +1,128 @@
+/**
+ * Backup freshness drift check.
+ *
+ * For each installed module that declares an `on_backup` hook,
+ * decides whether the most recent successful backup is too old based
+ * on the module's declared `manifest.backup.schedule`. Each schedule
+ * tier has a threshold with a small grace window so a slightly-late
+ * scheduled run doesn't flag drift on every audit.
+ *
+ * Modules without an `on_backup` hook are skipped — there's nothing
+ * to back up. Modules whose schedule is `manual` (or unset) skip the
+ * staleness check (the user decides cadence) but still get a
+ * `backup_missing` finding if no backup has ever been recorded.
+ *
+ * Time is injected so tests can pin "now" deterministically.
+ */
+
+import type { ModuleManifest } from '../../manifest/schema';
+import type { DriftFinding } from './types';
+
+export interface InstalledModuleBackupInfo {
+  id: string;
+  manifest: ModuleManifest;
+  /** Most recent successful backup timestamp (ms since epoch), or null. */
+  lastSuccessfulBackupAt: number | null;
+}
+
+export interface BackupsAuditDeps {
+  modules: InstalledModuleBackupInfo[];
+  /**
+   * Test-only override: forces this threshold for every module,
+   * ignoring `manifest.backup.schedule`. Production code never sets
+   * this — schedule-based thresholds are the right behavior.
+   */
+  staleAfterMs?: number;
+  /** Defaults to `Date.now()`. */
+  now?: () => number;
+}
+
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+
+/**
+ * Schedule → stale threshold. Each tier gets a grace window so a
+ * legitimately-just-late run doesn't trip the audit:
+ *
+ * - hourly  → 2h   (1h cadence + 1h grace)
+ * - daily   → 25h  (24h + 1h grace)
+ * - weekly  → 8d   (7d + 1d grace)
+ * - monthly → 32d  (~30d + 2d grace)
+ * - manual  → null (no staleness check; user-driven cadence)
+ *
+ * `undefined` (no `backup:` block in manifest) is treated as
+ * `manual` — author opted out of declaring a cadence.
+ */
+const SCHEDULE_THRESHOLDS = {
+  hourly: 2 * HOUR,
+  daily: 25 * HOUR,
+  weekly: 8 * DAY,
+  monthly: 32 * DAY,
+  manual: null,
+} as const;
+
+type ScheduleKey = keyof typeof SCHEDULE_THRESHOLDS;
+
+function moduleHasBackupHook(manifest: ModuleManifest): boolean {
+  return Boolean(manifest.hooks?.on_backup);
+}
+
+function scheduleFor(manifest: ModuleManifest): ScheduleKey {
+  const s = manifest.backup?.schedule;
+  if (s === 'hourly' || s === 'daily' || s === 'weekly' || s === 'monthly') return s;
+  return 'manual';
+}
+
+function thresholdFor(manifest: ModuleManifest, override: number | undefined): number | null {
+  if (override !== undefined) return override;
+  return SCHEDULE_THRESHOLDS[scheduleFor(manifest)];
+}
+
+function formatAge(ms: number): string {
+  const days = Math.floor(ms / DAY);
+  if (days >= 1) return `${days}d`;
+  const hours = Math.floor(ms / HOUR);
+  if (hours >= 1) return `${hours}h`;
+  const mins = Math.floor(ms / (60 * 1000));
+  return `${mins}m`;
+}
+
+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;
+
+    if (m.lastSuccessfulBackupAt === null) {
+      findings.push({
+        category: 'backups',
+        severity: 'drift',
+        code: 'backup_missing',
+        message: `${m.id}: no successful backup recorded (schedule: ${scheduleFor(m.manifest)})`,
+        remediation: `celilo backup create ${m.id} --force`,
+        actionable: true,
+        subject: m.id,
+      });
+      continue;
+    }
+
+    const threshold = thresholdFor(m.manifest, deps.staleAfterMs);
+    if (threshold === null) continue; // manual cadence — staleness is user-defined
+
+    const age = now - m.lastSuccessfulBackupAt;
+    if (age > threshold) {
+      findings.push({
+        category: 'backups',
+        severity: 'drift',
+        code: 'backup_stale',
+        message: `${m.id}: last successful backup is ${formatAge(age)} old (schedule: ${scheduleFor(m.manifest)}, threshold: ${formatAge(threshold)})`,
+        remediation: `celilo backup create ${m.id} --force`,
+        actionable: true,
+        subject: m.id,
+      });
+    }
+  }
+
+  return findings;
+}

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

@@ -0,0 +1,153 @@
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest } from '../../manifest/schema';
+import { type InstalledCapabilityModule, auditCapabilityAbi } from './capability-abi';
+
+function makeModule(
+  id: string,
+  opts: {
+    provides?: Array<{ name: string; version: string }>;
+    requires?: Array<{ name: string; version: string }>;
+    optional?: Array<{ name: string; version: string }>;
+  } = {},
+): InstalledCapabilityModule {
+  const manifest = {
+    id,
+    name: id,
+    version: '1.0.0',
+    celilo_contract: '1.0',
+    provides: opts.provides
+      ? {
+          capabilities: opts.provides.map((p) => ({ ...p, data: {}, functions: [] })),
+        }
+      : { capabilities: [] },
+    requires: opts.requires ? { capabilities: opts.requires } : { capabilities: [] },
+    optional: opts.optional ? { capabilities: opts.optional } : undefined,
+  } as unknown as ModuleManifest;
+  return { id, manifest };
+}
+
+const RUNTIME = {
+  public_web: '2.0.0',
+  idp: '1.0.0',
+  dns_registrar: '3.0.0',
+  firewall: '1.0.0',
+  dhcp_server: '1.0.0',
+  dns_internal: '1.0.0',
+};
+
+describe('auditCapabilityAbi', () => {
+  test('no findings when every provider claim matches runtime exactly', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [
+        makeModule('caddy', { provides: [{ name: 'public_web', version: '2.0.0' }] }),
+        makeModule('namecheap', { provides: [{ name: 'dns_registrar', version: '3.0.0' }] }),
+      ],
+      contractVersions: RUNTIME,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('blocked when a provider claims a major-version older than runtime', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [makeModule('caddy', { provides: [{ name: 'public_web', version: '1.0.0' }] })],
+      contractVersions: RUNTIME,
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toMatchObject({
+      category: 'capability_abi',
+      severity: 'blocked',
+      code: 'capability_abi_provider_mismatch',
+      subject: 'caddy',
+      actionable: false,
+    });
+    expect(result[0].details).toContain('cd modules/caddy');
+    expect(result[0].details).toContain('Application Binary Interface');
+  });
+
+  test('blocked when a provider claims a major-version newer than runtime', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [makeModule('caddy', { provides: [{ name: 'public_web', version: '3.0.0' }] })],
+      contractVersions: RUNTIME,
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].actionable).toBe(false);
+    expect(result[0].details).toContain('Upgrade celilo');
+  });
+
+  test('skips capabilities not in the runtime registry (third-party)', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [
+        makeModule('odd-module', { provides: [{ name: 'custom_metric', version: '99.0.0' }] }),
+      ],
+      contractVersions: RUNTIME,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('blocked when consumer requires a major-version mismatch with the deployed provider', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [
+        makeModule('namecheap', { provides: [{ name: 'dns_registrar', version: '3.0.0' }] }),
+        makeModule('caddy', { requires: [{ name: 'dns_registrar', version: '2.0.0' }] }),
+      ],
+      contractVersions: RUNTIME,
+    });
+
+    const caddyFinding = result.find(
+      (f) => f.subject === 'caddy' && f.code === 'capability_abi_consumer_mismatch',
+    );
+    expect(caddyFinding).toBeDefined();
+    expect(caddyFinding?.message).toContain('caddy requires dns_registrar@2.0.0');
+    expect(caddyFinding?.message).toContain('namecheap provides 3.0.0');
+  });
+
+  test('blocked when consumer requires a newer minor than provider has', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [
+        makeModule('namecheap', { provides: [{ name: 'dns_registrar', version: '3.0.0' }] }),
+        makeModule('lunacycle', { requires: [{ name: 'dns_registrar', version: '3.5.0' }] }),
+      ],
+      contractVersions: { ...RUNTIME, dns_registrar: '3.5.0' },
+    });
+
+    const finding = result.find((f) => f.subject === 'lunacycle');
+    expect(finding).toBeDefined();
+    expect(finding?.actionable).toBe(false);
+    expect(finding?.details).toContain('Upgrade namecheap');
+  });
+
+  test('no consumer finding when no provider is installed (deploy preflight handles it)', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [makeModule('lunacycle', { requires: [{ name: 'idp', version: '1.0.0' }] })],
+      contractVersions: RUNTIME,
+    });
+    expect(result.find((f) => f.code === 'capability_abi_consumer_mismatch')).toBeUndefined();
+  });
+
+  test('compatible: consumer requires older minor than provider has (additive)', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [
+        makeModule('namecheap', { provides: [{ name: 'dns_registrar', version: '3.5.0' }] }),
+        makeModule('caddy', { requires: [{ name: 'dns_registrar', version: '3.0.0' }] }),
+      ],
+      contractVersions: { ...RUNTIME, dns_registrar: '3.5.0' },
+    });
+    expect(result).toEqual([]);
+  });
+
+  test('also checks optional capabilities (they cause findings on mismatch)', async () => {
+    const result = await auditCapabilityAbi({
+      modules: [
+        makeModule('namecheap', { provides: [{ name: 'dns_registrar', version: '3.0.0' }] }),
+        makeModule('caddy', { optional: [{ name: 'dns_registrar', version: '2.0.0' }] }),
+      ],
+      contractVersions: RUNTIME,
+    });
+
+    expect(
+      result.some((f) => f.subject === 'caddy' && f.code === 'capability_abi_consumer_mismatch'),
+    ).toBe(true);
+  });
+});