@nwire/scan

Walks AppDefinition[] and produces the .nwire/ cache — the framework's static-reflection layer.

Reads every action / event / actor / projection / query / workflow / module / resolver / route / orchestrator-primitive / hook / plugin / DI binding across all registered apps and emits a set of JSON files under .nwire/. Studio reads these; the CLI reads these; codegen reads these. Rebuilt from scratch on each invocation (a few ms for hundreds of definitions).

pnpm add @nwire/scan

Quick example

import { buildCache, writeCache } from "@nwire/scan";
import { allApps } from "../apps";

const cache = buildCache(allApps, { mounts: rest.listMounts() });
await writeCache(cache, ".nwire");

Most users go through the CLI: nwire cache.

Emitted files

writeCache(cache, ".nwire") produces:

| File | Contents | | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | manifest.json | The whole Cache object — single read for tools that want it all. | | apps.json / modules.json | App + module surface (name, paths, members, source). | | actions.json | Per-action: schema, retry, policy, emits, persona, journeyStep, SLO, source. | | events.json | Per-event: schema, audience, outcome, visibility, source. | | actors.json | Per-actor: schema, states, methods, timers, stuckThresholds, SLA. | | projections.json / queries.json | Read-side definitions. | | resolvers.json / routes.json | Resolver bindings + their HTTP mount tuples (passed via BuildCacheOptions.mounts). | | models.json / errors.json / middleware.json | Interface-layer primitives — defineResource / defineError / defineMiddleware values passed via BuildCacheOptions.resources / .errors / .middleware. | | workflows.json | Reaction + saga definitions. | | external-calls.json / inbound-webhooks.json / outboxes.json / inboxes.json / crons.json | Orchestrator primitives. | | commands.json | Operator-script defineCommand entries. | | hooks.json | One entry per hook() instantiated in the process at scan time (id, name, chain count, listener count, source). | | plugins.json | One entry per registered plugin OR module (kind: "plugin" | "module"). | | di.json | One row per container binding visible at scan time (name, kind, source). | | graph.json | Cross-module event-graph edges (publisher → subscriber). |

Surface

| Export | Role | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | buildCache(apps, options?) | Returns the Cache object (every entry list + graph). | | writeCache(cache, dir) | Persist the cache as JSON files in dir. | | BuildCacheOptions | { mounts?: ResolverMount[] } — pass HTTP mount tuples in. | | zodToJsonSchema(schema) | Internal helper, exported for downstream schema tooling. | | Entry types | ActionEntry, EventEntry, ActorEntry, ProjectionEntry, QueryEntry, WorkflowEntry, ResolverEntry, RouteEntry, ModuleEntry, AppEntry, HookEntry, PluginEntry, DIBindingEntry, CommandEntry, ExternalCallEntry, InboundWebhookEntry, OutboxEntry, InboxEntry, CronEntry, EventGraphEdge, SourceLocationEntry. | | Cache | Top-level shape; manifest.json is JSON.stringify(cache). |

Hook + plugin + DI introspection

• hooks.json is snapshotted from listHooks() after the consumer's apps have loaded — runtime construction, plugin registration, and module wiring all create hooks during import, so the snapshot covers the full extension surface.
• plugins.json distinguishes plugins from modules-compiled-as-plugins via the kind field so Studio can render each with the right affordances.
• di.json walks app.container.list() defensively (older apps that predate list() are skipped silently).

Related

• @nwire/forge — provides the AppDefinition shape buildCache walks.
• @nwire/hooks — listHooks() is the source for hooks.json.
• @nwire/cli — nwire cache invokes this package; nwire ls / nwire studio read its output.
• @nwire/studio — reads .nwire/manifest.json to render every page.
• @nwire/mcp — read-only inspect tools fall back to .nwire/*.json when no live wire is mounted.

Status

v0.x — every entry type and emitted file is additive; new fields land as minor bumps. The cache contract IS the framework's static API for tooling.