@octanejs/cli 0.0.0

package/src/commands/mcp/clients.js

@@ -0,0 +1,281 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseJsonc } from '../../kernel/jsonc.js';
+
+/**
+ * @typedef {'user' | 'project'} Scope
+ */
+
+/**
+ * @typedef {Object} Paths
+ * @property {string} projectRoot
+ * @property {string} home resolved from the environment, so tests never touch a
+ *   real `~/.claude.json`
+ */
+
+/**
+ * @typedef {Object} Client
+ * @property {string} id
+ * @property {string} label
+ * @property {string | null} cli binary that owns this client's config, if any
+ * @property {Scope[]} scopes
+ * @property {(scope: Scope, paths: Paths) => string} configPath
+ * @property {(name: string, entry: import('./server.js').ServerEntry, scope: Scope) => string[] | null} cliArgs
+ * @property {(name: string, scope: Scope) => string[] | null} cliRemoveArgs
+ * @property {(text: string, name: string) => unknown | null} readServer current entry, or null
+ * @property {(text: string, name: string, entry: import('./server.js').ServerEntry) => string} write
+ * @property {(text: string, name: string) => string} remove
+ */
+
+/**
+ * Read a config file that may be missing, empty, or corrupt.
+ *
+ * All three happen in the wild: `~/.cursor/mcp.json` in particular is commonly
+ * present but not valid JSON. Treating those as an empty document is what keeps
+ * the merge from either crashing or silently discarding a real config.
+ *
+ * @param {string} file
+ * @returns {string}
+ */
+export function readConfigText(file) {
+	if (!existsSync(file)) return '';
+	try {
+		return readFileSync(file, 'utf8');
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * @param {string} text
+ * @returns {Record<string, any>}
+ */
+function parseObject(text) {
+	if (text.trim() === '') return {};
+	try {
+		const parsed = parseJsonc(text);
+		return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+			? /** @type {Record<string, any>} */ (parsed)
+			: {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Most clients store MCP servers in a JSON object under a single key. The only
+ * differences are the file path, the key name, and whether servers can be
+ * nested per project.
+ *
+ * @param {{
+ *   id: string,
+ *   label: string,
+ *   cli?: string | null,
+ *   scopes?: Scope[],
+ *   key?: string,
+ *   entry?: (entry: import('./server.js').ServerEntry) => object,
+ *   configPath: (scope: Scope, paths: Paths) => string,
+ *   cliArgs?: Client['cliArgs'],
+ *   cliRemoveArgs?: Client['cliRemoveArgs'],
+ * }} spec
+ * @returns {Client}
+ */
+function jsonClient(spec) {
+	const key = spec.key ?? 'mcpServers';
+	const shape = spec.entry ?? ((entry) => entry);
+
+	return {
+		id: spec.id,
+		label: spec.label,
+		cli: spec.cli ?? null,
+		scopes: spec.scopes ?? ['user', 'project'],
+		configPath: spec.configPath,
+		cliArgs: spec.cliArgs ?? (() => null),
+		cliRemoveArgs: spec.cliRemoveArgs ?? (() => null),
+
+		readServer(text, name) {
+			return parseObject(text)[key]?.[name] ?? null;
+		},
+
+		write(text, name, entry) {
+			const config = parseObject(text);
+			config[key] = { ...config[key], [name]: shape(entry) };
+			return `${JSON.stringify(config, null, 2)}\n`;
+		},
+
+		remove(text, name) {
+			const config = parseObject(text);
+			if (config[key]) delete config[key][name];
+			return `${JSON.stringify(config, null, 2)}\n`;
+		},
+	};
+}
+
+/**
+ * Replace or append a TOML table, without a TOML parser.
+ *
+ * The section boundary is unambiguous (a line starting with `[`), so a splice
+ * preserves every unrelated key, comment, and ordering choice in the file. A
+ * parse-and-reserialize round trip would not.
+ *
+ * @param {string} text
+ * @param {string} header
+ * @param {string[] | null} body null removes the section
+ * @returns {string}
+ */
+export function spliceTomlSection(text, header, body) {
+	const lines = text.split('\n');
+	const start = lines.findIndex((line) => line.trim() === header);
+
+	if (start === -1) {
+		if (!body) return text;
+		const prefix = text.trim() === '' ? '' : `${text.replace(/\n+$/, '')}\n\n`;
+		return `${prefix}${header}\n${body.join('\n')}\n`;
+	}
+
+	const end = sectionEnd(lines, start);
+	const before = lines.slice(0, start);
+	const after = lines.slice(end);
+
+	// Blank lines are trimmed only at the splice boundary. A global whitespace
+	// pass would also reach inside a multi-line TOML string elsewhere in the
+	// file, which is exactly the unrelated user data this splice exists to
+	// leave alone.
+	while (before.length > 0 && before[before.length - 1].trim() === '') before.pop();
+
+	const separator = before.length > 0 ? [''] : [];
+	const replacement = body ? [...separator, header, ...body] : [];
+	const tail = after.length > 0 ? ['', ...after] : [''];
+
+	return [...before, ...replacement, ...tail].join('\n');
+}
+
+/**
+ * Index of the first line after the section starting at `start`.
+ *
+ * @param {string[]} lines
+ * @param {number} start
+ * @returns {number}
+ */
+function sectionEnd(lines, start) {
+	let end = start + 1;
+	while (end < lines.length && !/^\s*\[/.test(lines[end])) end++;
+	return end;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+const toml = (value) => JSON.stringify(String(value));
+
+/** @type {Client} */
+const codex = {
+	id: 'codex',
+	label: 'Codex',
+	cli: 'codex',
+	// Codex keeps MCP servers in one user-level config; it has no project scope.
+	scopes: ['user'],
+	configPath: (scope, paths) => path.join(paths.home, '.codex', 'config.toml'),
+
+	cliArgs: (name, entry) => [
+		'mcp',
+		'add',
+		...Object.entries(entry.env ?? {}).flatMap(([key, value]) => ['--env', `${key}=${value}`]),
+		name,
+		'--',
+		entry.command,
+		...entry.args,
+	],
+	cliRemoveArgs: (name) => ['mcp', 'remove', name],
+
+	readServer(text, name) {
+		const lines = text.split('\n');
+		const start = lines.findIndex((line) => line.trim() === `[mcp_servers.${name}]`);
+		if (start === -1) return null;
+		// Bounded to this section: an unbounded search would report a later
+		// server's command as if it were ours.
+		const body = lines.slice(start + 1, sectionEnd(lines, start)).join('\n');
+		return { command: /^\s*command\s*=\s*"([^"]*)"/m.exec(body)?.[1] ?? null };
+	},
+
+	write(text, name, entry) {
+		const body = [
+			`command = ${toml(entry.command)}`,
+			`args = [${entry.args.map(toml).join(', ')}]`,
+		];
+		const env = Object.entries(entry.env ?? {});
+		if (env.length > 0) {
+			body.push(`env = { ${env.map(([key, value]) => `${key} = ${toml(value)}`).join(', ')} }`);
+		}
+		return spliceTomlSection(text, `[mcp_servers.${name}]`, body);
+	},
+
+	remove: (text, name) => spliceTomlSection(text, `[mcp_servers.${name}]`, null),
+};
+
+/**
+ * Every client the CLI knows how to configure.
+ *
+ * Adding one is a single entry here: the add/status/remove commands are generic
+ * over this table.
+ *
+ * @type {Client[]}
+ */
+export const CLIENTS = [
+	jsonClient({
+		id: 'claude',
+		label: 'Claude Code',
+		cli: 'claude',
+		// `project` is the committed .mcp.json the whole team shares; `user`
+		// is the personal config. This mirrors `claude mcp add --scope`.
+		configPath: (scope, paths) =>
+			scope === 'project'
+				? path.join(paths.projectRoot, '.mcp.json')
+				: path.join(paths.home, '.claude.json'),
+		// The name goes before `-e`: Claude declares `--env <env...>` as variadic,
+		// so an `-e` ahead of the positional swallows the server name and the CLI
+		// rejects it as a malformed environment variable.
+		cliArgs: (name, entry, scope) => [
+			'mcp',
+			'add',
+			'--scope',
+			scope,
+			name,
+			...Object.entries(entry.env ?? {}).flatMap(([key, value]) => ['-e', `${key}=${value}`]),
+			'--',
+			entry.command,
+			...entry.args,
+		],
+		// Scope is forwarded: `claude mcp remove` without it removes from
+		// whichever scope the entry happens to exist in, which need not be the
+		// one `mcp remove --scope` just reported.
+		cliRemoveArgs: (name, scope) => ['mcp', 'remove', '--scope', scope, name],
+	}),
+	codex,
+	jsonClient({
+		id: 'cursor',
+		label: 'Cursor',
+		configPath: (scope, paths) =>
+			scope === 'project'
+				? path.join(paths.projectRoot, '.cursor', 'mcp.json')
+				: path.join(paths.home, '.cursor', 'mcp.json'),
+	}),
+	jsonClient({
+		id: 'vscode',
+		label: 'VS Code',
+		// VS Code names the map `servers`, not `mcpServers`, and its schema
+		// discriminates transports on `type`; without it the entry is rejected
+		// and the server silently never registers.
+		key: 'servers',
+		entry: (entry) => ({ type: 'stdio', ...entry }),
+		scopes: ['project'],
+		configPath: (scope, paths) => path.join(paths.projectRoot, '.vscode', 'mcp.json'),
+	}),
+];
+
+/**
+ * @param {string} id
+ * @returns {Client | undefined}
+ */
+export const findClient = (id) => CLIENTS.find((client) => client.id === id);

package/src/commands/mcp/detect.js

@@ -0,0 +1,58 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { CLIENTS, readConfigText } from './clients.js';
+import { SERVER_NAME } from './server.js';
+
+/**
+ * Honour an overridden HOME so a test run can never read or write the real
+ * `~/.claude.json`.
+ *
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @returns {string}
+ */
+export const resolveHome = (ctx) => ctx.env.HOME ?? ctx.env.USERPROFILE ?? homedir();
+
+/**
+ * @typedef {Object} ClientState
+ * @property {import('./clients.js').Client} client
+ * @property {import('./clients.js').Scope} scope
+ * @property {string} configPath
+ * @property {boolean} configExists
+ * @property {boolean} cliAvailable
+ * @property {unknown | null} server the octane entry already registered, if any
+ */
+
+/**
+ * Inspect every known client for a given scope.
+ *
+ * A client counts as present when either its config file exists or its CLI is
+ * on PATH, so a fresh install of a tool that has not written its config yet is
+ * still offered.
+ *
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {import('./clients.js').Scope} scope
+ * @param {string} projectRoot
+ * @returns {ClientState[]}
+ */
+export function detectClients(ctx, scope, projectRoot) {
+	const paths = { projectRoot, home: resolveHome(ctx) };
+
+	return CLIENTS.filter((client) => client.scopes.includes(scope)).map((client) => {
+		const configPath = client.configPath(scope, paths);
+		const configExists = existsSync(configPath);
+		return {
+			client,
+			scope,
+			configPath,
+			configExists,
+			cliAvailable: Boolean(client.cli && ctx.exec.which(client.cli)),
+			server: configExists ? client.readServer(readConfigText(configPath), SERVER_NAME) : null,
+		};
+	});
+}
+
+/**
+ * @param {ClientState} state
+ * @returns {boolean}
+ */
+export const isPresent = (state) => state.configExists || state.cliAvailable;

package/src/commands/mcp/index.js

@@ -0,0 +1,23 @@
+import { defineCommand } from '../../kernel/command.js';
+import { SERVER_PACKAGE } from './server.js';
+
+export default defineCommand({
+	description: `Manage the Octane MCP server (${SERVER_PACKAGE}) across coding agents.`,
+	subcommands: [
+		{
+			name: 'add',
+			summary: 'Register the Octane MCP server with an agent.',
+			load: () => import('./add.js'),
+		},
+		{
+			name: 'status',
+			summary: 'Show where the Octane MCP server is registered.',
+			load: () => import('./status.js'),
+		},
+		{
+			name: 'remove',
+			summary: 'Remove the Octane MCP server from an agent.',
+			load: () => import('./remove.js'),
+		},
+	],
+});

package/src/commands/mcp/remove.js

@@ -0,0 +1,105 @@
+import { copyFileSync, writeFileSync } from 'node:fs';
+import { defineCommand } from '../../kernel/command.js';
+import { EXIT } from '../../kernel/errors.js';
+import { CLIENTS, readConfigText } from './clients.js';
+import { detectClients } from './detect.js';
+import { SERVER_NAME } from './server.js';
+
+export default defineCommand({
+	description: `Remove the "${SERVER_NAME}" MCP server from one or more agents.`,
+	positionals: [
+		{
+			name: 'client',
+			description: `Clients to clean up: ${CLIENTS.map((c) => c.id).join(', ')}. Defaults to every configured client.`,
+			variadic: true,
+		},
+	],
+	flags: {
+		scope: {
+			type: 'string',
+			choices: ['user', 'project'],
+			default: 'user',
+			placeholder: '<scope>',
+			description: 'Which installation to remove.',
+		},
+	},
+
+	async run(ctx, input) {
+		const scope = /** @type {import('./clients.js').Scope} */ (input.flags.scope);
+		const project = ctx.project();
+
+		const configured = detectClients(ctx, scope, project.root).filter(
+			(state) =>
+				state.server !== null &&
+				(input.positionals.length === 0 || input.positionals.includes(state.client.id)),
+		);
+
+		ctx.ui.intro('octane mcp remove');
+
+		if (configured.length === 0) {
+			ctx.ui.outro(`No ${scope}-scope client has an "${SERVER_NAME}" server.`);
+			return { json: { ok: true, removed: [] } };
+		}
+
+		if (ctx.dryRun) {
+			for (const state of configured) {
+				const args = state.cliAvailable ? state.client.cliRemoveArgs(SERVER_NAME, scope) : null;
+				ctx.ui.note(`${state.client.label} (${scope})`, [
+					args
+						? `would run: ${state.client.cli} ${args.join(' ')}`
+						: `would rewrite: ${state.configPath}`,
+				]);
+			}
+			return {
+				json: { ok: true, dryRun: true, removed: configured.map((state) => state.client.id) },
+			};
+		}
+
+		const confirmed = await ctx.ui.confirm({
+			message: `Remove "${SERVER_NAME}" from ${configured.map((s) => s.client.label).join(', ')}?`,
+			flag: '--yes',
+			initial: true,
+		});
+		if (!confirmed) return { exitCode: EXIT.OK, json: { ok: true, removed: [] } };
+
+		/** @type {{ client: string, method: string, target: string, ok: boolean, message: string }[]} */
+		const removed = [];
+
+		for (const state of configured) {
+			const { client } = state;
+			const args =
+				client.cli && state.cliAvailable ? client.cliRemoveArgs(SERVER_NAME, scope) : null;
+
+			if (client.cli && args) {
+				const result = await ctx.exec.run(client.cli, args, { cwd: ctx.cwd });
+				removed.push({
+					client: client.id,
+					method: 'cli',
+					target: client.cli,
+					ok: result.code === 0,
+					message: result.code === 0 ? 'Removed' : (result.stderr || result.stdout).trim(),
+				});
+				continue;
+			}
+
+			const current = readConfigText(state.configPath);
+			copyFileSync(state.configPath, `${state.configPath}.octane-backup`);
+			writeFileSync(state.configPath, client.remove(current, SERVER_NAME));
+			removed.push({
+				client: client.id,
+				method: 'file',
+				target: state.configPath,
+				ok: true,
+				message: 'Removed',
+			});
+		}
+
+		for (const entry of removed) {
+			const mark = entry.ok ? ctx.ui.colors.green('✔') : ctx.ui.colors.red('✖');
+			ctx.ui.log(`  ${mark} ${entry.client} ${ctx.ui.colors.dim(entry.message)}`);
+		}
+
+		const ok = removed.every((entry) => entry.ok);
+		return { exitCode: ok ? EXIT.OK : EXIT.FAILURE, json: { ok, removed } };
+	},
+});

package/src/commands/mcp/server.js

@@ -0,0 +1,46 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { readJsonc } from '../../kernel/jsonc.js';
+
+export const SERVER_NAME = 'octane';
+export const SERVER_PACKAGE = '@octanejs/mcp-server';
+
+/**
+ * @typedef {Object} ServerEntry
+ * @property {string} command
+ * @property {string[]} args
+ * @property {Record<string, string>} [env]
+ */
+
+/**
+ * Walk up for an octane monorepo checkout.
+ *
+ * The MCP server registers its maintainer tools only when `OCTANE_REPO_ROOT`
+ * points at a checkout, so installing from inside one should wire that up
+ * rather than silently offering half the toolset.
+ *
+ * @param {string} from
+ * @returns {string | null}
+ */
+export function findRepoRoot(from) {
+	let dir = path.resolve(from);
+	for (;;) {
+		const manifest = path.join(dir, 'packages', 'octane', 'package.json');
+		if (existsSync(manifest) && readJsonc(manifest)?.name === 'octane') return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/**
+ * @param {{ command?: string, repoRoot?: string | null }} [options]
+ * @returns {ServerEntry}
+ */
+export function buildServerEntry({ command, repoRoot } = {}) {
+	/** @type {ServerEntry} */
+	const entry = command ? { command, args: [] } : { command: 'npx', args: ['-y', SERVER_PACKAGE] };
+
+	if (repoRoot) entry.env = { OCTANE_REPO_ROOT: repoRoot };
+	return entry;
+}

package/src/commands/mcp/status.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { defineCommand } from '../../kernel/command.js';
+import { detectClients } from './detect.js';
+import { SERVER_NAME } from './server.js';
+
+/** @type {import('./clients.js').Scope[]} */
+const SCOPES = ['user', 'project'];
+
+export default defineCommand({
+	description: `Show which agents have the "${SERVER_NAME}" MCP server registered.`,
+
+	async run(ctx) {
+		const project = ctx.project();
+
+		const rows = SCOPES.flatMap((scope) =>
+			detectClients(ctx, scope, project.root).map((state) => ({
+				client: state.client.id,
+				label: state.client.label,
+				scope,
+				configured: state.server !== null,
+				cliAvailable: state.cliAvailable,
+				configPath: state.configPath,
+				configExists: state.configExists,
+			})),
+		);
+
+		ctx.ui.intro('octane mcp status');
+		const width = rows.reduce((max, row) => Math.max(max, row.label.length), 0);
+
+		for (const row of rows) {
+			const mark = row.configured ? ctx.ui.colors.green('✔') : ctx.ui.colors.dim('○');
+			const where = row.configExists ? path.normalize(row.configPath) : 'no config file';
+			const detail = row.configured ? where : row.cliAvailable ? `installed, ${where}` : where;
+			ctx.ui.log(
+				`  ${mark} ${row.label.padEnd(width)}  ${row.scope.padEnd(7)} ${ctx.ui.colors.dim(detail)}`,
+			);
+		}
+
+		const configured = rows.filter((row) => row.configured).length;
+		ctx.ui.outro(
+			configured === 0
+				? 'Not registered anywhere yet. Run `octane mcp add`.'
+				: `Registered in ${configured} place(s).`,
+		);
+
+		return { json: { server: SERVER_NAME, clients: rows } };
+	},
+});

package/src/data/index.js

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * The binding and error-code catalogs, snapshotted from the octane repository
+ * at publish time by `scripts/generate-cli-data.mjs`. Read from disk rather
+ * than imported so the module works identically under Node, vitest, and any
+ * bundler.
+ */
+export const DATA = JSON.parse(
+	readFileSync(new URL('./octane-data.json', import.meta.url), 'utf8'),
+);
+
+/** Matches `formatProdErrorMessage` in packages/octane/src/error-message.ts. */
+export const ERROR_DOCS_URL = 'https://octanejs.dev/errors/';
+
+/**
+ * @typedef {Object} Binding
+ * @property {string} name
+ * @property {string} version
+ * @property {string} category
+ * @property {{ package: string, version: string } | null} upstream
+ * @property {string} surface
+ * @property {string[]} divergences
+ * @property {string} ssr
+ * @property {string | null} verified
+ */
+
+/** @type {Binding[]} */
+export const BINDINGS = DATA.bindings;
+
+/**
+ * Resolve what a user asked for to the binding that provides it.
+ *
+ * Accepts the binding's own name, the React package it ports, or any upstream
+ * package recorded in that binding's status.json.
+ *
+ * @param {string} name
+ * @returns {{ binding: Binding, via: 'binding' | 'react-package' } | null}
+ */
+export function resolveBinding(name) {
+	const direct = BINDINGS.find((binding) => binding.name === name);
+	if (direct) return { binding: direct, via: 'binding' };
+
+	const mapped = DATA.reactPackages[name];
+	const fromMap = mapped && BINDINGS.find((binding) => binding.name === mapped);
+	if (fromMap) return { binding: fromMap, via: 'react-package' };
+
+	const upstream = BINDINGS.find((binding) => binding.upstream?.package === name);
+	return upstream ? { binding: upstream, via: 'react-package' } : null;
+}
+
+/**
+ * @param {string} query
+ * @param {{ surface?: boolean }} [options] search the prose too. Useful for an
+ *   explicit `octane bindings <query>`, but too loose for "did you mean",
+ *   where matching a word buried in a paragraph suggests unrelated packages.
+ * @returns {Binding[]}
+ */
+export function searchBindings(query, { surface = true } = {}) {
+	const needle = query.toLowerCase();
+	if (needle === '') return [];
+
+	return BINDINGS.filter((binding) =>
+		[
+			binding.name,
+			binding.category,
+			binding.upstream?.package ?? '',
+			surface ? binding.surface : '',
+		]
+			.join(' ')
+			.toLowerCase()
+			.includes(needle),
+	);
+}