@nwire/cli 0.12.0 → 0.13.0

package/dist/lib/dev-host.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The one-Vite dev host — `nwire dev`'s single process.
+ *
+ * A programmatic Vite server that loads the wire via `ssrLoadModule` (real TS
+ * + HMR, no `vite-node` child) and serves, on ONE port:
+ *   - the wire's HTTP surface — mounted as Connect-style middleware from
+ *     each adapter's transport-agnostic `handler()`. Adapters self-dispatch:
+ *     if they don't own a URL they call `next()` and the next handler (or
+ *     Vite's middleware chain) gets a shot. No prefix hard-coding in the host.
+ *   - the Studio data API (`/__nwire/*`) — served from the in-process runtime
+ *     directly via `studio-host-api.ts`. No disk/proxy indirection.
+ *   - the built Studio SPA (everything else, with SPA fallback).
+ *
+ * PROD IS UNTOUCHED: the wire's `main.ts` still calls `endpoint().run()`. This
+ * host only sets `globalThis.__nwireDevHost` before loading it, which flips the
+ * endpoint into mount-without-listen mode and hands back the booted app(s) +
+ * each adapter's `(req,res,next)` handler. Non-HTTP transports (queue/cron/nats)
+ * just run in-process; the host never names a transport.
+ *
+ * ## HMR reload model
+ *
+ * When a file that feeds the wire changes, Vite emits a `change` event on its
+ * watcher. The host:
+ *   1. Acquires a reload lock — concurrent file saves are coalesced into one
+ *      reload; any in-flight reload is let complete before the next starts.
+ *   2. Stops all booted apps in reverse order (mirrors the prod shutdown loop).
+ *   3. Invalidates the changed module and its entire import chain in Vite's SSR
+ *      module graph so the next `ssrLoadModule` re-evaluates from disk.
+ *   4. Resets `mounts[]` and re-calls `ssrLoadModule(entry)` so the new wire
+ *      is collected afresh.
+ *   5. Atomically swaps `wireHandlers` (a `let` the request handler closure
+ *      reads) so in-flight requests are not interrupted.
+ *
+ * There is no double-boot risk: step 2 tears down the previous generation
+ * before step 4 boots the next. The global collector is reset in step 4 before
+ * loading so stale collect() calls from the previous generation are inert.
+ *
+ * Studio's own assets are the built SPA (static, served by sirv) — HMR for
+ * the wire source does not affect the Studio bundle.
+ */
+import { type Server } from "node:http";
+import { type ViteDevServer } from "vite";
+import type { DevHostMount } from "@nwire/endpoint";
+export interface DevHostOptions {
+    /** Project root — Vite's root + where the wire + `.nwire/` live. */
+    readonly cwd: string;
+    /** Wire entry, root-relative (e.g. `/app/main.ts`). */
+    readonly entry: string;
+    /** Port for the single HTTP front. */
+    readonly port: number;
+    /** Bind host. Default `127.0.0.1`. */
+    readonly host?: string;
+    /**
+     * Initial active endpoint name. When provided, the host will front that
+     * endpoint's HTTP handlers. Defaults to the first mount with HTTP handlers.
+     */
+    readonly activeEndpoint?: string;
+}
+export interface DevHost {
+    readonly vite: ViteDevServer;
+    readonly server: Server;
+    /** What each loaded endpoint handed over (one per `endpoint().run()`). */
+    readonly mounts: readonly DevHostMount[];
+    /** Name of the currently active HTTP front (or undefined when none present). */
+    readonly activeEndpointName: string | undefined;
+    /**
+     * Switch the active HTTP front at runtime. Throws when no mount with the
+     * given name exists. The change takes effect on the next incoming request.
+     */
+    setActiveEndpoint(name: string): void;
+    close(): Promise<void>;
+}
+/**
+ * Determine which mount should front the HTTP surface.
+ *
+ * Selection rules (in order):
+ *   1. When `preferredName` is given, use the mount with that name (if it has HTTP handlers).
+ *   2. Otherwise pick the first mount that carries at least one HTTP handler.
+ *   3. When no mount has HTTP handlers, fall back to the first mount (for non-HTTP projects).
+ *
+ * Returns `undefined` when `mounts` is empty.
+ */
+export declare function resolveActiveMount(mounts: readonly DevHostMount[], preferredName?: string): DevHostMount | undefined;
+/**
+ * Boot the dev host. Registers the dev-host collector, loads the wire (which
+ * mounts port-less + collects), then serves the wire + Studio on one port.
+ */
+export declare function startDevHost(opts: DevHostOptions): Promise<DevHost>;

