@octanejs/cli 0.0.0

package/src/commands/init/index.js

@@ -0,0 +1,277 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { defineCommand } from '../../kernel/command.js';
+import { setCompilerOption } from '../../kernel/edit.js';
+import { CliError, EXIT } from '../../kernel/errors.js';
+import { installPackages } from '../../kernel/install.js';
+import {
+	MODES,
+	SCRIPTS,
+	VITE_SCRIPTS,
+	appComponent,
+	integrationFor,
+	octaneConfig,
+	tsconfig,
+	viteConfig,
+} from './templates.js';
+
+/**
+ * @typedef {Object} Change
+ * @property {string} file relative to the project root
+ * @property {string} summary
+ * @property {() => void} apply
+ */
+
+/**
+ * Refuse to rewrite a project with uncommitted work in it, so `git diff` stays
+ * a usable way to review what init did.
+ *
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @returns {Promise<boolean>} true when the tree is dirty
+ */
+async function isDirty(ctx) {
+	if (!ctx.exec.which('git')) return false;
+	const result = await ctx.exec.run('git', ['status', '--porcelain'], { cwd: ctx.cwd });
+	return result.code === 0 && result.stdout.trim() !== '';
+}
+
+/**
+ * @param {string} file
+ * @param {string} body
+ * @returns {() => void}
+ */
+const writeFile = (file, body) => () => {
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, body);
+};
+
+/**
+ * @param {import('../../kernel/project.js').Project} project
+ * @param {keyof typeof MODES} mode
+ * @param {ReturnType<typeof integrationFor>} integration
+ * @returns {{ changes: Change[], manual: string[] }}
+ */
+function plan(project, mode, integration) {
+	const { root } = project;
+	/** @type {Change[]} */
+	const changes = [];
+	/** @type {string[]} */
+	const manual = [];
+	const at = (/** @type {string} */ file) => path.join(root, file);
+
+	if (!project.tsconfig) {
+		changes.push({
+			file: 'tsconfig.json',
+			summary: 'create, configured for .tsrx',
+			apply: writeFile(at('tsconfig.json'), `${JSON.stringify(tsconfig, null, 2)}\n`),
+		});
+	} else {
+		const file = project.tsconfig.path;
+		const options = project.tsconfig.config.compilerOptions ?? {};
+		/** @type {[string, unknown][]} */
+		const needed = [];
+		if (options.jsxImportSource !== 'octane') needed.push(['jsxImportSource', 'octane']);
+		if (!Array.isArray(options.plugins))
+			needed.push(['plugins', [{ name: '@tsrx/typescript-plugin' }]]);
+		else if (
+			!options.plugins.some((/** @type {any} */ p) => p?.name === '@tsrx/typescript-plugin')
+		) {
+			manual.push('Add { "name": "@tsrx/typescript-plugin" } to compilerOptions.plugins.');
+		}
+
+		if (needed.length > 0) {
+			changes.push({
+				file: path.relative(root, file),
+				summary: `set ${needed.map(([key]) => key).join(', ')}`,
+				apply() {
+					let text = readFileSync(file, 'utf8');
+					for (const [key, value] of needed) {
+						const edited = setCompilerOption(text, key, value);
+						if (!edited) throw new CliError(`Could not edit ${path.basename(file)} safely.`);
+						text = edited.text;
+					}
+					writeFileSync(file, text);
+				},
+			});
+		}
+	}
+
+	const bundlerConfigPath = project.bundlerConfigPath ?? at('vite.config.ts');
+	if (!project.bundlerConfigPath) {
+		changes.push({
+			file: 'vite.config.ts',
+			summary: `create, registering ${integration.specifier}`,
+			apply: writeFile(bundlerConfigPath, viteConfig(mode)),
+		});
+	} else if (!readFileSync(bundlerConfigPath, 'utf8').includes(integration.specifier)) {
+		// Rewriting an arbitrary bundler config is guesswork; state the exact
+		// edit instead of attempting it. The specifier is the one for THIS
+		// project's bundler, not the Vite plugin init would otherwise scaffold.
+		manual.push(
+			`In ${path.relative(root, bundlerConfigPath)}, add: import { octane } from '${integration.specifier}';`,
+			'then include octane() in the plugins array.',
+		);
+	}
+
+	// init only knows how to scaffold Vite. On another bundler it still does the
+	// parts that are correct everywhere (tsconfig, the right plugin, the right
+	// dependency) and states the rest, rather than writing an octane.config.ts
+	// whose import does not resolve or `vite` scripts with no vite installed.
+	// @octanejs/rspack-plugin in particular exports no defineConfig/RenderRoute:
+	// it is the low-level integration where the app owns its own shell.
+	const scaffoldsVite = project.bundler === null || project.bundler === 'vite';
+
+	if (mode === 'fullstack' && !scaffoldsVite) {
+		manual.push(
+			`Add an octane.config.ts for ${project.bundler}: see https://octanejs.dev/docs/build-tools`,
+		);
+	}
+
+	if (mode === 'fullstack' && scaffoldsVite) {
+		if (!project.octaneConfigPath) {
+			changes.push({
+				file: 'octane.config.ts',
+				summary: 'create, with one route at /',
+				apply: writeFile(at('octane.config.ts'), octaneConfig),
+			});
+		}
+		if (!existsSync(at('src/App.tsrx'))) {
+			changes.push({
+				file: 'src/App.tsrx',
+				summary: 'create the route entry referenced by octane.config.ts',
+				apply: writeFile(at('src/App.tsrx'), appComponent),
+			});
+		}
+	}
+
+	const scripts = project.manifest.scripts ?? {};
+	const applicable = scaffoldsVite ? { ...VITE_SCRIPTS, ...SCRIPTS } : SCRIPTS;
+	const missing = Object.entries(applicable).filter(([name]) => !scripts[name]);
+	if (missing.length > 0) {
+		changes.push({
+			file: 'package.json',
+			summary: `add scripts: ${missing.map(([name]) => name).join(', ')}`,
+			apply() {
+				const manifest = JSON.parse(readFileSync(at('package.json'), 'utf8'));
+				manifest.scripts = { ...manifest.scripts, ...Object.fromEntries(missing) };
+				writeFileSync(at('package.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+			},
+		});
+	}
+
+	return { changes, manual };
+}
+
+export default defineCommand({
+	requiresProject: true,
+	description:
+		'Wire Octane into the project in this directory: the bundler plugin, the TypeScript\n' +
+		'settings .tsrx needs, the scripts, and the dependencies.',
+	flags: {
+		mode: {
+			type: 'string',
+			choices: Object.keys(MODES),
+			placeholder: '<mode>',
+			description: 'spa for a client-only app, fullstack for routing and SSR.',
+		},
+		install: {
+			type: 'boolean',
+			default: true,
+			description: 'Install dependencies (--no-install skips).',
+		},
+		force: { type: 'boolean', description: 'Proceed even with uncommitted changes.' },
+	},
+
+	async run(ctx, input) {
+		const project = ctx.project();
+
+		if (!input.flags.force && !ctx.dryRun && (await isDirty(ctx))) {
+			throw new CliError('This project has uncommitted changes.', {
+				hint: 'Commit or stash first so you can review what init writes, or pass --force.',
+			});
+		}
+
+		const mode = /** @type {keyof typeof MODES} */ (
+			input.flags.mode ??
+				(await ctx.ui.select({
+					message: 'What are you building?',
+					flag: '--mode',
+					initial: 'spa',
+					options: Object.entries(MODES).map(([value, entry]) => ({
+						value,
+						label: entry.label,
+						hint: entry.hint,
+					})),
+				}))
+		);
+
+		const integration = integrationFor(project.bundler, mode);
+		const { changes, manual } = plan(project, mode, integration);
+		const declared = project.declaredDependencies;
+		const dependencies = integration.dependencies.filter((name) => !declared[name]);
+		const devDependencies = integration.devDependencies.filter((name) => !declared[name]);
+
+		ctx.ui.intro('octane init');
+
+		if (changes.length === 0 && dependencies.length === 0 && devDependencies.length === 0) {
+			ctx.ui.outro('Already set up. Run `octane doctor` to confirm.');
+			return { json: { ok: true, mode, changes: [], installed: [] } };
+		}
+
+		ctx.ui.note(
+			ctx.dryRun ? 'Would change' : 'Will change',
+			changes.length > 0
+				? changes.map((c) => `${c.file}  ${ctx.ui.colors.dim(c.summary)}`)
+				: ['nothing'],
+		);
+		if (dependencies.length + devDependencies.length > 0) {
+			ctx.ui.note('Will install', [
+				...dependencies,
+				...devDependencies.map((name) => `${name} (dev)`),
+			]);
+		}
+
+		if (ctx.dryRun) {
+			return {
+				json: { ok: true, dryRun: true, mode, changes: changes.map((c) => c.file), manual },
+			};
+		}
+
+		const confirmed = await ctx.ui.confirm({ message: 'Apply?', flag: '--yes', initial: true });
+		if (!confirmed)
+			return { exitCode: EXIT.OK, json: { ok: true, mode, changes: [], installed: [] } };
+
+		for (const change of changes) change.apply();
+
+		/** @type {string[]} */
+		const installed = [];
+		if (input.flags.install && dependencies.length + devDependencies.length > 0) {
+			const spinner = ctx.ui.spinner(`Installing with ${project.packageManager ?? 'npm'}`);
+			try {
+				for (const [names, dev] of [
+					[dependencies, false],
+					[devDependencies, true],
+				]) {
+					if (/** @type {string[]} */ (names).length === 0) continue;
+					await installPackages(ctx, project, /** @type {string[]} */ (names), {
+						dev: Boolean(dev),
+					});
+					installed.push(.../** @type {string[]} */ (names));
+				}
+			} catch (error) {
+				spinner.stop('Install failed');
+				throw error;
+			}
+			spinner.stop(`Installed ${installed.length} package(s)`);
+		} else if (dependencies.length + devDependencies.length > 0) {
+			manual.push(`Install: ${[...dependencies, ...devDependencies].join(' ')}`);
+		}
+
+		if (manual.length > 0) ctx.ui.note('Do this by hand', manual);
+		ctx.ui.outro('Run `octane doctor` to verify the result.');
+
+		return {
+			json: { ok: true, mode, changes: changes.map((c) => c.file), installed, manual },
+		};
+	},
+});

package/src/commands/init/templates.js

@@ -0,0 +1,124 @@
+/**
+ * The two supported ways to compile Octane.
+ *
+ * `spa` wires the compiler plugin only, which is all a client-rendered app
+ * needs. `fullstack` wires the metaframework plugin, which adds routing,
+ * streaming SSR, hydration, and the production build.
+ */
+export const MODES = {
+	spa: {
+		label: 'Client-only app',
+		hint: "compiles .tsrx, keeps the bundler's standard HTML handling",
+		dependencies: [],
+	},
+	fullstack: {
+		label: 'Routing and SSR',
+		hint: 'adds octane.config.ts, streaming SSR, hydration, production build',
+		dependencies: [],
+	},
+};
+
+/**
+ * Which package supplies the Octane plugin, per bundler and mode.
+ *
+ * `init` only scaffolds a Vite project, but it also advises projects that
+ * already have a bundler config, and naming the Vite plugin at an Rspack
+ * project would wire the wrong plugin into the wrong bundler.
+ */
+const INTEGRATIONS = {
+	vite: {
+		spa: { specifier: 'octane/compiler/vite', packages: [] },
+		fullstack: { specifier: '@octanejs/vite-plugin', packages: ['@octanejs/vite-plugin'] },
+	},
+	rspack: {
+		spa: { specifier: 'octane/compiler/bundler', packages: [] },
+		fullstack: { specifier: '@octanejs/rspack-plugin', packages: ['@octanejs/rspack-plugin'] },
+	},
+	rsbuild: {
+		spa: { specifier: 'octane/compiler/bundler', packages: [] },
+		fullstack: { specifier: '@octanejs/rsbuild-plugin', packages: ['@octanejs/rsbuild-plugin'] },
+	},
+	rspeedy: {
+		spa: { specifier: 'octane/compiler/bundler', packages: [] },
+		fullstack: { specifier: '@octanejs/rspeedy-plugin', packages: ['@octanejs/rspeedy-plugin'] },
+	},
+};
+
+/**
+ * @param {keyof typeof INTEGRATIONS | null} bundler defaults to vite, which is
+ *   what `init` scaffolds when a project has no bundler config yet
+ * @param {keyof typeof MODES} mode
+ * @returns {{ specifier: string, dependencies: string[], devDependencies: string[] }}
+ */
+export function integrationFor(bundler, mode) {
+	const target = INTEGRATIONS[bundler ?? 'vite'] ?? INTEGRATIONS.vite;
+	return {
+		specifier: target[mode].specifier,
+		dependencies: ['octane', ...target[mode].packages],
+		// The bundler itself is only ours to install when we are the ones
+		// creating its config.
+		devDependencies: ['@tsrx/typescript-plugin', ...(bundler === null ? ['vite'] : [])],
+	};
+}
+
+/**
+ * @param {keyof typeof MODES} mode
+ * @returns {string}
+ */
+export const viteConfig = (mode) => `import { defineConfig } from 'vite';
+import { octane } from '${integrationFor('vite', mode).specifier}';
+
+export default defineConfig({
+\tplugins: [octane()],
+\tbuild: { target: 'esnext' },
+});
+`;
+
+export const octaneConfig = `import { defineConfig, RenderRoute } from '@octanejs/vite-plugin';
+
+export default defineConfig({
+\trouter: {
+\t\troutes: [new RenderRoute({ path: '/', entry: ['App', '/src/App.tsrx'] })],
+\t},
+});
+`;
+
+export const appComponent = `export function App() @{
+\t<div class="app">
+\t\t<h1>{'Hello from Octane' as string}</h1>
+\t</div>
+}
+`;
+
+export const tsconfig = {
+	compilerOptions: {
+		target: 'esnext',
+		module: 'esnext',
+		moduleResolution: 'bundler',
+		lib: ['esnext', 'dom', 'dom.iterable'],
+		strict: true,
+		noEmit: true,
+		allowImportingTsExtensions: true,
+		isolatedModules: true,
+		esModuleInterop: true,
+		skipLibCheck: true,
+		jsx: 'react-jsx',
+		jsxImportSource: 'octane',
+		plugins: [{ name: '@tsrx/typescript-plugin' }],
+	},
+	include: ['src/**/*', 'vite.config.ts'],
+};
+
+/**
+ * Scripts that are correct whatever the bundler is. `tsrx-tsc` is the only
+ * typechecker that reads `.tsrx`, regardless of how the project builds.
+ */
+export const SCRIPTS = {
+	typecheck: 'tsrx-tsc --noEmit -p tsconfig.json',
+};
+
+/** Added only when init is the one creating the Vite config. */
+export const VITE_SCRIPTS = {
+	dev: 'vite',
+	build: 'vite build',
+};

package/src/commands/mcp/add.js

@@ -0,0 +1,241 @@
+import { copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { defineCommand } from '../../kernel/command.js';
+import { CliError, EXIT, usageError } from '../../kernel/errors.js';
+import { CLIENTS, findClient, readConfigText } from './clients.js';
+import { detectClients, isPresent } from './detect.js';
+import { SERVER_NAME, SERVER_PACKAGE, buildServerEntry, findRepoRoot } from './server.js';
+
+/**
+ * @typedef {Object} Outcome
+ * @property {string} client
+ * @property {string} scope
+ * @property {'cli' | 'file'} method
+ * @property {string} target
+ * @property {'added' | 'updated' | 'unchanged' | 'skipped' | 'failed'} status
+ * @property {string} message
+ */
+
+/**
+ * Install by handing the work to the client's own CLI, which owns its config
+ * schema and can change it without telling us.
+ *
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {import('./detect.js').ClientState} state
+ * @param {import('./server.js').ServerEntry} entry
+ * @returns {Promise<Outcome | null>} null when the CLI route is unavailable
+ */
+async function installViaCli(ctx, state, entry) {
+	const { client } = state;
+	const args =
+		client.cli && state.cliAvailable ? client.cliArgs(SERVER_NAME, entry, state.scope) : null;
+	if (!client.cli || !args) return null;
+
+	const result = await ctx.exec.run(client.cli, args, { cwd: ctx.cwd });
+	const base = {
+		client: client.id,
+		scope: state.scope,
+		method: /** @type {const} */ ('cli'),
+		target: client.cli,
+	};
+
+	if (result.code !== 0) {
+		return {
+			...base,
+			status: 'failed',
+			message:
+				(result.stderr || result.stdout).trim() || `${client.cli} exited with ${result.code}`,
+		};
+	}
+	return {
+		...base,
+		status: state.server ? 'updated' : 'added',
+		message: `${client.cli} ${args.join(' ')}`,
+	};
+}
+
+/**
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {import('./detect.js').ClientState} state
+ * @param {import('./server.js').ServerEntry} entry
+ * @returns {Outcome}
+ */
+function installViaFile(ctx, state, entry) {
+	const { client, configPath } = state;
+	const current = readConfigText(configPath);
+	const next = client.write(current, SERVER_NAME, entry);
+	const base = {
+		client: client.id,
+		scope: state.scope,
+		method: /** @type {const} */ ('file'),
+		target: configPath,
+	};
+
+	if (next === current) return { ...base, status: 'unchanged', message: 'Already up to date' };
+
+	mkdirSync(path.dirname(configPath), { recursive: true });
+	// Back up anything that was already there. These files hold the user's other
+	// servers and, for Claude Code, unrelated state.
+	if (current !== '') copyFileSync(configPath, `${configPath}.octane-backup`);
+	writeFileSync(configPath, next);
+
+	return {
+		...base,
+		status: state.server ? 'updated' : 'added',
+		message:
+			current === '' ? 'Created' : `Merged (backup at ${path.basename(configPath)}.octane-backup)`,
+	};
+}
+
+export default defineCommand({
+	description:
+		`Register the Octane MCP server (${SERVER_PACKAGE}) with a coding agent, so it can\n` +
+		'reach the Octane skills, bindings data, and React-to-Octane bridging tools.',
+	positionals: [
+		{
+			name: 'client',
+			description: `Clients to configure: ${CLIENTS.map((c) => c.id).join(', ')}. Defaults to every detected client.`,
+			variadic: true,
+		},
+	],
+	flags: {
+		scope: {
+			type: 'string',
+			choices: ['user', 'project'],
+			default: 'user',
+			placeholder: '<scope>',
+			description: 'Install for this user, or into this project so the team shares it.',
+		},
+		command: {
+			type: 'string',
+			placeholder: '<bin>',
+			description: `Run the server this way instead of \`npx -y ${SERVER_PACKAGE}\`.`,
+		},
+		force: { type: 'boolean', description: 'Overwrite an existing octane entry without asking.' },
+	},
+
+	async run(ctx, input) {
+		const scope = /** @type {import('./clients.js').Scope} */ (input.flags.scope);
+		const project = ctx.project();
+		const detected = detectClients(ctx, scope, project.root);
+
+		const selected =
+			input.positionals.length > 0
+				? resolveRequested(input.positionals, detected)
+				: await chooseClients(ctx, detected);
+
+		if (selected.length === 0) throw new CliError('No clients selected.');
+
+		const repoRoot = findRepoRoot(ctx.cwd);
+		const entry = buildServerEntry({ command: input.flags.command, repoRoot });
+
+		ctx.ui.intro('octane mcp add');
+		if (repoRoot)
+			ctx.ui.log(ctx.ui.colors.dim(`Detected an Octane checkout: OCTANE_REPO_ROOT=${repoRoot}`));
+
+		if (ctx.dryRun) {
+			for (const state of selected) {
+				ctx.ui.note(`${state.client.label} (${scope})`, [
+					state.cliAvailable && state.client.cli
+						? `would run: ${state.client.cli} ${state.client.cliArgs(SERVER_NAME, entry, scope)?.join(' ')}`
+						: `would write: ${state.configPath}`,
+					...JSON.stringify({ [SERVER_NAME]: entry }, null, 2).split('\n'),
+				]);
+			}
+			return { json: { ok: true, dryRun: true, clients: selected.map((s) => s.client.id) } };
+		}
+
+		/** @type {Outcome[]} */
+		const outcomes = [];
+		for (const state of selected) {
+			const existing = state.server && !input.flags.force;
+			if (existing) {
+				const replace = await ctx.ui.confirm({
+					message: `${state.client.label} already has an "${SERVER_NAME}" server. Replace it?`,
+					flag: '--force',
+					initial: false,
+				});
+				if (!replace) {
+					const viaCli = state.cliAvailable && state.client.cli;
+					outcomes.push({
+						client: state.client.id,
+						scope,
+						method: viaCli ? 'cli' : 'file',
+						target: viaCli ? /** @type {string} */ (state.client.cli) : state.configPath,
+						status: 'skipped',
+						message: 'Left the existing entry in place',
+					});
+					continue;
+				}
+			}
+			outcomes.push((await installViaCli(ctx, state, entry)) ?? installViaFile(ctx, state, entry));
+		}
+
+		for (const outcome of outcomes) {
+			const failed = outcome.status === 'failed';
+			const mark = failed ? ctx.ui.colors.red('✖') : ctx.ui.colors.green('✔');
+			ctx.ui.log(
+				`  ${mark} ${outcome.client} (${outcome.scope}) ${ctx.ui.colors.dim(outcome.message)}`,
+			);
+		}
+		ctx.ui.outro('Restart the agent to pick up the new server.');
+
+		const ok = outcomes.every((outcome) => outcome.status !== 'failed');
+		return { exitCode: ok ? EXIT.OK : EXIT.FAILURE, json: { ok, server: entry, outcomes } };
+	},
+});
+
+/**
+ * @param {string[]} ids
+ * @param {import('./detect.js').ClientState[]} detected
+ * @returns {import('./detect.js').ClientState[]}
+ */
+function resolveRequested(ids, detected) {
+	return ids.map((id) => {
+		if (!findClient(id)) {
+			throw usageError(
+				`Unknown client: ${id}`,
+				`Known clients: ${CLIENTS.map((c) => c.id).join(', ')}.`,
+			);
+		}
+		const state = detected.find((candidate) => candidate.client.id === id);
+		if (!state) {
+			throw usageError(
+				`${id} does not support --scope ${detected[0]?.scope ?? 'this scope'}.`,
+				`${id} supports: ${findClient(id)?.scopes.join(', ')}.`,
+			);
+		}
+		return state;
+	});
+}
+
+/**
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {import('./detect.js').ClientState[]} detected
+ * @returns {Promise<import('./detect.js').ClientState[]>}
+ */
+async function chooseClients(ctx, detected) {
+	const present = detected.filter(isPresent);
+	if (present.length === 0) {
+		throw new CliError('No supported agent found on this machine.', {
+			hint: `Name one explicitly: octane mcp add ${CLIENTS.map((c) => c.id).join('|')}`,
+		});
+	}
+
+	const chosen = await ctx.ui.multiselect({
+		message: 'Which agents should get the Octane MCP server?',
+		flag: '<client>',
+		initial: present.map((state) => state.client.id),
+		options: present.map((state) => ({
+			value: state.client.id,
+			label: state.client.label,
+			hint: state.server
+				? 'already configured'
+				: state.cliAvailable
+					? 'via its CLI'
+					: state.configPath,
+		})),
+	});
+
+	return present.filter((state) => chosen.includes(state.client.id));
+}