@octanejs/cli 0.0.0

package/src/kernel/project.js

@@ -0,0 +1,376 @@
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { readJsonc } from './jsonc.js';
+
+const IGNORED_DIRS = new Set([
+	'node_modules',
+	'dist',
+	'build',
+	'.git',
+	'coverage',
+	'.next',
+	'.vercel',
+]);
+const SOURCE_EXTENSIONS = new Set(['.tsrx', '.tsx', '.ts', '.jsx', '.js', '.mts', '.mjs']);
+const SOURCE_FILE_LIMIT = 5000;
+const EXTENDS_LIMIT = 10;
+
+const LOCKFILES = /** @type {const} */ ([
+	['pnpm-lock.yaml', 'pnpm'],
+	['package-lock.json', 'npm'],
+	['yarn.lock', 'yarn'],
+	['bun.lockb', 'bun'],
+	['bun.lock', 'bun'],
+]);
+
+const BUNDLER_CONFIGS = /** @type {const} */ ([
+	['vite.config', 'vite'],
+	['rspack.config', 'rspack'],
+	['rsbuild.config', 'rsbuild'],
+	['lynx.config', 'rspeedy'],
+]);
+
+const CONFIG_EXTENSIONS = ['.ts', '.mts', '.js', '.mjs', '.cts', '.cjs'];
+
+/**
+ * @param {string} base
+ * @returns {string | null}
+ */
+function firstExisting(base) {
+	for (const ext of CONFIG_EXTENSIONS) {
+		if (existsSync(base + ext)) return base + ext;
+	}
+	return null;
+}
+
+/**
+ * Nearest ancestor directory containing a `package.json`.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function findRoot(cwd) {
+	let dir = path.resolve(cwd);
+	for (;;) {
+		if (existsSync(path.join(dir, 'package.json'))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return path.resolve(cwd);
+		dir = parent;
+	}
+}
+
+/**
+ * @param {string} root
+ * @param {string} spec
+ * @param {string} fromDir
+ * @returns {string | null}
+ */
+function resolveExtends(root, spec, fromDir) {
+	if (spec.startsWith('.') || path.isAbsolute(spec)) {
+		const base = path.resolve(fromDir, spec);
+		if (existsSync(base) && !spec.endsWith('.json')) return path.join(base, 'tsconfig.json');
+		return existsSync(base) ? base : `${base}.json`;
+	}
+	const candidate = path.join(root, 'node_modules', spec);
+	if (existsSync(candidate)) {
+		return existsSync(path.join(candidate, 'tsconfig.json'))
+			? path.join(candidate, 'tsconfig.json')
+			: candidate;
+	}
+	return existsSync(`${candidate}.json`) ? `${candidate}.json` : null;
+}
+
+/**
+ * Load a tsconfig with its `extends` chain flattened. `compilerOptions` merges
+ * shallowly with the child winning, which is what TypeScript itself does and is
+ * the only part the doctor checks read.
+ *
+ * @param {string} root
+ * @param {string} [file]
+ * @returns {{ path: string, config: any, chain: string[] } | null}
+ */
+export function loadTsconfig(root, file = path.join(root, 'tsconfig.json')) {
+	if (!existsSync(file)) return null;
+
+	/** @type {string[]} */
+	const chain = [];
+	/** @type {any} */
+	let merged = {};
+	/** @type {string | null} */
+	let current = file;
+
+	while (current && chain.length < EXTENDS_LIMIT) {
+		const config = readJsonc(current);
+		if (!config) break;
+		chain.push(current);
+
+		merged = {
+			...config,
+			...merged,
+			compilerOptions: { ...(config.compilerOptions ?? {}), ...(merged.compilerOptions ?? {}) },
+		};
+
+		const parent = config.extends;
+		if (typeof parent !== 'string') break;
+		current = resolveExtends(root, parent, path.dirname(current));
+	}
+
+	return chain.length > 0 ? { path: file, config: merged, chain } : null;
+}
+
+/**
+ * Read an installed package's manifest by walking `node_modules` upwards. Done
+ * by hand rather than through `require.resolve` because most packages do not
+ * expose `./package.json` in their export map.
+ *
+ * @param {string} root
+ * @param {string} name
+ * @returns {{ version: string, dir: string, manifest: any } | null}
+ */
+export function readInstalled(root, name) {
+	let dir = path.resolve(root);
+	for (;;) {
+		const candidate = path.join(dir, 'node_modules', name);
+		const manifest = readJsonc(path.join(candidate, 'package.json'));
+		if (manifest) return { version: String(manifest.version ?? '0.0.0'), dir: candidate, manifest };
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/**
+ * Every physically distinct copy of a package reachable from the project's
+ * direct dependencies.
+ *
+ * Two copies of `octane` in one tree is the single worst failure mode in the
+ * ecosystem: hooks and context are keyed per-runtime, so a duplicate breaks
+ * them silently rather than loudly. The scan is deliberately bounded to the
+ * top level and one level of nesting, which is where real duplicates surface,
+ * instead of walking the whole tree.
+ *
+ * @param {string} root
+ * @param {string} name
+ * @returns {{ version: string, realPath: string, via: string }[]}
+ */
+export function findCopies(root, name) {
+	const modules = path.join(root, 'node_modules');
+	if (!existsSync(modules)) return [];
+
+	/** @type {Map<string, { version: string, realPath: string, via: string }>} */
+	const found = new Map();
+
+	const record = (/** @type {string} */ dir, /** @type {string} */ via) => {
+		const manifest = readJsonc(path.join(dir, 'package.json'));
+		if (!manifest) return;
+		let realPath = dir;
+		try {
+			realPath = realpathSync(dir);
+		} catch {
+			// Broken link; report the logical path.
+		}
+		if (!found.has(realPath)) {
+			found.set(realPath, { version: String(manifest.version ?? '0.0.0'), realPath, via });
+		}
+	};
+
+	record(path.join(modules, name), 'the project');
+
+	/** @type {string[]} */
+	const owners = [];
+	for (const entry of safeReaddir(modules)) {
+		if (entry.startsWith('.')) continue;
+		if (entry.startsWith('@')) {
+			for (const scoped of safeReaddir(path.join(modules, entry))) {
+				owners.push(`${entry}/${scoped}`);
+			}
+		} else {
+			owners.push(entry);
+		}
+	}
+
+	for (const owner of owners) {
+		if (owner === name) continue;
+		record(path.join(modules, owner, 'node_modules', name), owner);
+	}
+
+	return [...found.values()];
+}
+
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function safeReaddir(dir) {
+	try {
+		return readdirSync(dir);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Walk project sources, skipping build output and dependencies.
+ *
+ * @param {string} root
+ * @param {{ limit?: number }} [options]
+ * @returns {string[]}
+ */
+export function scanSourceFiles(root, { limit = SOURCE_FILE_LIMIT } = {}) {
+	/** @type {string[]} */
+	const files = [];
+	/** @type {string[]} */
+	const queue = [root];
+
+	while (queue.length > 0 && files.length < limit) {
+		const dir = queue.pop();
+		if (dir === undefined) break;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith('.') && entry.name !== '.') continue;
+			const absolute = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (!IGNORED_DIRS.has(entry.name)) queue.push(absolute);
+			} else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
+				files.push(absolute);
+				if (files.length >= limit) break;
+			}
+		}
+	}
+
+	return files;
+}
+
+/**
+ * @typedef {Object} Project
+ * @property {string} root
+ * @property {string | null} manifestPath null when no package.json exists
+ *   anywhere up the tree, which is what separates "a project" from "a directory"
+ * @property {any} manifest
+ * @property {Record<string, string>} declaredDependencies every dependency kind, merged
+ * @property {string[]} bindings installed `@octanejs/*` package names
+ * @property {'pnpm' | 'npm' | 'yarn' | 'bun' | null} packageManager
+ * @property {string | null} lockfile
+ * @property {{ path: string, config: any, chain: string[] } | null} tsconfig
+ * @property {string | null} bundlerConfigPath
+ * @property {'vite' | 'rspack' | 'rsbuild' | 'rspeedy' | null} bundler
+ * @property {string | null} octaneConfigPath
+ * @property {string[]} sourceFiles
+ * @property {string[]} tsrxFiles
+ * @property {boolean} isOctaneProject
+ */
+
+/**
+ * Detect everything the commands share about a project, in one pass. Commands
+ * read this model instead of re-globbing, so a `doctor` run touches the tree
+ * once.
+ *
+ * @param {string} cwd
+ * @returns {Project}
+ */
+export function detectProject(cwd) {
+	const root = findRoot(cwd);
+	const manifestPath = path.join(root, 'package.json');
+	const manifest = readJsonc(manifestPath);
+
+	const declaredDependencies = {
+		...(manifest?.dependencies ?? {}),
+		...(manifest?.devDependencies ?? {}),
+		...(manifest?.peerDependencies ?? {}),
+	};
+
+	// Walk up for the lockfile: in a monorepo it lives at the workspace root, not
+	// beside the package being inspected.
+	let packageManager = /** @type {Project['packageManager']} */ (null);
+	let lockfile = null;
+	for (let dir = root; ;) {
+		for (const [file, name] of LOCKFILES) {
+			if (existsSync(path.join(dir, file))) {
+				lockfile = path.relative(root, path.join(dir, file)) || file;
+				packageManager = name;
+				break;
+			}
+		}
+		const parent = path.dirname(dir);
+		if (lockfile || parent === dir) break;
+		dir = parent;
+	}
+
+	if (!packageManager && typeof manifest?.packageManager === 'string') {
+		packageManager = /** @type {Project['packageManager']} */ (
+			manifest.packageManager.split('@')[0]
+		);
+	}
+
+	let bundlerConfigPath = null;
+	let bundler = /** @type {Project['bundler']} */ (null);
+	for (const [base, name] of BUNDLER_CONFIGS) {
+		const found = firstExisting(path.join(root, base));
+		if (found) {
+			bundlerConfigPath = found;
+			bundler = name;
+			break;
+		}
+	}
+
+	const sourceFiles = scanSourceFiles(root);
+	const tsrxFiles = sourceFiles.filter((file) => file.endsWith('.tsrx'));
+
+	return {
+		root,
+		manifestPath: manifest === null ? null : manifestPath,
+		manifest: manifest ?? {},
+		declaredDependencies,
+		bindings: Object.keys(declaredDependencies).filter((name) => name.startsWith('@octanejs/')),
+		packageManager,
+		lockfile,
+		tsconfig: loadTsconfig(root),
+		bundlerConfigPath,
+		bundler,
+		octaneConfigPath: firstExisting(path.join(root, 'octane.config')),
+		sourceFiles,
+		tsrxFiles,
+		isOctaneProject:
+			'octane' in declaredDependencies ||
+			tsrxFiles.length > 0 ||
+			readInstalled(root, 'octane') !== null,
+	};
+}
+
+/**
+ * The shared, serializable view of a project. `doctor --json` and `info` both
+ * report it, so a bug report and a CI result describe the same thing.
+ *
+ * @param {Project} project
+ * @returns {Record<string, unknown>}
+ */
+export function summarizeProject(project) {
+	const octane = readInstalled(project.root, 'octane');
+
+	return {
+		root: project.root,
+		name: project.manifest.name ?? null,
+		hasManifest: project.manifestPath !== null,
+		packageManager: project.packageManager,
+		lockfile: project.lockfile,
+		bundler: project.bundler,
+		bundlerConfig: project.bundlerConfigPath
+			? path.relative(project.root, project.bundlerConfigPath)
+			: null,
+		octaneConfig: project.octaneConfigPath
+			? path.relative(project.root, project.octaneConfigPath)
+			: null,
+		octane: octane?.version ?? null,
+		tsconfig: project.tsconfig ? path.relative(project.root, project.tsconfig.path) : null,
+		tsrxFileCount: project.tsrxFiles.length,
+		bindings: project.bindings.map((name) => ({
+			name,
+			version: readInstalled(project.root, name)?.version ?? null,
+		})),
+	};
+}

