@bluelibs/runner-dev 6.1.0 → 6.3.0

package/readmes/COMPACT_GUIDE.md

@@ -0,0 +1,254 @@
+# Runner-Dev Compact Guide
+
+Runner-Dev is the developer-facing toolkit for inspecting, querying, and debugging Runner apps through a docs UI, GraphQL endpoint, MCP server, live telemetry, and controlled hot-swapping. Use it when the task is about what a Runner app looks like at runtime, what the docs/AI layer sees, or how runner-dev exposes that information.
+
+It also supports a static export path through `exportDocs(app, { output?, overwrite? })` when you want the visual catalog without keeping a live server around.
+
+## Use This When
+
+- The task touches `/docs/data`, docs UI, chat context, agent-facing documentation, or the topology graph / blast-radius / mindmap views.
+- You need GraphQL or MCP access to runtime topology, telemetry, schema, or diagnostics.
+- You are debugging telemetry, live events, durable metadata, hook targets, or lane surfaces.
+- You are changing runner-dev CLI, MCP tools, docs payload shaping, or introspection behavior.
+
+## Fastest Path To Success
+
+1. Decide whether the target app is already running.
+2. If it is running, prefer MCP or GraphQL before reading lots of source.
+3. If it is package work, locate the subsystem first:
+   - docs payloads and docs UI
+   - introspector/store serialization
+   - MCP tools
+   - live telemetry
+   - swap/hot-reload
+4. Patch the smallest surface that explains the behavior.
+5. Run the narrowest relevant test first, then widen only if needed.
+
+## Quick Setup
+
+Register runner-dev in the Runner root:
+
+```ts
+import { r } from "@bluelibs/runner";
+import { dev } from "@bluelibs/runner-dev";
+
+export const app = r
+  .resource("app")
+  .register([
+    dev.with({
+      port: 1337,
+      maxEntries: 1000,
+    }),
+  ])
+  .build();
+```
+
+Expected endpoints after the app starts:
+
+- UI: `http://localhost:1337`
+- GraphQL: `http://localhost:1337/graphql`
+- Live stream: `http://localhost:1337/live/stream`
+- Docs payload: `http://localhost:1337/docs/data`
+
+Static export option:
+
+```ts
+// scripts/export-docs.ts
+import { exportDocs } from "@bluelibs/runner-dev";
+import { app } from "../src/app";
+
+await exportDocs(app);
+// Optional custom destination:
+await exportDocs(app, {
+  output: "./artifacts/runner-dev-catalog",
+  overwrite: true,
+});
+```
+
+Add a package script:
+
+```json
+{
+  "scripts": {
+    "docs:export": "tsx scripts/export-docs.ts"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run docs:export
+```
+
+Notes:
+
+- default output is `./runner-dev-catalog`
+- `exportDocs()` uses Runner dry-run under the hood: it effectively does `run(app, { dryRun: true })` and snapshots the composed in-memory store
+- `exportDocs(app)` writes a standalone `index.html` plus `snapshot.json`
+- custom non-empty directories require `overwrite: true`
+- the exported `index.html` is standalone and can be opened directly over `file://`
+- `snapshot.json` is still written as an auxiliary artifact for inspection, debugging, and snapshot-backed MCP
+- this works well in CI too: upload the export folder as a build artifact and inspect it after the pipeline finishes
+- in this repository, `npm run play:export` is the same pattern wired to the enhanced showcase app
+
+## MCP Quickstart
+
+Use MCP against either a live Dev GraphQL endpoint or an exported `snapshot.json`.
+
+Minimal client config:
+
+```json
+{
+  "mcpServers": {
+    "runner-dev": {
+      "command": "npx",
+      "args": ["@bluelibs/runner-dev", "mcp"],
+      "env": {
+        "ENDPOINT": "http://localhost:1337/graphql",
+        "ALLOW_MUTATIONS": "false"
+      }
+    }
+  }
+}
+```
+
+Authenticated variant:
+
+```json
+{
+  "mcpServers": {
+    "runner-dev": {
+      "command": "npx",
+      "args": ["@bluelibs/runner-dev", "mcp"],
+      "env": {
+        "ENDPOINT": "http://localhost:1337/graphql",
+        "HEADERS": "{\"Authorization\":\"Bearer <token>\"}",
+        "ALLOW_MUTATIONS": "false"
+      }
+    }
+  }
+}
+```
+
+Direct launch:
+
+```bash
+ENDPOINT=http://localhost:1337/graphql npx -y @bluelibs/runner-dev mcp
+SNAPSHOT_FILE=./runner-dev-catalog/snapshot.json npx -y @bluelibs/runner-dev mcp
+```
+
+First checks, in order:
+
+1. `graphql.ping`
+2. `project.overview`
+3. `graphql.query`
+
+Shell equivalents:
+
+```bash
+ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev ping
+ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev overview --details 5
+ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev query 'query { tasks { id } resources { id } }' --format pretty
+```
+
+Notes:
+
+- Keep `ALLOW_MUTATIONS=false` unless you intentionally need write access.
+- Set `HEADERS` if the GraphQL endpoint requires auth.
+- `SNAPSHOT_FILE` enables read-only MCP over an exported catalog without starting the app.
+- If `graphql.ping` fails, check that the app is running, the port is correct, and `HEADERS` is valid JSON.
+
+## First Things To Inspect
+
+If the app is running:
+
+- Start from `/docs/data` when the question is about what the docs UI or AI sees.
+- Use `project.overview` for a fast topology summary.
+- Use GraphQL for focused reads, not giant dumps.
+- Use live telemetry only with narrow limits such as `last: 10`.
+
+Minimal topology query:
+
+```graphql
+query FirstLook {
+  tasks {
+    id
+  }
+  resources {
+    id
+  }
+  hooks {
+    id
+  }
+  diagnostics {
+    severity
+    code
+    message
+  }
+}
+```
+
+Minimal live query:
+
+```graphql
+query LiveFirstLook {
+  live {
+    logs(last: 10) {
+      level
+      message
+      correlationId
+    }
+    errors(last: 10) {
+      sourceKind
+      message
+      correlationId
+    }
+  }
+}
+```
+
+## High-Value Source Files
+
+When working inside `@bluelibs/runner-dev`, start here:
+
+- `src/resources/routeHandlers/getDocsData.ts` for docs payloads and bundled context
+- `src/resources/models/Introspector.ts` and related store initialization for topology
+- `src/mcp/tools/*` for MCP help/query behavior
+- `src/resources/live.resource.ts` and telemetry resources for live data
+- `src/ui/src/components/Documentation/*` for docs/chat UI behavior
+- `src/ui/src/components/Documentation/components/TopologyPanel.tsx` and `src/ui/src/components/Documentation/utils/topologyGraph.ts` for topology graph projections and rendering
+- `src/resources/swap.resource.ts` and `src/resources/swap.tools.ts` for hot-swapping surfaces
+
+## Core Surfaces
+
+- Docs UI: the browser surface for architecture, live data, and AI assistance
+- Topology graph: a focused lens for blast-radius analysis and resource mindmaps
+- `/docs/data`: the JSON payload feeding docs UI and in-app AI context
+- GraphQL: the main runtime introspection surface
+- MCP: the fastest AI-native access path when the app is already running
+- Live telemetry: logs, emissions, errors, runs, and correlation-driven inspection
+- Swap tooling: controlled runtime task replacement and restoration
+
+## Current Compatibility Notes
+
+Assume current Runner reality, not old examples:
+
+- Identity moved from `asyncContexts.tenant` to `asyncContexts.identity`; related middleware uses `identityScope`.
+- Hook targets may come from selectors such as `subtreeOf(...)` or predicates, not only raw `hook.on`.
+- Event Lane routing comes from `r.eventLane(...).applyTo([...])`, not old lane-tag assumptions.
+- Runner supports `run(app, { signal })`, `run(app, { identity })`, and `runtime.dispose({ force: true })`.
+
+## AI Working Strategy
+
+- Use the Runner skill for framework design or core Runner contracts.
+- Use runner-dev context for tooling behavior, docs payloads, MCP, GraphQL, telemetry, and UI integration.
+- Prefer focused tests first: `npm run test -- docs.data`, `npm run test -- mcp`, `npm run test -- live`, or another narrow suite near the touched surface.
+- Use `pure: true` when validating swapped task behavior safely.
+- Avoid huge live queries, broad schema dumps, or mutation access unless the task truly needs them.
+
+## Go Deeper
+
+- Read `README.md` for installation, CLI, and broader examples.
+- Read the Runner skill for framework-level architecture and contracts.
+- Read source near the touched surface before broadening to unrelated subsystems.

