@octanejs/cli 0.0.0

package/src/index.js

@@ -0,0 +1,4 @@
+export { main, VERSION } from './kernel/main.js';
+export { defineCommand } from './kernel/command.js';
+export { CliError, EXIT } from './kernel/errors.js';
+export { detectProject } from './kernel/project.js';

package/src/kernel/args.js

@@ -0,0 +1,181 @@
+import { usageError } from './errors.js';
+
+/**
+ * @typedef {Object} FlagSpec
+ * @property {'boolean' | 'string' | 'number'} type
+ * @property {string} description
+ * @property {string} [short] single character alias, without the dash
+ * @property {unknown} [default]
+ * @property {readonly string[]} [choices]
+ * @property {boolean} [repeatable] collect every occurrence into an array
+ * @property {string} [placeholder] value name shown in help, e.g. `<dir>`
+ */
+
+/**
+ * @typedef {Object} PositionalSpec
+ * @property {string} name
+ * @property {string} description
+ * @property {boolean} [required] documentation only; commands enforce it
+ *   themselves so that an interactive session can prompt for the value instead
+ * @property {boolean} [variadic]
+ */
+
+/**
+ * @typedef {Object} ParsedArgs
+ * @property {Record<string, unknown>} flags
+ * @property {string[]} positionals
+ * @property {string[]} rest tokens after a bare `--`
+ */
+
+/**
+ * Flags every command accepts. Merged into each command's own spec so that
+ * parsing, validation, and help all see one flat table.
+ *
+ * @type {Record<string, FlagSpec>}
+ */
+export const GLOBAL_FLAGS = {
+	help: { type: 'boolean', short: 'h', description: 'Show help for this command.' },
+	version: { type: 'boolean', short: 'v', description: 'Print the CLI version.' },
+	json: { type: 'boolean', description: 'Emit a single JSON result and no human output.' },
+	cwd: { type: 'string', placeholder: '<dir>', description: 'Run against a different directory.' },
+	yes: { type: 'boolean', short: 'y', description: 'Accept every prompt with its default.' },
+	'dry-run': { type: 'boolean', description: 'Report what would change without writing.' },
+	color: { type: 'boolean', default: true, description: 'Colorize output (--no-color disables).' },
+	verbose: { type: 'boolean', description: 'Include diagnostic detail in output.' },
+};
+
+/**
+ * @param {FlagSpec} spec
+ * @param {string} name
+ * @param {string} raw
+ * @returns {unknown}
+ */
+function coerce(spec, name, raw) {
+	if (spec.type === 'number') {
+		const value = Number(raw);
+		if (!Number.isFinite(value)) throw usageError(`--${name} expects a number, got "${raw}".`);
+		return value;
+	}
+	if (spec.type === 'boolean') {
+		if (raw === 'true') return true;
+		if (raw === 'false') return false;
+		throw usageError(`--${name} expects true or false, got "${raw}".`);
+	}
+	if (spec.choices && !spec.choices.includes(raw)) {
+		throw usageError(`--${name} expects one of: ${spec.choices.join(', ')}. Got "${raw}".`);
+	}
+	return raw;
+}
+
+/**
+ * @param {Record<string, FlagSpec>} specs
+ * @returns {Map<string, string>}
+ */
+function shortIndex(specs) {
+	const index = new Map();
+	for (const [name, spec] of Object.entries(specs)) {
+		if (spec.short) index.set(spec.short, name);
+	}
+	return index;
+}
+
+/**
+ * Parse argv against a flag/positional spec.
+ *
+ * Supports `--name`, `--name=value`, `--name value`, `--no-name` for booleans,
+ * `-x` short aliases, and a bare `--` terminator. An unrecognized flag is a
+ * usage error rather than a silently ignored token, because a typo'd flag that
+ * parses as a positional is the worst possible failure mode for a `--fix`-style
+ * command.
+ *
+ * @param {string[]} argv
+ * @param {{ flags?: Record<string, FlagSpec>, positionals?: PositionalSpec[] }} spec
+ * @returns {ParsedArgs}
+ */
+export function parseArgs(argv, spec = {}) {
+	const specs = { ...GLOBAL_FLAGS, ...(spec.flags ?? {}) };
+	const shorts = shortIndex(specs);
+
+	/** @type {Record<string, unknown>} */
+	const flags = {};
+	/** @type {string[]} */
+	const positionals = [];
+	/** @type {string[]} */
+	let rest = [];
+
+	for (const [name, entry] of Object.entries(specs)) {
+		if (entry.default !== undefined) flags[name] = entry.default;
+		else if (entry.repeatable) flags[name] = [];
+	}
+
+	/**
+	 * @param {string} name
+	 * @param {unknown} value
+	 */
+	const assign = (name, value) => {
+		const entry = specs[name];
+		if (entry.repeatable) {
+			const list = Array.isArray(flags[name]) ? /** @type {unknown[]} */ (flags[name]) : [];
+			list.push(value);
+			flags[name] = list;
+		} else {
+			flags[name] = value;
+		}
+	};
+
+	for (let i = 0; i < argv.length; i++) {
+		const token = argv[i];
+
+		if (token === '--') {
+			rest = argv.slice(i + 1);
+			break;
+		}
+
+		if (!token.startsWith('-') || token === '-') {
+			positionals.push(token);
+			continue;
+		}
+
+		const isLong = token.startsWith('--');
+		const body = isLong ? token.slice(2) : token.slice(1);
+		const eq = body.indexOf('=');
+		const key = eq === -1 ? body : body.slice(0, eq);
+		const inline = eq === -1 ? undefined : body.slice(eq + 1);
+
+		let name = (isLong ? key : shorts.get(key)) ?? '';
+		let negated = false;
+
+		if (isLong && !specs[name] && key.startsWith('no-') && specs[key.slice(3)]) {
+			name = key.slice(3);
+			negated = true;
+		}
+
+		const entry = specs[name];
+		if (!entry) throw usageError(`Unknown flag: ${token}`, 'Run with --help to see valid flags.');
+
+		if (negated) {
+			if (entry.type !== 'boolean') throw usageError(`--no-${name} is only valid for flags.`);
+			assign(name, false);
+			continue;
+		}
+
+		if (inline !== undefined) {
+			assign(name, coerce(entry, name, inline));
+			continue;
+		}
+
+		if (entry.type === 'boolean') {
+			assign(name, true);
+			continue;
+		}
+
+		const next = argv[i + 1];
+		if (next === undefined || (next.startsWith('-') && next !== '-')) {
+			throw usageError(`--${name} expects a value.`);
+		}
+		assign(name, coerce(entry, name, next));
+		i++;
+	}
+
+	return { flags, positionals, rest };
+}

