@octanejs/mcp-server 0.2.9 → 0.2.11

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@octanejs/mcp-server",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.22.2"
   },
   "description": "MCP server exposing Octane repository automation for coding agents.",
   "license": "MIT",

package/skills/bridge-react-package.md

@@ -32,6 +32,11 @@ of bridging by hand:
 | `@base-ui-components/react` | `@octanejs/base-ui` |
 | `@dnd-kit/react` | `@octanejs/dnd-kit` |
 | `sonner` | `@octanejs/sonner` |
+| `streamdown` | `@octanejs/streamdown` |
+| `@streamdown/code` | `@octanejs/streamdown/code` |
+| `@streamdown/math` | `@octanejs/streamdown/math` |
+| `@streamdown/mermaid` | `@octanejs/streamdown/mermaid` |
+| `@streamdown/cjk` | `@octanejs/streamdown/cjk` |
 | `recharts` | `@octanejs/recharts` |
 | `@react-three/fiber` | `@octanejs/three` |
 | `@visx/*` | `@octanejs/visx` |
@@ -71,7 +76,23 @@ So a bridge never means "run the React package unchanged". It means:
    `*-core` dependency, or a pure internal module). Identify the React surface:
    hooks, components, providers, portals, refs.
 
-2. **Map the React APIs.** Same-name and same-semantics in Octane: `useState`,
+2. **Bridge from the pinned upstream source, not from memory.** Fix the exact
+   upstream version you are bridging and copy that release's React binding source
+   into your repository next to your port, for example
+   `src/vendor/<package>@<version>/`, keeping the upstream LICENSE and leaving
+   the copy unmodified. Put each Octane module beside the upstream module it
+   replaces, and work through them one by one. A bridge written from the README
+   or from type declarations covers the demo path and silently drops the rest of
+   the API. Anything you cannot reach (React internals, class components,
+   synthetic-event timing) goes in a short divergence note next to the port, with
+   what to do instead. On an upgrade, re-copy at the new version: the diff
+   against the old copy is your work list.
+   Inspect both the published package and the canonical repository at the pinned
+   tag. Do not assume the registry artifact contains source, tests, fixtures,
+   snapshots, or runner configuration; fetch missing evidence from the tagged
+   repository and record which artifact supplied it.
+
+3. **Map the React APIs.** Same-name and same-semantics in Octane: `useState`,
    `useReducer`, `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useMemo`,
    `useCallback`, `useRef`, `useContext`, `useId`, `useImperativeHandle`,
    `useSyncExternalStore` (full React 19 shape, including `getServerSnapshot`),
@@ -83,7 +104,7 @@ So a bridge never means "run the React package unchanged". It means:
    server rendering imports from `octane/server`, including the streaming
    `renderToPipeableStream`/`renderToReadableStream`.
 
-3. **Handle the gaps:**
+4. **Handle the gaps:**
    - `forwardRef`: does not exist. Accept `ref` as a normal prop (React 19
      style) and drop the wrapper.
    - Class components: rewrite as function components. Error boundary classes
@@ -98,7 +119,7 @@ So a bridge never means "run the React package unchanged". It means:
    - StrictMode double-invoke: does not exist; delete test expectations that
      count double renders.
 
-4. **Custom hooks in plain `.ts` files.** Octane's compiler auto-slots hook
+5. **Custom hooks in plain `.ts` files.** Octane's compiler auto-slots hook
    calls in files it compiles. A binding published as plain `.ts` that calls
    hooks internally must forward the caller's slot: accept a trailing `slot`
    argument and derive stable child slots per call site. The convention used by
@@ -122,13 +143,27 @@ So a bridge never means "run the React package unchanged". It means:
    auto-slotting pass. The simpler alternative: keep the binding in compiled
    files so slots are injected for you.
 
-5. **Re-author shipped components in `.tsrx`.** `props.children` works, refs are
+6. **Re-author shipped components in `.tsrx`.** `props.children` works, refs are
    props, lists use `@for (const x of xs; key x.id) { }`, conditionals use
    `@if`, dynamic text holes use `{expr as string}` unless the expression is
    provably a string.
 