package/skills/core/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: Runner DevTools Usage
+description: Use when working on @bluelibs/runner-dev itself, especially for docs UI behavior, introspection resources, GraphQL tooling, MCP helpers, telemetry surfaces, and agent-facing documentation. Start here when the task needs runner-dev-specific context instead of the general Runner framework skill.
+---
+
+# Runner Dev
+
+Start with `./references/readmes/COMPACT_GUIDE.md`.
+It is the canonical compact runner-dev guide and should stay aligned with the current toolkit behavior.
+
+Use `./references/README.md` when the task needs installation, CLI, or broader user-facing usage details.
+Use `./references/readmes/API_REFERENCE.md` when the task needs the current GraphQL surface used by docs or MCP flows.
+
+Reference layout:
+
+- `./references/README.md` mirrors the repo root `README.md`
+- `./references/readmes/` mirrors the repo `readmes/` directory, including `COMPACT_GUIDE.md` and `API_REFERENCE.md`
+
+Use this skill when the task involves:
+
+- docs UI behavior, `/docs/data`, in-app documentation delivery, or the topology graph / blast-radius / mindmap views
+- MCP helpers, GraphQL tooling, introspection resources, or chat context wiring
+- live telemetry, hot-swapping, CLI surfaces, or other runner-dev tooling
+- agent-facing documentation that must stay aligned with `readmes/COMPACT_GUIDE.md` and `README.md`
+- GraphQL schema and MCP contract work grounded in `./references/readmes/API_REFERENCE.md`
+
+Reach for the general Runner skill when the problem is about framework design rather than runner-dev's tooling surface.

