@celilo/cli 0.22.0 → 0.23.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,
@@ -77,6 +77,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';
@@ -578,6 +579,20 @@ 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')
 
@@ -649,6 +664,12 @@ 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"
@@ -1397,8 +1418,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 +1520,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':
@@ -2465,31 +2490,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.
  */

package/src/cli/stdout-is-undecorated.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Recurrence gate for celilo#699 — ordinary stdout carries no decoration, and
+ * diagnostics do not share the stream with results.
+ *
+ * The CLI used to render every successful message through `@clack/prompts`,
+ * which prefixed each line with `│  ` and coloured it. Two costs followed, and
+ * this file pins both shut:
+ *
+ *  1. `line.startsWith('<module-id> ')` over `celilo module list` matched
+ *     nothing, because the line actually began `│  caddy (v2.2.0) - …`. In
+ *     celilo#695 that read as a MISSING MODULE rather than as a parse failure,
+ *     and cost a full e2e run to find. `e2e/tests/module-pause.test.ts` asserts
+ *     the same property against the real fleet topology; this is its fast
+ *     equivalent, so a regression is caught in seconds rather than in Docker.
+ *
+ *  2. clack wrote errors to stdout, so no caller could tell a result from a
+ *     complaint about producing one — `src/test-utils/cli.ts` carried a comment
+ *     saying exactly that, twice, and merged both streams to cope.
+ *
+ * Spawns the real CLI rather than using `CLIContext`: that harness runs the CLI
+ * in `CLI_SERVER_MODE`, which returns `result.message` over a protocol and
+ * never reaches the stdout writer under test here.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { type IntegrationTestContext, setupIntegrationTest } from '@/test-utils/integration';
+
+let ctx: IntegrationTestContext;
+
+function celilo(command: string): { stdout: string; stderr: string; status: number | null } {
+  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,
+  });
+  return { stdout: result.stdout, stderr: result.stderr, status: result.status };
+}
+
+/** The `│` clack used to open every rendered line with. */
+const BOX_DRAWING = /[│┌└├─]/;
+const ANSI = /\x1b\[[0-9;]*m/;
+
+describe('celilo#699 — stdout is undecorated', () => {
+  beforeAll(async () => {
+    ctx = await setupIntegrationTest();
+    // A module has to exist for `module list` to print a roster line at all —
+    // an empty roster would pass every assertion below without testing them.
+    const imported = celilo('module import ../../modules/celilo-mgmt');
+    expect(imported.status, `module import failed:\n${imported.stderr}`).toBe(0);
+  });
+
+  afterAll(async () => {
+    await ctx.cleanup();
+  });
+
+  test('module list lines start with the module id, with no preprocessing', () => {
+    const { stdout, status, stderr } = celilo('module list');
+    expect(status, `module list failed:\n${stderr}`).toBe(0);
+
+    // The exact shape celilo#695 tried and failed to match. No ANSI stripping,
+    // no prefix trimming — if this needs either, the bug is back.
+    const line = stdout.split('\n').find((l) => l.startsWith('celilo-mgmt '));
+
+    expect(
+      line,
+      `No line began with "celilo-mgmt ". stdout was:\n${JSON.stringify(stdout)}`,
+    ).toBeDefined();
+  });
+
+  test('module list stdout carries no box-drawing or ANSI', () => {
+    const { stdout } = celilo('module list');
+    expect(BOX_DRAWING.test(stdout), `box-drawing in stdout:\n${JSON.stringify(stdout)}`).toBe(
+      false,
+    );
+    expect(ANSI.test(stdout), `ANSI in stdout:\n${JSON.stringify(stdout)}`).toBe(false);
+  });
+
+  test('a failing command writes its diagnostic to stderr, not stdout', () => {
+    const { stdout, stderr, status } = celilo('module where no-such-module-exists');
+
+    expect(status).not.toBe(0);
+    expect(stderr).toContain('Error');
+    // The whole point: stdout stays empty so a caller parsing it is not handed
+    // an error message where a result belongs.
+    expect(stdout.trim(), `error text leaked to stdout: ${JSON.stringify(stdout)}`).toBe('');
+  });
+});

package/src/cli/types.ts

@@ -20,8 +20,13 @@ export interface CommandSuccess {
   message: string;
   data?: unknown;
   /**
-   * When true, the CLI writes `message` directly to stdout (no clack formatting).
-   * Use for commands designed to be consumed by scripts (e.g. `module secret get`).
+   * Marks a command whose `message` is a machine-readable payload (JSON, a
+   * unit file, a secret) rather than prose for a human.
+   *
+   * Every successful message now reaches stdout verbatim, so this no longer
+   * selects a different destination. It is kept as the contract: these are the
+   * commands a script parses, and nothing may ever decorate them (celilo#698,
+   * where ten JSON payloads were rendered unparseable by the formatter).
    */
   rawOutput?: boolean;
 }