@celilo/cli 1.12.0 → 1.14.0

package/src/services/instance-ops.test.ts

@@ -0,0 +1,302 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createModuleDeployWorker, isInstanceRequestRefusedError } from '@celilo/capabilities';
+import { type DbClient, createDbClient } from '../db/client';
+import type { ModuleManifest } from '../manifest/schema';
+import {
+  createInstanceOps,
+  refuseUndeclaredNetworks,
+  validateInstanceConfig,
+} from './instance-ops';
+import { deriveInstanceModuleId } from './module-instances';
+
+const manifest = (over: Record<string, unknown> = {}): ModuleManifest =>
+  ({
+    celilo_contract: '1.0',
+    id: 'lab',
+    name: 'BYOI Lab',
+    version: '1.0.0',
+    requires: { capabilities: [] },
+    provides: { capabilities: [] },
+    variables: { owns: [], imports: [] },
+    ...over,
+  }) as unknown as ModuleManifest;
+
+const ownedVar = (over: Record<string, unknown>) => ({
+  name: 'ssh_key',
+  type: 'string',
+  required: true,
+  source: 'user',
+  description: '',
+  ...over,
+});
+
+describe('validateInstanceConfig', () => {
+  test('accepts a config supplying every required user variable', () => {
+    const m = manifest({ variables: { owns: [ownedVar({})], imports: [] } });
+    expect(validateInstanceConfig(m, { ssh_key: 'ssh-ed25519 AAAA' })).toEqual([]);
+  });
+
+  test('reports a required variable that was not supplied', () => {
+    const m = manifest({ variables: { owns: [ownedVar({})], imports: [] } });
+    const problems = validateInstanceConfig(m, {});
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain("'ssh_key' is required");
+  });
+
+  test('a required variable with a default need not be supplied', () => {
+    const m = manifest({
+      variables: { owns: [ownedVar({ default: 'ssh-ed25519 DEFAULT' })], imports: [] },
+    });
+    expect(validateInstanceConfig(m, {})).toEqual([]);
+  });
+
+  test('refuses a key the submodule does not declare, and lists what it does', () => {
+    const m = manifest({ variables: { owns: [ownedVar({})], imports: [] } });
+    const problems = validateInstanceConfig(m, { ssh_key: 'k', nonsense: 1 });
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain("'nonsense' is not declared");
+    expect(problems[0]).toContain('ssh_key');
+  });
+
+  // A derived value silently overwritten at generate time looks like celilo
+  // ignoring the request, so it is refused rather than accepted and discarded.
+  test('refuses a declared variable celilo derives rather than the caller supplying', () => {
+    const m = manifest({
+      variables: {
+        owns: [ownedVar({}), ownedVar({ name: 'container_ip', source: 'infrastructure' })],
+        imports: [],
+      },
+    });
+    const problems = validateInstanceConfig(m, { ssh_key: 'k', container_ip: '10.0.0.5' });
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('celilo derives it');
+  });
+
+  // Four failed instantiations to learn four missing keys is the experience
+  // this avoids.
+  test('reports every problem at once', () => {
+    const m = manifest({
+      variables: { owns: [ownedVar({}), ownedVar({ name: 'owner_sub' })], imports: [] },
+    });
+    expect(validateInstanceConfig(m, { junk: 1 })).toHaveLength(3);
+  });
+});
+
+describe('refuseUndeclaredNetworks', () => {
+  test('passes when every insisted network is declared', () => {
+    const m = manifest({ requires: { capabilities: [], networks: [{ name: 'quarantine' }] } });
+    expect(refuseUndeclaredNetworks(m, ['dmz', 'quarantine'])).toBeNull();
+  });
+
+  test('refuses and names the missing network', () => {
+    const m = manifest({ requires: { capabilities: [], networks: [{ name: 'quarantine' }] } });
+    const refusal = refuseUndeclaredNetworks(m, ['dmz']);
+    expect(refusal).toContain('quarantine');
+    expect(refusal).toContain('never creates a network');
+  });
+
+  test('a submodule insisting on nothing passes', () => {
+    expect(refuseUndeclaredNetworks(manifest(), [])).toBeNull();
+  });
+});
+
+describe('createInstanceOps against a real database', () => {
+  let root: string;
+  let db: DbClient;
+  let parentPath: string;
+
+  const SUBMODULE_YAML = `
+celilo_contract: "1.0"
+id: lab
+name: BYOI Lab
+version: 1.0.0
+variables:
+  owns:
+    - name: ssh_key
+      type: string
+      required: true
+      source: user
+      description: Public key baked into authorized_keys
+`;
+
+  async function setup(opts: { submoduleYaml?: string; declaredNetworks?: string[] } = {}) {
+    parentPath = join(root, 'modules', 'byoi');
+    const submodulePath = join(parentPath, 'submodules', 'lab');
+    await mkdir(join(submodulePath, 'ansible'), { recursive: true });
+    await writeFile(join(parentPath, 'manifest.yml'), 'id: byoi\n');
+    await writeFile(join(submodulePath, 'manifest.yml'), opts.submoduleYaml ?? SUBMODULE_YAML);
+
+    db.$client.run(
+      "INSERT INTO modules (id,name,version,manifest_data,source_path) VALUES ('byoi','byoi','1.0.0',?,?)",
+      [JSON.stringify({ id: 'byoi', submodules: ['lab'] }), parentPath],
+    );
+
+    return createInstanceOps({
+      parentId: 'byoi',
+      db,
+      declaredNetworks: opts.declaredNetworks ?? ['quarantine'],
+    });
+  }
+
+  const worker = (ops: ReturnType<typeof createInstanceOps>) =>
+    createModuleDeployWorker({ moduleId: 'byoi', ops });
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'celilo-instance-ops-'));
+    db = createDbClient({ path: join(root, 'celilo.db') });
+  });
+
+  afterEach(async () => {
+    db.$client.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('records an instance, its config, and its symlink farm', async () => {
+    const ops = await setup();
+    const moduleId = await ops.create({
+      submodule: 'lab',
+      instanceKey: 'sub-abc',
+      config: { ssh_key: 'ssh-ed25519 AAAA' },
+      label: 'Sally',
+    });
+
+    expect(moduleId).toBe(deriveInstanceModuleId('byoi', 'lab', 'sub-abc'));
+
+    // A flat peer of every other module, never nested under the parent.
+    const instancePath = join(dirname(parentPath), moduleId);
+    expect(dirname(instancePath)).toBe(dirname(parentPath));
+    expect(existsSync(join(instancePath, 'generated'))).toBe(true);
+    expect(existsSync(join(instancePath, 'ansible'))).toBe(true);
+
+    const row = db.$client
+      .query('SELECT state, label, parent_id, submodule FROM module_instances')
+      .get() as Record<string, unknown>;
+    expect(row).toMatchObject({
+      state: 'pending',
+      label: 'Sally',
+      parent_id: 'byoi',
+      submodule: 'lab',
+    });
+
+    const config = db.$client
+      .query("SELECT value_json FROM module_configs WHERE module_id = ? AND key = 'ssh_key'")
+      .get(moduleId) as { value_json: string };
+    expect(JSON.parse(config.value_json)).toBe('ssh-ed25519 AAAA');
+  });
+
+  // A reconcile loop that fires twice must not produce a second system.
+  test('is idempotent on the caller key and repairs the farm on a repeat', async () => {
+    const ops = await setup();
+    const first = await ops.create({
+      submodule: 'lab',
+      instanceKey: 'sub-abc',
+      config: { ssh_key: 'k1' },
+    });
+
+    const instancePath = join(dirname(parentPath), first);
+    await rm(join(instancePath, 'ansible'), { force: true });
+
+    const second = await ops.create({
+      submodule: 'lab',
+      instanceKey: 'sub-abc',
+      config: { ssh_key: 'k2' },
+    });
+
+    expect(second).toBe(first);
+    expect(
+      (db.$client.query('SELECT count(*) n FROM module_instances').get() as { n: number }).n,
+    ).toBe(1);
+    // A retry REPAIRS rather than merely not-breaking.
+    expect(existsSync(join(instancePath, 'ansible'))).toBe(true);
+  });
+
+  test('refuses invalid config before writing anything', async () => {
+    const ops = await setup();
+
+    let caught: unknown;
+    try {
+      await ops.create({ submodule: 'lab', instanceKey: 'sub-abc', config: {} });
+    } catch (error) {
+      caught = error;
+    }
+    // Duck-typed, because the error crosses the identity boundary a module's
+    // bundled copy of @celilo/capabilities creates (celilo#173).
+    expect(isInstanceRequestRefusedError(caught)).toBe(true);
+
+    expect(
+      (db.$client.query('SELECT count(*) n FROM module_instances').get() as { n: number }).n,
+    ).toBe(0);
+  });
+
+  // D8, and at the REQUEST rather than three minutes into a terraform apply.
+  test('refuses an undeclared network before provisioning', async () => {
+    const ops = await setup({
+      submoduleYaml: `${SUBMODULE_YAML}
+requires:
+  networks:
+    - name: quarantine
+`,
+      declaredNetworks: ['dmz'],
+    });
+
+    await expect(
+      ops.create({ submodule: 'lab', instanceKey: 'k', config: { ssh_key: 'x' } }),
+    ).rejects.toThrow(/quarantine/);
+  });
+
+  test('a framework refusal reaches the caller as accepted:false, not a throw', async () => {
+    const capability = worker(await setup());
+
+    const result = await capability.instantiate({
+      submodule: 'lab',
+      instanceKey: 'sub-abc',
+      config: {},
+    });
+
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) expect(result.reason).toContain("'ssh_key' is required");
+  });
+
+  test('destroy marks the instance and reports its id', async () => {
+    const ops = await setup();
+    const moduleId = await ops.create({
+      submodule: 'lab',
+      instanceKey: 'sub-abc',
+      config: { ssh_key: 'k' },
+    });
+
+    expect(await ops.markForDestruction('lab', 'sub-abc')).toBe(moduleId);
+
+    const row = db.$client.query('SELECT state FROM module_instances').get() as { state: string };
+    expect(row.state).toBe('destroying');
+  });
+
+  test('destroying something that was never there reports null', async () => {
+    const ops = await setup();
+    expect(await ops.markForDestruction('lab', 'never')).toBeNull();
+  });
+
+  test('list reports what was recorded, scoped to the caller', async () => {
+    const ops = await setup();
+    await ops.create({ submodule: 'lab', instanceKey: 'a', config: { ssh_key: 'k' } });
+    await ops.create({ submodule: 'lab', instanceKey: 'b', config: { ssh_key: 'k' } });
+
+    const listed = await ops.list();
+
+    expect(listed.map((i) => i.instanceKey).sort()).toEqual(['a', 'b']);
+    expect(listed.every((i) => i.state === 'pending')).toBe(true);
+    expect(listed.every((i) => i.failureReason === null)).toBe(true);
+  });
+
+  test('declaredSubmodules reads the parent manifest, so authority is not supplied', async () => {
+    const ops = await setup();
+    expect(ops.declaredSubmodules()).toEqual(['lab']);
+
+    const result = await worker(ops).instantiate({ submodule: 'not-mine', instanceKey: 'k' });
+    expect(result.accepted).toBe(false);
+  });
+});

