@bluelibs/runner-dev 6.1.0 → 6.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluelibs/runner-dev",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "BlueLibs Runner DevTools",
   "main": "dist/index.js",
   "repository": {
@@ -11,34 +11,42 @@
     "build": "tsc -p config/ts/tsconfig.json && npm run build:ui",
     "watch": "tsc -p config/ts/tsconfig.json -w",
     "clean": "rm -rf dist",
+    "skills:pack:materialize": "node ./scripts/pack-npm-skills.mjs materialize",
+    "skills:pack:restore": "node ./scripts/pack-npm-skills.mjs restore",
     "cli": "ts-node --project config/ts/tsconfig.json src/cli.ts",
+    "cli:local": "ts-node --project config/ts/tsconfig.json src/cli.ts",
     "start": "node dist/main.js",
-    "dev": "ts-node-dev --project config/ts/tsconfig.json --respawn --transpile-only --watch src --watch scripts src/main.ts",
+    "dev": "tsx watch --tsconfig config/ts/tsconfig.json src/main.ts",
     "build:ui": "cd src/ui && vite build",
     "dev:ui": "cd src/ui && vite",
     "preview:ui": "cd src/ui && vite preview --port 5173",
     "build:ui:watch": "cd src/ui && vite build --watch --clearScreen=false",
-    "play:server": "ts-node-dev --project config/ts/tsconfig.json --respawn --transpile-only src/__tests__/dummy/dummyServer.ts --watch src/**/*",
+    "play:server": "tsx watch --tsconfig config/ts/tsconfig.json src/__tests__/dummy/dummyServer.ts",
     "test": "jest --config config/jest/jest.config.js --verbose --runInBand",
+    "test:qa": "node ./scripts/run-jest-summary.mjs",
     "test:dev": "jest --config config/jest/jest.config.js --verbose --watch",
     "coverage": "jest --config config/jest/jest.config.js --verbose --coverage",
     "test:clean": "jest --config config/jest/jest.config.js --clearCache",
     "testonly": "npm test",
     "test:ci": "npm run build && npm run test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "node scripts/check-runner-dependency.mjs && npm run build",
     "typedoc": "typedoc --options config/typedoc/typedoc.json",
     "lint": "eslint src --config config/eslint/eslint.config.mjs",
     "lint:fix": "eslint src --config config/eslint/eslint.config.mjs --fix",
-    "qa": "npm run lint:fix && npm run build && npm run test && npm run typedoc",
+    "qa": "npm run lint:fix && npm run typecheck && npm run build && npm run test:qa && npm run typedoc",
     "coverage:ai": "jest --config config/jest/jest.config.js --coverage --coverageReporters=text-summary",
     "codegen": "graphql-codegen --config config/codegen.ts",
     "prebuild": "ts-node --project config/ts/tsconfig.json scripts/sync-version.ts && npm run codegen",
     "play": "concurrently -k -n UI,SRV -c blue,green \"npm:build:ui:watch\" \"npm:play:server\"",
     "play:cli": "npm run play:server",
+    "play:export": "ts-node --project config/ts/tsconfig.json src/__tests__/dummy/exportPlayCatalog.ts",
     "demo:ping": "ENDPOINT=http://localhost:31337/graphql node dist/cli.js ping",
     "demo:query": "ENDPOINT=http://localhost:31337/graphql node dist/cli.js query 'query { tasks { id } }' --format pretty",
     "demo:overview": "ENDPOINT=http://localhost:31337/graphql node dist/cli.js overview --details 5",
-    "sync:docs": "ts-node --project config/ts/tsconfig.json scripts/sync-docs.ts"
+    "postinstall": "npm-skills extract --skip-production --override",
+    "prepack": "npm run build && npm run skills:pack:materialize",
+    "postpack": "npm run skills:pack:restore"
   },
   "bin": {
     "runner-dev": "dist/cli.js"
@@ -57,7 +65,7 @@
     "@types/benchmark": "^2.1.5",
     "@types/express": "^5.0.3",
     "@types/graphql": "^0.11.3",
-    "@types/jest": "^27.0.0",
+    "@types/jest": "^30.0.0",
     "@types/marked": "^5.0.2",
     "@types/node": "^20.0.0",
     "@types/react": "^18.3.11",
@@ -75,7 +83,7 @@
     "eslint-plugin-jest": "^29.12.2",
     "eslint-plugin-prettier": "3.1.1",
     "globals": "^15.15.0",
-    "jest": "^29.0.0",
+    "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "jest-junit": "^10.0.0",
     "marked": "^16.2.1",
@@ -86,9 +94,9 @@
     "reflect-metadata": "^0.2.2",
     "sass-embedded": "^1.90.0",
     "supertest": "^7.1.4",
-    "ts-jest": "^29.0.0",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
-    "ts-node-dev": "^2.0.0",
+    "tsx": "^4.20.5",
     "typedoc": "^0.26.7",
     "typedoc-material-theme": "^1.1.0",
     "typescript": "^5.6.2",
@@ -104,7 +112,6 @@
     "@adobe/jsonschema2md": "^8.0.5",
     "@apollo/server": "^5.0.0",
     "@as-integrations/express5": "^1.1.2",
-    "@bluelibs/runner": "^6.1.0",
     "@bluelibs/smart": "^2.2.1",
     "@modelcontextprotocol/sdk": "^1.17.2",
     "@types/prismjs": "^1.26.5",
@@ -116,7 +123,8 @@
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "zod": "3.25.76",
-    "zod-to-json-schema": "^3.24.6"
+    "zod-to-json-schema": "^3.24.6",
+    "npm-skills": "^0.4.0"
   },
   "overrides": {
     "react": "18.3.1",
@@ -126,6 +134,13 @@
       "react-dom": "18.3.1"
     }
   },
+  "npmSkills": {
+    "consume": {
+      "only": [
+        "@bluelibs/runner"
+      ]
+    }
+  },
   "prettier": {
     "trailingComma": "es5",
     "tabWidth": 2,
@@ -141,5 +156,8 @@
         }
       }
     ]
+  },
+  "peerDependencies": {
+    "@bluelibs/runner": "^6.3.3"
   }
 }

package/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
+```