@nwire/scan 0.10.1 → 0.11.0

package/dist/scan.d.ts

@@ -1,11 +1,11 @@
 /**
  * `@nwire/scan` — produces the `.nwire/` cache by inspecting booted apps.
  *
- * Each input must be a `ForgeApp` (or any object exposing `appName`,
- * `dispatcher()`, `container`, `runtime`). The scanner walks the
- * dispatcher metadata maps to collect actions, actors, projections,
- * queries, workflows, and external calls, and reads `container.list()`
- * for DI bindings + `runtime.listHooks()` for hooks.
+ * Each input is an `App` (or any object exposing `appName`, `container`,
+ * `runtime`). When forge is installed, the scanner walks the dispatcher
+ * metadata maps to collect actions, actors, projections, queries,
+ * workflows, and external calls. It also reads `container.list()` for
+ * DI bindings and `runtime.listHooks()` for hooks.
  *
  * Callers are responsible for booting their apps before scanning — the
  * forge plugin populates the dispatcher during `app.start()`.
@@ -18,9 +18,28 @@ export interface SourceLocationEntry {
 export interface ActionEntry {
     readonly name: string;
     readonly app: string;
-    readonly module?: string;
+    readonly description?: string;
     readonly public: boolean;
     readonly inputSchema?: unknown;
+    /** Event names this action emits, in declaration order. */
+    readonly emits: readonly string[];
+    /** True when a handler was wired via defineAction({handler}) — false for split definitions. */
+    readonly hasInlineHandler: boolean;
+    readonly persona?: string;
+    readonly journeyStep?: string;
+    readonly capability?: string;
+    readonly slo?: {
+        p95LatencyMs?: number;
+        successRate?: number;
+    };
+    readonly retry?: {
+        max: number;
+        backoff?: string;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    readonly policy?: string | readonly string[] | readonly [action: string, subject: string];
+    readonly tags?: readonly string[];
     readonly source?: SourceLocationEntry;
 }
 export interface ExternalCallEntry {
@@ -58,42 +77,62 @@ export interface WorkflowEntry {
     readonly name: string;
     readonly app: string;
     readonly public: boolean;
+    readonly description?: string;
+    /** Event names this workflow listens to. */
+    readonly subscribesTo: readonly string[];
+    /** Action names this workflow dispatches inside its body. */
+    readonly dispatches: readonly string[];
     readonly source?: SourceLocationEntry;
 }
 export interface EventEntry {
     readonly name: string;
     readonly app: string;
     readonly public: boolean;
+    readonly description?: string;
+    readonly version?: number;
+    /** Free-form labels for audience filtering ("product", "analytics", "partner-billing"). */
+    readonly audience?: readonly string[];
     readonly source?: SourceLocationEntry;
 }
 export interface ActorEntry {
     readonly name: string;
     readonly app: string;
+    /** State names declared in the actor's `states` map. */
+    readonly states: readonly string[];
     readonly source?: SourceLocationEntry;
 }
 export interface ProjectionEntry {
     readonly name: string;
     readonly app: string;
+    readonly description?: string;
+    /** Event names this projection folds in via its `listens` array. */
+    readonly listens: readonly string[];
     readonly source?: SourceLocationEntry;
 }
 export interface QueryEntry {
     readonly name: string;
     readonly app: string;
     readonly public: boolean;
-    readonly source?: SourceLocationEntry;
-}
-export interface ModuleEntry {
-    readonly name: string;
-    readonly app: string;
+    /** Name of the projection this query reads from (projection-form queries only). */
+    readonly projection?: string;
     readonly source?: SourceLocationEntry;
 }
 export interface AppEntry {
     readonly name: string;
     readonly description?: string;
-    readonly modules: readonly string[];
+    /** Plugin names installed on this app, in install order. */
+    readonly plugins: readonly string[];
     readonly tenantModel?: string;
     readonly tenantKey?: string;
 }
+export interface SinkEntry {
+    readonly name: string;
+    readonly app: string;
+    /** Adapter kind tag — "bullmq", "nats", "capture", etc. */
+    readonly kind?: string;
+    readonly position: "early" | "middle" | "terminal";
+    readonly direction: "outbound";
+}
 export interface RouteEntry {
     readonly method: string;
     readonly path: string;
@@ -161,7 +200,6 @@ export interface EventGraphEdge {
 export interface Cache {
     readonly generatedAt: string;
     readonly apps: readonly AppEntry[];
-    readonly modules: readonly ModuleEntry[];
     readonly actions: readonly ActionEntry[];
     readonly events: readonly EventEntry[];
     readonly actors: readonly ActorEntry[];
@@ -178,6 +216,7 @@ export interface Cache {
     readonly commands: readonly CommandEntry[];
     readonly hooks: readonly HookEntry[];
     readonly plugins: readonly PluginEntry[];
+    readonly sinks: readonly SinkEntry[];
     readonly bindings: readonly DIBindingEntry[];
     readonly resources: readonly ResourceEntry[];
     readonly errors: readonly ErrorEntry[];
@@ -221,7 +260,13 @@ export interface BuildCacheOptions {
 }
 interface ScannedApp {
     readonly appName: string;
+    readonly description?: string;
     dispatcher?: () => any;
+    /** Plugin definitions installed via createApp({plugins}) or .with(). */
+    readonly plugins?: readonly {
+        name: string;
+        $source?: SourceLocationEntry;
+    }[];
     container: {
         resolve?: <T = any>(name: string) => T;
         list?(): readonly {
@@ -238,6 +283,13 @@ interface ScannedApp {
             listeners: number;
             source?: SourceLocationEntry;
         }[];
+        listSinkStages?(): readonly {
+            name: string;
+            kind?: string;
+            position: "early" | "middle" | "terminal";
+            direction?: "outbound";
+        }[];
+        hooks?: Record<string, any>;
     };
 }
 export declare function buildCache(apps: readonly ScannedApp[], options?: BuildCacheOptions): Cache;

package/dist/scan.js

@@ -1,11 +1,11 @@
 /**
  * `@nwire/scan` — produces the `.nwire/` cache by inspecting booted apps.
  *
- * Each input must be a `ForgeApp` (or any object exposing `appName`,
- * `dispatcher()`, `container`, `runtime`). The scanner walks the
- * dispatcher metadata maps to collect actions, actors, projections,
- * queries, workflows, and external calls, and reads `container.list()`
- * for DI bindings + `runtime.listHooks()` for hooks.
+ * Each input is an `App` (or any object exposing `appName`, `container`,
+ * `runtime`). When forge is installed, the scanner walks the dispatcher
+ * metadata maps to collect actions, actors, projections, queries,
+ * workflows, and external calls. It also reads `container.list()` for
+ * DI bindings and `runtime.listHooks()` for hooks.
  *
  * Callers are responsible for booting their apps before scanning — the
  * forge plugin populates the dispatcher during `app.start()`.
@@ -41,6 +41,70 @@ function resolveDispatcher(app) {
 function sourceOf(value) {
     return value?.$source;
 }
+/**
+ * Coerce a Zod schema into a JSON-Schema-shaped `{ type, properties,
+ * required }` value Studio's form renderer + SchemaTree understand. The
+ * scanner doesn't carry a Zod dep, so we walk the runtime shape Zod 4
+ * publishes (`def.type`, `def.shape`, `def.innerType`, etc.) and project
+ * the bits Studio needs.
+ *
+ * Falls back to the raw value when the shape is unrecognisable so the
+ * SchemaTree's "raw JSON" view still shows something.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function zodToJsonSchema(schema) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    const s = schema;
+    const def = (s.def ?? s._def ?? {});
+    const type = String(def.type ?? "");
+    switch (type) {
+        case "object": {
+            const shape = (def.shape ?? {});
+            const properties = {};
+            const required = [];
+            for (const [key, raw] of Object.entries(shape)) {
+                const field = raw;
+                const inner = zodToJsonSchema(field);
+                properties[key] = inner;
+                // A field is required when its def isn't `optional`/`nullable`.
+                const innerType = (field.def ?? {}).type;
+                if (innerType !== "optional" && innerType !== "nullable") {
+                    required.push(key);
+                }
+            }
+            return { type: "object", properties, required };
+        }
+        case "string":
+            return { type: "string" };
+        case "number":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+        case "literal":
+            return { type: typeof def.value, enum: [def.value] };
+        case "enum": {
+            const opts = (def.entries ?? def.values ?? []);
+            return { type: "string", enum: opts };
+        }
+        case "array":
+            return { type: "array", items: zodToJsonSchema(def.element) };
+        case "optional":
+        case "nullable":
+        case "default":
+            return zodToJsonSchema(def.innerType);
+        case "union": {
+            const opts = (def.options ?? []);
+            return { anyOf: opts.map((o) => zodToJsonSchema(o)) };
+        }
+        case "record":
+            return { type: "object", additionalProperties: zodToJsonSchema(def.valueType) };
+        default:
+            // Unrecognised — return the raw shape so the SchemaTree at least
+            // shows the JSON, even if the form renderer can't drive it.
+            return schema;
+    }
+}
 function safeMap(map) {
     return map ?? new Map();
 }
@@ -48,7 +112,6 @@ export function buildCache(apps, options = {}) {
     const out = {
         generatedAt: new Date().toISOString(),
         apps: [],
-        modules: [],
         actions: [],
         events: [],
         actors: [],
@@ -65,6 +128,7 @@ export function buildCache(apps, options = {}) {
         commands: [],
         hooks: [],
         plugins: [],
+        sinks: [],
         bindings: [],
         resources: [],
         errors: [],
@@ -73,7 +137,32 @@ export function buildCache(apps, options = {}) {
     };
     const eventNamesSeen = new Set();
     for (const app of apps) {
-        out.apps.push({ name: app.appName, modules: [] });
+        const pluginNames = (app.plugins ?? []).map((p) => p.name);
+        out.apps.push({
+            name: app.appName,
+            description: app.description,
+            plugins: pluginNames,
+        });
+        // ── Plugins ─────────────────────────────────────────────────────
+        for (const plugin of app.plugins ?? []) {
+            out.plugins.push({
+                name: plugin.name,
+                kind: "plugin",
+                app: app.appName,
+                source: plugin.$source,
+            });
+        }
+        // ── Sink stages (outbound) ─────────────────────────────────────
+        const sinkStages = app.runtime?.listSinkStages?.() ?? [];
+        for (const stage of sinkStages) {
+            out.sinks.push({
+                name: stage.name,
+                app: app.appName,
+                kind: stage.kind,
+                position: stage.position,
+                direction: stage.direction ?? "outbound",
+            });
+        }
         const dispatcher = resolveDispatcher(app);
         if (!dispatcher) {
             // Plain HTTP App with no forge — the scanner has nothing to
@@ -84,20 +173,34 @@ export function buildCache(apps, options = {}) {
         const handlers = safeMap(dispatcher.handlers);
         for (const [name, handler] of handlers) {
             const action = handler.action ?? {};
+            const emits = (action.emits ?? []);
             out.actions.push({
                 name,
                 app: app.appName,
+                description: typeof action.description === "string" ? action.description : undefined,
                 public: Boolean(action.$public),
-                inputSchema: action.schema,
+                inputSchema: zodToJsonSchema(action.schema),
+                emits: emits.map((e) => String(e?.name ?? "")).filter(Boolean),
+                hasInlineHandler: typeof action.handler === "object" && action.handler !== null,
+                persona: typeof action.persona === "string" ? action.persona : undefined,
+                journeyStep: typeof action.journeyStep === "string" ? action.journeyStep : undefined,
+                capability: typeof action.capability === "string" ? action.capability : undefined,
+                slo: action.slo,
+                retry: action.retry,
+                policy: action.policy,
+                tags: action.tags,
                 source: sourceOf(action),
             });
-            for (const ev of (action.emits ?? [])) {
+            for (const ev of emits) {
                 if (ev?.name && !eventNamesSeen.has(ev.name)) {
                     eventNamesSeen.add(ev.name);
                     out.events.push({
                         name: ev.name,
                         app: app.appName,
                         public: Boolean(ev.$public),
+                        description: typeof ev.description === "string" ? ev.description : undefined,
+                        version: typeof ev.version === "number" ? ev.version : undefined,
+                        audience: Array.isArray(ev.audience) ? ev.audience : undefined,
                         source: sourceOf(ev),
                     });
                 }
@@ -109,19 +212,37 @@ export function buildCache(apps, options = {}) {
         // ── Actors ──────────────────────────────────────────────────────
         const actors = safeMap(dispatcher.actors);
         for (const [name, def] of actors) {
-            out.actors.push({ name, app: app.appName, source: sourceOf(def) });
+            const stateNames = def.states && typeof def.states === "object"
+                ? Object.keys(def.states)
+                : [];
+            out.actors.push({
+                name,
+                app: app.appName,
+                states: stateNames,
+                source: sourceOf(def),
+            });
         }
         // ── Projections + listened events ──────────────────────────────
         const projections = safeMap(dispatcher.projections);
         for (const [name, def] of projections) {
-            out.projections.push({ name, app: app.appName, source: sourceOf(def) });
-            for (const ev of (def.listens ?? [])) {
+            const listens = (def.listens ?? []);
+            out.projections.push({
+                name,
+                app: app.appName,
+                description: typeof def.description === "string" ? def.description : undefined,
+                listens: listens.map((e) => String(e?.name ?? "")).filter(Boolean),
+                source: sourceOf(def),
+            });
+            for (const ev of listens) {
                 if (ev?.name && !eventNamesSeen.has(ev.name)) {
                     eventNamesSeen.add(ev.name);
                     out.events.push({
                         name: ev.name,
                         app: app.appName,
                         public: Boolean(ev.$public),
+                        description: typeof ev.description === "string" ? ev.description : undefined,
+                        version: typeof ev.version === "number" ? ev.version : undefined,
+                        audience: Array.isArray(ev.audience) ? ev.audience : undefined,
                         source: sourceOf(ev),
                     });
                 }
@@ -133,10 +254,12 @@ export function buildCache(apps, options = {}) {
         // ── Queries ─────────────────────────────────────────────────────
         const queries = safeMap(dispatcher.queries);
         for (const [name, def] of queries) {
+            const proj = def.projection;
             out.queries.push({
                 name,
                 app: app.appName,
                 public: Boolean(def.$public),
+                projection: typeof proj?.name === "string" ? proj.name : undefined,
                 source: sourceOf(def),
             });
         }
@@ -144,10 +267,15 @@ export function buildCache(apps, options = {}) {
         const workflowDefs = dispatcher.listWorkflows?.() ?? [];
         for (const def of workflowDefs) {
             const name = String(def.name);
+            const subscribed = (def.subscribedEvents ?? new Set());
+            const dispatched = (def.dispatchedActions ?? new Set());
             out.workflows.push({
                 name,
                 app: app.appName,
                 public: Boolean(def.$public),
+                description: typeof def.description === "string" ? def.description : undefined,
+                subscribesTo: [...subscribed],
+                dispatches: [...dispatched],
                 source: sourceOf(def),
             });
             for (const evName of (def.subscribedEvents ?? new Set())) {
@@ -173,15 +301,37 @@ export function buildCache(apps, options = {}) {
             });
         }
         // ── Hooks ──────────────────────────────────────────────────────
-        const hooks = app.runtime?.listHooks?.() ?? [];
-        for (const h of hooks) {
-            out.hooks.push({
-                id: h.id,
-                name: h.name,
-                chain: h.chain,
-                listeners: h.listeners,
-                source: h.source,
-            });
+        // Prefer the structural listHooks helper if the runtime exposes one;
+        // otherwise walk `runtime.hooks` map and read step counts off each
+        // hook. Framework slots that haven't been materialised by a plugin
+        // (`runtime.defineHook(name)`) are absent — that's correct, we don't
+        // want to surface dead slots.
+        const explicit = app.runtime?.listHooks?.();
+        if (explicit) {
+            for (const h of explicit) {
+                out.hooks.push({
+                    id: h.id,
+                    name: h.name,
+                    chain: h.chain,
+                    listeners: h.listeners,
+                    source: h.source,
+                });
+            }
+        }
+        else if (app.runtime?.hooks) {
+            const hookMap = app.runtime.hooks;
+            for (const [slotName, hookValue] of Object.entries(hookMap)) {
+                if (!hookValue || typeof hookValue !== "object")
+                    continue;
+                const h = hookValue;
+                const counts = typeof h.stepCounts === "function" ? h.stepCounts() : { chain: 0, listeners: 0 };
+                out.hooks.push({
+                    id: h.id ?? slotName,
+                    name: slotName,
+                    chain: counts.chain,
+                    listeners: counts.listeners,
+                });
+            }
         }
     }
     // ── Routes (from passed-in interfaces) ────────────────────────────
@@ -198,13 +348,23 @@ export function buildCache(apps, options = {}) {
     for (const r of options.resources ?? []) {
         if ("definition" in r) {
             const def = r.definition;
-            out.resources.push({ name: String(def?.name ?? ""), app: r.app, module: r.module, source: sourceOf(def) });
+            out.resources.push({
+                name: String(def?.name ?? ""),
+                app: r.app,
+                module: r.module,
+                source: sourceOf(def),
+            });
         }
     }
     for (const e of options.errors ?? []) {
         if ("definition" in e) {
             const def = e.definition;
-            out.errors.push({ code: String(def?.code ?? ""), app: e.app, module: e.module, source: sourceOf(def) });
+            out.errors.push({
+                code: String(def?.code ?? ""),
+                app: e.app,
+                module: e.module,
+                source: sourceOf(def),
+            });
         }
     }
     for (const m of options.middleware ?? []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/scan",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Nwire — system registry scanner. Walks AppDefinition[] manifests and writes the .nwire/ cache (actions, events, actors, projections, queries, modules, routes, event graph). Vite plugin + standalone function.",
   "keywords": [
     "cache",
@@ -33,16 +33,16 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@nwire/hooks": "0.10.1",
-    "@nwire/messages": "0.10.1",
-    "@nwire/forge": "0.10.1"
+    "@nwire/forge": "0.11.0",
+    "@nwire/messages": "0.11.0",
+    "@nwire/hooks": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",
     "typescript": "^5.9.3",
     "vite": "npm:rolldown-vite@latest",
     "vitest": "^4.0.18",
-    "@nwire/container": "0.10.1"
+    "@nwire/container": "0.11.0"
   },
   "scripts": {
     "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",