@celilo/cli 0.22.0 → 0.24.0

package/src/cli/index.ts

@@ -4,6 +4,7 @@
  * Orchestration function (Rule 10.1) - routes commands to handlers
  */
 
+import { log as uiLog } from '@celilo/cli-display';
 import {
   COMMANDS,
   type CommandDef,
@@ -11,7 +12,6 @@ import {
   resolveRemote,
   runRemoteClient,
 } from '@celilo/core';
-import * as p from '@clack/prompts';
 import { CLIServerRequestSchema, parseJsonWithValidation } from '../validation/schemas';
 import {
   handleApiAuthorizedKeys,
@@ -48,6 +48,7 @@ import {
   handleEventsTail,
   handleEventsUninstallDaemon,
 } from './commands/events';
+import { handleFirewallInterfaceList } from './commands/firewall-interface-list';
 import { handleHookRun } from './commands/hook-run';
 import {
   handleIpamIpListReservations,
@@ -68,7 +69,11 @@ import { moduleAudit } from './commands/module-audit';
 import { handleModuleBuild } from './commands/module-build';
 import { handleModuleChangeset } from './commands/module-changeset';
 import { handleModuleCheck } from './commands/module-check';
-import { handleModuleConfigGet, handleModuleConfigSet } from './commands/module-config';
+import {
+  handleModuleConfigGet,
+  handleModuleConfigSet,
+  handleModuleConfigUnset,
+} from './commands/module-config';
 import { handleModuleDeploy } from './commands/module-deploy';
 import { handleModuleGenerate } from './commands/module-generate';
 import { handleModuleHealth } from './commands/module-health';
@@ -77,6 +82,7 @@ import { handleModuleJournal } from './commands/module-journal';
 import { handleModuleList } from './commands/module-list';
 import { handleModuleLogs } from './commands/module-logs';
 import { handleModuleOperations } from './commands/module-operations';
+import { handleModulePause, handleModuleUnpause } from './commands/module-pause';
 import { handleModulePublish } from './commands/module-publish';
 import { handleModuleRemove } from './commands/module-remove';
 import { handleModuleSearch } from './commands/module-search';
@@ -203,6 +209,7 @@ Commands:
   storage                  Manage backup storage destinations
   backup                   Create and manage backups
   restore                  Restore a celilo-mgmt backup from a local file (fresh-bootstrap path)
+  firewall                 Inspect a firewall's interfaces (classification, on demand)
   machine                  Manage machine pool (bring-your-own-hardware)
   system                   Manage system configuration
   apt-upgrade              Upgrade the deb-installed celilo packages + apply migrations
@@ -578,11 +585,26 @@ Subcommands:
 
   remove <id>                          Remove a module and all its data
 
+  pause <id>                           Quiesce a module without uninstalling it (container keeps running)
+    Options:
+      --cascade                        Also pause every dependent module, consumers first
+      --stop-infra                     Also stop the module's container or service
+      --reason <text>                  Why the pause was taken, recorded on the module
+      --dry-run                        Print the ordered plan and change nothing
+      --yes                            Skip the cascade confirmation
+
+  unpause <id>                         Redeploy a paused module, rebinding it to current providers
+    Options:
+      --cascade                        Also unpause every dependent module, providers first
+      --dry-run                        Print the ordered plan and change nothing
+      --yes                            Skip the cascade confirmation
+
   verify <id>                          Verify module integrity (signature + checksums)
                                          (legacy alias: 'audit')
 
   config set <id> <key> <value>        Set module configuration value
   config get <id> [key]                Get module configuration value(s)
+  config unset <id> <key>              Remove an override; follow the manifest again
 
   secret set <id> <key> <value>        Set encrypted module secret
   secret list <id>                     List module secrets
@@ -649,11 +671,19 @@ Examples:
   celilo module publish ./modules/*                # publish every module in a dir
   celilo module list
   celilo module remove homebridge
+
+  # Swap a capability provider (e.g. a replaced edge router):
+  celilo module pause --cascade greenwave --reason "ISP swapped the router"
+  celilo module remove greenwave
+  celilo module import axon && celilo module deploy axon
+  celilo module unpause --cascade axon
   celilo module verify homebridge
   celilo module config set homebridge hostname myhost
   celilo module config set homebridge container_ip "192.168.0.110/24"
   celilo module config get homebridge
   celilo module config get homebridge hostname
+  celilo module config set caddy backup_schedule 6h
+  celilo module config unset caddy backup_schedule
   celilo module show-config homebridge
   celilo module show-zone homebridge
   celilo module build caddy
@@ -896,6 +926,28 @@ Related Commands:
 /**
  * Display machine command help
  */
+function displayFirewallHelp(): CommandResult {
+  console.log(`
+celilo firewall — inspect a firewall's interfaces
+
+Usage:
+  celilo firewall interface list [<hostname>]
+
+  Shows how celilo classifies every interface on a firewall: the zone it
+  matched, the external edge, or ALIEN when nothing accounts for it.
+
+  Read-only. It reads the recorded interface table and the declared zone
+  subnets and classifies in memory — it never touches the box, so it is safe
+  to run against a firewall whose converge is currently refusing.
+
+  With no hostname, every machine celilo classifies as a router is shown.
+
+  An interface celilo cannot attribute is resolved by DECLARING it:
+    celilo system config set network.<zone>.subnet <cidr>
+`);
+  return { success: true, message: 'firewall help' };
+}
+
 function displayMachineHelp(): CommandResult {
   const helpText = `
 Celilo - Machine Pool Management
@@ -1397,8 +1449,8 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     const { main: runPublish } = await import('./commands/publish');
     await runPublish(publishArgv);
     // runPublish handles its own console output (multi-phase, multi-line);
-    // returning an empty success message tells the outer CLI loop to skip
-    // the clack outro and exit 0 cleanly. Any failure inside runPublish
+    // returning an empty success message tells the outer CLI loop to write
+    // nothing more and exit 0 cleanly. Any failure inside runPublish
     // calls process.exit() directly and never returns here.
     return { success: true, message: '' };
   }
@@ -1499,6 +1551,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleModuleHealth(parsed.args, parsed.flags);
       case 'operations':
         return handleModuleOperations(parsed.args, parsed.flags);
+      case 'pause':
+        return handleModulePause(parsed.args, parsed.flags);
+      case 'unpause':
+        return handleModuleUnpause(parsed.args, parsed.flags);
       case 'remove':
         return handleModuleRemove(parsed.args, parsed.flags);
       case 'update':
@@ -1519,7 +1575,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         if (!configSubcommand) {
           return {
             success: false,
-            error: 'Config action required (set or get)\n\nRun "celilo help" for usage',
+            error: 'Config action required (set, get or unset)\n\nRun "celilo help" for usage',
           };
         }
         const configArgs = parsed.args.slice(1);
@@ -1529,6 +1585,9 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         if (configSubcommand === 'get') {
           return handleModuleConfigGet(configArgs);
         }
+        if (configSubcommand === 'unset') {
+          return handleModuleConfigUnset(configArgs);
+        }
         return {
           success: false,
           error: `Unknown config action: ${configSubcommand}`,
@@ -2025,6 +2084,29 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     };
   }
 
+  if (parsed.command === 'firewall') {
+    if (parsed.flags.help || parsed.flags.h || !parsed.subcommand) {
+      return displayFirewallHelp();
+    }
+    if (parsed.subcommand === 'interface') {
+      // `interface` is a group, not a leaf: `list` is its only verb today.
+      // `acknowledge` and `enforce` were both deleted in the design amendments —
+      // there is no policy toggle and no per-interface escape hatch.
+      const verb = parsed.args[0];
+      if (!verb || verb === 'list') {
+        return handleFirewallInterfaceList(parsed.args.slice(1), parsed.flags);
+      }
+      return {
+        success: false,
+        error: `Unknown firewall interface subcommand: ${verb}\n\nRun "celilo firewall --help" for usage`,
+      };
+    }
+    return {
+      success: false,
+      error: `Unknown firewall subcommand: ${parsed.subcommand}\n\nRun "celilo firewall --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'machine') {
     // Handle machine --help
     if (parsed.flags.help || parsed.flags.h) {
@@ -2465,31 +2547,31 @@ export async function main(): Promise<void> {
         process.exit(0);
       }
 
-      // Script-friendly commands bypass clack and write directly to stdout
-      if (result.rawOutput) {
-        process.stdout.write(`${result.message}\n`);
-        process.exit(0);
-      }
-
       // Empty message → command already emitted its own output (e.g. via
-      // ProgressDisplay) and doesn't want a clack outro on top.
+      // ProgressDisplay) and doesn't want anything written on top.
       if (!result.message) {
         process.exit(0);
       }
 
-      // Handle multi-line messages: split on section boundaries (\n\n) so
-      // lines within a section are logged together (avoiding clack's per-call spacing).
-      const sections = result.message.split('\n\n');
-      p.log.success(sections[0]);
-      for (let i = 1; i < sections.length; i++) {
-        if (sections[i].trim()) {
-          p.log.message(sections[i]);
-        }
-      }
+      // A successful command's message IS its result, so it goes to stdout
+      // verbatim — no glyph, no `│  ` prefix, no re-wrapping on `\n\n`.
+      //
+      // `rawOutput` no longer selects a different destination; it is kept
+      // because it still records which commands are contractually
+      // machine-readable, and because JSON payloads must never acquire a
+      // decoration if this branch ever grows one again (celilo#698).
+      //
+      // The old path split the message on `\n\n` and fed each section to the
+      // clack renderer, which prefixed every line. That is what made
+      // `line.startsWith('<module-id> ')` over `celilo module list` match
+      // nothing — read in celilo#695 as a missing module rather than as a
+      // parse failure, at the cost of a full e2e run.
+      process.stdout.write(`${result.message}\n`);
       process.exit(0);
     }
 
-    p.log.error(`Error: ${result.error}`);
+    // Diagnostics go to stderr so a caller can separate them from the result.
+    uiLog.error(`Error: ${result.error}`);
     if (result.details) {
       console.error('Details:', result.details);
     }

package/src/cli/json-output.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Recurrence gate for celilo#698 — a command that emits JSON must emit JSON
+ * that parses, with no preprocessing.
+ *
+ * `cli/index.ts` already implements the rule: a `CommandResult` carrying
+ * `rawOutput: true` is written straight to stdout, while everything else goes
+ * through the decorating renderer that prefixes each line with `│  ` and wraps
+ * it in ANSI colour. A JSON payload that forgets the flag therefore reaches
+ * stdout as something no `JSON.parse` will accept — and the workaround
+ * (`| sed 's/\x1b\[[0-9;]*m//g'`) got written into CLAUDE.md instead of the fix.
+ *
+ * Two gates here, deliberately different in kind:
+ *
+ *  1. `emits parseable JSON` — spawns the REAL CLI and parses its raw stdout.
+ *     This is the honest end-to-end check, and it is the one that fails today
+ *     without the fix. It cannot use `CLIContext`: that harness drives the CLI
+ *     in `CLI_SERVER_MODE`, which returns `result.message` over a protocol and
+ *     never exercises the stdout renderer where the bug lives.
+ *
+ *  2. `every JSON CommandResult sets rawOutput` — a static scan, so a NEW
+ *     command that forgets the flag fails even though nobody added it to the
+ *     table above.
+ *
+ * Lives under `src/` rather than `test-integration/` for one blunt reason:
+ * `test-integration/` is run by no CI workflow (the `validate` job runs
+ * `test:unit`, which is `bun test src/`), so a gate placed there would never
+ * have failed anything. See celilo#703.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { type IntegrationTestContext, setupIntegrationTest } from '@/test-utils/integration';
+
+const COMMANDS_DIR = join(import.meta.dir, 'commands');
+
+/**
+ * Commands whose stdout is a JSON document. Each is spawned as a real process
+ * and its stdout handed to `JSON.parse` verbatim.
+ *
+ * `events` verbs share one `jsonResult()` helper, so a few representatives
+ * cover all 16 of its call sites; the rest are the distinct `--json` surfaces.
+ */
+const JSON_COMMANDS = [
+  'events status',
+  'events tail --limit 5',
+  'events list-subscribers',
+  'module list --json',
+  'module health --json',
+  'system audit --json',
+  'alerts list --json',
+  'commands --json',
+] as const;
+
+describe('celilo#698 — JSON commands emit parseable JSON', () => {
+  let ctx: IntegrationTestContext;
+
+  beforeAll(async () => {
+    ctx = await setupIntegrationTest();
+  });
+
+  afterAll(async () => {
+    await ctx.cleanup();
+  });
+
+  for (const command of JSON_COMMANDS) {
+    test(`celilo ${command} emits parseable JSON`, () => {
+      const result = spawnSync('bun', ['run', 'src/cli/index.ts', ...command.split(' ')], {
+        encoding: 'utf8',
+        env: {
+          ...process.env,
+          CELILO_DB_PATH: ctx.dbPath,
+          CELILO_DATA_DIR: ctx.dataDir,
+          CELILO_SUPPRESS_DEPRECATION: '1',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 60_000,
+      });
+
+      expect(
+        result.status,
+        `celilo ${command} exited ${result.status}\nstderr: ${result.stderr}`,
+      ).toBe(0);
+
+      // Verbatim: no ANSI stripping, no prefix removal, no line filtering.
+      // If this throws, the payload went through the decorating renderer.
+      expect(() => JSON.parse(result.stdout)).not.toThrow();
+    });
+  }
+});
+
+/**
+ * Walk from the index of a `{` to the index just past its matching `}`,
+ * skipping over string literals so a brace inside a string doesn't unbalance
+ * the count.
+ */
+function objectEnd(source: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < source.length; i++) {
+    const char = source[i];
+    if (char === '{') {
+      depth++;
+    } else if (char === '}') {
+      depth--;
+      if (depth === 0) return i + 1;
+    } else if (char === '"' || char === "'" || char === '`') {
+      const quote = char;
+      i++;
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === '\\') i++;
+        i++;
+      }
+    }
+  }
+  return -1;
+}
+
+/** Index of the `{` opening the object literal that encloses `index`. */
+function enclosingObjectStart(source: string, index: number): number {
+  let depth = 0;
+  for (let i = index; i >= 0; i--) {
+    if (source[i] === '}') {
+      depth++;
+    } else if (source[i] === '{') {
+      if (depth === 0) return i;
+      depth--;
+    }
+  }
+  return -1;
+}
+
+describe('celilo#698 recurrence gate — every JSON CommandResult sets rawOutput', () => {
+  const files = readdirSync(COMMANDS_DIR).filter(
+    (f) => f.endsWith('.ts') && !f.endsWith('.test.ts'),
+  );
+
+  test('command files exist to scan', () => {
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  for (const file of files) {
+    test(`${file} sets rawOutput on every JSON message`, () => {
+      const source = readFileSync(join(COMMANDS_DIR, file), 'utf8');
+      const pattern = /\bmessage:\s*JSON\.stringify\b/g;
+      let match: RegExpExecArray | null = pattern.exec(source);
+
+      while (match !== null) {
+        const open = enclosingObjectStart(source, match.index);
+        const literal = open < 0 ? '' : source.slice(open, objectEnd(source, open));
+        const line = source.slice(0, match.index).split('\n').length;
+
+        expect(
+          /\brawOutput\b/.test(literal),
+          `${file}:${line} returns a JSON message without rawOutput: true. Without the flag the payload goes through the decorating renderer and no longer parses. Add \`rawOutput: true\` to the same result object.`,
+        ).toBe(true);
+
+        match = pattern.exec(source);
+      }
+    });
+  }
+});

package/src/cli/prompts.ts

@@ -1,10 +1,32 @@
 /**
  * Prompt Utilities
- * Beautiful interactive prompts using @clack/prompts
+ *
+ * A thin celilo-facing wrapper over the prompt/message primitives in
+ * `@celilo/cli-display`. Roughly 160 `log.*` call sites and every legacy
+ * direct prompt route through this module, which is what made replacing
+ * `@clack/prompts` a one-file change rather than a 160-file one (celilo#699).
+ *
+ * NOTE: new interactive decisions must NOT be added here. They belong on the
+ * event-bus interview (`services/bus-interview`), which a headless responder
+ * can answer; `test-integration/cli/headless-drivable.test.ts` enforces that
+ * no command reaches for these directly. What remains is the terminal renderer
+ * for a bus question, plus the legacy prompts that predate the interview.
  */
 
-import { getActiveDisplay, setActiveDisplay } from '@celilo/cli-display';
-import * as p from '@clack/prompts';
+import {
+  CANCEL,
+  cancel,
+  getActiveDisplay,
+  intro,
+  isCancel,
+  log,
+  note,
+  outro,
+  password,
+  setActiveDisplay,
+  text,
+  confirm as uiConfirm,
+} from '@celilo/cli-display';
 
 // Re-export so existing imports from `../cli/prompts` keep working.
 // The singleton itself lives in @celilo/cli-display so module code
@@ -12,25 +34,26 @@ import * as p from '@clack/prompts';
 // it via @celilo/capabilities's re-export.
 export { getActiveDisplay, setActiveDisplay };
 
+export { log };
+
 /**
  * Interactive prompt wrapper with celilo branding
  */
 export async function celiloIntro(title: string): Promise<void> {
-  p.intro(title);
+  intro(title);
 }
 
 export async function celiloOutro(message: string): Promise<void> {
-  p.outro(message);
+  outro(message);
 }
 
 /**
- * Prompt for text input with validation and help text
+ * Prompt for text input with validation and help text.
  *
- * Displays:
- * - Question/prompt message
- * - Input field with placeholder
- * - Help text below (muted) - like @clack/prompts screenshot
- * - Validation errors inline
+ * Displays the question, an input field with the placeholder, and any
+ * validation error inline. A cancel (Ctrl-C / Escape) exits the process, which
+ * is the behaviour every existing caller is written against: they treat the
+ * return as an unconditional `string`.
  */
 export async function promptText(options: {
   message: string;
@@ -38,19 +61,14 @@ export async function promptText(options: {
   placeholder?: string;
   validate?: (value: string | undefined) => string | Error | undefined;
 }): Promise<string> {
-  const result = await p.text({
-    message: options.message,
-    defaultValue: options.defaultValue,
-    placeholder: options.placeholder,
-    validate: options.validate,
-  });
-
-  if (p.isCancel(result)) {
-    p.cancel('Operation cancelled');
+  const result = await text(options);
+
+  if (isCancel(result)) {
+    cancel('Operation cancelled');
     process.exit(0);
   }
 
-  return result as string;
+  return result;
 }
 
 /**
@@ -62,30 +80,25 @@ export async function promptPassword(options: {
   validate?: (value: string | undefined) => string | Error | undefined;
 }): Promise<string> {
   while (true) {
-    const result = await p.password({
-      message: options.message,
-      validate: options.validate,
-    });
+    const result = await password(options);
 
-    if (p.isCancel(result)) {
-      p.cancel('Operation cancelled');
+    if (isCancel(result)) {
+      cancel('Operation cancelled');
       process.exit(0);
     }
 
-    const confirm = await p.password({
-      message: `Confirm ${options.message}`,
-    });
+    const confirmation = await password({ message: `Confirm ${options.message}` });
 
-    if (p.isCancel(confirm)) {
-      p.cancel('Operation cancelled');
+    if (isCancel(confirmation)) {
+      cancel('Operation cancelled');
       process.exit(0);
     }
 
-    if (result === confirm) {
-      return result as string;
+    if (result === confirmation) {
+      return result;
     }
 
-    p.log.warning('Passwords do not match. Please try again.');
+    log.warn('Passwords do not match. Please try again.');
   }
 }
 
@@ -96,53 +109,19 @@ export async function promptConfirm(options: {
   message: string;
   initialValue?: boolean;
 }): Promise<boolean> {
-  const result = await p.confirm({
-    message: options.message,
-    initialValue: options.initialValue,
-  });
+  const result = await uiConfirm(options);
 
-  if (p.isCancel(result)) {
-    p.cancel('Operation cancelled');
+  if (result === CANCEL) {
+    cancel('Operation cancelled');
     process.exit(0);
   }
 
-  return result as boolean;
+  return result;
 }
 
 /**
  * Show note/information box
  */
 export function showNote(message: string, title?: string): void {
-  p.note(message, title);
+  note(message, title);
 }
-
-/**
- * Show log messages
- */
-export const log = {
-  success: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(`\x1b[32m✔\x1b[0m ${message}`);
-    p.log.success(message);
-  },
-  error: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(`\x1b[31m✗\x1b[0m ${message}`);
-    p.log.error(message);
-  },
-  warn: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(`\x1b[33m⚠\x1b[0m ${message}`);
-    p.log.warn(message);
-  },
-  info: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.instantEvent(message);
-    p.log.info(message);
-  },
-  message: (message: string) => {
-    const d = getActiveDisplay();
-    if (d) return d.subEvent(message);
-    p.log.message(message);
-  },
-};

package/src/cli/service-credential.ts

@@ -8,10 +8,10 @@
  * secrets therefore travel by **flag or env var**, never over the event bus.
  *
  * The resolution order is: explicit `--<flag>` → `$ENV` → (only when stdin is
- * a TTY) a local clack `password` prompt → otherwise a fail-fast error naming
+ * a TTY) a local masked `password` prompt → otherwise a fail-fast error naming
  * the flag and env var. This keeps a zero-TTY `service add` possible while the
  * credential never lands on the bus, and the local password prompt is the one
- * clack input the recurrence gate (D6) allow-lists — precisely because a
+ * direct prompt the recurrence gate (D6) tolerates — precisely because a
  * flag/env path always exists alongside it.
  */
 
@@ -29,7 +29,7 @@ export interface ServiceCredentialSpec {
 }
 
 /**
- * Resolve a service-credential secret from flag → env → (TTY) clack password →
+ * Resolve a service-credential secret from flag → env → (TTY) password prompt →
  * error. Returns the secret value as a string. Throws an actionable error when
  * no value is available on a non-TTY run.
  */