@celilo/cli 0.2.0 → 0.3.0

package/src/services/module-deploy.ts

@@ -244,10 +244,61 @@ async function invokeHookWithEnsureRetry(
  * @param options - Deployment options
  * @returns Deployment result with phase tracking
  */
+/**
+ * Public entry point. Wraps the core deploy work with event-bus
+ * lifecycle emits (`deploy.started.<id>`, `deploy.completed.<id>`,
+ * `deploy.failed.<id>`) so subscribers — production smoke tests,
+ * alerting, etc. — can react. Bus emit failures are best-effort and
+ * never affect the deploy outcome.
+ */
 export async function deployModule(
   moduleId: string,
   db: DbClient,
   options: DeployOptions = {},
+): Promise<DeployResult> {
+  const startedAt = Date.now();
+  const { emitDeployCompleted, emitDeployFailed, emitDeployStarted, emitHealthCheckFailed } =
+    await import('./celilo-events');
+
+  emitDeployStarted({ module: moduleId, startedAt });
+
+  let result: DeployResult;
+  try {
+    result = await deployModuleImpl(moduleId, db, options);
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    emitDeployFailed({
+      module: moduleId,
+      startedAt,
+      durationMs: Date.now() - startedAt,
+      error,
+    });
+    throw err;
+  }
+
+  const durationMs = Date.now() - startedAt;
+  if (result.success) {
+    emitDeployCompleted({ module: moduleId, startedAt, durationMs });
+  } else {
+    emitDeployFailed({
+      module: moduleId,
+      startedAt,
+      durationMs,
+      error: result.error ?? 'unknown error',
+    });
+    // Health-check failures are a sub-class worth surfacing on their own
+    // channel so subscribers can target them without parsing error strings.
+    if (result.error?.toLowerCase().includes('health check')) {
+      emitHealthCheckFailed({ module: moduleId, reason: result.error });
+    }
+  }
+  return result;
+}
+
+async function deployModuleImpl(
+  moduleId: string,
+  db: DbClient,
+  options: DeployOptions = {},
 ): Promise<DeployResult> {
   const phases: DeployResult['phases'] = {};
 
@@ -295,7 +346,6 @@ export async function deployModule(
       }
     }
 
-    log.info(`Deploying module: ${moduleId}`);
     const validation = await validateAndPrepareDeployment(moduleId, db);
     phases.validation = validation.success;
     phases.autoGenerated = validation.autoGenerated;
@@ -469,11 +519,9 @@ export async function deployModule(
       }
     }
 