package/dist/lib/dev-host.js

@@ -0,0 +1,426 @@
+/**
+ * The one-Vite dev host — `nwire dev`'s single process.
+ *
+ * A programmatic Vite server that loads the wire via `ssrLoadModule` (real TS
+ * + HMR, no `vite-node` child) and serves, on ONE port:
+ *   - the wire's HTTP surface — mounted as Connect-style middleware from
+ *     each adapter's transport-agnostic `handler()`. Adapters self-dispatch:
+ *     if they don't own a URL they call `next()` and the next handler (or
+ *     Vite's middleware chain) gets a shot. No prefix hard-coding in the host.
+ *   - the Studio data API (`/__nwire/*`) — served from the in-process runtime
+ *     directly via `studio-host-api.ts`. No disk/proxy indirection.
+ *   - the built Studio SPA (everything else, with SPA fallback).
+ *
+ * PROD IS UNTOUCHED: the wire's `main.ts` still calls `endpoint().run()`. This
+ * host only sets `globalThis.__nwireDevHost` before loading it, which flips the
+ * endpoint into mount-without-listen mode and hands back the booted app(s) +
+ * each adapter's `(req,res,next)` handler. Non-HTTP transports (queue/cron/nats)
+ * just run in-process; the host never names a transport.
+ *
+ * ## HMR reload model
+ *
+ * When a file that feeds the wire changes, Vite emits a `change` event on its
+ * watcher. The host:
+ *   1. Acquires a reload lock — concurrent file saves are coalesced into one
+ *      reload; any in-flight reload is let complete before the next starts.
+ *   2. Stops all booted apps in reverse order (mirrors the prod shutdown loop).
+ *   3. Invalidates the changed module and its entire import chain in Vite's SSR
+ *      module graph so the next `ssrLoadModule` re-evaluates from disk.
+ *   4. Resets `mounts[]` and re-calls `ssrLoadModule(entry)` so the new wire
+ *      is collected afresh.
+ *   5. Atomically swaps `wireHandlers` (a `let` the request handler closure
+ *      reads) so in-flight requests are not interrupted.
+ *
+ * There is no double-boot risk: step 2 tears down the previous generation
+ * before step 4 boots the next. The global collector is reset in step 4 before
+ * loading so stale collect() calls from the previous generation are inert.
+ *
+ * Studio's own assets are the built SPA (static, served by sirv) — HMR for
+ * the wire source does not affect the Studio bundle.
+ */
+import { createServer as createHttpServer, } from "node:http";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import sirv from "sirv";
+import { createServer as createViteServer } from "vite";
+import { createStudioHostApi } from "./studio-host-api.js";
+// ── Active-endpoint selection helpers ────────────────────────────────────────
+/**
+ * Determine which mount should front the HTTP surface.
+ *
+ * Selection rules (in order):
+ *   1. When `preferredName` is given, use the mount with that name (if it has HTTP handlers).
+ *   2. Otherwise pick the first mount that carries at least one HTTP handler.
+ *   3. When no mount has HTTP handlers, fall back to the first mount (for non-HTTP projects).
+ *
+ * Returns `undefined` when `mounts` is empty.
+ */
+export function resolveActiveMount(mounts, preferredName) {
+    if (mounts.length === 0)
+        return undefined;
+    // Preferred by name
+    if (preferredName !== undefined) {
+        const byName = mounts.find((m) => m.name === preferredName);
+        if (byName)
+            return byName;
+    }
+    // First with HTTP handlers
+    const firstHttp = mounts.find((m) => m.handlers.length > 0);
+    if (firstHttp)
+        return firstHttp;
+    // Fallback: first mount (non-HTTP project)
+    return mounts[0];
+}
+/** Resolve the Studio SPA dist dir.
+ *
+ * Resolution order:
+ *  1. Bundled copy vendored into the CLI's own dist/studio at build time —
+ *     the normal path for any scaffolded app (no @nwire/studio dep needed).
+ *  2. Consumer project's node_modules — for projects that install @nwire/studio
+ *     explicitly (dev-deps workflow, in-repo hacking).
+ *  3. CLI's own node_modules — covers the framework workspace dev loop.
+ */
+function resolveStudioDist(cwd) {
+    // 1. Bundled inside the CLI's own dist/studio.
+    const bundled = resolve(dirname(fileURLToPath(import.meta.url)), "..", "studio");
+    if (existsSync(bundled))
+        return bundled;
+    // 2 & 3. Fall back to resolving @nwire/studio from node_modules.
+    const tryFrom = (base) => {
+        try {
+            const pkg = createRequire(base).resolve("@nwire/studio/package.json");
+            const dist = resolve(dirname(pkg), "dist");
+            return dist;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return tryFrom(resolve(cwd, "package.json")) ?? tryFrom(fileURLToPath(import.meta.url));
+}
+/**
+ * Wrap a raw `(req, res)` adapter handler as a Connect-style handler.
+ *
+ * Koa's `callback()` (and equivalents) already behave like a Connect-style
+ * middleware for routes they don't own — they respond with 404 for unknown
+ * routes rather than calling a next function. We normalise them here: if the
+ * handler writes a 404 status without any body, we treat that as "not owned"
+ * and call `next()` instead, so the host's chain continues.
+ *
+ * Most adapters already short-circuit on their owned prefix; this wrapper is
+ * defensive — it ensures unknown routes fall through cleanly in all cases.
+ */
+function toConnectHandler(raw) {
+    return (req, res, next) => {
+        // Intercept the response to detect a "not found" pass-through from the adapter.
+        let headerWritten = false;
+        const origWriteHead = res.writeHead.bind(res);
+        const origWrite = res.write.bind(res);
+        const origEnd = res.end.bind(res);
+        // Track whether the adapter wrote a real response body.
+        let bodyWritten = false;
+        let capturedStatus;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        res.writeHead = (statusCode, ...args) => {
+            capturedStatus = statusCode;
+            headerWritten = true;
+            return origWriteHead(statusCode, ...args);
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        res.write = (...args) => {
+            bodyWritten = true;
+            return origWrite(...args);
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        res.end = (...args) => {
+            // Restore patched methods before deciding
+            res.writeHead = origWriteHead;
+            res.write = origWrite;
+            res.end = origEnd;
+            // Effective status: `capturedStatus` when the adapter called writeHead()
+            // explicitly; otherwise fall back to `res.statusCode` (Koa sets this
+            // directly without ever calling writeHead before end).
+            const effectiveStatus = capturedStatus ?? res.statusCode;
+            const firstArg = args[0];
+            // "Not Found" is Koa's default catch-all body for unmatched routes (Koa
+            // sets res.statusCode = 404 and calls res.end("Not Found") directly,
+            // never calling writeHead). Treat it as "not mine" so the host's chain
+            // continues to Vite + sirv.
+            const isDefaultNotFound = firstArg === "Not Found" ||
+                (firstArg instanceof Buffer && firstArg.toString() === "Not Found");
+            const hasBody = bodyWritten ||
+                (!isDefaultNotFound &&
+                    firstArg !== undefined &&
+                    firstArg !== null &&
+                    firstArg !== "" &&
+                    !(firstArg instanceof Function));
+            // If the adapter signalled a 404 with no meaningful body and no prior
+            // writes, treat as "not mine" and fall through to the next handler in
+            // the chain (Vite → sirv). Otherwise commit the response.
+            if (effectiveStatus !== 404 || hasBody) {
+                return origEnd(...args);
+            }
+            // Hand the socket to the next handler in the chain (Vite → sirv).
+            //
+            // Koa sets response headers (Content-Type, Content-Length, x-correlation-id, etc.)
+            // on `res` BEFORE calling `res.end`. When we intercept and redirect to `next()`,
+            // those stale headers must be removed so sirv can write a fresh 200 response.
+            // Otherwise the client reads the wrong Content-Length and misparses the body.
+            //
+            // Koa (and other async-middleware frameworks) also schedule a `handleResponse`
+            // call on the next microtask tick. By the time that fires, `res.writableEnded`
+            // will be `true` (sirv's write completed), so Node's internal http machinery
+            // silently ignores the second end() call. No guard needed.
+            for (const name of res.getHeaderNames()) {
+                res.removeHeader(name);
+            }
+            res.statusCode = 200;
+            next();
+        };
+        raw(req, res);
+    };
+}
+// ── Reload helpers ───────────────────────────────────────────────────────────
+/**
+ * Drain all mounts in reverse-registration order, mirroring the prod shutdown
+ * loop. Each mount's `shutdown()` tears down its adapters (reverse) then its
+ * apps — so non-HTTP transports (queue/cron/nats) that started in-process get
+ * cleaned up, not just the apps. Errors are swallowed so a single failing mount
+ * doesn't block the rest (reload + close must always continue).
+ */
+async function stopMounts(mounts, reason = "dev-host") {
+    for (let i = mounts.length - 1; i >= 0; i--) {
+        try {
+            await mounts[i].shutdown(reason);
+        }
+        catch {
+            // Swallow — reload/close must continue even if one mount fails to drain.
+        }
+    }
+}
+/**
+ * Invalidate a changed file and its entire SSR import chain in Vite's module
+ * graph. This ensures `ssrLoadModule` re-evaluates from disk on the next call
+ * rather than returning a stale cached module.
+ */
+function invalidateModuleGraph(vite, file) {
+    const mods = vite.moduleGraph.getModulesByFile(file);
+    if (!mods)
+        return;
+    for (const mod of mods) {
+        vite.moduleGraph.invalidateModule(mod);
+    }
+}
+/**
+ * Boot the dev host. Registers the dev-host collector, loads the wire (which
+ * mounts port-less + collects), then serves the wire + Studio on one port.
+ */
+export async function startDevHost(opts) {
+    // `mounts` is the live array that `createStudioHostApi` reads on every request.
+    // It is replaced (reset + repopulated) on each HMR reload without the server
+    // or the Studio handler needing to be recreated.
+    const mounts = [];
+    // `activeEndpointName` tracks which mount is fronting the HTTP surface.
+    // Reads are synchronous (the request handler closure snaps it per request).
+    // Writes take effect immediately — the next request sees the new front.
+    let activeEndpointName = opts.activeEndpoint;
+    // Install the global collector. The endpoint reads this and hands back its
+    // apps + handlers without binding a port.
+    function installCollector() {
+        globalThis.__nwireDevHost = {
+            collect: (m) => mounts.push(m),
+        };
+    }
+    installCollector();
+    const vite = await createViteServer({
+        root: opts.cwd,
+        // Disable consumer vite.config.ts discovery — the host only needs Vite for
+        // SSR module loading + the HMR client. Pulling in frontend plugins (vue,
+        // tailwind, svelte) would slow boot and may conflict with the SSR pipeline.
+        configFile: false,
+        server: { middlewareMode: true },
+        appType: "custom",
+        logLevel: "warn",
+    });
+    // `wireHandlers` is a `let` so reloads can atomically swap the reference the
+    // request handler closure reads without re-creating the HTTP server.
+    let wireHandlers = [];
+    // `activeOwns` answers "does the wire own this URL path?" for the active
+    // mount. When present, the host routes owned paths to the wire and everything
+    // else straight to Studio — no response-sniffing. Undefined when the adapter
+    // doesn't compute ownership; the host then runs handlers + sniffs a 404.
+    let activeOwns;
+    /** Point the HTTP front at a resolved mount (handlers + ownership). */
+    function adoptMount(mount) {
+        wireHandlers = (mount?.handlers ?? []).map((h) => toConnectHandler(h));
+        activeOwns = mount?.owns;
+    }
+    async function loadEntry() {
+        await vite.ssrLoadModule(opts.entry);
+        // Re-resolve the active mount after each (re)load. When the user specified
+        // a preferred name, honour it; otherwise fall back to the first HTTP mount.
+        const active = resolveActiveMount(mounts, activeEndpointName);
+        activeEndpointName = active?.name;
+        // Only the active mount's handlers front the HTTP surface. Other mounts
+        // (workers/cron/non-HTTP) still run in-process and are observable via
+        // telemetry + manifest.
+        adoptMount(active);
+    }
+    // Initial load — boot the wire for the first time.
+    await loadEntry();
+    // ── Studio data API ─────────────────────────────────────────────────────
+    // `mounts` is passed by reference — the API reads the current snapshot on
+    // every request, so it automatically picks up the new runtime after a reload.
+    // The getter/setter let the endpoints route switch the active front at runtime.
+    const studioApi = createStudioHostApi({
+        mounts,
+        cwd: opts.cwd,
+        getActiveEndpointName: () => activeEndpointName,
+        setActiveEndpoint: (name) => {
+            const target = mounts.find((m) => m.name === name);
+            if (!target)
+                throw new Error(`No mounted endpoint named "${name}"`);
+            activeEndpointName = name;
+            adoptMount(target);
+        },
+    });
+    // ── Studio SPA (static) ─────────────────────────────────────────────────
+    const studioDist = resolveStudioDist(opts.cwd);
+    const serveStudio = studioDist ? sirv(studioDist, { single: true, dev: false }) : undefined;
+    // ── HTTP server ─────────────────────────────────────────────────────────
+    // Serve Vite + the built Studio SPA (with SPA fallback). The tail of the
+    // request chain for any path the wire does not own.
+    const serveStudioChain = (req, res) => {
+        // Vite middlewares (transform/HMR client) first, then the built SPA.
+        vite.middlewares(req, res, () => {
+            if (serveStudio) {
+                serveStudio(req, res, () => {
+                    res.statusCode = 404;
+                    res.end("not found");
+                });
+            }
+            else {
+                res.statusCode = 404;
+                res.end("@nwire/studio not found");
+            }
+        });
+    };
+    const server = createHttpServer((req, res) => {
+        const pathname = new URL(req.url ?? "/", "http://x").pathname;
+        // 1. Studio data API — in-process runtime, no disk/proxy indirection.
+        if (studioApi(req, res))
+            return;
+        // 2. When the active mount declares ownership, route deterministically:
+        //    a path the wire doesn't own (`/`, Studio assets + deep links) goes
+        //    straight to Studio — even when the wire has adopter-wide auth that
+        //    would otherwise 401 every path and shadow Studio.
+        if (activeOwns && !activeOwns(pathname)) {
+            serveStudioChain(req, res);
+            return;
+        }
+        // 3. Wire HTTP surface — Connect-style chain. Each adapter self-dispatches:
+        //    if it doesn't own the URL it calls next() and the chain continues.
+        //    The toConnectHandler 404-sniff covers adapters without `owns`.
+        const handlers = wireHandlers; // read the current generation
+        let idx = 0;
+        const next = () => {
+            const h = handlers[idx++];
+            if (h) {
+                h(req, res, next);
+            }
+            else {
+                // 4. Fall through to Vite + the built Studio SPA.
+                serveStudioChain(req, res);
+            }
+        };
+        next();
+    });
+    // ── HMR reload loop ─────────────────────────────────────────────────────
+    //
+    // When any file that feeds the wire changes, Vite emits `change`. We:
+    //   1. Acquire a reload lock (one in-flight reload at a time; concurrent
+    //      saves coalesce — the last queued reload wins).
+    //   2. Stop the current apps (reverse order, mirrors prod shutdown).
+    //   3. Invalidate the changed file in Vite's SSR module graph.
+    //   4. Reset `mounts[]` and re-execute the entry.
+    //   5. Atomically update `wireHandlers` so the request handler sees the
+    //      new generation immediately.
+    //
+    // The global collector is reinstalled in step 4 (via `installCollector`)
+    // before `loadEntry` runs so any stale collect() calls from the old
+    // generation write into the freshly-reset `mounts[]`.
+    let reloading = false;
+    let pendingReload = false;
+    async function reload(changedFile) {
+        if (reloading) {
+            // Another reload is in flight — mark that a further reload is needed
+            // once the current one completes. This coalesces rapid saves.
+            pendingReload = true;
+            return;
+        }
+        reloading = true;
+        try {
+            // Stop the previous generation of apps.
+            await stopMounts(mounts);
+            // Reset the collector target and invalidate the module graph.
+            mounts.length = 0;
+            invalidateModuleGraph(vite, changedFile);
+            installCollector();
+            await loadEntry();
+        }
+        catch (err) {
+            // A load error (syntax/runtime) leaves `wireHandlers` empty until the
+            // user fixes the source. Log clearly; keep the server alive so the
+            // watcher can retry on the next save.
+            console.error("[nwire dev] reload failed:", err);
+        }
+        finally {
+            reloading = false;
+        }
+        if (pendingReload) {
+            pendingReload = false;
+            // Re-run with a sentinel path — the full module graph was already
+            // invalidated by the previous reload; an additional invalidation of the
+            // entry covers any further changes.
+            await reload(opts.entry);
+        }
+    }
+    vite.watcher.on("change", (file) => {
+        // Only reload when the changed file is part of the loaded SSR module
+        // graph. Changes to Studio assets (already built) are irrelevant.
+        const mods = vite.moduleGraph.getModulesByFile(file);
+        if (!mods?.size)
+            return;
+        void reload(file);
+    });
+    // ── Listen ──────────────────────────────────────────────────────────────
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, opts.host ?? "127.0.0.1", resolve);
+    });
+    return {
+        vite,
+        server,
+        mounts,
+        get activeEndpointName() {
+            return activeEndpointName;
+        },
+        setActiveEndpoint(name) {
+            const target = mounts.find((m) => m.name === name);
+            if (!target)
+                throw new Error(`No mounted endpoint named "${name}"`);
+            activeEndpointName = name;
+            adoptMount(target);
+        },
+        async close() {
+            // Stop accepting new connections first.
+            await new Promise((r) => server.close(() => r()));
+            // Close Vite (stops the watcher + HMR WebSocket).
+            await vite.close();
+            // Drain the current wire generation cleanly.
+            await stopMounts(mounts);
+        },
+    };
+}

package/dist/lib/ensure-built.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Keep workspace `dist/` fresh — but only inside the framework monorepo.
+ *
+ * Inside the nwire repo, examples link to `@nwire/*` via the source
+ * packages' built `dist/`. Nothing rebuilds those on `nwire dev` / `nwire
+ * studio`, so a stale `dist` surfaces as runtime crashes like
+ * `captureSourceLocation is not a function`. Real consumer apps install
+ * prebuilt `@nwire/*` from npm and must never trigger a build — so this is
+ * a strict no-op outside the monorepo.
+ */
+/**
+ * Walk up from `start` looking for the nwire monorepo root: a directory
+ * that has BOTH a `pnpm-workspace.yaml` AND the `@nwire/*` source packages
+ * (`packages/core-runtime/src`). The second check is what distinguishes
+ * the framework repo from an arbitrary consumer monorepo that merely
+ * happens to use pnpm workspaces — those install nwire prebuilt and must
+ * not be rebuilt.
+ *
+ * Returns the repo root, or `undefined` when `start` is not inside the
+ * framework monorepo.
+ */
+export declare function findMonorepoRoot(start: string): string | undefined;
+/**
+ * Ensure the workspace `@nwire/*` packages are built before a dev session.
+ * No-op outside the framework monorepo. Inside it, runs the turbo-backed
+ * `pnpm build` from the repo root — which is a ~200ms no-op when everything
+ * is fresh and only rebuilds what changed otherwise.
+ *
+ * A failing build is surfaced as a warning but never hard-blocks: a partial
+ * build still beats refusing to start, and the user sees the error inline.
+ */
+export declare function ensureWorkspaceBuilt(cwd?: string): void;

package/dist/lib/ensure-built.js

@@ -0,0 +1,62 @@
+/**
+ * Keep workspace `dist/` fresh — but only inside the framework monorepo.
+ *
+ * Inside the nwire repo, examples link to `@nwire/*` via the source
+ * packages' built `dist/`. Nothing rebuilds those on `nwire dev` / `nwire
+ * studio`, so a stale `dist` surfaces as runtime crashes like
+ * `captureSourceLocation is not a function`. Real consumer apps install
+ * prebuilt `@nwire/*` from npm and must never trigger a build — so this is
+ * a strict no-op outside the monorepo.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { palette } from "./colors.js";
+import { execSync } from "./exec.js";
+/**
+ * Walk up from `start` looking for the nwire monorepo root: a directory
+ * that has BOTH a `pnpm-workspace.yaml` AND the `@nwire/*` source packages
+ * (`packages/core-runtime/src`). The second check is what distinguishes
+ * the framework repo from an arbitrary consumer monorepo that merely
+ * happens to use pnpm workspaces — those install nwire prebuilt and must
+ * not be rebuilt.
+ *
+ * Returns the repo root, or `undefined` when `start` is not inside the
+ * framework monorepo.
+ */
+export function findMonorepoRoot(start) {
+    let dir = resolve(start);
+    // Guard against symlink loops / odd filesystems with a generous bound.
+    for (let depth = 0; depth < 64; depth++) {
+        const hasWorkspace = existsSync(resolve(dir, "pnpm-workspace.yaml"));
+        const hasSource = existsSync(resolve(dir, "packages", "core-runtime", "src"));
+        if (hasWorkspace && hasSource)
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Ensure the workspace `@nwire/*` packages are built before a dev session.
+ * No-op outside the framework monorepo. Inside it, runs the turbo-backed
+ * `pnpm build` from the repo root — which is a ~200ms no-op when everything
+ * is fresh and only rebuilds what changed otherwise.
+ *
+ * A failing build is surfaced as a warning but never hard-blocks: a partial
+ * build still beats refusing to start, and the user sees the error inline.
+ */
+export function ensureWorkspaceBuilt(cwd = process.cwd()) {
+    const root = findMonorepoRoot(cwd);
+    if (!root)
+        return; // consumer app — installs prebuilt @nwire/*, never build.
+    // eslint-disable-next-line no-console
+    console.log(palette.dim("  ensuring workspace build…"));
+    const code = execSync("pnpm", ["build"], { cwd: root, quiet: true });
+    if (code !== 0) {
+        // eslint-disable-next-line no-console
+        console.warn(palette.warn("  workspace build reported errors — continuing anyway.") +
+            palette.dim(` (pnpm build exited ${code} in ${root})`));
+    }
+}

package/dist/lib/ensure-scan.d.ts

@@ -4,9 +4,14 @@
  * every CLI command that reads the scan cache.
  *
  * Cheap path: compute fingerprint, compare to saved; if match, return.
- * Expensive path: spawn the cache-runner under vite-node to rebuild,
- * then save the new fingerprint. The expensive path runs at most once
- * per source change.
+ * Expensive path: rebuild the manifest IN-PROCESS via `@nwire/scan`'s
+ * `buildManifest` + `writeManifest` — a pure static scan of the source
+ * tree plus the folded `.nwire/topology.json` a running app self-emits.
+ * No app boot, no loader, no subprocess.
+ *
+ * If `.nwire/topology.json` is absent (the app has never run), the
+ * manifest still writes — static-only; the topology layer fills in the
+ * next time the app runs and re-emits.
  */
 export interface EnsureScanOptions {
     /**
@@ -25,4 +30,4 @@ export interface EnsureScanResult {
     /** The fingerprint that's now saved on disk. */
     readonly fingerprint: string;
 }
-export declare function ensureScanFresh(cwd?: string, opts?: EnsureScanOptions): EnsureScanResult;
+export declare function ensureScanFresh(cwd?: string, opts?: EnsureScanOptions): Promise<EnsureScanResult>;