@octanejs/cli 0.0.0

package/src/kernel/errors.js

@@ -0,0 +1,42 @@
+/**
+ * Exit codes are part of the CLI's contract: CI and agents branch on them, so
+ * they are fixed here rather than invented per command.
+ *
+ * - `OK`         nothing to report
+ * - `FAILURE`    the command ran and failed
+ * - `USAGE`      the invocation was wrong (unknown flag, missing input)
+ * - `DIAGNOSTIC` the command ran fine and reported problems (doctor findings)
+ */
+export const EXIT = {
+	OK: 0,
+	FAILURE: 1,
+	USAGE: 2,
+	DIAGNOSTIC: 3,
+};
+
+/**
+ * An error with a presentation. Anything thrown as a `CliError` is rendered as
+ * a message the caller can act on; anything else is an internal bug and is
+ * reported with its stack.
+ */
+export class CliError extends Error {
+	/**
+	 * @param {string} message
+	 * @param {{ exitCode?: number, hint?: string }} [options]
+	 */
+	constructor(message, options = {}) {
+		super(message);
+		this.name = 'CliError';
+		this.exitCode = options.exitCode ?? EXIT.FAILURE;
+		this.hint = options.hint;
+	}
+}
+
+/**
+ * @param {string} message
+ * @param {string} [hint]
+ * @returns {CliError}
+ */
+export function usageError(message, hint) {
+	return new CliError(message, { exitCode: EXIT.USAGE, hint });
+}

package/src/kernel/exec.js

@@ -0,0 +1,62 @@
+import { execFile } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @typedef {Object} ExecResult
+ * @property {number} code
+ * @property {string} stdout
+ * @property {string} stderr
+ */
+
+/**
+ * @typedef {Object} Exec
+ * @property {(bin: string) => string | null} which
+ * @property {(file: string, args: string[], options?: { cwd?: string }) => Promise<ExecResult>} run
+ */
+
+/**
+ * Process access, isolated behind one small interface. This is the only such
+ * seam in the kernel: it exists so that commands which shell out to another
+ * tool (`claude mcp add`, a package manager install) stay testable without
+ * spawning anything. Filesystem work deliberately does *not* go through an
+ * adapter, because fixture directories on disk test it more honestly than a
+ * mock would.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Exec}
+ */
+export function createExec(env = process.env) {
+	const extensions =
+		process.platform === 'win32' ? (env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+
+	return {
+		which(bin) {
+			for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+				if (!dir) continue;
+				for (const ext of extensions) {
+					const candidate = path.join(dir, bin + ext);
+					try {
+						accessSync(candidate, constants.X_OK);
+						return candidate;
+					} catch {
+						// Not here; keep walking PATH.
+					}
+				}
+			}
+			return null;
+		},
+
+		run(file, args, options = {}) {
+			return new Promise((resolve) => {
+				execFile(file, args, { cwd: options.cwd, env }, (error, stdout, stderr) => {
+					resolve({
+						code: error ? (typeof error.code === 'number' ? error.code : 1) : 0,
+						stdout: String(stdout),
+						stderr: String(stderr),
+					});
+				});
+			});
+		},
+	};
+}

package/src/kernel/help.js

