@celilo/cli 0.1.0

package/src/services/backup-metadata.ts

@@ -0,0 +1,198 @@
+/**
+ * Backup metadata service - CRUD operations for backup records.
+ * Tracks both system state and module data backups.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { desc, eq, like } from 'drizzle-orm';
+import { getDb } from '../db/client';
+import { type Backup, type BackupStatus, type BackupType, backups } from '../db/schema';
+
+/** Short ID length used for display and lookup */
+export const SHORT_ID_LENGTH = 8;
+
+export interface CreateBackupParams {
+  moduleId?: string | null;
+  storageId: string;
+  storagePath: string;
+  backupType: BackupType;
+  moduleVersion?: string;
+}
+
+export interface BackupRecord extends Backup {
+  id: string;
+}
+
+/**
+ * Create a new backup record (status: in_progress)
+ */
+export function createBackupRecord(params: CreateBackupParams): BackupRecord {
+  const db = getDb();
+  const id = randomUUID();
+  const now = new Date();
+
+  const values = {
+    id,
+    moduleId: params.moduleId ?? null,
+    storageId: params.storageId,
+    storagePath: params.storagePath,
+    backupType: params.backupType,
+    moduleVersion: params.moduleVersion ?? null,
+    schemaVersion: null,
+    sizeBytes: null,
+    metadata: {},
+    status: 'in_progress' as BackupStatus,
+    errorMessage: null,
+    startedAt: now,
+    completedAt: null,
+  };
+
+  db.insert(backups).values(values).run();
+
+  return { ...values, startedAt: now, completedAt: null } as BackupRecord;
+}
+
+/**
+ * Mark a backup as completed with final metadata
+ */
+export function completeBackup(
+  id: string,
+  params: {
+    sizeBytes: number;
+    metadata?: Record<string, unknown>;
+    schemaVersion?: string;
+  },
+): void {
+  const db = getDb();
+  db.update(backups)
+    .set({
+      status: 'completed' as BackupStatus,
+      sizeBytes: params.sizeBytes,
+      metadata: params.metadata ?? {},
+      schemaVersion: params.schemaVersion ?? null,
+      completedAt: new Date(),
+    })
+    .where(eq(backups.id, id))
+    .run();
+}
+
+/**
+ * Mark a backup as failed
+ */
+export function failBackup(id: string, errorMessage: string): void {
+  const db = getDb();
+  db.update(backups)
+    .set({
+      status: 'failed' as BackupStatus,
+      errorMessage,
+      completedAt: new Date(),
+    })
+    .where(eq(backups.id, id))
+    .run();
+}
+
+/**
+ * Get a backup by ID or short ID prefix.
+ * Supports both full UUIDs and 8-char short IDs.
+ */
+export function getBackup(id: string): Backup | null {
+  const db = getDb();
+
+  // Try exact match first
+  const exact = db.select().from(backups).where(eq(backups.id, id)).limit(1).all();
+  if (exact.length > 0) return exact[0];
+
+  // Try prefix match for short IDs
+  if (id.length < 36) {
+    const prefixed = db
+      .select()
+      .from(backups)
+      .where(like(backups.id, `${id}%`))
+      .all();
+    if (prefixed.length === 1) return prefixed[0];
+    if (prefixed.length > 1) {
+      throw new Error(
+        `Ambiguous backup ID '${id}' matches ${prefixed.length} backups. Use a longer prefix.`,
+      );
+    }
+  }
+
+  // Try name match (case-insensitive)
+  const byName = db.select().from(backups).where(like(backups.name, id)).all();
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    throw new Error(
+      `Ambiguous backup name '${id}' matches ${byName.length} backups. Use a unique name or backup ID.`,
+    );
+  }
+
+  return null;
+}
+
+/**
+ * List backups with optional module filter and limit
+ */
+export function listBackups(options?: {
+  moduleId?: string;
+  limit?: number;
+}): Backup[] {
+  const db = getDb();
+  const limit = options?.limit ?? 20;
+
+  if (options?.moduleId) {
+    return db
+      .select()
+      .from(backups)
+      .where(eq(backups.moduleId, options.moduleId))
+      .orderBy(desc(backups.startedAt))
+      .limit(limit)
+      .all();
+  }
+
+  return db.select().from(backups).orderBy(desc(backups.startedAt)).limit(limit).all();
+}
+
+/**
+ * List completed backups for a specific module, ordered newest first
+ */
+export function listCompletedBackupsForModule(moduleId: string): Backup[] {
+  const db = getDb();
+  return db
+    .select()
+    .from(backups)
+    .where(eq(backups.moduleId, moduleId))
+    .orderBy(desc(backups.startedAt))
+    .all()
+    .filter((b) => b.status === 'completed');
+}
+
+/**
+ * Set or clear a human-readable name on a backup
+ */
+export function updateBackupName(id: string, name: string | null): void {
+  const db = getDb();
+  db.update(backups).set({ name }).where(eq(backups.id, id)).run();
+}
+
+/**
+ * Delete a backup record
+ */
+export function deleteBackupRecord(id: string): void {
+  const db = getDb();
+  db.delete(backups).where(eq(backups.id, id)).run();
+}
+
+/**
+ * Format bytes into human-readable size
+ */
+export function formatSize(bytes: number | null): string {
+  if (bytes === null || bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let size = bytes;
+  let unitIndex = 0;
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+  return `${size.toFixed(unitIndex === 0 ? 0 : 1)} ${units[unitIndex]}`;
+}

package/src/services/backup-restore.ts

@@ -0,0 +1,229 @@
+/**
+ * Backup restore service.
+ * Downloads, decrypts, extracts backup archives and executes on_restore hooks.
+ * For system state backups, restores the Celilo database.
+ */
+
+import { execSync } from 'node:child_process';
+import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { getDbPath } from '../config/paths';
+import { closeDb, getDb } from '../db/client';
+import { moduleConfigs, modules, secrets as secretsTable } from '../db/schema';
+import type { Backup } from '../db/schema';
+import { invokeHook } from '../hooks/executor';
+import { createConsoleLogger } from '../hooks/logger';
+import type { ModuleManifest } from '../manifest/schema';
+import { decryptSecret } from '../secrets/encryption';
+import { getOrCreateMasterKey } from '../secrets/master-key';
+import { shellEscape } from '../utils/shell';
+import { createStorageProvider } from './backup-storage';
+
+export interface RestoreResult {
+  success: boolean;
+  error?: string;
+  healthCheckPassed?: boolean;
+}
+
+/**
+ * Restore a system state backup (replaces the Celilo database)
+ */
+export async function restoreSystemStateBackup(backup: Backup): Promise<RestoreResult> {
+  const provider = await createStorageProvider(backup.storageId);
+  const tempDir = join(tmpdir(), `celilo-restore-${backup.id}`);
+
+  try {
+    mkdirSync(tempDir, { recursive: true });
+
+    // Download encrypted archive
+    const encryptedPath = join(tempDir, 'system.enc');
+    await provider.download(backup.storagePath, encryptedPath);
+
+    // Decrypt
+    const encryptedData = JSON.parse(readFileSync(encryptedPath, 'utf-8'));
+    const masterKey = await getOrCreateMasterKey();
+    const base64Data = decryptSecret(encryptedData, masterKey);
+    const dbData = Buffer.from(base64Data, 'base64');
+
+    // Write restored database to temp file first
+    const restoredDbPath = join(tempDir, 'celilo.db');
+    writeFileSync(restoredDbPath, dbData);
+
+    // Close current database connection
+    closeDb();
+
+    // Replace the database file
+    const dbPath = getDbPath();
+    copyFileSync(restoredDbPath, dbPath);
+
+    // Remove WAL/SHM files (they're from the old DB state)
+    try {
+      rmSync(`${dbPath}-wal`, { force: true });
+    } catch {
+      // May not exist
+    }
+    try {
+      rmSync(`${dbPath}-shm`, { force: true });
+    } catch {
+      // May not exist
+    }
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: `System restore failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Best effort cleanup
+    }
+  }
+}
+
+/**
+ * Build config and secret maps for a module
+ */
+async function buildModuleContext(moduleId: string): Promise<{
+  configMap: Record<string, unknown>;
+  secretMap: Record<string, string>;
+}> {
+  const db = getDb();
+
+  const configs = db.select().from(moduleConfigs).where(eq(moduleConfigs.moduleId, moduleId)).all();
+  const configMap: Record<string, unknown> = {};
+  for (const c of configs) {
+    configMap[c.key] = c.valueJson ? JSON.parse(c.valueJson) : c.value;
+  }
+
+  const secretRecords = db
+    .select()
+    .from(secretsTable)
+    .where(eq(secretsTable.moduleId, moduleId))
+    .all();
+  const masterKey = await getOrCreateMasterKey();
+  const secretMap: Record<string, string> = {};
+  for (const s of secretRecords) {
+    secretMap[s.name] = decryptSecret(
+      { encryptedValue: s.encryptedValue, iv: s.iv, authTag: s.authTag },
+      masterKey,
+    );
+  }
+
+  return { configMap, secretMap };
+}
+
+/**
+ * Restore a module data backup.
+ * Downloads, decrypts, extracts, then executes the module's on_restore hook.
+ * Optionally runs a health check after restore.
+ */
+export async function restoreModuleBackup(
+  backup: Backup,
+  options: { runHealthCheck?: boolean } = {},
+): Promise<RestoreResult> {
+  if (!backup.moduleId) {
+    return { success: false, error: 'Backup has no associated module' };
+  }
+
+  const db = getDb();
+  const mod = db.select().from(modules).where(eq(modules.id, backup.moduleId)).get();
+  if (!mod) {
+    return { success: false, error: `Module not found: ${backup.moduleId}` };
+  }
+
+  const manifest = mod.manifestData as unknown as ModuleManifest;
+  const hookDef = manifest.hooks?.on_restore;
+  if (!hookDef) {
+    return {
+      success: false,
+      error: `Module '${mod.id}' has no on_restore hook defined`,
+    };
+  }
+
+  const provider = await createStorageProvider(backup.storageId);
+  const tempDir = join(tmpdir(), `celilo-restore-${backup.id}`);
+  const restoreDir = join(tempDir, 'artifacts');
+
+  try {
+    mkdirSync(restoreDir, { recursive: true });
+
+    // Download encrypted archive
+    const encryptedPath = join(tempDir, 'backup.tar.enc');
+    await provider.download(backup.storagePath, encryptedPath);
+
+    // Decrypt
+    const encryptedData = JSON.parse(readFileSync(encryptedPath, 'utf-8'));
+    const masterKey = await getOrCreateMasterKey();
+    const base64Data = decryptSecret(encryptedData, masterKey);
+    const tarData = Buffer.from(base64Data, 'base64');
+
+    // Write tar and extract
+    const tarPath = join(tempDir, 'backup.tar');
+    writeFileSync(tarPath, tarData);
+    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(restoreDir)}`);
+
+    // Build context for hook execution
+    const { configMap, secretMap } = await buildModuleContext(mod.id);
+    const logger = createConsoleLogger(mod.id, 'on_restore');
+
+    // Execute on_restore hook
+    const hookResult = await invokeHook(
+      mod.sourcePath,
+      'on_restore',
+      manifest.celilo_contract,
+      hookDef,
+      {
+        restore_dir: restoreDir,
+        schema_version: backup.schemaVersion ?? '',
+      },
+      configMap,
+      secretMap,
+      logger,
+      {
+        debug: false,
+      },
+    );
+
+    if (!hookResult.success) {
+      return {
+        success: false,
+        error: hookResult.error ?? 'on_restore hook failed',
+      };
+    }
+
+    // Run health check if requested and the module has one
+    let healthCheckPassed: boolean | undefined;
+    if (options.runHealthCheck && manifest.hooks?.health_check) {
+      try {
+        const { runModuleHealthCheck } = await import('./health-runner');
+        const healthResult = await runModuleHealthCheck(mod.id, db, {
+          noInteractive: true,
+        });
+        healthCheckPassed = healthResult.status === 'healthy';
+      } catch {
+        healthCheckPassed = false;
+      }
+    }
+
+    return {
+      success: true,
+      healthCheckPassed,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Restore failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  } finally {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // Best effort cleanup
+    }
+  }
+}