package/src/kernel/banner.js

@@ -0,0 +1,98 @@
+/**
+ * The Octane mark, for the root invocation only.
+ *
+ * It is decoration, so it appears exactly where decoration is harmless: a human
+ * run of bare `octane` or `octane --help`. Never under `--json`, where it would
+ * sit in front of the document, and never on a subcommand, where it would be
+ * noise on every `doctor` run in a loop.
+ *
+ * The glyphs are the art itself, not a fill pattern: their varying weight is
+ * what gives the flame its shading, so they are kept verbatim rather than
+ * flattened to block characters. Colour is the only thing applied on top, and
+ * it follows the two fills in `icon.svg`.
+ */
+const MARK = [
+	'        :&',
+	'      ::&&',
+	'     :&&&&&&:',
+	'  :&&&&r; :&&&:',
+	' &&&&&rr; rr&&&',
+	':&&:&rrrrrr&&&&',
+	' &&&&rr&r&&&&:',
+	'  ::&&&&&::',
+];
+
+/**
+ * The low-ink glyphs that make up the inner flame. Everything else is the outer
+ * body, including the edge characters that share some of these shapes.
+ */
+const INNER = new Set('rltj;-|+_');
+
+/** The two fills in `icon.svg`, which are also `--text` and `--accent` on the site. */
+const CREAM = [244, 238, 232];
+const FIRE = [255, 65, 90];
+
+/**
+ * @param {import('./ui.js').Ui} ui
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ cream: (s: string) => string, fire: (s: string) => string }}
+ */
+function palette(ui, env) {
+	if (ui.mode !== 'interactive') {
+		const plain = (/** @type {string} */ s) => s;
+		return { cream: plain, fire: plain };
+	}
+	if (env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit') {
+		const rgb =
+			(/** @type {number[]} */ [r, g, b]) =>
+			(/** @type {string} */ s) =>
+				`\x1b[38;2;${r};${g};${b}m${s}\x1b[39m`;
+		return { cream: rgb(CREAM), fire: rgb(FIRE) };
+	}
+	// 256- and 16-colour terminals: the mark still reads as a two-tone flame,
+	// just in the nearest available pair.
+	return { cream: ui.colors.white, fire: ui.colors.red };
+}
+
+/**
+ * Colour a row, emitting one escape per run of like-coloured glyphs rather than
+ * per character.
+ *
+ * @param {string} row
+ * @param {ReturnType<typeof palette>} colors
+ * @returns {string}
+ */
+function paintRow(row, colors) {
+	let out = '';
+	for (let i = 0; i < row.length;) {
+		const kind = row[i] === ' ' ? 'gap' : INNER.has(row[i]) ? 'inner' : 'outer';
+		let end = i;
+		while (
+			end < row.length &&
+			(row[end] === ' ' ? 'gap' : INNER.has(row[end]) ? 'inner' : 'outer') === kind
+		) {
+			end++;
+		}
+		const run = row.slice(i, end);
+		out += kind === 'gap' ? run : (kind === 'inner' ? colors.fire : colors.cream)(run);
+		i = end;
+	}
+	return out;
+}
+
+/**
+ * @param {import('./context.js').Ctx} ctx
+ */
+export function renderBanner(ctx) {
+	if (ctx.json) return;
+
+	const colors = palette(ctx.ui, ctx.env);
+	const { bold, dim } = ctx.ui.colors;
+
+	ctx.ui.log('');
+	for (const row of MARK) ctx.ui.log(`  ${paintRow(row, colors)}`);
+	ctx.ui.log('');
+	ctx.ui.log(`  ${bold(colors.cream('OCTANE CLI'))} ${dim(`v${ctx.version}`)}`);
+	ctx.ui.log(`  ${dim("React's programming model, compiled.")}`);
+	ctx.ui.log('');
+}