@@ -0,0 +1,97 @@
+import { GLOBAL_FLAGS } from './args.js';
+
+/**
+ * @param {string} name
+ * @param {import('./args.js').FlagSpec} spec
+ * @returns {string}
+ */
+function flagLabel(name, spec) {
+	const short = spec.short ? `-${spec.short}, ` : '    ';
+	const value = spec.type === 'boolean' ? '' : ` ${spec.placeholder ?? '<value>'}`;
+	return `${short}--${name}${value}`;
+}
+
+/**
+ * @param {[string, string][]} rows
+ * @param {(text: string) => string} accent
+ * @returns {string[]}
+ */
+function table(rows, accent) {
+	const width = rows.reduce((max, [label]) => Math.max(max, label.length), 0);
+	return rows.map(([label, description]) => `  ${accent(label.padEnd(width))}  ${description}`);
+}
+
+/**
+ * Render help entirely from the command spec, so usage text cannot drift from
+ * what the parser actually accepts.
+ *
+ * @param {{
+ *   path: string[],
+ *   module: import('./command.js').CommandModule | null,
+ *   entries: import('./command.js').CommandEntry[],
+ *   colors: { bold: (s: string) => string, dim: (s: string) => string, cyan: (s: string) => string },
+ * }} input
+ * @returns {string}
+ */
+export function renderHelp({ path, module, entries, colors }) {
+	const invocation = ['octane', ...path].join(' ');
+	const subcommands = module?.subcommands ?? (path.length === 0 ? entries : []);
+	const positionals = module?.positionals ?? [];
+
+	/** @type {string[]} */
+	const lines = [];
+
+	const argsUsage = positionals
+		.map((p) => (p.required ? `<${p.name}>` : `[${p.name}]`) + (p.variadic ? '...' : ''))
+		.join(' ');
+
+	lines.push(colors.bold('Usage'));
+	lines.push(
+		`  ${invocation}${subcommands.length > 0 ? ' <command>' : ''}${argsUsage ? ` ${argsUsage}` : ''} [options]`,
+	);
+
+	if (module?.description) {
+		lines.push('', module.description);
+	}
+
+	if (subcommands.length > 0) {
+		lines.push('', colors.bold('Commands'));
+		lines.push(
+			...table(
+				subcommands.map((entry) => [entry.name, entry.summary]),
+				colors.cyan,
+			),
+		);
+	}
+
+	if (positionals.length > 0) {
+		lines.push('', colors.bold('Arguments'));
+		lines.push(
+			...table(
+				positionals.map((p) => [p.name, p.description]),
+				colors.cyan,
+			),
+		);
+	}
+
+	const own = Object.entries(module?.flags ?? {});
+	if (own.length > 0) {
+		lines.push('', colors.bold('Options'));
+		lines.push(
+			...table(
+				own.map(([name, spec]) => [flagLabel(name, spec), spec.description]),
+				colors.cyan,
+			),
+		);
+	}
+
+	lines.push('', colors.bold('Global options'));
+	lines.push(
+		...table(
+			Object.entries(GLOBAL_FLAGS).map(([name, spec]) => [flagLabel(name, spec), spec.description]),
+			colors.dim,
+		),
+	);
+
+	return lines.join('\n');
+}

package/src/kernel/install.js

@@ -0,0 +1,43 @@
+import { CliError } from './errors.js';
+
+/** How each package manager spells "add a dependency". */
+const MANAGERS = {
+	pnpm: { add: ['add'], dev: '-D' },
+	npm: { add: ['install'], dev: '--save-dev' },
+	yarn: { add: ['add'], dev: '-D' },
+	bun: { add: ['add'], dev: '-d' },
+};
+
+/**
+ * @param {import('./project.js').Project} project
+ * @param {string[]} names
+ * @param {boolean} dev
+ * @returns {{ manager: string, args: string[] }}
+ */
+export function installCommand(project, names, dev = false) {
+	const manager = project.packageManager ?? 'npm';
+	const recipe = MANAGERS[/** @type {keyof typeof MANAGERS} */ (manager)] ?? MANAGERS.npm;
+	return { manager, args: [...recipe.add, ...(dev ? [recipe.dev] : []), ...names] };
+}
+
+/**
+ * Install through the project's own package manager, which owns version
+ * resolution. The CLI never invents a version range.
+ *
+ * @param {import('./context.js').Ctx} ctx
+ * @param {import('./project.js').Project} project
+ * @param {string[]} names
+ * @param {{ dev?: boolean }} [options]
+ * @returns {Promise<string>} the command that ran
+ */
+export async function installPackages(ctx, project, names, { dev = false } = {}) {
+	const { manager, args } = installCommand(project, names, dev);
+	const result = await ctx.exec.run(manager, args, { cwd: project.root });
+
+	if (result.code !== 0) {
+		throw new CliError(`\`${manager} ${args.join(' ')}\` failed.`, {
+			hint: (result.stderr || result.stdout).trim() || 'Install the packages by hand.',
+		});
+	}
+	return `${manager} ${args.join(' ')}`;
+}

package/src/kernel/jsonc.js

