@octanejs/mcp-server 0.2.6 → 0.2.9

package/README.md

@@ -57,11 +57,12 @@ maintainer tools):
 
 ## Tools (always available)
 
-The server initialization instructions direct coding agents to call
-`octane_engineering_plan` and load `build-octane-software` before creating or
-materially changing Octane code. This makes the correctness, performance
-evidence, adversarial self-review, and handoff requirements available even when
-the host does not automatically discover skills.
+The server initialization instructions are one orienting sentence plus a pointer
+to `octane_engineering_plan`, because they are injected into every session
+whether or not it touches Octane. The correctness, performance-evidence,
+self-review, and handoff requirements live in that tool response, so they stay
+reachable even on hosts that do not discover skills. Each tool description says
+when to call it.
 
 ### `octane_engineering_plan`
 
@@ -112,24 +113,30 @@ without registering its React-package mapping fails CI.
 
 Returns a skill by name. Bundled skills (shipped with this package):
 
-- `bridge-react-package` — the full workflow for porting a React library.
-- `build-octane-software` — production engineering, performance, validation,
+- `bridge-react-package`: the full workflow for porting a React library.
+- `build-octane-software`: production engineering, performance, validation,
   and adversarial self-review gates for Octane code.
-- `migrate-react-component` — React JSX to `.tsrx` conversion reference.
-- `react-divergences` — Octane's intentional differences from React.
-- `setup-ssr` — server rendering and hydration setup.
+- `migrate-react-component`: React JSX to `.tsrx` conversion reference.
+- `react-divergences`: Octane's intentional differences from React.
+- `setup-ssr`: server rendering and hydration setup.
 
-When running inside the octane monorepo, the maintainer skills from
-`.ai/skills` are also available: `react-library-port`, `bug-hunter`,
+When running inside the octane monorepo, the skills from `.rulesync/skills` are
+also available: `authoring-tsrx`, `react-library-port`, `bug-hunter`,
 `create-a-pr`, `handle-issue`, `octane-core-extend`, `triage`,
-`performance-audit`.
+`performance-audit`. A test compares this map against the directory in both
+directions, so a new skill cannot stay unreachable here. This tool reads the RuleSync source, and
+`pnpm rules:generate` writes the per-agent copies (`.claude/skills/`,
+`.github/skills/`, `.cursor/skills/`, `.gemini/skills/`) from the same text, so
+hosts that discover skills natively and hosts that call this tool see the same
+thing.
 
 ## Tools (octane monorepo only)
 
 ### `octane_project_map`
 
-Returns `.ai/project-map.md` with package layout, authoritative sources,
-invariants, and validation commands.
+Returns `AGENTS.md`: the RuleSync-generated root rule, covering what Octane is,
+which source owns which behavior, the intentional divergences from React, and the
+validation commands. CI fails if it drifts from its source in `.rulesync/rules/`.
 
 ### `octane_triage_paths`
 
@@ -152,11 +159,14 @@ optionally writes the generated Vitest skeleton to an output file.
 
 Runs benchmark suites through the unified runner (`node benchmarks/bench.mjs`):
 one manifest suite by name (`js-framework`, `todomvc`, `weather-app`,
-`weather-app-lighthouse`, `chat-stream`, `dbmon`, `news`, `react-hosted-islands`,
-`ssr-throughput`, `streaming-ssr`,
-`codegen-size`, `bundle-size`, `three-renderer`, `three-bundle-size`, …) or every
-suite with `all`; `quick` selects the reduced-iteration smoke pass. The suite
-list mirrors the runner manifest and `node benchmarks/bench.mjs --list`.
+`hydration-interactivity`, `hydration-stress`, `lifecycle-memory`,
+`controlled-form`, `external-store-fanout`, `external-store-integrations`,
+`scheduler-responsiveness`, `suspense-recovery`, `event-delegation`,
+`application-composition`, `scaling-curves`, `streaming-ssr`,
+`streaming-backpressure`, `compiler-throughput`, `codegen-size`,
+`bundle-size`, `three-renderer`, `three-bundle-size`, …) or every suite with
+`all`; `quick` selects the reduced-iteration smoke pass. The suite list mirrors
+the runner manifest and `node benchmarks/bench.mjs --list`.
 
 ### `octane_issue_context`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/mcp-server",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -36,7 +36,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "start": "node src/index.js",

package/skills/migrate-react-component.md