package/src/kernel/registry.js

@@ -0,0 +1,52 @@
+/**
+ * The root command table.
+ *
+ * Adding a command is one directory under `src/commands/` plus one entry here.
+ * The list is static so it stays greppable and cannot drift out of sync with
+ * the help output, while `load` keeps every command module off the startup
+ * path until it is the one being run.
+ *
+ * @type {import('./command.js').CommandEntry[]}
+ */
+export const COMMANDS = [
+	{
+		name: 'init',
+		summary: 'Wire Octane into the project in this directory.',
+		load: () => import('../commands/init/index.js'),
+	},
+	{
+		name: 'doctor',
+		summary: 'Diagnose an Octane project and optionally repair it.',
+		load: () => import('../commands/doctor/index.js'),
+	},
+	{
+		name: 'analyze',
+		summary: 'Compile the project and report the Octane compiler diagnostics.',
+		load: () => import('../commands/analyze.js'),
+	},
+	{
+		name: 'info',
+		summary: 'Print environment and project details for a bug report.',
+		load: () => import('../commands/info.js'),
+	},
+	{
+		name: 'add',
+		summary: 'Install an Octane binding and report how it differs from upstream.',
+		load: () => import('../commands/add.js'),
+	},
+	{
+		name: 'bindings',
+		summary: 'List and search the @octanejs/* bindings.',
+		load: () => import('../commands/bindings.js'),
+	},
+	{
+		name: 'explain',
+		summary: 'Explain an Octane runtime error code.',
+		load: () => import('../commands/explain.js'),
+	},
+	{
+		name: 'mcp',
+		summary: 'Register the Octane MCP server with Claude Code, Codex, Cursor, or VS Code.',
+		load: () => import('../commands/mcp/index.js'),
+	},
+];

