@celilo/cli 0.5.0-alpha.4 → 0.5.0-alpha.6

package/drizzle/0010_dns_internal_records.sql

@@ -0,0 +1,12 @@
+CREATE TABLE `dns_internal_records` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`provider_module_id` text NOT NULL,
+	`consumer_module_id` text NOT NULL,
+	`host` text NOT NULL,
+	`ip` text NOT NULL,
+	`registered_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`provider_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade,
+	FOREIGN KEY (`consumer_module_id`) REFERENCES `modules`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `dns_internal_records_provider_host_idx` ON `dns_internal_records` (`provider_module_id`,`host`);

package/drizzle/0011_backups_name.sql

@@ -0,0 +1 @@
+ALTER TABLE `backups` ADD `name` text;

package/drizzle/meta/_journal.json

@@ -71,6 +71,20 @@
       "when": 1781280898000,
       "tag": "0009_dns_registrations",
       "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "6",
+      "when": 1781481600000,
+      "tag": "0010_dns_internal_records",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "6",
+      "when": 1781481660000,
+      "tag": "0011_backups_name",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.5.0-alpha.4",
+  "version": "0.5.0-alpha.6",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -54,7 +54,7 @@
     "@aws-sdk/client-s3": "^3.1024.0",
     "@celilo/capabilities": "^0.4.2",
     "@celilo/cli-display": "^0.1.9",
-    "@celilo/event-bus": "^0.1.6",
+    "@celilo/event-bus": "^0.1.7",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/ansible/inventory.test.ts

