@octanejs/mcp-server 0.2.1 → 0.2.3

package/README.md

@@ -72,8 +72,10 @@ exists, an overall verdict (`bridgeable`, `bridgeable-with-rewrites`,
 
 ### `octane_bindings`
 
-Returns the map of React packages with maintained `@octanejs/*` ports
-(zustand, query, motion, stylex, router, lexical, floating-ui, radix).
+Returns the map of React packages with maintained `@octanejs/*` ports. The map
+lives in `src/bridge.js` (`KNOWN_BINDINGS`), and its tests derive the complete
+binding package set from the workspace manifests, so adding a published binding
+without registering its React-package mapping fails CI.
 
 ### `octane_skill`
 

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@octanejs/mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "description": "MCP server exposing Octane repository automation for coding agents.",
   "license": "MIT",
   "author": {

package/skills/bridge-react-package.md

@@ -10,13 +10,20 @@ of bridging by hand:
 | React package | Octane binding |
 | --- | --- |
 | `zustand` | `@octanejs/zustand` |
-| `@tanstack/react-query` | `@octanejs/query` |
+| `jotai` | `@octanejs/jotai` |
+| `@apollo/client` | `@octanejs/apollo-client` |
+| `@tanstack/react-query` | `@octanejs/tanstack-query` |
+| `@tanstack/react-router` | `@octanejs/tanstack-router` |
+| `@tanstack/react-table` | `@octanejs/tanstack-table` |
+| `@tanstack/react-virtual` | `@octanejs/tanstack-virtual` |
 | `framer-motion` / `motion` | `@octanejs/motion` |
 | `@stylexjs/stylex` | `@octanejs/stylex` |
-| `react-router` / `react-router-dom` | `@octanejs/router` |
+| `react-router` / `react-router-dom` | `@octanejs/remix-router` |
 | `@lexical/react` | `@octanejs/lexical` |
+| `lucide-react` | `@octanejs/lucide` |
 | `@floating-ui/react` | `@octanejs/floating-ui` |
 | `radix-ui` | `@octanejs/radix` |
+| `react-i18next` | `@octanejs/i18next` |
 
 For anything else, run the `octane_bridge_react_package` tool to get a scan of the
 package's React API usage and a tailored plan, then follow the workflow below.

package/src/bridge.js

@@ -1,28 +1,57 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 
+// React package → maintained @octanejs binding. bridge.test.js derives the
+// expected value set from the workspace manifests, so publishing a new binding
+// without registering it here fails the mcp-server tests.
 export const KNOWN_BINDINGS = {
 	zustand: '@octanejs/zustand',
-	'@tanstack/react-query': '@octanejs/query',
+	jotai: '@octanejs/jotai',
+	'@apollo/client': '@octanejs/apollo-client',
+	'@tanstack/react-query': '@octanejs/tanstack-query',
+	'@tanstack/react-router': '@octanejs/tanstack-router',
+	'@tanstack/react-table': '@octanejs/tanstack-table',
+	'@tanstack/react-virtual': '@octanejs/tanstack-virtual',
 	'framer-motion': '@octanejs/motion',
 	motion: '@octanejs/motion',
 	'@stylexjs/stylex': '@octanejs/stylex',
-	'react-router': '@octanejs/router',
-	'react-router-dom': '@octanejs/router',
+	'react-router': '@octanejs/remix-router',
+	'react-router-dom': '@octanejs/remix-router',
 	'@lexical/react': '@octanejs/lexical',
+	'lucide-react': '@octanejs/lucide',
 	'@floating-ui/react': '@octanejs/floating-ui',
 	'radix-ui': '@octanejs/radix',
+	'react-hook-form': '@octanejs/hook-form',
+	'@base-ui-components/react': '@octanejs/base-ui',
+	'@dnd-kit/react': '@octanejs/dnd-kit',
+	sonner: '@octanejs/sonner',
+	recharts: '@octanejs/recharts',
+	'react-redux': '@octanejs/redux',
+	'@reduxjs/toolkit': '@octanejs/redux-toolkit',
+	'@testing-library/react': '@octanejs/testing-library',
+	'react-i18next': '@octanejs/i18next',
+	'@mdx-js/react': '@octanejs/mdx',
 };
 
+// Workspace directory names for the maintained bindings. Keep this derived
+// from KNOWN_BINDINGS so repository path routing cannot drift from the public
+// binding list (aliases such as `motion` intentionally collapse to one dir).
+export const KNOWN_BINDING_PACKAGE_DIRS = new Set(
+	Object.values(KNOWN_BINDINGS).map((name) => name.slice('@octanejs/'.length)),
+);
+
 export const KNOWN_VANILLA_CORES = {
+	'@apollo/client': '@apollo/client',
 	'@tanstack/react-query': '@tanstack/query-core',
 	'@tanstack/react-table': '@tanstack/table-core',
 	'@tanstack/react-virtual': '@tanstack/virtual-core',
 	'@tanstack/react-form': '@tanstack/form-core',
 	'@floating-ui/react': '@floating-ui/dom',
+	'@dnd-kit/react': '@dnd-kit/dom',
 	'@xstate/react': 'xstate',
 	'react-redux': 'redux',
 	'@reduxjs/toolkit': 'redux',
+	'react-i18next': 'i18next',
 	'react-hook-form': null,
 	zustand: 'zustand/vanilla',
 	valtio: 'valtio/vanilla',
@@ -33,9 +62,12 @@ export const KNOWN_VANILLA_CORES = {
 export const REACT_API_MAP = {
 	useState: {
 		status: 'same',
-		note: 'Identical, including lazy initializer and functional updates.',
+		note: 'Same lazy initializer and functional-update semantics; Octane additionally exposes a stable current-state getter at tuple index 2.',
+	},
+	useReducer: {
+		status: 'same',
+		note: 'Same reducer and lazy-init semantics; Octane additionally exposes a stable current-state getter at tuple index 2.',
 	},
-	useReducer: { status: 'same', note: 'Identical, including lazy init third argument.' },
 	useEffect: { status: 'same', note: 'Identical deps/cleanup semantics.' },
 	useLayoutEffect: { status: 'same', note: 'Identical: synchronous after DOM mutation.' },
 	useInsertionEffect: { status: 'same', note: 'Supported.' },

package/src/bridge.test.js

@@ -1,8 +1,15 @@
 import { describe, expect, it } from 'vitest';
-import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { bridgeReport, detectVanillaCore, scanSource, KNOWN_BINDINGS } from './bridge.js';
+import {
+	bridgeReport,
+	detectVanillaCore,
+	scanSource,
+	KNOWN_BINDINGS,
+	KNOWN_BINDING_PACKAGE_DIRS,
+} from './bridge.js';
 
 describe('scanSource', () => {
 	it('collects React API usage counts and import specifiers', () => {
@@ -33,6 +40,7 @@ describe('scanSource', () => {
 
 describe('detectVanillaCore', () => {
 	it('prefers the known-core table', () => {
+		expect(detectVanillaCore('@apollo/client', {})).toBe('@apollo/client');
 		expect(detectVanillaCore('@tanstack/react-query', {})).toBe('@tanstack/query-core');
 		expect(detectVanillaCore('zustand', {})).toBe('zustand/vanilla');
 	});
@@ -137,18 +145,40 @@ describe('bridgeReport', () => {
 });
 
 describe('KNOWN_BINDINGS', () => {
-	it('covers every published @octanejs binding', () => {
-		expect(new Set(Object.values(KNOWN_BINDINGS))).toEqual(
-			new Set([
-				'@octanejs/zustand',
-				'@octanejs/query',
-				'@octanejs/motion',
-				'@octanejs/stylex',
-				'@octanejs/router',
-				'@octanejs/lexical',
-				'@octanejs/floating-ui',
-				'@octanejs/radix',
-			]),
-		);
+	it('covers every published @octanejs binding (derived from workspace manifests)', async () => {
+		// The expected set is DERIVED from packages/*/package.json rather than
+		// hand-maintained, so publishing a new binding without registering it in
+		// KNOWN_BINDINGS fails here. Only genuinely-not-a-binding packages (the
+		// core runtime, build/deploy infrastructure, this MCP server) are
+		// excluded by name.
+		const NON_BINDINGS = new Set([
+			'octane',
+			'@octanejs/app-core',
+			'@octanejs/rspack-plugin',
+			'@octanejs/rsbuild-plugin',
+			'@octanejs/vite-plugin',
+			'@octanejs/adapter-vercel',
+			'@octanejs/mcp-server',
+		]);
+		const packagesRoot = fileURLToPath(new URL('../..', import.meta.url));
+		const bindings = [];
+		const bindingDirectories = [];
+		for (const entry of await readdir(packagesRoot, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			let manifest;
+			try {
+				manifest = JSON.parse(
+					await readFile(join(packagesRoot, entry.name, 'package.json'), 'utf8'),
+				);
+			} catch {
+				continue; // not a package dir
+			}
+			if (manifest.private || NON_BINDINGS.has(manifest.name)) continue;
+			bindings.push(manifest.name);
+			bindingDirectories.push(entry.name);
+		}
+		expect(bindings.length).toBeGreaterThan(0);
+		expect(new Set(Object.values(KNOWN_BINDINGS))).toEqual(new Set(bindings));
+		expect(KNOWN_BINDING_PACKAGE_DIRS).toEqual(new Set(bindingDirectories));
 	});
 });

package/src/index.js

@@ -7,7 +7,7 @@ import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { bridgeReport, KNOWN_BINDINGS } from './bridge.js';
+import { bridgeReport, KNOWN_BINDINGS, KNOWN_BINDING_PACKAGE_DIRS } from './bridge.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = resolve(dirname(__filename), '..');
@@ -59,9 +59,13 @@ export function areaForPath(path) {
 		return 'core-runtime';
 	}
 	if (path.startsWith('packages/octane/tests/')) return 'core-tests';
+	if (path.startsWith('packages/app-core/')) return 'metaframework-core';
+	if (path.startsWith('packages/rspack-plugin-octane/')) return 'rspack-plugin';
+	if (path.startsWith('packages/rsbuild-plugin-octane/')) return 'rsbuild-plugin';
 	if (path.startsWith('packages/vite-plugin-octane/')) return 'vite-plugin';
 	if (path.startsWith('packages/octane-mcp-server/')) return 'mcp-server';
-	if (/^packages\/(zustand|query|motion|stylex|router|lexical|floating-ui|radix)\//.test(path)) {
+	const packageMatch = path.match(/^packages\/([^/]+)\//);
+	if (packageMatch && KNOWN_BINDING_PACKAGE_DIRS.has(packageMatch[1])) {
 		return 'ecosystem-binding';
 	}
 	if (path.startsWith('benchmarks/')) return 'benchmark';
@@ -88,13 +92,12 @@ export function validationFor(paths, taskKind) {
 	}
 	if (areas.has('ecosystem-binding')) {
 		for (const path of paths) {
-			const match = path.match(
-				/^packages\/(zustand|query|motion|stylex|router|lexical|floating-ui|radix)\//,
-			);
-			if (match)
+			const match = path.match(/^packages\/([^/]+)\//);
+			if (match && KNOWN_BINDING_PACKAGE_DIRS.has(match[1])) {
 				commands.add(
 					`./node_modules/.bin/vitest run packages/${match[1]}/tests --project ${match[1]}`,
 				);
+			}
 		}
 	}
 	if (areas.has('mcp-server')) {
@@ -102,7 +105,14 @@ export function validationFor(paths, taskKind) {
 			'./node_modules/.bin/vitest run packages/octane-mcp-server --project octane-mcp-server',
 		);
 	}
-	if (areas.has('vite-plugin')) commands.add('pnpm typecheck');
+	if (
+		areas.has('metaframework-core') ||
+		areas.has('rspack-plugin') ||
+		areas.has('rsbuild-plugin') ||
+		areas.has('vite-plugin')
+	) {
+		commands.add('pnpm typecheck');
+	}
 	if (areas.has('benchmark') || taskKind === 'performance') commands.add('pnpm bench');
 	if (taskKind === 'api' || taskKind === 'core' || taskKind === 'package')
 		commands.add('pnpm typecheck');

package/src/index.test.js

@@ -11,6 +11,7 @@ import {
 	scaffoldReactPort,
 	validationFor,
 } from './index.js';
+import { KNOWN_BINDING_PACKAGE_DIRS } from './bridge.js';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -26,6 +27,20 @@ describe('@octanejs/mcp-server helpers', () => {
 		expect(areaForPath('.rulesync/rules/project.md')).toBe('rulesync-source');
 	});
 
+	it('classifies every maintained binding and recommends its test project', () => {
+		const paths = [...KNOWN_BINDING_PACKAGE_DIRS].map(
+			(directory) => `packages/${directory}/src/index.ts`,
+		);
+		const commands = validationFor(paths, 'binding');
+
+		for (const directory of KNOWN_BINDING_PACKAGE_DIRS) {
+			expect(areaForPath(`packages/${directory}/src/index.ts`)).toBe('ecosystem-binding');
+			expect(commands).toContain(
+				`./node_modules/.bin/vitest run packages/${directory}/tests --project ${directory}`,
+			);
+		}
+	});
+
 	it('recommends validation commands from changed paths', () => {
 		const commands = validationFor(
 			[