From 0487882c1ef6b96728bdac0d8d6b906f510e82ce Mon Sep 17 00:00:00 2001
From: Giulio Fagioli <fagioli.giulio@gmail.com>
Date: Mon, 1 Jun 2026 11:56:36 +0200
Subject: [PATCH 1/4] refactor(cli): centralize output, error formatting, and
 error handling

Extract shared formatError (errors.ts), terminal output/colors/icons
(ui.ts, NO_COLOR/TTY-aware via styleText), and a runAction wrapper that
gives every command uniform error UX. Removes duplicated catch blocks and
ANSI magic strings; fixes list-style commands lacking error handling.
---
 src/commands/copy-config.ts        | 29 +++++------
 src/commands/create.ts             | 15 +++---
 src/commands/login.ts              | 56 +++++++++++-----------
 src/commands/remove.ts             | 15 +++---
 src/commands/rename.ts             | 15 +++---
 src/commands/run.ts                | 12 ++---
 src/commands/skills.ts             | 34 ++++++-------
 src/commands/use.ts                | 12 ++---
 src/lib/compliance.ts              |  4 +-
 src/lib/errors.ts                  |  4 ++
 src/lib/profile-config-copy.ts     |  5 +-
 src/lib/profile-store.ts           |  5 +-
 src/lib/run-action.ts              | 30 ++++++++++++
 src/lib/ui.ts                      | 66 +++++++++++++++++++++++++
 tests/commands/copy-config.test.ts | 12 +++--
 tests/commands/create.test.ts      |  2 +-
 tests/lib/compliance.test.ts       |  3 +-
 tests/lib/errors.test.ts           | 14 ++++++
 tests/lib/run-action.test.ts       | 62 ++++++++++++++++++++++++
 tests/lib/ui.test.ts               | 77 ++++++++++++++++++++++++++++++
 20 files changed, 358 insertions(+), 114 deletions(-)
 create mode 100644 src/lib/errors.ts
 create mode 100644 src/lib/run-action.ts
 create mode 100644 src/lib/ui.ts
 create mode 100644 tests/lib/errors.test.ts
 create mode 100644 tests/lib/run-action.test.ts
 create mode 100644 tests/lib/ui.test.ts

diff --git a/src/commands/copy-config.ts b/src/commands/copy-config.ts
index 4ed544e..d049cff 100644
--- a/src/commands/copy-config.ts
+++ b/src/commands/copy-config.ts
@@ -7,6 +7,8 @@ import {
   type ProfileConfigCopySelector,
   planProfileConfigCopy,
 } from '../lib/profile-config-copy.js'
