@octanejs/mcp-server 0.2.2 → 0.2.5

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), '..');
@@ -18,6 +18,7 @@ const PACKAGE_ROOT = resolve(dirname(__filename), '..');
 // workflows: triage, PRs, core changes).
 export const BUNDLED_SKILLS = {
 	'bridge-react-package': 'skills/bridge-react-package.md',
+	'build-octane-software': 'skills/build-octane-software.md',
 	'migrate-react-component': 'skills/migrate-react-component.md',
 	'react-divergences': 'skills/react-divergences.md',
 	'setup-ssr': 'skills/setup-ssr.md',
@@ -33,16 +34,46 @@ export const REPO_SKILLS = {
 	triage: '.ai/skills/triage.md',
 };
 
-const BENCHMARKS = {
-	dbmon: '@benchmarks/dbmon',
-	'js-framework': 'octane-js-framework-benchmarks',
-	news: '@benchmarks/news',
-	'recursive-context': '@benchmarks/recursive-context',
-	'signal-favoring': '@benchmarks/signal-favoring',
-};
+// Suite names from the unified runner manifest (`SUITES` in
+// benchmarks/bench.mjs; `node benchmarks/bench.mjs --list` prints the same
+// set). index.test.js keeps this list in sync with the runner.
+export const BENCHMARK_SUITES = [
+	'js-framework',
+	'js-framework-reorder',
+	'todomvc',
+	'weather-app',
+	'weather-app-lighthouse',
+	'chat-stream',
+	'dbmon',
+	'recursive-context',
+	'signal-favoring',
+	'news',
+	'effectful-list',
+	'memo-wall',
+	'portal-swarm',
+	'react-hosted-islands',
+	'ssr-throughput',
+	'streaming-ssr',
+	'dbmon-deopt',
+	'js-framework-deopt',
+	'async-waterfall',
+	'async-composition',
+	'codegen-size',
+	'bundle-size',
+	'three-renderer',
+	'three-bundle-size',
+];
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 
+export function instructionsFor(repoMode) {
+	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.';
+	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;
+}
+
 export function text(content) {
 	return { content: [{ type: 'text', text: content }] };
 }
@@ -59,12 +90,19 @@ 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/adapter-vercel/')) return 'deploy-adapter';
+	if (path.startsWith('packages/octane-evals/')) return 'evals';
 	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';
+	if (path.startsWith('website/')) return 'website';
 	if (path.startsWith('.rulesync/')) return 'rulesync-source';
 	if (path.startsWith('.ai/') || path.startsWith('.codex/') || path.startsWith('.claude/')) {
 		return 'agent-instructions';
@@ -88,13 +126,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,8 +139,49 @@ 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('benchmark') || taskKind === 'performance') commands.add('pnpm bench');
+	if (areas.has('evals')) {
+		commands.add(
+			'./node_modules/.bin/vitest run packages/octane-evals/tests --project octane-evals',
+		);
+	}
+	if (areas.has('website')) {
+		commands.add('./node_modules/.bin/vitest run website/tests --project website');
+	}
+	if (areas.has('metaframework-core')) {
+		commands.add('./node_modules/.bin/vitest run packages/app-core/tests --project app-core');
+	}
+	if (areas.has('rspack-plugin')) {
+		commands.add(
+			'./node_modules/.bin/vitest run packages/rspack-plugin-octane/tests --project rspack-plugin',
+		);
+	}
+	if (areas.has('rsbuild-plugin')) {
+		commands.add(
+			'./node_modules/.bin/vitest run packages/rsbuild-plugin-octane/tests --project rsbuild-plugin',
+		);
+	}
+	if (areas.has('vite-plugin')) {
+		commands.add(
+			'./node_modules/.bin/vitest run packages/vite-plugin-octane/tests --project vite-plugin',
+		);
+	}
+	if (areas.has('deploy-adapter')) {
+		commands.add(
+			'./node_modules/.bin/vitest run packages/adapter-vercel/tests --project adapter-vercel',
+		);
+	}
+	if (
+		areas.has('metaframework-core') ||
+		areas.has('rspack-plugin') ||
+		areas.has('rsbuild-plugin') ||
+		areas.has('vite-plugin') ||
+		areas.has('deploy-adapter')
+	) {
+		commands.add('pnpm typecheck');
+	}
+	if (areas.has('benchmark') || taskKind === 'performance' || taskKind === 'core') {
+		commands.add('node benchmarks/bench.mjs --quick --ratios');
+	}
 	if (taskKind === 'api' || taskKind === 'core' || taskKind === 'package')
 		commands.add('pnpm typecheck');
 	commands.add('pnpm format:check');
@@ -111,6 +189,74 @@ export function validationFor(paths, taskKind) {
 	return [...commands];
 }
 
+export function engineeringPlanFor(input, repoMode = false) {
+	const paths = input.paths ?? [];
+	const scope = input.scope;
+	const changeKind = input.changeKind ?? 'feature';
+	const performanceSensitive =
+		scope === 'framework-core' ||
+		changeKind === 'performance' ||
+		input.performanceSensitive === true;
+	const correctnessGate =
+		changeKind === 'bug'
+			? 'Reproduce the bug through a realistic public boundary and verify that the test has a credible pre-fix failure.'
+			: 'Protect the new or changed behavior through a realistic public boundary with an assertion that would fail if the contract were absent.';
+	const plan = {
+		scope,
+		changeKind,
+		performanceSensitive,
+		areas: paths.map((path) => ({ path, area: areaForPath(path) })),
+		requiredSkills: ['build-octane-software'],
+		gates: {
+			contract: [
+				'State the consumer-observable behavior, invariants, failure states, and supported execution modes.',
+				'Inspect current source, callers, tests, configuration, and documented Octane divergences before editing.',
+			],
+			correctness: [
+				correctnessGate,
+				'Exercise applicable empty, large, repeated, nested, error, abort, cleanup, production, SSR, and hydration cases.',
+			],
+			performance: performanceSensitive
+				? [
+						'Identify hot paths and record a relevant baseline before editing.',
+						'Compare baseline and candidate with the same environment, warmup, iterations, and semantic controls.',
+						'Inspect allocations, retained memory, DOM work, compiler and generated-code cost, SSR/hydration work, and bundle size as applicable.',
+						'Do not claim improvement when the delta is within noise or no trustworthy measurement exists.',
+					]
+				: [
+						'Check that the change does not add unnecessary reactive work, retained state, dependencies, or common-path cost.',
+						'Measure the important user journey when the change can materially affect it.',
+					],
+			selfReview: [
+				'Read the complete diff adversarially and try to falsify the solution with boundary and lifecycle cases.',
+				'Trace new state and allocations through invalidation, cleanup, errors, and aborts.',
+				'Compare with a simpler design and remove complexity that does not justify its permanent cost.',
+				'Resolve findings, rerun affected checks, and repeat the review on the final diff.',
+			],
+			handoff: [
+				'Report the protected contract, validation commands and results, and applicable baseline/candidate measurements.',
+				'Report improvements made during self-review, untested modes, inconclusive evidence, and residual risk.',
+			],
+		},
+	};
+
+	if (scope === 'framework-core' && repoMode) {
+		plan.requiredSkills.push('octane-core-extend', 'performance-audit');
+	}
+	if (scope === 'framework-core' && !repoMode) {
+		plan.blockingConditions = [
+			'Framework-core work requires the MCP server to run against an Octane monorepo checkout. Set OCTANE_REPO_ROOT, reconnect, and request this plan again so maintainer skills and repository validation are available.',
+		];
+	}
+	if (repoMode) {
+		const taskKind =
+			scope === 'framework-core' ? 'core' : performanceSensitive ? 'performance' : changeKind;
+		plan.validationCommands = validationFor(paths, taskKind);
+	}
+
+	return plan;
+}
+
 export function runCommand(command, args, options = {}) {
 	const cwd = options.cwd ?? process.cwd();
 	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -172,15 +318,14 @@ export async function scaffoldReactPort(repoRoot, input) {
 }
 
 export async function runBenchmark(repoRoot, input) {
-	const args =
-		input.benchmark === 'all'
-			? ['bench']
-			: ['--filter', BENCHMARKS[input.benchmark], 'run', 'bench'];
-	const result = await runCommand('pnpm', args, {
+	const args = ['benchmarks/bench.mjs'];
+	if (input.benchmark && input.benchmark !== 'all') args.push(input.benchmark);
+	if (input.quick) args.push('--quick');
+	const result = await runCommand(process.execPath, args, {
 		cwd: repoRoot,
-		timeoutMs: input.timeoutMs ?? 300_000,
+		timeoutMs: input.timeoutMs ?? 600_000,
 	});
-	return { command: ['pnpm', ...args], benchmark: input.benchmark, ...result };
+	return { command: [process.execPath, ...args], benchmark: input.benchmark, ...result };
 }
 
 export async function issueContext(repoRoot, input) {
@@ -236,7 +381,7 @@ function registerUserTools(server, repoRoot, repoMode) {
 		{
 			title: 'Octane skill',
 			description:
-				'Return an Octane agent skill by name. Bundled skills cover working WITH octane in any project: bridging React packages, migrating React components to .tsrx, intentional React divergences, and SSR setup.' +
+				'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.' +
 				(repoMode ? ' Repo skills cover octane maintainer workflows.' : ''),
 			inputSchema: {
 				name: z.enum(Object.keys(skills)),
@@ -249,12 +394,33 @@ function registerUserTools(server, repoRoot, repoMode) {
 		},
 	);
 
+	server.registerTool(
+		'octane_engineering_plan',
+		{
+			title: 'Plan high-quality Octane engineering work',
+			description:
+				'Return required correctness, performance-evidence, adversarial self-review, and handoff gates before creating or materially changing Octane software. Framework-core scope always requires baseline/candidate performance evidence and the maintainer core/performance skills.',
+			inputSchema: {
+				scope: z.enum(['application', 'library', 'framework-core']),
+				changeKind: z
+					.enum(['bug', 'feature', 'performance', 'refactor', 'api', 'docs', 'test', 'unknown'])
+					.default('feature'),
+				paths: z.array(z.string()).default([]).describe('Repository-relative changed paths.'),
+				performanceSensitive: z
+					.boolean()
+					.optional()
+					.describe('Force performance evidence for application or library work.'),
+			},
+		},
+		async (input) => text(JSON.stringify(engineeringPlanFor(input, repoMode), null, 2)),
+	);
+
 	server.registerTool(
 		'octane_bridge_react_package',
 		{
 			title: 'Bridge a React package to Octane',
 			description:
-				'Scan a React package (from node_modules by name, or any source directory by path) for React API usage and return an Octane compatibility report: which APIs map 1:1, which need rewrites (forwardRef, useDebugValue, lazy, class components), whether a framework-agnostic core can be reused verbatim, whether an official @octanejs binding already exists, and a step-by-step bridge plan. Follow up with the bridge-react-package skill for the full workflow.',
+				'Scan a React package (from node_modules by name, or any source directory by path) for React API usage and return an Octane compatibility report: which APIs map 1:1, which need rewrites (forwardRef, class components, React-style text-host onChange, react-dom/server imports), whether a framework-agnostic core can be reused verbatim, whether an official @octanejs binding already exists, and a step-by-step bridge plan. Follow up with the bridge-react-package skill for the full workflow.',
 			inputSchema: {
 				package: z
 					.string()
@@ -379,9 +545,10 @@ function registerRepoTools(server, repoRoot) {
 		{
 			title: 'Run Octane benchmark',
 			description:
-				'Run one of the known Octane benchmark workspaces, or all benchmarks via pnpm bench.',
+				'Run benchmark suites through the unified runner (node benchmarks/bench.mjs): one manifest suite by name, or every suite with "all". Set quick for the reduced-iteration smoke pass.',
 			inputSchema: {
-				benchmark: z.enum(['all', ...Object.keys(BENCHMARKS)]).default('all'),
+				benchmark: z.enum(['all', ...BENCHMARK_SUITES]).default('all'),
+				quick: z.boolean().default(false),
 				timeoutMs: z.number().int().positive().optional(),
 			},
 		},
@@ -408,7 +575,10 @@ function registerRepoTools(server, repoRoot) {
 export function createServer(options = {}) {
 	const repoRoot = resolve(options.repoRoot || process.env.OCTANE_REPO_ROOT || process.cwd());
 	const repoMode = isOctaneRepo(repoRoot);
-	const server = new McpServer({ name: 'octane', version: '0.2.0' });
+	const server = new McpServer(
+		{ name: 'octane', version: '0.2.0' },
+		{ instructions: instructionsFor(repoMode) },
+	);
 	registerUserTools(server, repoRoot, repoMode);
 	if (repoMode) registerRepoTools(server, repoRoot);
 	return server;

package/src/index.test.js

@@ -1,4 +1,6 @@
 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 { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -6,11 +8,16 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
 	areaForPath,
+	BENCHMARK_SUITES,
 	BUNDLED_SKILLS,
+	createServer,
+	engineeringPlanFor,
 	isOctaneRepo,
+	runCommand,
 	scaffoldReactPort,
 	validationFor,
 } from './index.js';
+import { KNOWN_BINDING_PACKAGE_DIRS } from './bridge.js';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -22,10 +29,63 @@ describe('@octanejs/mcp-server helpers', () => {
 		expect(areaForPath('packages/zustand/src/index.ts')).toBe('ecosystem-binding');
 		expect(areaForPath('packages/radix/src/index.ts')).toBe('ecosystem-binding');
 		expect(areaForPath('packages/octane-mcp-server/src/index.js')).toBe('mcp-server');
+		expect(areaForPath('packages/adapter-vercel/src/index.ts')).toBe('deploy-adapter');
+		expect(areaForPath('packages/octane-evals/tools/run.mjs')).toBe('evals');
+		expect(areaForPath('website/src/pages/index.tsrx')).toBe('website');
 		expect(areaForPath('benchmarks/news/run.mjs')).toBe('benchmark');
 		expect(areaForPath('.rulesync/rules/project.md')).toBe('rulesync-source');
 	});
 
+	it('recommends the adapter, evals, and website test projects', () => {
+		const commands = validationFor(
+			[
+				'packages/adapter-vercel/src/index.ts',
+				'packages/octane-evals/tools/run.mjs',
+				'website/src/pages/index.tsrx',
+			],
+			'feature',
+		);
+
+		expect(commands).toContain(
+			'./node_modules/.bin/vitest run packages/adapter-vercel/tests --project adapter-vercel',
+		);
+		expect(commands).toContain(
+			'./node_modules/.bin/vitest run packages/octane-evals/tests --project octane-evals',
+		);
+		expect(commands).toContain('./node_modules/.bin/vitest run website/tests --project website');
+		expect(commands).toContain('pnpm typecheck');
+	});
+
+	it('keeps the benchmark suite list in sync with the unified runner manifest', async () => {
+		// BENCHMARK_SUITES is hand-maintained in index.js; the runner manifest in
+		// benchmarks/bench.mjs is the source of truth. --list prints one suite
+		// name per line, in manifest order.
+		const repoRoot = resolve(PACKAGE_ROOT, '../..');
+		const result = await runCommand(process.execPath, ['benchmarks/bench.mjs', '--list'], {
+			cwd: repoRoot,
+		});
+		expect(result.code).toBe(0);
+		const suites = result.stdout
+			.split('\n')
+			.map((line) => line.trim())
+			.filter((line) => line && line !== 'Available suites:');
+		expect(suites).toEqual(BENCHMARK_SUITES);
+	});
+
+	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(
 			[
@@ -48,9 +108,86 @@ describe('@octanejs/mcp-server helpers', () => {
 			'./node_modules/.bin/vitest run packages/radix/tests --project radix',
 		);
 		expect(commands).toContain('pnpm typecheck');
+		expect(commands).toContain('node benchmarks/bench.mjs --quick --ratios');
 		expect(commands).toContain('pnpm format:check');
 	});
 
+	it('requires performance evidence and adversarial review for framework fundamentals', () => {
+		const plan = engineeringPlanFor(
+			{
+				scope: 'framework-core',
+				changeKind: 'refactor',
+				paths: ['packages/octane/src/runtime.ts'],
+			},
+			true,
+		);
+
+		expect(plan.performanceSensitive).toBe(true);
+		expect(plan.requiredSkills).toEqual([
+			'build-octane-software',
+			'octane-core-extend',
+			'performance-audit',
+		]);
+		expect(plan.gates.performance).toContain(
+			'Identify hot paths and record a relevant baseline before editing.',
+		);
+		expect(plan.gates.selfReview).toContain(
+			'Resolve findings, rerun affected checks, and repeat the review on the final diff.',
+		);
+		expect(plan.validationCommands).toContain('node benchmarks/bench.mjs --quick --ratios');
+	});
+
+	it('blocks framework-core plans when maintainer tools are unavailable', () => {
+		const plan = engineeringPlanFor({ scope: 'framework-core', changeKind: 'bug' });
+
+		expect(plan.requiredSkills).toEqual(['build-octane-software']);
+		expect(plan.blockingConditions).toContain(
+			'Framework-core work requires the MCP server to run against an Octane monorepo checkout. Set OCTANE_REPO_ROOT, reconnect, and request this plan again so maintainer skills and repository validation are available.',
+		);
+		expect(plan.gates.correctness).toContain(
+			'Reproduce the bug through a realistic public boundary and verify that the test has a credible pre-fix failure.',
+		);
+	});
+
+	it('keeps performance gates and validation commands aligned', () => {
+		const performancePlan = engineeringPlanFor(
+			{ scope: 'application', changeKind: 'performance' },
+			true,
+		);
+		const flaggedPlan = engineeringPlanFor(
+			{ scope: 'library', changeKind: 'feature', performanceSensitive: true },
+			true,
+		);
+
+		for (const plan of [performancePlan, flaggedPlan]) {
+			expect(plan.performanceSensitive).toBe(true);
+			expect(plan.gates.performance).toContain(
+				'Identify hot paths and record a relevant baseline before editing.',
+			);
+			expect(plan.validationCommands).toContain('node benchmarks/bench.mjs --quick --ratios');
+		}
+	});
+
+	it('advertises the engineering gates during MCP initialization', async () => {
+		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 tools = await client.listTools();
+			expect(tools.tools.map((tool) => tool.name)).toContain('octane_engineering_plan');
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
 	it('detects the octane monorepo for repo-mode tools', async () => {
 		expect(isOctaneRepo(resolve(PACKAGE_ROOT, '../..'))).toBe(true);
 		const elsewhere = await mkdtemp(join(tmpdir(), 'octane-mcp-test-'));