@celilo/cli 1.8.0 → 1.9.0

package/src/services/module-instances.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type DbClient, createDbClient } from '../db/client';
+import { deriveInstanceModuleId, ownedSystemModuleIds } from './module-instances';
+
+describe('deriveInstanceModuleId', () => {
+  test('is deterministic, so an instantiate is safe to retry', () => {
+    const a = deriveInstanceModuleId('byoi', 'lab', 'sub-abc123');
+    const b = deriveInstanceModuleId('byoi', 'lab', 'sub-abc123');
+    expect(a).toBe(b);
+  });
+
+  test('produces a valid kebab-case module id from an opaque key', () => {
+    // celilo never interprets the key, so it may be anything at all.
+    const id = deriveInstanceModuleId('byoi', 'lab', 'Sally Smith <sally@example.com> 🎉');
+    expect(id).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/);
+    expect(id.startsWith('byoi-lab-')).toBe(true);
+  });
+
+  test('two parents using the same key get different ids', () => {
+    expect(deriveInstanceModuleId('byoi', 'lab', 'shared-key')).not.toBe(
+      deriveInstanceModuleId('forgejo', 'lab', 'shared-key'),
+    );
+  });
+
+  test('one parent reusing a key across two submodules gets different ids', () => {
+    expect(deriveInstanceModuleId('forgejo', 'runner', 'proj-1')).not.toBe(
+      deriveInstanceModuleId('forgejo', 'builder', 'proj-1'),
+    );
+  });
+
+  // Without a separator in the hash input, ("a", "b-c") and ("a-b", "c") hash
+  // the same string. The kind of ambiguity that never shows up until it does.
+  test('a hyphen moving between parent and submodule changes the id', () => {
+    expect(deriveInstanceModuleId('a', 'b-c', 'k')).not.toBe(
+      deriveInstanceModuleId('a-b', 'c', 'k'),
+    );
+  });
+
+  test('a different key changes the id', () => {
+    expect(deriveInstanceModuleId('byoi', 'lab', 'one')).not.toBe(
+      deriveInstanceModuleId('byoi', 'lab', 'two'),
+    );
+  });
+});
+
+describe('module_instances storage', () => {
+  let root: string;
+  let db: DbClient;
+
+  const addModule = (id: string) =>
+    db.$client.run(
+      "INSERT INTO modules (id,name,version,manifest_data,source_path) VALUES (?,?,'1.0.0','{}','/tmp/'||?)",
+      [id, id, id],
+    );
+
+  const addInstance = (parent: string, submodule: string, key: string) => {
+    const id = deriveInstanceModuleId(parent, submodule, key);
+    addModule(id);
+    db.$client.run(
+      'INSERT INTO module_instances (module_id,parent_id,submodule,instance_key) VALUES (?,?,?,?)',
+      [id, parent, submodule, key],
+    );
+    return id;
+  };
+
+  const instanceCount = () =>
+    (db.$client.query('SELECT count(*) n FROM module_instances').get() as { n: number }).n;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'celilo-instances-'));
+    db = createDbClient({ path: join(root, 'celilo.db') });
+    for (const id of ['byoi', 'forgejo']) addModule(id);
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('identity is the triple, not the key alone', () => {
+    const columns = db.$client
+      .query("PRAGMA index_info('module_instances_identity_idx')")
+      .all() as Array<{ name: string }>;
+    expect(columns.map((c) => c.name)).toEqual(['parent_id', 'submodule', 'instance_key']);
+  });
+
+  test('two parents may use the same instance key', () => {
+    addInstance('byoi', 'lab', 'shared');
+    expect(() => addInstance('forgejo', 'lab', 'shared')).not.toThrow();
+    expect(instanceCount()).toBe(2);
+  });
+
+  test('one parent cannot reuse a key for the same submodule', () => {
+    addInstance('byoi', 'lab', 'dup');
+    expect(() =>
+      db.$client.run(
+        'INSERT INTO module_instances (module_id,parent_id,submodule,instance_key) VALUES (?,?,?,?)',
+        ['byoi-lab-other', 'byoi', 'lab', 'dup'],
+      ),
+    ).toThrow(/UNIQUE constraint failed/);
+  });
+
+  // A row must never outlive the parent it names.
+  test('removing a parent removes its instance rows and leaves other parents alone', () => {
+    addInstance('byoi', 'lab', 'a');
+    addInstance('forgejo', 'runner', 'b');
+    expect(instanceCount()).toBe(2);
+
+    db.$client.run("DELETE FROM modules WHERE id='byoi'");
+
+    expect(
+      db.$client.query('SELECT parent_id FROM module_instances').all() as Array<{
+        parent_id: string;
+      }>,
+    ).toEqual([{ parent_id: 'forgejo' }]);
+  });
+
+  test('an instance defaults to pending with no failure recorded', () => {
+    addInstance('byoi', 'lab', 'fresh');
+    const row = db.$client
+      .query('SELECT state, failure_reason, retryable FROM module_instances')
+      .get() as { state: string; failure_reason: string | null; retryable: number | null };
+    expect(row.state).toBe('pending');
+    expect(row.failure_reason).toBeNull();
+    expect(row.retryable).toBeNull();
+  });
+});
+
+describe('ownedSystemModuleIds', () => {
+  let root: string;
+  let db: DbClient;
+
+  const addModule = (id: string) =>
+    db.$client.run(
+      "INSERT INTO modules (id,name,version,manifest_data,source_path) VALUES (?,?,'1.0.0','{}','/tmp/'||?)",
+      [id, id, id],
+    );
+
+  const addInstance = (parent: string, submodule: string, key: string) => {
+    const id = deriveInstanceModuleId(parent, submodule, key);
+    addModule(id);
+    db.$client.run(
+      'INSERT INTO module_instances (module_id,parent_id,submodule,instance_key) VALUES (?,?,?,?)',
+      [id, parent, submodule, key],
+    );
+    return id;
+  };
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'celilo-owned-'));
+    db = createDbClient({ path: join(root, 'celilo.db') });
+    for (const id of ['forgejo', 'caddy']) addModule(id);
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  // The state of every fleet until submodules ship, and the reason this is
+  // correct on its own rather than merely inert: an empty table gives every
+  // module itself, so a caller reaches only what it provisioned.
+  test('with no instances in existence, a module owns exactly itself', () => {
+    expect(ownedSystemModuleIds('caddy', db)).toEqual(['caddy']);
+    expect(ownedSystemModuleIds('forgejo', db)).toEqual(['forgejo']);
+  });
+
+  test('a parent gets itself and every instance it owns', () => {
+    const a = addInstance('forgejo', 'runner', 'proj-1');
+    const b = addInstance('forgejo', 'runner', 'proj-2');
+
+    const owned = ownedSystemModuleIds('forgejo', db);
+
+    expect(owned).toContain('forgejo');
+    expect(owned).toContain(a);
+    expect(owned).toContain(b);
+    expect(owned).toHaveLength(3);
+  });
+
+  test("a parent does not reach another parent's instances", () => {
+    addInstance('forgejo', 'runner', 'proj-1');
+    expect(ownedSystemModuleIds('caddy', db)).toEqual(['caddy']);
+  });
+
+  // Ownership is one level deep by construction, so the answer terminates
+  // without anyone reasoning about depth.
+  test('an instance owns nobody, so the answer is one level and terminates', () => {
+    const instance = addInstance('forgejo', 'runner', 'proj-1');
+    expect(ownedSystemModuleIds(instance, db)).toEqual([instance]);
+  });
+
+  test('a module that does not exist owns only the name it was asked about', () => {
+    expect(ownedSystemModuleIds('never-installed', db)).toEqual(['never-installed']);
+  });
+});

