@nwire/scan 0.13.2 → 0.13.3

package/dist/ast-extract.d.ts

@@ -12,7 +12,7 @@
  * workflows (including the workflow closure edge-walk and the projection /
  * workflow event-graph edges).
  */
-import type { ActionEntry, ActorEntry, CommandEntry, CronEntry, ErrorEntry, EventEntry, EventGraphEdge, ExternalCallEntry, InboundWebhookEntry, InboxEntry, OutboxEntry, ProjectionEntry, QueryEntry, ResourceEntry, SourceLocationEntry, WorkflowEntry } from "./scan.js";
+import type { ActionEntry, ActorEntry, CommandEntry, CronEntry, ErrorEntry, EventEntry, EventGraphEdge, ExternalCallEntry, HandlerEntry, InboundWebhookEntry, InboxEntry, OutboxEntry, ProjectionEntry, QueryEntry, ResourceEntry, SourceLocationEntry, WorkflowEntry } from "./scan.js";
 /** A `config/*.ts` module — its file and the top-level config field names it exposes. */
 export interface ConfigModuleEntry {
     readonly file: string;
@@ -27,13 +27,14 @@ export interface SchemaEntry {
     readonly source?: SourceLocationEntry;
 }
 export interface UnanalyzableEntry {
-    readonly kind: "event" | "action" | "actor" | "projection" | "query" | "workflow" | "command" | "cron" | "externalCall" | "inboundWebhook" | "outbox" | "inbox" | "resource" | "error" | "schema";
+    readonly kind: "event" | "action" | "handler" | "actor" | "projection" | "query" | "workflow" | "command" | "cron" | "externalCall" | "inboundWebhook" | "outbox" | "inbox" | "resource" | "error" | "schema";
     readonly reason: string;
     readonly source: SourceLocationEntry;
 }
 export interface AstExtract {
     readonly events: EventEntry[];
     readonly actions: ActionEntry[];
+    readonly handlers: HandlerEntry[];
     readonly actors: ActorEntry[];
     readonly projections: ProjectionEntry[];
     readonly queries: QueryEntry[];

package/dist/ast-extract.js

@@ -427,6 +427,7 @@ export function extractFromFiles(files, app = "") {
     const parsed = parse(files);
     const events = [];
     const actions = [];
+    const handlers = [];
     const actors = [];
     const projections = [];
     const queries = [];
@@ -659,6 +660,36 @@ export function extractFromFiles(files, app = "") {
             });
         });
     }
+    // ── Pass 2b: handlers ──
+    // The transport-core primitive. Same name shape as actions (positional or
+    // `{ name }`); no emits/projection contract — just the request→response unit.
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineHandler"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const cfg = configObject(node);
+            const name = actionName(node, cfg);
+            if (!name) {
+                unanalyzable.push({
+                    kind: "handler",
+                    reason: "non-literal or missing handler name",
+                    source: src,
+                });
+                return;
+            }
+            const handlerExpr = cfg ? prop(cfg, "handler") : undefined;
+            const calls = handlerExpr ? extractCalls(handlerExpr, externalCallNameByBinding) : [];
+            handlers.push({
+                name,
+                app,
+                public: isPublic(node),
+                description: cfg ? stringLiteral(prop(cfg, "description")) : undefined,
+                calls: calls.length ? calls : undefined,
+                source: src,
+            });
+        });
+    }
     // ── Pass 3: projections ──
     // After events so `listens`/`on` refs resolve. Records the projection
     // binding so queries (pass 5) can map a projection ref → its name.
