@nemus-cli/nemus 0.5.0 → 0.9.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

@@ -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/config-schema.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'vitest';
+import { CONFIG_DEFAULTS, UserConfig } from './config';
+import {
+  CONFIG_KEYS,
+  CONFIG_SCHEMA,
+  isConfigKey,
+  parseConfigValue,
+  applyConfigSet,
+  applyConfigUnset,
+  validateTypedValue,
+  reviewConfigFileText,
+  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('validateTypedValue (already-typed, as from the JSON file)', () => {
+  it('accepts correctly-typed values', () => {
+    expect(validateTypedValue('autoReportBugs', true)).toEqual({ ok: true });
+    expect(validateTypedValue('cloneProtocol', 'https')).toEqual({ ok: true });
+    expect(validateTypedValue('githubOrg', '')).toEqual({ ok: true }); // allowEmpty
+    expect(validateTypedValue('workspacesDir', '/x')).toEqual({ ok: true });
+  });
+  it('rejects wrong types and bad enum/empty values', () => {
+    expect(validateTypedValue('autoReportBugs', 'yes').ok).toBe(false); // string, not boolean
+    expect(validateTypedValue('cloneProtocol', 'ftp').ok).toBe(false);
+    expect(validateTypedValue('cloneProtocol', 42 as unknown).ok).toBe(false);
+    expect(validateTypedValue('workspacesDir', '   ').ok).toBe(false); // required, blank
+    expect(validateTypedValue('installMcp', 1 as unknown).ok).toBe(false);
+  });
+});
+
+describe('reviewConfigFileText (for `config edit`)', () => {
+  it('flags unparseable JSON', () => {
+    const r = reviewConfigFileText('{ not json');
+    expect(r.parseError).toBe(true);
+    expect(r.ok).toBe(false);
+  });
+  it('flags non-object JSON (null / array / scalar) without throwing', () => {
+    for (const t of ['null', '42', '"str"', '[1,2]']) {
+      const r = reviewConfigFileText(t);
+      expect(r.notObject).toBe(true);
+      expect(r.ok).toBe(false);
+      expect(r.unknownKeys).toEqual([]); // no numeric-index "keys" from an array
+    }
+  });
+  it('reports unknown keys but stays ok if known values are valid', () => {
+    const r = reviewConfigFileText(JSON.stringify({ githubOrg: 'acme', bogus: 1, nope: true }));
+    expect(r.unknownKeys.sort()).toEqual(['bogus', 'nope']);
+    expect(r.ok).toBe(true);
+  });
+  it('catches invalid VALUES the same way config set would', () => {
+    const r = reviewConfigFileText(JSON.stringify({ cloneProtocol: 'ftp', autoReportBugs: 'yes' }));
+    expect(r.ok).toBe(false);
+    expect(r.invalid.join('\n')).toMatch(/cloneProtocol must be one of/);
+    expect(r.invalid.join('\n')).toMatch(/autoReportBugs must be a boolean/);
+  });
+  it('accepts a clean object', () => {
+    const r = reviewConfigFileText(JSON.stringify({ cloneProtocol: 'https', installMcp: true }));
+    expect(r).toMatchObject({ parseError: false, notObject: false, unknownKeys: [], invalid: [], ok: true });
+  });
+});
+
+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);
+  });
+});

package/src/utils/config-schema.ts