package/src/services/module-instances.ts

@@ -0,0 +1,96 @@
+/**
+ * Instance identity (openspec/changes/submodules, D2 and D4).
+ *
+ * A parent module addresses the instances it owns by an opaque key it chose.
+ * celilo addresses them by a `modules.id`, because an instance IS a module row,
+ * and that is what lets every reader keyed on `moduleId` keep working. This
+ * file is the single place those two names meet, so the mapping cannot drift.
+ *
+ * The rest of the submodules mechanism (the symlink farm an instance's install
+ * is, the deploy-worker capability, the lifecycle) is not here. This is the
+ * identity and the ownership question, landed ahead of it because
+ * `hook-process-boundary` stage 3 needs `ownedSystemModuleIds` and nothing else
+ * from that change.
+ */
+
+import { createHash } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { moduleInstances } from '../db/schema';
+
+/**
+ * Bits of hash in a derived instance id, as hex characters.
+ *
+ * 12 hex characters is 48 bits, so a birthday collision needs on the order of
+ * 16 million instances of ONE submodule under ONE parent. A fleet runs tens.
+ * Short enough to read in `celilo module list`, long enough that nobody has to
+ * think about it.
+ */
+const INSTANCE_ID_HASH_CHARS = 12;
+
+/**
+ * The `modules.id` an instance runs as.
+ *
+ * Derived rather than supplied, for two reasons. The parent's key is opaque and
+ * may be anything (D2 forbids celilo interpreting it), while `modules.id` must
+ * be kebab-case. And identity is the TRIPLE of parent, submodule and key, so
+ * the first two have to be inside the hash, or two parents using the same key
+ * would collide.
+ *
+ * Deterministic: the same triple always yields the same id, which is what makes
+ * an instantiate safe to retry.
+ */
+export function deriveInstanceModuleId(
+  parentId: string,
+  submodule: string,
+  instanceKey: string,
+): string {
+  // The separator matters. Hashing the concatenation alone would let
+  // ("a", "b-c") and ("a-b", "c") collide, which is the kind of ambiguity that
+  // never shows up until it does.
+  const digest = createHash('sha256')
+    .update(`${parentId} ${submodule} ${instanceKey}`)
+    .digest('hex')
+    .slice(0, INSTANCE_ID_HASH_CHARS);
+
+  return `${parentId}-${submodule}-${digest}`;
+}
+
+/**
+ * Every module id whose systems `moduleId` transitively owns: itself, plus each
+ * of its instances.
+ *
+ * This is the allow-list behind D12 of `openspec/changes/hook-process-boundary`
+ * ("a module may reach the systems it provisioned, or that its submodules
+ * provisioned"). Feed it to `getModuleSystems` per id, or use it directly as an
+ * `IN (...)` set.
+ *
+ * NOT RECURSIVE, and that is a property of the model rather than a shortcut.
+ * Nesting is refused when a parent is imported: a submodule may not declare
+ * submodules of its own, so ownership is exactly one level deep by
+ * construction. A parent owns instances, and an instance owns nothing. So this
+ * is one indexed lookup on `module_instances_parent_idx` rather than a walk,
+ * which is what makes it cheap enough to run at hook-invocation time.
+ *
+ * A recursive walk that happens to terminate and one that cannot recurse are
+ * different things, and only the second is safe to call per invocation without
+ * reasoning about depth.
+ *
+ * An instance asking gets only itself, which is correct: an instance provisions
+ * its own systems and owns nobody else's.
+ *
+ * Correct with no instances in existence, which is the state of every fleet
+ * until submodules ship: the table is empty, so every module gets `[itself]`,
+ * and a caller reaches only the systems it provisioned. That is the answer the
+ * allow-list wants today, and it picks up submodule behaviour later with no
+ * second edit.
+ */
+export function ownedSystemModuleIds(moduleId: string, db: DbClient): string[] {
+  const instances = db
+    .select({ moduleId: moduleInstances.moduleId })
+    .from(moduleInstances)
+    .where(eq(moduleInstances.parentId, moduleId))
+    .all();
+
+  return [moduleId, ...instances.map((row) => row.moduleId)];
+}

