@celilo/cli 0.3.30 → 0.4.0-alpha.1

package/src/cli/commands/machine-add.ts

@@ -7,14 +7,22 @@ import { existsSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getDb } from '../../db/client';
+import type { NetworkZone } from '../../db/schema';
 import {
   detectMachineInfo,
+  detectMachineInfoLocal,
   detectNetworkInterfaces,
+  detectNetworkInterfacesLocal,
   testSshConnection,
 } from '../../services/machine-detector';
 import { addMachine, getMachineByIp } from '../../services/machine-pool';
 import { loadExistingConfiguration } from '../../services/system-init';
 import { detectZoneFromIp } from '../../services/zone-detector';
+import type {
+  DetectedMachineInfo,
+  MachineRole,
+  NetworkInterface,
+} from '../../types/infrastructure';
 import { celiloIntro, celiloOutro, promptText } from '../prompts';
 import type { CommandResult } from '../types';
 import { validateIpAddress, validateRequired } from '../validators';
@@ -95,7 +103,6 @@ export async function handleMachineAdd(
     // Hybrid mode: use flags for what's provided, prompt for what's missing
     let ipAddress: string;
     let sshUser: string;
-    let sshKeyPath: string;
 
     // IP address: from positional arg, --ip flag, or prompt
     if (args[0] && /^\d+\.\d+\.\d+\.\d+$/.test(args[0])) {
@@ -118,8 +125,21 @@ export async function handleMachineAdd(
       };
     }
 
-    // SSH user: from flag, default to 'root', or prompt
-    if (typeof flags['ssh-user'] === 'string') {
+    // The local management box (127.0.0.1, or explicit --local) deploys
+    // over Ansible's local connection — no SSH, no key, no connectivity
+    // test. Determine this BEFORE the SSH-user step so the local path
+    // never prompts (it would hang a non-interactive bootstrap postinst).
+    const isLocal = ipAddress === '127.0.0.1' || flags.local === true;
+    // An explicit --zone overrides inference (needed for the local box,
+    // whose 127.0.0.1 matches no zone subnet, and useful before a firewall
+    // has provided the target zone).
+    const zoneOverride = typeof flags.zone === 'string' ? (flags.zone as NetworkZone) : undefined;
+
+    // SSH user: irrelevant for a local machine (local connection); else
+    // from flag, default to 'root', or prompt.
+    if (isLocal) {
+      sshUser = 'root';
+    } else if (typeof flags['ssh-user'] === 'string') {
       sshUser = flags['ssh-user'];
     } else {
       sshUser = await promptText({
@@ -130,76 +150,100 @@ export async function handleMachineAdd(
       });
     }
 
-    // SSH key: from flag, auto-detect, or error
-    if (typeof flags['ssh-key-file'] === 'string') {
-      sshKeyPath = flags['ssh-key-file'];
-      const expandedPath = sshKeyPath.replace(/^~/, process.env.HOME || '~');
-      if (!existsSync(expandedPath)) {
-        return { success: false, error: `SSH key file not found: ${expandedPath}` };
-      }
+    let detectedInfo: DetectedMachineInfo;
+    let zone: NetworkZone;
+    let interfaces: NetworkInterface[];
+    let role: MachineRole;
+    let sshKey: string;
+
+    if (isLocal) {
+      console.log('\nLocal machine — detecting locally (no SSH)...');
+      detectedInfo = await detectMachineInfoLocal();
+      const net = await detectNetworkInterfacesLocal();
+      interfaces = net.interfaces;
+      role = net.role;
+      // The box you're installing on is, by definition, on the internal LAN.
+      zone = zoneOverride ?? 'internal';
+      sshKey = ''; // local connection — no key needed
+      console.log(
+        `✓ Local: ${detectedInfo.hostname} — ${detectedInfo.hardware.cpu_cores} cores, ` +
+          `${detectedInfo.hardware.memory_mb} MB, ${detectedInfo.hardware.disk_gb} GB (zone ${zone}, connection local)\n`,
+      );
     } else {
-      // Auto-detect SSH key from system config
-      const detectedKeyPath = findSshPrivateKey();
-      if (!detectedKeyPath) {
-        return {
-          success: false,
-          error:
-            'Cannot find SSH private key.\n\n' +
-            'The ssh.public_key system config is set, but no matching private key was found in ~/.ssh/\n\n' +
-            'Specify manually with: --ssh-key-file ~/.ssh/id_ed25519',
-        };
+      // SSH key: from flag, auto-detect, or error
+      let sshKeyPath: string;
+      if (typeof flags['ssh-key-file'] === 'string') {
+        sshKeyPath = flags['ssh-key-file'];
+        const expandedPath = sshKeyPath.replace(/^~/, process.env.HOME || '~');
+        if (!existsSync(expandedPath)) {
+          return { success: false, error: `SSH key file not found: ${expandedPath}` };
+        }
+      } else {
+        // Auto-detect SSH key from system config
+        const detectedKeyPath = findSshPrivateKey();
+        if (!detectedKeyPath) {
+          return {
+            success: false,
+            error:
+              'Cannot find SSH private key.\n\n' +
+              'The ssh.public_key system config is set, but no matching private key was found in ~/.ssh/\n\n' +
+              'Specify manually with: --ssh-key-file ~/.ssh/id_ed25519',
+          };
+        }
+        sshKeyPath = detectedKeyPath;
+        console.log(`Using SSH key: ${sshKeyPath}`);
       }
-      sshKeyPath = detectedKeyPath;
-      console.log(`Using SSH key: ${sshKeyPath}`);
-    }
 
-    // Expand tilde in path
-    const expandedKeyPath = sshKeyPath.replace(/^~/, process.env.HOME || '~');
+      // Expand tilde in path
+      const expandedKeyPath = sshKeyPath.replace(/^~/, process.env.HOME || '~');
 
-    // Read SSH key content
-    const sshKey = readFileSync(expandedKeyPath, 'utf8');
+      // Read SSH key content
+      sshKey = readFileSync(expandedKeyPath, 'utf8');
 
-    console.log('\nTesting SSH connection...');
+      console.log('\nTesting SSH connection...');
 
-    // Test SSH connectivity
-    const canConnect = await testSshConnection(ipAddress, sshUser, expandedKeyPath);
-    if (!canConnect) {
-      return {
-        success: false,
-        error: `Cannot connect to ${sshUser}@${ipAddress} with provided SSH key`,
-      };
-    }
+      // Test SSH connectivity
+      const canConnect = await testSshConnection(ipAddress, sshUser, expandedKeyPath);
+      if (!canConnect) {
+        return {
+          success: false,
+          error: `Cannot connect to ${sshUser}@${ipAddress} with provided SSH key`,
+        };
+      }
 
-    console.log('✓ SSH connection successful\n');
+      console.log('✓ SSH connection successful\n');
 
-    console.log('Detecting machine information...');
+      console.log('Detecting machine information...');
 
-    // Auto-detect machine info
-    const detectedInfo = await detectMachineInfo(ipAddress, sshUser, expandedKeyPath);
+      // Auto-detect machine info
+      detectedInfo = await detectMachineInfo(ipAddress, sshUser, expandedKeyPath);
 
-    console.log('✓ Machine detected:');
-    console.log(`  Hostname: ${detectedInfo.hostname}`);
-    console.log(`  OS: ${detectedInfo.osInfo}`);
-    console.log(
-      `  CPU: ${detectedInfo.hardware.cpu_cores} cores (${detectedInfo.hardware.arch || 'unknown'})`,
-    );
-    console.log(`  Memory: ${detectedInfo.hardware.memory_mb} MB`);
-    console.log(`  Disk: ${detectedInfo.hardware.disk_gb} GB\n`);
+      console.log('✓ Machine detected:');
+      console.log(`  Hostname: ${detectedInfo.hostname}`);
+      console.log(`  OS: ${detectedInfo.osInfo}`);
+      console.log(
+        `  CPU: ${detectedInfo.hardware.cpu_cores} cores (${detectedInfo.hardware.arch || 'unknown'})`,
+      );
+      console.log(`  Memory: ${detectedInfo.hardware.memory_mb} MB`);
+      console.log(`  Disk: ${detectedInfo.hardware.disk_gb} GB\n`);
 
-    // Auto-detect zone from IP
-    console.log('Detecting network zone...');
-    const zone = await detectZoneFromIp(ipAddress);
-    console.log(`✓ Zone: ${zone}\n`);
+      // Zone: explicit override, else infer from IP.
+      console.log('Detecting network zone...');
+      zone = zoneOverride ?? (await detectZoneFromIp(ipAddress));
+      console.log(`✓ Zone: ${zone}\n`);
 
-    // Detect network interfaces and classify machine
-    console.log('Detecting network interfaces...');
-    const { interfaces, role } = await detectNetworkInterfaces(ipAddress, sshUser, expandedKeyPath);
+      // Detect network interfaces and classify machine
+      console.log('Detecting network interfaces...');
+      const net = await detectNetworkInterfaces(ipAddress, sshUser, expandedKeyPath);
+      interfaces = net.interfaces;
+      role = net.role;
 
-    console.log(`✓ Role: ${role}`);
-    for (const iface of interfaces) {
-      console.log(`  ${iface.name}: ${iface.ipAddress} (${iface.zone})`);
+      console.log(`✓ Role: ${role}`);
+      for (const iface of interfaces) {
+        console.log(`  ${iface.name}: ${iface.ipAddress} (${iface.zone})`);
+      }
+      console.log('');
     }
-    console.log('');
 
     // Add machine to pool
     const earmark = typeof flags.earmark === 'string' ? flags.earmark : undefined;

package/src/cli/commands/module-import.ts

@@ -18,14 +18,23 @@
  */
 
 import { existsSync } from 'node:fs';
-import { unlink } from 'node:fs/promises';
+import { rm, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { eq } from 'drizzle-orm';
 import { getModuleStoragePath, shortenPath } from '../../config/paths';
 import { getDb } from '../../db/client';
+import { modules } from '../../db/schema';
+import type { ModuleManifest } from '../../manifest/schema';
 import { importModule } from '../../module/import';
 import { RegistryClient } from '../../registry/client';
-import { getArg, getFlag } from '../parser';
+import {
+  checkAspectApproval,
+  computeAspectScopeHash,
+  recordAspectApproval,
+} from '../../services/aspect-approvals';
+import { getArg, getFlag, hasFlag } from '../parser';
+import { promptConfirm } from '../prompts';
 import type { CommandResult } from '../types';
 import { generateTypesForImportedModule } from './module-types';
 
@@ -46,6 +55,124 @@ Examples:
  *
  * Exposed for tests; not exported from the package.
  */
+/**
+ * Run the base-module-aspect approval flow after a module's primary
+ * import succeeds. Per v2/CELILO_BASE.md D2:
+ *
+ *   - Modules without a `base_module_aspect` block: no-op.
+ *   - Re-imports of a version that's already been approved with the
+ *     same scope: no-op (don't re-prompt).
+ *   - First-time import (or new version) with a declared aspect:
+ *     show scope, prompt unless `--accept-aspects` is passed.
+ *   - Operator declines: roll back the import (DB row + on-disk
+ *     source dir) so re-running is a clean re-do.
+ *
+ * Returns `{ approved: true, message?: string }` on success, or
+ * `{ approved: false, error: string }` on decline or non-interactive
+ * mismatch. The caller is responsible for surfacing the error.
+ */
+async function handleAspectApprovalAfterImport(args: {
+  moduleId: string;
+  targetPath: string;
+  flags: Record<string, string | boolean>;
+  db: ReturnType<typeof getDb>;
+}): Promise<{ approved: true; message?: string } | { approved: false; error: string }> {
+  const { moduleId, targetPath, flags, db } = args;
+
+  const moduleRow = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!moduleRow) {
+    // Shouldn't happen — importModule just succeeded — but fail
+    // loudly rather than silently no-op.
+    return {
+      approved: false,
+      error: `Imported module '${moduleId}' missing from DB after import.`,
+    };
+  }
+
+  const manifest = moduleRow.manifestData as ModuleManifest;
+  const aspect = manifest.base_module_aspect;
+  if (!aspect) {
+    // No aspect declared — nothing to approve.
+    return { approved: true };
+  }
+
+  const status = checkAspectApproval(moduleId, moduleRow.version, aspect, db);
+  if (status === 'approved') {
+    // Same version + same scope already approved (re-import of a
+    // previously-accepted version). Skip the prompt silently.
+    return { approved: true };
+  }
+
+  const acceptViaFlag = hasFlag(flags, 'accept-aspects');
+  const approver = process.env.USER ?? null;
+
+  if (acceptViaFlag) {
+    recordAspectApproval({
+      moduleId,
+      version: moduleRow.version,
+      scopeHash: computeAspectScopeHash(aspect),
+      approver,
+      db,
+    });
+    return {
+      approved: true,
+      message: `Base-module aspect approved via --accept-aspects (zones: ${aspect.applicable_zones.join(', ')}; triggers: ${aspect.triggers.join(', ')})`,
+    };
+  }
+
+  // Interactive prompt path. Display the scope clearly so the
+  // operator's consent is informed.
+  const scopeMsg = [
+    `Module '${moduleId}' declares a base-module aspect:`,
+    `  Ansible role: ${aspect.ansible_role}`,
+    `  Target zones: ${aspect.applicable_zones.join(', ')}`,
+    `  Triggers:     ${aspect.triggers.join(', ')}`,
+    '',
+    `This means: when this module's primary deploys (or one of the listed triggers fires),`,
+    `celilo will run the '${aspect.ansible_role}' Ansible role on every non-api_only system`,
+    'in those zones.',
+  ].join('\n');
+  // Use process.stderr.write rather than the prompt UI so the
+  // multi-line scope block is preserved verbatim — @clack/prompts
+  // mangles multi-line message arguments.
+  process.stderr.write(`\n${scopeMsg}\n\n`);
+
+  const accepted = await promptConfirm({
+    message: 'Approve this base-module aspect?',
+    initialValue: false,
+  });
+
+  if (!accepted) {
+    // Roll back the import — DB delete cascades to configs/secrets/etc.
+    // We also rm the source dir so a re-import doesn't trip on the
+    // existing files.
+    db.delete(modules).where(eq(modules.id, moduleId)).run();
+    try {
+      await rm(targetPath, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup; if rm fails the operator can clean up
+      // manually. Don't mask the original "approval declined" error.
+    }
+    return {
+      approved: false,
+      error:
+        'Aspect approval declined; import rolled back. Re-run with --accept-aspects to skip the prompt.',
+    };
+  }
+
+  recordAspectApproval({
+    moduleId,
+    version: moduleRow.version,
+    scopeHash: computeAspectScopeHash(aspect),
+    approver,
+    db,
+  });
+  return {
+    approved: true,
+    message: `Base-module aspect approved (zones: ${aspect.applicable_zones.join(', ')}; triggers: ${aspect.triggers.join(', ')})`,
+  };
+}
+
 export function classifyImportArg(arg: string): 'path' | 'name' {
   if (arg.startsWith('/') || arg.startsWith('./') || arg.startsWith('../')) return 'path';
   if (arg.startsWith('~/') || arg === '~') return 'path';
@@ -142,12 +269,23 @@ async function handleFileImport(
     };
   }
 
+  const aspectOutcome = await handleAspectApprovalAfterImport({
+    moduleId: result.moduleId,
+    targetPath: result.targetPath,
+    flags,
+    db,
+  });
+  if (!aspectOutcome.approved) {
+    return { success: false, error: aspectOutcome.error };
+  }
+
   const typesPath = await generateTypesForImportedModule(result.targetPath);
   const typesMessage = typesPath ? `\nGenerated types: ${shortenPath(typesPath)}` : '';
+  const aspectMessage = aspectOutcome.message ? `\n${aspectOutcome.message}` : '';
 
   return {
     success: true,
-    message: `Successfully imported module: ${result.moduleId}\nFiles copied to: ${shortenPath(result.targetPath)}${typesMessage}`,
+    message: `Successfully imported module: ${result.moduleId}\nFiles copied to: ${shortenPath(result.targetPath)}${typesMessage}${aspectMessage}`,
     data: {
       moduleId: result.moduleId,
       targetPath: result.targetPath,
@@ -212,13 +350,24 @@ async function handlePublicRegistryImport(
       return { success: false, error: result.error, details: result.details };
     }
 
+    const aspectOutcome = await handleAspectApprovalAfterImport({
+      moduleId: result.moduleId,
+      targetPath: result.targetPath,
+      flags,
+      db,
+    });
+    if (!aspectOutcome.approved) {
+      return { success: false, error: aspectOutcome.error };
+    }
+    const aspectMessage = aspectOutcome.message ? `\n${aspectOutcome.message}` : '';
+
     // Type-generation is a developer-mode aid for module AUTHORS editing
     // hook scripts in the source tree. Registry installs are black-box
     // dependencies — the operator isn't editing them — so skipping the
     // type-gen pass saves the work and keeps the install output clean.
     return {
       success: true,
-      message: `Imported ${result.moduleId}@${latest.vers}\nFiles: ${shortenPath(result.targetPath)}`,
+      message: `Imported ${result.moduleId}@${latest.vers}\nFiles: ${shortenPath(result.targetPath)}${aspectMessage}`,
       data: {
         moduleId: result.moduleId,
         version: latest.vers,

package/src/cli/commands/module-remove.ts

@@ -16,7 +16,13 @@ import { runNamedHook } from '../../hooks/run-named-hook';
 import { deallocateForModule } from '../../ipam/auto-allocator';
 import { ModuleManifestSchema } from '../../manifest/schema';
 import { executeBuildWithProgress } from '../../services/build-stream';
+import {
+  emitUninstallCompleted,
+  emitUninstallFailed,
+  emitUninstallStarted,
+} from '../../services/celilo-events';
 import { getContainerService, getServiceCredentials } from '../../services/container-service';
+import { completeOperation, failOperation, startOperation } from '../../services/module-operations';
 import { getArg, hasFlag, validateRequiredArgs } from '../parser';
 import { log, promptConfirm } from '../prompts';
 import type { CommandResult } from '../types';
@@ -94,6 +100,57 @@ export async function handleModuleRemove(
     }
   }
 
+  // Pre-flight passed; we're committed to attempting the uninstall. Start
+  // operation tracking + emit lifecycle events from here on so backups and
+  // restores see the uninstall as in-flight and downstream subscribers can
+  // react.
+  const startedAt = Date.now();
+  const opId = startOperation(moduleId, 'uninstall');
+  emitUninstallStarted({ module: moduleId, startedAt });
+
+  let result: CommandResult;
+  try {
+    result = await performModuleRemove(moduleId, module, force, db);
+  } catch (err) {
+    failOperation(opId, err);
+    emitUninstallFailed({
+      module: moduleId,
+      startedAt,
+      durationMs: Date.now() - startedAt,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  }
+
+  const durationMs = Date.now() - startedAt;
+  if (result.success) {
+    completeOperation(opId);
+    emitUninstallCompleted({ module: moduleId, startedAt, durationMs });
+  } else {
+    failOperation(opId, result.error ?? 'unknown error');
+    emitUninstallFailed({
+      module: moduleId,
+      startedAt,
+      durationMs,
+      error: result.error ?? 'unknown error',
+    });
+  }
+  return result;
+}
+
+/**
+ * The actual uninstall work — on_uninstall hook, terraform destroy, DNS
+ * deregister, IPAM deallocate, subscription cleanup, DB delete. Split out
+ * so `handleModuleRemove` can wrap the call with operation tracking +
+ * lifecycle event emission. Pre-conditions (module exists, no dependents)
+ * are validated by the caller.
+ */
+async function performModuleRemove(
+  moduleId: string,
+  module: typeof modules.$inferSelect,
+  force: boolean,
+  db: ReturnType<typeof getDb>,
+): Promise<CommandResult> {
   // Run on_uninstall hook (if defined) BEFORE terraform destroy. Hooks
   // typically need the module's runtime to still be up so they can talk
   // to remote services — e.g. caddy's teardown SSHes the caddy host to
@@ -221,23 +278,35 @@ export async function handleModuleRemove(
     log.success('Infrastructure destroyed');
   }
 
-  // Remove DNS record (if dns_internal is available). Wrapped in a
-  // FuelGauge with a gauge logger so the dns_internal capability calls
-  // inside (`deleteRecord`, etc.) nest as sub-events rather than
-  // leaking to scrollback as unindented top-level lines via
-  // cli/prompts.log.instantEvent (which pops every pending step).
-  const dnsGauge = new FuelGauge(`Removing ${moduleId} from DNS`, {
-    skipAnimation: !process.stdout.isTTY,
-  });
-  dnsGauge.start();
-  try {
-    const dnsLogger = createGaugeLogger(dnsGauge, moduleId, 'auto_deregister_dns');
-    const { autoDeregisterDns } = await import('../../services/dns-auto-register');
-    await autoDeregisterDns(moduleId, db, dnsLogger);
-    dnsGauge.stop(true);
-  } catch {
-    dnsGauge.stop(false);
-    // Non-fatal -- continue with removal
+  // Capture the deployed systems BEFORE the module_systems rows are deleted
+  // (cascade on module removal) so the system.destroyed events (D5/D6) carry
+  // the host/IP each subscriber needs to deregister. One event per system.
+  const removedSystems = await (async () => {
+    try {
+      const { getModuleSystems } = await import('../../services/deployed-systems');
+      return getModuleSystems(moduleId, db);
+    } catch {
+      return [];
+    }
+  })();
+
+  // Announce teardown on the bus (D5, v2/EVENT_DRIVEN_HOOK_SUBSCRIPTIONS.md). A
+  // dns_internal provider's system.destroyed.* subscription runs its
+  // on_system_event hook (op: deregister) to remove each host's records.
+  if (removedSystems.length > 0) {
+    try {
+      const { emitSystemDestroyed } = await import('../../services/celilo-events');
+      for (const sys of removedSystems) {
+        emitSystemDestroyed({
+          module: moduleId,
+          hostname: sys.hostname,
+          targetIp: sys.ipv4_address,
+        });
+      }
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      log.warn(`Failed to emit system.destroyed for ${moduleId}: ${msg}`);
+    }
   }
 
   // Deallocate IPAM resources (if any)

package/src/cli/commands/module-status.ts

@@ -88,8 +88,12 @@ export async function handleModuleStatus(args: string[]): Promise<CommandResult>
   if (configs.length > 0) {
     const configLines = ['Configuration:'];
     for (const config of configs) {
-      const value = config.valueJson ? JSON.stringify(JSON.parse(config.valueJson)) : config.value;
-      configLines.push(`  ${config.key}: ${value}`);
+      // `value` is the human-readable display form (e.g. "test-host"
+      // for a string, "2222" for a number, JSON-stringified for
+      // complex types) — populated by upsertModuleConfig alongside
+      // the canonical valueJson. Using it here keeps the status
+      // output free of JSON-quote noise around primitives.
+      configLines.push(`  ${config.key}: ${config.value}`);
     }
     sections.push(configLines.join('\n'));
   } else {