@geminilight/mindos 0.1.7 → 0.1.9

package/bin/lib/build.js

@@ -0,0 +1,59 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ROOT, BUILD_STAMP } from './constants.js';
+import { red, dim, yellow } from './colors.js';
+import { run } from './utils.js';
+
+export function needsBuild() {
+  const nextDir = resolve(ROOT, 'app', '.next');
+  if (!existsSync(nextDir)) return true;
+  try {
+    const builtVersion = readFileSync(BUILD_STAMP, 'utf-8').trim();
+    const currentVersion = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version;
+    return builtVersion !== currentVersion;
+  } catch {
+    return true;
+  }
+}
+
+export function writeBuildStamp() {
+  const version = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')).version;
+  writeFileSync(BUILD_STAMP, version, 'utf-8');
+}
+
+export function clearBuildLock() {
+  const lockFile = resolve(ROOT, 'app', '.next', 'lock');
+  if (existsSync(lockFile)) {
+    rmSync(lockFile, { force: true });
+  }
+}
+
+export function cleanNextDir() {
+  const nextDir = resolve(ROOT, 'app', '.next');
+  if (existsSync(nextDir)) {
+    rmSync(nextDir, { recursive: true, force: true });
+  }
+}
+
+export function ensureAppDeps() {
+  const appNext = resolve(ROOT, 'app', 'node_modules', 'next', 'package.json');
+  if (!existsSync(appNext)) {
+    try {
+      execSync('npm --version', { stdio: 'pipe' });
+    } catch {
+      console.error(red('\n\u2718 npm not found in PATH.\n'));
+      console.error('  MindOS needs npm to install its app dependencies on first run.');
+      console.error('  This usually means Node.js is installed via a version manager (nvm, fnm, volta, etc.)');
+      console.error('  that only loads in interactive shells, but not in /bin/sh.\n');
+      console.error('  Fix: add your Node.js bin directory to a profile that /bin/sh reads (~/.profile).');
+      console.error('  Example:');
+      console.error(dim('    echo \'export PATH="$HOME/.nvm/versions/node/$(node --version)/bin:$PATH"\' >> ~/.profile'));
+      console.error(dim('    source ~/.profile\n'));
+      console.error('  Then run `mindos start` again.\n');
+      process.exit(1);
+    }
+    console.log(yellow('Installing app dependencies (first run)...\n'));
+    run('npm install --prefer-offline --no-workspaces', resolve(ROOT, 'app'));
+  }
+}

package/bin/lib/colors.js

@@ -0,0 +1,7 @@
+export const isTTY  = 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;

package/bin/lib/config.js

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { CONFIG_PATH } from './constants.js';
+
+export function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) return;
+  let config;
+  try {
+    config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    console.error(`Warning: failed to parse ${CONFIG_PATH}`);
+    return;
+  }
+
+  const set = (key, val) => {
+    if (val && !process.env[key]) process.env[key] = String(val);
+  };
+
+  set('MIND_ROOT',          config.mindRoot);
+  set('MINDOS_WEB_PORT',    config.port);
+  set('MINDOS_MCP_PORT',    config.mcpPort);
+  set('AUTH_TOKEN',         config.authToken);
+  set('WEB_PASSWORD',       config.webPassword);
+  set('AI_PROVIDER',        config.ai?.provider);
+
+  const providers = config.ai?.providers;
+  if (providers) {
+    set('ANTHROPIC_API_KEY', providers.anthropic?.apiKey);
+    set('ANTHROPIC_MODEL',   providers.anthropic?.model);
+    set('OPENAI_API_KEY',    providers.openai?.apiKey);
+    set('OPENAI_MODEL',      providers.openai?.model);
+    set('OPENAI_BASE_URL',   providers.openai?.baseUrl);
+  } else {
+    set('ANTHROPIC_API_KEY', config.ai?.anthropicApiKey);
+    set('ANTHROPIC_MODEL',   config.ai?.anthropicModel);
+    set('OPENAI_API_KEY',    config.ai?.openaiApiKey);
+    set('OPENAI_MODEL',      config.ai?.openaiModel);
+    set('OPENAI_BASE_URL',   config.ai?.openaiBaseUrl);
+  }
+}
+
+export function getStartMode() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')).startMode || 'start';
+  } catch {
+    return 'start';
+  }
+}

