@celilo/cli 0.3.30 → 0.4.0-alpha.1

package/src/services/module-operations.ts

@@ -0,0 +1,154 @@
+/**
+ * Module-operations tracking — used by `checkInFlight()` to refuse a
+ * backup or restore while another module operation (deploy, uninstall,
+ * backup, restore) is active.
+ *
+ * Lifecycle:
+ *   const opId = startOperation('homebridge', 'deploy');
+ *   try {
+ *     ...work...
+ *     completeOperation(opId);
+ *   } catch (err) {
+ *     failOperation(opId, err);
+ *     throw err;
+ *   }
+ *
+ * Rows with status='in_progress' whose pid is no longer alive are
+ * treated as abandoned (the process crashed before the completion
+ * update landed) and ignored by `checkInFlight()`. This keeps a single
+ * Ctrl-C from wedging the system, at the cost of leaving stale rows in
+ * the table; a future cleanup command can sweep them.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { getDb } from '../db/client';
+import { type ModuleOperation, type ModuleOperationKind, moduleOperations } from '../db/schema';
+
+/**
+ * Insert an in-progress row for an operation. Returns the operation id
+ * that must be passed to completeOperation/failOperation.
+ */
+export function startOperation(moduleId: string, operation: ModuleOperationKind): string {
+  const db = getDb();
+  const id = randomUUID();
+  db.insert(moduleOperations)
+    .values({
+      id,
+      moduleId,
+      operation,
+      status: 'in_progress',
+      pid: process.pid,
+    })
+    .run();
+  return id;
+}
+
+export function completeOperation(operationId: string): void {
+  const db = getDb();
+  db.update(moduleOperations)
+    .set({ status: 'completed', completedAt: new Date() })
+    .where(eq(moduleOperations.id, operationId))
+    .run();
+}
+
+export function failOperation(operationId: string, error: unknown): void {
+  const db = getDb();
+  const message = error instanceof Error ? error.message : String(error);
+  db.update(moduleOperations)
+    .set({ status: 'failed', completedAt: new Date(), errorMessage: message })
+    .where(eq(moduleOperations.id, operationId))
+    .run();
+}
+
+/**
+ * True if the OS still has a process with the given pid. `kill(pid, 0)`
+ * sends no signal but throws ESRCH if the process is gone — the standard
+ * idiom for liveness on POSIX.
+ */
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface InFlightConflict {
+  operation: ModuleOperation;
+  /** A short, operator-readable description: "deploy of homebridge (pid 12345)". */
+  describe: string;
+}
+
+/**
+ * Returns rows that genuinely look in-flight: status='in_progress' AND
+ * the originating process is still alive. Abandoned rows (process gone)
+ * are excluded so a stale Ctrl-C doesn't block future operations.
+ *
+ * @param excludeOperationId - operation id to exclude from the check
+ *   (so an operation doesn't see itself as a conflict).
+ */
+export function checkInFlight(excludeOperationId?: string): InFlightConflict[] {
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(moduleOperations)
+    .where(eq(moduleOperations.status, 'in_progress'))
+    .all();
+
+  const conflicts: InFlightConflict[] = [];
+  for (const row of rows) {
+    if (excludeOperationId && row.id === excludeOperationId) continue;
+    if (!isPidAlive(row.pid)) continue;
+    conflicts.push({
+      operation: row,
+      describe: `${row.operation} of ${row.moduleId} (pid ${row.pid})`,
+    });
+  }
+  return conflicts;
+}
+
+/**
+ * Throws an InFlightError when conflicts exist. Returned error message
+ * is operator-readable: it names the conflicting operation(s) and the
+ * suggested retry.
+ */
+export class InFlightError extends Error {
+  constructor(public readonly conflicts: InFlightConflict[]) {
+    const list = conflicts.map((c) => `  • ${c.describe}`).join('\n');
+    super(
+      `Cannot start: another module operation is in progress.\n${list}\nWait for it to complete (or fail) and re-run.`,
+    );
+    this.name = 'InFlightError';
+  }
+}
+
+/**
+ * Throws InFlightError if a conflicting operation is in flight.
+ * Call this BEFORE startOperation() at the entry of backup/restore
+ * service functions.
+ */
+export function refuseIfInFlight(excludeOperationId?: string): void {
+  const conflicts = checkInFlight(excludeOperationId);
+  if (conflicts.length > 0) {
+    throw new InFlightError(conflicts);
+  }
+}
+
+/**
+ * Restricted variant: refuse if any operation matching the predicate is
+ * in-flight. Used by callers that want to allow some concurrent ops
+ * (e.g. multiple backups across modules) but not others. Today's spec
+ * doesn't need this — refuseIfInFlight() suffices — but the hook is
+ * here for the future.
+ */
+export function refuseIfInFlightMatching(
+  predicate: (op: ModuleOperation) => boolean,
+  excludeOperationId?: string,
+): void {
+  const conflicts = checkInFlight(excludeOperationId).filter((c) => predicate(c.operation));
+  if (conflicts.length > 0) {
+    throw new InFlightError(conflicts);
+  }
+}

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

