@nemus-cli/nemus 0.4.0 → 0.8.0

package/src/commands/reflect.ts

@@ -1,15 +1,21 @@
 import { Command } from 'commander';
-import { logError, logInfo, logStep } from '../utils/logger';
+import { logError, logInfo, logStep, logWarning } from '../utils/logger';
 import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import {
   gatherReflectionCorpus,
   parseReflectionReport,
   saveReflectionReport,
+  renderReportMarkdown,
+  severitySummary,
+  groupRecommendations,
+  listSavedReports,
+  findSavedMatches,
   REFLECT_SCHEMA,
   ReflectionReport,
   ReflectProgress,
   Recommendation,
+  GroupBy,
 } from '../utils/reflect';
 import { analyzeCorpus, buildAnalysisPrompt } from '../utils/reflect-analyze';
 import { runAgentJsonAsync } from '../utils/agent-judge';
@@ -18,31 +24,63 @@ export function registerReflectCommand(parent: Command) {
   parent
     .command('reflect')
     .alias('retro')
-    .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
+    .description('Analyze recent sessions for improvements, or review saved reports ("history"/"show")')
+    .argument('[subcommand]', '"history" or "show" — omit to run a new analysis')
+    .argument('[id]', 'report id when using "show" (default: latest)')
     .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
     .option('-w, --workspace <name>', 'Analyze a single workspace by name (ignores --limit)')
     .option('--model <model>', 'Judge model override (agent-native pattern/id)')
     .option('--thinking <level>', 'Judge thinking level for pi: off|minimal|low|medium|high|xhigh|max')
     .option('--json', 'Output the report as JSON')
+    .option('--markdown', 'Output the report as Markdown (paste into an issue/PR)')
+    .option('--group-by <how>', 'Group recommendations by: priority | kind', 'priority')
     .option('--no-save', 'Do not save the report to ~/.nemus/reflect/')
     .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
-    .action(async (opts) => {
-      await handleReflect(opts);
+    .addHelpText(
+      'after',
+      '\nSaved reports:\n  nemus reflect history            List saved reports (newest first)\n  nemus reflect show [id]          Print a saved report (default: latest)\n',
+    )
+    // history/show are positional (not commander subcommands) on purpose: as
+    // subcommands they would share --json/--markdown/--group-by with this parent
+    // command, and the only commander fix (enablePositionalOptions on the root)
+    // breaks global flags placed after a subcommand (e.g. `nemus list --quiet`).
+    .action(async (subcommand: string | undefined, id: string | undefined, opts) => {
+      if (subcommand === 'history') return handleHistory(opts);
+      if (subcommand === 'show') return handleShow(id, opts);
+      if (subcommand !== undefined) {
+        const msg = `Unknown reflect subcommand "${subcommand}" (expected "history" or "show").`;
+        if (opts.json) outputJsonError(msg);
+        else logError(msg);
+        process.exit(1);
+      }
+      return handleReflect(opts);
     });
 }
 
+/** Validate --group-by; returns the value or exits non-zero with a clear error. */
+function resolveGroupBy(raw: string | undefined, json?: boolean): GroupBy {
+  if (raw === undefined || raw === 'priority' || raw === 'kind') return (raw ?? 'priority') as GroupBy;
+  const msg = `--group-by must be "priority" or "kind"; got "${raw}"`;
+  if (json) outputJsonError(msg);
+  else logError(msg);
+  process.exit(1);
+}
+
 async function handleReflect(opts: {
   limit?: string;
   workspace?: string;
   model?: string;
   thinking?: string;
   json?: boolean;
+  markdown?: boolean;
+  groupBy?: string;
   save?: boolean; // commander sets `save: false` for --no-save
   dryRun?: boolean;
 }) {
   const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
+  const groupBy = resolveGroupBy(opts.groupBy, opts.json);
   try {
-    const showProgress = !opts.json && !opts.dryRun;
+    const showProgress = !opts.json && !opts.markdown && !opts.dryRun;
     if (showProgress) {
       logStep(
         opts.workspace
@@ -85,7 +123,7 @@ async function handleReflect(opts: {
     const timeoutMs = Number.parseInt(process.env.NEMUS_JUDGE_TIMEOUT_MS ?? '', 10) || undefined;
     const model = opts.model ?? process.env.NEMUS_JUDGE_MODEL ?? undefined;
     const thinking = opts.thinking ?? process.env.NEMUS_JUDGE_THINKING ?? undefined;
-    const stopSpinner = opts.json
+    const stopSpinner = opts.json || opts.markdown
       ? () => {}
       : startSpinner(`Judging ${withSessions} session(s) with your configured agent (this can take a minute)…`);
     let parsed: unknown;
@@ -114,7 +152,25 @@ async function handleReflect(opts: {
       outputJson({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report, savedTo });
       return;
     }
-    printReport(report, corpus.workspaces.length, withSessions);
+    if (opts.markdown) {
+      // DATA channel: markdown to stdout, nothing else (a 'Saved report' note
+      // would corrupt a redirected .md file), so surface the path on stderr.
+      process.stdout.write(
+        renderReportMarkdown(
+          report,
+          {
+            analyzed: withSessions,
+            workspaces: corpus.workspaces.length,
+            workspace: opts.workspace,
+            generatedAt: new Date().toISOString(),
+          },
+          groupBy,
+        ),
+      );
+      if (savedTo) logInfo(`Saved report to ${colorize(savedTo, 'dim')}`);
+      return;
+    }
+    printReport(report, corpus.workspaces.length, withSessions, groupBy);
     if (savedTo) logInfo(`Saved report to ${colorize(savedTo, 'dim')}`);
   } catch (error) {
     const msg = error instanceof Error ? error.message : 'reflect failed';
@@ -183,7 +239,7 @@ function priorityBadge(p: Recommendation['priority']): string {
   return colorize('● low', 'gray');
 }
 
-function printReport(report: ReflectionReport, workspaces: number, analyzed: number) {
+function printReport(report: ReflectionReport, workspaces: number, analyzed: number, groupBy: GroupBy = 'priority') {
   console.log('');
   console.log(colorize('  Reflection', 'bright') + colorize(`  (${analyzed} sessions across ${workspaces} workspaces)`, 'dim'));
   console.log(colorize('  ' + '─'.repeat(56), 'dim'));
@@ -196,19 +252,99 @@ function printReport(report: ReflectionReport, workspaces: number, analyzed: num
     return;
   }
 
-  // High priority first.
-  const order = { high: 0, medium: 1, low: 2 };
-  const recs = [...report.recommendations].sort((a, b) => order[a.priority] - order[b.priority]);
+  console.log('\n  ' + colorize(severitySummary(report.recommendations), 'dim'));
 
-  console.log('');
-  for (const r of recs) {
-    const target = r.target ? colorize(`  [${r.target}]`, 'cyan') : '';
-    console.log(`  ${priorityBadge(r.priority)}  ${colorize(KIND_LABEL[r.kind], 'bright')}  ${r.title}${target}`);
-    if (r.detail) console.log(`      ${r.detail.replace(/\n/g, '\n      ')}`);
-    if (r.example) {
-      console.log(colorize('      example:', 'dim'));
-      console.log(colorize(r.example.replace(/^/gm, '        '), 'dim'));
+  for (const group of groupRecommendations(report.recommendations, groupBy)) {
+    console.log('\n  ' + colorize(group.heading, 'bright'));
+    for (const r of group.recs) {
+      const target = r.target ? colorize(`  [${r.target}]`, 'cyan') : '';
+      // Under a kind heading show the priority badge; under a priority heading
+      // show the kind label (the heading conveys the other axis).
+      const lead = groupBy === 'kind' ? priorityBadge(r.priority) : colorize(KIND_LABEL[r.kind], 'bright');
+      console.log(`    ${lead}  ${r.title}${target}`);
+      if (r.detail) console.log(`      ${r.detail.replace(/\n/g, '\n      ')}`);
+      if (r.example) {
+        console.log(colorize('      example:', 'dim'));
+        console.log(colorize(r.example.replace(/^/gm, '        '), 'dim'));
+      }
     }
-    console.log('');
   }
+  console.log('');
+}
+
+async function handleHistory(opts: { json?: boolean }) {
+  const reports = await listSavedReports();
+  if (opts.json) {
+    outputJson({
+      count: reports.length,
+      reports: reports.map((r) => ({
+        id: r.id,
+        generatedAt: r.generatedAt,
+        analyzed: r.analyzed,
+        workspaces: r.workspaces,
+        workspace: r.workspace,
+        recommendations: r.report.recommendations.length,
+        severity: severitySummary(r.report.recommendations),
+      })),
+    });
+    return;
+  }
+  if (reports.length === 0) {
+    logInfo('No saved reflection reports yet. Run `nemus reflect` to create one.');
+    return;
+  }
+  console.log('');
+  console.log(colorize('  Saved reflections', 'bright') + colorize(`  (${reports.length})`, 'dim'));
+  console.log(colorize('  ' + '─'.repeat(56), 'dim'));
+  for (const r of reports) {
+    const when = r.generatedAt ? new Date(r.generatedAt).toLocaleString() : r.id;
+    const scope = r.workspace ? colorize(` ${r.workspace}`, 'cyan') : colorize(` ${r.analyzed} sessions`, 'dim');
+    const sev = r.report.recommendations.length
+      ? colorize(`  ${severitySummary(r.report.recommendations)}`, 'dim')
+      : colorize('  no recs', 'green');
+    console.log(`  ${colorize(r.id, 'bright')}${scope}${sev}`);
+    console.log(colorize(`     ${when}`, 'dim'));
+  }
+  console.log('');
+  console.log(colorize('  nemus reflect show <id>   (or `latest`)', 'dim'));
+}
+
+async function handleShow(
+  id: string | undefined,
+  opts: { json?: boolean; markdown?: boolean; groupBy?: string },
+) {
+  const groupBy = resolveGroupBy(opts.groupBy, opts.json);
+  const matches = findSavedMatches(await listSavedReports(), id);
+  const saved = matches[0];
+  if (!saved) {
+    const msg = id && id !== 'latest'
+      ? `No saved report matching "${id}". Run "nemus reflect history" to list them.`
+      : 'No saved reflection reports yet. Run "nemus reflect" to create one.';
+    if (opts.json) outputJsonError(msg);
+    else logError(msg);
+    process.exit(1);
+  }
+  // An id-prefix that matches several reports resolves to the newest — say so
+  // (stderr only, so --json/--markdown stdout stays clean) rather than quietly
+  // showing a possibly-unintended report. An exact id / "latest" never multi-matches.
+  if (matches.length > 1 && !opts.json) {
+    logWarning(
+      `"${id}" matched ${matches.length} reports; showing the newest (${saved.id}). Use a longer id to disambiguate.`,
+    );
+  }
+  const meta = {
+    analyzed: saved.analyzed,
+    workspaces: saved.workspaces,
+    workspace: saved.workspace,
+    generatedAt: saved.generatedAt,
+  };
+  if (opts.json) {
+    outputJson({ id: saved.id, ...meta, ...saved.report });
+    return;
+  }
+  if (opts.markdown) {
+    process.stdout.write(renderReportMarkdown(saved.report, meta, groupBy));
+    return;
+  }
+  printReport(saved.report, saved.workspaces, saved.analyzed, groupBy);
 }

package/src/program.ts

@@ -1,28 +1,20 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { colors } from './utils/colors';
+import { setColorEnabled } from './utils/colors';
+import { renderHelpBanner } from './utils/banner';
+import { applyGlobalFlags } from './utils/global-flags';
 
 // Read version from package.json
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 
-const g = colors.green;
-const d = colors.dim;
-const b = colors.bright;
-const r = colors.reset;
-
-const INNER = 38;
-const titleLine = `>_  Nemus`;
-const titlePad = ' '.repeat(Math.max(0, INNER - 2 - titleLine.length));
-const versionLine = `v${pkg.version} · multi-repo workspaces`;
-const versionPad = ' '.repeat(Math.max(0, INNER - 7 - versionLine.length));
-const bar = '─'.repeat(INNER);
-const bannerText = `
-${d}    ╭${bar}╮${r}
-${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}${titlePad}${d}│${r}
-${d}    │${r}       ${d}${versionLine}${r}${versionPad}${d}│${r}
-${d}    ╰${bar}╯${r}
-`;
+// --no-color must be applied BEFORE commander parses so it reaches the help
+// banner (a preAction hook is too late for help output, and ES imports run
+// before hooks). It's a long flag, so it can't be bundled — an argv scan is
+// sufficient here. colors.ts already applied NO_COLOR / non-TTY at import.
+// --quiet is handled in the preAction hook below (it only affects command
+// logs, never help), which also catches bundled short forms like `-yq`.
+if (process.argv.includes('--no-color')) setColorEnabled(false);
 
 export const program = new Command();
 
@@ -32,7 +24,15 @@ program
   .version(pkg.version, '-V, --version')
   .option('-f, --force-refresh', 'Force refresh GitHub repos (skip cache)')
   .option('-y, --yes', 'Skip confirmations')
-  .addHelpText('before', bannerText);
+  .option('--no-color', 'Disable colored output (also honors NO_COLOR)')
+  .option('-q, --quiet', 'Suppress progress logs (keep warnings + errors)')
+  .addHelpText('before', () => renderHelpBanner(pkg.version));
+
+// Apply global --quiet / --color from commander's PARSED options (robust to
+// bundled short flags like `-yq` that a raw argv scan misses). Runs before every
+// command action; help output doesn't reach here, which is why --no-color is
+// also pre-scanned above.
+program.hook('preAction', () => applyGlobalFlags(program.opts()));
 
 // Register top-level commands
 import { registerCreateCommand } from './commands/create';
@@ -53,6 +53,7 @@ import { registerArchiveCommand } from './commands/archive';
 import { registerSessionsCommand } from './commands/sessions';
 import { registerGenerateDocsCommand } from './commands/generate-docs';
 import { registerConfigureCommand } from './commands/configure';
+import { registerConfigCommand } from './commands/config';
 import { registerConfigureClaudeCommand } from './commands/configure-claude';
 import { registerGhqStatusCommand } from './commands/ghq-status';
 import { registerSaveContextCommand } from './commands/save-context';
@@ -79,6 +80,7 @@ registerArchiveCommand(program);
 registerSessionsCommand(program);
 registerGenerateDocsCommand(program);
 registerConfigureCommand(program);
+registerConfigCommand(program);
 registerConfigureClaudeCommand(program);
 registerGhqStatusCommand(program);
 registerSaveContextCommand(program);

package/src/utils/banner.ts

@@ -1,17 +1,5 @@
 import { colors } from './colors';
 
-const g = colors.green;
-const d = colors.dim;
-const b = colors.bright;
-const r = colors.reset;
-
-export const BANNER = `
-${d}    ╭──────────────────────────────────────╮${r}
-${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}                           ${d}│${r}
-${d}    │${r}       ${d}multi-repo workspaces${r}          ${d}│${r}
-${d}    ╰──────────────────────────────────────╯${r}
-`;
-
 export const BANNER_PLAIN = `
     ╭──────────────────────────────────────╮
     │  >_  Nemus                           │
@@ -19,6 +7,37 @@ export const BANNER_PLAIN = `
     ╰──────────────────────────────────────╯
 `;
 
+// Rendered live (not captured at import) so --no-color / NO_COLOR applied before
+// this is called produce a plain banner. With color off, every colors.* is ''.
+export const renderBanner = (): string => {
+  const { green: g, dim: d, bright: b, reset: r } = colors;
+  return `
+${d}    ╭──────────────────────────────────────╮${r}
+${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}                           ${d}│${r}
+${d}    │${r}       ${d}multi-repo workspaces${r}          ${d}│${r}
+${d}    ╰──────────────────────────────────────╯${r}
+`;
+};
+
 export const printBanner = (): void => {
-  console.log(BANNER);
+  console.log(renderBanner());
+};
+
+// The `--help` banner: a boxed splash with the version + tagline, width-fitted.
+// Lives here alongside renderBanner() so the two renderers don't drift; also
+// rendered live so --no-color / NO_COLOR yields a plain box.
+export const renderHelpBanner = (version: string): string => {
+  const { green: g, dim: d, bright: b, reset: r } = colors;
+  const INNER = 38;
+  const titleLine = `>_  Nemus`;
+  const titlePad = ' '.repeat(Math.max(0, INNER - 2 - titleLine.length));
+  const versionLine = `v${version} · multi-repo workspaces`;
+  const versionPad = ' '.repeat(Math.max(0, INNER - 7 - versionLine.length));
+  const bar = '─'.repeat(INNER);
+  return `
+${d}    ╭${bar}╮${r}
+${d}    │${r}  ${g}>_${r}  ${b}Nemus${r}${titlePad}${d}│${r}
+${d}    │${r}       ${d}${versionLine}${r}${versionPad}${d}│${r}
+${d}    ╰${bar}╯${r}
+`;
 };

package/src/utils/colors.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { colors, colorize, setColorEnabled, isColorEnabled, detectColorEnabled } from './colors';
+
+// Tests toggle global color state; restore a known state afterward.
+afterEach(() => setColorEnabled(true));
+
+describe('setColorEnabled / colorize', () => {
+  it('wraps with ANSI when on, and is plain when off (same call sites)', () => {
+    setColorEnabled(true);
+    expect(isColorEnabled()).toBe(true);
+    const on = colorize('hi', 'green');
+    expect(on).toContain('\x1b[32m');
+    expect(on).toContain('\x1b[0m');
+    expect(on).toContain('hi');
+
+    setColorEnabled(false);
+    expect(isColorEnabled()).toBe(false);
+    expect(colorize('hi', 'green')).toBe('hi'); // no codes at all
+  });
+
+  it('empties inline colors.* codes in place when disabled', () => {
+    setColorEnabled(false);
+    expect(colors.gray).toBe('');
+    expect(colors.reset).toBe('');
+    setColorEnabled(true);
+    expect(colors.gray).toBe('\x1b[90m');
+  });
+});
+
+describe('detectColorEnabled', () => {
+  it('NO_COLOR disables regardless of value (even empty)', () => {
+    expect(detectColorEnabled({ NO_COLOR: '1' }, true)).toBe(false);
+    expect(detectColorEnabled({ NO_COLOR: '' }, true)).toBe(false);
+  });
+
+  it('FORCE_COLOR forces on even without a TTY (but 0/false do not)', () => {
+    expect(detectColorEnabled({ FORCE_COLOR: '1' }, false)).toBe(true);
+    expect(detectColorEnabled({ FORCE_COLOR: '0' }, false)).toBe(false);
+    expect(detectColorEnabled({ FORCE_COLOR: 'false' }, false)).toBe(false);
+  });
+
+  it('NO_COLOR beats FORCE_COLOR', () => {
+    expect(detectColorEnabled({ NO_COLOR: '1', FORCE_COLOR: '1' }, true)).toBe(false);
+  });
+
+  it('otherwise follows the TTY, and TERM=dumb disables', () => {
+    expect(detectColorEnabled({}, true)).toBe(true);
+    expect(detectColorEnabled({}, false)).toBe(false);
+    expect(detectColorEnabled({ TERM: 'dumb' }, true)).toBe(false);
+  });
+});

package/src/utils/colors.ts

@@ -1,4 +1,7 @@
-export const colors = {
+// ANSI escape codes. `colors` starts as a copy of these but is emptied in place
+// when color is disabled (--no-color / NO_COLOR / non-TTY), so BOTH `colorize()`
+// and inline `colors.x` template usage go plain without touching call sites.
+const ANSI = {
   reset: '\x1b[0m',
   bright: '\x1b[1m',
   dim: '\x1b[2m',
@@ -18,8 +21,52 @@ export const colors = {
   bgGreen: '\x1b[42m',
   bgYellow: '\x1b[43m',
   bgBlue: '\x1b[44m',
-};
+} as const;
+
+export type ColorName = keyof typeof ANSI;
+
+// Live map read at every use. Mutated in place by setColorEnabled so previously
+// imported references (e.g. `colors.gray` inside a template) see the change.
+export const colors: Record<ColorName, string> = { ...ANSI };
+
+let enabled = true;
 
-export const colorize = (text: string, color: keyof typeof colors): string => {
+/** Whether colored output is currently on. */
+export const isColorEnabled = (): boolean => enabled;
+
+/** Turn color on/off. When off, every `colors.*` code becomes '' so output is
+ *  plain; when on, the ANSI codes are restored. */
+export function setColorEnabled(on: boolean): void {
+  enabled = on;
+  for (const key of Object.keys(ANSI) as ColorName[]) {
+    colors[key] = on ? ANSI[key] : '';
+  }
+}
+
+/**
+ * Decide whether to use color by default, following the common conventions:
+ * - `NO_COLOR` (any value, even empty) disables — see https://no-color.org
+ * - `FORCE_COLOR` (and not "0"/"false") forces it on, even when not a TTY
+ * - otherwise on only when the stdout stream is a TTY and `TERM` isn't `dumb`
+ */
+export function detectColorEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+  isTTY: boolean = !!process.stdout.isTTY,
+): boolean {
+  if ('NO_COLOR' in env) return false;
+  const force = env.FORCE_COLOR;
+  if (force !== undefined && force !== '' && force !== '0' && force.toLowerCase() !== 'false') {
+    return true;
+  }
+  if (env.TERM === 'dumb') return false;
+  return isTTY;
+}
+
+export const colorize = (text: string, color: ColorName): string => {
   return `${colors[color]}${text}${colors.reset}`;
 };
+
+// Apply the environment default at import time so NO_COLOR / a non-TTY pipe is
+// respected even before any CLI flag is parsed (an explicit --no-color / --color
+// flag overrides this later).
+setColorEnabled(detectColorEnabled());

package/src/utils/config-schema.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { CONFIG_DEFAULTS, UserConfig } from './config';
+import {
+  CONFIG_KEYS,
+  CONFIG_SCHEMA,
+  isConfigKey,
+  parseConfigValue,
+  applyConfigSet,
+  applyConfigUnset,
+  formatConfigValue,
+} from './config-schema';
+
+describe('config schema coverage', () => {
+  it('describes every UserConfig key exactly once', () => {
+    expect(CONFIG_KEYS.slice().sort()).toEqual(Object.keys(CONFIG_DEFAULTS).sort());
+  });
+  it('is sorted for stable listing', () => {
+    expect(CONFIG_KEYS).toEqual(CONFIG_KEYS.slice().sort());
+  });
+});
+
+describe('isConfigKey', () => {
+  it('accepts known keys, rejects unknown / prototype keys', () => {
+    expect(isConfigKey('githubOrg')).toBe(true);
+    expect(isConfigKey('nope')).toBe(false);
+    expect(isConfigKey('toString')).toBe(false); // not an own property
+    expect(isConfigKey('')).toBe(false);
+  });
+});
+
+describe('parseConfigValue', () => {
+  it('coerces booleans from common words (case-insensitive)', () => {
+    for (const t of ['true', '1', 'YES', 'on', 'y']) {
+      expect(parseConfigValue('autoReportBugs', t)).toEqual({ ok: true, value: true });
+    }
+    for (const f of ['false', '0', 'No', 'off', 'n']) {
+      expect(parseConfigValue('autoReportBugs', f)).toEqual({ ok: true, value: false });
+    }
+  });
+  it('rejects non-boolean words with a helpful error', () => {
+    const r = parseConfigValue('installMcp', 'maybe');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toMatch(/boolean/);
+  });
+  it('validates enums', () => {
+    expect(parseConfigValue('cloneProtocol', 'https')).toEqual({ ok: true, value: 'https' });
+    const r = parseConfigValue('cloneProtocol', 'ftp');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toMatch(/ssh, https/);
+  });
+  it('normalizes enum case + whitespace to the canonical value', () => {
+    expect(parseConfigValue('cloneProtocol', 'HTTPS')).toEqual({ ok: true, value: 'https' });
+    expect(parseConfigValue('cloneProtocol', '  ssh ')).toEqual({ ok: true, value: 'ssh' });
+    expect(parseConfigValue('aiAgent', 'Both')).toEqual({ ok: true, value: 'both' });
+  });
+  it('trims surrounding whitespace on strings (case preserved)', () => {
+    expect(parseConfigValue('githubOrg', '  Acme-Corp ')).toEqual({ ok: true, value: 'Acme-Corp' });
+    expect(parseConfigValue('githubOrg', '   ')).toEqual({ ok: true, value: '' }); // trims to empty (allowed)
+    expect(parseConfigValue('workspacesDir', '   ').ok).toBe(false); // required, empty after trim
+  });
+  it('accepts agent enum values incl. auto/both', () => {
+    expect(parseConfigValue('aiAgent', 'both').ok).toBe(true);
+    expect(parseConfigValue('primaryAgent', 'both').ok).toBe(false); // no "both" for primary
+    expect(parseConfigValue('primaryAgent', 'pi').ok).toBe(true);
+  });
+  it('rejects empty required strings but allows empty githubOrg', () => {
+    expect(parseConfigValue('workspacesDir', '').ok).toBe(false);
+    expect(parseConfigValue('githubOrg', '')).toEqual({ ok: true, value: '' });
+  });
+});
+
+describe('applyConfigSet / applyConfigUnset (pure, immutable)', () => {
+  const base: UserConfig = { ...CONFIG_DEFAULTS, githubOrg: 'acme' };
+
+  it('returns a new object and does not mutate the input', () => {
+    const r = applyConfigSet(base, 'githubOrg', 'octocat');
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.next.githubOrg).toBe('octocat');
+      expect(r.value).toBe('octocat');
+    }
+    expect(base.githubOrg).toBe('acme'); // unchanged
+  });
+
+  it('rejects unknown keys', () => {
+    const r = applyConfigSet(base, 'bogus', 'x');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toMatch(/Unknown config key/);
+  });
+
+  it('unset resets to the default value', () => {
+    const r = applyConfigUnset(base, 'githubOrg');
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.next.githubOrg).toBe(CONFIG_DEFAULTS.githubOrg);
+  });
+});
+
+describe('formatConfigValue', () => {
+  it('renders booleans and empty strings predictably', () => {
+    expect(formatConfigValue(true)).toBe('true');
+    expect(formatConfigValue(false)).toBe('false');
+    expect(formatConfigValue('')).toBe('');
+    expect(formatConfigValue('ssh')).toBe('ssh');
+  });
+});
+
+describe('CONFIG_SCHEMA describe text', () => {
+  it('every key has a non-empty description', () => {
+    for (const k of CONFIG_KEYS) expect(CONFIG_SCHEMA[k].describe.length).toBeGreaterThan(0);
+  });
+});