package/src/kernel/command.js

@@ -0,0 +1,84 @@
+/**
+ * @typedef {Object} CommandEntry
+ * An index record. Name, aliases, and the one-line summary live here and
+ * nowhere else, so `octane --help` can list every command without importing a
+ * single command module.
+ * @property {string} name
+ * @property {string} summary
+ * @property {string[]} [aliases]
+ * @property {() => Promise<{ default: CommandModule }>} load
+ */
+
+/**
+ * @typedef {Object} CommandModule
+ * The behaviour half of a command. It never repeats its own name or summary.
+ * @property {string} [description] long help, shown above the flag table
+ * @property {Record<string, import('./args.js').FlagSpec>} [flags]
+ * @property {import('./args.js').PositionalSpec[]} [positionals]
+ * @property {CommandEntry[]} [subcommands]
+ * @property {boolean} [requiresProject] refuse to run outside a package.json,
+ *   for commands that write into one
+ * @property {(ctx: import('./context.js').Ctx, input: CommandInput) => Promise<CommandResult>} [run]
+ */
+
+/**
+ * @typedef {Object} CommandInput
+ * @property {Record<string, any>} flags
+ * @property {string[]} positionals
+ * @property {string[]} rest
+ */
+
+/**
+ * @typedef {void | number | { exitCode?: number, json?: unknown }} CommandResult
+ * Human output is written through `ctx.ui` as the command runs. `json` is the
+ * machine payload, printed by the kernel only under `--json`, so neither mode
+ * has to know about the other.
+ */
+
+/**
+ * Identity function that pins a module to the {@link CommandModule} shape.
+ *
+ * @param {CommandModule} command
+ * @returns {CommandModule}
+ */
+export function defineCommand(command) {
+	return command;
+}
+
+/**
+ * @param {CommandEntry[]} entries
+ * @param {string} name
+ * @returns {CommandEntry | undefined}
+ */
+export function findEntry(entries, name) {
+	return entries.find((entry) => entry.name === name || entry.aliases?.includes(name));
+}
+
+/**
+ * Walk argv through nested command registries, loading only the modules that
+ * are actually on the resolved path.
+ *
+ * @param {CommandEntry[]} entries
+ * @param {string[]} argv
+ * @returns {Promise<{ path: string[], module: CommandModule | null, argv: string[] }>}
+ */
+export async function resolveCommand(entries, argv) {
+	/** @type {string[]} */
+	const path = [];
+	/** @type {CommandModule | null} */
+	let module = null;
+	let available = entries;
+	let rest = argv;
+
+	while (rest.length > 0) {
+		const entry = rest[0].startsWith('-') ? undefined : findEntry(available, rest[0]);
+		if (!entry) break;
+
+		path.push(entry.name);
+		rest = rest.slice(1);
+		module = (await entry.load()).default;
+		available = module.subcommands ?? [];
+	}
+
+	return { path, module, argv: rest };
+}