-6. **Validate.** Drive real DOM events against the bridged binding and, where
-   possible, run the same fixture against the React original and compare
+7. **Run the package's own tests.** If the pinned release ships a suite, that is
+   the parity oracle: it encodes what its maintainers care about, and it covers
+   cases a suite written against your own bridge will not think to check. Run the
+   framework-neutral suites unmodified against the core you reused. Port the
+   React-binding ones case by case: fixtures re-authored in `.tsrx`,
+   `@octanejs/testing-library` in place of `@testing-library/react`, upstream case
+   names kept. Write down which upstream test files you ran, ported, or left out
+   and why. Do not soften an upstream assertion to get it green; find out whether
+   it is a bridge bug or a documented Octane divergence first.
+   Prove the evidence machinery fails closed too: removing, renaming, skipping,
+   or failing to execute a recorded case, or changing pinned evidence, must make
+   validation fail. A green port suite is not trustworthy when its collector can
+   silently go stale.
+
+8. **Validate the rest.** Drive real DOM events against the bridged binding and,
+   where possible, run the same fixture against the React original and compare
    rendered HTML after each step. Also test what HTML comparison cannot see:
    render counts, subscription add/remove, effect ordering, ref lifecycle.
 

package/skills/build-octane-software.md

@@ -34,6 +34,13 @@ details but do not replace these gates.
   hydration with production-compiled output and preserve abort/error behavior.
 - Treat bundle size and dependency cost as performance. Check for an official
   binding before adding a compatibility layer or a second framework runtime.
+- Publish every importable `.tsrx`, `.tsx`, `.ts`, and `.js` module as authored
+  and point package exports at that source. Do not ship Octane compiler output;
+  let the consuming application compile the source with its own toolchain.
+- When you do port a React package yourself, work from a pinned copy of that
+  release's source kept beside your port, cover its exports rather than the demo
+  path, and write down what parity could not reach. The `bridge-react-package`
+  skill has the procedure.
 
 ## Validate behavior and performance
 

package/src/bridge.js

@@ -6,14 +6,20 @@ import { join, resolve } from 'node:path';
 // 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 = {
+	'usehooks-ts': '@octanejs/usehooks-ts',
 	zustand: '@octanejs/zustand',
 	valtio: '@octanejs/valtio',
 	jotai: '@octanejs/jotai',
+	'@mantine/hooks': '@octanejs/mantine-hooks',
+	'mobx-react-lite': '@octanejs/mobx',
+	'mobx-react': '@octanejs/mobx',
 	'@apollo/client': '@octanejs/apollo-client',
 	'@tanstack/ai-react': '@octanejs/tanstack-ai',
 	'@tanstack/react-devtools': '@octanejs/tanstack-devtools',
 	'@tanstack/react-form': '@octanejs/tanstack-form',
 	'@tanstack/react-query': '@octanejs/tanstack-query',
+	wagmi: '@octanejs/wagmi',
+	'@rainbow-me/rainbowkit': '@octanejs/rainbowkit',
 	'@tanstack/react-router': '@octanejs/tanstack-router',
 	'@tanstack/react-store': '@octanejs/tanstack-store',
 	'@tanstack/react-router-ssr-query': '@octanejs/tanstack-router-ssr-query',
@@ -32,6 +38,7 @@ export const KNOWN_BINDINGS = {
 	'@lexical/react': '@octanejs/lexical',
 	'@tiptap/react': '@octanejs/tiptap',
 	'lucide-react': '@octanejs/lucide',
+	'@phosphor-icons/react': '@octanejs/phosphor-icons',
 	'@floating-ui/react': '@octanejs/floating-ui',
 	'react-aria': '@octanejs/aria',
 	'react-aria-components': '@octanejs/aria',
@@ -41,6 +48,14 @@ export const KNOWN_BINDINGS = {
 	'@base-ui-components/react': '@octanejs/base-ui',
 	'@dnd-kit/react': '@octanejs/dnd-kit',
 	sonner: '@octanejs/sonner',
+	'react-error-boundary': '@octanejs/react-error-boundary',
+	streamdown: '@octanejs/streamdown',
+	// The official plugins are consolidated as subpaths of the same package.
+	// The bundled bridge skill documents each exact import rewrite.
+	'@streamdown/code': '@octanejs/streamdown',
+	'@streamdown/math': '@octanejs/streamdown',
+	'@streamdown/mermaid': '@octanejs/streamdown',
+	'@streamdown/cjk': '@octanejs/streamdown',
 	shadcn: '@octanejs/shadcn',
 	recharts: '@octanejs/recharts',
 	'@react-three/fiber': '@octanejs/three',
@@ -95,6 +110,8 @@ export const KNOWN_BINDINGS = {
 	'@visx/zoom': '@octanejs/visx',
 	'react-redux': '@octanejs/redux',
 	'@reduxjs/toolkit': '@octanejs/redux-toolkit',
+	'@react-rxjs/core': '@octanejs/rxjs',
+	'@react-rxjs/utils': '@octanejs/rxjs',
 	'@testing-library/react': '@octanejs/testing-library',
 	'react-i18next': '@octanejs/i18next',
 	'@mdx-js/react': '@octanejs/mdx',
@@ -104,7 +121,11 @@ export const KNOWN_BINDINGS = {
 // 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']);
+export const KNOWN_NATIVE_BINDINGS = new Set([
+	'@octanejs/devtools',
+	'@octanejs/electron',
+	'@octanejs/tauri',
+]);
 
 // Workspace directory names for the maintained bindings. Keep this derived
 // from both catalogs so repository path routing cannot drift from the public
@@ -118,6 +139,7 @@ export const KNOWN_BINDING_PACKAGE_DIRS = new Set(
 export const KNOWN_VANILLA_CORES = {
 	'@apollo/client': '@apollo/client',
 	'@tanstack/react-query': '@tanstack/query-core',
+	wagmi: '@wagmi/core',
 	'@tanstack/react-table': '@tanstack/table-core',
 	'@tanstack/react-virtual': '@tanstack/virtual-core',
 	'@tanstack/react-form': '@tanstack/form-core',
@@ -534,6 +556,9 @@ function planFor(report) {
 			`Reuse the framework-agnostic core '${report.vanillaCore}' unchanged; it has no React imports and runs on Octane as-is.`,
 		);
 	}
+	steps.push(
+		"Pin the upstream version you are bridging and copy that release's React binding source into your repository beside the port, keeping the upstream LICENSE and leaving the copy unmodified, then work through it module by module. A bridge written from the README or the type declarations covers the demo path and drops the rest of the API; the copy is also the diff you review on the next upgrade.",
+	);
 	steps.push(
 		'Re-implement the React binding layer (the hooks/components that import react) against Octane hooks of the same names. Most store bindings reduce to useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot).',
 	);
@@ -556,7 +581,10 @@ function planFor(report) {
 		'Re-author any JSX components shipped by the package in .tsrx: compiled React JSX output cannot run on Octane, and hooks called from non-compiled files need compiler slotting (see the bridge-react-package skill for the subSlot pattern).',
 	);
 	steps.push(
-		'Validate with tests that drive real DOM events and compare behavior against the React original where possible.',
+		"Run the pinned release's own test suite against the bridge where it ships one: framework-neutral suites unmodified against the reused core, React-binding suites ported case by case (fixtures in .tsrx, @octanejs/testing-library for @testing-library/react, upstream case names kept). Note which upstream test files you ran, ported, or left out and why, and triage a failure before touching its assertion.",
+	);
+	steps.push(
+		'Validate the rest with tests that drive real DOM events and compare behavior against the React original where possible.',
 	);
 	return steps;
 }

package/src/bridge.test.js

@@ -186,6 +186,18 @@ describe('bridgeReport', () => {
 		expect(report.plan[0]).toContain('@octanejs/zustand');
 	});
 
+	it('tells the caller to bridge from a pinned copy of the upstream source', async () => {
+		const root = await mkdtemp(join(tmpdir(), 'octane-bridge-'));
+		await writeFakePackage(root, 'widgets', {
+			'index.js': `
+				import { useState } from 'react';
+				export function useWidget() { return useState(0); }
+			`,
+		});
+		const report = await bridgeReport({ packageName: 'widgets', projectRoot: root });
+		expect(report.plan.join('\n')).toContain('Pin the upstream version');
+	});
+
 	it('errors clearly when the package is not installed', async () => {
 		const root = await mkdtemp(join(tmpdir(), 'octane-bridge-'));
 		const report = await bridgeReport({ packageName: 'missing-lib', projectRoot: root });
@@ -253,6 +265,19 @@ describe('bridgeReportFromSource', () => {
 });
 
 describe('KNOWN_BINDINGS', () => {
+	it('maps Streamdown and every official plugin package to the consolidated binding', () => {
+		const upstreamPackages = [
+			'streamdown',
+			'@streamdown/code',
+			'@streamdown/math',
+			'@streamdown/mermaid',
+			'@streamdown/cjk',
+		];
+		expect(upstreamPackages.every((name) => KNOWN_BINDINGS[name] === '@octanejs/streamdown')).toBe(
+			true,
+		);
+	});
+
 	it('maps every public Visx entry point to the aggregate Octane port', async () => {
 		const packagesRoot = fileURLToPath(new URL('../..', import.meta.url));
 		const manifest = JSON.parse(await readFile(join(packagesRoot, 'visx', 'package.json'), 'utf8'));

package/src/index.js

@@ -46,6 +46,7 @@ export const BENCHMARK_SUITES = [
 	'weather-app',
 	'weather-app-lighthouse',
 	'chat-stream',
+	'streamdown-hosted',
 	'dbmon',
 	'recursive-context',
 	'signal-favoring',
@@ -276,6 +277,17 @@ export function engineeringPlanFor(input, repoMode = false) {
 	if (scope === 'framework-core' && repoMode) {
 		plan.requiredSkills.push('octane-core-extend', 'performance-audit');
 	}
+	// A binding is a port of one pinned upstream release, so its gates are about
+	// coverage of that release rather than the runtime cost gates above.
+	if (plan.areas.some((entry) => entry.area === 'ecosystem-binding')) {
+		plan.gates.parity = [
+			'Port module by module from the pinned upstream release vendored under packages/<name>/upstream/, not from the README, the type declarations, or memory.',
+			'Account for every export of the pinned upstream React entry points in the packages/<name>/UPSTREAM.md crosswalk: ported, reused verbatim from a framework-neutral core, divergence, or not applicable, each with its evidence. An unfinished export is an explicit gap row.',
+			'Record what parity cannot reach as a divergence in UPSTREAM.md and status.json, with the reason, what the consumer should do instead, and a behavioral test pinning the Octane behavior.',
+			"Run the pinned release's own suite as the parity oracle: its framework-neutral tests unmodified against the reused core, its React-binding tests ported case by case with the upstream case names and citations. Record every upstream test file as run as-is, ported, or out of scope with the reason, and never weaken an upstream assertion to make it pass.",
+		];
+		if (repoMode) plan.requiredSkills.push('react-library-port');
+	}
 	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.',

package/src/index.test.js

@@ -143,6 +143,25 @@ describe('@octanejs/mcp-server helpers', () => {
 		expect(plan.validationCommands).toContain('node benchmarks/bench.mjs --quick --ratios');
 	});
 
+	it('requires pinned-upstream coverage for binding work', () => {
+		const plan = engineeringPlanFor(
+			{ scope: 'library', changeKind: 'feature', paths: ['packages/zustand/src/index.ts'] },
+			true,
+		);
+
+		expect(plan.requiredSkills).toContain('react-library-port');
+		expect(plan.gates.parity.join('\n')).toContain('packages/<name>/UPSTREAM.md');
+		expect(plan.gates.parity.join('\n')).toContain('divergence');
+		expect(plan.gates.parity.join('\n')).toContain("pinned release's own suite");
+
+		const applicationPlan = engineeringPlanFor(
+			{ scope: 'application', changeKind: 'feature', paths: ['src/App.tsrx'] },
+			true,
+		);
+		expect(applicationPlan.gates.parity).toBeUndefined();
+		expect(applicationPlan.requiredSkills).not.toContain('react-library-port');
+	});
+
 	it('blocks framework-core plans when maintainer tools are unavailable', () => {
 		const plan = engineeringPlanFor({ scope: 'framework-core', changeKind: 'bug' });