@celilo/cli 0.1.0

package/src/db/migrate.ts

@@ -0,0 +1,30 @@
+import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
+import { closeDb, createDbClient, findMigrationsFolder } from './client';
+
+/**
+ * Run database migrations
+ */
+export async function runMigrations(dbPath?: string) {
+  console.log('Running database migrations...');
+
+  const db = createDbClient(dbPath ? { path: dbPath } : undefined);
+
+  try {
+    const migrationsFolder = findMigrationsFolder();
+    await migrate(db, { migrationsFolder });
+    console.log('Migrations completed successfully');
+  } catch (error) {
+    console.error('Migration failed:', error);
+    throw error;
+  } finally {
+    closeDb();
+  }
+}
+
+// Run migrations if executed directly
+if (import.meta.main) {
+  runMigrations().catch((error) => {
+    console.error('Failed to run migrations:', error);
+    process.exit(1);
+  });
+}

package/src/db/schema.test.ts

@@ -0,0 +1,221 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
+import { eq } from 'drizzle-orm';
+import { type DbClient, createDbClient } from './client';
+import { capabilities, moduleConfigs, modules, secrets } from './schema';
+import type { NewCapability, NewModule, NewModuleConfig, NewSecret } from './schema';
+
+describe('Database Schema', () => {
+  let db: DbClient;
+  let testDbPath: string;
+
+  beforeEach(async () => {
+    // Create unique database path for each test
+    testDbPath = `./test-celilo-${Date.now()}-${Math.random()}.db`;
+
+    // Create fresh database
+    db = createDbClient({ path: testDbPath });
+
+    // Create tables manually for testing (no migrations yet)
+    db.$client.run(`
+      CREATE TABLE IF NOT EXISTS modules (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        version TEXT NOT NULL,
+        description TEXT,
+        state TEXT NOT NULL DEFAULT 'IMPORTED',
+        manifest_data TEXT NOT NULL,
+        source_path TEXT NOT NULL,
+        imported_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        error_message TEXT
+      )
+    `);
+
+    db.$client.run(`
+      CREATE TABLE IF NOT EXISTS module_configs (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        module_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        value_json TEXT,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        FOREIGN KEY (module_id) REFERENCES modules(id) ON DELETE CASCADE
+      )
+    `);
+
+    db.$client.run(`
+      CREATE TABLE IF NOT EXISTS capabilities (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        module_id TEXT NOT NULL,
+        capability_name TEXT NOT NULL,
+        version TEXT NOT NULL,
+        data TEXT NOT NULL,
+        registered_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        FOREIGN KEY (module_id) REFERENCES modules(id) ON DELETE CASCADE
+      )
+    `);
+
+    db.$client.run(`
+      CREATE TABLE IF NOT EXISTS secrets (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        module_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        encrypted_value TEXT NOT NULL,
+        iv TEXT NOT NULL,
+        auth_tag TEXT NOT NULL,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+        FOREIGN KEY (module_id) REFERENCES modules(id) ON DELETE CASCADE
+      )
+    `);
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    if (existsSync(testDbPath)) {
+      await unlink(testDbPath);
+    }
+    // Clean up WAL and SHM files
+    const walPath = `${testDbPath}-wal`;
+    const shmPath = `${testDbPath}-shm`;
+    if (existsSync(walPath)) {
+      await unlink(walPath);
+    }
+    if (existsSync(shmPath)) {
+      await unlink(shmPath);
+    }
+  });
+
+  test('should create a module', () => {
+    const newModule: NewModule = {
+      id: 'homebridge',
+      name: 'Homebridge',
+      version: '1.0.0',
+      description: 'HomeKit bridge',
+      sourcePath: '/data/modules/homebridge',
+      manifestData: { id: 'homebridge', requires: {} },
+    };
+
+    const result = db.insert(modules).values(newModule).returning().get();
+
+    expect(result).toBeDefined();
+    expect(result.id).toBe('homebridge');
+    expect(result.name).toBe('Homebridge');
+    expect(result.state).toBe('IMPORTED');
+  });
+
+  test('should create module config', () => {
+    // Insert module first
+    const newModule: NewModule = {
+      id: 'homebridge',
+      name: 'Homebridge',
+      version: '1.0.0',
+      sourcePath: '/data/modules/homebridge',
+      manifestData: {},
+    };
+    db.insert(modules).values(newModule).run();
+
+    // Insert config
+    const newConfig: NewModuleConfig = {
+      moduleId: 'homebridge',
+      key: 'container_ip',
+      value: '192.168.0.50',
+    };
+
+    const result = db.insert(moduleConfigs).values(newConfig).returning().get();
+
+    expect(result).toBeDefined();
+    expect(result.moduleId).toBe('homebridge');
+    expect(result.key).toBe('container_ip');
+    expect(result.value).toBe('192.168.0.50');
+  });
+
+  test('should create capability', () => {
+    // Insert module first
+    const newModule: NewModule = {
+      id: 'dns-external',
+      name: 'DNS External',
+      version: '1.0.0',
+      sourcePath: '/data/modules/dns-external',
+      manifestData: {},
+    };
+    db.insert(modules).values(newModule).run();
+
+    // Insert capability
+    const newCapability: NewCapability = {
+      moduleId: 'dns-external',
+      capabilityName: 'dns_external',
+      version: '1.0.0',
+      data: {
+        nameserver: 'ns1.example.com',
+        zone: 'example.com',
+      },
+    };
+
+    const result = db.insert(capabilities).values(newCapability).returning().get();
+
+    expect(result).toBeDefined();
+    expect(result.capabilityName).toBe('dns_external');
+    expect(result.data).toEqual({
+      nameserver: 'ns1.example.com',
+      zone: 'example.com',
+    });
+  });
+
+  test('should create secret', () => {
+    // Insert module first
+    const newModule: NewModule = {
+      id: 'dns-external',
+      name: 'DNS External',
+      version: '1.0.0',
+      sourcePath: '/data/modules/dns-external',
+      manifestData: {},
+    };
+    db.insert(modules).values(newModule).run();
+
+    // Insert secret
+    const newSecret: NewSecret = {
+      moduleId: 'dns-external',
+      name: 'tsig_key',
+      encryptedValue: 'encrypted_data_here',
+      iv: 'initialization_vector',
+      authTag: 'authentication_tag',
+    };
+
+    const result = db.insert(secrets).values(newSecret).returning().get();
+
+    expect(result).toBeDefined();
+    expect(result.name).toBe('tsig_key');
+    expect(result.encryptedValue).toBe('encrypted_data_here');
+  });
+
+  test('should cascade delete module configs when module is deleted', () => {
+    // Insert module
+    const newModule: NewModule = {
+      id: 'homebridge',
+      name: 'Homebridge',
+      version: '1.0.0',
+      sourcePath: '/data/modules/homebridge',
+      manifestData: {},
+    };
+    db.insert(modules).values(newModule).run();
+
+    // Insert config
+    const newConfig: NewModuleConfig = {
+      moduleId: 'homebridge',
+      key: 'container_ip',
+      value: '192.168.0.50',
+    };
+    db.insert(moduleConfigs).values(newConfig).run();
+
+    // Delete module
+    db.delete(modules).where(eq(modules.id, 'homebridge')).run();
+
+    // Config should be deleted
+    const configs = db.select().from(moduleConfigs).all();
+    expect(configs).toHaveLength(0);
+  });
+});

