@bluelibs/runner-dev 5.1.0 → 6.0.0

package/AI.md

@@ -13,6 +13,25 @@ Runner-Dev is a powerful development toolkit for applications built with the **@
 - **MCP Integration**: AI-native development environment
 - **Tags (first-class)**: Discover Tag objects and reverse usage via GraphQL (`tags`, `tag(id)`).
 - **Documentation UI Overviews**: Sortable and searchable overview tables with a `Used By` counter column for faster cross-element inspection.
+- **Visibility Awareness**: Every element exposes `isPrivate` (based on Runner `isolate()` boundaries), and resources expose `isolation`.
+- **Subtree Governance Awareness**: Resources expose normalized `subtree` policy summaries (middleware and validator counts per branch).
+- **Lifecycle Awareness**: Resources expose `cooldown` support and run options expose `lifecycleMode`, `disposeBudgetMs`, `disposeDrainBudgetMs`.
+- **Lane Awareness**: Events expose optional `eventLane` summaries (`globals.tags.eventLane`) and both tasks and events expose optional `rpcLane` summaries (`globals.tags.rpcLane`).
+- **Isolation Wildcard Explorer**: Wildcard isolation rules can be clicked to inspect all matching resources in a searchable modal list.
+- **Tag Handlers**: Tag views separate direct tag usages from handler elements that depend on the tag id.
+- **Task Interceptor Introspection**: Tasks expose `interceptorCount` and `hasInterceptors` for runtime `task.intercept(...)` registrations.
+- **Schema Export Compatibility**: Schema fields prefer `toJSONSchema()` exporters (including matcher-normalized schemas), with `zod` conversion as compatibility fallback.
+
+## Runner 6.0 Migration Notes
+
+| Before                | After (hard switch)                                       |
+| --------------------- | --------------------------------------------------------- |
+| `Resource.exports`    | `Resource.isolation { deny, only, exports, exportsMode }` |
+| `Middleware.global`   | `Middleware.autoApply { enabled, scope, hasPredicate }`   |
+| `Tag.middlewares`     | `Tag.taskMiddlewares` + `Tag.resourceMiddlewares`         |
+| N/A                   | `Tag.errors`, `Tag.targets`                               |
+| `RunOptions.initMode` | `RunOptions.lifecycleMode` (+ disposal budgets)           |
+| `Resource.tunnelInfo` | Removed (hard switch to Event Lane + RPC Lane surfaces)   |
 
 ## Available GraphQL Queries
 