@@ -982,6 +1013,7 @@ export function extractFromFiles(files, app = "") {
     return {
         events,
         actions,
+        handlers,
         actors,
         projections,
         queries,

package/dist/graph.js

@@ -82,6 +82,15 @@ export function buildGraph(ast, topology) {
             intent: { public: q.public },
             data: { projection: q.projection },
         });
+    for (const h of ast.handlers ?? [])
+        add({
+            id: nid("handler", h.name),
+            kind: "handler",
+            name: h.name,
+            source: h.source,
+            intent: { description: h.description, public: h.public },
+            data: { calls: h.calls },
+        });
     // Shared state-machine emit: state nodes + `transitions` edges (on event).
     // `from: "*"` (always-active) is rooted at the machine node itself.
     const emitStates = (machineKind, machineName, declaredStates, transitions) => {
@@ -180,6 +189,9 @@ export function buildGraph(ast, topology) {
         for (const c of a.calls ?? [])
             edge(nid("action", a.name), nid("externalCall", c), "calls");
     }
+    for (const h of ast.handlers ?? [])
+        for (const c of h.calls ?? [])
+            edge(nid("handler", h.name), nid("externalCall", c), "calls");
     for (const ed of ast.graph.events) {
         switch (ed.via) {
             case "emits":

package/dist/manifest.d.ts

@@ -16,7 +16,7 @@ import { type AstExtract } from "./ast-extract.js";
 import { type Topology } from "./topology.js";
 import { type ManifestModel } from "./graph.js";
 /** Bumped when the manifest shape changes, so readers can detect a stale file. */
-export declare const MANIFEST_VERSION: 3;
+export declare const MANIFEST_VERSION: 4;
 /**
  * The project manifest — the static AST graph (events/actions/queries/actors/
  * workflows/projections + positions + event-causation edges) plus, when built

package/dist/manifest.js

@@ -19,7 +19,7 @@ import { extractFromFiles } from "./ast-extract.js";
 import { captureTopology } from "./topology.js";
 import { buildGraph } from "./graph.js";
 /** Bumped when the manifest shape changes, so readers can detect a stale file. */
-export const MANIFEST_VERSION = 3;
+export const MANIFEST_VERSION = 4;
 const SKIP_DIRS = new Set(["node_modules", "dist", ".nwire", ".git", ".vitepress", "__tests__"]);
 /**
  * Recursively collect non-test `.ts` source files under `root` — the input to

package/dist/registry-codegen.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Build-time registry codegen — the production half of auto-discovery.
+ *
+ * At runtime, `@nwire/app`'s `discoverPrimitives` walks `app/` with `node:fs`
+ * and dynamic `import()`. That's perfect for dev/test and Node production, but
+ * it costs a filesystem scan at every boot and doesn't work in a bundle (no
+ * `node:fs`, no dynamic dir import) — edge targets and single-file builds.
+ *
+ * This module generates a *static* registry: a tiny ESM source that imports
+ * every app primitive with plain `import * as` statements and classifies the
+ * real exported values via `@nwire/app`'s `classifyModules`. A bundler folds
+ * those static imports into the output, so production boots with zero fs scan
+ * and zero dynamic import — and it works anywhere ESM does.
+ *
+ * Equivalence is structural, not asserted: the codegen reuses the same
+ * `collectFiles` (which files count) and the generated module calls the same
+ * `classifyModules` (how exports map to kinds) that the runtime scan uses.
+ * There is no second copy of the rules to drift.
+ *
+ *   buildStart / load("virtual:nwire-registry")
+ *     → generateRegistryModule(appDir)
+ *     → import { classifyModules } from "@nwire/app"
+ *       import * as _m0 from "/abs/app/create-item.action.ts"
+ *       ...
+ *       export const registry = classifyModules([_m0, ...])
+ */
+/** The virtual module specifier the runtime imports and the plugin resolves. */
+export declare const REGISTRY_MODULE_ID = "virtual:nwire-registry";
+export interface RegistryCodegenOptions {
+    /**
+     * Absolute path to the app source root to scan. Defaults to `<cwd>/app`.
+     * The same directory `createApp({ discover })` walks at runtime.
+     */
+    readonly root?: string;
+}
+/**
+ * Generate the ESM source for the static registry module. Walks `root` for
+ * primitive files (using the runtime's own `collectFiles` rules) and emits a
+ * module that statically imports each and classifies them with the runtime's
+ * `classifyModules`.
+ *
+ * Returns a valid module even when no files are found — the registry is just
+ * empty, so `createApp` can fall through to whatever explicit arrays it has.
+ */
+export declare function generateRegistryModule(options?: RegistryCodegenOptions): string;

package/dist/registry-codegen.js

@@ -0,0 +1,62 @@
+/**
+ * Build-time registry codegen — the production half of auto-discovery.
+ *
+ * At runtime, `@nwire/app`'s `discoverPrimitives` walks `app/` with `node:fs`
+ * and dynamic `import()`. That's perfect for dev/test and Node production, but
+ * it costs a filesystem scan at every boot and doesn't work in a bundle (no
+ * `node:fs`, no dynamic dir import) — edge targets and single-file builds.
+ *
+ * This module generates a *static* registry: a tiny ESM source that imports
+ * every app primitive with plain `import * as` statements and classifies the
+ * real exported values via `@nwire/app`'s `classifyModules`. A bundler folds
+ * those static imports into the output, so production boots with zero fs scan
+ * and zero dynamic import — and it works anywhere ESM does.
+ *
+ * Equivalence is structural, not asserted: the codegen reuses the same
+ * `collectFiles` (which files count) and the generated module calls the same
+ * `classifyModules` (how exports map to kinds) that the runtime scan uses.
+ * There is no second copy of the rules to drift.
+ *
+ *   buildStart / load("virtual:nwire-registry")
+ *     → generateRegistryModule(appDir)
+ *     → import { classifyModules } from "@nwire/app"
+ *       import * as _m0 from "/abs/app/create-item.action.ts"
+ *       ...
+ *       export const registry = classifyModules([_m0, ...])
+ */
+import { collectFiles } from "@nwire/app";
+/** The virtual module specifier the runtime imports and the plugin resolves. */
+export const REGISTRY_MODULE_ID = "virtual:nwire-registry";
+/** Normalize a filesystem path to a forward-slash import specifier. */
+function toImportSpecifier(file) {
+    return file.replace(/\\/g, "/");
+}
+/**
+ * Generate the ESM source for the static registry module. Walks `root` for
+ * primitive files (using the runtime's own `collectFiles` rules) and emits a
+ * module that statically imports each and classifies them with the runtime's
+ * `classifyModules`.
+ *
+ * Returns a valid module even when no files are found — the registry is just
+ * empty, so `createApp` can fall through to whatever explicit arrays it has.
+ */
+export function generateRegistryModule(options = {}) {
+    const root = options.root ?? `${process.cwd()}/app`;
+    const files = collectFiles(root).map(toImportSpecifier).sort();
+    const imports = files.map((f, i) => `import * as _m${i} from ${JSON.stringify(f)};`);
+    const list = files.map((_, i) => `_m${i}`).join(", ");
+    return [
+        "// AUTO-GENERATED by @nwire/scan registry codegen — do not edit.",
+        "// Statically imports every app primitive so production registers them",
+        "// with no filesystem scan and no dynamic import (bundle/edge-safe).",
+        'import { classifyModules } from "@nwire/app";',
+        ...imports,
+        "",
+        `export const registry = classifyModules([${list}]);`,
+        "export const handlers = registry.handlers;",
+        "export const actors = registry.actors;",
+        "export const projections = registry.projections;",
+        "export const workflows = registry.workflows;",
+        "",
+    ].join("\n");
+}

package/dist/scan.d.ts

@@ -87,6 +87,21 @@ export interface CommandEntry {
     readonly app: string;
     readonly source?: SourceLocationEntry;
 }
+/**
+ * A `defineHandler(...)` — the transport-core primitive ("one handler, every
+ * transport"). Distinct from actions/queries: a handler has no projection
+ * backing and no event emission contract; it's the plain request→response unit
+ * any transport can dispatch.
+ */
+export interface HandlerEntry {
+    readonly name: string;
+    readonly app: string;
+    readonly public: boolean;
+    readonly description?: string;
+    /** External-call names invoked in the handler body. */
+    readonly calls?: readonly string[];
+    readonly source?: SourceLocationEntry;
+}
 export interface WorkflowEntry {
     readonly name: string;
     readonly app: string;
@@ -230,6 +245,7 @@ export interface EventGraphEdge {
 }
 export { buildManifest, writeManifest, readManifest, collectSourceFiles, MANIFEST_VERSION, type Manifest, } from "./manifest.js";
 export { extractFromFiles, collectConfigModules, type AstExtract, type SchemaEntry, type ConfigModuleEntry as AstConfigModuleEntry, } from "./ast-extract.js";
+export { generateRegistryModule, REGISTRY_MODULE_ID, type RegistryCodegenOptions, } from "./registry-codegen.js";
 export { captureTopology, type Topology, type CapabilityInfo, type StageInfo, type PluginInfo, type BindingInfo, type HandlerInfo, type HookInfo, type ContributionInfo, type TriggerInfo, } from "./topology.js";
 export { buildGraph, type ManifestModel, type GraphNode, type GraphEdge, type GraphIntent, type EdgeType, } from "./graph.js";
 export { listTelemetryRuns, readTelemetryRun, type TelemetryRunMeta } from "./telemetry-runs.js";

package/dist/scan.js

@@ -10,6 +10,7 @@
 // equivalence harness proves they match.
 export { buildManifest, writeManifest, readManifest, collectSourceFiles, MANIFEST_VERSION, } from "./manifest.js";
 export { extractFromFiles, collectConfigModules, } from "./ast-extract.js";
+export { generateRegistryModule, REGISTRY_MODULE_ID, } from "./registry-codegen.js";
 export { captureTopology, } from "./topology.js";
 export { buildGraph, } from "./graph.js";
 export { listTelemetryRuns, readTelemetryRun } from "./telemetry-runs.js";

package/dist/vite-plugin.d.ts

@@ -1,10 +1,17 @@
 /**
- * Vite/unplugin form — emit the build-time manifest.
+ * Vite/unplugin form — the build-side of nwire discovery. Two jobs:
  *
- * On build start and on dev-server start (re-emitted as `.ts` source changes),
- * walks the project's source tree with the AST extractor and writes
- * `.nwire/manifest.json`. No app boot — "scan the graph, not the runtime."
- * Serves the live manifest at `/__nwire/manifest` in dev.
+ *  1. **Descriptive manifest** — on build/dev start (and on `.ts` change),
+ *     walk the source tree with the AST extractor and write
+ *     `.nwire/manifest.json` for Studio. No app boot — "scan the graph, not
+ *     the runtime." Also served live at `/__nwire/manifest` in dev.
+ *
+ *  2. **Registry codegen** — resolve the `virtual:nwire-registry` module to a
+ *     static-import registry of every `app/` primitive. `createApp({ discover })`
+ *     imports this first, so a production bundle registers handlers/actors/etc.
+ *     with zero filesystem scan and zero dynamic import (edge-safe). In dev/test
+ *     without this plugin the import simply fails and `createApp` falls back to
+ *     the runtime fs-scan — same result, slower path.
  */
 import type { Plugin } from "vite";
 export interface NwireManifestPluginOptions {
@@ -14,6 +21,18 @@ export interface NwireManifestPluginOptions {
     readonly app?: string;
     /** Output directory for `manifest.json`. Default `.nwire`. */
     readonly outDir?: string;
+    /**
+     * App primitive root for registry codegen. Defaults to `<root>/app`. Set to
+     * `false` to disable codegen and only emit the descriptive manifest.
+     */
+    readonly appDir?: string | false;
+    /**
+     * Emit + serve the descriptive `.nwire/manifest.json`. Default `true`. Set to
+     * `false` when a host already owns that pipeline (the `nwire dev` host runs
+     * its own richer scan with runtime fold) — the plugin then only resolves the
+     * `virtual:nwire-registry` module.
+     */
+    readonly manifest?: boolean;
 }
 export declare function nwireManifestPlugin(options?: NwireManifestPluginOptions): Plugin;
 /** @deprecated Use {@link nwireManifestPlugin}. Kept so existing imports resolve. */

package/dist/vite-plugin.js

@@ -1,25 +1,61 @@
 /**
- * Vite/unplugin form — emit the build-time manifest.
+ * Vite/unplugin form — the build-side of nwire discovery. Two jobs:
  *
- * On build start and on dev-server start (re-emitted as `.ts` source changes),
- * walks the project's source tree with the AST extractor and writes
- * `.nwire/manifest.json`. No app boot — "scan the graph, not the runtime."
- * Serves the live manifest at `/__nwire/manifest` in dev.
+ *  1. **Descriptive manifest** — on build/dev start (and on `.ts` change),
+ *     walk the source tree with the AST extractor and write
+ *     `.nwire/manifest.json` for Studio. No app boot — "scan the graph, not
+ *     the runtime." Also served live at `/__nwire/manifest` in dev.
+ *
+ *  2. **Registry codegen** — resolve the `virtual:nwire-registry` module to a
+ *     static-import registry of every `app/` primitive. `createApp({ discover })`
+ *     imports this first, so a production bundle registers handlers/actors/etc.
+ *     with zero filesystem scan and zero dynamic import (edge-safe). In dev/test
+ *     without this plugin the import simply fails and `createApp` falls back to
+ *     the runtime fs-scan — same result, slower path.
  */
 import { buildManifest, writeManifest } from "./manifest.js";
+import { generateRegistryModule, REGISTRY_MODULE_ID } from "./registry-codegen.js";
 export function nwireManifestPlugin(options = {}) {
     const outDir = options.outDir ?? ".nwire";
     let root = options.root ?? process.cwd();
+    let isBuild = false;
+    // Rollup convention: prefix a resolved virtual id with `\0` so other plugins
+    // leave it alone and it never hits the filesystem resolver.
+    const resolvedRegistryId = `\0${REGISTRY_MODULE_ID}`;
+    const appDirFor = () => options.appDir || `${root}/app`;
     return {
         name: "nwire:manifest",
         configResolved(config) {
             if (!options.root && config.root)
                 root = config.root;
+            isBuild = config.command === "build";
+        },
+        // Always resolve the virtual id so the literal `import("virtual:nwire-registry")`
+        // in `@nwire/app` never hard-fails a Vite build or dev server.
+        resolveId(id) {
+            if (id === REGISTRY_MODULE_ID)
+                return resolvedRegistryId;
+            return null;
+        },
+        // Bake the static registry into production builds. In dev (serve) or when
+        // codegen is off, emit a null registry so `createApp` falls back to the
+        // runtime fs-scan — fresh on every change, HMR-friendly.
+        load(id) {
+            if (id !== resolvedRegistryId)
+                return null;
+            if (isBuild && options.appDir !== false) {
+                return generateRegistryModule({ root: appDirFor() });
+            }
+            return "export const registry = null;\n";
         },
         async buildStart() {
+            if (options.manifest === false)
+                return;
             await writeManifest(buildManifest(root, options.app), outDir);
         },
         async configureServer(server) {
+            if (options.manifest === false)
+                return;
             const emit = () => writeManifest(buildManifest(root, options.app), outDir);
             await emit();
             const onChange = (file) => {

package/package.json

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