+import { runAction } from '../lib/run-action.js'
+import { printSuccess, warnLine } from '../lib/ui.js'
 
 function confirm(question: string): Promise<boolean> {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
@@ -56,12 +58,12 @@ export function registerCopyConfig(program: Command): void {
     .option('--dry-run', 'Preview what would be copied without writing files')
     .option('-f, --force', 'Skip overwrite confirmation and apply immediately')
     .action(
-      async (
-        source: string,
-        target: string,
-        opts: { dryRun?: boolean; force?: boolean; only?: string[] },
-      ) => {
-        try {
+      runAction(
+        async (
+          source: string,
+          target: string,
+          opts: { dryRun?: boolean; force?: boolean; only?: string[] },
+        ) => {
           const plan = planProfileConfigCopy(
             source,
             target,
@@ -79,7 +81,9 @@ export function registerCopyConfig(program: Command): void {
 
           if (plan.overwriteCount > 0) {
             console.log(
-              `! ${plan.overwriteCount} existing path(s) in "${target}" will be overwritten.`,
+              warnLine(
+                `${plan.overwriteCount} existing path(s) in "${target}" will be overwritten.`,
+              ),
             )
             if (!opts.force) {
               const ok = await confirm('Continue? (y/N) ')
@@ -91,13 +95,10 @@ export function registerCopyConfig(program: Command): void {
           }
 
           const result = applyProfileConfigCopy(plan)
-          console.log(
-            `\x1b[32m✓\x1b[0m Copied ${result.copiedCount} item(s) from "${source}" to "${target}" (${result.createdCount} created, ${result.overwrittenCount} overwritten)`,
+          printSuccess(
+            `Copied ${result.copiedCount} item(s) from "${source}" to "${target}" (${result.createdCount} created, ${result.overwrittenCount} overwritten)`,
           )
-        } catch (e) {
-          console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-          process.exit(1)
-        }
-      },
+        },
+      ),
     )
 }
diff --git a/src/commands/create.ts b/src/commands/create.ts
index 929c908..138eb40 100644
--- a/src/commands/create.ts
+++ b/src/commands/create.ts
@@ -4,6 +4,8 @@ import { getCompactComplianceNoticeLines } from '../lib/compliance.js'
 import { addProfile } from '../lib/config.js'
 import { applyProfileConfigCopy, planProfileConfigCopy } from '../lib/profile-config-copy.js'
 import { createProfileDir, removeProfileDir } from '../lib/profiles.js'
+import { runAction } from '../lib/run-action.js'
+import { printSuccess } from '../lib/ui.js'
 
 /** Registers the CLI workflow for creating a managed profile. */
 export function registerCreate(program: Command): void {
@@ -13,8 +15,8 @@ export function registerCreate(program: Command): void {
     .option('-l, --label <label>', 'Profile label')
     .option('-b, --browser <path>', 'Browser for OAuth login')
     .option('--from <profile>', 'Initialize non-auth config from an existing profile')
-    .action((name: string, opts: { label?: string; browser?: string; from?: string }) => {
-      try {
+    .action(
+      runAction((name: string, opts: { label?: string; browser?: string; from?: string }) => {
         createProfileDir(name)
 
         let browser: string | undefined
@@ -46,14 +48,11 @@ export function registerCreate(program: Command): void {
           }
           throw setupErr
         }
-        console.log(`\x1b[32m✓\x1b[0m Profile "${name}" created`)
+        printSuccess(`Profile "${name}" created`)
         for (const line of getCompactComplianceNoticeLines()) {
           console.log(line)
         }
         console.log(`  Next: ccm login ${name}`)
-      } catch (e) {
-        console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-        process.exit(1)
-      }
-    })
+      }),
+    )
 }
diff --git a/src/commands/login.ts b/src/commands/login.ts
index 35d3634..f7caa7e 100644
--- a/src/commands/login.ts
+++ b/src/commands/login.ts
@@ -3,6 +3,7 @@ import { resolveBrowser } from '../lib/browsers.js'
 import { spawnClaude } from '../lib/claude.js'
 import { getProfile } from '../lib/config.js'
 import { getProfileDir, profileExists } from '../lib/profiles.js'
+import { runAction } from '../lib/run-action.js'
 
 /** Registers the CLI workflow for authenticating a managed profile. */
 export function registerLogin(program: Command): void {
@@ -12,35 +13,34 @@ export function registerLogin(program: Command): void {
     .option('--console', 'Use Anthropic Console (API key) auth')
     .option('-b, --browser <path>', 'Browser to use for OAuth')
     .option('--url-only', 'Print login URL without opening browser (supports code paste)')
-    .action((name: string, opts: { console?: boolean; browser?: string; urlOnly?: boolean }) => {
-      try {
-        if (!profileExists(name)) {
-          throw new Error(`Profile "${name}" does not exist. Create it first: ccm create ${name}`)
-        }
+    .action(
+      runAction(
+        (name: string, opts: { console?: boolean; browser?: string; urlOnly?: boolean }) => {
+          if (!profileExists(name)) {
+            throw new Error(`Profile "${name}" does not exist. Create it first: ccm create ${name}`)
+          }
 
-        const dir = getProfileDir(name)
-        const meta = getProfile(name)
+          const dir = getProfileDir(name)
+          const meta = getProfile(name)
 
-        let browser: string | undefined
-        if (opts.urlOnly) {
-          browser = 'true'
-        } else {
-          browser = resolveBrowser(opts.browser, meta)
-        }
+          let browser: string | undefined
+          if (opts.urlOnly) {
+            browser = 'true'
+          } else {
+            browser = resolveBrowser(opts.browser, meta)
+          }
 
-        if (opts.console) {
-          // API key auth: use `claude auth login --console`
-          const child = spawnClaude(dir, ['auth', 'login', '--console'], { browser })
-          child.on('close', code => process.exit(code ?? 0))
-        } else {
-          // OAuth: spawn `claude` directly (no subcommand)
-          // This triggers the interactive TUI with "Paste code here" support
-          const child = spawnClaude(dir, [], { browser })
-          child.on('close', code => process.exit(code ?? 0))
-        }
-      } catch (e) {
-        console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-        process.exit(1)
-      }
-    })
+          if (opts.console) {
+            // API key auth: use `claude auth login --console`
+            const child = spawnClaude(dir, ['auth', 'login', '--console'], { browser })
+            child.on('close', code => process.exit(code ?? 0))
+          } else {
+            // OAuth: spawn `claude` directly (no subcommand)
+            // This triggers the interactive TUI with "Paste code here" support
+            const child = spawnClaude(dir, [], { browser })
+            child.on('close', code => process.exit(code ?? 0))
+          }
+        },
+      ),
+    )
 }
diff --git a/src/commands/remove.ts b/src/commands/remove.ts
index abe7f7a..1eae997 100644
--- a/src/commands/remove.ts
+++ b/src/commands/remove.ts
@@ -1,6 +1,8 @@
 import { createInterface } from 'node:readline'
 import type { Command } from 'commander'
 import { getStoredProfile, removeStoredProfile } from '../lib/profile-store.js'
+import { runAction } from '../lib/run-action.js'
+import { printSuccess } from '../lib/ui.js'
 
 function confirm(question: string): Promise<boolean> {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
@@ -18,8 +20,8 @@ export function registerRemove(program: Command): void {
     .command('remove <name>')
     .description('Remove a profile')
     .option('-f, --force', 'Skip confirmation')
-    .action(async (name: string, opts: { force?: boolean }) => {
-      try {
+    .action(
+      runAction(async (name: string, opts: { force?: boolean }) => {
         const profile = getStoredProfile(name)
         if (!profile) {
           throw new Error(`Profile "${name}" does not exist`)
@@ -35,10 +37,7 @@ export function registerRemove(program: Command): void {
 
         removeStoredProfile(name)
         const stateSuffix = profile.state === 'ready' ? '' : ` (${profile.state})`
-        console.log(`\x1b[32m✓\x1b[0m Profile "${name}" removed${stateSuffix}`)
-      } catch (e) {
-        console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-        process.exit(1)
-      }
-    })
+        printSuccess(`Profile "${name}" removed${stateSuffix}`)
+      }),
+    )
 }
diff --git a/src/commands/rename.ts b/src/commands/rename.ts
index 6073682..2bb0e1f 100644
--- a/src/commands/rename.ts
+++ b/src/commands/rename.ts
@@ -1,18 +1,17 @@
 import type { Command } from 'commander'
 import { renameStoredProfile } from '../lib/profile-store.js'
+import { runAction } from '../lib/run-action.js'
+import { printSuccess } from '../lib/ui.js'
 
 /** Registers the CLI workflow for renaming a managed profile. */
 export function registerRename(program: Command): void {
   program
     .command('rename <old-name> <new-name>')
     .description('Rename a profile')
-    .action((oldName: string, newName: string) => {
-      try {
+    .action(
+      runAction((oldName: string, newName: string) => {
         renameStoredProfile(oldName, newName)
-        console.log(`\x1b[32m✓\x1b[0m Profile "${oldName}" renamed to "${newName}"`)
-      } catch (e) {
-        console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-        process.exit(1)
-      }
-    })
+        printSuccess(`Profile "${oldName}" renamed to "${newName}"`)
+      }),
+    )
 }
diff --git a/src/commands/run.ts b/src/commands/run.ts
index 6cd6520..0fc227f 100644
--- a/src/commands/run.ts
+++ b/src/commands/run.ts
@@ -1,6 +1,7 @@
 import type { Command } from 'commander'
 import { spawnClaude } from '../lib/claude.js'
 import { getProfileDir, profileExists } from '../lib/profiles.js'
+import { runAction } from '../lib/run-action.js'
 
 /** Registers the CLI workflow for running Claude Code with a prompt. */
 export function registerRun(program: Command): void {
@@ -8,8 +9,8 @@ export function registerRun(program: Command): void {
     .command('run <name>')
     .description('Run Claude Code with a prompt using a profile')
     .requiredOption('-p, --prompt <prompt>', 'Prompt to send')
-    .action((name: string, opts: { prompt: string }) => {
-      try {
+    .action(
+      runAction((name: string, opts: { prompt: string }) => {
         if (!profileExists(name)) {
           throw new Error(`Profile "${name}" does not exist`)
         }
@@ -17,9 +18,6 @@ export function registerRun(program: Command): void {
         const dir = getProfileDir(name)
         const child = spawnClaude(dir, ['-p', opts.prompt])
         child.on('close', code => process.exit(code ?? 0))
-      } catch (e) {
-        console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-        process.exit(1)
-      }
-    })
+      }),
+    )
 }
diff --git a/src/commands/skills.ts b/src/commands/skills.ts
index 967e6ac..e553d30 100644
--- a/src/commands/skills.ts
+++ b/src/commands/skills.ts
@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process'
 import type { Command } from 'commander'
 import { getProfileDir, profileExists } from '../lib/profiles.js'
+import { runAction } from '../lib/run-action.js'
 
 /**
  * Runs `npx skills <action> ...` with CLAUDE_CONFIG_DIR pointed at the profile
@@ -9,22 +10,17 @@ import { getProfileDir, profileExists } from '../lib/profiles.js'
  * from CLAUDE_CONFIG_DIR.
  */
 function runSkills(action: string, name: string, rest: string[]): void {
-  try {
-    if (!profileExists(name)) {
-      throw new Error(`Profile "${name}" does not exist. Create it first: ccm create ${name}`)
-    }
-
-    const dir = getProfileDir(name)
-    const args = ['-y', 'skills', action, ...rest, '-a', 'claude-code', '-g', '-y']
-    const child = spawn('npx', args, {
-      env: { ...process.env, CLAUDE_CONFIG_DIR: dir },
-      stdio: 'inherit',
-    })
-    child.on('close', code => process.exit(code ?? 0))
-  } catch (e) {
-    console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-    process.exit(1)
+  if (!profileExists(name)) {
+    throw new Error(`Profile "${name}" does not exist. Create it first: ccm create ${name}`)
   }
+
+  const dir = getProfileDir(name)
+  const args = ['-y', 'skills', action, ...rest, '-a', 'claude-code', '-g', '-y']
+  const child = spawn('npx', args, {
+    env: { ...process.env, CLAUDE_CONFIG_DIR: dir },
+    stdio: 'inherit',
+  })
+  child.on('close', code => process.exit(code ?? 0))
 }
 
 /** Registers the `skills` command group: install/manage skills per profile. */
@@ -38,26 +34,26 @@ export function registerSkills(program: Command): void {
     .description('Install skills from GitHub into a profile (e.g. owner/repo)')
     .allowUnknownOption(true)
     .helpOption(false)
-    .action((name: string, repos: string[]) => runSkills('add', name, repos))
+    .action(runAction((name: string, repos: string[]) => runSkills('add', name, repos)))
 
   skills
     .command('list <name> [args...]')
     .description('List skills installed in a profile')
     .allowUnknownOption(true)
     .helpOption(false)
-    .action((name: string, args: string[]) => runSkills('list', name, args))
+    .action(runAction((name: string, args: string[]) => runSkills('list', name, args)))
 
   skills
     .command('remove <name> [skills...]')
     .description('Remove skills from a profile')
     .allowUnknownOption(true)
     .helpOption(false)
-    .action((name: string, names: string[]) => runSkills('remove', name, names))
+    .action(runAction((name: string, names: string[]) => runSkills('remove', name, names)))
 
   skills
     .command('update <name> [skills...]')
     .description('Update skills in a profile')
     .allowUnknownOption(true)
     .helpOption(false)
-    .action((name: string, names: string[]) => runSkills('update', name, names))
+    .action(runAction((name: string, names: string[]) => runSkills('update', name, names)))
 }
diff --git a/src/commands/use.ts b/src/commands/use.ts
index 9a7dbaa..d68d98e 100644
--- a/src/commands/use.ts
+++ b/src/commands/use.ts
@@ -1,6 +1,7 @@
 import type { Command } from 'commander'
 import { spawnClaude } from '../lib/claude.js'
 import { getProfileDir, profileExists } from '../lib/profiles.js'
+import { runAction } from '../lib/run-action.js'
 
 /** Registers the CLI workflow for launching Claude Code with a profile. */
 export function registerUse(program: Command): void {
@@ -9,8 +10,8 @@ export function registerUse(program: Command): void {
     .description('Launch Claude Code with a profile')
     .allowUnknownOption()
     .helpOption(false)
-    .action((name: string, args: string[]) => {
-      try {
+    .action(
+      runAction((name: string, args: string[]) => {
         if (!profileExists(name)) {
           throw new Error(`Profile "${name}" does not exist. Create it first: ccm create ${name}`)
         }
@@ -18,9 +19,6 @@ export function registerUse(program: Command): void {
         const dir = getProfileDir(name)
         const child = spawnClaude(dir, args)
         child.on('close', code => process.exit(code ?? 0))
-      } catch (e) {
-        console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-        process.exit(1)
-      }
-    })
+      }),
+    )
 }
diff --git a/src/lib/compliance.ts b/src/lib/compliance.ts
index 5be9c72..e753be9 100644
--- a/src/lib/compliance.ts
+++ b/src/lib/compliance.ts
@@ -1,3 +1,5 @@
+import { warnLine } from './ui.js'
+
 export type ComplianceSource = {
   label: string
   url: string
@@ -40,7 +42,7 @@ function buildRuleLines(): string[] {
 /** Formats a short warning that can be embedded in interactive command output. */
 export function getCompactComplianceNoticeLines(): string[] {
   return [
-    '\x1b[33m!\x1b[0m Compliance notice',
+    warnLine('Compliance notice'),
     '  ccm isolates profiles but does not expand Anthropic usage rights.',
     '  Use each Claude account with one person and one active terminal session.',
     '  Do not share credentials or API keys across users or parallel operators.',
diff --git a/src/lib/errors.ts b/src/lib/errors.ts
new file mode 100644
index 0000000..805aa01
--- /dev/null
+++ b/src/lib/errors.ts
@@ -0,0 +1,4 @@
+/** Normalizes an unknown thrown value into a human-readable message. */
+export function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
diff --git a/src/lib/profile-config-copy.ts b/src/lib/profile-config-copy.ts
index 273500a..ea08873 100644
--- a/src/lib/profile-config-copy.ts
+++ b/src/lib/profile-config-copy.ts
@@ -1,6 +1,7 @@
 import { cpSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 import { PROFILES_DIR } from './constants.js'
+import { formatError } from './errors.js'
 import { getProfileDir, profileExists, validateProfileName } from './profiles.js'
 
 const SUPPORTED_CONFIG_PATHS = ['settings.json', 'plugins'] as const
@@ -220,7 +221,3 @@ function getStagedPath(path: string): string {
 
   throw new Error(`Could not allocate a temporary path for "${base}"`)
 }
-
-function formatError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}
diff --git a/src/lib/profile-store.ts b/src/lib/profile-store.ts
index 8758c34..344dbf2 100644
--- a/src/lib/profile-store.ts
+++ b/src/lib/profile-store.ts
@@ -9,6 +9,7 @@ import {
 } from './browsers.js'
 import { addProfile, getProfile, loadConfig, removeProfile, renameProfile } from './config.js'
 import { BROWSERS_DIR, CONFIG_FILE, PROFILES_DIR } from './constants.js'
+import { formatError } from './errors.js'
 import {
   finalizeStagedProfileDirRemoval,
   getProfileDir,
@@ -287,7 +288,3 @@ function restoreConfigEntry(meta: ProfileMeta, configFile: string): void {
   }
   addProfile(meta, configFile)
 }
-
-function formatError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}
diff --git a/src/lib/run-action.ts b/src/lib/run-action.ts
new file mode 100644
index 0000000..bb4fab9
--- /dev/null
+++ b/src/lib/run-action.ts
@@ -0,0 +1,30 @@
+import { formatError } from './errors.js'
+import { printError } from './ui.js'
+
+/**
+ * Wraps a commander action so any thrown (or rejected) error is reported as a
+ * single `✗ message` line and exits with code 1. Centralizes the error-handling
+ * boilerplate every command would otherwise repeat.
+ *
+ * The wrapper stays synchronous for synchronous actions (so callers see the
+ * failure on the same tick) and only awaits when the action returns a promise.
+ */
+export function runAction<Args extends unknown[]>(
+  action: (...args: Args) => void | Promise<void>,
+): (...args: Args) => void | Promise<void> {
+  return (...args: Args): void | Promise<void> => {
+    try {
+      const result = action(...args)
+      if (result instanceof Promise) {
+        return result.catch(fail)
+      }
+    } catch (error) {
+      fail(error)
+    }
+  }
+}
+
+function fail(error: unknown): never {
+  printError(formatError(error))
+  process.exit(1)
+}
diff --git a/src/lib/ui.ts b/src/lib/ui.ts
new file mode 100644
index 0000000..b30c1be
--- /dev/null
+++ b/src/lib/ui.ts
@@ -0,0 +1,66 @@
+import { styleText } from 'node:util'
+
+/**
+ * Terminal output helpers. Colors are applied via `node:util` styleText, which
+ * automatically degrades to plain text when output is not a TTY or NO_COLOR is
+ * set — so commands never hand-write ANSI escapes and machine consumers get
+ * clean strings.
+ */
+
+/** Status glyphs used across command output. */
+export const icons = {
+  success: '✓',
+  error: '✗',
+  warn: '!',
+  dot: '●',
+} as const
+
+/** Wraps text in green. */
+export function green(text: string): string {
+  return styleText('green', text)
+}
+
+/** Wraps text in red. */
+export function red(text: string): string {
+  return styleText('red', text)
+}
+
+/** Wraps text in yellow. */
+export function yellow(text: string): string {
+  return styleText('yellow', text)
+}
+
+/** Wraps text in dim styling. */
+export function dim(text: string): string {
+  return styleText('dim', text)
+}
+
+/** Builds a success line: green check followed by the message. */
+export function successLine(message: string): string {
+  return `${green(icons.success)} ${message}`
+}
+
+/** Builds an error line: red cross followed by the message. */
+export function errorLine(message: string): string {
+  return `${red(icons.error)} ${message}`
+}
+
+/** Builds a warning line: yellow bang followed by the message. */
+export function warnLine(message: string): string {
+  return `${yellow(icons.warn)} ${message}`
+}
+
+/** Picks the colored status dot for a profile's logged-in state. */
+export function statusDot(loggedIn: boolean): string {
+  return loggedIn ? green(icons.dot) : red(icons.dot)
+}
+
+/** Prints a success line to stdout. */
+export function printSuccess(message: string): void {
+  console.log(successLine(message))
+}
+
+/** Prints an error line to stderr. */
+export function printError(message: string): void {
+  console.error(errorLine(message))
+}
diff --git a/tests/commands/copy-config.test.ts b/tests/commands/copy-config.test.ts
index 8e694cd..373ab6f 100644
--- a/tests/commands/copy-config.test.ts
+++ b/tests/commands/copy-config.test.ts
@@ -114,10 +114,14 @@ describe('command: copy-config', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'copy-config', 'source', 'target'])
 
-    expect(log).toHaveBeenCalledWith('! 1 existing path(s) in "target" will be overwritten.')
+    expect(log).toHaveBeenCalledWith(
+      expect.stringContaining('1 existing path(s) in "target" will be overwritten.'),
+    )
     expect(question).toHaveBeenCalledWith('Continue? (y/N) ', expect.any(Function))
     expect(log).toHaveBeenCalledWith(
-      '\x1b[32m✓\x1b[0m Copied 1 item(s) from "source" to "target" (0 created, 1 overwritten)',
+      expect.stringContaining(
+        'Copied 1 item(s) from "source" to "target" (0 created, 1 overwritten)',
+      ),
     )
     expect(mockApplyProfileConfigCopy).toHaveBeenCalledTimes(1)
   })
@@ -247,7 +251,7 @@ describe('command: copy-config', () => {
     await expect(
       program.parseAsync(['node', 'ccm', 'copy-config', 'source', 'target']),
     ).rejects.toThrow('exit:1')
-    expect(errLog).toHaveBeenCalledWith('\x1b[31m✗\x1b[0m boom')
+    expect(errLog).toHaveBeenCalledWith(expect.stringContaining('boom'))
   })
 
   test('prints error and exits on non-Error throw', async () => {
@@ -260,6 +264,6 @@ describe('command: copy-config', () => {
     await expect(
       program.parseAsync(['node', 'ccm', 'copy-config', 'source', 'target']),
     ).rejects.toThrow('exit:1')
-    expect(errLog).toHaveBeenCalledWith('\x1b[31m✗\x1b[0m string boom')
+    expect(errLog).toHaveBeenCalledWith(expect.stringContaining('string boom'))
   })
 })
diff --git a/tests/commands/create.test.ts b/tests/commands/create.test.ts
index a199377..64b5d2a 100644
--- a/tests/commands/create.test.ts
+++ b/tests/commands/create.test.ts
@@ -106,7 +106,7 @@ describe('command: create', () => {
       const program = createProgram()
       program.parse(['node', 'ccm', 'create', 'test'])
 
-      expect(log).toHaveBeenCalledWith('\x1b[32m✓\x1b[0m Profile "test" created')
+      expect(log).toHaveBeenCalledWith(expect.stringContaining('Profile "test" created'))
     })
 
     test('prints compact compliance notice after success', () => {
diff --git a/tests/lib/compliance.test.ts b/tests/lib/compliance.test.ts
index c4e8903..57e11f5 100644
--- a/tests/lib/compliance.test.ts
+++ b/tests/lib/compliance.test.ts
@@ -5,6 +5,7 @@ import {
   getCompactComplianceNoticeLines,
   getFullComplianceNoticeLines,
 } from '../../src/lib/compliance.js'
+import { warnLine } from '../../src/lib/ui.js'
 
 describe('compliance notices', () => {
   test('exports the official sources used by the notice', () => {
@@ -33,7 +34,7 @@ describe('compliance notices', () => {
 
   test('formats the compact notice for interactive commands', () => {
     expect(getCompactComplianceNoticeLines()).toEqual([
-      '\x1b[33m!\x1b[0m Compliance notice',
+      warnLine('Compliance notice'),
       '  ccm isolates profiles but does not expand Anthropic usage rights.',
       '  Use each Claude account with one person and one active terminal session.',
       '  Do not share credentials or API keys across users or parallel operators.',
diff --git a/tests/lib/errors.test.ts b/tests/lib/errors.test.ts
new file mode 100644
index 0000000..4458a1b
--- /dev/null
+++ b/tests/lib/errors.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, test } from 'vitest'
+import { formatError } from '../../src/lib/errors.js'
+
+describe('formatError', () => {
+  test('returns the message for Error instances', () => {
+    expect(formatError(new Error('boom'))).toBe('boom')
+  })
+
+  test('stringifies non-Error values', () => {
+    expect(formatError('plain string')).toBe('plain string')
+    expect(formatError(42)).toBe('42')
+    expect(formatError({ toString: () => 'obj' })).toBe('obj')
+  })
+})
diff --git a/tests/lib/run-action.test.ts b/tests/lib/run-action.test.ts
new file mode 100644
index 0000000..b9c3c90
--- /dev/null
+++ b/tests/lib/run-action.test.ts
@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { runAction } from '../../src/lib/run-action.js'
+
+beforeEach(() => {
+  vi.restoreAllMocks()
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+  vi.spyOn(process, 'exit').mockImplementation(code => {
+    throw new Error(`exit:${code}`)
+  })
+})
+
+describe('runAction', () => {
+  test('runs a synchronous action and returns undefined on success', () => {
+    const fn = vi.fn()
+    const wrapped = runAction(fn)
+    expect(wrapped('a', 'b')).toBeUndefined()
+    expect(fn).toHaveBeenCalledWith('a', 'b')
+  })
+
+  test('awaits an async action and resolves on success', async () => {
+    const fn = vi.fn(async () => {})
+    const wrapped = runAction(fn)
+    await expect(wrapped()).resolves.toBeUndefined()
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  test('handles a synchronous throw: prints error and exits 1', () => {
+    const err = vi.spyOn(console, 'error')
+    const wrapped = runAction(() => {
+      throw new Error('sync boom')
+    })
+    expect(() => wrapped()).toThrow('exit:1')
+    expect(err).toHaveBeenCalledWith(expect.stringContaining('sync boom'))
+  })
+
+  test('handles an async rejection: prints error and exits 1', async () => {
+    const err = vi.spyOn(console, 'error')
+    const wrapped = runAction(async () => {
+      throw new Error('async boom')
+    })
+    await expect(wrapped()).rejects.toThrow('exit:1')
+    expect(err).toHaveBeenCalledWith(expect.stringContaining('async boom'))
+  })
+
+  test('formats non-Error throws', () => {
+    const err = vi.spyOn(console, 'error')
+    const wrapped = runAction(() => {
+      throw 'string failure'
+    })
+    expect(() => wrapped()).toThrow('exit:1')
+    expect(err).toHaveBeenCalledWith(expect.stringContaining('string failure'))
+  })
+
+  test('exits with exactly code 1', () => {
+    const exit = vi.spyOn(process, 'exit')
+    const wrapped = runAction(() => {
+      throw new Error('x')
+    })
+    expect(() => wrapped()).toThrow()
+    expect(exit).toHaveBeenCalledWith(1)
+  })
+})
diff --git a/tests/lib/ui.test.ts b/tests/lib/ui.test.ts
new file mode 100644
index 0000000..bf11ed6
--- /dev/null
+++ b/tests/lib/ui.test.ts
@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import {
+  dim,
+  errorLine,
+  green,
+  icons,
+  printError,
+  printSuccess,
+  red,
+  statusDot,
+  successLine,
+  warnLine,
+  yellow,
+} from '../../src/lib/ui.js'
+
+describe('ui — color helpers (forced color)', () => {
+  const prev = process.env.FORCE_COLOR
+  beforeEach(() => {
+    process.env.FORCE_COLOR = '1'
+  })
+  afterEach(() => {
+    if (prev === undefined) delete process.env.FORCE_COLOR
+    else process.env.FORCE_COLOR = prev
+  })
+
+  test('green/red/yellow/dim emit distinct ANSI styling', () => {
+    expect(green('x')).toContain('x')
+    expect(green('x')).not.toBe('x')
+    expect(red('x')).not.toBe(green('x'))
+    expect(yellow('x')).not.toBe(green('x'))
+    expect(dim('x')).not.toBe('x')
+  })
+
+  test('statusDot uses green when logged in and red when not', () => {
+    expect(statusDot(true)).toBe(green(icons.dot))
+    expect(statusDot(false)).toBe(red(icons.dot))
+    expect(statusDot(true)).not.toBe(statusDot(false))
+  })
+})
+
+describe('ui — line builders', () => {
+  test('successLine prefixes the success icon', () => {
+    expect(successLine('done')).toBe(`${green(icons.success)} done`)
+    expect(successLine('done')).toContain(icons.success)
+    expect(successLine('done')).toContain('done')
+  })
+
+  test('errorLine prefixes the error icon', () => {
+    expect(errorLine('nope')).toBe(`${red(icons.error)} nope`)
+    expect(errorLine('nope')).toContain(icons.error)
+  })
+
+  test('warnLine prefixes the warn icon', () => {
+    expect(warnLine('careful')).toBe(`${yellow(icons.warn)} careful`)
+    expect(warnLine('careful')).toContain(icons.warn)
+  })
+
+  test('icons are the expected glyphs', () => {
+    expect(icons).toEqual({ success: '✓', error: '✗', warn: '!', dot: '●' })
+  })
+})
+
+describe('ui — print helpers', () => {
+  test('printSuccess writes the success line to stdout', () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    printSuccess('created')
+    expect(log).toHaveBeenCalledWith(successLine('created'))
+    log.mockRestore()
+  })
+
+  test('printError writes the error line to stderr', () => {
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {})
+    printError('boom')
+    expect(err).toHaveBeenCalledWith(errorLine('boom'))
+    err.mockRestore()
+  })
+})

From 2f02c1ba12d5a6438247d2d8db6c861909233235 Mon Sep 17 00:00:00 2001
From: Giulio Fagioli <fagioli.giulio@gmail.com>
Date: Mon, 1 Jun 2026 11:56:49 +0200
Subject: [PATCH 2/4] feat(cli): add --json output and shell completion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

list/status gain --json for scriptable output (shared projection in
profile-view.ts; null instead of the — placeholder). New ccm completion
<bash|zsh|fish> derives the command list from the live registry so it
never drifts. All new modules added to the Stryker mutate set.
---
 src/commands/completion.ts        |  28 +++++
 src/commands/list.ts              |  80 ++++++++------
 src/commands/status.ts            |  81 ++++++++------
 src/index.ts                      |   2 +
 src/lib/completion.ts             |  57 ++++++++++
 src/lib/profile-view.ts           |  44 ++++++++
 stryker.config.mjs                |   8 ++
 tests/commands/completion.test.ts |  58 ++++++++++
 tests/commands/list.test.ts       | 110 +++++++++++++++---
 tests/commands/status.test.ts     | 178 ++++++++++++++++++++++++++++--
 tests/lib/completion.test.ts      |  76 +++++++++++++
 tests/lib/profile-view.test.ts    |  90 +++++++++++++++
 12 files changed, 723 insertions(+), 89 deletions(-)
 create mode 100644 src/commands/completion.ts
 create mode 100644 src/lib/completion.ts
 create mode 100644 src/lib/profile-view.ts
 create mode 100644 tests/commands/completion.test.ts
 create mode 100644 tests/lib/completion.test.ts
 create mode 100644 tests/lib/profile-view.test.ts

diff --git a/src/commands/completion.ts b/src/commands/completion.ts
new file mode 100644
index 0000000..a72891a
--- /dev/null
+++ b/src/commands/completion.ts
@@ -0,0 +1,28 @@
+import type { Command } from 'commander'
+import { generateCompletion, parseShell, SUPPORTED_SHELLS } from '../lib/completion.js'
+import { runAction } from '../lib/run-action.js'
+
+/** Collects the top-level command names (and aliases) registered on a program. */
+export function collectCommandNames(program: Command): string[] {
+  const names = new Set<string>()
+  for (const command of program.commands) {
+    const name = command.name()
+    if (name === 'completion') continue
+    names.add(name)
+    for (const alias of command.aliases()) names.add(alias)
+  }
+  return [...names].sort((left, right) => left.localeCompare(right))
+}
+
+/** Registers the CLI workflow for emitting shell completion scripts. */
+export function registerCompletion(program: Command): void {
+  program
+    .command('completion <shell>')
+    .description(`Print a shell completion script (${SUPPORTED_SHELLS.join(', ')})`)
+    .action(
+      runAction((shell: string) => {
+        const parsed = parseShell(shell)
+        console.log(generateCompletion(parsed, collectCommandNames(program)))
+      }),
+    )
+}
diff --git a/src/commands/list.ts b/src/commands/list.ts
index 18370ab..3bfa96f 100644
--- a/src/commands/list.ts
+++ b/src/commands/list.ts
@@ -1,43 +1,61 @@
 import type { Command } from 'commander'
 import { getAuthStatus } from '../lib/claude.js'
 import { listStoredProfiles } from '../lib/profile-store.js'
+import { NO_ACCOUNT_PLACEHOLDER, toProfileView } from '../lib/profile-view.js'
+import { runAction } from '../lib/run-action.js'
+
+const COLUMNS = {
+  name: 20,
+  state: 14,
+  auth: 15,
+  account: 35,
+} as const
+
+const TABLE_WIDTH = COLUMNS.name + COLUMNS.state + COLUMNS.auth + COLUMNS.account + 'CREATED'.length
 
 /** Registers the CLI workflow for listing managed profiles. */
 export function registerList(program: Command): void {
   program
     .command('list')
     .description('List all profiles, including drifted config/filesystem entries')
-    .action(async () => {
-      const profiles = listStoredProfiles()
-
-      if (profiles.length === 0) {
-        console.log('No profiles. Create one: ccm create <name>')
-        return
-      }
-
-      const statuses = await Promise.all(
-        profiles.map(async profile => {
-          const status = profile.hasDirectory ? await getAuthStatus(profile.dir) : undefined
-          return { profile, status }
-        }),
-      )
-
-      console.log(
-        `${'NAME'.padEnd(20)}${'STATE'.padEnd(14)}${'AUTH'.padEnd(15)}${'ACCOUNT'.padEnd(
-          35,
-        )}CREATED`,
-      )
-      console.log('─'.repeat(99))
-
-      for (const { profile, status } of statuses) {
-        const account = status?.email ?? status?.apiKeySource ?? '—'
-        const authMethod = status?.authMethod ?? 'unavailable'
-        const created = profile.meta?.createdAt.slice(0, 10) ?? '—'
+    .option('--json', 'Output machine-readable JSON')
+    .action(
+      runAction(async (opts: { json?: boolean }) => {
+        const profiles = listStoredProfiles()
+
+        const views = await Promise.all(
+          profiles.map(async profile => {
+            const status = profile.hasDirectory ? await getAuthStatus(profile.dir) : undefined
+            return toProfileView(profile, status)
+          }),
+        )
+
+        if (opts.json) {
+          console.log(JSON.stringify(views, null, 2))
+          return
+        }
+
+        if (views.length === 0) {
+          console.log('No profiles. Create one: ccm create <name>')
+          return
+        }
+
         console.log(
-          `${profile.name.padEnd(20)}${profile.state.padEnd(14)}${authMethod.padEnd(
-            15,
-          )}${account.padEnd(35)}${created}`,
+          `${'NAME'.padEnd(COLUMNS.name)}${'STATE'.padEnd(COLUMNS.state)}${'AUTH'.padEnd(
+            COLUMNS.auth,
+          )}${'ACCOUNT'.padEnd(COLUMNS.account)}CREATED`,
         )
-      }
-    })
+        console.log('─'.repeat(TABLE_WIDTH))
+
+        for (const view of views) {
+          const account = view.account ?? NO_ACCOUNT_PLACEHOLDER
+          const created = view.createdAt?.slice(0, 10) ?? NO_ACCOUNT_PLACEHOLDER
+          console.log(
+            `${view.name.padEnd(COLUMNS.name)}${view.state.padEnd(COLUMNS.state)}${view.authMethod.padEnd(
+              COLUMNS.auth,
+            )}${account.padEnd(COLUMNS.account)}${created}`,
+          )
+        }
+      }),
+    )
 }
diff --git a/src/commands/status.ts b/src/commands/status.ts
index 0e71f4a..140d469 100644
--- a/src/commands/status.ts
+++ b/src/commands/status.ts
@@ -1,54 +1,69 @@
 import type { Command } from 'commander'
 import { getAuthStatus } from '../lib/claude.js'
 import { getStoredProfile, listStoredProfiles } from '../lib/profile-store.js'
+import { NO_ACCOUNT_PLACEHOLDER, toProfileView } from '../lib/profile-view.js'
+import { runAction } from '../lib/run-action.js'
+import { statusDot } from '../lib/ui.js'
 
 /** Registers the CLI workflow for inspecting profile auth status. */
 export function registerStatus(program: Command): void {
   program
     .command('status [name]')
     .description('Show auth status for a profile (or all profiles)')
-    .action(async (name?: string) => {
-      try {
+    .option('--json', 'Output machine-readable JSON')
+    .action(
+      runAction(async (name: string | undefined, opts: { json?: boolean }) => {
         if (name) {
           const profile = getStoredProfile(name)
           if (!profile) {
             throw new Error(`Profile "${name}" does not exist`)
           }
           const status = profile.hasDirectory ? await getAuthStatus(profile.dir) : undefined
-          console.log(`Profile: ${name}`)
-          console.log(`State: ${profile.state}`)
-          console.log(`Logged in: ${status?.loggedIn ?? 'unknown'}`)
-          console.log(`Auth method: ${status?.authMethod ?? 'unavailable'}`)
-          if (profile.meta?.createdAt) console.log(`Created: ${profile.meta.createdAt}`)
-          if (!profile.hasDirectory) console.log('Directory: missing')
+          const view = toProfileView(profile, status)
+
+          if (opts.json) {
+            console.log(JSON.stringify(view, null, 2))
+            return
+          }
+
+          console.log(`Profile: ${view.name}`)
+          console.log(`State: ${view.state}`)
+          console.log(`Logged in: ${view.loggedIn ?? 'unknown'}`)
+          console.log(`Auth method: ${view.authMethod}`)
+          if (view.createdAt) console.log(`Created: ${view.createdAt}`)
+          if (!view.hasDirectory) console.log('Directory: missing')
           if (status?.email) console.log(`Email: ${status.email}`)
           if (status?.orgName) console.log(`Org: ${status.orgName}`)
           if (status?.subscriptionType) console.log(`Subscription: ${status.subscriptionType}`)
-        } else {
-          const profiles = listStoredProfiles()
-          if (profiles.length === 0) {
-            console.log('No profiles.')
-            return
-          }
-          const statuses = await Promise.all(
-            profiles.map(async profile => ({
-              profile,
-              status: profile.hasDirectory ? await getAuthStatus(profile.dir) : undefined,
-            })),
+          return
+        }
+
+        const profiles = listStoredProfiles()
+        const views = await Promise.all(
+          profiles.map(async profile => {
+            const status = profile.hasDirectory ? await getAuthStatus(profile.dir) : undefined
+            return toProfileView(profile, status)
+          }),
+        )
+
+        if (opts.json) {
+          console.log(JSON.stringify(views, null, 2))
+          return
+        }
+
+        if (views.length === 0) {
+          console.log('No profiles.')
+          return
+        }
+
+        for (const view of views) {
+          const icon = statusDot(view.loggedIn === true)
+          const account = view.account ?? NO_ACCOUNT_PLACEHOLDER
+          const stateSuffix = view.state === 'ready' ? '' : ` [${view.state}]`
+          console.log(
+            `${icon} ${view.name.padEnd(20)} ${view.authMethod.padEnd(15)} ${account}${stateSuffix}`,
           )
-          for (const { profile, status } of statuses) {
-            const icon = status?.loggedIn === true ? '\x1b[32m●\x1b[0m' : '\x1b[31m●\x1b[0m'
-            const account = status?.email ?? status?.apiKeySource ?? '—'
-            const authMethod = status?.authMethod ?? 'unavailable'
-            const stateSuffix = profile.state === 'ready' ? '' : ` [${profile.state}]`
-            console.log(
-              `${icon} ${profile.name.padEnd(20)} ${authMethod.padEnd(15)} ${account}${stateSuffix}`,
-            )
-          }
         }
-      } catch (e) {
-        console.error(`\x1b[31m✗\x1b[0m ${e instanceof Error ? e.message : String(e)}`)
-        process.exit(1)
-      }
-    })
+      }),
+    )
 }
diff --git a/src/index.ts b/src/index.ts
index 3fd02c0..c1d9ba6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,6 +1,7 @@
 declare const __PKG_VERSION__: string
 
 import { Command } from 'commander'
+import { registerCompletion } from './commands/completion.js'
 import { registerCompliance } from './commands/compliance.js'
 import { registerCopyConfig } from './commands/copy-config.js'
 import { registerCreate } from './commands/create.js'
@@ -29,5 +30,6 @@ registerStatus(program)
 registerUse(program)
 registerRun(program)
 registerSkills(program)
+registerCompletion(program)
 
 program.parse()
diff --git a/src/lib/completion.ts b/src/lib/completion.ts
new file mode 100644
index 0000000..7e4587c
--- /dev/null
+++ b/src/lib/completion.ts
@@ -0,0 +1,57 @@
+/** Shells for which completion scripts can be generated. */
+export const SUPPORTED_SHELLS = ['bash', 'zsh', 'fish'] as const
+
+export type CompletionShell = (typeof SUPPORTED_SHELLS)[number]
+
+/** Narrows an arbitrary string to a supported shell, or throws. */
+export function parseShell(value: string): CompletionShell {
+  if ((SUPPORTED_SHELLS as readonly string[]).includes(value)) {
+    return value as CompletionShell
+  }
+  throw new Error(`Unsupported shell "${value}". Supported: ${SUPPORTED_SHELLS.join(', ')}`)
+}
+
+function bashScript(commands: string[]): string {
+  return `# ccm bash completion
+_ccm_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${commands.join(' ')}" -- "$cur") )
+  fi
+}
+complete -F _ccm_completions ccm
+`
+}
+
+function zshScript(commands: string[]): string {
+  return `#compdef ccm
+# ccm zsh completion
+_ccm() {
+  local -a commands
+  commands=(${commands.map(name => `'${name}'`).join(' ')})
+  if (( CURRENT == 2 )); then
+    compadd -- \${commands[@]}
+  fi
+}
+compdef _ccm ccm
+`
+}
+
+function fishScript(commands: string[]): string {
+  return commands
+    .map(name => `complete -c ccm -n "__fish_use_subcommand" -a "${name}"`)
+    .join('\n')
+    .concat('\n')
+}
+
+/** Generates a shell completion script listing the given top-level commands. */
+export function generateCompletion(shell: CompletionShell, commands: string[]): string {
+  switch (shell) {
+    case 'bash':
+      return bashScript(commands)
+    case 'zsh':
+      return zshScript(commands)
+    case 'fish':
+      return fishScript(commands)
+  }
+}
diff --git a/src/lib/profile-view.ts b/src/lib/profile-view.ts
new file mode 100644
index 0000000..194b54e
--- /dev/null
+++ b/src/lib/profile-view.ts
@@ -0,0 +1,44 @@
+import type { ClaudeAuthStatus } from '../types.js'
+import type { StoredProfile } from './profile-store.js'
+
+/** Machine-readable projection of a profile and its Claude auth status. */
+export interface ProfileView {
+  name: string
+  state: StoredProfile['state']
+  authMethod: string
+  account: string | null
+  loggedIn: boolean | null
+  createdAt: string | null
+  hasConfig: boolean
+  hasDirectory: boolean
+}
+
+/** Account label used in human-readable output when no account is known. */
+export const NO_ACCOUNT_PLACEHOLDER = '—'
+
+/** Resolves the account label from an auth status (email, else API key source). */
+export function accountLabel(status: ClaudeAuthStatus | undefined): string | null {
+  return status?.email ?? status?.apiKeySource ?? null
+}
+
+/** Resolves the auth method, defaulting to "unavailable" when unknown. */
+export function authMethodLabel(status: ClaudeAuthStatus | undefined): string {
+  return status?.authMethod ?? 'unavailable'
+}
+
+/** Projects a stored profile and its auth status into a serializable view. */
+export function toProfileView(
+  profile: StoredProfile,
+  status: ClaudeAuthStatus | undefined,
+): ProfileView {
+  return {
+    name: profile.name,
+    state: profile.state,
+    authMethod: authMethodLabel(status),
+    account: accountLabel(status),
+    loggedIn: status?.loggedIn ?? null,
+    createdAt: profile.meta?.createdAt ?? null,
+    hasConfig: profile.hasConfig,
+    hasDirectory: profile.hasDirectory,
+  }
+}
diff --git a/stryker.config.mjs b/stryker.config.mjs
index 924a236..76aa6b3 100644
--- a/stryker.config.mjs
+++ b/stryker.config.mjs
@@ -6,17 +6,25 @@ export default {
   checkers: ['typescript'],
   tsconfigFile: 'tsconfig.json',
   mutate: [
+    'src/commands/completion.ts',
     'src/commands/copy-config.ts',
     'src/commands/compliance.ts',
     'src/commands/create.ts',
+    'src/commands/list.ts',
     'src/commands/skills.ts',
+    'src/commands/status.ts',
     'src/lib/browsers.ts',
     'src/lib/claude.ts',
     'src/lib/compliance.ts',
+    'src/lib/completion.ts',
     'src/lib/config.ts',
+    'src/lib/errors.ts',
     'src/lib/profile-config-copy.ts',
     'src/lib/profile-store.ts',
+    'src/lib/profile-view.ts',
     'src/lib/profiles.ts',
+    'src/lib/run-action.ts',
+    'src/lib/ui.ts',
   ],
   ignorePatterns: ['dist', 'coverage', '.stryker-tmp'],
   reporters: ['progress', 'html', 'clear-text', 'dashboard'],
diff --git a/tests/commands/completion.test.ts b/tests/commands/completion.test.ts
new file mode 100644
index 0000000..96145b7
--- /dev/null
+++ b/tests/commands/completion.test.ts
@@ -0,0 +1,58 @@
+import { Command } from 'commander'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { collectCommandNames, registerCompletion } from '../../src/commands/completion.js'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.spyOn(console, 'log').mockImplementation(() => {})
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+  vi.spyOn(process, 'exit').mockImplementation(code => {
+    throw new Error(`exit:${code}`)
+  })
+})
+
+function createProgram() {
+  const program = new Command()
+  program.exitOverride()
+  program.command('create <name>').action(() => {})
+  program.command('list').action(() => {})
+  program
+    .command('compliance')
+    .alias('tos')
+    .action(() => {})
+  registerCompletion(program)
+  return program
+}
+
+describe('collectCommandNames', () => {
+  test('returns sorted command names and aliases, excluding completion', () => {
+    const program = createProgram()
+    expect(collectCommandNames(program)).toEqual(['compliance', 'create', 'list', 'tos'])
+  })
+})
+
+describe('command: completion', () => {
+  test('registers a description listing the supported shells', () => {
+    const program = createProgram()
+    const completion = program.commands.find(command => command.name() === 'completion')
+    expect(completion?.description()).toBe('Print a shell completion script (bash, zsh, fish)')
+  })
+
+  test('prints a script for a valid shell containing the commands', () => {
+    const log = vi.spyOn(console, 'log')
+    const program = createProgram()
+    program.parse(['node', 'ccm', 'completion', 'bash'])
+
+    const output = log.mock.calls.at(-1)?.[0] as string
+    expect(output).toContain('create')
+    expect(output).toContain('list')
+    expect(output).toContain('complete -F _ccm_completions ccm')
+  })
+
+  test('exits with error for an unsupported shell', () => {
+    const errLog = vi.spyOn(console, 'error')
+    const program = createProgram()
+    expect(() => program.parse(['node', 'ccm', 'completion', 'nushell'])).toThrow('exit:1')
+    expect(errLog).toHaveBeenCalledWith(expect.stringContaining('Unsupported shell'))
+  })
+})
diff --git a/tests/commands/list.test.ts b/tests/commands/list.test.ts
index 895baf4..bd2fd34 100644
--- a/tests/commands/list.test.ts
+++ b/tests/commands/list.test.ts
@@ -18,6 +18,10 @@ const mockListStoredProfiles = vi.mocked(listStoredProfiles)
 beforeEach(() => {
   vi.clearAllMocks()
   vi.spyOn(console, 'log').mockImplementation(() => {})
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+  vi.spyOn(process, 'exit').mockImplementation(code => {
+    throw new Error(`exit:${code}`)
+  })
 })
 
 function createProgram() {
@@ -28,6 +32,16 @@ function createProgram() {
 }
 
 describe('command: list', () => {
+  test('registers description and --json option text', () => {
+    const program = createProgram()
+    const list = program.commands.find(command => command.name() === 'list')
+    expect(list?.description()).toBe(
+      'List all profiles, including drifted config/filesystem entries',
+    )
+    const jsonOption = list?.options.find(option => option.long === '--json')
+    expect(jsonOption?.description).toBe('Output machine-readable JSON')
+  })
+
   test('prints empty message when no profiles exist', async () => {
     mockListStoredProfiles.mockReturnValue([])
     const log = vi.spyOn(console, 'log')
@@ -70,28 +84,37 @@ describe('command: list', () => {
     expect(mockGetAuthStatus).toHaveBeenCalledTimes(2)
   })
 
-  test('displays header row with column names', async () => {
+  test('displays header, separator, and an exactly formatted data row', async () => {
     mockListStoredProfiles.mockReturnValue([
       {
-        name: 'x',
-        dir: '/tmp/profiles/x',
+        name: 'work',
+        dir: '/tmp/profiles/work',
         state: 'ready',
         hasConfig: true,
         hasDirectory: true,
-        meta: { name: 'x', createdAt: '2026-01-01' },
+        meta: { name: 'work', createdAt: '2026-01-15T00:00:00.000Z' },
       },
     ])
-    mockGetAuthStatus.mockResolvedValue({ loggedIn: true, authMethod: 'api_key' })
+    mockGetAuthStatus.mockResolvedValue({
+      loggedIn: true,
+      authMethod: 'claude.ai',
+      email: 'u@t.com',
+    })
     const log = vi.spyOn(console, 'log')
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'list'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('NAME'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('STATE'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('AUTH'))
+    // Exact column layout pins padding widths, separator width, and the createdAt slice.
+    expect(log).toHaveBeenCalledWith(
+      'NAME                STATE         AUTH           ACCOUNT                            CREATED',
+    )
+    expect(log).toHaveBeenCalledWith('─'.repeat(91))
+    expect(log).toHaveBeenCalledWith(
+      'work                ready         claude.ai      u@t.com                            2026-01-15',
+    )
   })
 
-  test('shows orphaned profile rows when metadata is missing', async () => {
+  test('shows orphaned profile rows with dash placeholders for account and created', async () => {
     mockListStoredProfiles.mockReturnValue([
       {
         name: 'x',
@@ -106,8 +129,10 @@ describe('command: list', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'list'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('orphaned'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('—'))
+    // Both the account and the created columns fall back to the em-dash placeholder.
+    expect(log).toHaveBeenCalledWith(
+      'x                   orphaned      none           —                                  —',
+    )
   })
 
   test('shows dash when no email or apiKeySource', async () => {
@@ -145,7 +170,66 @@ describe('command: list', () => {
     await program.parseAsync(['node', 'ccm', 'list'])
 
     expect(mockGetAuthStatus).not.toHaveBeenCalled()
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('unavailable'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('config-only'))
+    expect(log).toHaveBeenCalledWith(
+      'stale               config-only   unavailable    —                                  2026-01-01',
+    )
+  })
+
+  test('--json prints a parseable array of profile views', async () => {
+    mockListStoredProfiles.mockReturnValue([
+      {
+        name: 'work',
+        dir: '/tmp/profiles/work',
+        state: 'ready',
+        hasConfig: true,
+        hasDirectory: true,
+        meta: { name: 'work', createdAt: '2026-01-15T00:00:00.000Z' },
+      },
+    ])
+    mockGetAuthStatus.mockResolvedValue({
+      loggedIn: true,
+      authMethod: 'claude.ai',
+      email: 'u@t.com',
+    })
+    const log = vi.spyOn(console, 'log')
+    const program = createProgram()
+    await program.parseAsync(['node', 'ccm', 'list', '--json'])
+
+    const payload = JSON.parse(log.mock.calls.at(-1)?.[0] as string)
+    expect(payload).toEqual([
+      {
+        name: 'work',
+        state: 'ready',
+        authMethod: 'claude.ai',
+        account: 'u@t.com',
+        loggedIn: true,
+        createdAt: '2026-01-15T00:00:00.000Z',
+        hasConfig: true,
+        hasDirectory: true,
+      },
+    ])
+    // Human table header must not be printed in JSON mode.
+    expect(log).not.toHaveBeenCalledWith(expect.stringContaining('NAME'))
+  })
+
+  test('--json emits an empty array when no profiles exist', async () => {
+    mockListStoredProfiles.mockReturnValue([])
+    const log = vi.spyOn(console, 'log')
+    const program = createProgram()
+    await program.parseAsync(['node', 'ccm', 'list', '--json'])
+
+    expect(JSON.parse(log.mock.calls.at(-1)?.[0] as string)).toEqual([])
+    expect(log).not.toHaveBeenCalledWith(expect.stringContaining('No profiles'))
+  })
+
+  test('prints error and exits when listing fails', async () => {
+    mockListStoredProfiles.mockImplementation(() => {
+      throw new Error('store unreadable')
+    })
+    const errLog = vi.spyOn(console, 'error')
+    const program = createProgram()
+
+    await expect(program.parseAsync(['node', 'ccm', 'list'])).rejects.toThrow('exit:1')
+    expect(errLog).toHaveBeenCalledWith(expect.stringContaining('store unreadable'))
   })
 })
diff --git a/tests/commands/status.test.ts b/tests/commands/status.test.ts
index 3680458..d7e21fd 100644
--- a/tests/commands/status.test.ts
+++ b/tests/commands/status.test.ts
@@ -1,6 +1,7 @@
 import { Command } from 'commander'
-import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import { registerStatus } from '../../src/commands/status.js'
+import { statusDot } from '../../src/lib/ui.js'
 
 vi.mock('../../src/lib/claude.js', () => ({
   getAuthStatus: vi.fn(),
@@ -17,8 +18,13 @@ const mockGetAuthStatus = vi.mocked(getAuthStatus)
 const mockGetStoredProfile = vi.mocked(getStoredProfile)
 const mockListStoredProfiles = vi.mocked(listStoredProfiles)
 
+const prevForceColor = process.env.FORCE_COLOR
+
 beforeEach(() => {
   vi.clearAllMocks()
+  // Force color so the logged-in/out status dots differ (green vs red), making the
+  // statusDot(...) call observable instead of collapsing to a plain glyph.
+  process.env.FORCE_COLOR = '1'
   vi.spyOn(console, 'log').mockImplementation(() => {})
   vi.spyOn(console, 'error').mockImplementation(() => {})
   vi.spyOn(process, 'exit').mockImplementation(code => {
@@ -26,6 +32,11 @@ beforeEach(() => {
   })
 })
 
+afterEach(() => {
+  if (prevForceColor === undefined) delete process.env.FORCE_COLOR
+  else process.env.FORCE_COLOR = prevForceColor
+})
+
 function createProgram() {
   const program = new Command()
   program.exitOverride()
@@ -34,6 +45,14 @@ function createProgram() {
 }
 
 describe('command: status', () => {
+  test('registers description and --json option text', () => {
+    const program = createProgram()
+    const status = program.commands.find(command => command.name() === 'status')
+    expect(status?.description()).toBe('Show auth status for a profile (or all profiles)')
+    const jsonOption = status?.options.find(option => option.long === '--json')
+    expect(jsonOption?.description).toBe('Output machine-readable JSON')
+  })
+
   test('shows auth status for specified profile', async () => {
     mockGetStoredProfile.mockReturnValue({
       name: 'work',
@@ -53,15 +72,23 @@ describe('command: status', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'status', 'work'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('work'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('true'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('me@test.com'))
+    expect(log).toHaveBeenCalledWith('Profile: work')
+    expect(log).toHaveBeenCalledWith('State: ready')
+    expect(log).toHaveBeenCalledWith('Logged in: true')
+    expect(log).toHaveBeenCalledWith('Auth method: claude.ai')
+    expect(log).toHaveBeenCalledWith('Created: 2026-01-01')
+    expect(log).toHaveBeenCalledWith('Email: me@test.com')
+    expect(log).toHaveBeenCalledWith('Subscription: max')
+    // A profile with a directory must NOT print the "missing" line.
+    expect(log).not.toHaveBeenCalledWith('Directory: missing')
   })
 
-  test('fails if profile does not exist', async () => {
+  test('fails with a descriptive message if profile does not exist', async () => {
     mockGetStoredProfile.mockReturnValue(undefined)
+    const errLog = vi.spyOn(console, 'error')
     const program = createProgram()
     await expect(program.parseAsync(['node', 'ccm', 'status', 'ghost'])).rejects.toThrow('exit:1')
+    expect(errLog).toHaveBeenCalledWith(expect.stringContaining('Profile "ghost" does not exist'))
   })
 
   test('shows all profiles when no name given', async () => {
@@ -121,9 +148,9 @@ describe('command: status', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'status', 'work'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('u@t.com'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('pro'))
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('Org'))
+    expect(log).toHaveBeenCalledWith('Email: u@t.com')
+    expect(log).toHaveBeenCalledWith('Org: Org')
+    expect(log).toHaveBeenCalledWith('Subscription: pro')
   })
 
   test('shows unauthenticated state', async () => {
@@ -140,7 +167,8 @@ describe('command: status', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'status', 'work'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('false'))
+    expect(log).toHaveBeenCalledWith('Logged in: false')
+    expect(log).toHaveBeenCalledWith('Auth method: none')
   })
 
   test('shows apiKeySource when email is absent in list view', async () => {
@@ -163,7 +191,10 @@ describe('command: status', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'status'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('env_var'))
+    // Logged-in dot, padded name/auth columns, account from apiKeySource, no drift suffix.
+    expect(log).toHaveBeenCalledWith(
+      `${statusDot(true)} ${'api'.padEnd(20)} ${'api_key'.padEnd(15)} env_var`,
+    )
   })
 
   test('shows dash when both email and apiKeySource absent in list view', async () => {
@@ -185,7 +216,10 @@ describe('command: status', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'status'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('—'))
+    // Logged-out dot and em-dash account placeholder, ready state so no suffix.
+    expect(log).toHaveBeenCalledWith(
+      `${statusDot(false)} ${'bare'.padEnd(20)} ${'none'.padEnd(15)} —`,
+    )
   })
 
   test('prints error when getAuthStatus rejects', async () => {
@@ -252,6 +286,8 @@ describe('command: status', () => {
     expect(mockGetAuthStatus).not.toHaveBeenCalled()
     expect(log).toHaveBeenCalledWith('State: config-only')
     expect(log).toHaveBeenCalledWith('Directory: missing')
+    expect(log).toHaveBeenCalledWith('Logged in: unknown')
+    expect(log).toHaveBeenCalledWith('Auth method: unavailable')
   })
 
   test('marks drift in list view output', async () => {
@@ -269,6 +305,124 @@ describe('command: status', () => {
     const program = createProgram()
     await program.parseAsync(['node', 'ccm', 'status'])
 
-    expect(log).toHaveBeenCalledWith(expect.stringContaining('[config-only]'))
+    // Drifted state appends a bracketed suffix; config-only never queries auth.
+    expect(log).toHaveBeenCalledWith(
+      `${statusDot(false)} ${'stale'.padEnd(20)} ${'unavailable'.padEnd(15)} — [config-only]`,
+    )
+  })
+
+  test('--json prints a single profile view', async () => {
+    mockGetStoredProfile.mockReturnValue({
+      name: 'work',
+      dir: '/tmp/profiles/work',
+      state: 'ready',
+      hasConfig: true,
+      hasDirectory: true,
+      meta: { name: 'work', createdAt: '2026-01-01T00:00:00.000Z' },
+    })
+    mockGetAuthStatus.mockResolvedValue({
+      loggedIn: true,
+      authMethod: 'claude.ai',
+      email: 'u@t.com',
+    })
+    const log = vi.spyOn(console, 'log')
+    const program = createProgram()
+    await program.parseAsync(['node', 'ccm', 'status', 'work', '--json'])
+
+    expect(JSON.parse(log.mock.calls.at(-1)?.[0] as string)).toEqual({
+      name: 'work',
+      state: 'ready',
+      authMethod: 'claude.ai',
+      account: 'u@t.com',
+      loggedIn: true,
+      createdAt: '2026-01-01T00:00:00.000Z',
+      hasConfig: true,
+      hasDirectory: true,
+    })
+    // Human key/value lines must not be printed in JSON mode.
+    expect(log).not.toHaveBeenCalledWith(expect.stringContaining('Auth method:'))
+  })
+
+  test('--json prints an array for all profiles', async () => {
+    mockListStoredProfiles.mockReturnValue([
+      {
+        name: 'bare',
+        dir: '/tmp/profiles/bare',
+        state: 'orphaned',
+        hasConfig: false,
+        hasDirectory: true,
+      },
+    ])
+    mockGetAuthStatus.mockResolvedValue({ loggedIn: false, authMethod: 'none' })
+    const log = vi.spyOn(console, 'log')
+    const program = createProgram()
+    await program.parseAsync(['node', 'ccm', 'status', '--json'])
+
+    expect(JSON.parse(log.mock.calls.at(-1)?.[0] as string)).toEqual([
+      {
+        name: 'bare',
+        state: 'orphaned',
+        authMethod: 'none',
+        account: null,
+        loggedIn: false,
+        createdAt: null,
+        hasConfig: false,
+        hasDirectory: true,
+      },
+    ])
+  })
+
+  test('colors the dot by per-profile login state in the list view', async () => {
+    mockListStoredProfiles.mockReturnValue([
+      {
+        name: 'in',
+        dir: '/tmp/profiles/in',
+        state: 'ready',
+        hasConfig: true,
+        hasDirectory: true,
+        meta: { name: 'in', createdAt: '2026-01-01' },
+      },
+      {
+        name: 'out',
+        dir: '/tmp/profiles/out',
+        state: 'ready',
+        hasConfig: true,
+        hasDirectory: true,
+        meta: { name: 'out', createdAt: '2026-01-02' },
+      },
+    ])
+    mockGetAuthStatus.mockImplementation(async (dir: string) =>
+      dir.endsWith('/in')
+        ? { loggedIn: true, authMethod: 'claude.ai', email: 'a@b.c' }
+        : { loggedIn: false, authMethod: 'none' },
+    )
+    const log = vi.spyOn(console, 'log')
+    const program = createProgram()
+    await program.parseAsync(['node', 'ccm', 'status'])
+
+    // Mixed login states in one run: a constant or flipped dot fails one of the two rows.
+    expect(log).toHaveBeenCalledWith(
+      `${statusDot(true)} ${'in'.padEnd(20)} ${'claude.ai'.padEnd(15)} a@b.c`,
+    )
+    expect(log).toHaveBeenCalledWith(
+      `${statusDot(false)} ${'out'.padEnd(20)} ${'none'.padEnd(15)} —`,
+    )
+    expect(statusDot(true)).not.toBe(statusDot(false))
+  })
+
+  test('omits the Created line when a single profile has no createdAt', async () => {
+    mockGetStoredProfile.mockReturnValue({
+      name: 'nodate',
+      dir: '/tmp/profiles/nodate',
+      state: 'orphaned',
+      hasConfig: false,
+      hasDirectory: true,
+    })
+    mockGetAuthStatus.mockResolvedValue({ loggedIn: false, authMethod: 'none' })
+    const log = vi.spyOn(console, 'log')
+    const program = createProgram()
+    await program.parseAsync(['node', 'ccm', 'status', 'nodate'])
+
+    expect(log).not.toHaveBeenCalledWith(expect.stringContaining('Created:'))
   })
 })
diff --git a/tests/lib/completion.test.ts b/tests/lib/completion.test.ts
new file mode 100644
index 0000000..72433d6
--- /dev/null
+++ b/tests/lib/completion.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'vitest'
+import {
+  type CompletionShell,
+  generateCompletion,
+  parseShell,
+  SUPPORTED_SHELLS,
+} from '../../src/lib/completion.js'
+
+const COMMANDS = ['create', 'list', 'use']
+
+describe('parseShell', () => {
+  test.each(SUPPORTED_SHELLS)('accepts %s', shell => {
+    expect(parseShell(shell)).toBe(shell)
+  })
+
+  test('rejects unsupported shells and lists the supported ones', () => {
+    expect(() => parseShell('powershell')).toThrow(
+      'Unsupported shell "powershell". Supported: bash, zsh, fish',
+    )
+  })
+})
+
+describe('generateCompletion', () => {
+  test('bash script is exact (commands space-joined inside compgen)', () => {
+    expect(generateCompletion('bash', COMMANDS)).toBe(
+      `# ccm bash completion
+_ccm_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "create list use" -- "$cur") )
+  fi
+}
+complete -F _ccm_completions ccm
+`,
+    )
+  })
+
+  test('zsh script is exact (commands quoted and space-joined)', () => {
+    expect(generateCompletion('zsh', COMMANDS)).toBe(
+      `#compdef ccm
+# ccm zsh completion
+_ccm() {
+  local -a commands
+  commands=('create' 'list' 'use')
+  if (( CURRENT == 2 )); then
+    compadd -- \${commands[@]}
+  fi
+}
+compdef _ccm ccm
+`,
+    )
+  })
+
+  test('fish script is exact (one newline-joined complete line per command)', () => {
+    expect(generateCompletion('fish', COMMANDS)).toBe(
+      `complete -c ccm -n "__fish_use_subcommand" -a "create"
+complete -c ccm -n "__fish_use_subcommand" -a "list"
+complete -c ccm -n "__fish_use_subcommand" -a "use"
+`,
+    )
+  })
+
+  test.each(SUPPORTED_SHELLS)('%s script mentions every command', shell => {
+    const script = generateCompletion(shell, COMMANDS)
+    for (const name of COMMANDS) {
+      expect(script).toContain(name)
+    }
+  })
+
+  test('produces distinct scripts per shell', () => {
+    const scripts = SUPPORTED_SHELLS.map((shell: CompletionShell) =>
+      generateCompletion(shell, COMMANDS),
+    )
+    expect(new Set(scripts).size).toBe(SUPPORTED_SHELLS.length)
+  })
+})
diff --git a/tests/lib/profile-view.test.ts b/tests/lib/profile-view.test.ts
new file mode 100644
index 0000000..c7756aa
--- /dev/null
+++ b/tests/lib/profile-view.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, test } from 'vitest'
+import type { StoredProfile } from '../../src/lib/profile-store.js'
+import {
+  accountLabel,
+  authMethodLabel,
+  NO_ACCOUNT_PLACEHOLDER,
+  toProfileView,
+} from '../../src/lib/profile-view.js'
+
+const readyProfile: StoredProfile = {
+  name: 'work',
+  dir: '/tmp/profiles/work',
+  state: 'ready',
+  hasConfig: true,
+  hasDirectory: true,
+  meta: { name: 'work', createdAt: '2026-01-15T00:00:00.000Z' },
+}
+
+describe('accountLabel', () => {
+  test('prefers email', () => {
+    expect(
+      accountLabel({ loggedIn: true, authMethod: 'x', email: 'a@b.c', apiKeySource: 'env' }),
+    ).toBe('a@b.c')
+  })
+
+  test('falls back to apiKeySource when email absent', () => {
+    expect(accountLabel({ loggedIn: true, authMethod: 'x', apiKeySource: 'env' })).toBe('env')
+  })
+
+  test('returns null when neither present', () => {
+    expect(accountLabel({ loggedIn: false, authMethod: 'none' })).toBeNull()
+  })
+
+  test('returns null when status is undefined', () => {
+    expect(accountLabel(undefined)).toBeNull()
+  })
+})
+
+describe('authMethodLabel', () => {
+  test('returns the auth method when present', () => {
+    expect(authMethodLabel({ loggedIn: true, authMethod: 'claude.ai' })).toBe('claude.ai')
+  })
+
+  test('returns "unavailable" when status is undefined', () => {
+    expect(authMethodLabel(undefined)).toBe('unavailable')
+  })
+})
+
+describe('toProfileView', () => {
+  test('projects a ready profile with auth status', () => {
+    expect(
+      toProfileView(readyProfile, { loggedIn: true, authMethod: 'claude.ai', email: 'a@b.c' }),
+    ).toEqual({
+      name: 'work',
+      state: 'ready',
+      authMethod: 'claude.ai',
+      account: 'a@b.c',
+      loggedIn: true,
+      createdAt: '2026-01-15T00:00:00.000Z',
+      hasConfig: true,
+      hasDirectory: true,
+    })
+  })
+
+  test('uses null fields when status and metadata are missing', () => {
+    const orphan: StoredProfile = {
+      name: 'orphan',
+      dir: '/tmp/profiles/orphan',
+      state: 'orphaned',
+      hasConfig: false,
+      hasDirectory: true,
+    }
+    expect(toProfileView(orphan, undefined)).toEqual({
+      name: 'orphan',
+      state: 'orphaned',
+      authMethod: 'unavailable',
+      account: null,
+      loggedIn: null,
+      createdAt: null,
+      hasConfig: false,
+      hasDirectory: true,
+    })
+  })
+})
+
+describe('NO_ACCOUNT_PLACEHOLDER', () => {
+  test('is the em dash', () => {
+    expect(NO_ACCOUNT_PLACEHOLDER).toBe('—')
+  })
+})

From a7b0d9da94ddb5239d2e8df65a71e58de10982ae Mon Sep 17 00:00:00 2001
From: Giulio Fagioli <fagioli.giulio@gmail.com>
Date: Mon, 1 Jun 2026 11:56:59 +0200
Subject: [PATCH 3/4] docs: add ARCHITECTURE, CLAUDE.md, editorconfig; document
 new features

ARCHITECTURE.md covers state reconciliation, the transactional
stage/rollback protocol, the testability DI seam, and why error handling
lives in runAction rather than index.ts. README documents --json and shell
completion; CLAUDE.md captures the build/test/mutation invariants.
---
 .editorconfig   |  12 +++++
 ARCHITECTURE.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md       |  55 +++++++++++++++++++++++
 CONTRIBUTING.md |   4 +-
 README.md       |  49 ++++++++++++++++++++-
 5 files changed, 232 insertions(+), 3 deletions(-)
 create mode 100644 .editorconfig
 create mode 100644 ARCHITECTURE.md
 create mode 100644 CLAUDE.md

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..8c52ff9
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..950933d
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,115 @@
+# Architecture
+
+This document explains the non-obvious design decisions in `ccm` — the ones that aren't visible from
+the command list. The headline ideas: profiles have **no single source of truth**, so state is
+*reconciled*; and every destructive operation is **transactional**, so a mid-operation failure never
+leaves a half-migrated profile.
+
+## State model
+
+A profile is not one thing. It is up to three independent pieces of on-disk state:
+
+| Piece            | Location                          | Owner            |
+| ---------------- | --------------------------------- | ---------------- |
+| Metadata         | `~/.ccm/config.json` (`profiles`) | ccm              |
+| Config directory | `~/.ccm/profiles/<name>/`         | Claude Code      |
+| Browser wrapper  | `~/.ccm/browsers/<name>`          | ccm (optional)   |
+
+These can drift out of sync — a directory deleted by hand, a config edited externally, a crash
+between two writes. Rather than trust one source, `listStoredProfiles` / `getStoredProfile`
+(`src/lib/profile-store.ts`) **reconcile** the config keys with the filesystem and classify each
+profile into a state:
+
+- `ready` — present in both config and filesystem (the normal case).
+- `orphaned` — directory exists, but no config entry.
+- `config-only` — config entry exists, but no directory.
+
+`ccm list` and `ccm status` surface these states so drift is visible instead of silently misleading.
+`profile-view.ts` projects this reconciled view (plus live Claude auth status) into the serializable
+shape emitted by `--json`.
+
+## Transactional protocol
+
+`remove`, `rename`, and `copy-config` each mutate more than one of the three state pieces. A naive
+implementation deletes/renames/copies in sequence and hopes nothing throws halfway. ccm instead uses a
+**stage → mutate → finalize** protocol with rollback, so each operation is all-or-nothing.
+
+### Why staging exists
+
+`rename(2)` is atomic on a POSIX filesystem; a recursive copy is not. So:
+
+- **Removal** (`removeStoredProfile`) does not delete eagerly. It first *stages* the directory and
+  browser wrapper by renaming them aside (`stageProfileDirRemoval` →
+  `.<name>.staged-<pid>-<timestamp>`), then removes the config entry, then *finalizes* by deleting the
+  staged copies. If the config write fails, the staged assets are renamed back. If finalization fails,
+  both the assets and the config entry are restored.
+- **Rename** (`renameStoredProfile`) renames the directory, then the browser wrapper, then the config
+  entry — each step guarded. A failure at any step rolls the prior steps back in reverse order before
+  re-throwing.
+- **Copy** (`applyProfileConfigCopy` in `profile-config-copy.ts`) stages any path it is about to
+  overwrite (rename to a staged path), copies the new content, then deletes the staged originals. On
+  failure it removes what it copied and renames the staged originals back.
+
+### Rollback runs in reverse
+
+`rollbackCopy` undoes work in the opposite order it was applied: remove copied targets newest-first,
+then restore staged originals newest-first. Reverse order matters because later operations can depend
+on earlier ones (a created parent directory, an overwritten file shadowing a staged one). Unwinding a
+stack in LIFO order is the only ordering that is always safe.
+
+### Staged path safety
+
+`getStagedPath` builds the temporary name from `process.pid` + `Date.now()`, with an incrementing
+suffix and a 100-attempt cap. The PID component keeps two concurrent `ccm` processes from colliding on
+the same staged path; the timestamp + counter handle repeats within one process. If all 100 candidates
+are somehow taken, it throws rather than guess — failing loudly beats clobbering a real file.
+
+### Rollback-of-rollback
+
+Rollback can itself fail (a filesystem that broke mid-operation may also break during recovery). The
+code never swallows that. It aggregates recovery errors and folds them into the thrown message —
+`Failed to remove profile "x": <original>. Recovery failed: <details>` — so the user learns both what
+went wrong *and* that the automatic repair didn't fully succeed, including which assets to inspect by
+hand. This is the difference between "operation failed, state intact" and "operation failed, state
+unknown" — and the message tells you which.
+
+## Testability is a design constraint, not an afterthought
+
+Every library function takes its filesystem roots as parameters that default to the real paths:
+
+```ts
+export function listStoredProfiles(
+  configFile = CONFIG_FILE,
+  profilesDir = PROFILES_DIR,
+): StoredProfile[]
+```
+
+This dependency-injection seam is deliberate. It lets tests run against temp directories with zero
+global mocking, and it is *why* 100% line, branch, function, and mutation coverage is achievable on
+real file I/O instead of stubs. When adding a function that touches disk, keep the seam.
+
+## Error handling: `runAction`, not a top-level catch
+
+CLI commands wrap their action body in `runAction` (`src/lib/run-action.ts`), which prints a single
+`✗ <message>` line and exits with code 1 on any throw or rejection. It runs synchronous actions
+synchronously (so failures surface on the same tick, which the tests rely on) and only awaits when the
+action returns a promise.
+
+The tempting alternative — one `try/catch` around `program.parse()` in `index.ts` — was rejected on
+purpose. `index.ts` is excluded from coverage (it is pure command registration), so putting error
+logic there would hide it from the 100% gate. `runAction` lives in a covered, mutation-tested library
+file, so the behavior every command depends on is actually verified. Honest coverage over convenient
+coverage.
+
+Output styling (colors, icons, the `✓`/`✗`/`!`/`●` glyphs) is centralized in `src/lib/ui.ts`, built on
+`node:util` `styleText`. Because `styleText` degrades to plain text on a non-TTY or under `NO_COLOR`,
+piping `ccm list` or `--json` into another tool yields clean, escape-free strings without any
+command-level branching.
+
+## Privacy boundary
+
+ccm never reads, parses, or copies Claude auth tokens. It manipulates *directories* and sets
+`CLAUDE_CONFIG_DIR`; Claude Code owns everything inside a profile dir. `ccm copy-config` is explicitly
+scoped to non-auth config (`settings.json`, `plugins`) and refuses anything else. Auth status shown by
+`ccm status` comes from invoking `claude auth status --json` in the profile's environment, not from
+inspecting credentials directly.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2635ab0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+Guidance for AI agents (and humans) working in this repo. See `ARCHITECTURE.md` for the design
+deep-dive.
+
+## What this is
+
+`ccm` (`@remeic/ccm`) — nvm-like manager for Claude Code profiles. Each profile is an isolated
+`CLAUDE_CONFIG_DIR`, so multiple Claude accounts can coexist without re-login. CLI built on
+`commander` + `zod`. Zero other runtime deps — keep it that way.
+
+## Commands
+
+Bun is the dev package manager (`bun.lock`). Node 24 (`.nvmrc`, `engines`).
+
+```bash
+bun install
+bun run build           # tsup → single ESM file in dist/
+bun run dev             # tsup watch
+bun run test            # vitest
+bun run test:coverage   # vitest + coverage (gate)
+bun run test:mutation   # stryker (gate)
+bun run lint            # biome check
+bun run lint:fix        # biome check --write
+bun run format          # biome format
+```
+
+## Non-negotiable invariants
+
+- **100% coverage** (vitest, all of branches/functions/lines/statements) and **100% mutation**
+  (Stryker, `break: 100`). Any new code must be fully tested AND mutation-proof. CI enforces both.
+- **Every new `src/lib/*.ts` and mutated `src/commands/*.ts` must be added to `stryker.config.mjs`
+  `mutate[]`.** Omitting it silently weakens the 100%-mutation claim — a reviewer will diff `mutate[]`
+  against `src/`. Add a direct `tests/lib/*.test.ts` for each new lib file; don't rely on caller
+  coverage to kill mutants.
+- `src/index.ts` and `src/types.ts` are excluded from coverage — keep them logic-free (registration
+  and schemas only). Don't move testable logic there to dodge the gate.
+
+## Conventions
+
+- **ESM `.js` import specifiers** in `.ts` source (e.g. `import { x } from './foo.js'`) — required by
+  the bundler's module resolution. New files follow this.
+- **Layering:** `src/lib/*` = pure, testable logic (named exports + `/** JSDoc */`). `src/commands/*` =
+  CLI wiring (commander registration, I/O). Keep UI out of logic.
+- **UI/output:** colors, icons, and print helpers live in `src/lib/ui.ts` (built on `node:util`
+  `styleText`, NO_COLOR/non-TTY aware). Never hand-write `\x1b[...` escapes in commands.
+- **Errors:** `formatError` in `src/lib/errors.ts`; CLI error handling via `runAction` in
+  `src/lib/run-action.ts` (prints `✗ message` + `exit(1)`). Don't re-add per-command try/catch
+  boilerplate; keep only inner try/catch that carries real rollback semantics.
+- **Dependency-injectable seams:** lib functions take `configFile`/`profilesDir`/`browsersDir` params
+  defaulting to the real paths. This is what makes 100% coverage achievable — preserve the pattern.
+- **Validation:** all external input via zod schemas in `src/types.ts` (profile names, config shape,
+  Claude auth status). Parse with `.safeParse` and degrade gracefully.
+- Biome style: single quotes, no semicolons, trailing commas, 100-col width. Conventional Commits
+  (commitlint-enforced).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index deff891..a004f05 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,7 +16,9 @@ The codebase separates pure logic from CLI wiring:
 - `src/lib/` — core modules (config I/O, profile management, Claude interaction). No CLI framework dependencies.
 - `src/commands/` — thin Commander.js command registrations that call into `lib/`.
 
-This makes the core logic independently testable without mocking the CLI framework.
+This makes the core logic independently testable without mocking the CLI framework. For the design
+rationale (state reconciliation, the transactional stage/rollback protocol, and why error handling
+lives in `runAction` rather than `index.ts`), see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Development
 
diff --git a/README.md b/README.md
index 2f9c13e..b5675bb 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,8 @@ Manage separate Claude Code profiles for personal, work, and client accounts wit
 - [Quick Start](#quick-start)
 - [Commands](#commands)
 - [Compliance Notice](#compliance-notice)
+- [Scripting (JSON Output)](#scripting-json-output)
+- [Shell Completion](#shell-completion)
 - [Passing Flags and Environment Variables](#passing-flags-and-environment-variables)
 - [Multi-Account Login](#multi-account-login)
   - [Different Browser per Profile](#different-browser-per-profile)
@@ -135,15 +137,16 @@ $ ccm use work
 | -------------------------------------------------------- | ------------------------------------------------------------- |
 | `ccm create <name> [-l label] [-b browser] [--from p]`   | Create a profile. `--from` seeds non-auth config              |
 | `ccm compliance` / `ccm tos`                             | Show the compliance notice, disclaimer, and official sources  |
-| `ccm list`                                               | List all profiles with auth status, including drifted entries |
+| `ccm list [--json]`                                      | List all profiles with auth status, including drifted entries. `--json` for scripts |
 | `ccm use <name> [args...]`                               | Launch Claude Code. Extra args are passed to Claude            |
 | `ccm login <name> [--console] [-b browser] [--url-only]` | Authenticate a profile                                        |
-| `ccm status [name]`                                      | Show auth status and storage state for one or all profiles    |
+| `ccm status [name] [--json]`                             | Show auth status and storage state for one or all profiles. `--json` for scripts |
 | `ccm rename <old-name> <new-name>`                       | Rename a profile (config, directory, and browser wrapper)     |
 | `ccm remove <name> [-f]`                                 | Remove a profile. `-f` skips confirmation                     |
 | `ccm copy-config <source> <target> [--only x] [--dry-run] [-f]` | Copy non-auth config (settings/hooks/skills plugins) |
 | `ccm run <name> -p <prompt>`                             | Run a prompt non-interactively                                |
 | `ccm skills <add\|list\|remove\|update> <name> [repos...]` | Manage skills scoped to a profile (wraps `npx skills`)       |
+| `ccm completion <bash\|zsh\|fish>`                       | Print a shell completion script                               |
 
 ## Compliance Notice
 
@@ -162,6 +165,39 @@ The notice is intentionally conservative:
 - If a team needs parallel access, they should use separate seats/accounts or API-key-based access under applicable Anthropic commercial terms.
 - The notice is compliance guidance, not legal advice. Users remain responsible for reviewing Anthropic terms for their exact workflow.
 
+## Scripting (JSON Output)
+
+`ccm list` and `ccm status` accept `--json` for machine-readable output you can pipe into `jq` or
+other tooling. Color is automatically disabled when output is not a TTY (or when `NO_COLOR` is set),
+so human-facing commands stay clean in pipes and logs.
+
+```bash
+# All profiles as JSON
+ccm list --json | jq '.[] | select(.loggedIn) | .name'
+
+# A single profile
+ccm status work --json | jq '.account'
+```
+
+Each entry: `{ name, state, authMethod, account, loggedIn, createdAt, hasConfig, hasDirectory }`.
+Unknown values are `null` (never the `—` placeholder used in the human table).
+
+## Shell Completion
+
+`ccm completion <shell>` prints a completion script. The command list is derived from the live
+command registry, so it never drifts as commands are added.
+
+```bash
+# zsh
+ccm completion zsh > "${fpath[1]}/_ccm"
+
+# bash
+ccm completion bash >> ~/.bashrc
+
+# fish
+ccm completion fish > ~/.config/fish/completions/ccm.fish
+```
+
 ## Passing Flags and Environment Variables
 
 Extra args in `ccm use` are forwarded to `claude` (with or without the `--` separator). Env vars from your shell are inherited.
@@ -307,10 +343,16 @@ src/
 │   ├── profiles.ts          # Profile directory management and validation
 │   ├── profile-store.ts     # Reconciled config/filesystem profile view
 │   ├── profile-config-copy.ts # Config copy planner + transactional apply/rollback
+│   ├── profile-view.ts      # Serializable projection shared by list/status (incl. --json)
 │   ├── claude.ts            # Claude binary discovery, spawning, auth status
 │   ├── compliance.ts        # Centralized compliance notice text and official sources
+│   ├── completion.ts        # Shell completion script generation (bash/zsh/fish)
+│   ├── errors.ts            # Shared error-message formatting
+│   ├── run-action.ts        # Wraps command actions with uniform error handling
+│   ├── ui.ts                # Terminal output helpers (NO_COLOR/TTY-aware)
 │   └── browsers.ts          # Browser wrapper generation and validation
 └── commands/
+    ├── completion.ts        # Emit a shell completion script
     ├── copy-config.ts       # Copy non-auth config between profiles (dry-run + rollback)
     ├── compliance.ts        # Dedicated compliance/TOS command
     ├── create.ts            # Create profile (with rollback on failure)
@@ -323,6 +365,9 @@ src/
     └── run.ts               # Run prompt with specific profile
 ```
 
+For the design rationale behind the reconciled profile store and the transactional
+staging/rollback used by remove, rename, and copy-config, see **[ARCHITECTURE.md](ARCHITECTURE.md)**.
+
 ### Profile Isolation
 
 Claude Code reads auth tokens, settings, and project data from whatever directory `CLAUDE_CONFIG_DIR` points to. ccm exploits this by creating a separate directory per profile and setting this environment variable when spawning Claude:

From c57743c055a328f20b8b661fb847fe2a8e5a67bd Mon Sep 17 00:00:00 2001
From: Giulio Fagioli <fagioli.giulio@gmail.com>
Date: Mon, 1 Jun 2026 11:57:23 +0200
Subject: [PATCH 4/4] chore: ignore Stryker reports/ output directory

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index b4237d4..fbdb8fd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ coverage/
 .DS_Store
 .stryker-tmp/
 mutation-report/
+reports/