package/src/kernel/context.js

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { createExec } from './exec.js';
+import { usageError } from './errors.js';
+import { detectProject } from './project.js';
+import { createUi, resolveMode } from './ui.js';
+
+/**
+ * @typedef {Object} Ctx
+ * @property {string} cwd
+ * @property {NodeJS.ProcessEnv} env
+ * @property {string} version
+ * @property {import('./ui.js').Ui} ui
+ * @property {import('./exec.js').Exec} exec
+ * @property {boolean} json
+ * @property {boolean} yes
+ * @property {boolean} dryRun
+ * @property {boolean} verbose
+ * @property {() => import('./project.js').Project} project
+ * @property {() => import('./project.js').Project} refreshProject
+ */
+
+/**
+ * @param {{
+ *   flags: Record<string, any>,
+ *   version: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   stdout?: NodeJS.WritableStream,
+ *   tty?: boolean,
+ *   exec?: import('./exec.js').Exec,
+ * }} options
+ * @returns {Ctx}
+ */
+export function createContext({
+	flags,
+	version,
+	env = process.env,
+	stdout = process.stdout,
+	tty = Boolean(/** @type {any} */ (stdout).isTTY),
+	exec,
+}) {
+	const cwd = path.resolve(flags.cwd ?? process.cwd());
+	// A typo'd --cwd would otherwise be reported on as if it were an empty
+	// project, which reads as a real (and wrong) result.
+	if (flags.cwd !== undefined && !existsSync(cwd)) {
+		throw usageError(`--cwd directory does not exist: ${cwd}`);
+	}
+	const json = Boolean(flags.json);
+	const ui = createUi({
+		mode: resolveMode({ json, color: flags.color !== false, tty, env }),
+		yes: Boolean(flags.yes),
+		stdout,
+	});
+
+	/** @type {import('./project.js').Project | undefined} */
+	let project;
+
+	return {
+		cwd,
+		env,
+		version,
+		ui,
+		exec: exec ?? createExec(env),
+		json,
+		yes: Boolean(flags.yes),
+		dryRun: Boolean(flags['dry-run']),
+		verbose: Boolean(flags.verbose),
+		project() {
+			project ??= detectProject(cwd);
+			return project;
+		},
+		/** Re-read the project from disk, after a command has written to it. */
+		refreshProject() {
+			project = detectProject(cwd);
+			return project;
+		},
+	};
+}

package/src/kernel/edit.js

