@nemus-cli/nemus 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-01
+
+### Added
+
+- **`nemus config edit`** opens the config file in `$VISUAL`/`$EDITOR` (seeding
+  it with the current resolved config on first run) and re-validates the JSON
+  afterward, warning about unrecognized keys. Refuses to run without an
+  interactive terminal.
+- **Environment-variable reference** in the README documenting every variable
+  Nemus reads (`NEMUS_*`, `WORKSPACE_*`, `NO_COLOR`/`FORCE_COLOR`,
+  `VISUAL`/`EDITOR`).
+
 ## [0.8.0] - 2026-09-01
 
 ### Added

package/README.md

@@ -259,6 +259,25 @@ nemus config path                     # print the config file location
 
 `get`/`list` also accept `--json`. An unknown key or an invalid value exits
 non-zero with a clear message (e.g. `cloneProtocol must be one of: ssh, https`).
+`config edit` opens the file in `$VISUAL`/`$EDITOR` (seeding it with the current
+resolved config first) and re-validates the JSON afterward.
+
+### Environment variables
+
+Everything Nemus reads from the environment (all optional):
+
+| Variable | Effect |
+| --- | --- |
+| `NEMUS_DIR` | Override where workspaces are created (also `WORKSPACE_MANAGER_DIR`). |
+| `NEMUS_CACHE_DIR` | Override the cache/config/state dir, default `~/.nemus` (also `WORKSPACE_MANAGER_CACHE_DIR`). |
+| `NEMUS_JUDGE_MODEL` | Model for the `reflect` judge (overrides `--model`'s default). |
+| `NEMUS_JUDGE_THINKING` | Thinking level for the `reflect` judge on pi (`off`…`max`). |
+| `NEMUS_JUDGE_TIMEOUT_MS` | Timeout for the `reflect` judge call. |
+| `NEMUS_BUG_REPORT_REPO` | Repo that `report-bug` files issues against. |
+| `NEMUS_SKIP_CONFIGURE` | Skip the one-time post-install `configure` prompt. |
+| `WORKSPACE_CLONE_TIMEOUT_MS` | Git clone timeout (default 15 min). |
+| `NO_COLOR` / `FORCE_COLOR` | Disable / force ANSI color (see [Global flags](#global-flags)). |
+| `VISUAL` / `EDITOR` | Editor launched by `nemus config edit`. |
 
 ### Global flags
 

package/dist/commands/config.js

@@ -1,7 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerConfigCommand = registerConfigCommand;
+const fs = __importStar(require("fs"));
 const config_1 = require("../utils/config");
+const editor_1 = require("../utils/editor");
 const config_schema_1 = require("../utils/config-schema");
 const output_1 = require("../utils/output");
 const logger_1 = require("../utils/logger");
@@ -94,6 +129,53 @@ function registerConfigCommand(parent) {
         .action(() => {
         process.stdout.write(config_1.CONFIG_PATH + '\n');
     });
+    config
+        .command('edit')
+        .description('Open the config file in $EDITOR (or $VISUAL)')
+        .action(() => {
+        handleEdit();
+    });
+}
+function handleEdit() {
+    if (!process.stdout.isTTY) {
+        (0, logger_1.logError)('`config edit` needs an interactive terminal. Use `config set <key> <value>` in scripts.');
+        process.exitCode = 1;
+        return;
+    }
+    // Seed the file with the fully-resolved config so there's something complete
+    // to edit on a first run (getUserConfig merges defaults + any overrides).
+    if (!fs.existsSync(config_1.CONFIG_PATH))
+        (0, config_1.saveUserConfig)((0, config_1.getUserConfig)());
+    const result = (0, editor_1.openInEditor)(config_1.CONFIG_PATH);
+    if (!result.ok) {
+        (0, logger_1.logError)(result.error ?? `editor exited with code ${result.code}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Re-validate: a hand-edit can produce invalid JSON or invalid values, which
+    // getUserConfig would silently ignore (falling back to defaults). Surface that
+    // instead, using the SAME schema `config set` uses so both write paths agree.
+    const review = (0, config_schema_1.reviewConfigFileText)(fs.readFileSync(config_1.CONFIG_PATH, 'utf-8'));
+    if (review.parseError) {
+        (0, logger_1.logError)(`${config_1.CONFIG_PATH} is not valid JSON after editing — changes are kept, but Nemus will use defaults until it parses.`);
+        process.exitCode = 1;
+        return;
+    }
+    if (review.notObject) {
+        (0, logger_1.logError)(`${config_1.CONFIG_PATH} must contain a JSON object — changes are kept, but Nemus will use defaults until it does.`);
+        process.exitCode = 1;
+        return;
+    }
+    if (review.unknownKeys.length > 0)
+        (0, logger_1.logWarning)(`Ignoring unrecognized key(s): ${review.unknownKeys.join(', ')}`);
+    if (!review.ok) {
+        for (const e of review.invalid)
+            (0, logger_1.logWarning)(e);
+        (0, logger_1.logError)('Some values are invalid and will fall back to their defaults until fixed.');
+        process.exitCode = 1;
+        return;
+    }
+    (0, logger_1.logSuccess)('Config saved.');
 }
 function printAll(cfg, json) {
     if (json) {

package/dist/utils/config-schema.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONFIG_KEYS = exports.CONFIG_SCHEMA = void 0;
 exports.isConfigKey = isConfigKey;
 exports.parseConfigValue = parseConfigValue;
+exports.validateTypedValue = validateTypedValue;
 exports.applyConfigSet = applyConfigSet;
 exports.applyConfigUnset = applyConfigUnset;
 exports.formatConfigValue = formatConfigValue;
+exports.reviewConfigFileText = reviewConfigFileText;
 const config_1 = require("./config");
 const AGENT_VALUES = ['claude', 'pi', 'opencode', 'codex', 'gemini'];
 exports.CONFIG_SCHEMA = {
@@ -64,6 +66,30 @@ function parseConfigValue(key, raw) {
     }
     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.
+ */
+function validateTypedValue(key, value) {
+    const spec = exports.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.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. */
 function applyConfigSet(current, key, raw) {
     if (!isConfigKey(key)) {
@@ -86,3 +112,34 @@ function applyConfigUnset(current, key) {
 function formatConfigValue(value) {
     return typeof value === 'boolean' ? String(value) : String(value ?? '');
 }
+/**
+ * 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.
+ */
+function reviewConfigFileText(text) {
+    const base = { parseError: false, notObject: false, unknownKeys: [], invalid: [] };
+    let raw;
+    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;
+    const known = new Set(exports.CONFIG_KEYS);
+    const unknownKeys = Object.keys(obj).filter((k) => !known.has(k));
+    const invalid = [];
+    for (const key of exports.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/dist/utils/editor.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEditor = resolveEditor;
+exports.openInEditor = openInEditor;
+const child_process_1 = require("child_process");
+/**
+ * Resolve the user's preferred editor as an argv array. Honors `$VISUAL` then
+ * `$EDITOR` (the long-standing Unix convention — `VISUAL` wins for full-screen
+ * editors), falling back to `notepad` on Windows and `vi` elsewhere. The env
+ * value may include flags (e.g. `code --wait`, `emacs -nw`), so it's split on
+ * whitespace into a command + args. Pure + unit-tested.
+ */
+function resolveEditor(env = process.env, platform = process.platform) {
+    const raw = (env.VISUAL || env.EDITOR || '').trim();
+    if (raw)
+        return raw.split(/\s+/);
+    return platform === 'win32' ? ['notepad'] : ['vi'];
+}
+/**
+ * Open `file` in the resolved editor, inheriting the terminal so the editor is
+ * interactive. Returns a structured result rather than throwing so the caller
+ * controls messaging/exit. `spawn` is injected for tests.
+ */
+function openInEditor(file, deps = {}) {
+    const spawn = deps.spawn ?? child_process_1.spawnSync;
+    const [cmd, ...args] = resolveEditor(deps.env, deps.platform);
+    const res = spawn(cmd, [...args, file], { stdio: 'inherit' });
+    if (res.error) {
+        const err = res.error;
+        const reason = err.code === 'ENOENT' ? `editor "${cmd}" not found` : err.message;
+        return { ok: false, editor: cmd, error: reason };
+    }
+    const code = typeof res.status === 'number' ? res.status : 1;
+    return { ok: code === 0, editor: cmd, code };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "workspaces": [
     "packages/*"
   ],

package/src/commands/config.ts

@@ -1,15 +1,18 @@
 import { Command } from 'commander';
+import * as fs from 'fs';
 import { getUserConfig, saveUserConfig, CONFIG_PATH } from '../utils/config';
+import { openInEditor } from '../utils/editor';
 import {
   CONFIG_KEYS,
   CONFIG_SCHEMA,
   isConfigKey,
   applyConfigSet,
   applyConfigUnset,
+  reviewConfigFileText,
   formatConfigValue,
 } from '../utils/config-schema';
 import { outputJson, outputJsonError } from '../utils/output';
-import { logSuccess, logError } from '../utils/logger';
+import { logSuccess, logError, logWarning } from '../utils/logger';
 import { colorize } from '../utils/colors';
 
 /**
@@ -93,6 +96,54 @@ export function registerConfigCommand(parent: Command): void {
     .action(() => {
       process.stdout.write(CONFIG_PATH + '\n');
     });
+
+  config
+    .command('edit')
+    .description('Open the config file in $EDITOR (or $VISUAL)')
+    .action(() => {
+      handleEdit();
+    });
+}
+
+function handleEdit(): void {
+  if (!process.stdout.isTTY) {
+    logError('`config edit` needs an interactive terminal. Use `config set <key> <value>` in scripts.');
+    process.exitCode = 1;
+    return;
+  }
+  // Seed the file with the fully-resolved config so there's something complete
+  // to edit on a first run (getUserConfig merges defaults + any overrides).
+  if (!fs.existsSync(CONFIG_PATH)) saveUserConfig(getUserConfig());
+
+  const result = openInEditor(CONFIG_PATH);
+  if (!result.ok) {
+    logError(result.error ?? `editor exited with code ${result.code}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Re-validate: a hand-edit can produce invalid JSON or invalid values, which
+  // getUserConfig would silently ignore (falling back to defaults). Surface that
+  // instead, using the SAME schema `config set` uses so both write paths agree.
+  const review = reviewConfigFileText(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  if (review.parseError) {
+    logError(`${CONFIG_PATH} is not valid JSON after editing — changes are kept, but Nemus will use defaults until it parses.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (review.notObject) {
+    logError(`${CONFIG_PATH} must contain a JSON object — changes are kept, but Nemus will use defaults until it does.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (review.unknownKeys.length > 0) logWarning(`Ignoring unrecognized key(s): ${review.unknownKeys.join(', ')}`);
+  if (!review.ok) {
+    for (const e of review.invalid) logWarning(e);
+    logError('Some values are invalid and will fall back to their defaults until fixed.');
+    process.exitCode = 1;
+    return;
+  }
+  logSuccess('Config saved.');
 }
 
 function printAll(cfg: ReturnType<typeof getUserConfig>, json?: boolean): void {

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

@@ -7,6 +7,8 @@ import {
   parseConfigValue,
   applyConfigSet,
   applyConfigUnset,
+  validateTypedValue,
+  reviewConfigFileText,
   formatConfigValue,
 } from './config-schema';
 
@@ -95,6 +97,53 @@ describe('applyConfigSet / applyConfigUnset (pure, immutable)', () => {
   });
 });
 
+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');

package/src/utils/config-schema.ts

@@ -80,6 +80,29 @@ export function parseConfigValue(key: ConfigKey, raw: string): ParseResult {
   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,
@@ -110,3 +133,45 @@ export function applyConfigUnset(
 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/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/);
+  });
+});

package/src/utils/editor.ts

@@ -0,0 +1,48 @@
+import { spawnSync } from 'child_process';
+
+/**
+ * Resolve the user's preferred editor as an argv array. Honors `$VISUAL` then
+ * `$EDITOR` (the long-standing Unix convention — `VISUAL` wins for full-screen
+ * editors), falling back to `notepad` on Windows and `vi` elsewhere. The env
+ * value may include flags (e.g. `code --wait`, `emacs -nw`), so it's split on
+ * whitespace into a command + args. Pure + unit-tested.
+ */
+export function resolveEditor(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  const raw = (env.VISUAL || env.EDITOR || '').trim();
+  if (raw) return raw.split(/\s+/);
+  return platform === 'win32' ? ['notepad'] : ['vi'];
+}
+
+export interface EditorResult {
+  ok: boolean;
+  /** Editor argv[0] that was launched. */
+  editor: string;
+  /** Process exit code, when the editor ran and exited normally. */
+  code?: number;
+  /** Populated when the editor couldn't be launched at all. */
+  error?: string;
+}
+
+/**
+ * Open `file` in the resolved editor, inheriting the terminal so the editor is
+ * interactive. Returns a structured result rather than throwing so the caller
+ * controls messaging/exit. `spawn` is injected for tests.
+ */
+export function openInEditor(
+  file: string,
+  deps: { spawn?: typeof spawnSync; env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform } = {},
+): EditorResult {
+  const spawn = deps.spawn ?? spawnSync;
+  const [cmd, ...args] = resolveEditor(deps.env, deps.platform);
+  const res = spawn(cmd, [...args, file], { stdio: 'inherit' });
+  if (res.error) {
+    const err = res.error as NodeJS.ErrnoException;
+    const reason = err.code === 'ENOENT' ? `editor "${cmd}" not found` : err.message;
+    return { ok: false, editor: cmd, error: reason };
+  }
+  const code = typeof res.status === 'number' ? res.status : 1;
+  return { ok: code === 0, editor: cmd, code };
+}