package/src/services/module-journal.test.ts

@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import { type RunResult, type Runner, createMockRunner } from '@celilo/capabilities';
 import type { DbClient } from '../db/client';
 import { moduleSystems, modules } from '../db/schema';
-import { setupTestDatabase } from '../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../test-utils/database';
 import { planJournalRead, readModuleJournal } from './module-journal';
 
 /**
@@ -64,7 +64,7 @@ let db: DbClient;
 
 beforeEach(async () => {
   dir = mkdtempSync(join(tmpdir(), 'module-journal-'));
-  db = await setupTestDatabase(join(dir, 'celilo.db'));
+  db = await setupTestDatabaseAt(join(dir, 'celilo.db'));
 });
 
 afterEach(() => {

package/src/services/module-subscriptions.test.ts

@@ -9,7 +9,7 @@ import { closeDb, getDb } from '../db/client';
 import { ModuleManifestSchema } from '../manifest/schema';
 import { ModuleSubscriptionSchema } from '../manifest/schema';
 import type { ModuleManifest } from '../manifest/schema';
-import { setupTestDatabase as migrateDbFile } from '../test-utils/setup-test-db';
+import { setupTestDatabaseAt as migrateDbFile } from '../test-utils/database';
 import {
   registerModuleSubscriptions,
   resolveSubscription,

package/src/services/port-forwards.test.ts

@@ -6,7 +6,7 @@ import type { PortForwardStore } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { portForwards } from '../db/schema';
-import { setupTestDatabase } from '../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../test-utils/database';
 import { deleteClaimedRows } from './capability-table-rows';
 import { buildPortForwardStore } from './port-forwards';
 
@@ -22,7 +22,7 @@ describe('port-forward store', () => {
     dir = mkdtempSync(join(tmpdir(), 'pf-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     store = buildPortForwardStore(db, 'caddy');
   });
   afterEach(() => {

package/src/services/trusted-sources.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../db/client';
 import { systemConfig } from '../db/schema';
 import { loadTrustedSubnets } from '../hooks/capability-loader';
-import { setupTestDatabase } from '../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../test-utils/database';
 import {
   buildTrustedSourceStore,
   composeTrustedSubnets,
@@ -26,7 +26,7 @@ describe('trusted-source store', () => {
     dir = mkdtempSync(join(tmpdir(), 'ts-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
   });
   afterEach(() => {
     db.$client.close();
@@ -138,7 +138,7 @@ describe('the render input excludes registrations; the reporting view includes t
     dir = mkdtempSync(join(tmpdir(), 'ts-render-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     db.insert(systemConfig).values({ key: 'network.internal.subnet', value: CONTROL_PLANE }).run();
     buildTrustedSourceStore(db, 'wireguard').replace(FW, {
       subnets: [VPN],

package/src/templates/ingress-ip.test.ts

@@ -58,8 +58,30 @@ const removeModule = async (moduleId: string): Promise<void> => {
   db.$client.prepare('DELETE FROM module_configs WHERE module_id = ?').run(moduleId);
 };
 
+/**
+ * Every module these tests name, as a real row. `module_configs` carries a
+ * foreign key onto `modules`, so without the parent the config write
+ * `ensureIngressIps` performs is rejected and the function reports failure —
+ * which is what happens in production too, and never happened here while the
+ * test helper ran with foreign keys off (celilo#1074).
+ *
+ * Worth knowing WHICH tests that would have broken. Only some: "two modules get
+ * two different addresses" fails loudly, but "REUSES the same address on a
+ * second generate" compares one unwritten value to another and passes. So a
+ * repair that chased the red would have left this file's central guard asserting
+ * `undefined === undefined`.
+ */
+const NAMED_MODULES = ['technitium', 'knot-unbound-internal', 'caddy', 'caddy-internal'];
+
 beforeEach(async () => {
   db = await setupTestDatabase();
+  for (const id of NAMED_MODULES) {
+    db.$client
+      .prepare(
+        'INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES (?, ?, ?, ?, ?)',
+      )
+      .run(id, id, '1.0.0', `/test/${id}`, '{}');
+  }
   db.$client
     .prepare('INSERT OR REPLACE INTO system_config (key, value) VALUES (?, ?)')
     .run('network.internal.subnet', '10.226.1.0/24');
@@ -78,6 +100,13 @@ describe('ensureIngressIps', () => {
     // every time the module is regenerated, and nothing reports a problem.
     await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
+    // Assert the read SUCCEEDED before comparing two of them. Without this the
+    // test passes whenever BOTH reads fail the same way, which is exactly what
+    // happened when foreign keys were switched on and the config write this
+    // depends on started being rejected (celilo#1074): `undefined` equals
+    // `undefined`, and the file's central guard stayed green while proving
+    // nothing.
+    expect(first).toBeDefined();
 
     await ensureIngressIps('technitium', wantsIngress, db);
     const second = storedIp('technitium');
@@ -88,6 +117,7 @@ describe('ensureIngressIps', () => {
   test('stays stable across many generates, not just two', async () => {
     await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
+    expect(first).toBeDefined();
 
     for (let i = 0; i < 5; i++) {
       await ensureIngressIps('technitium', wantsIngress, db);
@@ -179,6 +209,7 @@ describe('releasing ingress IPs on module removal', () => {
     // one address per install/remove cycle until it runs out.
     await ensureIngressIps('technitium', wantsIngress, db);
     const first = storedIp('technitium');
+    expect(first).toBeDefined();
 
     await removeModule('technitium');
     await ensureIngressIps('technitium', wantsIngress, db);

package/src/test-utils/database.ts

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { drizzle } from 'drizzle-orm/bun-sqlite';
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
-import { type DbClient, findMigrationsFolder } from '../db/client';
+import { type DbClient, createDbClient, findMigrationsFolder } from '../db/client';
 import * as schema from '../db/schema';
 
 /**
@@ -31,6 +31,10 @@ import * as schema from '../db/schema';
  */
 export async function setupTestDatabase(): Promise<DbClient> {
   const sqlite = new Database(':memory:');
+  // Matches `createDbClient` (db/client.ts). SQLite defaults this OFF per
+  // connection, so without it every `onDelete: 'cascade'` in the schema is
+  // enforced in production and inert in the suite (celilo#1074).
+  sqlite.run('PRAGMA foreign_keys = ON');
   const db = drizzle(sqlite, { schema });
   const migrationsFolder = findMigrationsFolder();
   await migrate(db, { migrationsFolder });
@@ -60,6 +64,8 @@ export async function setupTestDatabaseFile(): Promise<{
   const tempDir = await mkdtemp(join(tmpdir(), 'celilo-test-'));
   const dbPath = join(tempDir, 'test.db');
   const sqlite = new Database(dbPath);
+  // See setupTestDatabase — celilo#1074.
+  sqlite.run('PRAGMA foreign_keys = ON');
   const db = drizzle(sqlite, { schema });
   const migrationsFolder = findMigrationsFolder();
   await migrate(db, { migrationsFolder });
@@ -72,6 +78,30 @@ export async function setupTestDatabaseFile(): Promise<{
   return { db, path: dbPath, cleanup };
 }
 
+/**
+ * Create a test database at a path the CALLER chooses.
+ *
+ * The other two helpers pick the location — memory, or a temp directory they
+ * own. This one exists for tests that must hand the same path to something
+ * else, typically a spawned CLI through `CELILO_DB_PATH`.
+ *
+ * It was a second module, `test-utils/setup-test-db.ts`, exporting a function
+ * ALSO called `setupTestDatabase` and another also called
+ * `cleanupTestDatabase`, with different arities and — until celilo#1074 —
+ * opposite foreign-key semantics. Which contract a test was under depended
+ * entirely on which file its import line named, and nothing at the call site
+ * showed it. One caller had already aliased the import to `migrateDbFile` to
+ * make it readable. The two colliding names are gone rather than renamed: there
+ * is no longer a wrong one to pick.
+ *
+ * @param testDbPath - Where to create the database file
+ */
+export async function setupTestDatabaseAt(testDbPath: string): Promise<DbClient> {
+  const db = createDbClient({ path: testDbPath });
+  await migrate(db, { migrationsFolder: findMigrationsFolder() });
+  return db;
+}
+
 /**
  * Clean up test database
  *

package/src/test-utils/setup-test-db.ts

@@ -1,80 +0,0 @@
-import { existsSync } from 'node:fs';
-import { unlink } from 'node:fs/promises';
-import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
-import { type DbClient, createDbClient, findMigrationsFolder } from '../db/client';
-
-// `findMigrationsFolder` is imported from db/client rather than redefined here.
-// This file used to carry its own copy, and the copy had drifted: it listed
-// only CWD-RELATIVE candidates (`./drizzle`, `process.cwd()/drizzle`, …) and was
-// missing the `join(currentDir, '../../drizzle')` fallback that resolves
-// relative to the source file.
-//
-// The effect was invisible from `apps/celilo` and total from the repo root —
-// which is where CLAUDE.md says to run the gate. Every suite using
-// setupTestDatabase threw here, left `db` unassigned, and then failed again in
-// its own afterEach on `db.$client`, so one missing path candidate presented as
-// hundreds of unrelated-looking assertion failures (celilo: 668 across the
-// repo, 341 in apps/celilo/src alone).
-
-/**
- * Setup test database with real migrations
- *
- * This helper ensures tests use the same schema as production by running
- * actual migrations instead of manual CREATE TABLE statements.
- *
- * Benefits:
- * - Single source of truth for schema
- * - Tests automatically use latest schema
- * - Validates migration correctness
- *
- * @param testDbPath - Path to test database file
- * @returns Database client instance
- */
-export async function setupTestDatabase(testDbPath: string) {
-  // Create database client
-  const db = createDbClient({ path: testDbPath });
-
-  // Find and run migrations
-  const migrationsFolder = findMigrationsFolder();
-  await migrate(db, { migrationsFolder });
-
-  return db;
-}
-
-/**
- * Cleanup test database
- *
- * @param db - Database client to close
- * @param testDbPath - Path to test database file to delete
- */
-export async function cleanupTestDatabase(db: DbClient, testDbPath: string) {
-  // Close database connection
-  db.$client.close();
-
-  // Delete test database file
-  if (existsSync(testDbPath)) {
-    await unlink(testDbPath);
-  }
-
-  // Also delete WAL and SHM files if they exist
-  const walPath = `${testDbPath}-wal`;
-  const shmPath = `${testDbPath}-shm`;
-
-  if (existsSync(walPath)) {
-    await unlink(walPath);
-  }
-
-  if (existsSync(shmPath)) {
-    await unlink(shmPath);
-  }
-}
-
-/**
- * Generate unique test database path
- *
- * @param prefix - Optional prefix for the database file (defaults to 'test-celilo')
- * @returns Unique database file path
- */
-export function generateTestDbPath(prefix = 'test-celilo'): string {
-  return `./${prefix}-${Date.now()}-${Math.random()}.db`;
-}