@@ -0,0 +1,91 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * Parse JSON with comments and trailing commas, the dialect `tsconfig.json` and
+ * every editor MCP config are actually written in. Comments and commas are
+ * handled in one pass so that a `,` or `//` inside a string literal is never
+ * mistaken for syntax.
+ *
+ * @param {string} text
+ * @returns {unknown}
+ */
+export function parseJsonc(text) {
+	let out = '';
+	let lastMeaningful = -1;
+	let i = 0;
+
+	const push = (/** @type {string} */ ch) => {
+		if ((ch === '}' || ch === ']') && lastMeaningful >= 0 && out[lastMeaningful] === ',') {
+			out = out.slice(0, lastMeaningful) + out.slice(lastMeaningful + 1);
+			lastMeaningful = -1;
+			for (let j = out.length - 1; j >= 0; j--) {
+				if (!/\s/.test(out[j])) {
+					lastMeaningful = j;
+					break;
+				}
+			}
+		}
+		out += ch;
+		if (!/\s/.test(ch)) lastMeaningful = out.length - 1;
+	};
+
+	while (i < text.length) {
+		const ch = text[i];
+
+		if (ch === '"') {
+			// Emit the whole literal verbatim. Nothing inside it is syntax, so a
+			// `//`, a `]`, or a `,` in a string value must not reach `push`.
+			const start = i++;
+			while (i < text.length) {
+				if (text[i] === '\\') {
+					i += 2;
+					continue;
+				}
+				if (text[i] === '"') {
+					i++;
+					break;
+				}
+				i++;
+			}
+			out += text.slice(start, i);
+			lastMeaningful = out.length - 1;
+			continue;
+		}
+
+		if (ch === '/' && text[i + 1] === '/') {
+			while (i < text.length && text[i] !== '\n') i++;
+			continue;
+		}
+
+		if (ch === '/' && text[i + 1] === '*') {
+			i += 2;
+			while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+			i += 2;
+			continue;
+		}
+
+		push(ch);
+		i++;
+	}
+
+	return JSON.parse(out);
+}
+
+/**
+ * @param {string} file
+ * @returns {any | null} `null` when the file is missing, empty, or unparseable
+ */
+export function readJsonc(file) {
+	let text;
+	try {
+		text = readFileSync(file, 'utf8');
+	} catch {
+		return null;
+	}
+	if (text.trim() === '') return null;
+	try {
+		return parseJsonc(text);
+	} catch {
+		return null;
+	}
+}

package/src/kernel/main.js