@@ -38,7 +38,7 @@ locals, early returns) stays above it.
 | `items.map(x => <li key={x.id}>...` | `@for (const x of items; key x.id) { <li>... }` with optional `@empty { }` |
 | `cond ? <A/> : <B/>` in JSX | `@if (cond) { <A/> } @else { <B/> }` |
 | `{cond && <A/>}` | `@if (cond) { <A/> }` |
-| switch on a value | `@switch (v) { @case (a) { } @default { } }` |
+| switch on a value | `@switch (v) { @case a: { } @default: { } }` |
 | `<Suspense fallback={...}>` | `<Suspense>` or `@try { } @pending { }` |
 | Error boundary class | `<ErrorBoundary>` or `@try { } @catch (e) { }` |
 | `forwardRef((props, ref) => ...)` | plain function; `ref` arrives as a prop |

package/src/bridge.js

@@ -1,11 +1,13 @@
 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.
+// React package → maintained @octanejs binding. Bindings with no React-package
+// equivalent live in KNOWN_NATIVE_BINDINGS below. bridge.test.js derives the
+// expected union from the workspace manifests, so publishing a new binding
+// without registering it in either catalog fails the mcp-server tests.
 export const KNOWN_BINDINGS = {
 	zustand: '@octanejs/zustand',
+	valtio: '@octanejs/valtio',
 	jotai: '@octanejs/jotai',
 	'@apollo/client': '@octanejs/apollo-client',
 	'@tanstack/ai-react': '@octanejs/tanstack-ai',
@@ -14,6 +16,9 @@ export const KNOWN_BINDINGS = {
 	'@tanstack/react-query': '@octanejs/tanstack-query',
 	'@tanstack/react-router': '@octanejs/tanstack-router',
 	'@tanstack/react-store': '@octanejs/tanstack-store',
+	'@tanstack/react-router-ssr-query': '@octanejs/tanstack-router-ssr-query',
+	'@tanstack/react-hotkeys': '@octanejs/tanstack-hotkeys',
+	'@tanstack/react-pacer': '@octanejs/tanstack-pacer',
 	'@tanstack/react-table': '@octanejs/tanstack-table',
 	'@tanstack/react-virtual': '@octanejs/tanstack-virtual',
 	'framer-motion': '@octanejs/motion',
@@ -23,6 +28,7 @@ export const KNOWN_BINDINGS = {
 	'react-router': '@octanejs/remix-router',
 	'react-router-dom': '@octanejs/remix-router',
 	nuqs: '@octanejs/nuqs',
+	cmdk: '@octanejs/cmdk',
 	'@lexical/react': '@octanejs/lexical',
 	'@tiptap/react': '@octanejs/tiptap',
 	'lucide-react': '@octanejs/lucide',
@@ -35,6 +41,7 @@ export const KNOWN_BINDINGS = {
 	'@base-ui-components/react': '@octanejs/base-ui',
 	'@dnd-kit/react': '@octanejs/dnd-kit',
 	sonner: '@octanejs/sonner',
+	shadcn: '@octanejs/shadcn',
 	recharts: '@octanejs/recharts',
 	'@react-three/fiber': '@octanejs/three',
 	'@visx/visx': '@octanejs/visx',
@@ -94,11 +101,18 @@ export const KNOWN_BINDINGS = {
 	'dexie-react-hooks': '@octanejs/dexie',
 };
 
+// Octane-specific ecosystem packages that have no React import to rewrite.
+// Keep these out of KNOWN_BINDINGS so the React bridge never invents a source
+// package mapping for native tooling.
+export const KNOWN_NATIVE_BINDINGS = new Set(['@octanejs/devtools', '@octanejs/tauri']);
+
 // Workspace directory names for the maintained bindings. Keep this derived
-// from KNOWN_BINDINGS so repository path routing cannot drift from the public
+// from both catalogs 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)),
+	[...Object.values(KNOWN_BINDINGS), ...KNOWN_NATIVE_BINDINGS].map((name) =>
+		name.slice('@octanejs/'.length),
+	),
 );
 
 export const KNOWN_VANILLA_CORES = {

package/src/bridge.test.js

@@ -10,6 +10,7 @@ import {
 	detectVanillaCore,
 	scanSource,
 	KNOWN_BINDINGS,
+	KNOWN_NATIVE_BINDINGS,
 	KNOWN_BINDING_PACKAGE_DIRS,
 } from './bridge.js';
 
@@ -267,7 +268,7 @@ describe('KNOWN_BINDINGS', () => {
 		// metaframeworks and infrastructure cannot drift into the binding catalog.
 		const bindings = getBindingPackages();
 		expect(bindings.length).toBeGreaterThan(0);
-		expect(new Set(Object.values(KNOWN_BINDINGS))).toEqual(
+		expect(new Set([...Object.values(KNOWN_BINDINGS), ...KNOWN_NATIVE_BINDINGS])).toEqual(
 			new Set(bindings.map(({ name }) => name)),
 		);
 		expect(KNOWN_BINDING_PACKAGE_DIRS).toEqual(new Set(bindings.map(({ dir }) => dir)));

package/src/index.js

@@ -13,9 +13,10 @@ const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = resolve(dirname(__filename), '..');
 
 // Bundled skills ship with the npm package and work in ANY project using
-// octane. Repo skills live in the octane monorepo's .ai/skills and are only
-// available when the server runs against a checkout (they cover maintainer
-// workflows: triage, PRs, core changes).
+// octane. Repo skills are read from the RuleSync source, not a generated copy,
+// so this server and every per-agent output (.claude/skills, .github/skills,
+// …) serve the same text. They cover maintainer workflows: triage, PRs, core
+// changes, and are only available when the server runs against a checkout.
 export const BUNDLED_SKILLS = {
 	'bridge-react-package': 'skills/bridge-react-package.md',
 	'build-octane-software': 'skills/build-octane-software.md',
@@ -25,13 +26,14 @@ export const BUNDLED_SKILLS = {
 };
 
 export const REPO_SKILLS = {
-	'bug-hunter': '.ai/skills/bug-hunter.md',
-	'create-a-pr': '.ai/skills/create-a-pr.md',
-	'handle-issue': '.ai/skills/handle-issue.md',
-	'octane-core-extend': '.ai/skills/octane-core-extend.md',
-	'performance-audit': '.ai/skills/performance-audit.md',
-	'react-library-port': '.ai/skills/react-library-port.md',
-	triage: '.ai/skills/triage.md',
+	'authoring-tsrx': '.rulesync/skills/authoring-tsrx/SKILL.md',
+	'bug-hunter': '.rulesync/skills/bug-hunter/SKILL.md',
+	'create-a-pr': '.rulesync/skills/create-a-pr/SKILL.md',
+	'handle-issue': '.rulesync/skills/handle-issue/SKILL.md',
+	'octane-core-extend': '.rulesync/skills/octane-core-extend/SKILL.md',
+	'performance-audit': '.rulesync/skills/performance-audit/SKILL.md',
+	'react-library-port': '.rulesync/skills/react-library-port/SKILL.md',
+	triage: '.rulesync/skills/triage/SKILL.md',
 };
 
 // Suite names from the unified runner manifest (`SUITES` in
@@ -48,13 +50,27 @@ export const BENCHMARK_SUITES = [
 	'recursive-context',
 	'signal-favoring',
 	'news',
+	'hydration-interactivity',
+	'hydration-stress',
+	'lifecycle-memory',
+	'controlled-form',
+	'external-store-fanout',
+	'external-store-integrations',
+	'scheduler-responsiveness',
+	'suspense-recovery',
+	'event-delegation',
+	'application-composition',
+	'scaling-curves',
+	'store-selector-fanout',
 	'effectful-list',
+	'list-clear',
 	'memo-wall',
 	'portal-swarm',
 	'react-hosted-islands',
 	'ssr-throughput',
 	'streaming-ssr',
 	'ssr-http',
+	'streaming-backpressure',
 	'ssr-workerd',
 	'tanstack-start',
 	'dbmon-deopt',
@@ -62,7 +78,10 @@ export const BENCHMARK_SUITES = [
 	'async-waterfall',
 	'async-composition',
 	'lynx-list',
+	'lynx-render',
+	'lynx-bundle-size',
 	'codegen-size',
+	'compiler-throughput',
 	'bundle-size',
 	'three-renderer',
 	'three-bundle-size',
@@ -71,10 +90,15 @@ export const BENCHMARK_SUITES = [
 const DEFAULT_TIMEOUT_MS = 120_000;
 
 export function instructionsFor(repoMode) {
+	// This text is injected into every session of every connected agent, whether
+	// or not it touches Octane, so it stays one orienting sentence plus one
+	// pointer. The gates themselves live in octane_engineering_plan, and each
+	// tool's own description says when to call it: that is where a model looks
+	// when it is actually deciding.
 	const common =
-		'Before creating or materially changing Octane software, call octane_engineering_plan and load the build-octane-software skill. Treat its correctness, performance evidence, and adversarial self-review gates as required. Load the task-specific migration, binding, divergence, or SSR skill in addition when relevant. Do not claim a performance improvement without comparable measurements.';
+		"Octane is a compiler-first UI framework with React's programming model, so React habits are the main source of wrong changes here. Before creating or materially changing Octane code, call octane_engineering_plan: it returns the gates that apply and names the skills to load.";
 	return repoMode
-		? `${common} For Octane framework-fundamental work, also load octane-core-extend and performance-audit, establish a relevant baseline before editing, and use octane_validate_plan for the final changed paths.`
+		? `${common} Inside this monorepo checkout it also returns the repository validation commands for the paths you changed.`
 		: common;
 }
 
@@ -108,7 +132,7 @@ export function areaForPath(path) {
 	if (path.startsWith('benchmarks/')) return 'benchmark';
 	if (path.startsWith('website/')) return 'website';
 	if (path.startsWith('.rulesync/')) return 'rulesync-source';
-	if (path.startsWith('.ai/') || path.startsWith('.codex/') || path.startsWith('.claude/')) {
+	if (path.startsWith('.codex/') || path.startsWith('.claude/')) {
 		return 'agent-instructions';
 	}
 	if (path.startsWith('docs/') || path.endsWith('.md')) return 'docs';
@@ -390,7 +414,7 @@ function registerUserTools(server, repoRoot, repoMode) {
 		{
 			title: 'Octane skill',
 			description:
-				'Return an Octane agent skill by name. Load build-octane-software before creating or materially changing Octane code; other bundled skills cover React package bridges, component migration, intentional divergences, and SSR setup.' +
+				'Fetch an Octane agent skill by name. Call when starting work the skill covers: build-octane-software for engineering gates, bridge-react-package for porting a React library, migrate-react-component for JSX to .tsrx, react-divergences before assuming React behavior, setup-ssr for server rendering.' +
 				(repoMode ? ' Repo skills cover octane maintainer workflows.' : ''),
 			inputSchema: {
 				name: z.enum(Object.keys(skills)),
@@ -476,12 +500,19 @@ function registerRepoTools(server, repoRoot) {
 		{
 			title: 'Octane project map',
 			description:
-				'Return Octane repository map, source ownership, validation commands, and skill paths.',
+				'Call when you need Octane repo orientation: what the framework is, which source owns which behavior, the intentional divergences from React, the validation commands, and the full package inventory.',
 			inputSchema: {},
 		},
 		async () => {
-			const projectMap = await readFile(resolve(repoRoot, '.ai/project-map.md'), 'utf8');
-			return text(projectMap);
+			// Composed from the two generated sources rather than a hand-written
+			// summary, because both are CI-gated: AGENTS.md against .rulesync/rules,
+			// and packages.md against the workspace manifests. A third restatement
+			// would be the one free to drift.
+			const [rootRule, packages] = await Promise.all([
+				readFile(resolve(repoRoot, 'AGENTS.md'), 'utf8'),
+				readFile(resolve(repoRoot, 'docs/packages.md'), 'utf8'),
+			]);
+			return text(`${rootRule.trimEnd()}\n\n---\n\n${packages.trimStart()}`);
 		},
 	);
 
@@ -489,7 +520,8 @@ function registerRepoTools(server, repoRoot) {
 		'octane_triage_paths',
 		{
 			title: 'Triage Octane paths',
-			description: 'Classify changed paths by Octane repo area.',
+			description:
+				'Call before editing unfamiliar paths in this monorepo to learn which area owns them.',
 			inputSchema: {
 				paths: z.array(z.string()).describe('Repository-relative paths'),
 			},
@@ -504,7 +536,8 @@ function registerRepoTools(server, repoRoot) {
 		'octane_validate_plan',
 		{
 			title: 'Octane validation plan',
-			description: 'Recommend validation commands for changed paths and task kind.',
+			description:
+				'Call when a change is finished to get the validation commands that cover the paths you touched.',
 			inputSchema: {
 				paths: z.array(z.string()).default([]).describe('Repository-relative changed paths'),
 				taskKind: z
@@ -534,7 +567,8 @@ function registerRepoTools(server, repoRoot) {
 		'octane_scaffold_react_port',
 		{
 			title: 'Scaffold React test port',
-			description: 'Run scripts/scaffold-react-port.mjs for a React upstream test file.',
+			description:
+				'Call when porting a React test file into the conformance suite, returns a triage skeleton of in-scope cases and out-of-scope reasons.',
 			inputSchema: {
 				reactTestFile: z
 					.string()

package/src/index.test.js

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -10,6 +10,7 @@ import {
 	areaForPath,
 	BENCHMARK_SUITES,
 	BUNDLED_SKILLS,
+	REPO_SKILLS,
 	createServer,
 	engineeringPlanFor,
 	isOctaneRepo,
@@ -173,20 +174,50 @@ describe('@octanejs/mcp-server helpers', () => {
 		}
 	});
 
-	it('advertises the engineering gates during MCP initialization', async () => {
+	it('routes to the engineering gates without restating them at initialization', async () => {
+		// Initialization instructions are injected into every session, so they stay
+		// short and point at the tool. The gates themselves must still be reachable
+		//: that is the contract, not any particular wording.
 		const server = createServer({ repoRoot: resolve(PACKAGE_ROOT, '../..') });
 		const client = new Client({ name: 'octane-mcp-test', version: '1.0.0' });
 		const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
 
 		try {
 			await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
-			expect(client.getInstructions()).toContain(
-				'Before creating or materially changing Octane software',
-			);
-			expect(client.getInstructions()).toContain('establish a relevant baseline before editing');
+			const instructions = client.getInstructions();
+			expect(instructions).toContain('octane_engineering_plan');
+			expect(instructions.length).toBeLessThan(600);
 
 			const tools = await client.listTools();
 			expect(tools.tools.map((tool) => tool.name)).toContain('octane_engineering_plan');
+
+			const plan = await client.callTool({
+				name: 'octane_engineering_plan',
+				arguments: { scope: 'framework-core', changeKind: 'performance' },
+			});
+			const body = plan.content[0].text;
+			expect(body).toContain('Identify hot paths and record a relevant baseline before editing.');
+			expect(body).toContain('build-octane-software');
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it('serves the project map from both generated, CI-gated sources', async () => {
+		// A hand-written map is the copy free to drift, which is why the old one
+		// did. Both halves here are regenerated and checked by CI.
+		const server = createServer({ repoRoot: resolve(PACKAGE_ROOT, '../..') });
+		const client = new Client({ name: 'octane-mcp-test', version: '1.0.0' });
+		const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+		try {
+			await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+			const map = (await client.callTool({ name: 'octane_project_map', arguments: {} })).content[0]
+				.text;
+			expect(map).toContain('Your React instincts are the main failure mode here');
+			expect(map).toContain('Package inventory (generated)');
+			expect(map).toContain('framework binding');
 		} finally {
 			await client.close();
 			await server.close();
@@ -207,6 +238,26 @@ describe('@octanejs/mcp-server helpers', () => {
 		}
 	});
 
+	it('serves every RuleSync skill, and only skills that exist', async () => {
+		// Checking that each mapped path resolves catches a dangling entry but not
+		// a missing one, which is how authoring-tsrx was added to .rulesync and
+		// stayed unreachable through octane_skill. Compare both directions.
+		const repoRoot = resolve(PACKAGE_ROOT, '../..');
+		const onDisk = readdirSync(resolve(repoRoot, '.rulesync/skills'), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.sort();
+
+		expect(Object.keys(REPO_SKILLS).sort()).toEqual(onDisk);
+
+		for (const file of Object.values(REPO_SKILLS)) {
+			expect(file.startsWith('.rulesync/skills/')).toBe(true);
+			expect(existsSync(resolve(repoRoot, file))).toBe(true);
+			const body = await readFile(resolve(repoRoot, file), 'utf8');
+			expect(body).toMatch(/^---\n[\s\S]*?\ndescription: /);
+		}
+	});
+
 	it('runs the React port scaffolder wrapper', async () => {
 		const repoRoot = await mkdtemp(join(tmpdir(), 'octane-mcp-test-'));
 		await mkdir(join(repoRoot, 'scripts'), { recursive: true });