@@ -61,7 +61,7 @@ describe('generateHostsIni', () => {
       },
       {
         hostname: 'dns-ext',
-        ansibleHost: '188.166.157.2',
+        ansibleHost: '192.0.2.20',
         ansibleUser: 'root',
         groups: ['dns_external'],
       },
@@ -72,7 +72,7 @@ describe('generateHostsIni', () => {
     expect(result).toContain('[homebridge]');
     expect(result).toContain('[dns_external]');
     expect(result).toContain('iot ansible_host=192.168.0.110 ansible_user=root');
-    expect(result).toContain('dns-ext ansible_host=188.166.157.2 ansible_user=root');
+    expect(result).toContain('dns-ext ansible_host=192.0.2.20 ansible_user=root');
   });
 
   test('includes SSH private key file path when provided', () => {
@@ -136,8 +136,8 @@ describe('generateHostVarsYaml', () => {
   test('generates YAML for arrays', () => {
     const vars = {
       zone_records: [
-        { name: 'ns1', type: 'A', value: '188.166.157.2' },
-        { name: 'www', type: 'A', value: '71.36.99.96' },
+        { name: 'ns1', type: 'A', value: '192.0.2.20' },
+        { name: 'www', type: 'A', value: '203.0.113.10' },
       ],
     };
 
@@ -146,9 +146,9 @@ describe('generateHostVarsYaml', () => {
     expect(result).toContain('zone_records:');
     expect(result).toContain('- name: ns1');
     expect(result).toContain('type: A');
-    expect(result).toContain('value: 188.166.157.2');
+    expect(result).toContain('value: 192.0.2.20');
     expect(result).toContain('- name: www');
-    expect(result).toContain('value: 71.36.99.96');
+    expect(result).toContain('value: 203.0.113.10');
   });
 
   test('generates YAML for nested objects', () => {
@@ -359,13 +359,13 @@ describe('Database integration', () => {
       );
 
       upsertModuleConfig(db, 'dns', 'zone_records', [
-        { name: 'ns1', type: 'A', value: '188.166.157.2' },
+        { name: 'ns1', type: 'A', value: '192.0.2.20' },
       ]);
 
       const vars = buildHostVars('dns', db);
 
       expect(Array.isArray(vars.zone_records)).toBe(true);
-      expect(vars.zone_records).toEqual([{ name: 'ns1', type: 'A', value: '188.166.157.2' }]);
+      expect(vars.zone_records).toEqual([{ name: 'ns1', type: 'A', value: '192.0.2.20' }]);
     });
   });
 
@@ -416,13 +416,13 @@ describe('Database integration', () => {
       );
 
       upsertModuleConfig(db, 'dns-external', 'hostname', 'dns-ext');
-      upsertModuleConfig(db, 'dns-external', 'vps_ip', '188.166.157.2');
+      upsertModuleConfig(db, 'dns-external', 'vps_ip', '192.0.2.20');
 
       const host = extractInventoryHost('dns-external', db);
 
       expect(host).not.toBeNull();
       expect(host?.hostname).toBe('dns-ext');
-      expect(host?.ansibleHost).toBe('188.166.157.2'); // VPS IP used directly
+      expect(host?.ansibleHost).toBe('192.0.2.20'); // VPS IP used directly
       expect(host?.ansibleUser).toBe('root');
       expect(host?.groups).toEqual(['dns-external']);
     });

package/src/ansible/validation.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'bun:test';
+import { skipIntegration } from '../test-utils/integration-guard';
 import {
   isAnsibleInventoryAvailable,
   isAnsibleLintAvailable,
@@ -54,17 +55,23 @@ describe('validateWithAnsibleLint', () => {
 });
 
 describe('validatePlaybookSyntax', () => {
-  test('returns error when playbook does not exist', async () => {
-    const result = await validatePlaybookSyntax('/nonexistent/playbook.yml', '/tmp');
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('Playbook not found');
-  });
+  test.skipIf(skipIntegration({ tools: ['ansible'] }))(
+    'returns error when playbook does not exist',
+    async () => {
+      const result = await validatePlaybookSyntax('/nonexistent/playbook.yml', '/tmp');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Playbook not found');
+    },
+  );
 
-  test('returns error when inventory does not exist', async () => {
-    const result = await validatePlaybookSyntax('/tmp/playbook.yml', '/nonexistent/inventory');
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('not found');
-  });
+  test.skipIf(skipIntegration({ tools: ['ansible'] }))(
+    'returns error when inventory does not exist',
+    async () => {
+      const result = await validatePlaybookSyntax('/tmp/playbook.yml', '/nonexistent/inventory');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('not found');
+    },
+  );
 
   test('returns error when ansible-playbook not installed', async () => {
     if (!isAnsiblePlaybookAvailable()) {
@@ -76,11 +83,14 @@ describe('validatePlaybookSyntax', () => {
 });
 
 describe('validateInventory', () => {
-  test('returns error when inventory does not exist', async () => {
-    const result = await validateInventory('/nonexistent/inventory');
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('Inventory not found');
-  });
+  test.skipIf(skipIntegration({ tools: ['ansible'] }))(
+    'returns error when inventory does not exist',
+    async () => {
+      const result = await validateInventory('/nonexistent/inventory');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Inventory not found');
+    },
+  );
 
   test('returns error when ansible-inventory not installed', async () => {
     if (!isAnsibleInventoryAvailable()) {

package/src/cli/command-registry.ts

@@ -956,14 +956,25 @@ export const COMMANDS: CommandDef[] = [
           },
         ],
       },
+      {
+        name: 'migrate',
+        description: 'Apply pending database migrations (idempotent; safe to re-run)',
+      },
       {
         name: 'doctor',
-        description: 'Diagnose system prerequisites and @celilo/* version drift',
+        description:
+          'Diagnose system prerequisites, @celilo/* version drift, and (on a management plane) fleet-runtime drift',
         flags: [
           {
             name: 'fix',
             description:
-              'Repair drift by `bun link`-ing each drifted @celilo/* package from the workspace',
+              'Repair the auto-fixable findings: `bun link` drifted @celilo/* packages and resync bus subscribers',
+            takesValue: false,
+          },
+          {
+            name: 'fleet',
+            description:
+              'Force the fleet-runtime section (dispatcher, subscribers, capability chains) even without a celilo DB',
             takesValue: false,
           },
         ],

package/src/cli/commands/events.test.ts

@@ -165,20 +165,20 @@ describe('celilo events command handlers', () => {
     });
     setupBus.close();
 
-    const res = await handleEventsReply([String(query.id), '"lunacycle.net"'], {});
+    const res = await handleEventsReply([String(query.id), '"example.net"'], {});
     expect(res.success).toBe(true);
     if (!res.success) throw new Error('expected success');
     const data = res.data as { status: string; family: string; value: unknown };
     expect(data.status).toBe('replied');
     expect(data.family).toBe('config');
-    expect(data.value).toBe('lunacycle.net');
+    expect(data.value).toBe('example.net');
 
     const checkBus = openBus({ dbPath, events: defineEvents({}) });
     const replies = checkBus.recentEvents({ type: 'config.required.lunacycle.domain.reply' });
     checkBus.close();
     expect(replies).toHaveLength(1);
     expect(replies[0].replyFor).toBe(query.id);
-    expect(replies[0].payload).toEqual({ value: 'lunacycle.net' });
+    expect(replies[0].payload).toEqual({ value: 'example.net' });
     expect(replies[0].emittedBy).toBe('claude-config-responder');
   });
 
@@ -229,7 +229,7 @@ describe('celilo events command handlers', () => {
     setupBus.close();
 
     // A bare word isn't valid JSON — the operator must quote strings.
-    const res = await handleEventsReply([String(query.id), 'lunacycle.net'], {});
+    const res = await handleEventsReply([String(query.id), 'example.net'], {});
     expect(res.success).toBe(false);
     if (res.success) throw new Error('expected failure');
     expect(res.error).toContain('Invalid JSON value');

package/src/cli/commands/events.ts

@@ -439,7 +439,7 @@ export async function handleEventsReply(
     return {
       success: false,
       error: `Usage: celilo events reply <query-event-id> <value-json>
-  e.g. celilo events reply 42 '"lunacycle.net"'`,
+  e.g. celilo events reply 42 '"example.net"'`,
     };
   }
   const queryId = Number(idArg);
@@ -454,7 +454,7 @@ export async function handleEventsReply(
     return {
       success: false,
       error: `Invalid JSON value: ${err instanceof Error ? err.message : String(err)}
-  Encode the answer as JSON, e.g. '"lunacycle.net"', '8080', '["a","b"]'.`,
+  Encode the answer as JSON, e.g. '"example.net"', '8080', '["a","b"]'.`,
     };
   }
 

package/src/cli/commands/service-add-proxmox.ts

@@ -122,6 +122,14 @@ export async function handleServiceAddProxmox(
       validate: validateRequired('Storage'),
     });
 
+    // VM template name for `requires.system.type: vm` modules. Optional —
+    // skip if you only deploy LXC modules. See v2/PROXMOX_VM_TEMPLATE.md.
+    const vmTemplateInput = await promptText({
+      message: 'VM template name (optional — for VM-type modules):',
+      placeholder: 'e.g., ubuntu-2404-cloud-init-9000',
+    });
+    const vmTemplate = vmTemplateInput?.trim() || undefined;
+
     // Find storage that supports vztmpl content. We do this BEFORE prompting
     // for a template so the user only ever sees one storage in subsequent
     // messages, and so the saved volid uses the right storage.
@@ -178,6 +186,7 @@ export async function handleServiceAddProxmox(
         default_target_node: targetNode,
         lxc_template: lxcTemplate,
         storage,
+        ...(vmTemplate ? { vm_template: vmTemplate } : {}),
       },
     });
 

package/src/cli/commands/system-doctor.ts

@@ -30,10 +30,20 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
+import { defineEvents, openBus } from '@celilo/event-bus';
 import cliPkg from '../../../package.json' with { type: 'json' };
+import { getDbPath, getEventBusPath } from '../../config/paths';
+import { getDb } from '../../db/client';
+import {
+  type FleetFinding,
+  type FleetFindingStatus,
+  checkSubscribers,
+  runFleetChecks,
+} from '../../services/fleet-checks';
+import { resyncAllSubscriptions } from '../../services/module-subscriptions';
 import { checkAllPrerequisites, failingPrerequisites } from '../../system/prereqs';
 import type { CommandResult } from '../types';
 
@@ -296,6 +306,93 @@ function renderPrereqSection(): { lines: string[]; failingCount: number } {
   return { lines, failingCount: failingPrerequisites(checks).length };
 }
 
+/**
+ * mtime (ms) of the installed dispatcher code (`@celilo/event-bus`
+ * package.json). The fleet dispatcher check compares this against the
+ * running dispatcher's start time to spot a process on stale code. Null
+ * when the package can't be located (the staleness aspect is then skipped).
+ */
+function installedEventBusMtime(): number | null {
+  try {
+    const require = createRequire(import.meta.url);
+    return statSync(require.resolve('@celilo/event-bus/package.json')).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+const FLEET_GLYPH: Record<FleetFindingStatus, string> = {
+  ok: `${ANSI.green}✔${ANSI.reset}`,
+  warn: `${ANSI.yellow}⚠${ANSI.reset}`,
+  fail: `${ANSI.red}✗${ANSI.reset}`,
+};
+
+function renderFleetFinding(f: FleetFinding): string[] {
+  const lines = [`  ${FLEET_GLYPH[f.status]} ${f.title}  ${ANSI.dim}— ${f.summary}${ANSI.reset}`];
+  for (const d of f.detail) lines.push(`      ${ANSI.dim}${d}${ANSI.reset}`);
+  if (f.remediation && f.status !== 'ok')
+    lines.push(`    ${ANSI.dim}→ ${f.remediation}${ANSI.reset}`);
+  return lines;
+}
+
+/**
+ * The fleet-runtime section: dispatcher / subscribers / capability-chain
+ * drift, read from the celilo DB + event bus. State-aware, so it's skipped
+ * cleanly on a fresh dev box with no DB unless `--fleet` forces it. `--fix`
+ * runs only the auto-fixable checks (today: subscribers resync).
+ */
+async function renderFleetSection(opts: { forced: boolean; fix: boolean }): Promise<{
+  lines: string[];
+  failCount: number;
+  warnCount: number;
+}> {
+  const lines: string[] = ['Fleet runtime'];
+  const dbExists = existsSync(getDbPath());
+
+  if (!dbExists) {
+    if (opts.forced) {
+      lines.push(
+        `  ${ANSI.dim}skipped — no celilo database at ${getDbPath()} (not a management plane)${ANSI.reset}`,
+      );
+      return { lines, failCount: 0, warnCount: 0 };
+    }
+    // Dev box, no --fleet: don't render the section at all.
+    return { lines: [], failCount: 0, warnCount: 0 };
+  }
+
+  const bus = openBus({ dbPath: getEventBusPath(), events: defineEvents({}) });
+  try {
+    const db = getDb();
+    let findings = await runFleetChecks(bus, db, {
+      installedCodeMtimeMs: installedEventBusMtime(),
+    });
+
+    if (opts.fix) {
+      const subscribers = findings.find((f) => f.id === 'subscribers');
+      if (subscribers?.autoFixable && subscribers.status !== 'ok') {
+        const r = resyncAllSubscriptions();
+        lines.push(
+          `  ${ANSI.dim}--fix: re-registered ${r.registered} subscription(s) from ${r.modules} module(s).${ANSI.reset}`,
+        );
+        // Re-evaluate the subscribers finding so the section shows the healed state.
+        const healed = checkSubscribers(bus, db);
+        findings = findings.map((f) => (f.id === 'subscribers' ? healed : f));
+      }
+    }
+
+    let failCount = 0;
+    let warnCount = 0;
+    for (const f of findings) {
+      lines.push(...renderFleetFinding(f));
+      if (f.status === 'fail') failCount++;
+      else if (f.status === 'warn') warnCount++;
+    }
+    return { lines, failCount, warnCount };
+  } finally {
+    bus.close();
+  }
+}
+
 export async function handleSystemDoctor(
   _args: string[],
   flags: Record<string, string | boolean>,
@@ -397,61 +494,59 @@ export async function handleSystemDoctor(
 
   const fix = flags.fix === true;
 
+  // Drift repair (bun link). Does NOT early-return — the fleet section
+  // still runs on a --fix invocation so a single `--fix` heals both.
   if (fix && drifted.length > 0) {
     lines.push(`Repairing ${drifted.length} drifted package(s) with \`bun link\`:`);
     lines.push(...applyFix(drifted, cliRoot));
+    lines.push(`${ANSI.dim}\`bun unlink\` from each workspace dir reverses.${ANSI.reset}`);
+    lines.push('');
+    // Linked from the workspace now — no longer drift for the summary.
+    driftCount = 0;
+    drifted.length = 0;
+  } else if (fix && drifted.length === 0) {
+    lines.push(`${ANSI.dim}--fix: no drifted packages to repair.${ANSI.reset}`);
     lines.push('');
+  } else if (drifted.length > 0) {
     lines.push(
-      `${ANSI.dim}Re-run \`celilo system doctor\` to verify; \`bun unlink\` from each workspace dir reverses.${ANSI.reset}`,
+      `${ANSI.dim}Run \`celilo system doctor --fix\` to bun-link drifted packages from the workspace.${ANSI.reset}`,
     );
-    // Note: --fix only addresses drift, not missing prereqs. If prereqs
-    // failed, surface that even on a successful --fix run.
-    if (prereqResult.failingCount > 0) {
-      return {
-        success: false,
-        error: `${prereqResult.failingCount} system prerequisite(s) missing or below minimum — install before running celilo`,
-        details: lines.join('\n'),
-      };
-    }
-    return {
-      success: true,
-      message: lines.join('\n'),
-      rawOutput: true,
-    };
+    lines.push('');
   }
 
-  if (fix && drifted.length === 0) {
-    lines.push(`${ANSI.dim}--fix: nothing to repair.${ANSI.reset}`);
+  // Fleet-runtime section (state-aware; only renders on a management
+  // plane with a celilo DB, or when --fleet forces it).
+  const fleet = await renderFleetSection({ forced: flags.fleet === true, fix });
+  if (fleet.lines.length > 0) {
+    lines.push(...fleet.lines);
+    lines.push('');
   }
 
-  if (driftCount > 0 || unresolvedCount > 0 || prereqResult.failingCount > 0) {
-    const summary: string[] = [];
-    if (prereqResult.failingCount > 0) {
-      summary.push(`${prereqResult.failingCount} prerequisite(s) missing/below-minimum`);
-    }
-    if (driftCount > 0) summary.push(`${driftCount} package(s) behind workspace`);
-    if (unresolvedCount > 0) summary.push(`${unresolvedCount} unresolved`);
-    if (drifted.length > 0) {
-      lines.push(
-        `${ANSI.dim}Run \`celilo system doctor --fix\` to bun-link drifted packages from the workspace.${ANSI.reset}`,
-      );
-    }
-    // Distinguish prereq-only from drift-only from both — the
-    // operator's next move is different.
-    const errorPrefix =
-      driftCount === 0 && unresolvedCount === 0
-        ? 'System prerequisites missing'
-        : prereqResult.failingCount === 0
-          ? 'Drift detected'
-          : 'Issues detected';
+  // Unified summary: anything that fails the run, with a per-cause count.
+  const problems: string[] = [];
+  if (prereqResult.failingCount > 0) {
+    problems.push(`${prereqResult.failingCount} prerequisite(s) missing/below-minimum`);
+  }
+  if (driftCount > 0) problems.push(`${driftCount} package(s) behind workspace`);
+  if (unresolvedCount > 0) problems.push(`${unresolvedCount} unresolved`);
+  if (fleet.failCount > 0) problems.push(`${fleet.failCount} fleet check(s) failing`);
+
+  if (problems.length > 0) {
     return {
       success: false,
-      error: `${errorPrefix}: ${summary.join(', ')}`,
+      error: `Issues detected: ${problems.join(', ')}`,
       details: lines.join('\n'),
     };
   }
 
-  lines.push(`${ANSI.green}OK${ANSI.reset} — no issues detected`);
+  // Fleet warnings don't fail the run, but they shouldn't read as a clean bill.
+  if (fleet.warnCount > 0) {
+    lines.push(
+      `${ANSI.yellow}OK with warnings${ANSI.reset} — ${fleet.warnCount} fleet warning(s); see above`,
+    );
+  } else {
+    lines.push(`${ANSI.green}OK${ANSI.reset} — no issues detected`);
+  }
   return {
     success: true,
     message: lines.join('\n'),

package/src/cli/commands/system-migrate.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../../db/client';
+import { handleSystemMigrate } from './system-migrate';
+
+describe('handleSystemMigrate', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'sysmig-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+  });
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('reports a fresh/current DB as up to date with the full schema', async () => {
+    const result = await handleSystemMigrate();
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.message).toContain('up to date');
+      expect(result.message).toContain('tables');
+    }
+  });
+
+  it('is idempotent — a second run is also clean', async () => {
+    (await handleSystemMigrate()).success;
+    closeDb();
+    const second = await handleSystemMigrate();
+    expect(second.success).toBe(true);
+  });
+});

package/src/cli/commands/system-migrate.ts

@@ -0,0 +1,65 @@
+/**
+ * `celilo system migrate` — apply pending DB migrations (ISS-0100).
+ *
+ * Drizzle's migrator is the single migration mechanism; createDbClient already
+ * auto-migrates on open, so this command is the explicit, operator-visible
+ * entrypoint the .deb postinst and celilo-mgmt deploy call. Idempotent: a
+ * current DB reports "up to date".
+ */
+
+import type { Database } from 'bun:sqlite';
+import { getDb } from '../../db/client';
+import { runMigrationsOn } from '../../db/migrate';
+import { findSchemaDrift } from '../../db/schema-introspection';
+import type { CommandResult } from '../types';
+
+function countApplied(sqlite: Database): number {
+  try {
+    const row = sqlite
+      .query<{ c: number }, []>('SELECT COUNT(*) AS c FROM `__drizzle_migrations`')
+      .get();
+    return row?.c ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+export async function handleSystemMigrate(): Promise<CommandResult> {
+  // getDb() auto-migrates on open; do it inside try so an existing DB that
+  // predates the drizzle-authoritative change fails with an actionable message
+  // instead of a raw migrator error.
+  let db: ReturnType<typeof getDb>;
+  try {
+    db = getDb();
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      error: `Migration failed: ${msg}\n\nIf this DB predates the drizzle-authoritative migration change, it needs a one-time remediation (stamp \`__drizzle_migrations\` to the latest migration + create any missing table) before the migrator can run cleanly — see ISS-0100.`,
+    };
+  }
+
+  const sqlite = db.$client;
+  const before = countApplied(sqlite);
+  try {
+    runMigrationsOn(db); // idempotent re-assert
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+  const applied = countApplied(sqlite) - before;
+
+  const drift = findSchemaDrift(sqlite);
+  if (drift.missingTables.length > 0 || drift.missingColumns.length > 0) {
+    const missing = [...drift.missingTables, ...drift.missingColumns].join(', ');
+    return {
+      success: false,
+      error: `Schema still behind after migrate — missing: ${missing}. This DB likely needs one-time remediation — see ISS-0100.`,
+    };
+  }
+
+  const lines = [
+    applied > 0 ? `Applied ${applied} migration(s).` : 'Schema already up to date.',
+    `Schema current: ${drift.tableCount} tables.`,
+  ];
+  return { success: true, message: lines.join('\n') };
+}

package/src/cli/completion.ts

@@ -460,6 +460,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'audit',
       'update',
       'doctor',
+      'migrate',
     ];
     return filterSuggestions(subcommands, args[1] || '');
   }

package/src/cli/index.ts

@@ -89,6 +89,7 @@ import { handleSystemAudit } from './commands/system-audit';
 import { handleSystemConfigGet, handleSystemConfigSet } from './commands/system-config';
 import { handleSystemDoctor } from './commands/system-doctor';
 import { handleSystemInit } from './commands/system-init';
+import { handleSystemMigrate } from './commands/system-migrate';
 import { handleSystemSecretGet } from './commands/system-secret-get';
 import { handleSystemSecretSet } from './commands/system-secret-set';
 import { handleSystemUpdate } from './commands/system-update';
@@ -286,7 +287,7 @@ Examples:
   celilo events tail --type deploy.completed.lunacycle   # filter by type
   celilo events emit deploy.completed.lunacycle '{}'     # operator-fired event
   celilo events tail --type 'config.required.*'          # see pending deploy questions
-  celilo events reply 42 '"lunacycle.net"'               # answer query #42 (config)
+  celilo events reply 42 '"example.net"'               # answer query #42 (config)
 `;
   return { success: true, message: helpText.trim() };
 }
@@ -1090,7 +1091,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
           '',
           'Examples:',
           '  celilo hook run namecheap validate_config --debug',
-          '  celilo hook run namecheap container_created vps_ip=138.68.140.177',
+          '  celilo hook run namecheap container_created vps_ip=192.0.2.30',
         ].join('\n'),
       };
     }
@@ -1783,6 +1784,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleSystemDoctor(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'migrate') {
+      return handleSystemMigrate();
+    }
+
     return {
       success: false,
       error: `Unknown system subcommand: ${parsed.subcommand}\n\nRun "celilo system --help" for usage`,