@@ -0,0 +1,177 @@
+import { UserConfig, CONFIG_DEFAULTS } from './config';
+
+/**
+ * Declarative schema for the non-interactive `nemus config get/set` command.
+ * Every writable UserConfig field is described here with its type + allowed
+ * values, so `set` can validate/coerce a string argument and `get`/`list` can
+ * enumerate keys. Kept as pure data + pure functions so it's fully unit-tested
+ * without touching disk. Keep this in sync with the UserConfig interface — the
+ * `satisfies` check below fails the build if a key is misspelled.
+ */
+export type ConfigKey = keyof UserConfig;
+
+type FieldSpec =
+  | { type: 'string'; allowEmpty?: boolean; describe: string }
+  | { type: 'boolean'; describe: string }
+  | { type: 'enum'; values: readonly string[]; describe: string };
+
+const AGENT_VALUES = ['claude', 'pi', 'opencode', 'codex', 'gemini'] as const;
+
+export const CONFIG_SCHEMA = {
+  workspacesDir: { type: 'string', describe: 'Directory where workspaces are created' },
+  githubOrg: { type: 'string', allowEmpty: true, describe: 'Default GitHub org for repo lookups' },
+  cloneProtocol: { type: 'enum', values: ['ssh', 'https'], describe: 'Protocol used to clone repos' },
+  aiAgent: {
+    type: 'enum',
+    values: [...AGENT_VALUES, 'both', 'auto'],
+    describe: 'AI agent(s) to integrate with',
+  },
+  primaryAgent: {
+    type: 'enum',
+    values: [...AGENT_VALUES, 'auto'],
+    describe: 'Agent launched when opening a workspace',
+  },
+  autoLaunchClaude: { type: 'boolean', describe: 'Auto-launch the agent after creating a workspace' },
+  generateClaudeContext: { type: 'boolean', describe: 'Generate agent context files (AGENTS.md)' },
+  installMcp: { type: 'boolean', describe: 'Install the MCP server during configure' },
+  piWorkspaceInputStatus: { type: 'boolean', describe: "Show workspace status in Pi's input area" },
+  claudeWorkspaceStatusLine: { type: 'boolean', describe: "Show workspace table in Claude's status line" },
+  autoReportBugs: { type: 'boolean', describe: 'Auto-file a GitHub issue when a command crashes' },
+} satisfies Record<ConfigKey, FieldSpec>;
+
+export const CONFIG_KEYS = Object.keys(CONFIG_SCHEMA).sort() as ConfigKey[];
+
+const TRUE_WORDS = new Set(['true', '1', 'yes', 'on', 'y']);
+const FALSE_WORDS = new Set(['false', '0', 'no', 'off', 'n']);
+
+/** True if `key` is a writable config key. */
+export function isConfigKey(key: string): key is ConfigKey {
+  return Object.prototype.hasOwnProperty.call(CONFIG_SCHEMA, key);
+}
+
+export type ParseResult =
+  | { ok: true; value: UserConfig[ConfigKey] }
+  | { ok: false; error: string };
+
+/** Validate + coerce a raw string for `key` into the field's typed value. */
+export function parseConfigValue(key: ConfigKey, raw: string): ParseResult {
+  const spec: FieldSpec = CONFIG_SCHEMA[key];
+  if (spec.type === 'boolean') {
+    const v = raw.trim().toLowerCase();
+    if (TRUE_WORDS.has(v)) return { ok: true, value: true };
+    if (FALSE_WORDS.has(v)) return { ok: true, value: false };
+    return { ok: false, error: `${key} expects a boolean (true/false); got "${raw}"` };
+  }
+  if (spec.type === 'enum') {
+    // Enum values are all lowercase, so normalize input like booleans do —
+    // `HTTPS` / ` https ` should resolve to the canonical value, not fail.
+    const v = raw.trim().toLowerCase();
+    if ((spec.values as readonly string[]).includes(v)) {
+      return { ok: true, value: v as UserConfig[ConfigKey] };
+    }
+    return { ok: false, error: `${key} must be one of: ${spec.values.join(', ')}; got "${raw}"` };
+  }
+  // string: trim surrounding whitespace (a stray space in a path/org is almost
+  // always a mistake), but preserve case.
+  const trimmed = raw.trim();
+  if (!spec.allowEmpty && trimmed === '') {
+    return { ok: false, error: `${key} cannot be empty` };
+  }
+  return { ok: true, value: trimmed };
+}
+
+/**
+ * Validate an already-typed value (as it appears in the JSON config file) for
+ * `key` against its field spec. This is the parse-free sibling of
+ * parseConfigValue (which coerces a CLI string): it checks that a boolean field
+ * holds a boolean, an enum holds an allowed string, and a string field holds a
+ * (non-empty, unless allowEmpty) string. Used by `config edit` so a hand-edit
+ * is validated the same way `config set` validates. Pure + unit-tested.
+ */
+export function validateTypedValue(key: ConfigKey, value: unknown): { ok: true } | { ok: false; error: string } {
+  const spec: FieldSpec = CONFIG_SCHEMA[key];
+  if (spec.type === 'boolean') {
+    return typeof value === 'boolean' ? { ok: true } : { ok: false, error: `${key} must be a boolean` };
+  }
+  if (spec.type === 'enum') {
+    return typeof value === 'string' && (spec.values as readonly string[]).includes(value)
+      ? { ok: true }
+      : { ok: false, error: `${key} must be one of: ${spec.values.join(', ')}` };
+  }
+  if (typeof value !== 'string') return { ok: false, error: `${key} must be a string` };
+  if (!spec.allowEmpty && value.trim() === '') return { ok: false, error: `${key} cannot be empty` };
+  return { ok: true };
+}
+
+/** Apply a `set` to a config object, returning a NEW config or an error. Pure. */
+export function applyConfigSet(
+  current: UserConfig,
+  key: string,
+  raw: string,
+): { ok: true; next: UserConfig; value: UserConfig[ConfigKey] } | { ok: false; error: string } {
+  if (!isConfigKey(key)) {
+    return { ok: false, error: `Unknown config key "${key}". Run "nemus config list" to see valid keys.` };
+  }
+  const parsed = parseConfigValue(key, raw);
+  if (!parsed.ok) return parsed;
+  return { ok: true, next: { ...current, [key]: parsed.value }, value: parsed.value };
+}
+
+/** Reset a key to its default value, returning a NEW config or an error. Pure. */
+export function applyConfigUnset(
+  current: UserConfig,
+  key: string,
+): { ok: true; next: UserConfig; value: UserConfig[ConfigKey] } | { ok: false; error: string } {
+  if (!isConfigKey(key)) {
+    return { ok: false, error: `Unknown config key "${key}". Run "nemus config list" to see valid keys.` };
+  }
+  const value = CONFIG_DEFAULTS[key];
+  return { ok: true, next: { ...current, [key]: value }, value };
+}
+
+/** Render a config value for plain (scriptable) stdout output. */
+export function formatConfigValue(value: unknown): string {
+  return typeof value === 'boolean' ? String(value) : String(value ?? '');
+}
+
+export interface ConfigFileReview {
+  /** JSON.parse failed. */
+  parseError: boolean;
+  /** Parsed, but not a plain object (null / array / scalar). */
+  notObject: boolean;
+  /** Keys present in the file that aren't recognized config keys. */
+  unknownKeys: string[];
+  /** Validation error messages for known keys holding invalid values. */
+  invalid: string[];
+  /** True when the file is a usable config object (may still have warnings). */
+  ok: boolean;
+}
+
+/**
+ * Review the raw text of a hand-edited config file the same way `config set`
+ * validates: it must parse, be a plain object, only use known keys, and every
+ * known key present must hold a schema-valid value. Pure so `config edit` can be
+ * fully unit-tested without spawning an editor.
+ */
+export function reviewConfigFileText(text: string): ConfigFileReview {
+  const base = { parseError: false, notObject: false, unknownKeys: [] as string[], invalid: [] as string[] };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return { ...base, parseError: true, ok: false };
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...base, notObject: true, ok: false };
+  }
+  const obj = raw as Record<string, unknown>;
+  const known = new Set<string>(CONFIG_KEYS);
+  const unknownKeys = Object.keys(obj).filter((k) => !known.has(k));
+  const invalid: string[] = [];
+  for (const key of CONFIG_KEYS) {
+    if (!(key in obj)) continue;
+    const res = validateTypedValue(key, obj[key]);
+    if (!res.ok) invalid.push(res.error);
+  }
+  return { parseError: false, notObject: false, unknownKeys, invalid, ok: invalid.length === 0 };
+}