package/src/kernel/semver.js

@@ -0,0 +1,111 @@
+// Minor and patch are optional so that partial ranges (`>=22`, `^8.0`) parse.
+const VERSION = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?/;
+const COMPARATOR = /^(\^|~|>=|<=|>|<|=)?\s*(.+)$/;
+
+/**
+ * @typedef {{ parts: [number, number, number], prerelease: string | null }} Version
+ */
+
+/**
+ * @param {string} input
+ * @returns {Version | null}
+ */
+export function parseVersion(input) {
+	const match = VERSION.exec(String(input).trim());
+	if (!match) return null;
+	return {
+		parts: [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)],
+		prerelease: match[4] ?? null,
+	};
+}
+
+/**
+ * @param {Version} a
+ * @param {Version} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareVersions(a, b) {
+	for (let i = 0; i < 3; i++) {
+		if (a.parts[i] !== b.parts[i]) return a.parts[i] < b.parts[i] ? -1 : 1;
+	}
+	if (a.prerelease === b.prerelease) return 0;
+	if (a.prerelease === null) return 1;
+	if (b.prerelease === null) return -1;
+	return a.prerelease < b.prerelease ? -1 : 1;
+}
+
+/**
+ * @param {Version} version
+ * @param {string} operator
+ * @param {Version} target
+ * @returns {boolean}
+ */
+function test(version, operator, target) {
+	const order = compareVersions(version, target);
+	switch (operator) {
+		case '>=':
+			return order >= 0;
+		case '>':
+			return order > 0;
+		case '<=':
+			return order <= 0;
+		case '<':
+			return order < 0;
+		case '^': {
+			if (order < 0) return false;
+			const [major, minor] = target.parts;
+			if (major > 0) return version.parts[0] === major;
+			if (minor > 0) return version.parts[0] === 0 && version.parts[1] === minor;
+			return (
+				version.parts[0] === 0 && version.parts[1] === 0 && version.parts[2] === target.parts[2]
+			);
+		}
+		case '~':
+			return (
+				order >= 0 && version.parts[0] === target.parts[0] && version.parts[1] === target.parts[1]
+			);
+		default:
+			return order === 0;
+	}
+}
+
+/**
+ * Evaluate a version against a range.
+ *
+ * Deliberately narrow: it understands the comparator forms that Octane and its
+ * bindings actually publish, and returns `null` for anything else (`workspace:*`,
+ * git URLs, tags) so callers can say "not verified" instead of inventing a
+ * verdict.
+ *
+ * @param {string} version
+ * @param {string} range
+ * @returns {boolean | null}
+ */
+export function satisfies(version, range) {
+	const current = parseVersion(version);
+	if (!current) return null;
+
+	const trimmed = String(range).trim();
+	if (trimmed === '' || trimmed === '*' || trimmed === 'x' || trimmed === 'latest') return true;
+
+	for (const union of trimmed.split('||')) {
+		let matched = true;
+		let evaluated = false;
+
+		for (const token of union.trim().split(/\s+/)) {
+			if (token === '') continue;
+			const parsed = COMPARATOR.exec(token);
+			const target = parsed && parseVersion(parsed[2]);
+			if (!target) return null;
+			evaluated = true;
+			if (!test(current, parsed[1] ?? '=', target)) {
+				matched = false;
+				break;
+			}
+		}
+
+		if (evaluated && matched) return true;
+	}
+
+	return false;
+}