package/src/services/instance-ops.ts

@@ -0,0 +1,292 @@
+/**
+ * The side-effecting half of `celilo_module_deploy_worker`
+ * (openspec/changes/submodules, D3, D6, D8).
+ *
+ * `createModuleDeployWorker` in `@celilo/capabilities` owns the refusals a
+ * caller can reason about without a database: does this module declare that
+ * submodule, is the key usable. This owns everything that touches celilo:
+ * validating config against the submodule's declared variables, refusing a
+ * network nobody declared, deriving the instance's `modules.id`, writing the
+ * rows, and building its symlink farm.
+ *
+ * Split that way so the capability's contract is testable with no database at
+ * all (Rule 2.3), and so every refusal here happens BEFORE anything is
+ * provisioned. An instance whose config is wrong is refused at the request, not
+ * discovered at deploy time when there is no operator to tell.
+ *
+ * ── What this does NOT do ──
+ *
+ * It records intent. It does not provision. `instantiate` returns as soon as
+ * the rows and the farm exist, because provisioning takes minutes and the
+ * caller is a hook on a timer (D6). What picks a `pending` instance up and
+ * deploys it is a separate decision and is not made here.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import {
+  type InstanceOps,
+  InstanceRequestRefusedError,
+  type InstantiateRequest,
+  type ModuleInstance,
+} from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { moduleInstances, modules } from '../db/schema';
+import type { ModuleManifest } from '../manifest/schema';
+import { SUBMODULES_DIR, validateManifest } from '../manifest/validate';
+import { writeModuleConfigKey } from './config-interview';
+import {
+  buildInstanceLinkFarm,
+  deriveInstanceModuleId,
+  submoduleSourcePath,
+} from './module-instances';
+
+/**
+ * Config keys a caller may not set, because celilo derives them.
+ *
+ * A variable whose `source` is anything but `user` is celilo's answer, not the
+ * parent's: `infrastructure` comes from the selected host, `capability` from a
+ * provider, `system` from system config, `terraform` from an output. Letting a
+ * caller supply one would have it silently overwritten at generate time, which
+ * looks like celilo ignoring the request.
+ */
+function callerSettableVariables(manifest: ModuleManifest): Map<string, { required: boolean }> {
+  const settable = new Map<string, { required: boolean }>();
+  for (const variable of manifest.variables?.owns ?? []) {
+    if (variable.source !== 'user') continue;
+    settable.set(variable.name, { required: variable.required && variable.default === undefined });
+  }
+  return settable;
+}
+
+/**
+ * Validate an instance's config against the submodule's declared variables.
+ *
+ * Pure, so the rules are testable without a filesystem or a database. Reports
+ * EVERY problem rather than the first: a caller fixing one key at a time across
+ * four round trips, each costing a failed instantiation, is the experience this
+ * avoids.
+ */
+export function validateInstanceConfig(
+  submoduleManifest: ModuleManifest,
+  config: Record<string, unknown>,
+): string[] {
+  const settable = callerSettableVariables(submoduleManifest);
+  const declaredNames = new Set((submoduleManifest.variables?.owns ?? []).map((v) => v.name));
+  const problems: string[] = [];
+
+  for (const key of Object.keys(config)) {
+    if (settable.has(key)) continue;
+    problems.push(
+      declaredNames.has(key)
+        ? `'${key}' is not a caller-supplied value — celilo derives it. Remove it from the instance config.`
+        : `'${key}' is not declared by submodule '${submoduleManifest.id}'. It declares: ${[...settable.keys()].join(', ') || '(nothing settable)'}.`,
+    );
+  }
+
+  for (const [name, { required }] of settable) {
+    if (required && config[name] === undefined) {
+      problems.push(
+        `'${name}' is required by submodule '${submoduleManifest.id}' and was not supplied.`,
+      );
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Refuse a submodule that insists on a network celilo has not been told about
+ * (D8), at the REQUEST rather than at provision time.
+ *
+ * celilo owns the network namespace: a module may insist a network exists and
+ * read its value, and may never write one. So an instantiation cannot create
+ * the missing network, and discovering it three minutes into a terraform apply
+ * gives an operator a failure that names an address instead of a name.
+ *
+ * Pure over the declared set, because "which networks exist" is a system-config
+ * question the caller resolves.
+ */
+export function refuseUndeclaredNetworks(
+  submoduleManifest: ModuleManifest,
+  declaredNetworks: readonly string[],
+): string | null {
+  const insisted = (submoduleManifest.requires?.networks ?? [])
+    .map((requirement) => requirement.name)
+    .filter((name): name is string => typeof name === 'string');
+
+  const missing = insisted.filter((name) => !declaredNetworks.includes(name));
+  if (missing.length === 0) return null;
+
+  return `Submodule '${submoduleManifest.id}' requires network(s) ${missing.join(', ')}, which celilo has no definition for. Declare them first — a module never creates a network, and an instance cannot either.`;
+}
+
+export interface InstanceOpsContext {
+  /** The calling module, whose authority the capability has already checked. */
+  parentId: string;
+  db: DbClient;
+  /** Networks celilo has definitions for. Supplied so this stays testable. */
+  declaredNetworks: readonly string[];
+}
+
+/**
+ * Read and validate a submodule's own manifest from its parent's install.
+ *
+ * Re-read at request time rather than trusted from import. A parent updated
+ * since it was imported ships a different submodule, and the instance about to
+ * be created runs the version ON DISK.
+ */
+async function loadSubmoduleManifest(
+  parentSourcePath: string,
+  submodule: string,
+): Promise<ModuleManifest> {
+  const manifestPath = join(submoduleSourcePath(parentSourcePath, submodule), 'manifest.yml');
+  if (!existsSync(manifestPath)) {
+    throw new InstanceRequestRefusedError(
+      `Submodule '${submodule}' has no manifest at ${SUBMODULES_DIR}/${submodule}/manifest.yml. Its parent's install is incomplete; reinstall or update it.`,
+    );
+  }
+
+  const parsed = validateManifest(await readFile(manifestPath, 'utf-8'));
+  if (!parsed.success) {
+    throw new InstanceRequestRefusedError(
+      `Submodule '${submodule}' has an invalid manifest: ${parsed.errors.map((e) => `${e.path}: ${e.message}`).join(', ')}`,
+    );
+  }
+  return parsed.data;
+}
+
+/** Build the framework-side ops for one calling module. */
+export function createInstanceOps(context: InstanceOpsContext): InstanceOps {
+  const { parentId, db, declaredNetworks } = context;
+
+  function parentRow() {
+    const row = db.select().from(modules).where(eq(modules.id, parentId)).get();
+    if (!row) {
+      throw new InstanceRequestRefusedError(`Module '${parentId}' is not installed.`);
+    }
+    return row;
+  }
+
+  function rowToInstance(row: typeof moduleInstances.$inferSelect): ModuleInstance {
+    return {
+      submodule: row.submodule,
+      instanceKey: row.instanceKey,
+      moduleId: row.moduleId,
+      label: row.label,
+      state: row.state,
+      failureReason: row.failureReason,
+      retryable: row.retryable,
+    };
+  }
+
+  return {
+    declaredSubmodules() {
+      const manifest = parentRow().manifestData as unknown as ModuleManifest;
+      return manifest.submodules ?? [];
+    },
+
+    async create(request: InstantiateRequest) {
+      const parent = parentRow();
+      const submoduleManifest = await loadSubmoduleManifest(parent.sourcePath, request.submodule);
+
+      const config = request.config ?? {};
+      const configProblems = validateInstanceConfig(submoduleManifest, config);
+      if (configProblems.length > 0) {
+        throw new InstanceRequestRefusedError(
+          `Configuration for '${request.submodule}' instance '${request.instanceKey}' is not valid:\n  ${configProblems.join('\n  ')}`,
+        );
+      }
+
+      const networkRefusal = refuseUndeclaredNetworks(submoduleManifest, declaredNetworks);
+      if (networkRefusal) throw new InstanceRequestRefusedError(networkRefusal);
+
+      const moduleId = deriveInstanceModuleId(parentId, request.submodule, request.instanceKey);
+
+      // Idempotent on the caller's key (D6), so a reconcile loop that fires
+      // twice is harmless rather than producing a second system. The farm is
+      // still rebuilt below: an existing instance whose parent gained a subtree
+      // needs its links converged, and doing it here means a retry REPAIRS.
+      const existing = db
+        .select()
+        .from(moduleInstances)
+        .where(eq(moduleInstances.moduleId, moduleId))
+        .get();
+
+      // A peer of every other module, never nested under the parent (D4). The
+      // flat store is what keeps backup's cross-module walk, `module list`,
+      // health and fleet status working on an instance with no change.
+      const instancePath = join(dirname(parent.sourcePath), moduleId);
+      await buildInstanceLinkFarm({
+        instancePath,
+        submodulePath: submoduleSourcePath(parent.sourcePath, request.submodule),
+      });
+
+      if (!existing) {
+        db.insert(modules)
+          .values({
+            id: moduleId,
+            name: `${submoduleManifest.name} (${request.label ?? request.instanceKey})`,
+            version: submoduleManifest.version,
+            description: submoduleManifest.description,
+            manifestData: submoduleManifest as unknown as Record<string, unknown>,
+            sourcePath: instancePath,
+            state: 'IMPORTED',
+          })
+          .run();
+
+        db.insert(moduleInstances)
+          .values({
+            moduleId,
+            parentId,
+            submodule: request.submodule,
+            instanceKey: request.instanceKey,
+            label: request.label ?? null,
+            state: 'pending',
+          })
+          .run();
+      }
+
+      // After the rows exist, so a config write cannot land on a module that is
+      // not there. Re-applied on a repeat create, which is what makes an
+      // instantiate a converge rather than a create-once.
+      for (const [key, value] of Object.entries(config)) {
+        await writeModuleConfigKey(moduleId, key, value, db);
+      }
+
+      return moduleId;
+    },
+
+    async markForDestruction(submodule: string, instanceKey: string) {
+      const moduleId = deriveInstanceModuleId(parentId, submodule, instanceKey);
+      const existing = db
+        .select()
+        .from(moduleInstances)
+        .where(eq(moduleInstances.moduleId, moduleId))
+        .get();
+
+      // Nothing to destroy is a success, so a reconcile loop need not check
+      // first. Null says so rather than an id that names nothing.
+      if (!existing) return null;
+
+      db.update(moduleInstances)
+        .set({ state: 'destroying', updatedAt: new Date() })
+        .where(eq(moduleInstances.moduleId, moduleId))
+        .run();
+
+      return moduleId;
+    },
+
+    async list() {
+      return db
+        .select()
+        .from(moduleInstances)
+        .where(eq(moduleInstances.parentId, parentId))
+        .orderBy(moduleInstances.createdAt)
+        .all()
+        .map(rowToInstance);
+    },
+  };
+}