dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/cli/src/mcp-cmd.js

@@ -0,0 +1,326 @@
+// `dexterm mcp …` — the read-only MCP server plus one-command setup for any agent (task-1405).
+//
+//   dexterm mcp                         run the read-only MCP server on stdio (what the analyst uses and
+//                                       what `claude mcp add dexterm -- dexterm mcp` wires up)
+//   dexterm mcp install <client>        write/print the MCP config for a client (claude-code, claude-desktop,
+//                                       cursor, codex, openclaw, generic). Shows the exact change, asks first,
+//                                       is idempotent, and backs the file up before editing.
+//   dexterm mcp doctor                  spawn the server over stdio, do the MCP handshake, and list the tools,
+//                                       prompts and resources the agent sees — proof the connection works.
+//
+// install writes nothing without consent: it prints the target file and the exact snippet, then (unless
+// --yes) asks on a TTY; a non-TTY run without --yes prints the plan and stops. --print never writes. The
+// config dir is resolved from the environment; --config FILE overrides it (tests point this at a temp dir),
+// so this command NEVER has to touch the real ~/.claude, Cursor or Claude Desktop config to be exercised.
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+function flag(rest, name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
+function has(rest, name) { return rest.includes(name); }
+export function defaultCommand(env, useNode) {
+    if (!useNode)
+        return { command: 'dexterm', args: ['mcp'] };
+    // Fallback for when dexterm is not on PATH: run this repo's server bin with the current node.
+    return { command: process.execPath, args: [mcpBinPath(), 'mcp'] };
+}
+/** Where this repo's standalone MCP server bin lives (used by the --node command and by `doctor`). */
+export function mcpBinPath() {
+    const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
+    return resolve(here, '..', '..', 'mcp', 'bin', 'dexterm-mcp.mjs');
+}
+function home(env) { return env.HOME || env.USERPROFILE || homedir(); }
+function appSupport(env, platform, app) {
+    if (platform === 'darwin')
+        return join(home(env), 'Library', 'Application Support', app);
+    if (platform === 'win32')
+        return join(env.APPDATA || join(home(env), 'AppData', 'Roaming'), app);
+    return join(env.XDG_CONFIG_HOME || join(home(env), '.config'), app);
+}
+export const CLIENTS = [
+    {
+        id: 'claude-code', label: 'Claude Code', format: 'json', keyPath: 'mcpServers',
+        path: (env) => join(env.DEXTERM_CWD || process.cwd(), '.mcp.json'),
+        note: 'project-scoped .mcp.json in the current directory; or run `claude mcp add dexterm -- dexterm mcp`.',
+    },
+    {
+        id: 'claude-desktop', label: 'Claude Desktop', format: 'json', keyPath: 'mcpServers',
+        path: (env, platform) => join(appSupport(env, platform, 'Claude'), 'claude_desktop_config.json'),
+        note: 'restart Claude Desktop after editing so it re-reads the config.',
+    },
+    {
+        id: 'cursor', label: 'Cursor', format: 'json', keyPath: 'mcpServers',
+        path: (env) => join(home(env), '.cursor', 'mcp.json'),
+        note: 'global Cursor MCP config (~/.cursor/mcp.json); a project .cursor/mcp.json works too.',
+    },
+    {
+        id: 'codex', label: 'Codex CLI', format: 'toml', keyPath: 'mcp_servers',
+        path: (env) => join(env.CODEX_HOME || join(home(env), '.codex'), 'config.toml'),
+        note: 'Codex reads MCP servers from the [mcp_servers.*] tables in ~/.codex/config.toml.',
+    },
+    {
+        id: 'openclaw', label: 'OpenClaw / generic agent', format: 'print', keyPath: 'mcpServers',
+        path: () => null,
+        note: 'OpenClaw and most agents take a standard mcpServers entry; paste this where your agent reads MCP servers, or pass --config FILE to write a JSON file.',
+    },
+    {
+        id: 'generic', label: 'Generic (print the snippet)', format: 'print', keyPath: 'mcpServers',
+        path: () => null,
+        note: 'the standard stdio MCP server entry; add it to your client\'s MCP config.',
+    },
+];
+export function clientById(id) { return CLIENTS.find((c) => c.id === id); }
+/** The JSON object a json-format client expects under its server map, for `dexterm`. */
+export function serverEntryJson(cmd) {
+    return { command: cmd.command, args: cmd.args };
+}
+/** The TOML block a codex-style client expects. */
+export function serverEntryToml(cmd) {
+    const args = cmd.args.map((a) => JSON.stringify(a)).join(', ');
+    return `[mcp_servers.dexterm]\ncommand = ${JSON.stringify(cmd.command)}\nargs = [${args}]\n`;
+}
+/** Plan a JSON merge: returns the new file text and whether anything changes. Preserves every other key. */
+export function planJson(existingText, keyPath, entry) {
+    let obj = {};
+    if (existingText && existingText.trim()) {
+        try {
+            const parsed = JSON.parse(existingText);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                obj = parsed;
+        }
+        catch {
+            throw new Error('the existing config is not valid JSON — fix or move it, then re-run');
+        }
+    }
+    const map = (obj[keyPath] && typeof obj[keyPath] === 'object' && !Array.isArray(obj[keyPath])) ? obj[keyPath] : {};
+    const prev = map.dexterm;
+    const was = prev === undefined ? 'absent' : JSON.stringify(prev) === JSON.stringify(entry) ? 'same' : 'different';
+    const next = { ...obj, [keyPath]: { ...map, dexterm: entry } };
+    return { text: JSON.stringify(next, null, 2) + '\n', changed: was !== 'same', was };
+}
+/** Plan a TOML merge: append the dexterm block when there is no [mcp_servers.dexterm] yet; never clobber. */
+export function planToml(existingText, block) {
+    const cur = existingText ?? '';
+    if (cur.includes(block.trim()))
+        return { text: cur, changed: false, was: 'same', conflict: false };
+    if (/\[mcp_servers\.dexterm\]/.test(cur))
+        return { text: cur, changed: false, was: 'different', conflict: true };
+    const sep = cur.length && !cur.endsWith('\n\n') ? (cur.endsWith('\n') ? '\n' : '\n\n') : '';
+    return { text: cur + sep + block, changed: true, was: 'absent', conflict: false };
+}
+function readLineYesNo(io, prompt) {
+    const stdin = io.stdin;
+    if (!stdin || !stdin.isTTY)
+        return Promise.resolve(false);
+    return new Promise((res) => {
+        const rl = readline.createInterface({ input: stdin, output: io.stdout });
+        rl.question(prompt, (ans) => { rl.close(); res(/^y(es)?$/i.test(ans.trim())); });
+    });
+}
+function backupPath(file) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `${file}.bak-${stamp}`;
+}
+async function install(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    const id = rest.find((a) => !a.startsWith('-'));
+    const spec = id ? clientById(id) : undefined;
+    if (!spec) {
+        errOut(`usage: dexterm mcp install <${CLIENTS.map((c) => c.id).join('|')}> [--config FILE] [--print] [--node] [--yes]`);
+        if (id)
+            errOut(`unknown client "${id}". known: ${CLIENTS.map((c) => c.id).join(', ')}`);
+        return 2;
+    }
+    const printOnly = has(rest, '--print');
+    const useNode = has(rest, '--node');
+    const yes = has(rest, '--yes') || has(rest, '-y');
+    const cmd = defaultCommand(io.env, useNode);
+    const override = flag(rest, '--config');
+    const target = override ? resolve(override) : spec.path(io.env, process.platform);
+    const forcePrint = spec.format === 'print' && !override;
+    // The snippet we would add, always shown.
+    const snippet = spec.format === 'toml' ? serverEntryToml(cmd) : JSON.stringify({ [spec.keyPath]: { dexterm: serverEntryJson(cmd) } }, null, 2);
+    out(`dexterm MCP server for ${spec.label}:`);
+    out('');
+    out(indent(snippet));
+    out('');
+    if (spec.note)
+        out(`note: ${spec.note}`);
+    if (printOnly || forcePrint) {
+        if (forcePrint && !printOnly)
+            out('(this client has no single well-known config file — paste the snippet above, or pass --config FILE to write it.)');
+        return 0;
+    }
+    if (!target) {
+        out('pass --config FILE to write this to a specific file.');
+        return 0;
+    }
+    const existed = existsSync(target);
+    const existingText = existed ? readFileSync(target, 'utf8') : null;
+    let plan;
+    try {
+        plan = spec.format === 'toml'
+            ? planToml(existingText, serverEntryToml(cmd))
+            : planJson(existingText, spec.keyPath, serverEntryJson(cmd));
+    }
+    catch (e) {
+        errOut(`dexterm mcp install: ${e.message} (${target})`);
+        return 1;
+    }
+    out('');
+    out(`target: ${target}${existed ? '' : ' (new file)'}`);
+    if (plan.conflict) {
+        out('a [mcp_servers.dexterm] section already exists and differs; not modifying it. Review it by hand, or edit it to match the snippet above.');
+        return 0;
+    }
+    if (!plan.changed) {
+        out('already configured — nothing to change (idempotent).');
+        return 0;
+    }
+    out(plan.was === 'different' ? 'this UPDATES the existing dexterm entry.' : existed ? 'this ADDS a dexterm entry (your other servers are preserved).' : 'this CREATES the config file with a dexterm entry.');
+    if (!yes) {
+        const ok = await readLineYesNo(io, 'write this change? [y/N] ');
+        if (!ok) {
+            out(io.stdin?.isTTY ? 'cancelled; nothing was written.' : 'not a TTY and --yes was not given; nothing written. Re-run with --yes to write, or --print to just print.');
+            return io.stdin?.isTTY ? 0 : 0;
+        }
+    }
+    try {
+        mkdirSync(dirname(target), { recursive: true });
+        if (existed) {
+            const bak = backupPath(target);
+            copyFileSync(target, bak);
+            out(`backed up: ${bak}`);
+        }
+        writeFileSync(target, plan.text, { mode: 0o600 });
+        out(`wrote ${target}.`);
+        out(`verify it: dexterm mcp doctor`);
+        return 0;
+    }
+    catch (e) {
+        errOut(`dexterm mcp install: could not write ${target}: ${e.message}`);
+        return 1;
+    }
+}
+function indent(s) { return s.split('\n').map((l) => '  ' + l).join('\n'); }
+async function doctor(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    // Prefer the command install writes (`dexterm mcp`); fall back to this repo's node bin when dexterm is
+    // not on PATH (e.g. a dev checkout). Either way this is a real stdio child, not an in-process shortcut.
+    const useNode = has(rest, '--node');
+    const cmd = useNode ? defaultCommand(io.env, true) : { command: 'dexterm', args: ['mcp'] };
+    out(`dexterm mcp doctor — spawning: ${cmd.command} ${cmd.args.join(' ')}`);
+    const result = await probe(cmd, io.env).catch((e) => ({ error: e.message }));
+    if ('error' in result && !useNode && /ENOENT|not found|spawn/i.test(result.error)) {
+        // dexterm not on PATH: retry with the bundled node bin so doctor still verifies the server.
+        out(`(dexterm not on PATH; retrying with this checkout's server)`);
+        const fallback = defaultCommand(io.env, true);
+        out(`dexterm mcp doctor — spawning: ${fallback.command} ${fallback.args.join(' ')}`);
+        const r2 = await probe(fallback, io.env).catch((e) => ({ error: e.message }));
+        return report(r2, out, errOut);
+    }
+    return report(result, out, errOut);
+}
+function report(r, out, errOut) {
+    if ('error' in r) {
+        errOut(`✗ could not reach the MCP server: ${r.error}`);
+        return 1;
+    }
+    const info = r.serverInfo;
+    out(`✓ connected to ${info?.name ?? 'dexterm'} ${info?.version ?? ''} over stdio (MCP initialize ok)`);
+    out(`tools (${r.tools.length}): ${r.tools.join(', ')}`);
+    out(`prompts/skills (${r.prompts.length}): ${r.prompts.join(', ') || '(none)'}`);
+    out(`resources: ${r.resources}`);
+    out('the connection works; add it to your agent with `dexterm mcp install <client>`.');
+    return 0;
+}
+function probe(cmd, env) {
+    return new Promise((res, rej) => {
+        const child = spawn(cmd.command, cmd.args, { stdio: ['pipe', 'pipe', 'pipe'], env: { ...env, DEXTERM_OFFLINE: '1', NO_COLOR: '1' } });
+        const timer = setTimeout(() => { try {
+            child.kill();
+        }
+        catch { /* ignore */ } rej(new Error('timed out waiting for the server (10s)')); }, 10_000);
+        let stderr = '';
+        child.on('error', (e) => { clearTimeout(timer); rej(e); });
+        child.stderr.on('data', (d) => { stderr += String(d); });
+        const rl = readline.createInterface({ input: child.stdout });
+        const pending = new Map();
+        let seq = 0;
+        const send = (method, params) => {
+            const id = ++seq;
+            const msg = { jsonrpc: '2.0', id, method, ...(params ? { params } : {}) };
+            return new Promise((r) => { pending.set(id, r); child.stdin.write(JSON.stringify(msg) + '\n'); });
+        };
+        rl.on('line', (line) => {
+            if (!line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (typeof msg.id === 'number' && pending.has(msg.id)) {
+                const r = pending.get(msg.id);
+                pending.delete(msg.id);
+                r(msg.result ?? {});
+            }
+        });
+        (async () => {
+            try {
+                const init = await send('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'dexterm-doctor', version: '1' } });
+                const toolsRes = await send('tools/list');
+                const promptsRes = await send('prompts/list');
+                const resRes = await send('resources/list');
+                clearTimeout(timer);
+                try {
+                    child.stdin.end();
+                }
+                catch { /* ignore */ }
+                try {
+                    child.kill();
+                }
+                catch { /* ignore */ }
+                const tools = Array.isArray(toolsRes.tools) ? toolsRes.tools.map((t) => String(t.name)) : [];
+                const prompts = Array.isArray(promptsRes.prompts) ? promptsRes.prompts.map((p) => String(p.name)) : [];
+                const resources = Array.isArray(resRes.resources) ? resRes.resources.length : 0;
+                res({ serverInfo: init.serverInfo ?? {}, tools, prompts, resources });
+            }
+            catch (e) {
+                clearTimeout(timer);
+                rej(new Error(`${e.message}${stderr ? ` · server stderr: ${stderr.slice(0, 200)}` : ''}`));
+            }
+        })();
+    });
+}
+const USAGE = `dexterm mcp [<command>]
+  (no command)              run the read-only MCP server on stdio (claude mcp add dexterm -- dexterm mcp)
+  install <client>          write/print the MCP config for a client and verify what changes
+                            clients: ${CLIENTS.map((c) => c.id).join(', ')}
+                            --config FILE  write to a specific file (instead of the client's default)
+                            --print        only print the snippet, never write
+                            --node         emit a "node <path> mcp" command (when dexterm is not on PATH)
+                            --yes          write without the confirmation prompt
+  doctor                    spawn the server, do the MCP handshake, and list the tools/prompts/resources`;
+/** `dexterm mcp …`. With no subcommand (or an arg the server consumes, e.g. --replay) it runs the server. */
+export async function runMcp(rest, io) {
+    const sub = rest[0];
+    if (sub === 'install')
+        return install(rest.slice(1), io);
+    if (sub === 'doctor')
+        return doctor(rest.slice(1), io);
+    if (sub === 'help' || sub === '--help' || sub === '-h') {
+        io.stdout.write(USAGE + '\n');
+        return 0;
+    }
+    // Anything else (no args, or server flags like --replay) → the stdio server, unchanged.
+    const { runStdioServer } = await import('../../mcp/src/index.js');
+    await runStdioServer({ argv: rest });
+    return 0;
+}

package/dist/packages/cli/src/narrative-cmd.js

@@ -0,0 +1,76 @@
+// `dexterm narrative [--window 1h|24h] [--summary] [--db PATH]` (task-1356, AI-SUITE-DESIGN §7).
+// Computes the narrative board from the history recorder's snapshots and prints it (or the deterministic
+// 90-second morning summary with --summary). No network, no model. Read-only on the DB.
+import { DatabaseSync } from 'node:sqlite';
+import { defaultDbPath } from '../../data/src/index.js';
+import { computeBoard, recentNarrativeRows, loadDefaultLexicon, renderBoardText, summaryText } from '../../packs/src/index.js';
+export const NARRATIVE_HELP = `dexterm narrative: the narrative board over recorded history (task-1356). No network, no model.
+
+  dexterm narrative [--window 1h|24h] [--summary] [--db PATH]
+
+  --window   1h (default) or 24h: which window the "what is working" score uses.
+  --summary  print the deterministic 90-second spoken summary instead of the table (keyless, no model).
+  --db       defaults to DEXTERM_DB_PATH, else ~/.local/share/dexterm/dexterm.db.
+
+  Narratives are clustered from token names against a versioned lexicon (owner: maintainers); X/Telegram-only
+  narratives are missed and the honest unclassified share is shown. The board needs the app to have been
+  running with the recorder on (switch off with --no-recorder / DEXTERM_RECORDER=0).`;
+function parse(argv) {
+    const opts = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const k = a.slice(2);
+        const v = argv[i + 1];
+        if (v !== undefined && !v.startsWith('--') && k !== 'summary') {
+            opts[k] = v;
+            i++;
+        }
+        else
+            opts[k] = true;
+    }
+    return opts;
+}
+export function narrativeCommand(argv, io) {
+    const opts = parse(argv);
+    if (opts.help || opts.h) {
+        io.stdout.write(NARRATIVE_HELP + '\n');
+        return 0;
+    }
+    const path = typeof opts.db === 'string' ? opts.db : (io.env.DEXTERM_DB_PATH || defaultDbPath(io.env));
+    if (path === ':memory:') {
+        io.stderr.write('dexterm narrative: an in-memory DB has no history\n');
+        return 2;
+    }
+    const window = opts.window === '24h' ? '24h' : '1h';
+    let db = null;
+    try {
+        db = new DatabaseSync(path, { readOnly: true });
+        const hasTable = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'token_snapshots'").get();
+        if (!hasTable) {
+            io.stderr.write(`dexterm narrative: no recorded history in ${path} (run the app with the recorder on first)\n`);
+            return 2;
+        }
+        const rows = recentNarrativeRows(db, {});
+        const board = computeBoard(rows, loadDefaultLexicon(), { window });
+        if (opts.summary) {
+            const s = summaryText(board);
+            io.stdout.write(`${s.text}\n\n[${s.words} words ≈ ${s.approx_sec}s at 150 wpm; deterministic template, no model]\n`);
+        }
+        else {
+            io.stdout.write(renderBoardText(board));
+        }
+        return 0;
+    }
+    catch (e) {
+        io.stderr.write(`dexterm narrative: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}