-    log.success('Validation passed:');
-    log.message('  Templates generated');
-    if (validation.autoBuilt) {
-      log.message('  Module built');
-    }
+    log.success(
+      validation.autoBuilt ? 'Templates generated and module built' : 'Templates generated',
+    );
 
     // Run validate_config hook if defined (e.g., credential validation via Playwright)
     if (manifest.hooks?.validate_config) {
@@ -613,7 +661,7 @@ export async function deployModule(
       // Run on_install hook for config-only modules (e.g. publishing static files to caddy)
       if (manifest.hooks?.on_install) {
         const onInstallDef = manifest.hooks.on_install;
-        log.info('Running on_install hook...');
+        log.success('Running on_install hook');
 
         const { moduleConfigs: pcTable, secrets: secretsTable } = await import('../db/schema');
         const installConfigs = db
@@ -695,7 +743,6 @@ export async function deployModule(
       // Run health checks for config-only modules too
       if (manifest.hooks?.health_check) {
         const { runModuleHealthCheck } = await import('./health-runner');
-        log.info('Running health checks...');
         const healthResult = await runModuleHealthCheck(moduleId, db, {
           debug: options.debug,
           noInteractive: options.noInteractive,
@@ -710,7 +757,6 @@ export async function deployModule(
             .join('\n');
           return { success: false, phases, error: `Health checks failed:\n${failedChecks}` };
         }
-        log.success('Health checks passed → VERIFIED');
       }
 
       return {
@@ -855,7 +901,7 @@ export async function deployModule(
 
         if (!containerCreatedHook) continue;
 
-        log.info(
+        log.message(
           `Running container_created hook on ${capRecord.moduleId} (provides ${requiredCap.name})`,
         );
 
@@ -988,7 +1034,6 @@ export async function deployModule(
     let machineId: string | undefined;
     if (plan.infrastructure?.type === 'machine' && plan.infrastructure.machineId) {
       machineId = plan.infrastructure.machineId;
-      log.info(`Writing temporary SSH key for machine: ${machineId}`);
       await writeTemporarySshKey(machineId);
     }
 
@@ -1012,15 +1057,16 @@ export async function deployModule(
         plan.infrastructure?.type === 'container_service' &&
         plan.infrastructure.serviceId
       ) {
-        // TODO: Extract Terraform outputs and update module_infrastructure.containerMetadata
-        // This will be implemented when we add Terraform output parsing
-        log.warn('Container service metadata update not yet implemented');
+        // TODO: extract Terraform outputs and persist them on
+        // module_infrastructure.containerMetadata. Until that lands,
+        // the deploy still succeeds — we just don't track which
+        // container ID/IP got assigned per module in the DB.
       }
 
       // Run on_install hook (post-deploy actions like port forwarding, DNS registration)
       if (manifest.hooks?.on_install) {
         const onInstallDef = manifest.hooks.on_install;
-        log.info('Running on_install hook...');
+        log.success('Running on_install hook');
 
         const { moduleConfigs: pcTable, secrets: secretsTable } = await import('../db/schema');
         const installConfigs = db
@@ -1120,7 +1166,6 @@ export async function deployModule(
       // Run health checks after successful deployment
       if (manifest.hooks?.health_check) {
         const { runModuleHealthCheck } = await import('./health-runner');
-        log.info('Running post-deploy health checks...');
         const healthResult = await runModuleHealthCheck(moduleId, db, {
           debug: options.debug,
           noInteractive: options.noInteractive,
@@ -1144,10 +1189,6 @@ export async function deployModule(
             error: `Health checks failed:\n${failedChecks}`,
           };
         }
-        const summary = healthResult.checks
-          .map((c) => `  ${c.status === 'pass' ? '✓' : '⚠'} ${c.name}`)
-          .join('\n');
-        log.success(`Health checks passed → VERIFIED\n${summary}`);
       }
 
       // Auto-register module hostname in internal DNS (if available)
@@ -1167,7 +1208,7 @@ export async function deployModule(
         );
       }
 
-      display.instantEvent(`\x1b[32m✓\x1b[0m Module '${moduleId}' deployed successfully`);
+      log.success(`Module '${moduleId}' deployed successfully`);
       return {
         success: true,
         phases,
@@ -1175,7 +1216,6 @@ export async function deployModule(
     } finally {
       // Clean up temporary SSH key
       if (machineId) {
-        log.info(`Cleaning up temporary SSH key for machine: ${machineId}`);
         deleteTemporarySshKey(machineId);
       }
     }

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

@@ -0,0 +1,197 @@
+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 { defineEvents, openBus } from '@celilo/event-bus';
+import type { ModuleManifest } from '../manifest/schema';
+import {
+  registerModuleSubscriptions,
+  resolveSubscription,
+  unregisterModuleSubscriptions,
+} from './module-subscriptions';
+
+const baseManifest = (overrides: Partial<ModuleManifest> = {}): ModuleManifest => ({
+  celilo_contract: '1.0',
+  id: 'lunacycle',
+  name: 'Lunacycle',
+  version: '1.0.0',
+  requires: { capabilities: [] },
+  provides: { capabilities: [] },
+  variables: { owns: [], imports: [] },
+  ...overrides,
+});
+
+describe('resolveSubscription', () => {
+  it('substitutes $self in pattern and ${MODULE_PATH} in handler', () => {
+    const resolved = resolveSubscription(
+      {
+        name: 'smoke-after-deploy',
+        pattern: 'deploy.completed.$self',
+        handler: 'bun ${MODULE_PATH}/celilo/scripts/smoke.ts',
+      },
+      'lunacycle',
+      '/var/lib/celilo/modules/lunacycle',
+    );
+
+    expect(resolved.name).toBe('lunacycle.smoke-after-deploy');
+    expect(resolved.pattern).toBe('deploy.completed.lunacycle');
+    expect(resolved.handler).toBe('bun /var/lib/celilo/modules/lunacycle/celilo/scripts/smoke.ts');
+    expect(resolved.registeredBy).toBe('lunacycle');
+  });
+
+  it('only substitutes $self when followed by . or end-of-string', () => {
+    // `$selfish` would not be a real pattern but we want to ensure the
+    // substitution doesn't accidentally rewrite identifier-like names.
+    const resolved = resolveSubscription(
+      {
+        name: 'a',
+        pattern: '$self.x.$selfish',
+        handler: 'echo',
+      },
+      'foo',
+      '/p',
+    );
+    expect(resolved.pattern).toBe('foo.x.$selfish');
+  });
+
+  it('passes through max_attempts and timeout_ms when set', () => {
+    const resolved = resolveSubscription(
+      {
+        name: 'a',
+        pattern: 'x',
+        handler: 'echo',
+        max_attempts: 5,
+        timeout_ms: 90000,
+      },
+      'foo',
+      '/p',
+    );
+    expect(resolved.maxAttempts).toBe(5);
+    expect(resolved.timeoutMs).toBe(90000);
+  });
+});
+
+describe('register / unregister roundtrip', () => {
+  let dir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'modsubs-test-'));
+    dbPath = join(dir, 'events.db');
+    process.env.CELILO_EVENT_BUS_PATH = dbPath;
+  });
+  afterEach(() => {
+    process.env.CELILO_EVENT_BUS_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('manifest with no subscriptions is a no-op', () => {
+    const result = registerModuleSubscriptions(baseManifest(), '/p');
+    expect(result.registered).toBe(0);
+  });
+
+  it('registers each subscription as a row, names scoped to module id', () => {
+    const result = registerModuleSubscriptions(
+      baseManifest({
+        subscriptions: [
+          {
+            name: 'smoke',
+            pattern: 'deploy.completed.$self',
+            handler: 'bun ${MODULE_PATH}/x.ts',
+          },
+          {
+            name: 'on-cert-rotated',
+            pattern: 'cert.rotated',
+            handler: 'echo',
+          },
+        ],
+      }),
+      '/var/lib/celilo/modules/lunacycle',
+    );
+    expect(result.registered).toBe(2);
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      const rows = bus.db
+        .query<{ name: string; pattern: string; handler: string }, []>(
+          'SELECT name, pattern, handler FROM subscribers ORDER BY name',
+        )
+        .all();
+      expect(rows).toEqual([
+        {
+          name: 'lunacycle.on-cert-rotated',
+          pattern: 'cert.rotated',
+          handler: 'echo',
+        },
+        {
+          name: 'lunacycle.smoke',
+          pattern: 'deploy.completed.lunacycle',
+          handler: 'bun /var/lib/celilo/modules/lunacycle/x.ts',
+        },
+      ]);
+    } finally {
+      bus.close();
+    }
+  });
+
+  it('re-registering the same manifest is idempotent (updates rows in place)', () => {
+    const m = baseManifest({
+      subscriptions: [{ name: 's', pattern: 'a', handler: 'echo first' }],
+    });
+    registerModuleSubscriptions(m, '/p');
+    // Edit the in-memory manifest and re-register; same name, new handler.
+    if (!m.subscriptions) throw new Error('subscriptions missing');
+    m.subscriptions[0].handler = 'echo second';
+    registerModuleSubscriptions(m, '/p');
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      const rows = bus.db
+        .query<{ count: number }, []>('SELECT COUNT(*) AS count FROM subscribers')
+        .get();
+      expect(rows?.count).toBe(1);
+      const row = bus.db.query<{ handler: string }, []>('SELECT handler FROM subscribers').get();
+      expect(row?.handler).toBe('echo second');
+    } finally {
+      bus.close();
+    }
+  });
+
+  it('unregister removes all subscriptions for the module, scoped by name prefix', () => {
+    registerModuleSubscriptions(
+      baseManifest({
+        id: 'lunacycle',
+        subscriptions: [
+          { name: 'a', pattern: 'x.$self', handler: 'echo' },
+          { name: 'b', pattern: 'y.$self', handler: 'echo' },
+        ],
+      }),
+      '/p',
+    );
+    // Another module's subs should NOT be touched.
+    registerModuleSubscriptions(
+      baseManifest({
+        id: 'authentik',
+        subscriptions: [{ name: 'a', pattern: 'z.$self', handler: 'echo' }],
+      }),
+      '/p',
+    );
+
+    const result = unregisterModuleSubscriptions('lunacycle');
+    expect(result.unregistered).toBe(2);
+
+    const bus = openBus({ dbPath, events: defineEvents({}) });
+    try {
+      const rows = bus.db
+        .query<{ name: string }, []>('SELECT name FROM subscribers ORDER BY name')
+        .all();
+      expect(rows).toEqual([{ name: 'authentik.a' }]);
+    } finally {
+      bus.close();
+    }
+  });
+});

package/src/services/module-subscriptions.ts

@@ -0,0 +1,120 @@
+/**
+ * Wire a module's manifest `subscriptions:` block into the SQLite event
+ * bus. Called from `module/import.ts` on install and from
+ * `cli/commands/module-remove.ts` on remove.
+ *
+ * Substitutions performed at subscribe time:
+ *   - `$self` in `pattern`    → the module's id
+ *   - `${MODULE_PATH}` in `handler` → the module's installed targetPath
+ *
+ * The bus subscriber's name is namespaced as `<module-id>.<sub-name>`
+ * so two modules can declare a subscription named `smoke` without
+ * colliding.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import { getEventBusPath } from '../config/paths';
+import type { ModuleManifest, ModuleSubscription } from '../manifest/schema';
+
+/**
+ * The bus is opened by the celilo CLI without an event registry — the
+ * CLI doesn't know the schemas of every module's events. The bus's
+ * empty-registry path skips payload validation, leaving that to the
+ * linked handlers (which open the bus *with* their own registry).
+ */
+const NO_SCHEMAS = defineEvents({});
+
+/**
+ * Resolve the per-module substitutions on a single subscription. Pure
+ * function: takes a parsed manifest entry, returns the bus-shaped
+ * subscribe options.
+ */
+export function resolveSubscription(
+  sub: ModuleSubscription,
+  moduleId: string,
+  modulePath: string,
+): {
+  name: string;
+  pattern: string;
+  handler: string;
+  maxAttempts?: number;
+  timeoutMs?: number;
+  registeredBy: string;
+} {
+  return {
+    name: scopedName(moduleId, sub.name),
+    pattern: substituteSelf(sub.pattern, moduleId),
+    handler: substituteModulePath(sub.handler, modulePath),
+    maxAttempts: sub.max_attempts,
+    timeoutMs: sub.timeout_ms,
+    registeredBy: moduleId,
+  };
+}
+
+/**
+ * Register all of a module's subscriptions on the bus. Idempotent —
+ * re-running with the same manifest updates existing rows in place.
+ *
+ * If the module's manifest declares no subscriptions, this is a
+ * cheap no-op (the bus DB isn't even touched).
+ */
+export function registerModuleSubscriptions(
+  manifest: ModuleManifest,
+  modulePath: string,
+): { registered: number } {
+  const subs = manifest.subscriptions ?? [];
+  if (subs.length === 0) return { registered: 0 };
+
+  const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  try {
+    for (const sub of subs) {
+      const resolved = resolveSubscription(sub, manifest.id, modulePath);
+      bus.subscribe(resolved);
+    }
+    return { registered: subs.length };
+  } finally {
+    bus.close();
+  }
+}
+
+/**
+ * Tear down every bus subscription that belongs to this module. Looks
+ * up rows by name prefix `<module-id>.` rather than rereading the
+ * old manifest, so a stale subscription left behind by a manifest
+ * change still gets cleaned up.
+ *
+ * Best-effort: if the bus DB doesn't exist (never opened), returns 0.
+ */
+export function unregisterModuleSubscriptions(moduleId: string): {
+  unregistered: number;
+} {
+  const bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+  try {
+    const likePattern = `${moduleId}.%`;
+    const rows = bus.db
+      .query<{ name: string }, [string]>('SELECT name FROM subscribers WHERE name LIKE ?')
+      .all(likePattern);
+    for (const row of rows) {
+      bus.unsubscribe(row.name);
+    }
+    return { unregistered: rows.length };
+  } finally {
+    bus.close();
+  }
+}
+
+function scopedName(moduleId: string, subName: string): string {
+  return `${moduleId}.${subName}`;
+}
+
+function substituteSelf(pattern: string, moduleId: string): string {
+  // `$self` matches when followed by a dot or end-of-string, so a
+  // pattern like `deploy.$self.foo` substitutes correctly without
+  // confusing `$selfish` if anyone wrote that. (No real reason they
+  // would, but be precise.)
+  return pattern.replace(/\$self(?=\.|$)/g, moduleId);
+}
+
+function substituteModulePath(handler: string, modulePath: string): string {
+  return handler.replace(/\$\{MODULE_PATH\}/g, modulePath);
+}

package/src/templates/generator.ts

@@ -491,9 +491,6 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
       }
     }
   } else {
-    // Module doesn't require infrastructure provisioning (e.g., VPS-based modules)
-    // Skip infrastructure selection
-    log.info('Skipping infrastructure selection (no requires.machine specified)');
     infrastructureSelection = undefined;
   }
 
@@ -525,12 +522,12 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
       if (!allocation) {
         // First generation - allocate VMID and IP
         allocation = await allocateForModule(moduleId, zone, db, db.$client);
-        log.info(
+        log.success(
           `Allocated VMID ${allocation.vmid} and IP ${allocation.containerIp} for ${moduleId}`,
         );
       } else {
         // Reuse existing allocation
-        log.info(
+        log.success(
           `Using existing allocation: VMID ${allocation.vmid}, IP ${allocation.containerIp}`,
         );
       }
@@ -615,7 +612,7 @@ export async function generateTemplates(options: GenerateOptions): Promise<Gener
           .run();
       }
 
-      log.info(
+      log.success(
         `Infrastructure properties resolved from service: target_node=${providerConfig.default_target_node}`,
       );
     }

package/src/variables/declarative-derivation.test.ts

@@ -940,11 +940,13 @@ describe('applyDeclarativeDerivations', () => {
     });
   });
 
-  describe('$self: directly in derive_from', () => {
-    // $self: in derive_from is a manifest authoring error — substituteVariables
-    // does not handle $self:, so it passes through all resolution passes unchanged.
-    // The hasUnresolved check must prevent it from poisoning selfConfig.
-    test('does not set selfConfig when derive_from contains $self: directly', () => {
+  describe('$self: in derive_from', () => {
+    // $self: is the canonical reference syntax in capability data blocks
+    // (e.g. authentik's `data.auth_url: $self:auth_url`), so it must
+    // resolve in derive_from too — otherwise capability-sourced variables
+    // that derive from another self variable can't be persisted.
+    // Equivalent to the {var} syntax; reads from selfConfig.
+    test('resolves $self: against selfConfig like {var}', () => {
       const manifest: ModuleManifest = {
         celilo_contract: '1.0',
         id: 'test-module',
@@ -959,7 +961,7 @@ describe('applyDeclarativeDerivations', () => {
               type: 'string',
               required: false,
               source: 'user',
-              derive_from: '$self:hostname', // Wrong syntax — $self: is not supported in derive_from
+              derive_from: '$self:hostname',
             },
           ],
           imports: [],
@@ -977,8 +979,91 @@ describe('applyDeclarativeDerivations', () => {
 
       applyDeclarativeDerivations(manifest, context);
 
-      // $self: passes through unresolved; must not poison selfConfig
-      expect(context.selfConfig.hostname_copy).toBeUndefined();
+      expect(context.selfConfig.hostname_copy).toBe('my-host');
+    });
+
+    test('resolves $self: inside string interpolation (authentik auth_url shape)', () => {
+      // Mirrors the authentik manifest pattern that motivated the fix:
+      // auth_url derives from "https://auth.$self:domain" where domain
+      // is another self-owned variable set by the user.
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'authentik',
+        name: 'Authentik',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'domain',
+              type: 'string',
+              required: true,
+              source: 'user',
+            },
+            {
+              name: 'auth_url',
+              type: 'string',
+              required: false,
+              source: 'capability',
+              derive_from: 'https://auth.$self:domain',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'authentik',
+        selfConfig: { domain: 'iamtheinternet.org' },
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.auth_url).toBe('https://auth.iamtheinternet.org');
+    });
+
+    test('throws when $self: references an undeclared variable', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test',
+        name: 'Test',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'derived',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '$self:nonexistent',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      // Optional variable + missing dep → derivation fails silently per
+      // applyDeclarativeDerivations' optional-variable rule. The error
+      // is thrown from substituteVariables but caught by the optional
+      // branch in applyDeclarativeDerivations, leaving selfConfig clean.
+      applyDeclarativeDerivations(manifest, context);
+      expect(context.selfConfig.derived).toBeUndefined();
     });
   });
 

package/src/variables/declarative-derivation.ts

@@ -65,6 +65,21 @@ function substituteVariables(
     return value;
   });
 
+  // Replace $self:key patterns (both $self:key and ${self:key} forms).
+  // Same lookup target as the {var} syntax below — both read selfConfig —
+  // but $self: is the form that appears in user-authored manifests and
+  // capability data blocks, so it must resolve here too. Without this,
+  // a `derive_from: "https://auth.$self:domain"` stays literally
+  // unresolved and the defensive guard in applyDeclarativeDerivations
+  // refuses to store it, breaking downstream capability consumers.
+  result = result.replace(/\$\{?self:([a-zA-Z0-9_]+)\}?/g, (_match, key) => {
+    const value = context.selfConfig[key];
+    if (value === undefined) {
+      throw new Error(`Missing self variable: ${key} (required by variable '${variableName}')`);
+    }
+    return value;
+  });
+
   // Replace {variable_name} patterns
   result = result.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, varName) => {
     const value = context.selfConfig[varName];