package/src/utils/config.ts

@@ -67,7 +67,7 @@ export interface UserConfig {
   autoReportBugs: boolean;
 }
 
-const DEFAULTS: UserConfig = {
+export const CONFIG_DEFAULTS: UserConfig = {
   workspacesDir: path.join(HOME_DIR, 'workspaces'),
   githubOrg: '',
   autoLaunchClaude: true,
@@ -81,6 +81,9 @@ const DEFAULTS: UserConfig = {
   autoReportBugs: false,
 };
 
+// Internal alias retained for the many references below.
+const DEFAULTS = CONFIG_DEFAULTS;
+
 function loadConfigFileSync(): Partial<UserConfig> {
   try {
     const content = fs.readFileSync(CONFIG_FILE, 'utf-8');

package/src/utils/editor.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+import { resolveEditor, openInEditor } from './editor';
+
+describe('resolveEditor', () => {
+  it('prefers $VISUAL over $EDITOR', () => {
+    expect(resolveEditor({ VISUAL: 'code --wait', EDITOR: 'vim' }, 'darwin')).toEqual(['code', '--wait']);
+  });
+  it('falls back to $EDITOR, splitting flags', () => {
+    expect(resolveEditor({ EDITOR: 'emacs -nw' }, 'linux')).toEqual(['emacs', '-nw']);
+  });
+  it('platform default when neither is set', () => {
+    expect(resolveEditor({}, 'win32')).toEqual(['notepad']);
+    expect(resolveEditor({}, 'linux')).toEqual(['vi']);
+    expect(resolveEditor({ EDITOR: '   ' }, 'darwin')).toEqual(['vi']); // blank ignored
+  });
+});
+
+describe('openInEditor', () => {
+  it('launches editor argv[0] + flags + file, inheriting stdio', () => {
+    const spawn = vi.fn().mockReturnValue({ status: 0 }) as any;
+    const res = openInEditor('/tmp/config.json', { spawn, env: { EDITOR: 'code --wait' }, platform: 'darwin' });
+    expect(spawn).toHaveBeenCalledWith('code', ['--wait', '/tmp/config.json'], { stdio: 'inherit' });
+    expect(res).toEqual({ ok: true, editor: 'code', code: 0 });
+  });
+
+  it('reports a non-zero editor exit as not-ok', () => {
+    const spawn = vi.fn().mockReturnValue({ status: 1 }) as any;
+    expect(openInEditor('/f', { spawn, env: { EDITOR: 'vi' } }).ok).toBe(false);
+  });
+
+  it('reports a missing editor (ENOENT) with a clear message', () => {
+    const spawn = vi.fn().mockReturnValue({ error: Object.assign(new Error('x'), { code: 'ENOENT' }) }) as any;
+    const res = openInEditor('/f', { spawn, env: { EDITOR: 'nope' } });
+    expect(res.ok).toBe(false);
+    expect(res.error).toMatch(/not found/);
+  });
+});