@@ -23,18 +42,39 @@ Runner-Dev is a powerful development toolkit for applications built with the **@
 query SystemOverview {
   all {
     id
+    isPrivate
     meta {
       title
       description
     }
     filePath
   }
+  runOptions {
+    mode
+    debug
+    debugMode
+    logsEnabled
+    logsPrintThreshold
+    logsPrintStrategy
+    logsBuffer
+    errorBoundary
+    shutdownHooks
+    dryRun
+    lazy
+    lifecycleMode
+    runtimeEventCycleDetection
+    hasOnUnhandledError
+    rootId
+  }
 }
 
 # Get specific element types
 query Architecture {
   tasks {
     id
+    isPrivate
+    interceptorCount
+    hasInterceptors
     meta {
       title
       description
@@ -47,6 +87,13 @@ query Architecture {
   }
   resources {
     id
+    isPrivate
+    isolation {
+      deny
+      only
+      exports
+      exportsMode
+    }
     meta {
       title
       description
@@ -146,6 +193,28 @@ query LiveTelemetry {
 }
 ```
 
+### SSE Live Streaming
+
+Server-Sent Events endpoint at `GET /live/stream` for near-instant push instead of polling:
+
+- **`telemetry`** event: `{ logs, emissions, errors, runs }` pushed ~100ms after each record (debounced)
+- **`health`** event: `{ memory, cpu, eventLoop, gc }` every 2s
+- Heartbeat comment every 15s to keep proxies alive
+- `Live.onRecord(callback)` fires synchronously on each `record*` call; returns an unsubscribe function
+- The built-in Live Panel auto-uses SSE and falls back to configurable-interval polling (500ms–10s)
+
+### Correlation ID Trace View
+
+The Live Panel includes a built-in **Trace View** — a unified timeline showing every log, event emission, error, and task run sharing a single `correlationId`, ordered chronologically. Click any correlationId badge (shown on logs, events, errors, and runs) to open the trace modal. This provides an in-process "distributed tracing" experience (like Jaeger).
+
+### Unified Modal System
+
+All UI modals (CodeModal, ExecuteModal, TraceView, RecentLogs, OverviewStatsPanel) are built on a shared `BaseModal` primitive (`src/ui/src/components/Documentation/components/modals/`). It provides:
+
+- **Stacking**: A `ModalStackContext` tracks open modals and assigns ascending z-indexes (base 10 000 + 10 per layer). Global Escape closes the topmost modal first.
+- **Consistent UX**: Portal to `document.body`, backdrop blur, scroll lock, focus trap, slide-up animation, ARIA `role="dialog"`.
+- **Sizes**: `sm | md | lg | xl | fullscreen` with responsive fallback to fullscreen on small viewports.
+
 ### Diagnostics & Health
 
 ```graphql
@@ -262,9 +331,11 @@ npx @bluelibs/runner-dev new <project-name>
 # Example
 npx @bluelibs/runner-dev new my-awesome-app
 ```
+
 This command creates a new Runner project with a complete TypeScript setup, Jest for testing, and all necessary dependencies.
 
 Key flags for `new`:
+
 - `--install`: Install dependencies after scaffolding.
 - `--run-tests`: Run the generated test suite after installation.
 - `--run`: Start the dev server after installation.
@@ -274,11 +345,13 @@ Key flags for `new`:
 All commands can be prefixed with environment variables like `ENDPOINT` and `HEADERS`.
 
 **Ping the server:**
+
 ```bash
 ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev ping
 ```
 
 **Execute a GraphQL query (Remote Mode):**
+
 ```bash
 # Simple query
 ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev query 'query { tasks { id } }'
@@ -306,11 +379,13 @@ npx @bluelibs/runner-dev query 'query { tasks { id } }' \
 ```
 
 Selection logic:
+
 - If `--entry-file` is provided, dry-run mode is used (no server; requires ts-node).
 - Otherwise, the CLI uses a remote endpoint via `--endpoint` or `ENDPOINT/GRAPHQL_ENDPOINT`.
 - If neither is provided, the command errors.
 
 **Generate a project overview:**
+
 ```bash
 ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev overview --details 10
 ```
@@ -339,7 +414,6 @@ ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev schema json
 
 This direct CLI access provides a powerful way for AI assistants with shell access to script complex interactions, perform detailed introspection, and validate application state without relying on MCP tools.
 
-
 ## Common Use Cases
 
 ### 1. Understanding System Architecture
@@ -479,7 +553,10 @@ Minimal workflow setup pattern:
 
 ```ts
 import { r } from "@bluelibs/runner";
-import { durableWorkflowTag, memoryDurableResource } from "@bluelibs/runner/node";
+import {
+  durableWorkflowTag,
+  memoryDurableResource,
+} from "@bluelibs/runner/node";
 
 const durable = memoryDurableResource.fork("app.durable");
 const durableRegistration = durable.with({});
@@ -496,10 +573,7 @@ const workflow = r
   })
   .build();
 
-const app = r
-  .resource("app")
-  .register([durableRegistration, workflow])
-  .build();
+const app = r.resource("app").register([durableRegistration, workflow]).build();
 ```
 
 ## Best Practices for AI Assistants

package/README.md

@@ -11,7 +11,7 @@ Runner Dev Tools provide introspection, live telemetry, and a GraphQL API to exp
 
 The way it works, is that this is a resource that opens a graphql server which opens your application to introspection.
 
-If you use `zod` for schemas of your runner primitives, you will get them beautifully transformed to JSON Schemas. This can be made to work with any schema that supports conversion to JSON Schemas.
+If your runner primitives expose `toJSONSchema()` (for example matcher-based normalized schemas), runner-dev uses that as first-class schema export. `zod` schemas are also supported and converted to JSON Schema.
 
 ## Install
 
@@ -40,20 +40,42 @@ const app = resource({
 
 - Fully-featured UI with AI assistance to explore your app, call tasks, emit events, diagnostics, logs and more.
 - Overview tables across UI sections now include sortable and searchable columns (`ID`, `Title`, `Description`, `Used By`) with per-element usage counters.
+- Overview tables now include `Visibility` (`Public`/`Private`) derived from Runner resource `isolate()` boundaries.
 - Introspector: programmatic API to inspect tasks, hooks, resources, events, middleware, and diagnostics (including file paths, contents)
+- Task introspection includes runtime `interceptorCount` / `hasInterceptors` (registered via `taskDependency.intercept(...)` in resource init).
+- Resource introspection includes `isolation` (`deny`, `only`, `exports`, `exportsMode`) from `.isolate(...)`.
+- Resource introspection includes `subtree` governance summaries (middleware attachment counts and validator counts per branch).
+- Resource introspection indicates whether a resource exposes a `cooldown()` hook for shutdown lifecycle.
+- Isolation wildcard rules are clickable in the docs UI and open a modal showing matched resources with inline filtering when lists are large.
+- Event introspection includes `transactional`, `parallel`, optional `eventLane { laneId, orderingKey, metadata }`, and optional `rpcLane { laneId }`.
+- Task introspection includes optional `rpcLane { laneId }`.
+- Tag pages distinguish between directly tagged elements and tag handlers (elements that depend on the tag id).
 - Live: in-memory logs and event emissions
 - Live File Previews and Saving.
 - GraphQL server: deep graph navigation over your app’s topology and live data
 - CLI with scaffolding, query-ing capabilities on a live endpoint or via dry-run mode.
 - MCP server: allow your AI to do introspection for you.
 
+## Runner 6.0 Migration Notes
+
+| Before                | After (hard switch)                                                                          |
+| --------------------- | -------------------------------------------------------------------------------------------- |
+| `Resource.exports`    | `Resource.isolation { deny, only, exports, exportsMode }`                                    |
+| `Middleware.global`   | `Middleware.autoApply { enabled, scope, hasPredicate }`                                      |
+| `Tag.middlewares`     | `Tag.taskMiddlewares` + `Tag.resourceMiddlewares`                                            |
+| N/A                   | `Tag.errors`, `Tag.targets`                                                                  |
+| `RunOptions.initMode` | `RunOptions.lifecycleMode` + `dispose.{ totalBudgetMs, drainingBudgetMs, cooldownWindowMs }` |
+| N/A                   | `Resource.subtree`, `Resource.cooldown`                                                      |
+| N/A                   | `Event.transactional`, `Event.parallel`, `Event.eventLane`, `Event.rpcLane`, `Task.rpcLane`  |
+| `Resource.tunnelInfo` | Removed (hard switch to lane surfaces)                                                       |
+
 ## Table of Contents
 
 - [Quickstart Guide](#quickstart)
 - [Model Context Protocol (MCP) Server](#cli-usage-mcp-server)
 - [CLI Tooling & Scaffolding](#cli-usage-direct)
 - [Live Telemetry & Correlation](#live-telemetry)
-- [Hot-Swapping Debugging System](#-hot-swapping-debugging-system)
+- [Hot-Swapping Debugging System](#hot-swapping-debugging-system)
 - [GraphQL API Examples](#example-queries)
 - [API Reference](API_REFERENCE.md)
 - [Contributing & Local Dev](CONTRIBUTING.md)
@@ -83,9 +105,10 @@ export const app = resource({
 
 Once your application is running with the `dev` resource, you can access the visual DevTools UI:
 
-🚀 **Open [http://localhost:1337](http://localhost:1337) in your browser.**
+Open [http://localhost:1337](http://localhost:1337) in your browser.
 
 Inside the UI, you can:
+
 - Explore the resource graph.
 - Manually invoke tasks with custom inputs.
 - Inspect live logs and event emissions in real-time.
@@ -318,13 +341,13 @@ Precedence:
 
 ### CLI Summary
 
-| Category | Description |
-| --- | --- |
-| **New Project** | `runner-dev new <project-name>` |
+| Category        | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| **New Project** | `runner-dev new <project-name>`                           |
 | **Scaffolding** | `runner-dev new <resource\|task\|event\|tag\|middleware>` |
-| **Queries** | `runner-dev query 'query { ... }'` |
-| **Overview** | `runner-dev overview --details 10` |
-| **Schema** | `runner-dev schema sdl` |
+| **Queries**     | `runner-dev query 'query { ... }'`                        |
+| **Overview**    | `runner-dev overview --details 10`                        |
+| **Schema**      | `runner-dev schema sdl`                                   |
 
 ---
 
@@ -547,6 +570,41 @@ Notes:
 - `cpu.usage` is a ratio; `loadAverage` is 1‑minute OS load.
 - `eventLoop.lag` may be 0 if `monitorEventLoopDelay` is unavailable.
 
+### SSE Live Streaming
+
+In addition to GraphQL polling, the server exposes a **Server-Sent Events** endpoint at `GET /live/stream` for near-instant telemetry delivery:
+
+```http
+GET /live/stream
+Accept: text/event-stream
+```
+
+The endpoint pushes two event types:
+
+| Event       | Cadence                                      | Payload                                                     |
+| ----------- | -------------------------------------------- | ----------------------------------------------------------- |
+| `telemetry` | ~100ms after each `record*` call (debounced) | `{ logs, emissions, errors, runs }` (delta since last push) |
+| `health`    | Every 2s                                     | `{ memory, cpu, eventLoop, gc }`                            |
+
+A heartbeat comment (`: heartbeat`) is sent every 15s to keep the connection alive through proxies.
+
+**JavaScript client example:**
+
+```js
+const es = new EventSource("http://localhost:1337/live/stream");
+es.addEventListener("telemetry", (e) => {
+  const { logs, emissions, errors, runs } = JSON.parse(e.data);
+  // merge into your state
+});
+es.addEventListener("health", (e) => {
+  const { memory, cpu, eventLoop, gc } = JSON.parse(e.data);
+});
+```
+
+The built-in Live Panel UI automatically uses SSE when available and falls back to configurable-interval polling (500ms–10s slider) when SSE is not supported.
+
+**Programmatic notification hook:** The `Live` interface exposes `onRecord(callback)` which fires synchronously whenever a `record*` method is called, returning an unsubscribe function. This is the mechanism the SSE endpoint uses internally.
+
 ### Correlation and call chains
 
 - What is correlationId? An opaque UUID (via `crypto.randomUUID()`) created for the first task in a run chain.
@@ -583,6 +641,14 @@ query TraceByCorrelation($ts: Float, $cid: String!) {
 }
 ```
 
+#### Trace View (UI)
+
+The Live Panel includes a built-in **Trace View** — click any `correlationId` badge in the Logs, Events, Errors, or Runs sub-tabs to open a unified timeline modal showing every entry that shares that ID, ordered chronologically. Each entry is color-coded by kind (log, event, error, run) with a vertical timeline gutter, relative offset labels, and expandable details. This provides an in-process "distributed tracing" experience similar to Jaeger or Zipkin, but entirely within the Dev UI.
+
+#### Unified Modal System
+
+All Dev UI modals (code viewer, execute, trace view, log details, stats overlay) share a common `BaseModal` primitive that provides portal rendering, backdrop blur, focus trap, scroll lock, slide-up animation, and ARIA dialog semantics. A `ModalStackContext` manages stacking so modals can open on top of other modals — each layer gets a higher z-index and the global <kbd>Esc</kbd> key always closes the topmost one first.
+
 ## Emitting Events (Runner-native)
 
 - Define an event:
@@ -640,7 +706,7 @@ export const logSomething = task({
 
 For full details on development, testing, and codegen, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## 🔥 Hot-Swapping Debugging System
+## Hot-Swapping Debugging System
 
 **Revolutionary live debugging feature that allows AI assistants and developers to dynamically replace task run functions in live applications.**
 
@@ -683,6 +749,18 @@ export const app = resource({
 
 #### Queries
 
+**Get the effective run options (how the app was started):**
+
+```graphql
+query {
+  runOptions {
+    mode
+    debug
+    rootId
+  }
+}
+```
+
 **Get currently swapped tasks:**
 
 ```graphql
@@ -750,7 +828,7 @@ mutation {
         await deps.emitLog({
           timestamp: new Date(),
           level: "info",
-          message: "🔍 DEBUG: Creating user started",
+          message: "DEBUG: Creating user started",
           data: { input }
         });
       }
@@ -775,7 +853,7 @@ mutation {
         await deps.emitLog({
           timestamp: new Date(),
           level: "info",
-          message: "🔍 DEBUG: User created successfully",
+          message: "DEBUG: User created successfully",
           data: { result }
         });
       }
@@ -856,7 +934,7 @@ Swapped functions can emit logs that are captured by the live telemetry system:
 # After swapping with debug logging, query the logs
 query RecentDebugLogs {
   live {
-    logs(last: 50, filter: { messageIncludes: "🔍 DEBUG" }) {
+    logs(last: 50, filter: { messageIncludes: "DEBUG" }) {
       timestampMs
       level
       message
@@ -1080,7 +1158,7 @@ The system automatically handles complex JavaScript types:
 
 For advanced debugging, the system provides an `eval` mutation to execute arbitrary JavaScript/TypeScript code on the server.
 
-**⚠️ Security Warning**: This feature is powerful and executes code with the same privileges as the application. It is intended for development environments only and is disabled by default in production. To enable it, set the environment variable `RUNNER_DEV_EVAL=1`.
+**Security Warning**: This feature is powerful and executes code with the same privileges as the application. It is intended for development environments only and is disabled by default in production. To enable it, set the environment variable `RUNNER_DEV_EVAL=1`.
 
 #### `eval` Mutation
 
@@ -1123,13 +1201,129 @@ mutation {
 
 ### Architecture
 
-The hot-swapping system consists of:
+The hot-swapping system is organized into five high-level capabilities:
+
+- **Execution Control**: swaps task `run` implementations at runtime and supports rollback.
+- **Validation Pipeline**: parses and compiles submitted code before activation.
+- **API Surface**: exposes swap and restore operations through GraphQL mutations.
+- **Observability**: integrates with live telemetry so swapped behavior can be inspected immediately.
+- **Safety Controls**: isolates failures to the attempted swap and preserves previous task behavior when validation fails.
+
+The implementation remains fully type-safe and is covered by both unit and GraphQL integration tests.
+
+---
+
+## System Architecture
+
+### Overview
+
+Runner-Dev is built as a modular system of resources that integrate with the @bluelibs/runner framework to provide comprehensive development tools. The architecture follows a resource-based composition pattern where each component is a self-contained resource that can be registered and configured independently.
+
+### Core Components
+
+```mermaid
+graph TB
+    subgraph "Core Framework (@bluelibs/runner)"
+        App[Application Root]
+        Resource[Resources]
+        Task[Tasks]
+        Event[Events]
+        Middleware[Middleware]
+        Hook[Hooks]
+        Tag[Tags]
+    end
+
+    subgraph "DevTools Layer (@bluelibs/runner-dev)"
+        Dev[dev Resource]
+        Introspector[Introspector]
+        Live[Live Telemetry]
+        Swap[Swap Manager]
+        GraphQL[GraphQL Server]
+        MCP[MCP Server]
+    end
+
+    subgraph "Interfaces"
+        UI[React UI]
+        CLI[CLI Tools]
+        AI[AI Assistants]
+    end
+
+    App --> Dev
+    Dev --> Introspector
+    Dev --> Live
+    Dev --> Swap
+    Dev --> GraphQL
+    GraphQL --> MCP
+
+    Introspector --> Resource
+    Introspector --> Task
+    Introspector --> Event
+    Introspector --> Middleware
+    Introspector --> Hook
+    Introspector --> Tag
+
+    GraphQL --> UI
+    GraphQL --> CLI
+    MCP --> AI
+```
+
+### Component Responsibilities (High-Level)
+
+| Layer                       | Responsibility                                                                   |
+| --------------------------- | -------------------------------------------------------------------------------- |
+| **Composition Layer**       | Registers and wires DevTools capabilities into the Runner application lifecycle. |
+| **Introspection Layer**     | Builds a runtime model of tasks, resources, events, middleware, hooks, and tags. |
+| **Observability Layer**     | Captures logs, emissions, errors, runs, and health metrics for analysis.         |
+| **Execution Control Layer** | Supports remote task invocation and controlled hot-swapping workflows.           |
+| **Access Layer**            | Exposes a GraphQL API and transports for UI, CLI, and MCP clients.               |
+
+### Data Flow
+
+```mermaid
+sequenceDiagram
+    participant App as Runner App
+    participant Dev as dev Resource
+    participant Intro as Introspector
+    participant GQL as GraphQL Server
+    participant UI as React UI
+
+    App->>Dev: register dev.with({port: 1337})
+    Dev->>Intro: walk application graph
+    Intro-->>Dev: serialized topology
+    Dev->>GQL: start server on port 1337
+
+    UI->>GQL: query { tasks { id dependsOn } }
+    GQL-->>UI: introspected data
+
+    UI->>GQL: mutation invokeTask(...)
+    GQL->>App: execute task
+    App-->>GQL: result
+    GQL-->>UI: response
+```
+
+### Key Architectural Patterns
+
+1. **Resource-Based Composition**: Everything in Runner is a resource that can be registered and composed. The dev tools themselves are resources.
+
+2. **Introspection System**: The Introspector walks the application graph at runtime, extracting metadata about:
+
+   - Tasks (dependencies, emissions, interceptors)
+   - Resources (isolation rules, subtree governance, cooldown hooks)
+   - Events (listeners, transactional/parallel modes, lanes)
+   - Middleware (auto-apply scopes, tags)
+   - Tags (cross-cutting concerns with handlers)
+
+3. **Live Telemetry**: In-memory store for recent activity with SSE streaming via `/live/stream`
+
+4. **Hot-Swapping**: Modify task implementations without restart via `swapTask` mutation
+
+5. **GraphQL API**: Full schema at `src/schema/` with queries for architecture and mutations for invocation/swapping
+
+6. **MCP Integration**: AI assistants can connect via Model Context Protocol to introspect and interact with running apps
 
-- **SwapManager Resource** (`src/resources/swap.resource.ts`): Core swapping logic
-- **GraphQL Types** (`src/schema/types/SwapType.ts`): Type definitions for GraphQL API
-- **GraphQL Mutations** (`src/schema/mutation.ts`): Remote swap operations
-- **TypeScript Compiler**: Automatic code compilation and validation
-- **State Management**: Tracking of swapped functions and original code
-- **Error Handling**: Comprehensive validation and recovery mechanisms
+### Entry Points
 
-The implementation maintains 100% type safety and provides extensive test coverage with both unit tests and GraphQL integration tests.
+- **Main export**: `src/index.ts` - exports `dev` resource and types
+- **CLI entry**: `src/cli.ts` - command-line interface
+- **MCP entry**: `src/mcp.ts` - Model Context Protocol server
+- **UI entry**: `src/ui/index.html` - React documentation UI

package/dist/cli/generators/scaffold/templates/package.json.d.ts

@@ -12,10 +12,10 @@ export declare function packageJson(projectName: string): {
         readonly "schema:sdl": "runner-dev schema sdl";
     };
     readonly dependencies: {
-        readonly "@bluelibs/runner": "^5.2.0";
+        readonly "@bluelibs/runner": "^6.0.0";
     };
     readonly devDependencies: {
-        readonly "@bluelibs/runner-dev": "^5.0.0";
+        readonly "@bluelibs/runner-dev": "^6.0.0";
         readonly typescript: "^5.6.3";
         readonly tsx: "^4.19.2";
         readonly jest: "^29.7.0";

package/dist/cli/generators/scaffold/templates/package.json.js

@@ -16,10 +16,10 @@ function packageJson(projectName) {
             "schema:sdl": "runner-dev schema sdl",
         },
         dependencies: {
-            "@bluelibs/runner": "^5.2.0",
+            "@bluelibs/runner": "^6.0.0",
         },
         devDependencies: {
-            "@bluelibs/runner-dev": "^5.0.0",
+            "@bluelibs/runner-dev": "^6.0.0",
             typescript: "^5.6.3",
             tsx: "^4.19.2",
             jest: "^29.7.0",