package/bin/lib/constants.js

@@ -0,0 +1,13 @@
+import { resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const ROOT        = resolve(__dirname, '..', '..');
+export const CONFIG_PATH = resolve(homedir(), '.mindos', 'config.json');
+export const PID_PATH    = resolve(homedir(), '.mindos', 'mindos.pid');
+export const BUILD_STAMP = resolve(ROOT, 'app', '.next', '.mindos-build-version');
+export const MINDOS_DIR  = resolve(homedir(), '.mindos');
+export const LOG_PATH    = resolve(MINDOS_DIR, 'mindos.log');
+export const CLI_PATH    = resolve(__dirname, '..', 'cli.js');
+export const NODE_BIN    = process.execPath;

package/bin/lib/gateway.js

@@ -0,0 +1,244 @@
+import { execSync } from 'node:child_process';
+import { existsSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { MINDOS_DIR, LOG_PATH, CLI_PATH, NODE_BIN } from './constants.js';
+import { green, red, dim, cyan } from './colors.js';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+export function getPlatform() {
+  if (process.platform === 'darwin') return 'launchd';
+  if (process.platform === 'linux')  return 'systemd';
+  return null;
+}
+
+export function ensureMindosDir() {
+  if (!existsSync(MINDOS_DIR)) mkdirSync(MINDOS_DIR, { recursive: true });
+}
+
+export async function waitForService(check, { retries = 10, intervalMs = 1000 } = {}) {
+  for (let i = 0; i < retries; i++) {
+    if (check()) return true;
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  return check();
+}
+
+export async function waitForHttp(port, { retries = 120, intervalMs = 2000, label = 'service' } = {}) {
+  process.stdout.write(cyan(`  Waiting for ${label} to be ready`));
+  for (let i = 0; i < retries; i++) {
+    try {
+      const { request } = await import('node:http');
+      const ok = await new Promise((resolve) => {
+        const req = request({ hostname: '127.0.0.1', port, path: '/', method: 'HEAD', timeout: 1500 },
+          (res) => { res.resume(); resolve(res.statusCode < 500); });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+        req.end();
+      });
+      if (ok) { process.stdout.write(` ${green('\u2714')}\n`); return true; }
+    } catch { /* not ready yet */ }
+    process.stdout.write('.');
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  process.stdout.write(` ${red('\u2718')}\n`);
+  return false;
+}
+
+function launchctlUid() {
+  return execSync('id -u').toString().trim();
+}
+
+// ── systemd (Linux) ──────────────────────────────────────────────────────────
+
+const SYSTEMD_DIR  = resolve(homedir(), '.config', 'systemd', 'user');
+const SYSTEMD_UNIT = resolve(SYSTEMD_DIR, 'mindos.service');
+
+const systemd = {
+  install() {
+    if (!existsSync(SYSTEMD_DIR)) mkdirSync(SYSTEMD_DIR, { recursive: true });
+    ensureMindosDir();
+    const currentPath = process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin';
+    const unit = [
+      '[Unit]',
+      'Description=MindOS app + MCP server',
+      'After=network.target',
+      '',
+      '[Service]',
+      'Type=simple',
+      `ExecStart=${NODE_BIN} ${CLI_PATH} start`,
+      'Restart=on-failure',
+      'RestartSec=3',
+      `Environment=HOME=${homedir()}`,
+      `Environment=PATH=${currentPath}`,
+      `EnvironmentFile=-${resolve(MINDOS_DIR, 'env')}`,
+      `StandardOutput=append:${LOG_PATH}`,
+      `StandardError=append:${LOG_PATH}`,
+      '',
+      '[Install]',
+      'WantedBy=default.target',
+    ].join('\n');
+    writeFileSync(SYSTEMD_UNIT, unit, 'utf-8');
+    console.log(green(`\u2714 Wrote ${SYSTEMD_UNIT}`));
+    execSync('systemctl --user daemon-reload', { stdio: 'inherit' });
+    execSync('systemctl --user enable mindos', { stdio: 'inherit' });
+    console.log(green('\u2714 Service installed and enabled'));
+  },
+
+  async start() {
+    execSync('systemctl --user start mindos', { stdio: 'inherit' });
+    const ok = await waitForService(() => {
+      try {
+        const out = execSync('systemctl --user is-active mindos', { encoding: 'utf-8' }).trim();
+        return out === 'active';
+      } catch { return false; }
+    });
+    if (!ok) {
+      console.error(red('\n\u2718 Service failed to start. Last log output:'));
+      try { execSync(`journalctl --user -u mindos -n 30 --no-pager`, { stdio: 'inherit' }); } catch {}
+      process.exit(1);
+    }
+    console.log(green('\u2714 Service started'));
+  },
+
+  stop() {
+    execSync('systemctl --user stop mindos', { stdio: 'inherit' });
+    console.log(green('\u2714 Service stopped'));
+  },
+
+  status() {
+    try {
+      execSync('systemctl --user status mindos', { stdio: 'inherit' });
+    } catch { /* status exits non-zero when stopped */ }
+  },
+
+  logs() {
+    execSync(`journalctl --user -u mindos -f`, { stdio: 'inherit' });
+  },
+
+  uninstall() {
+    try {
+      execSync('systemctl --user disable --now mindos', { stdio: 'inherit' });
+    } catch { /* may already be stopped */ }
+    if (existsSync(SYSTEMD_UNIT)) {
+      rmSync(SYSTEMD_UNIT);
+      console.log(green(`\u2714 Removed ${SYSTEMD_UNIT}`));
+    }
+    execSync('systemctl --user daemon-reload', { stdio: 'inherit' });
+    console.log(green('\u2714 Service uninstalled'));
+  },
+};
+
+// ── launchd (macOS) ──────────────────────────────────────────────────────────
+
+const LAUNCHD_DIR   = resolve(homedir(), 'Library', 'LaunchAgents');
+const LAUNCHD_PLIST = resolve(LAUNCHD_DIR, 'com.mindos.app.plist');
+const LAUNCHD_LABEL = 'com.mindos.app';
+
+const launchd = {
+  install() {
+    if (!existsSync(LAUNCHD_DIR)) mkdirSync(LAUNCHD_DIR, { recursive: true });
+    ensureMindosDir();
+    const currentPath = process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin';
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${NODE_BIN}</string>
+    <string>${CLI_PATH}</string>
+    <string>start</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${LOG_PATH}</string>
+  <key>StandardErrorPath</key><string>${LOG_PATH}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key><string>${homedir()}</string>
+    <key>PATH</key><string>${currentPath}</string>
+  </dict>
+</dict>
+</plist>
+`;
+    writeFileSync(LAUNCHD_PLIST, plist, 'utf-8');
+    console.log(green(`\u2714 Wrote ${LAUNCHD_PLIST}`));
+    try { execSync(`launchctl bootout gui/${launchctlUid()}/${LAUNCHD_LABEL}`, { stdio: 'pipe' }); } catch {}
+    try {
+      execSync(`launchctl bootstrap gui/${launchctlUid()} ${LAUNCHD_PLIST}`, { stdio: 'pipe' });
+    } catch (e) {
+      const msg = (e.stderr?.toString() ?? e.message ?? '').trim();
+      console.error(red(`\n\u2718 launchctl bootstrap failed: ${msg}`));
+      console.error(dim('  Try running: launchctl bootout gui/$(id -u)/com.mindos.app  then retry.\n'));
+      process.exit(1);
+    }
+    console.log(green('\u2714 Service installed'));
+  },
+
+  async start() {
+    execSync(`launchctl kickstart -k gui/${launchctlUid()}/${LAUNCHD_LABEL}`, { stdio: 'inherit' });
+    const ok = await waitForService(() => {
+      try {
+        const out = execSync(`launchctl print gui/${launchctlUid()}/${LAUNCHD_LABEL}`, { encoding: 'utf-8' });
+        return out.includes('state = running');
+      } catch { return false; }
+    });
+    if (!ok) {
+      console.error(red('\n\u2718 Service failed to start. Last log output:'));
+      try { execSync(`tail -n 30 ${LOG_PATH}`, { stdio: 'inherit' }); } catch {}
+      process.exit(1);
+    }
+    console.log(green('\u2714 Service started'));
+  },
+
+  stop() {
+    try {
+      execSync(`launchctl bootout gui/${launchctlUid()} ${LAUNCHD_PLIST}`, { stdio: 'inherit' });
+    } catch { /* may not be running */ }
+    console.log(green('\u2714 Service stopped'));
+  },
+
+  status() {
+    try {
+      execSync(`launchctl print gui/${launchctlUid()}/${LAUNCHD_LABEL}`, { stdio: 'inherit' });
+    } catch {
+      console.log(dim('Service is not running'));
+    }
+  },
+
+  logs() {
+    execSync(`tail -f ${LOG_PATH}`, { stdio: 'inherit' });
+  },
+
+  uninstall() {
+    try {
+      execSync(`launchctl bootout gui/${launchctlUid()} ${LAUNCHD_PLIST}`, { stdio: 'inherit' });
+    } catch { /* may not be running */ }
+    if (existsSync(LAUNCHD_PLIST)) {
+      rmSync(LAUNCHD_PLIST);
+      console.log(green(`\u2714 Removed ${LAUNCHD_PLIST}`));
+    }
+    console.log(green('\u2714 Service uninstalled'));
+  },
+};
+
+// ── Gateway dispatcher ───────────────────────────────────────────────────────
+
+export async function runGatewayCommand(sub) {
+  const platform = getPlatform();
+  if (!platform) {
+    console.error(red('Daemon mode is not supported on this platform (requires Linux/systemd or macOS/launchd)'));
+    process.exit(1);
+  }
+  const impl = platform === 'systemd' ? systemd : launchd;
+  const fn = impl[sub];
+  if (!fn) {
+    console.error(red(`Unknown gateway subcommand: ${sub}`));
+    console.error(dim('Available: install | uninstall | start | stop | status | logs'));
+    process.exit(1);
+  }
+  await fn();
+}

package/bin/lib/mcp-install.js

@@ -0,0 +1,156 @@
+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 } from './utils.js';
+
+export const MCP_AGENTS = {
+  'claude-code':     { name: 'Claude Code',     project: '.mcp.json',                       global: '~/.claude.json',                                                                         key: 'mcpServers' },
+  'claude-desktop':  { name: 'Claude Desktop',  project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Claude/claude_desktop_config.json' : '~/.config/Claude/claude_desktop_config.json', key: 'mcpServers' },
+  'cursor':          { name: 'Cursor',           project: '.cursor/mcp.json',                global: '~/.cursor/mcp.json',                                                                     key: 'mcpServers' },
+  'windsurf':        { name: 'Windsurf',         project: null,                               global: '~/.codeium/windsurf/mcp_config.json',                                                   key: 'mcpServers' },
+  'cline':           { name: 'Cline',            project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json' : '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json', key: 'mcpServers' },
+  'trae':            { name: 'Trae',             project: '.trae/mcp.json',                  global: '~/.trae/mcp.json',                                                                       key: 'mcpServers' },
+  'gemini-cli':      { name: 'Gemini CLI',       project: '.gemini/settings.json',           global: '~/.gemini/settings.json',                                                                key: 'mcpServers' },
+  'openclaw':        { name: 'OpenClaw',         project: null,                               global: '~/.openclaw/mcp.json',                                                                   key: 'mcpServers' },
+  'codebuddy':       { name: 'CodeBuddy',        project: null,                               global: '~/.claude-internal/.claude.json',                                                        key: 'mcpServers' },
+};
+
+export async function mcpInstall() {
+  // Support both `mindos mcp install [agent] [flags]` and `mindos mcp [flags]`
+  const sub = process.argv[3];
+  const startIdx = sub === 'install' ? 4 : 3;
+  const args = process.argv.slice(startIdx);
+
+  // parse flags
+  const hasGlobalFlag    = args.includes('-g') || args.includes('--global');
+  const hasYesFlag       = args.includes('-y') || args.includes('--yes');
+  const transportIdx     = args.findIndex(a => a === '--transport');
+  const urlIdx           = args.findIndex(a => a === '--url');
+  const tokenIdx         = args.findIndex(a => a === '--token');
+  const transportArg     = transportIdx >= 0 ? args[transportIdx + 1] : null;
+  const urlArg           = urlIdx     >= 0 ? args[urlIdx + 1]     : null;
+  const tokenArg         = tokenIdx   >= 0 ? args[tokenIdx + 1]   : null;
+
+  // agent positional arg: first non-flag arg (not preceded by a flag expecting a value)
+  const flagsWithValue = new Set(['--transport', '--url', '--token']);
+  const agentArg = args.find((a, i) => !a.startsWith('-') && (i === 0 || !flagsWithValue.has(args[i - 1]))) ?? null;
+
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(r => rl.question(q, r));
+  const choose = async (prompt, options, { defaultIdx = 0, forcePrompt = false } = {}) => {
+    if (hasYesFlag && !forcePrompt) return options[defaultIdx];
+    console.log(`\n${bold(prompt)}\n`);
+    options.forEach((o, i) => console.log(`  ${dim(`${i + 1}.`)} ${o.label} ${o.hint ? dim(`(${o.hint})`) : ''}`));
+    const ans = await ask(`\n${bold(`Enter number`)} ${dim(`[${defaultIdx + 1}]:`)} `);
+    const idx = ans.trim() === '' ? defaultIdx : parseInt(ans.trim(), 10) - 1;
+    return options[idx >= 0 && idx < options.length ? idx : defaultIdx];
+  };
+
+  console.log(`\n${bold('🔌 MindOS MCP Install')}\n`);
+
+  // ── 1. agent ────────────────────────────────────────────────────────────────
+  let agentKey = agentArg;
+  if (!agentKey) {
+    const keys = Object.keys(MCP_AGENTS);
+    const picked = await choose('Which Agent would you like to configure?',
+      keys.map(k => ({ label: MCP_AGENTS[k].name, hint: k, value: k })), { forcePrompt: true });
+    agentKey = picked.value;
+  }
+
+  const agent = MCP_AGENTS[agentKey];
+  if (!agent) {
+    rl.close();
+    console.error(red(`\nUnknown agent: ${agentKey}`));
+    console.error(dim(`Supported: ${Object.keys(MCP_AGENTS).join(', ')}`));
+    process.exit(1);
+  }
+
+  // ── 2. scope (only ask if agent supports both) ───────────────────────────────
+  let isGlobal = hasGlobalFlag;
+  if (!hasGlobalFlag) {
+    if (agent.project && agent.global) {
+      const picked = await choose('Install scope?', [
+        { label: 'Project',  hint: agent.project, value: 'project' },
+        { label: 'Global',   hint: agent.global,  value: 'global'  },
+      ]);
+      isGlobal = picked.value === 'global';
+    } else {
+      isGlobal = !agent.project;
+    }
+  }
+
+  const configPath = isGlobal ? agent.global : agent.project;
+  if (!configPath) {
+    rl.close();
+    console.error(red(`${agent.name} does not support ${isGlobal ? 'global' : 'project'} scope.`));
+    process.exit(1);
+  }
+
+  // ── 3. transport ─────────────────────────────────────────────────────────────
+  let transport = transportArg;
+  if (!transport) {
+    const picked = await choose('Transport type?', [
+      { label: 'stdio', hint: 'local, no server process needed (recommended)' },
+      { label: 'http',  hint: 'URL-based, use when server is running separately or remotely' },
+    ]);
+    transport = picked.label;
+  }
+
+  // ── 4. url + token (only for http) ───────────────────────────────────────────
+  let url = urlArg;
+  let token = tokenArg;
+
+  if (transport === 'http') {
+    if (!url) {
+      url = hasYesFlag ? 'http://localhost:8787/mcp' : (await ask(`${bold('MCP URL')} ${dim('[http://localhost:8787/mcp]:')} `)).trim() || 'http://localhost:8787/mcp';
+    }
+
+    if (!token) {
+      try { token = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')).authToken || ''; } catch {}
+      if (token) {
+        console.log(dim(`  Using auth token from ~/.mindos/config.json`));
+      } else if (!hasYesFlag) {
+        token = (await ask(`${bold('Auth token')} ${dim('(leave blank to skip):')} `)).trim();
+      } else {
+        console.log(yellow(`  Warning: no auth token found in ~/.mindos/config.json — config will have no auth.`));
+        console.log(dim(`  Run \`mindos onboard\` to set one, or pass --token <token>.`));
+      }
+    }
+  }
+
+  rl.close();
+
+  // ── build entry ──────────────────────────────────────────────────────────────
+  const entry = transport === 'stdio'
+    ? { type: 'stdio', command: 'mindos', args: ['mcp'], env: { MCP_TRANSPORT: 'stdio' } }
+    : token
+      ? { url, headers: { Authorization: `Bearer ${token}` } }
+      : { url };
+
+  // ── read + merge existing config ─────────────────────────────────────────────
+  const absPath = expandHome(configPath);
+  let config = {};
+  if (existsSync(absPath)) {
+    try { config = JSON.parse(readFileSync(absPath, 'utf-8')); } catch {
+      console.error(red(`\nFailed to parse existing config: ${absPath}`));
+      process.exit(1);
+    }
+  }
+
+  if (!config[agent.key]) config[agent.key] = {};
+  const existed = !!config[agent.key].mindos;
+  config[agent.key].mindos = entry;
+
+  // ── preview + write ──────────────────────────────────────────────────────────
+  console.log(`\n${bold('Preview:')} ${dim(absPath)}\n`);
+  console.log(dim(JSON.stringify({ [agent.key]: { mindos: entry } }, null, 2)));
+
+  const dir = resolve(absPath, '..');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(absPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+
+  console.log(`\n${green('\u2714')} ${existed ? 'Updated' : 'Installed'} MindOS MCP for ${bold(agent.name)}`);
+  console.log(dim(`  Config: ${absPath}\n`));
+}

package/bin/lib/mcp-spawn.js

@@ -0,0 +1,36 @@
+import { execSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ROOT } from './constants.js';
+import { bold, red, yellow } from './colors.js';
+
+export function spawnMcp(verbose = false) {
+  const mcpPort = process.env.MINDOS_MCP_PORT || '8787';
+  const webPort = process.env.MINDOS_WEB_PORT || '3000';
+  // Ensure mcp/node_modules exists (auto-install on first run)
+  const mcpSdk = resolve(ROOT, 'mcp', 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json');
+  if (!existsSync(mcpSdk)) {
+    console.log(yellow('Installing MCP dependencies (first run)...\n'));
+    execSync('npm install --prefer-offline --no-workspaces', { cwd: resolve(ROOT, 'mcp'), stdio: 'inherit' });
+  }
+  const env = {
+    ...process.env,
+    MCP_PORT: mcpPort,
+    MINDOS_URL: `http://localhost:${webPort}`,
+    ...(verbose ? { MCP_VERBOSE: '1' } : {}),
+  };
+  const child = spawn('npx', ['tsx', 'src/index.ts'], {
+    cwd: resolve(ROOT, 'mcp'),
+    stdio: 'inherit',
+    env,
+  });
+  child.on('error', (err) => {
+    if (err.message.includes('EADDRINUSE')) {
+      console.error(`\n${red('\u2718')} ${bold(`MCP port ${mcpPort} is already in use`)}`);
+      console.error(`  ${'Run:'} mindos stop\n`);
+    } else {
+      console.error(red('MCP server error:'), err.message);
+    }
+  });
+  return child;
+}

package/bin/lib/pid.js

@@ -0,0 +1,15 @@
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { PID_PATH } from './constants.js';
+
+export function savePids(...pids) {
+  writeFileSync(PID_PATH, pids.filter(Boolean).join('\n'), 'utf-8');
+}
+
+export function loadPids() {
+  if (!existsSync(PID_PATH)) return [];
+  return readFileSync(PID_PATH, 'utf-8').split('\n').map(Number).filter(Boolean);
+}
+
+export function clearPids() {
+  if (existsSync(PID_PATH)) rmSync(PID_PATH);
+}

package/bin/lib/port.js

@@ -0,0 +1,19 @@
+import { createConnection } from 'node:net';
+import { bold, dim, red } from './colors.js';
+
+export function isPortInUse(port) {
+  return new Promise((resolve) => {
+    const sock = createConnection({ port, host: '127.0.0.1' });
+    sock.once('connect', () => { sock.destroy(); resolve(true); });
+    sock.once('error',   () => { sock.destroy(); resolve(false); });
+  });
+}
+
+export async function assertPortFree(port, name) {
+  if (await isPortInUse(port)) {
+    console.error(`\n${red('\u2718')} ${bold(`Port ${port} is already in use`)} ${dim(`(${name})`)}`);
+    console.error(`\n  ${dim('Stop MindOS:')}       mindos stop`);
+    console.error(`  ${dim('Find the process:')}  lsof -i :${port}\n`);
+    process.exit(1);
+  }
+}

package/bin/lib/startup.js

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import { networkInterfaces } from 'node:os';
+import { CONFIG_PATH } from './constants.js';
+import { bold, dim, cyan, green } from './colors.js';
+
+export function getLocalIP() {
+  try {
+    for (const ifaces of Object.values(networkInterfaces())) {
+      for (const iface of ifaces) {
+        if (iface.family === 'IPv4' && !iface.internal) return iface.address;
+      }
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+export function printStartupInfo(webPort, mcpPort) {
+  let config = {};
+  try { config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch { /* ignore */ }
+  const authToken = config.authToken || '';
+  const localIP   = getLocalIP();
+
+  const auth = authToken
+    ? `,\n        "headers": { "Authorization": "Bearer ${authToken}" }`
+    : '';
+  const block = (host) =>
+    `  {\n    "mcpServers": {\n      "mindos": {\n        "url": "http://${host}:${mcpPort}/mcp"${auth}\n      }\n    }\n  }`;
+
+  console.log(`\n${'─'.repeat(53)}`);
+  console.log(`${bold('🧠 MindOS is starting')}\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`)}`);
+  if (localIP) console.log(`             ${cyan(`http://${localIP}:${mcpPort}/mcp`)}`);
+  if (localIP) console.log(dim(`\n  💡 Running on a remote server? Open the Network URL (${localIP}) in your browser,\n     or use SSH port forwarding: ssh -L ${webPort}:localhost:${webPort} user@${localIP}`));
+  console.log();
+  console.log(bold('Configure MCP in your Agent:'));
+  console.log(dim('  Local (same machine):'));
+  console.log(block('localhost'));
+  if (localIP) {
+    console.log(dim('\n  Remote (other device):'));
+    console.log(block(localIP));
+  }
+  if (authToken) {
+    console.log(`\n  🔑 ${bold('Auth token:')} ${cyan(authToken)}`);
+    console.log(dim('  Run `mindos token` anytime to view it again'));
+  }
+  console.log(dim('\n  Install Skills (optional):'));
+  console.log(dim('  npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y'));
+  console.log(`${'─'.repeat(53)}\n`);
+}