@@ -3,6 +3,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { defineEvents, openBus } from '@celilo/event-bus';
+import { ModuleSubscriptionSchema } from '../manifest/schema';
 import type { ModuleManifest } from '../manifest/schema';
 import {
   registerModuleSubscriptions,
@@ -69,6 +70,63 @@ describe('resolveSubscription', () => {
     expect(resolved.maxAttempts).toBe(5);
     expect(resolved.timeoutMs).toBe(90000);
   });
+
+  it('synthesizes a `celilo events run-hook` handler for a hook subscription', () => {
+    const resolved = resolveSubscription(
+      {
+        name: 'dns-register-system',
+        pattern: 'system.created.*',
+        hook: 'on_system_event',
+        hook_inputs: { op: 'register' },
+      },
+      'technitium',
+      '/var/lib/celilo/modules/technitium',
+    );
+    // The runner re-reads the manifest by (module, sub-name); the handler
+    // carries exactly those two identifiers and nothing module-path-specific.
+    expect(resolved.handler).toBe('celilo events run-hook technitium dns-register-system');
+    expect(resolved.name).toBe('technitium.dns-register-system');
+    expect(resolved.pattern).toBe('system.created.*');
+  });
+});
+
+describe('ModuleSubscriptionSchema handler/hook validation', () => {
+  const base = { name: 'a', pattern: 'x' };
+
+  it('accepts a handler-only subscription', () => {
+    expect(ModuleSubscriptionSchema.safeParse({ ...base, handler: 'echo' }).success).toBe(true);
+  });
+
+  it('accepts a hook-only subscription, with or without hook_inputs', () => {
+    expect(ModuleSubscriptionSchema.safeParse({ ...base, hook: 'on_system_event' }).success).toBe(
+      true,
+    );
+    expect(
+      ModuleSubscriptionSchema.safeParse({
+        ...base,
+        hook: 'on_system_event',
+        hook_inputs: { op: 'register' },
+      }).success,
+    ).toBe(true);
+  });
+
+  it('rejects declaring both handler and hook', () => {
+    expect(
+      ModuleSubscriptionSchema.safeParse({ ...base, handler: 'echo', hook: 'on_system_event' })
+        .success,
+    ).toBe(false);
+  });
+
+  it('rejects declaring neither handler nor hook', () => {
+    expect(ModuleSubscriptionSchema.safeParse(base).success).toBe(false);
+  });
+
+  it('rejects hook_inputs without a hook', () => {
+    expect(
+      ModuleSubscriptionSchema.safeParse({ ...base, handler: 'echo', hook_inputs: { op: 'x' } })
+        .success,
+    ).toBe(false);
+  });
 });
 
 describe('register / unregister roundtrip', () => {

package/src/services/module-subscriptions.ts

@@ -6,6 +6,8 @@
  * Substitutions performed at subscribe time:
  *   - `$self` in `pattern`    → the module's id
  *   - `${MODULE_PATH}` in `handler` → the module's installed targetPath
+ *   - a `hook:` subscription   → a synthesized `celilo events run-hook
+ *     <module> <sub-name>` handler (v2/EVENT_DRIVEN_HOOK_SUBSCRIPTIONS.md)
  *
  * The bus subscriber's name is namespaced as `<module-id>.<sub-name>`
  * so two modules can declare a subscription named `smoke` without
@@ -44,13 +46,34 @@ export function resolveSubscription(
   return {
     name: scopedName(moduleId, sub.name),
     pattern: substituteSelf(sub.pattern, moduleId),
-    handler: substituteModulePath(sub.handler, modulePath),
+    handler: resolveHandler(sub, moduleId, modulePath),
     maxAttempts: sub.max_attempts,
     timeoutMs: sub.timeout_ms,
     registeredBy: moduleId,
   };
 }
 
+/**
+ * The bus handler string for a subscription. A `hook:` subscription becomes a
+ * synthesized `celilo events run-hook <module> <sub-name>` invocation — the
+ * generic runner re-reads this module's manifest by (module, sub-name) to find
+ * the hook + its `hook_inputs`, then runs it in a fault-isolated subprocess
+ * with backend access. A `handler:` subscription is the literal command with
+ * `${MODULE_PATH}` resolved. The schema guarantees exactly one is set; the
+ * final throw is defense-in-depth (no surprises).
+ */
+function resolveHandler(sub: ModuleSubscription, moduleId: string, modulePath: string): string {
+  if (sub.hook) {
+    return `celilo events run-hook ${moduleId} ${sub.name}`;
+  }
+  if (sub.handler) {
+    return substituteModulePath(sub.handler, modulePath);
+  }
+  throw new Error(
+    `subscription '${sub.name}' on module '${moduleId}' declares neither 'handler' nor 'hook'`,
+  );
+}
+
 /**
  * Register all of a module's subscriptions on the bus. Idempotent —
  * re-running with the same manifest updates existing rows in place.

package/src/services/module-types-generator.test.ts

@@ -67,13 +67,13 @@ describe('generateModuleTypes', () => {
     const out = generateModuleTypes(baseManifest({ id: 'empty', name: 'Empty Module' }));
     expect(out).toContain('// Generated from manifest.yml');
     expect(out).toContain('Do not edit by hand');
-    expect(out).toContain('export interface EmptyConfig {');
+    expect(out).toContain('export type EmptyConfig = {');
     expect(out).toContain('(No variables declared — module has no typed config surface)');
   });
 
-  test('produces the right interface name from a kebab-case module ID', () => {
+  test('produces the right type-alias name from a kebab-case module ID', () => {
     const out = generateModuleTypes(baseManifest({ id: 'dns-external', name: 'DNS External' }));
-    expect(out).toContain('export interface DnsExternalConfig {');
+    expect(out).toContain('export type DnsExternalConfig = {');
   });
 
   test('renders required fields as non-optional', () => {

package/src/services/module-types-generator.ts

@@ -139,8 +139,13 @@ export function generateModuleTypes(manifest: ModuleManifest): string {
   lines.push(' * Fields are derived from `variables.owns` and `variables.imports` in the');
   lines.push(' * module manifest. Optional fields (marked with `?`) correspond to variables');
   lines.push(' * that are neither `required: true` nor have a `default:` value.');
+  lines.push(' *');
+  lines.push(' * Emitted as a `type` alias rather than an `interface` so it satisfies the');
+  lines.push(' * `Record<string, unknown>` constraint on `defineHook<Config>`: TypeScript');
+  lines.push(' * gives type aliases an implicit index signature but withholds one from');
+  lines.push(' * interfaces (which can be declaration-merged). See v2/issues.');
   lines.push(' */');
-  lines.push(`export interface ${typeName} {`);
+  lines.push(`export type ${typeName} = {`);
 
   const ownsFields: string[] = [];
   const importsFields: string[] = [];
@@ -182,7 +187,7 @@ export function generateModuleTypes(manifest: ModuleManifest): string {
     lines.push('  // (No variables declared — module has no typed config surface)');
   }
 
-  lines.push('}');
+  lines.push('};');
   lines.push('');
 
   return lines.join('\n');

package/src/services/proxmox-reconcile.test.ts

@@ -0,0 +1,333 @@
+/**
+ * SC5 unit tests — Proxmox reconciliation planning.
+ *
+ * Covers:
+ *   - planProxmoxReconcile: empty-block, no-systems-in-zone,
+ *     non-Proxmox provider skip, template resolution from
+ *     module config, $capability: resolution.
+ *
+ * executeProxmoxReconcile is currently observation-only (logs
+ * warnings); its log surface is tested by a single smoke test
+ * that just verifies the function doesn't throw on an empty plan
+ * and on a populated one.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import {
+  capabilities,
+  containerServices,
+  ipAllocations,
+  moduleInfrastructure,
+  modules,
+} from '../db/schema';
+import type { BaseModuleAspect } from '../manifest/schema';
+import { upsertModuleConfig } from './module-config';
+import { executeProxmoxReconcile, planProxmoxReconcile } from './proxmox-reconcile';
+
+const PROVIDER_MODULE_ID = 'knot-unbound-internal';
+
+function seedProviderModule(opts: { configs?: Record<string, string> } = {}) {
+  const db = getDb();
+  db.insert(modules)
+    .values({
+      id: PROVIDER_MODULE_ID,
+      name: PROVIDER_MODULE_ID,
+      version: '1.0.0',
+      manifestData: {
+        id: PROVIDER_MODULE_ID,
+        name: PROVIDER_MODULE_ID,
+        version: '1.0.0',
+        celilo_contract: '1.0',
+      },
+      sourcePath: `/tmp/${PROVIDER_MODULE_ID}`,
+    })
+    .run();
+  for (const [key, value] of Object.entries(opts.configs ?? {})) {
+    upsertModuleConfig(db, PROVIDER_MODULE_ID, key, value);
+  }
+}
+
+function seedProxmoxService(serviceId = 'proxmox-home-lab') {
+  const id = randomUUID();
+  getDb()
+    .insert(containerServices)
+    .values({
+      id,
+      serviceId,
+      name: serviceId,
+      providerName: 'proxmox',
+      zones: ['dmz', 'app', 'secure', 'internal'],
+      apiCredentialsEncrypted: '{}',
+      providerConfig: {},
+      verified: true,
+    })
+    .run();
+  return id;
+}
+
+function seedDigitalOceanService(serviceId = 'do-vps') {
+  const id = randomUUID();
+  getDb()
+    .insert(containerServices)
+    .values({
+      id,
+      serviceId,
+      name: serviceId,
+      providerName: 'digitalocean',
+      zones: ['external'],
+      apiCredentialsEncrypted: '{}',
+      providerConfig: {},
+      verified: true,
+    })
+    .run();
+  return id;
+}
+
+function seedContainerLxc(opts: {
+  moduleId: string;
+  serviceUuid: string;
+  vmid: number;
+  containerIp: string;
+  zone: 'dmz' | 'app' | 'secure' | 'internal';
+}) {
+  const db = getDb();
+  db.insert(modules)
+    .values({
+      id: opts.moduleId,
+      name: opts.moduleId,
+      version: '1.0.0',
+      manifestData: {
+        id: opts.moduleId,
+        name: opts.moduleId,
+        version: '1.0.0',
+        celilo_contract: '1.0',
+      },
+      sourcePath: `/tmp/${opts.moduleId}`,
+    })
+    .run();
+  db.insert(moduleInfrastructure)
+    .values({
+      id: randomUUID(),
+      moduleId: opts.moduleId,
+      infrastructureType: 'container_service',
+      machineId: null,
+      serviceId: opts.serviceUuid,
+      containerMetadata: { vmid: opts.vmid },
+    })
+    .run();
+  db.insert(ipAllocations)
+    .values({
+      moduleId: opts.moduleId,
+      vmid: opts.vmid,
+      containerIp: opts.containerIp,
+      zone: opts.zone,
+    })
+    .run();
+}
+
+const aspectWithReconcile: BaseModuleAspect = {
+  ansible_role: 'dns-client-config',
+  applicable_zones: ['app', 'secure'],
+  triggers: ['on_install'],
+  proxmox_reconcile: {
+    tfvars: {
+      nameserver: '$self:target_ip',
+    },
+  },
+};
+
+describe('proxmox-reconcile', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-proxmox-reconcile-test-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    await runMigrations(process.env.CELILO_DB_PATH);
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  describe('planProxmoxReconcile', () => {
+    it('returns an empty plan when the aspect has no proxmox_reconcile block', async () => {
+      seedProviderModule();
+      const aspect: BaseModuleAspect = {
+        ansible_role: 'noop',
+        applicable_zones: ['app'],
+        triggers: ['on_install'],
+      };
+      const plan = await planProxmoxReconcile({
+        aspect,
+        providerModuleId: PROVIDER_MODULE_ID,
+        db: getDb(),
+      });
+      expect(plan.actions).toEqual([]);
+      expect(plan.skipped).toEqual([]);
+    });
+
+    it('returns an empty plan when no container_service systems match the zones', async () => {
+      seedProviderModule({ configs: { target_ip: '192.168.0.10' } });
+      const plan = await planProxmoxReconcile({
+        aspect: aspectWithReconcile,
+        providerModuleId: PROVIDER_MODULE_ID,
+        db: getDb(),
+      });
+      expect(plan.actions).toEqual([]);
+    });
+
+    it('emits one action per Proxmox LXC in scope, with tfvars resolved', async () => {
+      seedProviderModule({ configs: { target_ip: '192.168.0.10' } });
+      const proxmoxId = seedProxmoxService();
+      seedContainerLxc({
+        moduleId: 'forgejo',
+        serviceUuid: proxmoxId,
+        vmid: 142,
+        containerIp: '10.0.20.42/24',
+        zone: 'app',
+      });
+      seedContainerLxc({
+        moduleId: 'authentik',
+        serviceUuid: proxmoxId,
+        vmid: 130,
+        containerIp: '10.0.20.30/24',
+        zone: 'app',
+      });
+
+      const plan = await planProxmoxReconcile({
+        aspect: aspectWithReconcile,
+        providerModuleId: PROVIDER_MODULE_ID,
+        db: getDb(),
+      });
+
+      expect(plan.actions).toHaveLength(2);
+      const byModule = new Map(plan.actions.map((a) => [a.moduleId, a]));
+      expect(byModule.get('forgejo')?.tfvarUpdates).toEqual({ nameserver: '192.168.0.10' });
+      expect(byModule.get('authentik')?.tfvarUpdates).toEqual({ nameserver: '192.168.0.10' });
+      expect(plan.skipped).toEqual([]);
+    });
+
+    it('skips non-Proxmox provider systems with a clear reason', async () => {
+      seedProviderModule({ configs: { target_ip: '192.168.0.10' } });
+      const doId = seedDigitalOceanService();
+      seedContainerLxc({
+        moduleId: 'external-app',
+        serviceUuid: doId,
+        vmid: 0, // n/a for DO; the field is just required
+        containerIp: '10.0.20.50/24',
+        zone: 'app',
+      });
+
+      const plan = await planProxmoxReconcile({
+        aspect: aspectWithReconcile,
+        providerModuleId: PROVIDER_MODULE_ID,
+        db: getDb(),
+      });
+      expect(plan.actions).toEqual([]);
+      expect(plan.skipped).toHaveLength(1);
+      expect(plan.skipped[0].system.moduleId).toBe('external-app');
+      expect(plan.skipped[0].reason).toContain('non-proxmox');
+    });
+
+    it('resolves $capability: templates against the providing module', async () => {
+      // Provider registers a capability whose data is consumed by the
+      // tfvar template. Real-world example: a future host-firewall
+      // aspect could read $capability:public_web.internal_ip.
+      seedProviderModule();
+      getDb()
+        .insert(capabilities)
+        .values({
+          moduleId: PROVIDER_MODULE_ID,
+          capabilityName: 'dns_internal',
+          version: '1.0.0',
+          data: { server: { ip: '10.99.0.53' } },
+        })
+        .run();
+
+      const proxmoxId = seedProxmoxService();
+      seedContainerLxc({
+        moduleId: 'forgejo',
+        serviceUuid: proxmoxId,
+        vmid: 142,
+        containerIp: '10.0.20.42/24',
+        zone: 'app',
+      });
+
+      const aspect: BaseModuleAspect = {
+        ansible_role: 'dns-client-config',
+        applicable_zones: ['app'],
+        triggers: ['on_install'],
+        proxmox_reconcile: {
+          tfvars: { nameserver: '$capability:dns_internal.server.ip' },
+        },
+      };
+      const plan = await planProxmoxReconcile({
+        aspect,
+        providerModuleId: PROVIDER_MODULE_ID,
+        db: getDb(),
+      });
+      expect(plan.actions[0].tfvarUpdates).toEqual({ nameserver: '10.99.0.53' });
+    });
+
+    it('throws with a clear message when a template references a missing field', async () => {
+      seedProviderModule(); // no target_ip configured
+      const proxmoxId = seedProxmoxService();
+      seedContainerLxc({
+        moduleId: 'forgejo',
+        serviceUuid: proxmoxId,
+        vmid: 142,
+        containerIp: '10.0.20.42/24',
+        zone: 'app',
+      });
+      await expect(
+        planProxmoxReconcile({
+          aspect: aspectWithReconcile,
+          providerModuleId: PROVIDER_MODULE_ID,
+          db: getDb(),
+        }),
+      ).rejects.toThrow(/Cannot resolve \$self:target_ip/);
+    });
+  });
+
+  describe('executeProxmoxReconcile', () => {
+    it('is a safe no-op on an empty plan', () => {
+      expect(() => executeProxmoxReconcile({ actions: [], skipped: [] })).not.toThrow();
+    });
+
+    it('does not throw on a populated plan (currently observation-only)', () => {
+      const plan = {
+        actions: [
+          {
+            moduleId: 'forgejo',
+            serviceId: 'proxmox-home-lab',
+            tfvarUpdates: { nameserver: '192.168.0.10' },
+            containerSystem: {
+              infrastructureId: 'infra-1',
+              moduleId: 'forgejo',
+              serviceId: 'proxmox-home-lab',
+              providerName: 'proxmox' as const,
+              zone: 'app' as const,
+              containerIp: '10.0.20.42/24',
+              containerMetadata: { vmid: 142 },
+              apiOnly: false,
+            },
+          },
+        ],
+        skipped: [],
+      };
+      expect(() => executeProxmoxReconcile(plan)).not.toThrow();
+    });
+  });
+});