package/src/db/schema.ts

@@ -0,0 +1,434 @@
+import { sql } from 'drizzle-orm';
+import { integer, sqliteTable, text, unique } from 'drizzle-orm/sqlite-core';
+
+/**
+ * Module lifecycle states
+ * IMPORTED, VALIDATED, CONFIGURED, GENERATING, ERROR, DEPLOYING, INSTALLED, VERIFIED, UNINSTALLING
+ */
+export type ModuleState =
+  | 'IMPORTED'
+  | 'VALIDATED'
+  | 'CONFIGURED'
+  | 'GENERATING'
+  | 'DEPLOYING'
+  | 'INSTALLED'
+  | 'VERIFIED'
+  | 'ERROR'
+  | 'UNINSTALLING';
+
+/**
+ * Modules table - stores module metadata and manifest data
+ */
+export const modules = sqliteTable('modules', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  version: text('version').notNull(),
+  description: text('description'),
+  state: text('state').$type<ModuleState>().notNull().default('IMPORTED'),
+  manifestData: text('manifest_data', { mode: 'json' }).$type<Record<string, unknown>>().notNull(),
+  sourcePath: text('source_path').notNull(),
+  importedAt: integer('imported_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  errorMessage: text('error_message'),
+});
+
+/**
+ * Module configuration - user-provided key-value pairs
+ * Stores configuration like container_ip, zone, etc.
+ *
+ * For primitive types (string, number, boolean):
+ *   - value: contains the value (as string)
+ *   - valueJson: NULL
+ *
+ * For complex types (arrays, objects):
+ *   - value: empty string
+ *   - valueJson: JSON-stringified complex value
+ */
+export const moduleConfigs = sqliteTable(
+  'module_configs',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    moduleId: text('module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    key: text('key').notNull(),
+    value: text('value').notNull(),
+    valueJson: text('value_json'), // JSON for complex types (arrays, objects)
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    uniqueModuleKey: unique().on(table.moduleId, table.key),
+  }),
+);
+
+/**
+ * Capabilities table - stores registered capabilities provided by modules
+ * Example: namecheap module provides dns_registrar capability
+ */
+export const capabilities = sqliteTable('capabilities', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  moduleId: text('module_id')
+    .notNull()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  capabilityName: text('capability_name').notNull(),
+  version: text('version').notNull(),
+  data: text('data', { mode: 'json' }).$type<Record<string, unknown>>().notNull(),
+  /** JSON array of zone names this capability applies to, or null for zone-agnostic */
+  zones: text('zones', { mode: 'json' }).$type<string[] | null>(),
+  registeredAt: integer('registered_at', { mode: 'timestamp' })
+    .notNull()
+    .default(sql`(unixepoch())`),
+});
+
+/**
+ * Capability secrets table - stores encrypted secrets owned by capabilities
+ * Values are encrypted with AES-256-GCM using master key
+ * Example: dns-external capability owns TSIG secret
+ */
+export const capabilitySecrets = sqliteTable(
+  'capability_secrets',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    capabilityId: integer('capability_id')
+      .notNull()
+      .references(() => capabilities.id, { onDelete: 'cascade' }),
+    name: text('name').notNull(),
+    description: text('description'), // Added to store secret description
+    encryptedValue: text('encrypted_value'), // Nullable - allows metadata-only storage during import
+    iv: text('iv'), // Nullable - populated when secret value is set
+    authTag: text('auth_tag'), // Nullable - populated when secret value is set
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    uniqueCapabilitySecret: unique().on(table.capabilityId, table.name),
+  }),
+);
+
+/**
+ * Secrets table - stores encrypted secrets per module
+ * Values are encrypted with AES-256-GCM using master key
+ */
+export const secrets = sqliteTable('secrets', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  moduleId: text('module_id')
+    .notNull()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  name: text('name').notNull(),
+  encryptedValue: text('encrypted_value').notNull(),
+  iv: text('iv').notNull(),
+  authTag: text('auth_tag').notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * System configuration - system-wide settings
+ * Used for $system: variables in templates
+ * Examples: DNS servers, network settings, domain names
+ */
+export const systemConfig = sqliteTable('system_config', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  key: text('key').notNull().unique(),
+  value: text('value').notNull(),
+  description: text('description'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * System secrets table - stores encrypted system-level secrets
+ * Values are encrypted with AES-256-GCM using master key
+ * Examples: Proxmox root password, API tokens, SSH keys
+ */
+export const systemSecrets = sqliteTable('system_secrets', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  key: text('key').notNull().unique(),
+  encryptedValue: text('encrypted_value').notNull(),
+  iv: text('iv').notNull(),
+  authTag: text('auth_tag').notNull(),
+  description: text('description'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * Module integrity table - stores checksums and signature for package verification
+ * Used for runtime auditing to detect tampering, missing files, or extra files
+ */
+export const moduleIntegrity = sqliteTable('module_integrity', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  moduleId: text('module_id')
+    .notNull()
+    .unique()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  checksums: text('checksums', { mode: 'json' }).$type<Record<string, string>>().notNull(), // { "path/to/file": "xxhash", ... }
+  signature: text('signature'), // Nullable - null for directory imports, populated for .netapp packages
+  importedAt: integer('imported_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * IPAM (IP Address Management) allocations table
+ * Tracks VMID and IP address assignments per module
+ * Prevents conflicts and enables automatic allocation from zone subnets
+ */
+export const ipAllocations = sqliteTable('ip_allocations', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  moduleId: text('module_id')
+    .notNull()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  vmid: integer('vmid').notNull().unique(),
+  containerIp: text('container_ip').notNull().unique(), // CIDR format (e.g., "10.0.10.10/24")
+  zone: text('zone').$type<'dmz' | 'app' | 'secure' | 'internal'>().notNull(),
+  allocatedAt: integer('allocated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * IP reservations table
+ * Allows users to reserve IPs for infrastructure or external services
+ * IPAM allocator skips reserved IPs
+ */
+export const ipReservations = sqliteTable('ip_reservations', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  ipStart: text('ip_start').notNull(), // Single IP or range start
+  ipEnd: text('ip_end'), // NULL for single IP, end IP for range
+  zone: text('zone').$type<'dmz' | 'app' | 'secure' | 'internal'>().notNull(),
+  reason: text('reason').notNull(),
+  reservedAt: integer('reserved_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * VMID reservations table
+ * Allows users to reserve VMIDs for existing VMs or external systems
+ * IPAM allocator skips reserved VMIDs
+ */
+export const vmidReservations = sqliteTable('vmid_reservations', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  vmid: integer('vmid').notNull().unique(),
+  reason: text('reason').notNull(),
+  reservedAt: integer('reserved_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * Module builds table
+ * Tracks build metadata for modules with custom compilation requirements
+ * Example: Caddy with RFC2136 DNS provider, custom Go binaries
+ */
+export type BuildStatus = 'success' | 'failed' | 'in_progress';
+
+export const moduleBuilds = sqliteTable('module_builds', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  moduleId: text('module_id')
+    .notNull()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  version: text('version').notNull(),
+  builtAt: integer('built_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  artifacts: text('artifacts', { mode: 'json' }).$type<string[]>().notNull(), // Array of artifact paths
+  environment: text('environment').$type<'nix' | 'system'>(),
+  status: text('status').$type<BuildStatus>().notNull(),
+  buildLog: text('build_log'), // Build output for debugging
+});
+
+/**
+ * Network zones type
+ * - internal: Home network (192.168.0.0/24)
+ * - dmz: Public-facing services in home lab (10.0.10.0/24)
+ * - app: Internal application services (10.0.20.0/24)
+ * - secure: Authentication and database services (10.0.30.0/24)
+ * - external: Internet-hosted services (outside home network)
+ */
+export type NetworkZone = 'internal' | 'dmz' | 'app' | 'secure' | 'external';
+
+/**
+ * Container services table
+ * Stores container service providers (Proxmox, Digital Ocean, etc.)
+ * that can provision new containers/VMs on demand
+ */
+export const containerServices = sqliteTable('container_services', {
+  id: text('id').primaryKey(), // UUID
+  serviceId: text('service_id').notNull().unique(), // User-facing kebab-case ID
+  name: text('name').notNull(),
+  providerName: text('provider_name')
+    .$type<'proxmox' | 'digitalocean' | 'aws' | 'gcp' | 'azure'>()
+    .notNull(),
+  zones: text('zones', { mode: 'json' }).$type<NetworkZone[]>().notNull(),
+  apiCredentialsEncrypted: text('api_credentials_encrypted').notNull(),
+  providerConfig: text('provider_config', { mode: 'json' })
+    .$type<Record<string, unknown>>()
+    .notNull(),
+  verified: integer('verified', { mode: 'boolean' }).notNull().default(false),
+  verifiedAt: integer('verified_at', { mode: 'timestamp' }),
+  verificationError: text('verification_error'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * Machines table
+ * Stores pre-existing machines (Raspberry Pi, VPS, bare metal)
+ * that users have added to the pool for hosting modules
+ */
+export const machines = sqliteTable('machines', {
+  id: text('id').primaryKey(), // UUID
+  hostname: text('hostname').notNull(),
+  zone: text('zone').$type<NetworkZone>().notNull(),
+  ipAddress: text('ip_address').notNull(),
+  sshUser: text('ssh_user').notNull(),
+  sshKeyEncrypted: text('ssh_key_encrypted').notNull(),
+  hardware: text('hardware', { mode: 'json' })
+    .$type<{
+      cpu_cores: number;
+      memory_mb: number;
+      disk_gb: number;
+      arch?: string;
+    }>()
+    .notNull(),
+  /** Machine classification: 'host' (single interface) or 'router' (multi-interface) */
+  role: text('role').$type<'host' | 'router'>().notNull().default('host'),
+  /** Detected network interfaces with IPs and zones */
+  interfaces: text('interfaces', { mode: 'json' })
+    .$type<Array<{ name: string; ipAddress: string; zone: string }>>()
+    .notNull()
+    .default(sql`'[]'`),
+  assignedModuleIds: text('assigned_module_ids', { mode: 'json' })
+    .$type<string[]>()
+    .notNull()
+    .default(sql`'[]'`),
+  /** Module ID this machine is earmarked for. If set, only this module can use this machine. */
+  earmarkedModule: text('earmarked_module'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * Module infrastructure table
+ * Tracks which infrastructure (machine or container service) is used for each module
+ */
+export const moduleInfrastructure = sqliteTable('module_infrastructure', {
+  id: text('id').primaryKey(), // UUID
+  moduleId: text('module_id')
+    .notNull()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  infrastructureType: text('infrastructure_type')
+    .$type<'machine' | 'container_service'>()
+    .notNull(),
+  machineId: text('machine_id').references(() => machines.id),
+  serviceId: text('service_id').references(() => containerServices.id),
+  containerMetadata: text('container_metadata', { mode: 'json' }).$type<Record<string, unknown>>(), // VMID, droplet ID, etc.
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * Web routes table
+ * Tracks routes registered by modules via public_web capability functions.
+ * Routes are registered during on_install hooks and removed during on_uninstall.
+ * The public_web provider (Caddy) uses these to generate its configuration.
+ */
+export const webRoutes = sqliteTable('web_routes', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  slug: text('slug').notNull(),
+  moduleId: text('module_id')
+    .notNull()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  type: text('type').$type<'static' | 'reverse_proxy'>().notNull(),
+  path: text('path').notNull().unique(),
+  targetHost: text('target_host'),
+  targetPort: integer('target_port'),
+  subdomain: text('subdomain'),
+  websocket: integer('websocket', { mode: 'boolean' }).notNull().default(false),
+  contentHash: text('content_hash'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * Backup storage providers - destinations for backup archives
+ * Supports local filesystem and S3-compatible storage (AWS S3, MinIO, Backblaze B2, Wasabi)
+ */
+export type BackupStorageProvider = 'local' | 's3';
+
+export const backupStorages = sqliteTable('backup_storages', {
+  id: text('id').primaryKey(), // UUID
+  storageId: text('storage_id').notNull().unique(), // User-facing kebab-case ID
+  name: text('name').notNull(),
+  providerName: text('provider_name').$type<BackupStorageProvider>().notNull(),
+  credentialsEncrypted: text('credentials_encrypted').notNull(), // Encrypted JSON blob
+  providerConfig: text('provider_config', { mode: 'json' })
+    .$type<Record<string, unknown>>()
+    .notNull(),
+  verified: integer('verified', { mode: 'boolean' }).notNull().default(false),
+  verifiedAt: integer('verified_at', { mode: 'timestamp' }),
+  verificationError: text('verification_error'),
+  isDefault: integer('is_default', { mode: 'boolean' }).notNull().default(false),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * Backup records - metadata for each backup taken
+ * Tracks both system state backups and module data backups
+ */
+export type BackupType = 'module_data' | 'system_state';
+export type BackupStatus = 'in_progress' | 'completed' | 'failed';
+
+export const backups = sqliteTable('backups', {
+  id: text('id').primaryKey(), // UUID
+  moduleId: text('module_id').references(() => modules.id, { onDelete: 'set null' }), // null = system state backup
+  storageId: text('storage_id')
+    .notNull()
+    .references(() => backupStorages.id),
+  storagePath: text('storage_path').notNull(), // path/key within storage
+  backupType: text('backup_type').$type<BackupType>().notNull(),
+  moduleVersion: text('module_version'), // module version at backup time
+  schemaVersion: text('schema_version'), // optional data schema version from on_backup hook
+  sizeBytes: integer('size_bytes'),
+  metadata: text('metadata', { mode: 'json' })
+    .$type<Record<string, unknown>>()
+    .notNull()
+    .default(sql`'{}'`),
+  status: text('status').$type<BackupStatus>().notNull().default('in_progress'),
+  errorMessage: text('error_message'),
+  name: text('name'), // optional human-readable name/annotation
+  startedAt: integer('started_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  completedAt: integer('completed_at', { mode: 'timestamp' }),
+});
+
+/**
+ * Type exports for use in application code
+ */
+export type Module = typeof modules.$inferSelect;
+export type NewModule = typeof modules.$inferInsert;
+export type ModuleConfig = typeof moduleConfigs.$inferSelect;
+export type NewModuleConfig = typeof moduleConfigs.$inferInsert;
+export type Capability = typeof capabilities.$inferSelect;
+export type NewCapability = typeof capabilities.$inferInsert;
+export type Secret = typeof secrets.$inferSelect;
+export type NewSecret = typeof secrets.$inferInsert;
+export type SystemConfig = typeof systemConfig.$inferSelect;
+export type NewSystemConfig = typeof systemConfig.$inferInsert;
+export type SystemSecret = typeof systemSecrets.$inferSelect;
+export type NewSystemSecret = typeof systemSecrets.$inferInsert;
+export type ModuleIntegrity = typeof moduleIntegrity.$inferSelect;
+export type NewModuleIntegrity = typeof moduleIntegrity.$inferInsert;
+export type IpAllocation = typeof ipAllocations.$inferSelect;
+export type NewIpAllocation = typeof ipAllocations.$inferInsert;
+export type IpReservation = typeof ipReservations.$inferSelect;
+export type NewIpReservation = typeof ipReservations.$inferInsert;
+export type VmidReservation = typeof vmidReservations.$inferSelect;
+export type NewVmidReservation = typeof vmidReservations.$inferInsert;
+export type ModuleBuild = typeof moduleBuilds.$inferSelect;
+export type NewModuleBuild = typeof moduleBuilds.$inferInsert;
+export type ContainerService = typeof containerServices.$inferSelect;
+export type NewContainerService = typeof containerServices.$inferInsert;
+export type Machine = typeof machines.$inferSelect;
+export type NewMachine = typeof machines.$inferInsert;
+export type ModuleInfrastructure = typeof moduleInfrastructure.$inferSelect;
+export type NewModuleInfrastructure = typeof moduleInfrastructure.$inferInsert;
+export type WebRoute = typeof webRoutes.$inferSelect;
+export type NewWebRoute = typeof webRoutes.$inferInsert;
+export type BackupStorage = typeof backupStorages.$inferSelect;
+export type NewBackupStorage = typeof backupStorages.$inferInsert;
+export type Backup = typeof backups.$inferSelect;
+export type NewBackup = typeof backups.$inferInsert;