@celilo/cli 2.1.0 → 2.2.1

package/src/cli/index.ts

@@ -631,6 +631,7 @@ Subcommands:
       --preflight                        Run pre-flight validation only (no deployment)
       --verbose                          Keep all sub-events visible (no collapse-on-success)
       --stop-after-interview             Exit after config+secrets interview (no infra/hooks)
+      --keep                             Retain the generated project after a successful deploy (it is deleted by design)
 
   health [module-id]                    Run health checks (transitions to VERIFIED on success)
     Options:
@@ -951,9 +952,10 @@ Usage:
   Shows how celilo classifies every interface on a firewall: the zone it
   matched, the external edge, or ALIEN when nothing accounts for it.
 
-  Read-only. It reads the recorded interface table and the declared zone
-  subnets and classifies in memory — it never touches the box, so it is safe
-  to run against a firewall whose converge is currently refusing.
+  It reads the interface table LIVE from the box, the same way the next
+  converge will, so its answer is the answer the converge will act on. If the
+  box cannot be reached, it says so and classifies the interface snapshot
+  recorded at machine add instead, labelled as possibly stale.
 
   With no hostname, every machine celilo classifies as a router is shown.
 
@@ -2237,7 +2239,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       }
       const configArgs = parsed.args.slice(1);
       if (configSubcommand === 'set') {
-        return handleSystemConfigSet(configArgs);
+        return await handleSystemConfigSet(configArgs, parsed.flags);
       }
       if (configSubcommand === 'get') {
         return handleSystemConfigGet(configArgs);

package/src/cli/restore-command.test.ts

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 describe('celilo restore', () => {
@@ -32,7 +33,7 @@ describe('celilo restore', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_DATA_DIR = undefined;
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     process.env.CELILO_SUPPRESS_DEPRECATION = undefined;

package/src/cli/restore-migration-failure.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Tests for the restore migration contract (celilo#1269):
+ *
+ *   1. A restore whose post-swap migration step fails reports FAILURE, not a
+ *      warning over a success result. The failure names the recovery command
+ *      (`celilo system migrate`) and the check that says whether the schema is
+ *      complete (`celilo system doctor`).
+ *   2. A connection held across the migration step is observable at the step's
+ *      own boundary: migrateRestoredDb throws naming the lock instead of
+ *      quietly proceeding over a locked database.
+ *
+ * The round-trip here (encrypted envelope → on_restore hook → staged system
+ * files → swap → migrate) is the first module-artifact round-trip at unit
+ * level; the envelope mechanics mirror backup-envelope-roundtrip.test.ts.
+ */
+
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { create as tarCreate } from 'tar';
+import { getDbPath } from '../config/paths';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { modules } from '../db/schema';
+import { getOrCreateMasterKey } from '../secrets/master-key';
+import { encryptFileToFile } from '../services/backup-cipher';
+import { buildManifest } from '../services/backup-manifest';
+import { migrateRestoredDb } from '../services/restore-from-file';
+import { resetTestDbPath } from '../test-utils/db-path';
+import { runCli } from './index';
+
+const FIXTURES_DIR = join(import.meta.dir, '../hooks/test-fixtures');
+const STAGING_HOOK = join(FIXTURES_DIR, 'on-restore-staging-hook.ts');
+const MODULE_ID = 'restore-migration-test';
+
+/** The manifest the module row carries: one on_restore hook, the fixture. */
+const MODULE_MANIFEST = {
+  celilo_contract: '1.0',
+  id: MODULE_ID,
+  name: 'Restore Migration Test',
+  version: '0.0.1',
+  hooks: {
+    on_restore: {
+      script: STAGING_HOOK,
+      timeout: 60000,
+    },
+  },
+};
+
+/**
+ * Build an encrypted module artifact whose envelope carries `dbBytes` as the
+ * backed-up celilo.db. The fixture on_restore hook stages it into system/ so
+ * the restore swaps it over the live DB before the migration step runs.
+ */
+async function buildModuleArtifact(dir: string, dbBytes: string): Promise<string> {
+  const envelopeDir = join(dir, 'envelope-build');
+  mkdirSync(join(envelopeDir, 'data'), { recursive: true });
+  writeFileSync(
+    join(envelopeDir, 'manifest.json'),
+    JSON.stringify(buildManifest({ kind: 'module', moduleId: MODULE_ID, moduleVersion: '0.0.1' })),
+  );
+  writeFileSync(join(envelopeDir, 'data', 'celilo.db'), dbBytes);
+  const tarPath = join(dir, 'envelope.tar');
+  await tarCreate({ file: tarPath, cwd: envelopeDir }, ['.']);
+  const masterKey = await getOrCreateMasterKey();
+  const artifactPath = join(dir, 'module.backup');
+  await encryptFileToFile(tarPath, artifactPath, masterKey);
+  return artifactPath;
+}
+
+describe('restore migration failure reporting (celilo#1269)', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-restore-mig-fail-test-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    process.env.CELILO_DATA_DIR = dir;
+    process.env.CELILO_MASTER_KEY_PATH = join(dir, 'master.key');
+    await runMigrations(process.env.CELILO_DB_PATH);
+
+    // The artifact's module must already be imported (restore-from-file's
+    // contract with bootstrap.sh). Its sourcePath points at the workspace
+    // fixture dir: the canonical <dataDir>/modules/<id> does not exist here,
+    // so restore-from-file falls back to sourcePath for the hook.
+    const db = getDb();
+    db.insert(modules)
+      .values({
+        id: MODULE_ID,
+        name: 'Restore Migration Test',
+        version: '0.0.1',
+        sourcePath: FIXTURES_DIR,
+        manifestData: MODULE_MANIFEST,
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    closeDb();
+    resetTestDbPath();
+    process.env.CELILO_DATA_DIR = undefined;
+    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  test('a restore whose migration step fails reports failure and names the recovery path', async () => {
+    // The artifact's celilo.db is not a database at all. The swap lands it
+    // (staging bytes are deliberately tolerated so the file-copy path stays
+    // testable), and the migration step then fails on open — the same
+    // failure surface a locked or half-restored DB produces.
+    const artifact = await buildModuleArtifact(dir, 'this is not a SQLite database');
+    const result = await runCli(['node', 'celilo', 'restore', '--from', artifact, '--force']);
+
+    expect(result.success).toBe(false);
+    const err = result.success ? '' : (result.error ?? '');
+    expect(err).toContain('migrat');
+    expect(err).toContain('celilo system migrate');
+    expect(err).toContain('celilo system doctor');
+  });
+
+  test('the swap happened even when migrations failed (the error says so)', async () => {
+    const artifact = await buildModuleArtifact(dir, 'this is not a SQLite database');
+    const result = await runCli(['node', 'celilo', 'restore', '--from', artifact, '--force']);
+
+    expect(result.success).toBe(false);
+    const err = result.success ? '' : (result.error ?? '');
+    // The operator must learn the swap DID land — the failure is about the
+    // schema step, not a lost restore.
+    expect(err).toContain('restored');
+  });
+
+  // The timeout is 30s, not the 5s default: the holder pins the write lock
+  // for the full busy_timeout window before the migration step gives up, and
+  // the two windows are the same 5s.
+  test('a connection held across the migration step throws naming the lock', async () => {
+    // Current schema, ledger emptied so drizzle has work to do, then a write
+    // lock held across the step. Deleting one ledger row is not enough: the
+    // watermark is created_at-based and every migration shares one timestamp,
+    // so the whole ledger has to go. The re-run hits "already exists", the
+    // ledger-repair path then tries to write, and that write blocks on the
+    // holder until busy_timeout expires.
+    const livePath = getDbPath();
+    const ledger = new Database(livePath);
+    ledger.run('DELETE FROM __drizzle_migrations');
+    ledger.close();
+
+    const holder = new Database(livePath);
+    holder.run('BEGIN IMMEDIATE');
+    try {
+      await expect(migrateRestoredDb()).rejects.toThrow(/locked/i);
+    } finally {
+      holder.close();
+    }
+  }, 30000);
+});

package/src/config/paths.test.ts

@@ -141,7 +141,7 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'returns data dir + celilo.db on macOS in production',
       () => {
-        process.env.CELILO_DB_PATH = undefined;
+        delete process.env.CELILO_DB_PATH;
         process.env.CELILO_DATA_DIR = undefined;
         process.env.ENVIRONMENT = undefined;
 
@@ -156,7 +156,7 @@ describe('paths configuration', () => {
     );
 
     it('returns celilo-data/celilo.db in development mode', () => {
-      process.env.CELILO_DB_PATH = undefined;
+      delete process.env.CELILO_DB_PATH;
       process.env.CELILO_DATA_DIR = undefined;
       process.env.ENVIRONMENT = 'dev';
 
@@ -165,7 +165,7 @@ describe('paths configuration', () => {
     });
 
     it('respects CELILO_DATA_DIR override', () => {
-      process.env.CELILO_DB_PATH = undefined;
+      delete process.env.CELILO_DB_PATH;
       process.env.CELILO_DATA_DIR = '/custom/data';
       process.env.ENVIRONMENT = undefined;
 

package/src/db/client.ts

@@ -96,6 +96,10 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
       runMigrationsOn(db);
     } catch (error) {
       console.error('Failed to run migrations:', error);
+      // Release the file before rethrowing: the caller never receives this
+      // connection, so leaving it open holds the WAL lock on a db it cannot
+      // use (celilo#1269).
+      sqlite.close();
       throw error;
     }
   }
@@ -120,6 +124,7 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
       }
     } catch (error) {
       console.error('Failed to backfill module_systems:', error);
+      sqlite.close();
       throw error;
     }
   }

package/src/db/migrate.test.ts

@@ -1,147 +1,74 @@
 /**
- * The frozen-watermark recurrence gate (celilo#169).
+ * Tests for the standalone migration entrypoint's connection lifecycle.
  *
- * The state under test is one no correct deploy can produce, so it is seeded
- * by hand rather than reached: a database written by a celilo from the
- * imperative hand-list era, where schema changes were applied directly and
- * `__drizzle_migrations` never recorded them. Its ledger therefore remembers
- * an old migration while the tables and columns of every later one are already
- * present.
+ * runMigrations opens its own connection via createDbClient — which is NOT
+ * the process-wide singleton. Its teardown used to call closeDb(), which
+ * closes the SINGLETON: a different connection. Two consequences, both bad:
+ * the connection this call created was never closed, and a caller that had
+ * the singleton open had it closed out from under it.
  *
- * That is the carve-out CLAUDE.md draws around seeding state: deploying
- * anything cannot reproduce this row, because current celilo has recorded
- * every migration it applied since ISS-0100 made drizzle authoritative. A
- * suite that starts from an empty database can only ever prove the forward
- * invariant, and says nothing about the installed base.
- *
- * What made it a hazard: drizzle's migrator is watermark-only. It re-runs
- * every migration newer than the newest ledger row, so the first `ALTER TABLE
- * ... ADD` dies on `duplicate column name`, the transaction rolls back, and
- * the throw happens inside `createDbClient` — so EVERY celilo command on that
- * box fails at database open, not just a migrate. celilo-mgr was remediated by
- * hand once. This gate is what stops the next one needing a runbook.
+ * One bun:sqlite caveat this suite deliberately does NOT paper over: closing
+ * a drizzle-wrapped connection releases the file only once drizzle's prepared
+ * statements are collected, so a just-closed connection can still hold locks
+ * until the next GC. The restore path (the only in-tree caller) does not need
+ * the file again after migrating, so the caveat is harmless there — the thing
+ * that must hold is that the CLOSE TARGETS THE RIGHT CONNECTION.
  */
 
-import { afterEach, describe, expect, test } from 'bun:test';
-import { rmSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+import { describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { type DbClient, createDbClient } from './client';
-import { runMigrationsOn } from './migrate';
-import { findSchemaDrift } from './schema-introspection';
-
-describe('runMigrationsOn — a database from the hand-list era', () => {
-  const paths: string[] = [];
-
-  const freshDb = (): { db: DbClient; path: string } => {
-    const path = join(tmpdir(), `celilo-migrate-test-${Bun.nanoseconds()}.db`);
-    paths.push(path);
-    return { db: createDbClient({ path }), path };
-  };
-
-  afterEach(() => {
-    for (const path of paths.splice(0)) {
-      for (const suffix of ['', '-wal', '-shm']) {
-        rmSync(`${path}${suffix}`, { force: true });
-      }
+import { resetTestDbPath } from '../test-utils/db-path';
+import { closeDb, getDb } from './client';
+import { runMigrations } from './migrate';
+import { systemConfig } from './schema';
+
+describe('runMigrations connection lifecycle', () => {
+  it("does not close the caller's singleton connection", async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-migrate-close-test-'));
+    try {
+      const livePath = join(dir, 'celilo.db');
+      process.env.CELILO_DB_PATH = livePath;
+      await runMigrations(livePath);
+
+      // A caller with the singleton open (e.g. the restore CLI between swap
+      // and resync) runs migrations on a path and keeps using ITS OWN
+      // connection. The old teardown called closeDb(), which closes the
+      // singleton — a different connection — so the caller's next query died
+      // with a closed-connection error.
+      const db = getDb();
+      db.insert(systemConfig).values({ key: 'probe', value: 'before' }).run();
+
+      const otherPath = join(dir, 'other.db');
+      await runMigrations(otherPath);
+
+      // The singleton must have survived the migration on the other path.
+      expect(() => db.select().from(systemConfig).limit(1).all()).not.toThrow();
+      closeDb();
+    } finally {
+      closeDb();
+      resetTestDbPath();
+      rmSync(dir, { recursive: true, force: true });
     }
   });
 
-  /**
-   * Freeze the ledger to its oldest entry, leaving the schema fully applied.
-   * This is the hand-list-era shape: the objects exist, the ledger has
-   * forgotten who made them.
-   */
-  const freezeWatermark = (db: DbClient): void => {
-    db.$client.run(
-      'DELETE FROM `__drizzle_migrations` WHERE created_at > (SELECT MIN(created_at) FROM `__drizzle_migrations`)',
-    );
-  };
-
-  const appliedCount = (db: DbClient): number =>
-    db.$client.query<{ c: number }, []>('SELECT COUNT(*) AS c FROM `__drizzle_migrations`').get()
-      ?.c ?? 0;
-
-  test('converges instead of dying on the first already-applied statement', () => {
-    const { db } = freshDb();
-    const migrationCount = appliedCount(db);
-    freezeWatermark(db);
-    expect(appliedCount(db)).toBe(1);
-
-    // Red before the ledger repair: drizzle re-runs 0001 and throws
-    // "duplicate column name: role", leaving the ledger frozen.
-    expect(() => runMigrationsOn(db)).not.toThrow();
-
-    expect(appliedCount(db)).toBe(migrationCount);
-  });
-
-  test('leaves the schema whole, so the drift detector goes green', () => {
-    const { db } = freshDb();
-    freezeWatermark(db);
-
-    runMigrationsOn(db);
-
-    const drift = findSchemaDrift(db.$client);
-    expect(drift.missingTables).toEqual([]);
-    expect(drift.missingColumns).toEqual([]);
-  });
-
-  test('is idempotent — a second pass applies nothing and still converges', () => {
-    const { db } = freshDb();
-    freezeWatermark(db);
-    runMigrationsOn(db);
-    const afterBaseline = appliedCount(db);
-
-    runMigrationsOn(db);
-
-    expect(appliedCount(db)).toBe(afterBaseline);
-  });
-
-  /**
-   * The repair must not become a blanket "assume it already ran". It fires only
-   * where the answer is unambiguous — the declared schema is entirely present,
-   * so every migration plainly did run and the ledger is what is wrong. A
-   * PARTIALLY applied schema is the genuinely hard case, and the one celilo-mgr
-   * was actually in: it carried 0011's column and not 0010's table. Stamping
-   * there would record migrations that never ran and bury the missing schema
-   * for good, so it keeps failing and a human decides.
-   */
-  test('refuses to stamp when the schema is only partly there', () => {
-    const { db } = freshDb();
-    freezeWatermark(db);
-    db.$client.run('DROP TABLE `dns_registrations`');
-
-    expect(() => runMigrationsOn(db)).toThrow();
-    // The ledger is left exactly as found, so the drift is still diagnosable.
-    expect(appliedCount(db)).toBe(1);
-  });
-
-  /**
-   * The path that actually matters. Every celilo command opens the database
-   * through createDbClient, which migrates on open, so a frozen watermark
-   * failed there rather than anywhere an operator could aim a fix at — and
-   * `celilo system migrate`, the command whose whole job is repairing this,
-   * reached its own repair through the same open and died first.
-   */
-  test('repairs on database open, not just when migrate is called by hand', () => {
-    const { db, path } = freshDb();
-    const migrationCount = appliedCount(db);
-    freezeWatermark(db);
-    db.$client.close();
-
-    const reopened = createDbClient({ path });
-
-    expect(appliedCount(reopened)).toBe(migrationCount);
-    expect(findSchemaDrift(reopened.$client).missingTables).toEqual([]);
-  });
-
-  test('a healthy database is untouched by the fallback', () => {
-    const { db } = freshDb();
-    const before = appliedCount(db);
-
-    runMigrationsOn(db);
-
-    expect(appliedCount(db)).toBe(before);
-    expect(findSchemaDrift(db.$client).missingTables).toEqual([]);
+  it('closes its own connection: the db reopens cleanly afterwards', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-migrate-own-conn-test-'));
+    try {
+      const dbPath = join(dir, 'celilo.db');
+      await runMigrations(dbPath);
+
+      // A fresh connection must be able to take the database over. The old
+      // closeDb() closed nothing here (the singleton was null), so this
+      // statement ran against a connection held open by nobody's bookkeeping
+      // — released only by GC, at a time of GC's choosing.
+      const probe = new Database(dbPath, { readonly: true });
+      expect(probe.query<{ journal_mode: string }, []>('PRAGMA journal_mode').get()).toBeDefined();
+      probe.close();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
   });
 });

package/src/db/migrate.ts

@@ -1,7 +1,7 @@
 import type { Database } from 'bun:sqlite';
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
 import { readMigrationFiles } from 'drizzle-orm/migrator';
-import { type DbClient, closeDb, createDbClient, findMigrationsFolder } from './client';
+import { type DbClient, createDbClient, findMigrationsFolder } from './client';
 import { findSchemaDrift } from './schema-introspection';
 
 /**
@@ -80,21 +80,26 @@ export function runMigrationsOn(db: DbClient): void {
 }
 
 /**
- * Run database migrations (standalone entrypoint — `bun run src/db/migrate.ts`).
- * createDbClient already migrates on open; this re-asserts for explicit use.
+ * Open a database at `dbPath` with migrations applied, then close it.
+ * Standalone entrypoint (`bun run src/db/migrate.ts`); tests also use it to
+ * prepare a fresh scratch database.
+ *
+ * createDbClient migrates synchronously on open (its own runMigrationsOn
+ * call), so this function is open + close. It deliberately does NOT call
+ * runMigrationsOn again: a second pass is always a ledger no-op when the
+ * first succeeded, and keeping it invited a double-migrate everywhere this
+ * entrypoint is used (celilo#1315).
  */
 export async function runMigrations(dbPath?: string) {
   console.log('Running database migrations...');
   const db = createDbClient(dbPath ? { path: dbPath } : undefined);
-  try {
-    runMigrationsOn(db);
-    console.log('Migrations completed successfully');
-  } catch (error) {
-    console.error('Migration failed:', error);
-    throw error;
-  } finally {
-    closeDb();
-  }
+  console.log('Migrations completed successfully');
+  // Close the connection THIS call created. It is not the singleton —
+  // createDbClient does not register one — so an old closeDb() here closed
+  // whatever else was open (usually nothing) and leaked this connection,
+  // which then held the file in WAL and blocked every later journal-mode
+  // switch on it (celilo#1269).
+  db.$client.close();
 }
 
 // Run migrations if executed directly

package/src/db/schema.ts

@@ -126,6 +126,16 @@ export const moduleConfigs = sqliteTable(
     key: text('key').notNull(),
     value: text('value').notNull(),
     valueJson: text('value_json'), // JSON for complex types (arrays, objects)
+    /**
+     * Who owns the row (hook-owned-state design D7 — one column shared with
+     * `derived-value-recomputation`). 'hook' means the owning module's own
+     * hook wrote it via `context.config.set`, and no operator path may touch
+     * it. NULL is every row written before the column existed — operator
+     * intent, legacy derived seeds, and framework keys alike — and stays the
+     * value for operator writes until derived-value-recomputation lands its
+     * own classification.
+     */
+    source: text('source'),
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
     updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },