Npm package

.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test
+      - run: npm audit --omit=dev
+      - run: npm pack --dry-run
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.nvmrc

@@ -0,0 +1 @@
+22

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjørn A. Johansen
+
+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.

README.md

@@ -1 +1,80 @@
-# React Observatory
+# Reactoscope
+
+Explore, stress-test, and get AI feedback on your React components — without writing a single test or storybook file.
+
+## Features
+
+- **Explore** — Renders any component with auto-generated prop controls based on its TypeScript types
+- **Stress Test** — Measures render performance, detects non-determinism, and spots memory leaks via server-side rendering
+- **AI Feedback** — Connects to a local Ollama instance to review component source code and provide suggestions
+
+## Quick Start
+
+### As a standalone CLI (no Vite project required)
+
+```bash
+npx reactoscope path/to/MyComponent.tsx
+```
+
+This starts a dev server and opens the Observatory UI in your browser.
+
+### As a Vite plugin
+
+```bash
+npm install reactoscope --save-dev
+```
+
+Add it to your Vite config:
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { observatory } from 'reactoscope'
+
+export default defineConfig({
+  plugins: [react(), ...observatory()],
+})
+```
+
+Then visit `/__observatory?component=path/to/MyComponent.tsx` in your browser while the dev server is running.
+
+## Options
+
+```ts
+observatory({
+  ollamaUrl: 'http://localhost:11434', // default
+})
+```
+
+| Option      | Type     | Default                  | Description                                               |
+| ----------- | -------- | ------------------------ | --------------------------------------------------------- |
+| `ollamaUrl` | `string` | `http://localhost:11434` | Base URL for the Ollama API used by the AI feedback panel |
+
+## Requirements
+
+- Node.js >= 22.18.0
+- React 19
+- TypeScript >= 5.8
+
+## How It Works
+
+Reactoscope is a set of Vite plugins that:
+
+1. **Schema plugin** — Parses your component's TypeScript props at dev time and serves them as JSON, powering the auto-generated prop controls
+2. **Stress plugin** — Renders your component server-side in a loop, measuring timing, output determinism, and heap growth
+3. **AI plugin** — Proxies requests to a local Ollama instance, injecting your component's source code as context
+4. **UI plugin** — Serves the pre-built Reactoscope dashboard at `/__observatory`
+
+The CLI wraps all of this into a single command using Vite's `createServer` API, so it works even in projects that don't use Vite.
+
+## AI Feedback
+
+The AI panel requires [Ollama](https://ollama.ai) running locally. Install it, pull a model, and the panel will auto-detect available models:
+
+```bash
+ollama pull llama3
+```
+
+## License
+
+MIT

bin/observe.js

@@ -1,42 +1,79 @@
 #!/usr/bin/env node
 
-import { spawn } from 'node:child_process'
 import { resolve, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { existsSync } from 'node:fs'
+import { createServer } from 'vite'
+import react from '@vitejs/plugin-react'
 
 const componentPath = process.argv[2]
 
 if (!componentPath) {
-  console.error('Usage: observe path/to/MyComponent.tsx')
+  console.error('Usage: reactoscope path/to/MyComponent.tsx')
   process.exit(1)
 }
 
-const projectRoot = resolve(fileURLToPath(import.meta.url), '../..')
-const abs = resolve(componentPath)
+const cwd = process.cwd()
+const abs = resolve(cwd, componentPath)
 
-// Make it relative to project root so we don't leak absolute paths
-const rel = relative(projectRoot, abs)
+if (!existsSync(abs)) {
+  console.error(`Error: File not found: ${abs}`)
+  process.exit(1)
+}
+
+const rel = relative(cwd, abs)
 
 if (rel.startsWith('..')) {
-  console.error('Error: Component must be inside the project directory.')
+  console.error(
+    'Error: Component must be inside the current working directory.',
+  )
   process.exit(1)
 }
 
-const viteBin = resolve(projectRoot, 'node_modules/.bin/vite')
-
-// spawn avoids shell injection — no shell is involved
-const existingNodeOptions = process.env.NODE_OPTIONS ?? ''
-const child = spawn(
-  viteBin,
-  ['--open', `/?component=${encodeURIComponent(rel)}`],
-  {
-    cwd: projectRoot,
-    stdio: 'inherit',
-    env: {
-      ...process.env,
-      NODE_OPTIONS: `${existingNodeOptions} --expose-gc`.trim(),
+const pkgRoot = resolve(fileURLToPath(import.meta.url), '../..')
+
+// Dynamic import so this works whether the user installed the package
+// or is running from the repo itself.
+const { observatory } = await import(resolve(pkgRoot, 'dist/plugin.mjs'))
+
+/** Check whether the user's Vite config already includes a React plugin. */
+function hasReactPlugin(plugins) {
+  const reactPluginNames = new Set([
+    'vite:react-babel',
+    'vite:react-swc',
+    'vite:react-refresh',
+  ])
+  return plugins.some((p) => {
+    if (Array.isArray(p)) return p.some((pp) => reactPluginNames.has(pp.name))
+    return reactPluginNames.has(p.name)
+  })
+}
+
+// Build the plugin list — always include observatory,
+// only add react() if the user's config doesn't already provide one.
+const extraPlugins = [...observatory()]
+
+const server = await createServer({
+  root: cwd,
+  plugins: [
+    {
+      name: 'observatory:inject',
+      config(config) {
+        const existing = config.plugins?.flat() ?? []
+        if (!hasReactPlugin(existing)) {
+          config.plugins = [react(), ...existing]
+        }
+      },
     },
+    ...extraPlugins,
+  ],
+  resolve: {
+    tsconfigPaths: true,
+  },
+  server: {
+    open: `/__observatory?component=${encodeURIComponent(rel)}`,
   },
-)
+})
 
-child.on('exit', (code) => process.exit(code ?? 0))
+await server.listen()
+server.printUrls()

index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>react-observatory</title>
+    <title>Reactoscope</title>
   </head>
   <body>
     <div id="root"></div>