package/src/kernel/ui.js

@@ -0,0 +1,155 @@
+import * as clack from '@clack/prompts';
+import { createColors } from 'picocolors';
+import { CliError, usageError } from './errors.js';
+
+/**
+ * @typedef {'interactive' | 'plain' | 'json'} UiMode
+ *
+ * - `interactive` a TTY session: clack prompts, colour, spinners
+ * - `plain`       a pipe, a CI log, or `--no-color`: line-oriented text only
+ * - `json`        `--json`: every human channel is silenced so stdout carries
+ *                 exactly one JSON document
+ */
+
+/**
+ * @typedef {Object} Choice
+ * @property {string} value
+ * @property {string} label
+ * @property {string} [hint]
+ */
+
+export const SYMBOLS = {
+	pass: '✔',
+	fail: '✖',
+	warn: '⚠',
+	skip: '○',
+};
+
+/**
+ * @param {{ json?: boolean, color?: boolean, tty?: boolean, env?: NodeJS.ProcessEnv }} options
+ * @returns {UiMode}
+ */
+export function resolveMode({ json = false, color = true, tty = false, env = {} } = {}) {
+	if (json) return 'json';
+	if (!tty || !color || env.NO_COLOR || env.CI) return 'plain';
+	return 'interactive';
+}
+
+/**
+ * @param {{ mode: UiMode, yes?: boolean, stdout?: NodeJS.WritableStream }} options
+ */
+export function createUi({ mode, yes = false, stdout = process.stdout }) {
+	const quiet = mode === 'json';
+	const colors = createColors(mode === 'interactive');
+	const write = (/** @type {string} */ line) => {
+		if (!quiet) stdout.write(`${line}\n`);
+	};
+
+	/**
+	 * Non-interactive sessions never block. Either `--yes` supplies the default
+	 * or the caller is told the exact flag that would have answered the prompt.
+	 *
+	 * @param {string} flag
+	 * @param {unknown} fallback
+	 */
+	const unattended = (flag, fallback) => {
+		if (yes && fallback !== undefined) return fallback;
+		throw usageError(
+			`${flag} is required when the CLI is not interactive.`,
+			`Pass ${flag}, or re-run in a terminal to be prompted.`,
+		);
+	};
+
+	/** @param {unknown} value */
+	const guard = (value) => {
+		if (clack.isCancel(value)) throw new CliError('Cancelled.');
+		return value;
+	};
+
+	return {
+		mode,
+		colors,
+		get canPrompt() {
+			return mode === 'interactive';
+		},
+
+		/** @param {string} title */
+		intro(title) {
+			if (mode === 'interactive') clack.intro(colors.bgCyan(colors.black(` ${title} `)));
+			else write(title);
+		},
+
+		/** @param {string} message */
+		outro(message) {
+			if (mode === 'interactive') clack.outro(message);
+			else write(message);
+		},
+
+		/** @param {string} [line] */
+		log(line = '') {
+			write(line);
+		},
+
+		/**
+		 * @param {string} title
+		 * @param {string[]} lines
+		 */
+		note(title, lines) {
+			if (mode === 'interactive') clack.note(lines.join('\n'), title);
+			else {
+				write(title);
+				for (const line of lines) write(`  ${line}`);
+			}
+		},
+
+		/** @param {string} label */
+		spinner(label) {
+			if (mode !== 'interactive') {
+				write(label);
+				return { update() {}, stop: (/** @type {string} */ done) => done && write(`  ${done}`) };
+			}
+			const spin = clack.spinner();
+			spin.start(label);
+			return {
+				update: (/** @type {string} */ message) => spin.message(message),
+				stop: (/** @type {string} */ message) => spin.stop(message ?? label),
+			};
+		},
+
+		/**
+		 * Choices are always strings (command names, client ids, mode names), so
+		 * this deliberately is not generic: callers narrow the result themselves.
+		 *
+		 * @param {{ message: string, flag: string, options: Choice[], initial?: string }} options
+		 * @returns {Promise<string>}
+		 */
+		async select({ message, flag, options, initial }) {
+			if (mode !== 'interactive') return String(unattended(flag, initial));
+			return String(guard(await clack.select({ message, options, initialValue: initial })));
+		},
+
+		/**
+		 * @param {{ message: string, flag: string, options: Choice[], initial?: string[] }} options
+		 * @returns {Promise<string[]>}
+		 */
+		async multiselect({ message, flag, options, initial }) {
+			if (mode !== 'interactive') {
+				return /** @type {string[]} */ (unattended(flag, initial));
+			}
+			return /** @type {string[]} */ (
+				guard(await clack.multiselect({ message, options, initialValues: initial }))
+			);
+		},
+
+		/**
+		 * @param {{ message: string, flag: string, initial?: boolean }} options
+		 * @returns {Promise<boolean>}
+		 */
+		async confirm({ message, flag, initial = true }) {
+			if (mode !== 'interactive') return Boolean(unattended(flag, initial));
+			return Boolean(guard(await clack.confirm({ message, initialValue: initial })));
+		},
+	};
+}
+
+/** @typedef {ReturnType<typeof createUi>} Ui */