@@ -0,0 +1,166 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from './args.js';
+import { renderBanner } from './banner.js';
+import { resolveCommand } from './command.js';
+import { createContext } from './context.js';
+import { CliError, EXIT, usageError } from './errors.js';
+import { renderHelp } from './help.js';
+import { COMMANDS } from './registry.js';
+
+export const VERSION = JSON.parse(
+	readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+).version;
+
+/**
+ * @typedef {Object} RunOptions
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {NodeJS.WritableStream} [stdout]
+ * @property {NodeJS.WritableStream} [stderr]
+ * @property {boolean} [tty]
+ * @property {import('./exec.js').Exec} [exec]
+ */
+
+/**
+ * Offer the commands available at `path` and dispatch the chosen one.
+ *
+ * Recursive by construction: choosing a group re-enters `dispatch`, which finds
+ * a module with subcommands and no `run` and calls back here. So `octane` then
+ * `mcp` walks into add/status/remove without the caller knowing how deep the
+ * tree goes.
+ *
+ * @param {import('./context.js').Ctx} ctx
+ * @param {RunOptions} options the original invocation options, so the chosen
+ *   command runs against the same streams and injected process access
+ * @param {string[]} path commands already chosen
+ * @param {import('./command.js').CommandEntry[]} entries what is available here
+ * @returns {Promise<number>}
+ */
+async function runMenu(ctx, options, path, entries) {
+	const name = await ctx.ui.select({
+		message: path.length === 0 ? 'What would you like to do?' : `octane ${path.join(' ')}`,
+		flag: '<command>',
+		options: entries.map((entry) => ({
+			value: entry.name,
+			label: entry.name,
+			hint: entry.summary,
+		})),
+	});
+	return dispatch([...path, name], options);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {RunOptions} options
+ * @returns {Promise<number>}
+ */
+async function dispatch(argv, options) {
+	const stdout = options.stdout ?? process.stdout;
+	const { path, module, argv: rest } = await resolveCommand(COMMANDS, argv);
+
+	if (!module && rest.length > 0 && !rest[0].startsWith('-')) {
+		throw usageError(`Unknown command: ${rest[0]}`, 'Run `octane --help` to list commands.');
+	}
+
+	const parsed = parseArgs(rest, module ?? {});
+	const ctx = createContext({
+		flags: parsed.flags,
+		version: VERSION,
+		env: options.env,
+		stdout,
+		tty: options.tty,
+		exec: options.exec,
+	});
+
+	// `--version` is documented as a global flag, so it answers everywhere rather
+	// than only at the root.
+	if (parsed.flags.version) {
+		if (ctx.json) stdout.write(`${JSON.stringify({ version: VERSION }, null, 2)}\n`);
+		else ctx.ui.log(VERSION);
+		return EXIT.OK;
+	}
+
+	if (!module?.run || parsed.flags.help) {
+		if (ctx.json) {
+			const listed = module?.subcommands ?? COMMANDS;
+			stdout.write(
+				`${JSON.stringify(
+					{
+						command: path.join(' ') || null,
+						commands: listed.map((e) => ({ name: e.name, summary: e.summary })),
+					},
+					null,
+					2,
+				)}\n`,
+			);
+			return EXIT.OK;
+		}
+		// Root invocation only: the wordmark heads `octane` and `octane --help`,
+		// not every subcommand's help.
+		if (path.length === 0) renderBanner(ctx);
+
+		// Nothing runnable was named, so offer what is available here instead of
+		// printing help at someone who has not asked for it. `--help` is an
+		// explicit request for the text, so it still wins.
+		const choices = module?.subcommands ?? (module ? [] : COMMANDS);
+		if (!parsed.flags.help && ctx.ui.canPrompt && choices.length > 0) {
+			return runMenu(ctx, options, path, choices);
+		}
+		ctx.ui.log(renderHelp({ path, module, entries: COMMANDS, colors: ctx.ui.colors }));
+		return EXIT.OK;
+	}
+
+	// Commands that write into a project need one to exist. Without this they
+	// fail deep inside an fs call with a raw ENOENT stack.
+	if (module.requiresProject && ctx.project().manifestPath === null) {
+		throw new CliError(`No package.json found in ${ctx.cwd} or any parent directory.`, {
+			hint: 'Run this inside a project, or create one first with `npm init -y`.',
+		});
+	}
+
+	const result = await module.run(ctx, {
+		flags: parsed.flags,
+		positionals: parsed.positionals,
+		rest: parsed.rest,
+	});
+
+	if (typeof result === 'number') return result;
+	if (result && typeof result === 'object') {
+		if (ctx.json && result.json !== undefined) {
+			stdout.write(`${JSON.stringify(result.json, null, 2)}\n`);
+		}
+		return result.exitCode ?? EXIT.OK;
+	}
+	return EXIT.OK;
+}
+
+/**
+ * Entry point. Never throws: every failure is rendered and turned into an exit
+ * code, in the caller's chosen output format.
+ *
+ * @param {string[]} argv
+ * @param {RunOptions} [options]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, options = {}) {
+	const stderr = options.stderr ?? process.stderr;
+	// Read from raw argv: a failure can happen before the flags are parsed, and
+	// the parser accepts `--json=true` as well as the bare form.
+	const json = argv.some((token) => token === '--json' || token.startsWith('--json='));
+
+	try {
+		return await dispatch(argv, options);
+	} catch (error) {
+		const known = error instanceof CliError;
+		const message = error instanceof Error ? error.message : String(error);
+
+		if (json) {
+			stderr.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
+		} else {
+			stderr.write(`\n${message}\n`);
+			if (known && error.hint) stderr.write(`${error.hint}\n`);
+			if (!known && error instanceof Error && error.stack) stderr.write(`\n${error.stack}\n`);
+		}
+
+		return known ? error.exitCode : EXIT.FAILURE;
+	}
+}