@@ -0,0 +1,238 @@
+/**
+ * Surgical JSONC editing.
+ *
+ * `--fix` rewrites files people hand-maintain, so edits are made as text
+ * splices rather than by reparsing and reserializing. A tsconfig that comes
+ * back with its comments stripped and its formatting churned is a worse outcome
+ * than the problem being fixed.
+ */
+
+/**
+ * Advance past a string literal or a comment beginning at `i`.
+ *
+ * Every scanner below routes through this. `tsconfig.json` is JSONC, so a `}`
+ * or a quoted key inside a comment is ordinary prose: treating it as syntax
+ * closes the wrong object and lets an edit land in the comment, or duplicate a
+ * key that was already there.
+ *
+ * @param {string} text
+ * @param {number} i
+ * @returns {{ end: number, kind: 'string' | 'comment' } | null}
+ */
+function skipTrivia(text, i) {
+	if (text[i] === '/' && text[i + 1] === '/') {
+		let j = i + 2;
+		while (j < text.length && text[j] !== '\n') j++;
+		return { end: j, kind: 'comment' };
+	}
+	if (text[i] === '/' && text[i + 1] === '*') {
+		let j = i + 2;
+		while (j < text.length && !(text[j] === '*' && text[j + 1] === '/')) j++;
+		return { end: Math.min(j + 2, text.length), kind: 'comment' };
+	}
+	if (text[i] === '"') {
+		let j = i + 1;
+		while (j < text.length && text[j] !== '"') j += text[j] === '\\' ? 2 : 1;
+		return { end: j + 1, kind: 'string' };
+	}
+	return null;
+}
+
+/**
+ * Index of the document's opening brace, skipping any leading comment.
+ *
+ * @param {string} text
+ * @returns {number}
+ */
+function findRootBrace(text) {
+	for (let i = 0; i < text.length;) {
+		const trivia = skipTrivia(text, i);
+		if (trivia) {
+			i = trivia.end;
+			continue;
+		}
+		if (text[i] === '{') return i;
+		i++;
+	}
+	return -1;
+}
+
+/**
+ * Match the object that starts at `open`.
+ *
+ * @param {string} text
+ * @param {number} open index of the `{`
+ * @returns {number} index of the matching `}`, or -1
+ */
+function matchBrace(text, open) {
+	let depth = 0;
+	for (let i = open; i < text.length;) {
+		const trivia = skipTrivia(text, i);
+		if (trivia) {
+			i = trivia.end;
+			continue;
+		}
+		const ch = text[i];
+		if (ch === '{' || ch === '[') depth++;
+		else if (ch === '}' || ch === ']') {
+			depth--;
+			if (depth === 0) return i;
+		}
+		i++;
+	}
+	return -1;
+}
+
+/**
+ * Locate a top-level property inside the object spanning [open, close].
+ *
+ * @param {string} text
+ * @param {number} open
+ * @param {number} close
+ * @param {string} key
+ * @returns {{ start: number, valueStart: number, valueEnd: number } | null}
+ */
+function findProperty(text, open, close, key) {
+	const needle = `"${key}"`;
+	let depth = 0;
+
+	for (let i = open + 1; i < close;) {
+		const trivia = skipTrivia(text, i);
+		if (trivia) {
+			if (trivia.kind === 'string' && depth === 0 && text.slice(i, trivia.end) === needle) {
+				let cursor = trivia.end;
+				while (cursor < close && /\s/.test(text[cursor])) cursor++;
+				if (text[cursor] === ':') {
+					cursor++;
+					while (cursor < close && /\s/.test(text[cursor])) cursor++;
+					const valueStart = cursor;
+					const valueEnd =
+						text[cursor] === '{' || text[cursor] === '['
+							? matchBrace(text, cursor) + 1
+							: scanScalar(text, cursor, close);
+					return { start: i, valueStart, valueEnd };
+				}
+			}
+			i = trivia.end;
+			continue;
+		}
+		const ch = text[i];
+		if (ch === '{' || ch === '[') depth++;
+		else if (ch === '}' || ch === ']') depth--;
+		i++;
+	}
+	return null;
+}
+
+/**
+ * @param {string} text
+ * @param {number} from
+ * @param {number} limit
+ * @returns {number}
+ */
+function scanScalar(text, from, limit) {
+	const trivia = skipTrivia(text, from);
+	if (trivia?.kind === 'string') return trivia.end;
+
+	let i = from;
+	// Stop before a trailing comment as well as the structural characters: the
+	// value ends where the comment begins, and the comment is not ours to move.
+	while (i < limit && !/[,}\]\n]/.test(text[i]) && !(text[i] === '/' && /[/*]/.test(text[i + 1]))) {
+		i++;
+	}
+	return i;
+}
+
+/**
+ * @param {string} text
+ * @param {number} open
+ * @returns {string}
+ */
+function detectIndent(text, open) {
+	const rest = text.slice(open + 1);
+	const match = /^\r?\n([ \t]+)/.exec(rest);
+	if (match) return match[1];
+	const outer = /\n([ \t]+)[^\n]*$/.exec(text.slice(0, open));
+	return outer ? `${outer[1]}${outer[1]}` : '\t';
+}
+
+/**
+ * Set `compilerOptions.<key>` to a JSON value, adding `compilerOptions` itself
+ * if the file does not have one.
+ *
+ * @param {string} text
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {{ text: string, changed: boolean } | null} `null` when the shape is
+ *   not one this editor can change safely
+ */
+export function setCompilerOption(text, key, value) {
+	const serialized = JSON.stringify(value);
+	const rootOpen = findRootBrace(text);
+	if (rootOpen === -1) return null;
+	const rootClose = matchBrace(text, rootOpen);
+	if (rootClose === -1) return null;
+
+	const options = findProperty(text, rootOpen, rootClose, 'compilerOptions');
+
+	if (!options) {
+		const indent = detectIndent(text, rootOpen);
+		const insertion = `\n${indent}"compilerOptions": { ${JSON.stringify(key)}: ${serialized} },`;
+		return {
+			text: text.slice(0, rootOpen + 1) + insertion + text.slice(rootOpen + 1),
+			changed: true,
+		};
+	}
+
+	if (text[options.valueStart] !== '{') return null;
+	const open = options.valueStart;
+	const close = matchBrace(text, open);
+	if (close === -1) return null;
+
+	const existing = findProperty(text, open, close, key);
+	if (existing) {
+		if (text.slice(existing.valueStart, existing.valueEnd).trim() === serialized) {
+			return { text, changed: false };
+		}
+		return {
+			text: text.slice(0, existing.valueStart) + serialized + text.slice(existing.valueEnd),
+			changed: true,
+		};
+	}
+
+	const indent = detectIndent(text, open);
+	const body = text.slice(open + 1, close);
+	const separator = body.trim() === '' ? '' : ',';
+	const insertion = `\n${indent}${JSON.stringify(key)}: ${serialized}${separator}`;
+	return { text: text.slice(0, open + 1) + insertion + text.slice(open + 1), changed: true };
+}
+
+/**
+ * Resolve a nested property to its value range, for callers that want to splice
+ * rather than reserialize.
+ *
+ * @param {string} text
+ * @param {string[]} keys
+ * @returns {{ valueStart: number, valueEnd: number } | null}
+ */
+export function findNestedProperty(text, keys) {
+	let open = text.indexOf('{');
+	if (open === -1) return null;
+	let close = matchBrace(text, open);
+	if (close === -1) return null;
+
+	/** @type {{ start: number, valueStart: number, valueEnd: number } | null} */
+	let found = null;
+
+	for (const key of keys) {
+		found = findProperty(text, open, close, key);
+		if (!found) return null;
+		if (text[found.valueStart] === '{') {
+			open = found.valueStart;
+			close = matchBrace(text, open);
+			if (close === -1) return null;
+		}
+	}
+
+	return found && { valueStart: found.valueStart, valueEnd: found.valueEnd };
+}