@geminilight/mindos 0.6.40 → 0.6.42

package/bin/commands/update.js

@@ -0,0 +1,286 @@
+/**
+ * mindos update — npm install latest, sync skills, rebuild, restart daemon or foreground instance.
+ *
+ * Heavy dependencies are loaded on demand to keep CLI cold start fast.
+ */
+
+import { execSync, spawn as nodeSpawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { ROOT, BUILD_STAMP, CONFIG_PATH, LOG_PATH } from '../lib/constants.js';
+import { bold, dim, cyan, green, red, yellow } from '../lib/colors.js';
+import { execInherited } from '../lib/shell.js';
+import { EXIT } from '../lib/command.js';
+import { stopMindos } from '../lib/stop.js';
+import { getLocalIP } from '../lib/startup.js';
+import { isPortInUse } from '../lib/port.js';
+
+/**
+ * Dynamically resolve the new ROOT after `npm install -g`.
+ * This is needed because constants are evaluated at module load time.
+ */
+function getUpdatedRoot() {
+  try {
+    const mindosBin = execSync('which mindos', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+    if (mindosBin) {
+      // mindos bin is usually at <root>/bin/cli.js or a symlink to it
+      let cliPath;
+      try {
+        cliPath = execSync(`readlink -f "${mindosBin}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+      } catch {
+        try {
+          cliPath = execSync(`realpath "${mindosBin}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+        } catch {
+          cliPath = mindosBin;
+        }
+      }
+      if (cliPath) {
+        // cliPath is like /path/to/node_modules/@geminilight/mindos/bin/cli.js
+        // ROOT is /path/to/node_modules/@geminilight/mindos
+        return resolve(dirname(cliPath), '..');
+      }
+    }
+  } catch {}
+  // Fallback to static ROOT
+  return ROOT;
+}
+
+/**
+ * Build the app in the given root if the build stamp doesn't match the package version.
+ * Used by `mindos update` to pre-build before restarting the daemon.
+ * @param {string} newRoot
+ */
+function buildIfNeeded(newRoot) {
+  // Check for prebuilt standalone first (npm package ships with it)
+  const standaloneServer = resolve(newRoot, '_standalone', 'server.js');
+  const standaloneStamp = resolve(newRoot, '_standalone', '.mindos-build-version');
+  if (existsSync(standaloneServer)) {
+    try {
+      const builtVersion = readFileSync(standaloneStamp, 'utf-8').trim();
+      const pkgVersion = JSON.parse(readFileSync(resolve(newRoot, 'package.json'), 'utf-8')).version;
+      if (builtVersion === pkgVersion) return; // prebuilt standalone matches, no build needed
+    } catch { /* fall through to legacy build */ }
+  }
+
+  const newBuildStamp = resolve(newRoot, 'app', '.next', '.mindos-build-version');
+  const newNextBin = resolve(newRoot, 'app', 'node_modules', '.bin', 'next');
+
+  let needBuild = true;
+  try {
+    const builtVersion = readFileSync(newBuildStamp, 'utf-8').trim();
+    const pkgVersion = JSON.parse(readFileSync(resolve(newRoot, 'package.json'), 'utf-8')).version;
+    needBuild = builtVersion !== pkgVersion;
+  } catch {
+    needBuild = true;
+  }
+
+  if (!needBuild) return;
+
+  console.log(yellow('\n  Building MindOS (version change detected)...\n'));
+  const appPkg = resolve(newRoot, 'app', 'package.json');
+  if (existsSync(appPkg)) {
+    execInherited('npm install', resolve(newRoot, 'app'));
+  }
+  const nextDir = resolve(newRoot, 'app', '.next');
+  if (existsSync(nextDir)) {
+    execInherited(`rm -rf "${nextDir}"`, newRoot);
+  }
+  execInherited('node scripts/gen-renderer-index.js', newRoot);
+  execInherited(`${newNextBin} build`, resolve(newRoot, 'app'));
+  const version = JSON.parse(readFileSync(resolve(newRoot, 'package.json'), 'utf-8')).version;
+  writeFileSync(newBuildStamp, version, 'utf-8');
+}
+
+export const meta = {
+  name: 'update',
+  group: 'Config',
+  summary: 'Update to latest version',
+  usage: 'mindos update',
+};
+
+export const run = async () => {
+  const { writeUpdateStatus, writeUpdateFailed } = await import('../lib/update-status.js');
+  const currentVersion = (() => {
+    try { return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version; } catch { return '?'; }
+  })();
+  console.log(`\n${bold('⬆  Updating MindOS...')}  ${dim(`(current: ${currentVersion})`)}\n`);
+
+  // Stage 1: Download
+  writeUpdateStatus('downloading', { fromVersion: currentVersion });
+  try {
+    execSync('npm install -g @geminilight/mindos@latest', { stdio: 'inherit' });
+  } catch {
+    writeUpdateFailed('downloading', 'npm install failed', { fromVersion: currentVersion });
+    console.error(red('Update failed. Try: npm install -g @geminilight/mindos@latest'));
+    process.exit(EXIT.ERROR);
+  }
+  if (existsSync(BUILD_STAMP)) rmSync(BUILD_STAMP);
+
+  // Resolve the new installation path (after npm install -g, ROOT is stale)
+  const updatedRoot = getUpdatedRoot();
+  const newVersion = (() => {
+    try { return JSON.parse(readFileSync(resolve(updatedRoot, 'package.json'), 'utf-8')).version; } catch { return '?'; }
+  })();
+  const vOpts = { fromVersion: currentVersion, toVersion: newVersion };
+
+  // Stage 2: Skills
+  writeUpdateStatus('skills', vOpts);
+  try {
+    const { checkSkillVersions, updateSkill } = await import('../lib/skill-check.js');
+    const mismatches = checkSkillVersions(updatedRoot);
+    for (const m of mismatches) {
+      updateSkill(m.bundledPath, m.installPath);
+      console.log(`  ${green('✓')} ${dim(`Skill ${m.name}: v${m.installed} → v${m.bundled}`)}`);
+    }
+  } catch { /* best-effort */ }
+
+  if (newVersion !== currentVersion) {
+    console.log(`\n${green(`✔ Updated ${currentVersion} → ${newVersion}`)}`);
+  } else {
+    console.log(`\n${green('✔ Already on the latest version')} ${dim(`(${currentVersion})`)}\n`);
+    return;
+  }
+
+  const gateway = await import('../lib/gateway.js');
+  const updatePlatform = await gateway.getPlatform();
+  let daemonRunning = false;
+  if (updatePlatform === 'systemd') {
+    try { execSync('systemctl --user is-active mindos', { stdio: 'pipe' }); daemonRunning = true; } catch {}
+  } else if (updatePlatform === 'launchd') {
+    try {
+      const uid = execSync('id -u').toString().trim();
+      execSync(`launchctl print gui/${uid}/com.mindos.app`, { stdio: 'pipe' });
+      daemonRunning = true;
+    } catch {}
+  }
+
+  if (daemonRunning) {
+    console.log(cyan('\n  Daemon is running — stopping to apply the new version...'));
+    await gateway.runGatewayCommand('stop');
+
+    // Stage 3: Rebuild
+    writeUpdateStatus('rebuilding', vOpts);
+    let daemonBuildFailed = '';
+    try {
+      buildIfNeeded(updatedRoot);
+    } catch (err) {
+      daemonBuildFailed = err instanceof Error ? err.message : String(err);
+      console.error(yellow(`\n  Pre-build failed: ${daemonBuildFailed}`));
+      console.error(yellow('  Daemon will attempt to rebuild on startup...\n'));
+    }
+
+    // Stage 4: Restart — always attempt, even if pre-build failed
+    // (daemon has auto-restart; `mindos start` retries the build)
+    writeUpdateStatus('restarting', vOpts);
+    await gateway.runGatewayCommand('install');
+    const updateConfig = (() => {
+      try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch { return {}; }
+    })();
+    const webPort = updateConfig.port ?? 3456;
+    const mcpPort = updateConfig.mcpPort ?? 8781;
+    console.log(dim('  (Waiting for Web UI to come back up — first run after update includes a rebuild...)'));
+    const ready = await gateway.waitForHttp(Number(webPort), { retries: 450, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH });
+    if (ready) {
+      const localIP = getLocalIP();
+      console.log(`\n${'─'.repeat(53)}`);
+      console.log(`${green('✔')} ${bold(`MindOS updated: ${currentVersion} → ${newVersion}`)}\n`);
+      console.log(`  ${green('●')} Web UI   ${cyan(`http://localhost:${webPort}`)}`);
+      if (localIP) console.log(`             ${cyan(`http://${localIP}:${webPort}`)}`);
+      console.log(`  ${green('●')} MCP      ${cyan(`http://localhost:${mcpPort}/mcp`)}`);
+      console.log(`\n  ${dim('View changelog:')}  ${cyan('https://github.com/GeminiLight/MindOS/releases')}`);
+      console.log(`${'─'.repeat(53)}\n`);
+      writeUpdateStatus('done', vOpts);
+    } else {
+      const failMsg = daemonBuildFailed
+        ? `Build failed (${daemonBuildFailed}), server did not come back up`
+        : 'Server did not come back up in time';
+      writeUpdateFailed('restarting', failMsg, vOpts);
+      console.error(red(`✘ ${failMsg}. Check logs: mindos logs\n`));
+      process.exit(EXIT.ERROR);
+    }
+  } else {
+    // Non-daemon mode: check if a MindOS instance is currently running
+    // (e.g. user started via `mindos start`, or GUI triggered this update).
+    // If so, stop it and restart from the NEW installation path.
+    const updateConfig = (() => {
+      try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch { return {}; }
+    })();
+    const webPort = Number(updateConfig.port ?? 3456);
+    const mcpPort = Number(updateConfig.mcpPort ?? 8781);
+
+    const wasRunning = await isPortInUse(webPort) || await isPortInUse(mcpPort);
+
+    if (wasRunning) {
+      console.log(cyan('\n  MindOS is running — restarting to apply the new version...'));
+      stopMindos();
+      // Wait for ports to free (up to 15s)
+      const deadline = Date.now() + 15_000;
+      while (Date.now() < deadline) {
+        const busy = await isPortInUse(webPort) || await isPortInUse(mcpPort);
+        if (!busy) break;
+        await new Promise((r) => setTimeout(r, 500));
+      }
+
+      // Stage 3: Rebuild
+      writeUpdateStatus('rebuilding', vOpts);
+      let buildFailed = '';
+      try {
+        buildIfNeeded(updatedRoot);
+      } catch (err) {
+        buildFailed = err instanceof Error ? err.message : String(err);
+        console.error(yellow(`\n  Pre-build failed: ${buildFailed}`));
+        console.error(yellow('  Starting server anyway (it will retry the build)...\n'));
+      }
+
+      // Stage 4: Restart — always attempt, even if pre-build failed
+      // (`mindos start` has its own build-on-startup logic)
+      writeUpdateStatus('restarting', vOpts);
+      const newCliPath = resolve(updatedRoot, 'bin', 'cli.js');
+      const childEnv = { ...process.env };
+      delete childEnv.MINDOS_WEB_PORT;
+      delete childEnv.MINDOS_MCP_PORT;
+      delete childEnv.MIND_ROOT;
+      delete childEnv.AUTH_TOKEN;
+      delete childEnv.WEB_PASSWORD;
+      const child = nodeSpawn(
+        process.execPath, [newCliPath, 'start'],
+        { detached: true, stdio: 'ignore', env: childEnv },
+      );
+      child.unref();
+
+      console.log(dim('  (Waiting for Web UI to come back up...)'));
+      const ready = await gateway.waitForHttp(webPort, { retries: 180, intervalMs: 2000, label: 'Web UI', logFile: LOG_PATH });
+      if (ready) {
+        const localIP = getLocalIP();
+        console.log(`\n${'─'.repeat(53)}`);
+        console.log(`${green('✔')} ${bold(`MindOS updated: ${currentVersion} → ${newVersion}`)}\n`);
+        console.log(`  ${green('●')} Web UI   ${cyan(`http://localhost:${webPort}`)}`);
+        if (localIP) console.log(`             ${cyan(`http://${localIP}:${webPort}`)}`);
+        console.log(`  ${green('●')} MCP      ${cyan(`http://localhost:${mcpPort}/mcp`)}`);
+        console.log(`\n  ${dim('View changelog:')}  ${cyan('https://github.com/GeminiLight/MindOS/releases')}`);
+        console.log(`${'─'.repeat(53)}\n`);
+        writeUpdateStatus('done', vOpts);
+      } else {
+        const failMsg = buildFailed
+          ? `Build failed (${buildFailed}), server did not come back up`
+          : 'Server did not come back up in time';
+        writeUpdateFailed('restarting', failMsg, vOpts);
+        console.error(red(`✘ ${failMsg}. Check logs: mindos logs\n`));
+        process.exit(EXIT.ERROR);
+      }
+    } else {
+      // No running instance — just build and tell user to start manually
+      try {
+        buildIfNeeded(updatedRoot);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(yellow(`\n  Pre-build failed: ${msg}`));
+        console.error(dim('  The build will be retried when you run `mindos start`.'));
+      }
+      console.log(`\n${green('✔')} ${bold(`Updated: ${currentVersion} → ${newVersion}`)}`);
+      console.log(dim('  Run `mindos start` to start the updated version.'));
+      console.log(`  ${dim('View changelog:')}  ${cyan('https://github.com/GeminiLight/MindOS/releases')}\n`);
+    }
+  }
+};

package/bin/lib/build.js

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
 import { resolve } from 'node:path';
 import { ROOT, BUILD_STAMP, DEPS_STAMP, STANDALONE_SERVER, STANDALONE_STAMP } from './constants.js';
 import { red, dim, yellow } from './colors.js';
-import { run, npmInstall } from './utils.js';
+import { execInherited as run, npmInstall } from './shell.js';
 
 export function needsBuild() {
   // Prefer prebuilt standalone shipped with the npm package.

package/bin/lib/colors.js

@@ -1,9 +1,10 @@
 const noColor = 'NO_COLOR' in process.env;
 const forceColor = process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '0';
-export const isTTY  = noColor ? false : (forceColor || process.stdout.isTTY);
-export const bold   = (s) => isTTY ? `\x1b[1m${s}\x1b[0m`  : s;
-export const dim    = (s) => isTTY ? `\x1b[2m${s}\x1b[0m`  : s;
-export const cyan   = (s) => isTTY ? `\x1b[36m${s}\x1b[0m` : s;
-export const green  = (s) => isTTY ? `\x1b[32m${s}\x1b[0m` : s;
-export const red    = (s) => isTTY ? `\x1b[31m${s}\x1b[0m` : s;
-export const yellow = (s) => isTTY ? `\x1b[33m${s}\x1b[0m` : s;
+const _tty  = noColor ? false : (forceColor || process.stdout.isTTY);
+export function isTTY() { return _tty; }
+export const bold   = (s) => _tty ? `\x1b[1m${s}\x1b[0m`  : s;
+export const dim    = (s) => _tty ? `\x1b[2m${s}\x1b[0m`  : s;
+export const cyan   = (s) => _tty ? `\x1b[36m${s}\x1b[0m` : s;
+export const green  = (s) => _tty ? `\x1b[32m${s}\x1b[0m` : s;
+export const red    = (s) => _tty ? `\x1b[31m${s}\x1b[0m` : s;
+export const yellow = (s) => _tty ? `\x1b[33m${s}\x1b[0m` : s;

package/bin/lib/command.js

@@ -1,59 +1,34 @@
 /**
- * Lightweight command registry — zero dependencies.
+ * Lightweight CLI utilities — zero dependencies beyond lib/.
  *
- * Each command exports: { meta, run }
- *   meta.name        — primary name
- *   meta.aliases     — optional alias names
- *   meta.group       — help group (Core, Knowledge, MCP, Sync, Gateway, Config)
- *   meta.summary     — one-line description
- *   meta.usage       — usage string (optional)
- *   meta.flags       — { flag: description } (optional)
- *   run(args, flags) — async handler
+ * Exports used by cli.js and bin/commands/*.js:
+ *   parseArgs(argv)          — parse process.argv into { command, args, flags }
+ *   printCommandHelp(cmd)    — auto-generate --help output from cmd.meta
+ *   output(data, flags)      — print human-readable or JSON
+ *   isJsonMode(flags)        — check --json flag
+ *   EXIT                     — standardized exit codes
  */
 
-import { bold, dim, cyan, green, red } from './colors.js';
-import { ROOT } from './constants.js';
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { bold, dim, cyan } from './colors.js';
 
 // ── Exit codes ────────────────────────────────────────────────────────────────
-// Standardized exit codes for CLI commands. Use these instead of raw numbers.
 export const EXIT = {
-  OK:        0,  // Success
-  ERROR:     1,  // General error
-  ARGS:      2,  // Invalid arguments or usage
-  CONNECT:   3,  // Connection refused / service not running
-  NOT_FOUND: 4,  // Resource not found (file, agent, etc.)
+  OK:        0,
+  ERROR:     1,
+  ARGS:      2,
+  CONNECT:   3,
+  NOT_FOUND: 4,
 };
 
-/** @type {Map<string, { meta: object, run: function }>} */
-const registry = new Map();
+// ── Arg parsing ───────────────────────────────────────────────────────────────
 
-/** @type {Map<string, string>} alias → primary name */
-const aliases = new Map();
-
-export function register(command) {
-  const { meta, run } = command;
-  registry.set(meta.name, { meta, run });
-  if (meta.aliases) {
-    for (const alias of meta.aliases) {
-      aliases.set(alias, meta.name);
-    }
-  }
-}
-
-export function resolve_command(name) {
-  if (registry.has(name)) return registry.get(name);
-  const primary = aliases.get(name);
-  if (primary) return registry.get(primary);
-  return null;
-}
-
-export function getAllCommands() {
-  return [...registry.values()];
+/** Parse process.argv into { command, args, flags } */
+function looksLikeFlag(s) {
+  if (!s || s.length < 2) return false;
+  if (s.startsWith('--')) return true;
+  return s.length === 2 && s[0] === '-' && /[a-zA-Z]/.test(s[1]);
 }
 
-/** Parse process.argv into { command, args, flags } */
 export function parseArgs(argv = process.argv.slice(2)) {
   const flags = {};
   const args = [];
@@ -63,17 +38,22 @@ export function parseArgs(argv = process.argv.slice(2)) {
     const arg = argv[i];
     if (arg.startsWith('--')) {
       const key = arg.slice(2);
-      // Check if next arg is a value (not a flag)
-      if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+      if (i + 1 < argv.length && !looksLikeFlag(argv[i + 1])) {
+        flags[key] = argv[i + 1];
+        i += 2;
+      } else {
+        flags[key] = true;
+        i++;
+      }
+    } else if (arg.startsWith('-') && arg.length === 2 && /[a-zA-Z]/.test(arg[1])) {
+      const key = arg.slice(1);
+      if (i + 1 < argv.length && !looksLikeFlag(argv[i + 1])) {
         flags[key] = argv[i + 1];
         i += 2;
       } else {
         flags[key] = true;
         i++;
       }
-    } else if (arg.startsWith('-') && arg.length === 2) {
-      flags[arg.slice(1)] = true;
-      i++;
     } else {
       args.push(arg);
       i++;
@@ -83,12 +63,12 @@ export function parseArgs(argv = process.argv.slice(2)) {
   return { command: args[0] || null, args: args.slice(1), flags };
 }
 
-/** Check if --json flag is set */
+// ── Output helpers ────────────────────────────────────────────────────────────
+
 export function isJsonMode(flags) {
   return flags.json === true;
 }
 
-/** Output helper: human-readable or JSON */
 export function output(data, flags) {
   if (isJsonMode(flags)) {
     console.log(JSON.stringify(data, null, 2));
@@ -99,56 +79,17 @@ export function output(data, flags) {
   }
 }
 
-/** Print global help */
-export function printHelp() {
-  const pkgVersion = (() => {
-    try {
-      return JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version;
-    } catch { return '?'; }
-  })();
-
-  const row = (c, d) => `  ${cyan(c.padEnd(38))}${dim(d)}`;
-
-  const groups = {};
-  for (const { meta } of registry.values()) {
-    const group = meta.group || 'Other';
-    if (!groups[group]) groups[group] = [];
-    const usage = meta.usage || `mindos ${meta.name}`;
-    groups[group].push(row(usage, meta.summary));
-  }
+// ── Command-specific help (auto-generated from meta) ──────────────────────────
 
-  const sections = [];
-  const groupOrder = ['Core', 'Knowledge', 'MCP', 'Sync', 'Gateway', 'Config'];
-  for (const g of groupOrder) {
-    if (groups[g]) {
-      sections.push(`${bold(`${g}:`)}\n${groups[g].join('\n')}`);
-    }
-  }
-  // Any remaining groups
-  for (const [g, items] of Object.entries(groups)) {
-    if (!groupOrder.includes(g)) {
-      sections.push(`${bold(`${g}:`)}\n${items.join('\n')}`);
-    }
-  }
-
-  console.log(`
-${bold('MindOS CLI')} ${dim(`v${pkgVersion}`)}
-
-${sections.join('\n\n')}
-
-${bold('Global Flags:')}
-  ${cyan('--json'.padEnd(38))}${dim('Output in JSON format (for agents)')}
-  ${cyan('--help, -h'.padEnd(38))}${dim('Show help')}
-  ${cyan('--version, -v'.padEnd(38))}${dim('Show version')}
-`);
-}
-
-/** Print command-specific help */
 export function printCommandHelp(cmd) {
   const { meta } = cmd;
   const usage = meta.usage || `mindos ${meta.name}`;
-  console.log(`\n${bold(usage)}\n`);
+  console.log(`\n${bold('USAGE')}`);
+  console.log(`  ${cyan(usage)}\n`);
   console.log(`  ${meta.summary}\n`);
+  if (meta.aliases && meta.aliases.length > 0) {
+    console.log(`${bold('Aliases:')} ${meta.aliases.join(', ')}\n`);
+  }
   if (meta.flags) {
     console.log(`${bold('Flags:')}`);
     for (const [flag, desc] of Object.entries(meta.flags)) {

package/bin/lib/config.js

@@ -23,8 +23,13 @@ export function loadConfig() {
   set('MINDOS_WEB_PORT',    config.port);
   set('MINDOS_MCP_PORT',    config.mcpPort);
   set('AUTH_TOKEN',         config.authToken);
+  set('MINDOS_AUTH_TOKEN',  config.authToken);
   set('WEB_PASSWORD',       config.webPassword);
   set('AI_PROVIDER',        config.ai?.provider);
+  // Remote URL: allows CLI to operate against a remote MindOS instance
+  if (config.url && !process.env.MINDOS_URL) {
+    process.env.MINDOS_URL = String(config.url);
+  }
 
   const providers = config.ai?.providers;
   if (providers) {

package/bin/lib/csv.js

@@ -0,0 +1,19 @@
+/**
+ * CSV utility functions for CLI.
+ * Port of app/lib/core/csv.ts logic (RFC 4180 escaping).
+ */
+
+/**
+ * Escape and join values into a single CSV row string.
+ * Follows RFC 4180: quote fields containing comma, double-quote, or newline.
+ * @param {string[]} row
+ * @returns {string} escaped CSV line (without trailing newline)
+ */
+export function escapeCsvRow(row) {
+  return row.map(cell => {
+    if (cell.includes(',') || cell.includes('"') || cell.includes('\n')) {
+      return `"${cell.replace(/"/g, '""')}"`;
+    }
+    return cell;
+  }).join(',');
+}

package/bin/lib/jsonc.js

@@ -0,0 +1,12 @@
+/**
+ * JSONC parser — strips comments before JSON.parse.
+ *
+ * VS Code-based editors (Cursor, Windsurf, Cline) use JSONC for config files.
+ */
+
+export const parseJsonc = (text) => {
+  let stripped = text.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*$)/gm, (m, g) => g ? '' : m);
+  stripped = stripped.replace(/\/\*[\s\S]*?\*\//g, '');
+  if (!stripped.trim()) return {};
+  return JSON.parse(stripped);
+};

package/bin/lib/markdown.js

@@ -0,0 +1,69 @@
+/**
+ * Pure Markdown section manipulation functions.
+ * Port of app/lib/core/lines.ts logic for CLI use (no server needed).
+ */
+
+/**
+ * Finds the line index of a heading in a lines array.
+ * Matches both exact ("## Foo") and bare ("Foo" matching "## Foo").
+ * @returns -1 if not found
+ */
+export function findHeadingIndex(lines, heading) {
+  const bare = heading.replace(/^#+\s*/, '');
+  return lines.findIndex(l => {
+    const trimmed = l.trim();
+    return trimmed === heading || trimmed.replace(/^#+\s*/, '') === bare;
+  });
+}
+
+/**
+ * Replace the body of a markdown section (heading → next same/higher-level heading).
+ * @returns new full content, or null if heading not found
+ */
+export function replaceSection(content, heading, newBody) {
+  const lines = content.split('\n');
+  const idx = findHeadingIndex(lines, heading);
+  if (idx === -1) return null;
+
+  const headingLevel = (lines[idx].match(/^#+/) ?? [''])[0].length;
+  let sectionEnd = lines.length - 1;
+  for (let i = idx + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^(#+)\s/);
+    if (m && m[1].length <= headingLevel) {
+      sectionEnd = i - 1;
+      break;
+    }
+  }
+  while (sectionEnd > idx && lines[sectionEnd].trim() === '') sectionEnd--;
+
+  const before = lines.slice(0, idx + 1);
+  const after = lines.slice(sectionEnd + 1);
+  return [...before, '', newBody, ...after].join('\n');
+}
+
+/**
+ * Insert content after a markdown heading (before existing body).
+ * @returns new full content, or null if heading not found
+ */
+export function insertAfterHeading(content, heading, insertion) {
+  const lines = content.split('\n');
+  const idx = findHeadingIndex(lines, heading);
+  if (idx === -1) return null;
+
+  let insertAt = idx + 1;
+  while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
+
+  const before = lines.slice(0, insertAt);
+  const after = lines.slice(insertAt);
+  return [...before, '', insertion, ...after].join('\n');
+}
+
+/**
+ * Extract all headings from markdown content.
+ * @returns array of heading lines (e.g., ["## A", "### B"])
+ */
+export function listHeadings(content) {
+  return content.split('\n')
+    .filter(l => /^#{1,6}\s/.test(l))
+    .map(l => l.trim());
+}

package/bin/lib/mcp-agents.js

@@ -8,13 +8,8 @@
  */
 
 import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
-
-function expandHome(p) {
-  return p.startsWith('~/') ? resolve(homedir(), p.slice(2)) : p;
-}
+import { expandHome } from './path-expand.js';
 
 export const MCP_AGENTS = {
   'claude-code': {

package/bin/lib/mcp-build.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { ROOT } from './constants.js';
 import { yellow } from './colors.js';
-import { run, npmInstall } from './utils.js';
+import { execInherited as run, npmInstall } from './shell.js';
 
 export const MCP_DIR = resolve(ROOT, 'mcp');
 export const MCP_SRC_DIR = resolve(MCP_DIR, 'src');

package/bin/lib/mcp-install.js

@@ -2,7 +2,8 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { CONFIG_PATH } from './constants.js';
 import { bold, dim, cyan, green, red, yellow } from './colors.js';
-import { expandHome, parseJsonc } from './utils.js';
+import { expandHome } from './path-expand.js';
+import { parseJsonc } from './jsonc.js';
 import { MCP_AGENTS, detectAgentPresence } from './mcp-agents.js';
 
 export { MCP_AGENTS };