@octanejs/cli 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @octanejs/cli
+
+The Octane command line. Diagnose a project, wire Octane into an existing one,
+install bindings, decode runtime errors, and register the Octane MCP server with
+your coding agent.
+
+```bash
+pnpm add -D @octanejs/cli
+octane doctor
+```
+
+Or without installing:
+
+```bash
+pnpm dlx @octanejs/cli doctor
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `octane init` | Wire Octane into the project in this directory: bundler plugin, tsconfig, scripts, dependencies. |
+| `octane doctor` | Check the project for the mistakes that break Octane quietly. `--fix` repairs the mechanical ones. |
+| `octane analyze` | Compile the project and report every Octane compiler diagnostic, with its code and suggested edit. |
+| `octane add <package>` | Install a binding, by its own name or by the React package it ports, and print its divergences. |
+| `octane bindings [query]` | List and search the `@octanejs/*` bindings. |
+| `octane explain <error>` | Decode a runtime error code, including the minified production message. |
+| `octane info` | Environment and project details worth pasting into a bug report. |
+| `octane mcp add` | Register the Octane MCP server with Claude Code, Codex, Cursor, or VS Code. |
+
+Run `octane <command> --help` for the flags. Every command accepts the same
+global options: `--json`, `--cwd <dir>`, `--yes`, `--dry-run`, `--no-color`,
+`--verbose`.
+
+## `octane doctor`
+
+Octane is a compiler framework, so its misconfigurations tend to fail quietly
+rather than loudly. Doctor looks for the ones that do:
+
+- **A second copy of `octane` in the tree.** Hooks and context are keyed per
+  runtime instance, so a duplicate breaks them without raising an error.
+- **`jsxImportSource` not set to `octane`**, or `@tsrx/typescript-plugin`
+  missing from `compilerOptions.plugins`.
+- **`tsc` instead of `tsrx-tsc`** in the typecheck script. Plain `tsc` cannot
+  read `.tsrx`.
+- **`declare module '*.tsrx'`** anywhere in your sources. It silences `.tsrx`
+  resolution instead of fixing it, so every import it covers becomes `any`,
+  including your own components.
+- **No Octane plugin in the bundler config**, or both the compiler plugin and
+  the metaframework plugin at once.
+- **Routes in `octane.config.ts` pointing at files that do not exist.**
+- **`forwardRef` imported from `octane`.** It does not exist; refs are plain
+  props.
+
+```bash
+octane doctor              # report
+octane doctor --fix        # repair the mechanical findings
+octane doctor --json       # for CI; exits 3 when an error-severity check fails
+```
+
+`--fix` only touches findings whose repair is unambiguous, and it edits files as
+text splices, so comments and formatting in your `tsconfig.json` survive.
+Anything else is reported with the exact remedy rather than guessed at.
+
+## `octane analyze`
+
+Where `doctor` checks how the project is wired, `analyze` checks the code. It
+compiles every `.tsrx` through the project's own `octane` and reports what the
+compiler found, so the results are exactly what a build would warn about, and
+new compiler diagnostics show up here without a CLI change.
+
+```bash
+octane analyze                              # every .tsrx in the project
+octane analyze src/App.tsrx                 # just these
+octane analyze --code OCTANE_HYDRATE_SPLIT_STYLE
+octane analyze --strict                     # warnings fail the run too
+```
+
+```
+src/Form.tsrx
+  ⚠ 12:43  `onChange` on <input type="text"> is a native commit event in Octane …
+      OCTANE_NATIVE_TEXT_ONCHANGE
+      suggestion: use `onInput` at 12:43
+```
+
+A file that will not parse is reported as an error and does not stop the rest of
+the run. Exit code is `3` when anything error-severity was found, or when
+`--strict` and there were warnings.
+
+## For agents and CI
+
+Every command is fully drivable by flags and emits a single JSON document under
+`--json`. Prompts only ever fill in *missing* input, and only in a real
+terminal: in a pipe or under `CI`, a missing answer is an error naming the flag
+that would have supplied it, never a hang.
+
+Exit codes: `0` success, `1` command failure, `2` usage error, `3` doctor found
+error-severity problems.
+
+## `octane mcp add`
+
+Registers `@octanejs/mcp-server` with whichever agents are installed. Where the
+client ships its own CLI (`claude`, `codex`) that CLI does the writing, since it
+owns its config schema; otherwise the config file is read, merged, backed up,
+and rewritten. Run inside an Octane checkout, it also sets `OCTANE_REPO_ROOT` so
+the maintainer tools register.
+
+```bash
+octane mcp add                      # pick from the agents it finds
+octane mcp add claude --scope project
+octane mcp status
+octane mcp remove cursor
+```
+
+## Adding a command
+
+`src/kernel/registry.js` is the command table. An entry carries the name, the
+one-line summary, and a lazy `load()`; the module it loads carries the flags,
+positionals, and `run`. Nothing is duplicated between them, help text is derived
+from the spec rather than written by hand, and only the command actually being
+run is ever imported.
+
+```js
+// src/kernel/registry.js
+{ name: 'lint', summary: 'Lint .tsrx sources.', load: () => import('../commands/lint.js') }
+```
+
+```js
+// src/commands/lint.js
+import { defineCommand } from '../kernel/command.js';
+
+export default defineCommand({
+	description: 'Lint .tsrx sources.',
+	flags: { strict: { type: 'boolean', description: 'Fail on warnings.' } },
+	async run(ctx, input) {
+		const project = ctx.project();
+		ctx.ui.log(`Linting ${project.tsrxFiles.length} file(s)`);
+		return { json: { files: project.tsrxFiles.length } };
+	},
+});
+```
+
+Commands write human output through `ctx.ui` and return their machine payload as
+`json`; the kernel prints whichever the caller asked for. Process access goes
+through `ctx.exec` so commands that shell out stay testable without spawning.
+A command that writes into the project sets `requiresProject: true`, and the
+kernel refuses to run it outside a `package.json` rather than letting it fail
+somewhere inside an `fs` call.
+
+Doctor checks follow the same pattern: add one to
+`src/commands/doctor/checks/<category>.js` with an `id`, a `severity`, a `run`,
+and, only when the repair is unambiguous, a `fix`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@octanejs/cli",
+  "version": "0.0.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "The Octane command line: diagnose, configure, and extend an Octane project.",
+  "license": "MIT",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "octane",
+    "cli",
+    "doctor",
+    "tsrx"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "octane": "src/bin/octane.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "test": "cd ../.. && vitest run --project cli"
+  }
+}

package/src/bin/octane.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../kernel/main.js';
+
+process.exitCode = await main(process.argv.slice(2));

package/src/commands/add.js

@@ -0,0 +1,138 @@
+import { defineCommand } from '../kernel/command.js';
+import { BINDINGS, resolveBinding, searchBindings } from '../data/index.js';
+import { EXIT, usageError } from '../kernel/errors.js';
+import { installCommand, installPackages } from '../kernel/install.js';
+
+/**
+ * @typedef {Object} Resolution
+ * @property {string} requested
+ * @property {import('../data/index.js').Binding | null} binding
+ * @property {'binding' | 'react-package'} [via]
+ * @property {string[]} suggestions
+ */
+
+/**
+ * @param {string} name
+ * @returns {Resolution}
+ */
+function resolve(name) {
+	const found = resolveBinding(name);
+	if (found) return { requested: name, binding: found.binding, via: found.via, suggestions: [] };
+
+	// Nothing ports this package. Offer the closest thing rather than a bare no.
+	const stem = name.replace(/^@[^/]+\//, '').replace(/^react-|-react$/g, '');
+	return {
+		requested: name,
+		binding: null,
+		suggestions: searchBindings(stem, { surface: false })
+			.slice(0, 3)
+			.map((binding) => binding.name),
+	};
+}
+
+export default defineCommand({
+	requiresProject: true,
+	description:
+		'Install an Octane binding, by its own name or by the React package it ports, and\n' +
+		'report the surface it supports and where it deliberately differs from upstream.',
+	positionals: [
+		{
+			name: 'package',
+			description: 'Binding or React package name.',
+			required: true,
+			variadic: true,
+		},
+	],
+	flags: {
+		install: {
+			type: 'boolean',
+			default: true,
+			description: 'Install (--no-install just reports).',
+		},
+		dev: { type: 'boolean', description: 'Install as a devDependency.' },
+	},
+
+	async run(ctx, input) {
+		if (input.positionals.length === 0) {
+			throw usageError('Nothing to add.', 'Try: octane add @tanstack/react-query');
+		}
+
+		const project = ctx.project();
+		const resolutions = input.positionals.map(resolve);
+		const found = resolutions.filter((entry) => entry.binding !== null);
+		const missing = resolutions.filter((entry) => entry.binding === null);
+
+		ctx.ui.intro('octane add');
+
+		for (const entry of missing) {
+			ctx.ui.log(
+				`  ${ctx.ui.colors.red('✖')} ${entry.requested} ${ctx.ui.colors.dim('has no Octane binding')}`,
+			);
+			if (entry.suggestions.length > 0) {
+				ctx.ui.log(`      ${ctx.ui.colors.dim(`closest: ${entry.suggestions.join(', ')}`)}`);
+			}
+		}
+
+		const names = [...new Set(found.map((entry) => /** @type {any} */ (entry.binding).name))];
+		const toInstall = names.filter((name) => !project.declaredDependencies[name]);
+
+		if (names.length > 0) {
+			const { manager, args } = installCommand(
+				project,
+				toInstall.length > 0 ? toInstall : names,
+				input.flags.dev,
+			);
+
+			if (ctx.dryRun || !input.flags.install) {
+				ctx.ui.note('Would run', [`${manager} ${args.join(' ')}`]);
+			} else if (toInstall.length === 0) {
+				ctx.ui.log(`  ${ctx.ui.colors.dim('Already declared; nothing to install.')}`);
+			} else {
+				const spinner = ctx.ui.spinner(`Installing ${toInstall.join(', ')}`);
+				const ran = await installPackages(ctx, project, toInstall, { dev: input.flags.dev });
+				spinner.stop(ran);
+			}
+		}
+
+		for (const entry of found) {
+			const binding = /** @type {import('../data/index.js').Binding} */ (entry.binding);
+			const heading =
+				entry.via === 'react-package'
+					? `${binding.name}  (ports ${entry.requested})`
+					: binding.name;
+
+			ctx.ui.note(heading, [
+				binding.surface,
+				...(binding.divergences.length > 0
+					? ['', 'Differs from upstream:', ...binding.divergences.map((line) => `  - ${line}`)]
+					: []),
+			]);
+		}
+
+		const ok = missing.length === 0;
+		ctx.ui.outro(
+			ok
+				? 'Run `octane doctor` to verify the result.'
+				: `Run \`octane bindings\` to browse all ${BINDINGS.length}.`,
+		);
+
+		return {
+			exitCode: ok ? EXIT.OK : EXIT.FAILURE,
+			json: {
+				ok,
+				installed: ctx.dryRun || !input.flags.install ? [] : toInstall,
+				resolved: found.map((entry) => ({
+					requested: entry.requested,
+					binding: /** @type {any} */ (entry.binding).name,
+					via: entry.via,
+					surface: /** @type {any} */ (entry.binding).surface,
+					divergences: /** @type {any} */ (entry.binding).divergences,
+				})),
+				unavailable: missing.map((entry) => ({
+					requested: entry.requested,
+					suggestions: entry.suggestions,
+				})),
+			},
+		};
+	},
+});

package/src/commands/analyze.js

@@ -0,0 +1,271 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { defineCommand } from '../kernel/command.js';
+import { CliError, EXIT } from '../kernel/errors.js';
+import { SYMBOLS } from '../kernel/ui.js';
+
+/**
+ * @typedef {Object} Finding
+ * @property {string} file relative to the project root
+ * @property {number} line
+ * @property {number} column 1-based, matching editor gutters
+ * @property {'error' | 'warning'} severity
+ * @property {string} code
+ * @property {string} message
+ * @property {string[]} suggestions
+ */
+
+/**
+ * Load the project's own compiler.
+ *
+ * The diagnostics belong to the compiler, and it is the compiler in the
+ * project's node_modules that decides what this project's code means. Shipping
+ * a second copy in the CLI would report on a different version than the one
+ * that builds the app.
+ *
+ * @param {string} root
+ * @returns {Promise<(source: string, filename: string, options?: object) => { diagnostics: readonly any[] }>}
+ */
+async function loadCompiler(root) {
+	const require = createRequire(path.join(root, 'noop.js'));
+	let entry;
+	try {
+		entry = require.resolve('octane/compiler');
+	} catch {
+		throw new CliError('Could not resolve `octane/compiler` from this project.', {
+			hint: 'Install the runtime first: pnpm add octane',
+		});
+	}
+	const module = await import(pathToFileURL(entry).href);
+	if (typeof module.compile !== 'function') {
+		throw new CliError('The installed octane build exposes no compiler.');
+	}
+	return module.compile;
+}
+
+/**
+ * Compiler suggestions are structured edits (a span plus the replacement), not
+ * prose. Describe the ones whose shape is known and drop the rest, so the report
+ * never prints `[object Object]`.
+ *
+ * @param {readonly any[] | undefined} suggestions
+ * @returns {string[]}
+ */
+function describeSuggestions(suggestions) {
+	const described = [];
+	for (const suggestion of suggestions ?? []) {
+		if (typeof suggestion === 'string') described.push(suggestion);
+		else if (typeof suggestion?.message === 'string') described.push(suggestion.message);
+		else if (typeof suggestion?.attribute === 'string') {
+			const at = suggestion.start
+				? ` at ${suggestion.start.line}:${suggestion.start.column + 1}`
+				: '';
+			described.push(`use \`${suggestion.attribute}\`${at}`);
+		}
+	}
+	return described;
+}
+
+/**
+ * Position appended by the compiler to a thrown message, e.g. `(App.tsrx:6:18)`.
+ * Semantic errors carry their location this way rather than on `loc`.
+ */
+const TRAILING_LOCATION = /\s*\(([^()\s]+):(\d+):(\d+)\)\s*$/;
+
+/**
+ * Normalise a thrown compile failure into a finding.
+ *
+ * Two shapes reach here. A genuine parse failure carries a Babel-style `loc`.
+ * A semantic failure (a slot-keyed hook in a plain JS loop, say) is thrown with
+ * its position appended to the message instead, so recovering it keeps the
+ * report pointing at the offending line rather than at 1:1.
+ *
+ * @param {unknown} error
+ * @param {string} file
+ * @param {string} [code] overrides the derived code, for a read failure
+ * @returns {Finding}
+ */
+function thrownFailure(error, file, code) {
+	const message = error instanceof Error ? error.message : String(error);
+	const loc = /** @type {any} */ (error)?.loc;
+	if (loc) {
+		return {
+			file,
+			line: loc.line ?? 1,
+			column: (loc.column ?? 0) + 1,
+			severity: 'error',
+			code: code ?? 'OCTANE_PARSE_ERROR',
+			message,
+			suggestions: [],
+		};
+	}
+
+	const trailing = TRAILING_LOCATION.exec(message);
+	return {
+		file,
+		line: trailing ? Number(trailing[2]) : 1,
+		column: trailing ? Number(trailing[3]) : 1,
+		severity: 'error',
+		// Not every throw is a parse failure; saying so sends people looking for
+		// a syntax mistake that is not there.
+		code: code ?? 'OCTANE_COMPILE_ERROR',
+		// The position now has its own columns, so drop the duplicate tail.
+		message: trailing ? message.slice(0, trailing.index) : message,
+		suggestions: [],
+	};
+}
+
+export default defineCommand({
+	description:
+		'Compile the project and report every diagnostic the Octane compiler raises:\n' +
+		'native-event mistakes, hydration hazards, renderer-boundary and client-only errors.',
+	positionals: [
+		{
+			name: 'path',
+			description: 'Files to analyze. Defaults to every .tsrx in the project.',
+			variadic: true,
+		},
+	],
+	flags: {
+		code: {
+			type: 'string',
+			repeatable: true,
+			placeholder: '<CODE>',
+			description: 'Only report this diagnostic code. Repeatable.',
+		},
+		strict: { type: 'boolean', description: 'Fail the run on warnings, not just errors.' },
+	},
+
+	async run(ctx, input) {
+		const project = ctx.project();
+		const compile = await loadCompiler(project.root);
+
+		const targets =
+			input.positionals.length > 0
+				? input.positionals.map((file) => path.resolve(ctx.cwd, file))
+				: project.tsrxFiles;
+
+		if (targets.length === 0) {
+			ctx.ui.intro('octane analyze');
+			ctx.ui.outro('No .tsrx files found.');
+			return { json: { ok: true, analyzed: 0, findings: [] } };
+		}
+
+		ctx.ui.intro('octane analyze');
+		const spinner = ctx.ui.spinner(`Compiling ${targets.length} file(s)`);
+
+		/** @type {Finding[]} */
+		const findings = [];
+		for (const absolute of targets) {
+			const file = displayPath(project.root, ctx.cwd, absolute);
+			let source;
+			try {
+				source = readFileSync(absolute, 'utf8');
+			} catch (error) {
+				// Unreadable is not unparseable; saying so sends people to the wrong fix.
+				findings.push(thrownFailure(error, file, 'OCTANE_READ_ERROR'));
+				continue;
+			}
+
+			try {
+				for (const diagnostic of compile(source, absolute, {}).diagnostics ?? []) {
+					findings.push({
+						file,
+						line: diagnostic.start?.line ?? 1,
+						column: (diagnostic.start?.column ?? 0) + 1,
+						severity: diagnostic.severity === 'error' ? 'error' : 'warning',
+						code: diagnostic.code,
+						// The compiler prefixes its own code; the report already has a
+						// column for it.
+						message: String(diagnostic.message).replace(`[${diagnostic.code}] `, ''),
+						suggestions: describeSuggestions(diagnostic.suggestions),
+					});
+				}
+			} catch (error) {
+				// A file that will not compile is the most severe thing analyze can
+				// find, and it must not stop the other files being reported.
+				findings.push(thrownFailure(error, file));
+			}
+		}
+		spinner.stop(`Compiled ${targets.length} file(s)`);
+
+		const selected = input.flags.code?.length
+			? findings.filter((finding) => input.flags.code.includes(finding.code))
+			: findings;
+
+		render(ctx, selected, targets.length);
+
+		const errors = selected.filter((finding) => finding.severity === 'error').length;
+		const warnings = selected.length - errors;
+		const failed = errors > 0 || (input.flags.strict && warnings > 0);
+
+		return {
+			exitCode: failed ? EXIT.DIAGNOSTIC : EXIT.OK,
+			json: {
+				ok: !failed,
+				analyzed: targets.length,
+				summary: { errors, warnings },
+				findings: selected,
+			},
+		};
+	},
+});
+
+/**
+ * Project-relative where that is meaningful, otherwise relative to the invoking
+ * directory, otherwise absolute. An explicit path outside the project would
+ * otherwise render as a wall of `../`.
+ *
+ * @param {string} root
+ * @param {string} cwd
+ * @param {string} absolute
+ * @returns {string}
+ */
+function displayPath(root, cwd, absolute) {
+	const fromRoot = path.relative(root, absolute);
+	if (!fromRoot.startsWith('..')) return fromRoot;
+	const fromCwd = path.relative(cwd, absolute);
+	return fromCwd.startsWith('..') ? absolute : fromCwd;
+}
+
+/**
+ * @param {import('../kernel/context.js').Ctx} ctx
+ * @param {Finding[]} findings
+ * @param {number} analyzed
+ */
+function render(ctx, findings, analyzed) {
+	const { colors } = ctx.ui;
+
+	if (findings.length === 0) {
+		ctx.ui.outro(colors.green(`No diagnostics across ${analyzed} file(s).`));
+		return;
+	}
+
+	for (const file of [...new Set(findings.map((finding) => finding.file))]) {
+		ctx.ui.log('');
+		ctx.ui.log(colors.bold(file));
+
+		for (const finding of findings.filter((entry) => entry.file === file)) {
+			const mark =
+				finding.severity === 'error' ? colors.red(SYMBOLS.fail) : colors.yellow(SYMBOLS.warn);
+			const where = colors.dim(`${finding.line}:${finding.column}`);
+			ctx.ui.log(`  ${mark} ${where}  ${finding.message}`);
+			ctx.ui.log(`      ${colors.dim(finding.code)}`);
+			for (const suggestion of finding.suggestions) {
+				ctx.ui.log(`      ${colors.dim(`suggestion: ${suggestion}`)}`);
+			}
+		}
+	}
+
+	const errors = findings.filter((finding) => finding.severity === 'error').length;
+	const warnings = findings.length - errors;
+	/** @type {string[]} */
+	const parts = [];
+	if (errors > 0) parts.push(colors.red(`${errors} error${errors === 1 ? '' : 's'}`));
+	if (warnings > 0) parts.push(colors.yellow(`${warnings} warning${warnings === 1 ? '' : 's'}`));
+
+	ctx.ui.log('');
+	ctx.ui.log(`${parts.join(colors.dim(' · '))} ${colors.dim(`across ${analyzed} file(s)`)}`);
+}

package/src/commands/bindings.js

@@ -0,0 +1,55 @@
+import { defineCommand } from '../kernel/command.js';
+import { BINDINGS, searchBindings } from '../data/index.js';
+
+export default defineCommand({
+	description: 'List the @octanejs/* bindings, what they port, and how they differ from upstream.',
+	positionals: [
+		{ name: 'query', description: 'Filter by binding name, upstream package, or category.' },
+	],
+	flags: {
+		divergences: { type: 'boolean', description: "Include each binding's known divergences." },
+	},
+
+	async run(ctx, input) {
+		const query = input.positionals.join(' ');
+		const matches = query ? searchBindings(query) : BINDINGS;
+
+		ctx.ui.intro(query ? `octane bindings: ${query}` : 'octane bindings');
+
+		if (matches.length === 0) {
+			ctx.ui.outro(
+				`Nothing matches "${query}". Run \`octane bindings\` to see all ${BINDINGS.length}.`,
+			);
+			return { json: { query, bindings: [] } };
+		}
+
+		const width = matches.reduce((max, binding) => Math.max(max, binding.name.length), 0);
+
+		for (const category of [...new Set(matches.map((binding) => binding.category))]) {
+			ctx.ui.log('');
+			ctx.ui.log(ctx.ui.colors.bold(category));
+
+			for (const binding of matches.filter((entry) => entry.category === category)) {
+				const upstream = binding.upstream
+					? `${binding.upstream.package}@${binding.upstream.version}`
+					: 'no React upstream';
+				ctx.ui.log(`  ${binding.name.padEnd(width)}  ${ctx.ui.colors.dim(upstream)}`);
+
+				if (input.flags.divergences) {
+					for (const divergence of binding.divergences) {
+						ctx.ui.log(
+							`      ${ctx.ui.colors.yellow('diverges:')} ${ctx.ui.colors.dim(divergence)}`,
+						);
+					}
+				}
+			}
+		}
+
+		ctx.ui.log('');
+		ctx.ui.outro(
+			`${matches.length} of ${BINDINGS.length} binding(s). \`octane add <package>\` installs one.`,
+		);
+
+		return { json: { query: query || null, bindings: matches } };
+	},
+});