package/src/services/backup-retention.ts

@@ -0,0 +1,84 @@
+/**
+ * Backup retention service.
+ * Enforces retention policies defined in module manifests.
+ * Policies are count-based (keep last N) and age-based (delete older than X days).
+ * Whichever limit is hit first triggers deletion.
+ */
+
+import type { Backup } from '../db/schema';
+import { deleteBackupRecord, listCompletedBackupsForModule } from './backup-metadata';
+import { createStorageProvider } from './backup-storage';
+
+export interface RetentionPolicy {
+  count: number;
+  maxAgeDays: number;
+}
+
+export interface PruneResult {
+  moduleId: string;
+  deleted: number;
+  deletedPaths: string[];
+}
+
+/**
+ * Identify backups that should be pruned per the retention policy
+ */
+export function identifyExpiredBackups(backupsList: Backup[], policy: RetentionPolicy): Backup[] {
+  const now = Date.now();
+  const maxAgeMs = policy.maxAgeDays * 24 * 60 * 60 * 1000;
+  const expired: Backup[] = [];
+
+  // Backups are already sorted newest-first from the query
+  for (let i = 0; i < backupsList.length; i++) {
+    const backup = backupsList[i];
+    const age = now - new Date(backup.startedAt).getTime();
+    const exceedsCount = i >= policy.count;
+    const exceedsAge = age > maxAgeMs;
+
+    if (exceedsCount || exceedsAge) {
+      expired.push(backup);
+    }
+  }
+
+  return expired;
+}
+
+/**
+ * Prune expired backups for a module.
+ * Deletes from storage and removes database records.
+ */
+export async function pruneBackupsForModule(
+  moduleId: string,
+  policy: RetentionPolicy,
+  dryRun = false,
+): Promise<PruneResult> {
+  const backupsList = listCompletedBackupsForModule(moduleId);
+  const expired = identifyExpiredBackups(backupsList, policy);
+
+  if (dryRun || expired.length === 0) {
+    return {
+      moduleId,
+      deleted: expired.length,
+      deletedPaths: expired.map((b) => b.storagePath),
+    };
+  }
+
+  const deletedPaths: string[] = [];
+
+  for (const backup of expired) {
+    try {
+      const provider = await createStorageProvider(backup.storageId);
+      await provider.delete(backup.storagePath);
+    } catch {
+      // Storage deletion may fail if file already removed — continue
+    }
+    deleteBackupRecord(backup.id);
+    deletedPaths.push(backup.storagePath);
+  }
+
+  return {
+    moduleId,
+    deleted: deletedPaths.length,
+    deletedPaths,
+  };
+}