@celilo/cli 0.1.0

package/src/cli/commands/backup-list.ts

@@ -0,0 +1,132 @@
+/**
+ * Backup List Command
+ * Lists available backups with metadata.
+ */
+
+import { formatSize, getBackup, listBackups } from '../../services/backup-metadata';
+import { getBackupStorage } from '../../services/backup-storage';
+import { celiloIntro } from '../prompts';
+import type { CommandResult } from '../types';
+
+/**
+ * Format a timestamp as a human-friendly relative string.
+ * Uses relative terms for recent backups and dates for older ones.
+ */
+function formatRelativeDate(date: Date): string {
+  const now = Date.now();
+  const diffMs = now - date.getTime();
+  const diffMins = Math.floor(diffMs / 60_000);
+  const diffHours = Math.floor(diffMs / 3_600_000);
+  const diffDays = Math.floor(diffMs / 86_400_000);
+
+  if (diffMins < 1) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays === 1) return 'yesterday';
+  if (diffDays < 7) return `${diffDays} days ago`;
+  if (diffDays < 14) return 'last week';
+  if (diffDays < 30) return `${Math.floor(diffDays / 7)} weeks ago`;
+  if (diffDays < 60) return 'last month';
+  return `${Math.floor(diffDays / 30)} months ago`;
+}
+
+/**
+ * Show detailed info for a single backup
+ */
+function showBackupDetail(backupId: string): CommandResult {
+  const backup = getBackup(backupId);
+  if (!backup) {
+    return { success: false, error: `Backup not found: ${backupId}` };
+  }
+
+  const storage = getBackupStorage(backup.storageId);
+  const isSystem = backup.backupType === 'system_state';
+
+  console.log('');
+  console.log(`  ID:             ${backup.id}`);
+  console.log(`  Short ID:       ${backup.id.substring(0, 8)}`);
+  if (backup.name) {
+    console.log(`  Name:           ${backup.name}`);
+  }
+  console.log(`  Type:           ${isSystem ? 'System State' : 'Module Data'}`);
+  if (!isSystem) {
+    console.log(`  Module:         ${backup.moduleId ?? 'unknown'}`);
+  }
+  if (backup.moduleVersion) {
+    console.log(`  Module Version: ${backup.moduleVersion}`);
+  }
+  if (backup.schemaVersion) {
+    console.log(`  Schema Version: ${backup.schemaVersion}`);
+  }
+  console.log(`  Status:         ${backup.status}`);
+  console.log(`  Size:           ${formatSize(backup.sizeBytes)}`);
+  console.log(
+    `  Date:           ${new Date(backup.startedAt).toISOString().replace('T', ' ').substring(0, 19)} UTC`,
+  );
+  console.log(`  Storage:        ${storage?.storageId ?? 'unknown'} (${storage?.name ?? '?'})`);
+  console.log(`  Path:           ${backup.storagePath}`);
+  if (backup.errorMessage) {
+    console.log(`  Error:          ${backup.errorMessage}`);
+  }
+  console.log('');
+
+  return { success: true, message: `Backup detail: ${backupId}` };
+}
+
+export async function handleBackupList(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  try {
+    const moduleIdOrBackupId = args[0];
+    const limit = typeof flags.limit === 'string' ? Number.parseInt(flags.limit, 10) : 20;
+
+    // If the argument looks like a backup ID (hex chars), show detail view
+    if (moduleIdOrBackupId && /^[0-9a-f]{8,}$/i.test(moduleIdOrBackupId)) {
+      const backup = getBackup(moduleIdOrBackupId);
+      if (backup) {
+        celiloIntro('Backup Detail');
+        return showBackupDetail(moduleIdOrBackupId);
+      }
+      // Fall through to module filter if not a backup ID
+    }
+
+    celiloIntro('Available Backups');
+
+    const moduleId = moduleIdOrBackupId;
+    const backupList = listBackups({ moduleId, limit });
+
+    if (backupList.length === 0) {
+      console.log('No backups found.\n');
+      console.log('Create a backup:');
+      console.log('  celilo backup create');
+      return { success: true, message: 'No backups found' };
+    }
+
+    console.log('');
+
+    for (const backup of backupList) {
+      const id = backup.id.substring(0, 8);
+      const module = backup.backupType === 'system_state' ? '[system]' : (backup.moduleId ?? '?');
+      const when = formatRelativeDate(new Date(backup.startedAt));
+      const size = formatSize(backup.sizeBytes);
+      const statusIcon =
+        backup.status === 'completed' ? '✓' : backup.status === 'failed' ? '✗' : '…';
+
+      const nameTag = backup.name ? `  "${backup.name}"` : '';
+      console.log(
+        `  ${statusIcon} ${id}  ${module.padEnd(12)} ${size.padEnd(10)} ${when}${nameTag}`,
+      );
+    }
+
+    console.log(`\n${backupList.length} backup${backupList.length === 1 ? '' : 's'} shown.`);
+    console.log('Run "celilo backup list <id>" for details.\n');
+
+    return { success: true, message: `Found ${backupList.length} backup(s)` };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to list backups: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/src/cli/commands/backup-name.ts

@@ -0,0 +1,73 @@
+/**
+ * Backup Name Command
+ * Set or view a human-readable name/annotation on a backup.
+ *
+ * Usage:
+ *   celilo backup name <backup-id> <name...>    Set a name
+ *   celilo backup name <backup-id>              Show current name
+ *   celilo backup name <backup-id> --clear      Remove the name
+ */
+
+import { formatSize, getBackup, updateBackupName } from '../../services/backup-metadata';
+import { celiloIntro, celiloOutro } from '../prompts';
+import type { CommandResult } from '../types';
+
+export async function handleBackupName(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  try {
+    const backupId = args[0];
+
+    if (!backupId) {
+      return {
+        success: false,
+        error:
+          'Backup ID is required\n\nUsage:\n  celilo backup name <backup-id> <name...>\n  celilo backup name <backup-id> --clear',
+      };
+    }
+
+    const backup = getBackup(backupId);
+    if (!backup) {
+      return { success: false, error: `Backup not found: ${backupId}` };
+    }
+
+    const shortId = backup.id.substring(0, 8);
+
+    // Clear the name
+    if (flags.clear) {
+      celiloIntro('Clear Backup Name');
+      updateBackupName(backup.id, null);
+      celiloOutro(`Name cleared for backup ${shortId}.`);
+      return { success: true, message: `Cleared name for ${shortId}` };
+    }
+
+    // Remaining args after the backup ID form the name
+    const nameParts = args.slice(1);
+
+    // No name provided — show current name
+    if (nameParts.length === 0) {
+      celiloIntro('Backup Name');
+      const module =
+        backup.backupType === 'system_state' ? '[system]' : (backup.moduleId ?? 'unknown');
+      console.log('');
+      console.log(`  Backup:  ${shortId} (${module}, ${formatSize(backup.sizeBytes)})`);
+      console.log(`  Name:    ${backup.name ?? '(none)'}`);
+      console.log('');
+      return { success: true, message: backup.name ?? '(none)' };
+    }
+
+    // Set the name (join all remaining args — supports both quoted and unquoted)
+    const name = nameParts.join(' ');
+    celiloIntro('Set Backup Name');
+    updateBackupName(backup.id, name);
+    celiloOutro(`Backup ${shortId} named: "${name}"`);
+
+    return { success: true, message: `Named ${shortId}: ${name}` };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to update backup name: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/src/cli/commands/backup-prune.ts

@@ -0,0 +1,98 @@
+/**
+ * Backup Prune Command
+ * Remove old backups according to retention policies defined in module manifests.
+ */
+
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { modules } from '../../db/schema';
+import type { ModuleManifest } from '../../manifest/schema';
+import { findBackupEligibleModules } from '../../services/backup-create';
+import { pruneBackupsForModule } from '../../services/backup-retention';
+import { celiloIntro, celiloOutro } from '../prompts';
+import type { CommandResult } from '../types';
+
+export async function handleBackupPrune(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  try {
+    celiloIntro('Prune Old Backups');
+
+    const specificModule = args[0];
+    const dryRun = Boolean(flags['dry-run']);
+
+    if (dryRun) {
+      console.log('(dry run — no backups will be deleted)\n');
+    }
+
+    let totalDeleted = 0;
+
+    if (specificModule) {
+      // Prune a specific module
+      const db = getDb();
+      const mod = db.select().from(modules).where(eq(modules.id, specificModule)).get();
+      if (!mod) {
+        return { success: false, error: `Module not found: ${specificModule}` };
+      }
+
+      const manifest = mod.manifestData as unknown as ModuleManifest;
+      const retention = manifest.backup?.retention;
+      if (!retention) {
+        console.log(`Module '${specificModule}' has no retention policy defined.`);
+        return { success: true, message: 'No retention policy' };
+      }
+
+      const result = await pruneBackupsForModule(
+        specificModule,
+        { count: retention.count, maxAgeDays: retention.max_age_days },
+        dryRun,
+      );
+
+      if (result.deleted > 0) {
+        const verb = dryRun ? 'Would delete' : 'Deleted';
+        console.log(`${verb} ${result.deleted} backup(s) for ${specificModule}:`);
+        for (const path of result.deletedPaths) {
+          console.log(`  - ${path}`);
+        }
+      } else {
+        console.log(`No expired backups for ${specificModule}.`);
+      }
+      totalDeleted = result.deleted;
+    } else {
+      // Prune all modules with retention policies
+      const eligible = findBackupEligibleModules();
+
+      for (const { module: mod, manifest } of eligible) {
+        const retention = manifest.backup?.retention;
+        if (!retention) continue;
+
+        const result = await pruneBackupsForModule(
+          mod.id,
+          { count: retention.count, maxAgeDays: retention.max_age_days },
+          dryRun,
+        );
+
+        if (result.deleted > 0) {
+          const verb = dryRun ? 'Would delete' : 'Deleted';
+          console.log(`${verb} ${result.deleted} backup(s) for ${mod.id}`);
+          totalDeleted += result.deleted;
+        }
+      }
+
+      if (totalDeleted === 0) {
+        console.log('No expired backups found.');
+      }
+    }
+
+    const verb = dryRun ? 'would be deleted' : 'deleted';
+    celiloOutro(totalDeleted > 0 ? `${totalDeleted} backup(s) ${verb}.` : 'No backups to prune.');
+
+    return { success: true, message: `Pruned ${totalDeleted} backup(s)` };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to prune backups: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/src/cli/commands/backup-restore.ts

@@ -0,0 +1,122 @@
+/**
+ * Backup Restore Command
+ * Restores from a backup archive, executing the module's on_restore hook.
+ */
+
+import * as p from '@clack/prompts';
+import { formatSize, getBackup } from '../../services/backup-metadata';
+import { restoreModuleBackup, restoreSystemStateBackup } from '../../services/backup-restore';
+import { getBackupStorage } from '../../services/backup-storage';
+import { celiloIntro, celiloOutro } from '../prompts';
+import type { CommandResult } from '../types';
+
+export async function handleBackupRestore(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  try {
+    celiloIntro('Restore Backup');
+
+    const backupId = args[0];
+    if (!backupId) {
+      return {
+        success: false,
+        error: 'Backup ID is required\n\nUsage: celilo backup restore <backup-id>',
+      };
+    }
+
+    const backup = getBackup(backupId);
+    if (!backup) {
+      return { success: false, error: `Backup not found: ${backupId}` };
+    }
+
+    if (backup.status !== 'completed') {
+      return {
+        success: false,
+        error: `Cannot restore backup with status '${backup.status}'. Only completed backups can be restored.`,
+      };
+    }
+
+    // Show backup details
+    const storage = getBackupStorage(backup.storageId);
+    const isSystem = backup.backupType === 'system_state';
+
+    console.log('\nBackup Details:');
+    console.log(`  Type:           ${isSystem ? 'System State' : 'Module Data'}`);
+    if (!isSystem) {
+      console.log(`  Module:         ${backup.moduleId ?? 'unknown'}`);
+      if (backup.moduleVersion) {
+        console.log(`  Module Version: ${backup.moduleVersion}`);
+      }
+      if (backup.schemaVersion) {
+        console.log(`  Schema Version: ${backup.schemaVersion}`);
+      }
+    }
+    console.log(
+      `  Date:           ${new Date(backup.startedAt).toISOString().replace('T', ' ').substring(0, 19)} UTC`,
+    );
+    console.log(`  Size:           ${formatSize(backup.sizeBytes)}`);
+    console.log(`  Storage:        ${storage?.storageId ?? 'unknown'}`);
+    console.log('');
+
+    if (isSystem) {
+      console.log('⚠ This will replace the current Celilo database with the backup version.');
+      console.log('  All module configs, secrets, and state will be overwritten.\n');
+    }
+
+    // Confirm unless --yes
+    if (!flags.yes) {
+      const confirmed = await p.confirm({
+        message: 'Proceed with restore?',
+        initialValue: false,
+      });
+
+      if (p.isCancel(confirmed) || !confirmed) {
+        p.cancel('Restore cancelled');
+        return { success: false, error: 'Cancelled by user' };
+      }
+    }
+
+    if (isSystem) {
+      // System state restore
+      console.log('\n▸ Downloading and decrypting backup...');
+      const result = await restoreSystemStateBackup(backup);
+
+      if (!result.success) {
+        console.log(`✗ ${result.error}`);
+        return { success: false, error: result.error ?? 'Restore failed' };
+      }
+
+      console.log('✓ System state restored');
+      celiloOutro('Restore complete. The database has been replaced with the backup version.');
+    } else {
+      // Module data restore
+      console.log('\n▸ Downloading and decrypting backup...');
+      console.log('▸ Executing on_restore hook...');
+
+      const result = await restoreModuleBackup(backup, { runHealthCheck: true });
+
+      if (!result.success) {
+        console.log(`✗ ${result.error}`);
+        return { success: false, error: result.error ?? 'Restore failed' };
+      }
+
+      console.log('✓ on_restore completed');
+
+      if (result.healthCheckPassed === true) {
+        console.log('✓ Health check passed');
+      } else if (result.healthCheckPassed === false) {
+        console.log('⚠ Health check failed after restore');
+      }
+
+      celiloOutro('Restore complete.');
+    }
+
+    return { success: true, message: `Restored backup: ${backupId}` };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Restore failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/src/cli/commands/capability-info.ts

@@ -0,0 +1,121 @@
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { capabilities, capabilitySecrets, modules } from '../../db/schema';
+import { getArg, validateRequiredArgs } from '../parser';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle capability info command
+ *
+ * Usage: celilo capability info <name>
+ *
+ * @param args - Command arguments
+ * @returns Command result with capability details
+ */
+export async function handleCapabilityInfo(args: string[]): Promise<CommandResult> {
+  const error = validateRequiredArgs(args, 1);
+  if (error) {
+    return {
+      success: false,
+      error: `${error}\n\nUsage: celilo capability info <name>`,
+    };
+  }
+
+  const capabilityName = getArg(args, 0);
+
+  if (!capabilityName) {
+    return {
+      success: false,
+      error: 'Capability name is required',
+    };
+  }
+
+  const db = getDb();
+
+  const capability = db
+    .select({
+      id: capabilities.id,
+      capabilityName: capabilities.capabilityName,
+      version: capabilities.version,
+      data: capabilities.data,
+      moduleId: capabilities.moduleId,
+      moduleState: modules.state,
+      registeredAt: capabilities.registeredAt,
+    })
+    .from(capabilities)
+    .innerJoin(modules, eq(capabilities.moduleId, modules.id))
+    .where(eq(capabilities.capabilityName, capabilityName))
+    .get();
+
+  if (!capability) {
+    return {
+      success: false,
+      error: `Capability not found: ${capabilityName}`,
+    };
+  }
+
+  // Get capability secrets
+  const secretRows = db
+    .select({
+      name: capabilitySecrets.name,
+      description: capabilitySecrets.description,
+      hasValue: capabilitySecrets.encryptedValue,
+    })
+    .from(capabilitySecrets)
+    .where(eq(capabilitySecrets.capabilityId, capability.id))
+    .all();
+
+  const sections: string[] = [];
+
+  // Section 1: Capability metadata
+  const metaLines = [
+    `Capability: ${capability.capabilityName}`,
+    `Version: ${capability.version}`,
+    `Provider: ${capability.moduleId} (state: ${capability.moduleState})`,
+    `Registered: ${capability.registeredAt.toISOString()}`,
+  ];
+  sections.push(metaLines.join('\n'));
+
+  // Section 2: Capability data
+  if (capability.data && Object.keys(capability.data).length > 0) {
+    const dataLines = ['Data:'];
+    formatData(capability.data, dataLines, 1);
+    sections.push(dataLines.join('\n'));
+  } else {
+    sections.push('Data: (none)');
+  }
+
+  // Section 3: Secrets
+  if (secretRows.length > 0) {
+    const secretLines = ['Secrets:'];
+    for (const secret of secretRows) {
+      const status = secret.hasValue ? '[configured]' : '[not set]';
+      const desc = secret.description ? ` - ${secret.description}` : '';
+      secretLines.push(`  ${secret.name}: ${status}${desc}`);
+    }
+    sections.push(secretLines.join('\n'));
+  }
+
+  return {
+    success: true,
+    message: sections.join('\n\n'),
+    data: { capability, secrets: secretRows },
+  };
+}
+
+/**
+ * Format nested data object for display
+ */
+function formatData(data: Record<string, unknown>, lines: string[], depth: number): void {
+  const indent = '  '.repeat(depth);
+  for (const [key, value] of Object.entries(data)) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      lines.push(`${indent}${key}:`);
+      formatData(value as Record<string, unknown>, lines, depth + 1);
+    } else if (Array.isArray(value)) {
+      lines.push(`${indent}${key}: [${value.join(', ')}]`);
+    } else {
+      lines.push(`${indent}${key}: ${value}`);
+    }
+  }
+}

package/src/cli/commands/capability-list.ts

@@ -0,0 +1,47 @@
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/client';
+import { capabilities, modules } from '../../db/schema';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle capability list command
+ *
+ * Usage: celilo capability list
+ *
+ * @returns Command result with all registered capabilities
+ */
+export async function handleCapabilityList(): Promise<CommandResult> {
+  const db = getDb();
+
+  const rows = db
+    .select({
+      capabilityName: capabilities.capabilityName,
+      version: capabilities.version,
+      moduleId: capabilities.moduleId,
+      moduleState: modules.state,
+    })
+    .from(capabilities)
+    .innerJoin(modules, eq(capabilities.moduleId, modules.id))
+    .all();
+
+  if (rows.length === 0) {
+    return {
+      success: true,
+      message:
+        'No capabilities registered\n\nCapabilities are registered when modules with "provides.capabilities" are imported.',
+    };
+  }
+
+  const lines = ['Registered capabilities:', ''];
+  for (const row of rows) {
+    lines.push(
+      `${row.capabilityName} v${row.version} (provided by: ${row.moduleId}, state: ${row.moduleState})`,
+    );
+  }
+
+  return {
+    success: true,
+    message: lines.join('\n'),
+    data: rows,
+  };
+}

package/src/cli/commands/completion.ts

@@ -0,0 +1,87 @@
+/**
+ * Completion Command
+ * Generate shell completion scripts for bash/zsh
+ */
+
+import { COMMANDS } from '../command-registry';
+import { generateBashCompletion } from '../completion';
+import { generateRichZshCompletion } from '../generate-zsh-completion';
+import { celiloIntro } from '../prompts';
+import type { CommandResult } from '../types';
+
+/**
+ * Handle completion command
+ *
+ * @param args - Command arguments: [shell]
+ * @param flags - Command flags
+ */
+export async function handleCompletion(
+  args: string[],
+  _flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  try {
+    const shell = args[0];
+
+    if (!shell) {
+      celiloIntro('Shell Completion');
+
+      return {
+        success: false,
+        error: `Shell argument required.
+
+Usage:
+  celilo completion bash    Generate bash completion script
+  celilo completion zsh     Generate zsh completion script
+
+Install zsh completions:
+  celilo completion zsh > ~/.zsh/completions/_celilo
+  exec zsh
+`,
+      };
+    }
+
+    if (shell === 'bash') {
+      const script = generateBashCompletion();
+      return {
+        success: true,
+        message: script,
+      };
+    }
+
+    if (shell === 'zsh') {
+      const script = generateRichZshCompletion(COMMANDS);
+      return {
+        success: true,
+        message: script,
+      };
+    }
+
+    celiloIntro('Shell Completion');
+
+    return {
+      success: false,
+      error: `Unknown shell: ${shell}
+
+Supported shells:
+  bash  Generate bash completion script
+  zsh   Generate zsh completion script
+
+Usage:
+  # Bash
+  celilo completion bash > /etc/bash_completion.d/celilo
+  # OR for user install:
+  celilo completion bash >> ~/.bashrc
+
+  # Zsh
+  celilo completion zsh > ~/.zsh/completions/_celilo
+  # OR for user install:
+  celilo completion zsh > /usr/local/share/zsh/site-functions/_celilo
+`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to generate completion script: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}