package/skills/core/references/readmes/API_REFERENCE.md

@@ -0,0 +1,364 @@
+# GraphQL API Reference
+
+This document tracks the current `@bluelibs/runner-dev` GraphQL surface.
+It has been refreshed for the current SDL and focuses on the entry points people actually reach for first: root queries, mutations, live telemetry, and the higher-signal topology types.
+
+If you need the complete schema SDL instead of the guided summary below, print it directly from the current build:
+
+```bash
+# Against a running app
+runner-dev schema sdl --endpoint http://localhost:1337/graphql
+
+# Or in dry-run mode from a local entry file
+runner-dev schema sdl --entry-file src/main.ts
+```
+
+## Highlights
+
+- Introspection spans tasks, hooks, resources, events, tags, errors, async contexts, middleware, run options, and interceptor ownership.
+- Resource docs now include `isolation`, `subtree`, cooldown/ready/health flags, and resolved registrations.
+- Task docs include durable workflow metadata, `flowShape`, RPC lane summary, and runtime interceptor ownership.
+- Live telemetry includes logs, event emissions, errors, runs, process stats, and per-resource health reports.
+- Mutations cover task swapping, unswapping, task/event invocation, file editing, and guarded eval.
+
+## Query Root
+
+The current `Query` type exposes:
+
+- `root: Resource`
+- `runOptions: RunOptions!`
+- `interceptorOwners: InterceptorOwnersSnapshot!`
+- `all(idIncludes: ID): [BaseElement!]!`
+- `tags: [Tag!]!`
+- `tag(id: ID!): Tag`
+- `task(id: ID!): Task`
+- `tasks(idIncludes: ID): [Task!]!`
+- `hook(id: ID!): Hook`
+- `hooks(idIncludes: ID): [Hook!]!`
+- `resource(id: ID!): Resource`
+- `resources(idIncludes: ID): [Resource!]!`
+- `event(id: ID!): Event`
+- `events(filter: EventFilterInput): [Event!]!`
+- `middleware(id: ID!): Middleware`
+- `middlewares(idIncludes: ID): [Middleware!]!`
+- `taskMiddlewares(idIncludes: ID): [TaskMiddleware!]!`
+- `resourceMiddlewares(idIncludes: ID): [ResourceMiddleware!]!`
+- `error(id: ID!): Error`
+- `errors(idIncludes: ID): [Error!]!`
+- `asyncContext(id: ID!): AsyncContext`
+- `asyncContexts(idIncludes: ID): [AsyncContext!]!`
+- `live: Live!`
+- `diagnostics: [Diagnostic!]!`
+- `swappedTasks: [SwappedTask!]!`
+
+### Common Query Filters
+
+- `EventFilterInput`
+  - `hasNoHooks: Boolean`
+  - `hideSystem: Boolean`
+  - `idIncludes: String`
+- `RunFilterInput`
+  - `nodeKinds`, `nodeIds`, `ok`, `parentIds`, `rootIds`, `correlationIds`
+- `LogFilterInput`
+  - `levels`, `messageIncludes`, `correlationIds`
+- `EmissionFilterInput`
+  - `eventIds`, `emitterIds`, `correlationIds`
+- `ErrorFilterInput`
+  - `sourceKinds`, `sourceIds`, `messageIncludes`, `correlationIds`
+
+## Mutation Root
+
+The current `Mutation` type exposes:
+
+- `swapTask(taskId: ID!, runCode: String!): SwapResult!`
+- `unswapTask(taskId: ID!): SwapResult!`
+- `unswapAllTasks: [SwapResult!]!`
+- `invokeTask(taskId: ID!, inputJson: String, pure: Boolean = false, evalInput: Boolean = false): InvokeResult!`
+- `invokeEvent(eventId: ID!, inputJson: String, evalInput: Boolean = false): InvokeEventResult!`
+- `editFile(path: String!, content: String!): EditFileResult!`
+- `eval(code: String!): EvalResult!`
+
+### Mutation Notes
+
+- `swapTask` replaces a task's `run()` implementation at runtime.
+- `invokeTask` supports `pure: true` to bypass middleware.
+- `editFile` accepts structured paths such as `workspace:src/index.ts`.
+- `eval` is guarded and disabled in production unless `RUNNER_DEV_EVAL=1`.
+
+## Core Types
+
+### BaseElement
+
+Shared across tasks, hooks, resources, middleware, events, tags, errors, and async contexts:
+
+- `id`
+- `meta`
+- `filePath`
+- `fileContents(startLine, endLine)`
+- `markdownDescription`
+- `isPrivate`
+- `visibilityReason`
+- `tags`
+- `tagsDetailed`
+
+Many concrete element types also expose:
+
+- `coverage`
+- `coverageContents`
+- `registeredBy`
+- resolved variants such as `registeredByResolved`
+
+### Task
+
+Key fields:
+
+- `dependsOn`, `dependsOnResolved`
+- `middleware`, `middlewareResolved`, `middlewareResolvedDetailed`
+- `emits`, `emitsResolved`
+- `inputSchema`, `inputSchemaReadable`
+- `rpcLane`
+- `interceptorCount`, `hasInterceptors`, `interceptorOwnerIds`
+- `runs(afterTimestamp, last, filter)`
+- `isDurable`, `durableResource`, `flowShape`
+- `overriddenBy`, `registeredBy`
+
+The middleware usage objects now include subtree provenance details:
+
+- `TaskMiddlewareUsage.id`
+- `TaskMiddlewareUsage.config`
+- `TaskMiddlewareUsage.origin`
+- `TaskMiddlewareUsage.subtreeOwnerId`
+- `TaskMiddlewareUsage.node`
+
+### Hook
+
+Key fields:
+
+- `events`
+- `event` (deprecated singular form)
+- `hookOrder`
+- `dependsOn`, `depenendsOnResolved`
+- `middleware`, `middlewareResolvedDetailed`
+- `runs(...)`
+
+### Resource
+
+Key fields:
+
+- `dependsOn`, `dependsOnResolved`
+- `config`, `configSchema`, `configSchemaReadable`
+- `context`
+- `middleware`, `middlewareResolvedDetailed`
+- `overrides`, `overridesResolved`
+- `registers`, `registersResolved`
+- `usedBy`
+- `emits`
+- `registeredBy`, `registeredByResolved`
+- `hasCooldown`, `hasReady`, `hasHealthCheck`
+- `isolation`
+- `subtree`
+
+Important nested resource types:
+
+- `ResourceIsolation`
+  - `deny`
+  - `only`
+  - `whitelist`
+  - `exports`
+  - `exportsMode`
+- `ResourceSubtreePolicy`
+  - `tasks`
+  - `middleware`
+  - `resources`
+  - `hooks`
+  - `taskMiddleware`
+  - `resourceMiddleware`
+  - `events`
+  - `tags`
+
+Subtree policy now covers identity-aware summaries too:
+
+- `ResourceSubtreeTaskBranch.identity`
+- `ResourceSubtreeMiddlewareScope.identityScope`
+
+### Middleware
+
+The generic `Middleware` type exposes the combined view used by the introspector:
+
+- `autoApply`
+- `emits`
+- `configSchema`, `configSchemaReadable`
+- `usedByTasks`, `usedByTasksResolved`, `usedByTasksDetailed`
+- `usedByResources`, `usedByResourcesResolved`, `usedByResourcesDetailed`
+
+Specialized views:
+
+- `TaskMiddleware.usedBy`
+- `TaskMiddleware.usedByDetailed`
+- `ResourceMiddleware.usedBy`
+- `ResourceMiddleware.usedByDetailed`
+
+### Event
+
+Key fields:
+
+- `payloadSchema`, `payloadSchemaReadable`
+- `transactional`
+- `parallel`
+- `eventLane`
+- `rpcLane`
+- `emittedBy`, `emittedByResolved`
+- `listenedToBy`, `listenedToByResolved`
+- `registeredBy`, `registeredByResolved`
+
+### Tag
+
+Tags now fan out across the full model:
+
+- `configSchema`
+- `config`
+- `targets`
+- `tasks`
+- `hooks`
+- `resources`
+- `taskMiddlewares`
+- `resourceMiddlewares`
+- `events`
+- `errors`
+- `all`
+
+### Error
+
+Key fields:
+
+- `dataSchema`
+- `thrownBy`
+
+### AsyncContext
+
+Key fields:
+
+- `serialize`
+- `parse`
+- `usedBy`
+- `requiredBy`
+- `providedBy`
+
+### RunOptions
+
+Runner-dev now exposes effective startup/runtime settings through `runOptions`:
+
+- `mode`
+- `debug`, `debugMode`
+- `logsEnabled`, `logsPrintThreshold`, `logsPrintStrategy`, `logsBuffer`
+- `errorBoundary`
+- `shutdownHooks`
+- `dryRun`
+- `lazy`
+- `lifecycleMode`
+- `dispose`
+- `executionContext`
+- `hasOnUnhandledError`
+- `rootId`
+
+Nested types:
+
+- `RunDisposeOptions`
+  - `totalBudgetMs`
+  - `drainingBudgetMs`
+  - `cooldownWindowMs`
+- `RunExecutionContextOptions`
+  - `enabled`
+  - `cycleDetection`
+
+### InterceptorOwnersSnapshot
+
+Useful when debugging `taskDependency.intercept(...)` and middleware interceptors:
+
+- `tasksById`
+- `middleware.globalTaskInterceptorOwnerIds`
+- `middleware.globalResourceInterceptorOwnerIds`
+- `middleware.perTaskMiddlewareInterceptorOwnerIds`
+- `middleware.perResourceMiddlewareInterceptorOwnerIds`
+
+## Live Telemetry
+
+`live: Live!` exposes:
+
+- `memory: MemoryStats!`
+- `cpu: CpuStats!`
+- `eventLoop(reset: Boolean): EventLoopStats!`
+- `gc(windowMs: Float): GcStats!`
+- `logs(afterTimestamp, last, filter): [LogEntry!]!`
+- `emissions(afterTimestamp, last, filter): [EmissionEntry!]!`
+- `errors(afterTimestamp, last, filter): [ErrorEntry!]!`
+- `runs(afterTimestamp, last, filter): [RunRecord!]!`
+- `healthReport: ResourceHealthReport`
+
+Supporting types include:
+
+- `LogEntry`
+- `EmissionEntry`
+- `ErrorEntry`
+- `RunRecord`
+- `ResourceHealthReport`
+- `ResourceHealthTotals`
+- `ResourceHealthEntry`
+
+## Durable Workflow Types
+
+Durable tasks now surface extracted structure without execution:
+
+- `DurableFlowShape.nodes`
+- `FlowStepNode`
+- `FlowSleepNode`
+- `FlowSignalNode`
+- `FlowEmitNode`
+- `FlowSwitchNode`
+- `FlowNoteNode`
+
+## Diagnostics And Swap Types
+
+- `Diagnostic`
+  - `severity`
+  - `code`
+  - `message`
+  - `nodeId`
+  - `nodeKind`
+- `SwapResult`
+- `SwappedTask`
+- `InvokeResult`
+- `InvokeEventResult`
+- `EvalResult`
+- `EditFileResult`
+
+## Enums Worth Knowing
+
+- `LogLevelEnum`
+  - `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `log`
+- `SourceKindEnum`
+  - `TASK`, `HOOK`, `RESOURCE`, `MIDDLEWARE`, `INTERNAL`
+- `NodeKindEnum`
+  - `TASK`, `HOOK`
+- `MiddlewareApplyScope`
+  - `WHERE_VISIBLE`, `SUBTREE`
+- `IsolationExportsMode`
+  - `UNSET`, `NONE`, `LIST`
+- `TagTarget`
+  - `TASKS`, `RESOURCES`, `EVENTS`, `HOOKS`, `TASK_MIDDLEWARES`, `RESOURCE_MIDDLEWARES`, `ERRORS`
+- `ResourceHealthStatus`
+  - `healthy`, `degraded`, `unhealthy`
+
+## SDL Regeneration
+
+When this file drifts, regenerate your view from the actual schema rather than hand-guessing:
+
+```bash
+runner-dev schema sdl --endpoint http://localhost:1337/graphql
+```
+
+Or from the repo without a running server:
+
+```bash
+runner-dev schema sdl --entry-file src/main.ts
+```