jev-devtools 0.1.1 → 0.1.2

package/README.md

@@ -10,7 +10,22 @@ A React drawer and Node adapter for inspecting TypeSafe Jev requests with animat
 
 ![Full 28-second Jev DevTools demo showing sample results, the request drawer, and animated diagrams.](https://raw.githubusercontent.com/diegoag64/jev-devtools/main/docs/assets/jev-devtools-preview.gif)
 
-The full sample recording loops above. [Download the MP4 (530 KB)](https://github.com/diegoag64/jev-devtools/raw/refs/heads/main/docs/assets/jev-devtools-demo.mp4).
+The full sample recording loops above.
+
+## Set up with your coding agent
+
+In your application's coding-agent chat, paste:
+
+```text
+Set up jev-devtools in this React app. Read and follow:
+https://raw.githubusercontent.com/diegoag64/jev-devtools/main/packages/jev-devtools/skills/setup-jev-devtools/SKILL.md
+Choose the recipe for this app's framework, wire the server capture and root
+drawer, and verify with a labeled sample request. Preserve existing app behavior.
+```
+
+After installing, the version-matched instructions are available locally at `node_modules/jev-devtools/skills/setup-jev-devtools/SKILL.md` with all references included. In a workspace, read the package installed for the consuming app. Agents can follow these files without web access. Tools with skill support can install/copy the entire `setup-jev-devtools` folder into their supported skills location; npm does not register it automatically.
+
+The [setup skill](https://github.com/diegoag64/jev-devtools/blob/main/packages/jev-devtools/skills/setup-jev-devtools/SKILL.md) covers React/Node/Vite and Next.js App Router, with no-key sample verification and troubleshooting. A Node backend is required for live calls; browser-only apps can use a local Vite sample server. [Agent documentation index](https://raw.githubusercontent.com/diegoag64/jev-devtools/main/llms.txt).
 
 ## Install
 
@@ -27,7 +42,7 @@ To try unpublished local changes instead:
 npm ci
 npm run pack:devtools
 # From the consuming app:
-npm install /absolute/path/to/jev-devtools-0.1.1.tgz
+npm install /absolute/path/to/jev-devtools-0.1.2.tgz
 ```
 
 Mount once:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jev-devtools",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "engines": {
     "node": ">=22.12"
@@ -24,7 +24,8 @@
     "lib",
     "README.md",
     "LICENSE",
-    "THIRD_PARTY_NOTICES.txt"
+    "THIRD_PARTY_NOTICES.txt",
+    "skills"
   ],
   "sideEffects": [
     "**/*.css"

package/skills/setup-jev-devtools/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: setup-jev-devtools
+description: Install and verify Jev DevTools in an existing React application with a Node backend or Next.js App Router. Use when asked to add the Jev request inspector, wire capture, or troubleshoot its setup.
+---
+
+# Set up Jev DevTools
+
+Complete the integration in the user's application: one React drawer, one shared Node adapter, and application calls through that adapter's TypeSafe client. Installing or mounting the drawer alone does not capture requests.
+
+## Choose the integration
+
+Inspect the app's package manager/lockfile, React and Node versions, root component, server entry point, existing TypeSafe client construction, and development URL. Preserve existing configuration, authentication, routes, providers, and client options. Follow the host project's instructions; this package's contributor workflow does not apply to consumer apps.
+
+- **Next.js App Router:** read [references/nextjs.md](references/nextjs.md).
+- **React with a Node backend, including Vite:** read [references/react-node.md](references/react-node.md). A browser-only app needs a Node server for Jev; the Vite development-server option is local only.
+- **Other Node frameworks:** use the Web Request/Response or middleware API described in the React/Node reference and verify that framework's routing. Do not assume the Next.js recipe applies to Pages Router. Edge runtimes and cross-process/serverless history aggregation are unsupported.
+
+Install `jev-devtools` using the app's existing package manager (npm: `npm install jev-devtools`; pnpm: `pnpm add jev-devtools`; Yarn: `yarn add jev-devtools`). Install in the workspace(s) that actually import it. It is a regular dependency when application modules import it, even though capture/display are development-only. React 18/19 and Node 22.12+ are required. Do not replace the app's framework or upgrade unrelated dependencies to force compatibility.
+
+## Integration invariants
+
+- Use only public imports: `jev-devtools`, `jev-devtools/styles.css`, and server-only `jev-devtools/server`. No provider, TanStack, Tailwind, or shadcn installation is needed.
+- Mount `<JevDevtools />` once with an explicit development flag and import the CSS. Server capture must also be explicitly enabled for development; both default to off.
+- Create a shared adapter; the inspector routes and application client must use it in the same Node realm/process. Replace existing `new TypeSafeClient(options)` construction with `inspector.createClient(options)` while preserving keys, transport options, retries, and call semantics. Keep existing `systemOne(...)` inputs and application behavior.
+- Browser and server `endpoint` paths must agree (default `/api/jev-devtools`). Route the base path and its subpaths. The server `origin` must exactly match the browser scheme, hostname, and port. A browser endpoint is a same-origin path, not an absolute backend URL.
+- Keep keys in server environment variables, never `VITE_*` or `NEXT_PUBLIC_*`. Use the host's environment loader and an ignored local env file. If a key is unavailable, complete setup and use the clearly labeled sample verification in [references/verify.md](references/verify.md); report that live inference remains unverified.
+- Preserve authentication and project redaction. Shared/non-loopback access requires a real `authorize(request)` check; do not bypass it with `() => true`. Keep local defaults unless shared access is requested. Separate processes require a different architecture, not extra adapter instances.
+
+## Finish and verify
+
+Read [references/verify.md](references/verify.md). Build/typecheck the consumer, check configuration and SSE, and demonstrate a captured sample or authorized existing request. Verify the disabled production behavior. Explain any unverified step instead of calling a build alone a working integration.
+
+Summarize changed files, the development URL, how to open the drawer, which client calls are captured, and whether verification used samples or live inference. Installing this tool does not authorize deployment, publishing, or paid inference.
+
+These references are bundled with the installed package. Prefer them and its `.d.ts` files over newer online docs when integrating an older version. No agent automatically discovers this file just because npm installed it; explicitly read it or install this whole skill folder in the coding tool's supported skills location.

package/skills/setup-jev-devtools/references/nextjs.md

@@ -0,0 +1,75 @@
+# Next.js App Router
+
+Use Node runtime, React 18/19, and an existing App Router app. Respect `src/` layout and existing aliases. The independent example is verified with Next.js 16.4.2 / React 19; adapt older versions only after checking their supported configuration. This recipe does not cover Pages Router or Edge.
+
+## Dependency and configuration
+
+Install `jev-devtools` and `server-only` with the app's package manager. Merge into the existing Next config; preserve its wrappers, options, and external packages:
+
+```js
+serverExternalPackages: ['@typesafe-ai/sdk'],
+```
+
+Externalize the SDK only, not `jev-devtools`: the React entry must use Next's React instance. See [Next's serverExternalPackages reference](https://nextjs.org/docs/app/api-reference/config/next-config-js/serverExternalPackages).
+
+## Shared server adapter
+
+```ts
+// server/jev.ts, or src/server/jev.ts
+import 'server-only';
+import { getJevDevtools } from 'jev-devtools/server';
+
+export const inspector = getJevDevtools('your-app-name', () => ({
+  enabled: process.env.NODE_ENV === 'development',
+  origin: process.env.JEV_DEVTOOLS_ORIGIN || 'http://localhost:3000',
+}));
+
+export const jev = inspector.createClient({
+  apiKey: process.env.TYPESAFE_API_KEY,
+  // Preserve existing SDK options, e.g. timeout, retries, and custom fetch.
+});
+```
+
+Use one stable, app-specific key. The first options factory wins; restart after changing origin, authorization, redaction, or other settings. Do not dispose on each request or hot reload. The helper shares memory within one Node realm, not separate workers/serverless instances.
+
+Set the exact browser origin and API key in the existing server environment (normally an ignored `.env.local`). Never use `NEXT_PUBLIC_` for credentials. SDK client construction requires a key even when capture is disabled. When no key is available, use the sample client in [verify.md](verify.md) for verification instead of constructing a live client with an undefined key.
+
+Import this `jev` in existing Route Handlers, Server Actions, and Server Components that call `systemOne(...)`. Keep their inputs and behavior; calls using other clients are not captured.
+
+## Inspector route
+
+```ts
+// app/api/jev-devtools/[[...path]]/route.ts
+// This relative import also works with src/app and src/server.
+import { inspector } from '../../../../server/jev';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+export const GET = (request: Request) => inspector.handleNodeRoute(request);
+export const DELETE = (request: Request) => inspector.handleNodeRoute(request);
+```
+
+Use the **optional** catch-all `[[...path]]`, which covers config at the base path as well as `/events` and `/clear`. Keep streams out of caches/proxy buffering. Match Host to the configured origin; `localhost` and `127.0.0.1` differ. For Next `basePath` or a custom endpoint, align server `endpoint`, client `endpoint`, and the externally visible route path.
+
+## Root client boundary and CSS
+
+```tsx
+// app/devtools.tsx
+'use client';
+import { JevDevtools } from 'jev-devtools';
+
+export function Devtools() {
+  return <JevDevtools
+    enabled={process.env.NODE_ENV === 'development'}
+    defaultOpen={false}
+  />;
+}
+```
+
+In the **existing** root layout, import `jev-devtools/styles.css`, import `Devtools`, and add `<Devtools />` inside `<body>` alongside the existing children/providers. Keep the layout a Server Component; do not mark the entire layout `use client`. Ensure segments doing Jev work run on Node, not Edge. The drawer renders no SSR markup and connects after mounting in development.
+
+## Verify
+
+Follow [verify.md](verify.md): a real captured sample, SSE and clear, build/typecheck, and disabled production endpoints. Check that a call from the app's actual server entry point reaches the shared drawer. Cached results/static rendering do not generate a new SDK call on every visit; repeated development renders may generate more than one. Record only what was observed.
+
+For a runnable, sample-only implementation with Route Handlers, Server Actions, and Server Components, see [examples/nextjs-app](https://github.com/diegoag64/jev-devtools/tree/main/examples/nextjs-app). Shared authentication/session scoping and further limitations are in the [Next.js guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/nextjs.md).

package/skills/setup-jev-devtools/references/react-node.md

@@ -0,0 +1,95 @@
+# React with a Node server
+
+## Mount the drawer
+
+Add to the existing root without replacing providers or routing:
+
+```tsx
+import { JevDevtools } from 'jev-devtools';
+import 'jev-devtools/styles.css';
+
+// Inside the existing root JSX, alongside the app:
+<JevDevtools enabled={import.meta.env.DEV} defaultOpen={false} />
+```
+
+`import.meta.env.DEV` is Vite-specific. For another bundler use its existing development flag. The component is SSR-safe; no provider or client prop is required. `endpoint` defaults to `/api/jev-devtools`. CSS is scoped to the inspector.
+
+## Existing Express/Connect backend
+
+Create a server-only module and import the same exports in the server bootstrap and all inference handlers:
+
+```ts
+// server/jev.ts (adapt the location to the app)
+import { createJevDevtools } from 'jev-devtools/server';
+
+export const inspector = createJevDevtools({
+  enabled: process.env.NODE_ENV === 'development',
+  origin: process.env.JEV_DEVTOOLS_ORIGIN || 'http://localhost:5173',
+});
+export const jev = inspector.createClient({
+  apiKey: process.env.TYPESAFE_API_KEY,
+  // Preserve the existing SDK client's other options here.
+});
+```
+
+Ensure the backend's dev command actually sets `NODE_ENV=development`; plain Node does not do so automatically. Load server env files using the app's existing loader before this module runs. The SDK still requires a key when capture is disabled. Do not import this module from React/browser code.
+
+```ts
+// In the existing Node server bootstrap:
+import { inspector } from './jev';
+app.use(inspector.middleware);
+// Existing inference handlers import jev from './jev' and call systemOne as before.
+```
+
+Mount at the application root, before fallback routes. Do not mount with `app.use('/api/jev-devtools', ...)`: Express strips the prefix the adapter needs. Dispose the adapter during server shutdown, not after each request. If the framework reloads server modules, use `getJevDevtools('your-app', () => options)` instead and restart after options change.
+
+### Separate Vite frontend and backend ports
+
+For a browser at `http://localhost:5173` and backend at `http://127.0.0.1:3001`, merge this into the existing Vite config:
+
+```ts
+server: {
+  port: 5173,
+  strictPort: true,
+  proxy: {
+    '/api/jev-devtools': {
+      target: 'http://127.0.0.1:3001',
+      changeOrigin: false,
+    },
+    // Preserve the app's existing proxy for its own inference endpoint.
+  },
+}
+```
+
+Set the adapter origin to the **frontend** origin. Preserve Host and the complete path; no prefix rewrite. Do not buffer or cache `/events`. A broader existing `/api` proxy may suffice if it obeys these rules. The React component must still use the relative same-origin endpoint. See [Vite proxy options](https://vite.dev/config/server-options.html#server-proxy).
+
+## Vite app without a backend: local sample setup
+
+A static React app cannot hold a Jev API key. To demonstrate local capture without creating a production backend, add a development-only Vite plugin. Keep existing plugins and configure `server: { host: '127.0.0.1', port: 5173, strictPort: true }`; open that exact origin. This plugin is not a production API.
+
+```ts
+// Add this object to the plugins array in vite.config.ts.
+// Import createJevDevtools from 'jev-devtools/server' in that config only.
+{
+  name: 'local-jev-inspector',
+  apply: 'serve',
+  configureServer(server) {
+    const inspector = createJevDevtools({
+      enabled: true,
+      origin: 'http://127.0.0.1:5173',
+    });
+    server.middlewares.use(inspector.middleware);
+    server.httpServer?.once('close', () => inspector.dispose());
+    // Register the sample client and handler described in verify.md here.
+    // Any live application handler must share this same inspector instance.
+  },
+}
+```
+
+Use the sample recipe in [verify.md](verify.md) for a temporary request endpoint. If the user needs persistent application APIs, use their intended Node backend instead; do not silently turn a dev plugin into production infrastructure. Vite does not automatically load `.env.local` into `process.env` while evaluating its config: for live development use the existing server environment strategy or Vite's server-side `loadEnv`, without exposing the key via `define` or client-prefixed variables.
+
+## Other Node frameworks
+
+`inspector.handle(request: Request)` returns a Web Response including SSE. Route GET for the base path and `/events`, plus DELETE for `/clear`, to that same adapter. Preserve streaming/cancellation rather than converting the response to JSON. `handleNodeRoute(request)` is for Node framework requests with internal URLs; it validates the actual Host against the configured origin before normalizing the URL. It does not trust forwarded host headers.
+
+Custom endpoints/base paths must match in browser props, server options, framework routes, and the external URL. For multiple users, `getSession(request)` defines a trusted server-side scope; wrap application requests with `inspector.run(request, callback)` using the same session resolver as the inspector endpoints. This wrapper scopes recording; it does not authenticate the application's inference route. Read the [access-control guide](https://github.com/diegoag64/jev-devtools/blob/main/docs/integration.md#history-and-access) before adapting to shared access.

package/skills/setup-jev-devtools/references/verify.md

@@ -0,0 +1,81 @@
+# Verify the consumer integration
+
+Use the host app's typecheck/build commands. Do not run the Jev DevTools monorepo scripts inside a consumer app. A passing build does not establish that capture is connected.
+
+## Sample request without a key
+
+Use this server-only fixture when live inference is not authorized or no key is configured. It exercises the real SDK and recorder with fixed sample data and no external inference call. Create it from the **same inspector** that serves the endpoints. Keep it visibly sample-only; never substitute it for the user's production inference path.
+
+```ts
+const sampleJev = inspector.createClient({
+  apiKey: 'sample-only',
+  logLevel: 'off',
+  fetch: async () => Response.json({
+    model: 'jev-sample',
+    answers: {
+      category: {
+        type: 'choice',
+        choice: 'billing',
+        probabilities: { billing: 0.8, other: 0.2 },
+        confidence: 0.7,
+      },
+    },
+  }),
+}, { label: 'Setup verification', source: 'sample' });
+
+async function runSample() {
+  return sampleJev.systemOne({
+    state: { message: 'I was charged twice.' },
+    questions: {
+      category: {
+        type: 'choice',
+        instructions: 'Which team should handle this message?',
+        criteria: { billing: 'Payment issues', other: 'Everything else' },
+      },
+    },
+  });
+}
+```
+
+For a Vite/Connect dev plugin, register a temporary local handler after mounting the inspector:
+
+```ts
+server.middlewares.use(async (req, res, next) => {
+  if (req.url !== '/__jev-setup-sample' || req.method !== 'POST') return next();
+  try {
+    await runSample();
+    res.writeHead(200, { 'content-type': 'application/json' }).end('{"ok":true}');
+  } catch {
+    res.writeHead(500).end('Sample failed');
+  }
+});
+```
+
+For Next, expose `runSample` from the server module and call it from a temporary development-only Node Route Handler (return 404 outside development). For an existing backend, use a temporary development-only handler or its existing test harness. Do not execute the sample in a separate CLI process and expect it to appear in the running server's memory. Remove temporary sample routes/UI after verification unless the user wants a demo; existing live flows must remain live.
+
+## Observable checks
+
+1. Start the app in development at the configured origin. GET `/api/jev-devtools` must return 200 JSON `{ "version": 1, "enabled": true }`, not the app's HTML fallback. Use the custom endpoint if configured.
+2. GET `/api/jev-devtools/events` should return `text/event-stream` with `event: snapshot`. The connection intentionally stays open. Use a bounded stream read and close it afterwards.
+3. Trigger the sample **in that running server**. Its next snapshot should contain the label `Setup verification`, source `sample`, context, question, returned choice `billing`, and probabilities. In the browser, open the bottom-right Jev DevTools launcher and inspect Flow, Questions, and Context. A configured endpoint with an empty history is not proof of capture.
+4. Use Clear and confirm the sample disappears. A scripted DELETE to `/api/jev-devtools/clear` must include the exact `Origin` header (and app authorization/session cookies when configured). Don't clear unrelated user history without consent; use a fresh local verification session when needed.
+5. Run the app's production build/typecheck. With development flags off, inspector endpoints return 404 and the drawer makes no requests. Existing application SDK calls should continue normally. Vite dev plugins are absent from static production output; the host backend must independently disable its adapter. This is runtime opt-in, not a guarantee that every bundler eliminates all inspector files.
+6. Confirm server SDK imports and credentials never enter browser bundles. Use the app's build analysis or module inspection if available. Don't infer this solely from a successful build.
+
+Report HTTP/capture checks separately from visual browser checks, and sample verification separately from live inference. If browser tools or a server runtime are unavailable, say which checks remain undone.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| No launcher | Mount once, import CSS, and explicitly enable in development. It intentionally renders nothing on the server. |
+| Disconnected or HTML instead of config | Ensure base path **and** subpaths reach the adapter before the SPA fallback; check proxy and Next optional catch-all. |
+| 403 | Match scheme/hostname/port and Host exactly; preserve proxy Host, verify Origin and authorization. Don't disable guards. |
+| Connected but empty | Use the adapter's instrumented client, same adapter/key/process and session. Direct SDK clients are not intercepted. |
+| Clear fails | Browser/server endpoint agreement, same-origin DELETE, exact Origin, authorization and session. |
+| Missing key | SDK needs a server key even with recording off; use the labeled sample transport for offline verification. |
+| Next reload loses or ignores settings | Use a stable `getJevDevtools` key; restart after option changes. Don't dispose during hot reload. |
+| Server import/build errors | Keep `/server` outside client modules. In Next externalize the SDK only. Use a supported Node runtime. |
+| Production 404 | Expected when disabled; app inference remains independent. |
+
+Capture is bounded to 50 calls in memory by default. Built-in redaction has limits; arbitrary secrets in prose are not detected. Diagrams show captured inputs/outputs, not hidden model reasoning or application routing decisions.