@entrinsik/vite-plugin-informer 2.10.0 → 2.12.0

package/README.md

@@ -13,6 +13,8 @@ npm run dev                                # local dev against the Informer in .
 npm run deploy                             # assemble + upload + deploy
 ```
 
+`informer-init` leaves an existing `@entrinsik/vite-plugin-informer` entry alone, and writes one only when the dependency is missing — in which case it uses its own version (2.12.0 and later; before that it wrote `^1.0.0`). A project scaffolded earlier still carries `^1.0.0`, which resolves to 1.0.5 and predates everything below: bump it by hand.
+
 ## What a deploy ships
 
 The assembler uploads your built frontend plus these source trees, matching how an App's library is structured in Informer:
@@ -23,7 +25,7 @@ The assembler uploads your built frontend plus these source trees, matching how
 | `webhooks/` | Publicly callable webhook routes |
 | `tools/` | AI tools, private to the App's agents |
 | `mcp/` | Tools exposed over the App's MCP endpoint |
-| `channels/` | Live channel join/leave handlers |
+| `channels/` | Live channel handlers: `join` / `joined` / `leave` and event-named handlers for `channel.send()`; `npm run dev` runs them locally, and the `channels:` block in `informer.yaml` declares relays only (each entry needs `on`) |
 | `migrations/` | Workspace database migrations, run in order on deploy |
 | `embeddings/` | Declarative embedding use cases (see below) |
 | `lib/`, `shared/` | Modules importable by the trees above |
@@ -44,6 +46,8 @@ Against an older server the CLI:
 
 A server whose version isn't comparable (a `dev` build, or an `/about` behind a proxy) is treated as current and warned about — gating it would break deploys to builds made from source.
 
+App Channels phase 2 (plugin ≥ 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless; plugin 2.12.0 aligns its channel semantics with the server's (wildcard gating, replay expiry, and the per-user send budget), so on 2.11.0 the dev mirror has the phase 2 surface but not all of its behavior.
+
 Feature-detect at runtime with optional chaining, since `platform` is absent entirely before 2026.1.3:
 
 ```javascript
@@ -116,11 +120,11 @@ const hits = await query(
 
 ### Dev loop
 
-`npm run deploy` uploads `embeddings/` like any other source tree — there is no manifest block to add (plugin ≥ 2.10.0; earlier versions never upload the folder, so the use case silently does not exist on the server). `npm run dev` never runs the pump, and its `embed()` throws an explanation rather than embedding (the dev mirror reports `platform.capabilities.embeddings: false`), so a search route is exercised against a deployed App. Feature-detect with `platform?.capabilities?.embeddings` — `typeof embed === 'function'` is true on both, since the binding exists either way. Then, in the App admin panel, the **Embeddings** tab lists each use case with its pump status (queued, running, up to date, last run, last error, skipped docs) and a **Run now** action; the same surface exists as API routes (`GET /apps/{id}/embeddings`, `POST /apps/{id}/embeddings/{name}/_run`). Deploy, run, read the error, fix, repeat.
+`npm run deploy` uploads `embeddings/` like any other source tree — there is no manifest block to add (plugin ≥ 2.10.0; earlier versions never upload the folder, so the use case silently does not exist on the server). `npm run dev` never runs the pump, and its `embed()` throws an explanation rather than embedding (the dev mirror reports `platform.capabilities.embeddings: false`), so a search route is exercised against a deployed App. Plugin ≥ 2.12.0 can opt in: `informer({ mock: { platform: { capabilities: { embeddings: true } } } })` binds the dev `embed()` to the deployed App's `_embed` route on the configured server (addressed by package.json `informer.id`; the dev credentials need write access to that App, and each call is billed to it), so the query vector under `npm run dev` is the deployed one — same model, same `revision`. The corpus is not: `query()` still reads the dev workspace datasource, which the pump never writes to, so a search route compares a deployed vector against local rows. Feature-detect with `platform?.capabilities?.embeddings` — `typeof embed === 'function'` is true on both, since the binding exists either way. Then, in the App admin panel, the **Embeddings** tab lists each use case with its pump status (queued, running, up to date, last run, last error, skipped docs) and a **Run now** action; the same surface exists as API routes (`GET /apps/{id}/embeddings`, `POST /apps/{id}/embeddings/{name}/_run`). Deploy, run, read the error, fix, repeat.
 
 ### Upgrading an App that already has an `embeddings/` folder
 
-`embeddings/` is a server-side folder from this release on, like `server/`: its files are uploaded with the library, never served to browsers, and scanned as pump handlers. An App that kept anything else there (assets, data files) loses those files in the browser after redeploying with plugin 2.10.0 or later. A `.js` file there that exports `GET` or `POST` but not both fails the deploy; one that exports neither is never scanned as a use case at all and lands as a warning on an otherwise successful deploy. Move such content elsewhere before upgrading; the deploy names every stray entry as a warning.
+`embeddings/` is a server-side folder from Informer 2026.1.3 on, like `server/`: its files are uploaded with the library, never served to browsers, and scanned as pump handlers. An App that kept anything else there (assets, data files) loses those files in the browser after redeploying with plugin 2.10.0 or later. A `.js` file there that exports `GET` or `POST` but not both fails the deploy; one that exports neither is never scanned as a use case at all and lands as a warning on an otherwise successful deploy. Move such content elsewhere before upgrading; the deploy names every stray entry as a warning.
 
 ### Older Informer releases
 

package/bin/init.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { readFile, writeFile, access } from 'node:fs/promises';
 import { resolve, basename } from 'node:path';
 import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
@@ -118,6 +118,16 @@ function prompt(question, defaultValue) {
     });
 }
 
+/**
+ * The devDependency range a fresh scaffold gets. Read inside init() rather than
+ * at module scope so a failure reaches init()'s error handler.
+ */
+async function pluginVersionRange() {
+    const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    if (!version) throw new Error('could not read the version of @entrinsik/vite-plugin-informer; reinstall the plugin');
+    return `^${version}`;
+}
+
 /**
  * Convert package name to friendly display name.
  * "magic-quickbooks-report" -> "Magic Quickbooks Report"
@@ -174,7 +184,8 @@ async function init() {
     // 5. Add plugin to dependencies if not present
     if (!pkg.devDependencies) pkg.devDependencies = {};
     if (!pkg.devDependencies['@entrinsik/vite-plugin-informer']) {
-        pkg.devDependencies['@entrinsik/vite-plugin-informer'] = '^1.0.0';
+        // Float the scaffold on the version that scaffolded it, not a fixed range.
+        pkg.devDependencies['@entrinsik/vite-plugin-informer'] = await pluginVersionRange();
         console.log('Added @entrinsik/vite-plugin-informer to devDependencies');
     }
 

package/bin/workspace.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { resolve, basename } from 'node:path';
 import { createClient } from '../src/client.js';
-import { loadEnv, envWritePath, parseModeArg } from '../src/env.js';
+import { loadEnv, envWritePath, localEnvValue, parseModeArg } from '../src/env.js';
 import { init, migrate, reset } from '../src/workspace.js';
 
 const mode = parseModeArg(process.argv);
@@ -41,12 +41,22 @@ const api = createClient({ baseUrl, apiKey, user, pass });
 const migrationsDir = resolve('migrations');
 const envPath = envWritePath({ mode });
 
+// loadEnv walks up to a parent .env (monorepo config), so process.env may
+// carry ANOTHER app's workspace id. Only this app's own env file decides
+// whether it is initialized; migrate/reset fall back to the inherited value.
+const localWorkspaceId = localEnvValue('INFORMER_DEV_WORKSPACE', { mode });
+const inheritedWorkspaceId = process.env.INFORMER_DEV_WORKSPACE || null;
+if (!localWorkspaceId && inheritedWorkspaceId && command === 'init') {
+    console.log(`Ignoring INFORMER_DEV_WORKSPACE=${inheritedWorkspaceId} inherited from the environment: ${basename(envPath)} does not define it.`);
+}
+const workspaceId = localWorkspaceId || inheritedWorkspaceId;
+
 try {
     if (command === 'init') {
         // Check if already initialized
-        if (process.env.INFORMER_DEV_WORKSPACE) {
-            console.error(`Workspace already initialized: ${process.env.INFORMER_DEV_WORKSPACE}`);
-            console.error('Run workspace:reset to start fresh, or remove INFORMER_DEV_WORKSPACE from .env to re-initialize.');
+        if (localWorkspaceId) {
+            console.error(`Workspace already initialized: ${localWorkspaceId}`);
+            console.error(`Run workspace:reset to start fresh, or remove INFORMER_DEV_WORKSPACE from ${basename(envPath)} to re-initialize.`);
             process.exit(1);
         }
 
@@ -72,7 +82,6 @@ try {
         await init({ api, slug, migrationsDir, envPath });
 
     } else if (command === 'migrate') {
-        const workspaceId = process.env.INFORMER_DEV_WORKSPACE;
         if (!workspaceId) {
             console.error('No dev workspace found. Run workspace:init first.');
             process.exit(1);
@@ -80,7 +89,6 @@ try {
         await migrate({ api, workspaceId, migrationsDir });
 
     } else if (command === 'reset') {
-        const workspaceId = process.env.INFORMER_DEV_WORKSPACE;
         if (!workspaceId) {
             console.error('No dev workspace found. Run workspace:init first.');
             process.exit(1);

package/index.d.ts

@@ -15,11 +15,25 @@ export interface AppDevBinding {
     app?: string;
 }
 
+/**
+ * What the platform offers the app, as the server injects it
+ * (`window.__INFORMER__.platform`). A mock override merges into the dev
+ * defaults, so naming one capability leaves the rest alone.
+ */
+export interface MockPlatform {
+    version?: string;
+    originMode?: boolean;
+    capabilities?: Record<string, boolean>;
+}
+
 export interface InformerPluginOptions {
     mock?: {
         report?: { id?: string; name?: string };
         theme?: 'light' | 'dark';
         roles?: string[];
+        /** The viewer identity, for testing `@user/<username>` channels as someone else. */
+        user?: { username?: string; displayName?: string };
+        platform?: MockPlatform;
     };
     devBindings?: Record<string, string | AppDevBinding>;
     proxy?: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.10.0",
+    "version": "2.12.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "scripts": {
         "test": "node --test"

package/src/agent-dev.js

@@ -4,15 +4,7 @@ import { parse as parseUrl } from 'node:url';
 import yaml from 'yaml';
 import { manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
 import { createDevChannels, createDevEmit } from './dev-channels.js';
-import { devPlatform } from './dev-platform.js';
-
-// embed() is present on a real install even without the embeddings
-// capability, where it throws a written explanation. Mirroring that here
-// keeps the dev failure the same lesson as the deployed one, instead of a
-// bare "embed is not a function" that reads like a missing binding.
-const embed = async () => {
-    throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
-};
+import { devPlatform, createDevEmbed } from './dev-platform.js';
 
 const parseYaml = yaml.parse;
 
@@ -164,7 +156,7 @@ async function readSSE(response) {
  *   behind `broadcast()` and the `channels:` relay (a private one when omitted)
  * @returns {Function} Connect middleware
  */
-export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels = createDevChannels() }) {
+export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels = createDevChannels(), platform = devPlatform(), appId = null }) {
 
     // query() — proxies to the workspace _sql endpoint (same as server-routes.js)
     async function query(sql, params) {
@@ -223,6 +215,11 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
         return { status, body, contentType };
     }
 
+    // Throws the written explanation unless the mock platform opts into
+    // embeddings; then posts to the deployed app's _embed route through
+    // apiFetch (hoisted below). See createDevEmbed.
+    const embed = createDevEmbed({ platform, apiFetch, appId });
+
     async function apiFetch(path, opts = {}) {
         return await fetchAs(authHeader, path, opts);
     }
@@ -455,7 +452,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
 
                         if (tool) {
                             try {
-                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, log, env, platform: devPlatform() });
+                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, log, env, platform });
                             } catch (err) {
                                 console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
                                 result = { error: err.message };

package/src/dev-bag.js

@@ -0,0 +1,241 @@
+import { loadManifest, manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
+import { createDevChannels, createDevEmit } from './dev-channels.js';
+import { LIMITS } from './dev-streams.js';
+import { devPlatform, createDevEmbed } from './dev-platform.js';
+
+/**
+ * The part of the dev handler bag every surface shares — `server/` routes and
+ * `channels/` handlers alike: the platform services (`query`, `fetch`, the
+ * typed dependency `context`, `emit`, `broadcast`, `notify`, `email`,
+ * `crypto`, `markdown`, `log`, `env`, `platform`). Each surface adds only its
+ * own inbound members (`request` + `respond` for HTTP, `channel` + `payload`
+ * for channels), the same split the prod sandbox's buildInvokeScript makes.
+ */
+
+// Cap dev proxy calls at 30s so a hung upstream fails loudly instead of
+// hanging the handler.
+const FETCH_TIMEOUT_MS = 30000;
+
+/**
+ * Read a response body into memory, refusing once it passes `max` and cancelling
+ * the reader so the rest never arrives. `arrayBuffer()` would buffer whatever the
+ * upstream sends before anything could measure it.
+ */
+async function readCapped(resp, max) {
+    if (!resp.body) return Buffer.from(await resp.arrayBuffer());
+    const reader = resp.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > max) {
+            await reader.cancel();
+            throw new RangeError(`The upstream body exceeds the ${max} bytes the dev server holds in memory`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+
+/** log(message, data) + log.debug/info/warn/error — the sandbox log surface, to the terminal. */
+export function buildDevLog(prefix = '[app-log]') {
+    const logCall = (level, message, data) => {
+        const msg = typeof message === 'string' ? message : JSON.stringify(message);
+        const args = [`${prefix} [${level}] ${msg}`];
+        if (data) args.push(data);
+        console.log(...args);
+    };
+    return Object.assign(
+        (message, data) => logCall('info', message, data),
+        {
+            debug: (message, data) => logCall('debug', message, data),
+            info: (message, data) => logCall('info', message, data),
+            warn: (message, data) => logCall('warn', message, data),
+            error: (message, data) => logCall('error', message, data)
+        }
+    );
+}
+
+/** The viewer identity dev handlers see — the same object the page gets as window.__INFORMER__.user. */
+export function buildDevUser(user) {
+    return {
+        username: (user && user.username) || 'dev',
+        displayName: (user && user.displayName) || 'Local Developer',
+        email: (user && user.email) || null,
+        timezone: (user && user.timezone) || null
+    };
+}
+
+/**
+ * Build the shared services once per dev server and the per-invocation bag
+ * on demand.
+ *
+ * @param {Object} opts
+ * @param {string} opts.serverOrigin - Informer server origin
+ * @param {string} opts.authHeader - Basic or Bearer auth header for /api calls
+ * @param {string|null} opts.devWorkspaceId - workspace datasource id for query()
+ * @param {string} opts.projectRoot - app project root
+ * @param {Object} [opts.devBindings] - dev bindings for `target: app` / `target: pack` deps
+ * @param {string|null} [opts.appToken] - INFORMER_APP_TOKEN for cross-app request()
+ * @param {ReturnType<typeof createDevChannels>} [opts.channels] - the dev channels hub
+ * @param {string} [opts.logPrefix] - prefix for notify/email/emit console lines
+ * @param {Object} [opts.platform] - the MERGED platform descriptor (dev defaults
+ *   + mock.platform). The bag must see the same one the browser does, or an app
+ *   that opts into `embeddings` reads the flag as true and still finds embed()
+ *   throwing. Defaults to the bare dev descriptor.
+ * @param {string|null} [opts.appId] - the deployed app's id, for the opt-in
+ *   dev embed()'s call to its `_embed` route
+ * @returns {{ query: Function, apiFetch: Function, build: (opts?: { forwarding?: Object|null }) => Promise<{ manifest: Object, bag: Object }> }}
+ */
+export function createDevBagBuilder({ serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings = {}, appToken = null, channels = createDevChannels(), logPrefix = '[app]', platform = devPlatform(), appId = null }) {
+    // query() implementation — proxies to the workspace _sql endpoint
+    async function query(sql, params) {
+        if (!devWorkspaceId) {
+            throw new Error('query() requires INFORMER_DEV_WORKSPACE. Run: npx informer-workspace init');
+        }
+
+        const resp = await globalThis.fetch(`${serverOrigin}/api/datasources/${devWorkspaceId}/_sql`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: authHeader },
+            body: JSON.stringify({ sql, params: params || [] })
+        });
+
+        if (!resp.ok) {
+            const err = await resp.json().catch(() => ({}));
+            const detail = err.message || resp.statusText;
+            throw new Error(`query() failed: ${resp.status} ${detail} (${serverOrigin}/api/datasources/${devWorkspaceId}/_sql)`);
+        }
+
+        const data = await resp.json();
+        return data.rows;
+    }
+
+    // fetch() implementation — proxies API calls to the Informer server
+    async function fetchAs(auth, path, opts = {}) {
+        const method = (opts.method || 'GET').toUpperCase();
+        // Same strict canonicalization as prod (app-sandbox.js normalizeFetchPath);
+        // reject non-canonical shapes here instead of silently accepting them.
+        const apiPath = normalizeFetchPath(path);
+        if (!apiPath) {
+            // `message` is where every other failure from here puts its
+            // sentence (the synthetic 502 below, and boom's own answers), so
+            // one field read by a caller finds all of them. `error` stays
+            // beside it for anything already reading that.
+            const reason = `Invalid fetch path: ${String(path).slice(0, 80)}`;
+            return { status: 400, body: { message: reason, error: reason }, contentType: 'application/json' };
+        }
+        const url = `${serverOrigin}${apiPath}`;
+        const fetchOpts = {
+            method,
+            headers: { Authorization: auth, 'Content-Type': 'application/json', ...(opts.headers || {}) }
+        };
+
+        if (opts.body && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+            fetchOpts.body = JSON.stringify(opts.body);
+        }
+
+        // Read the stream exactly once — `.json()` consumes/locks the body, so a
+        // `.text()` fallback would throw "Body is unusable" on any non-JSON
+        // response (auth-bounce HTML, proxy error page). Parse in memory
+        // instead — same as prod's unwrapInject. `raw: true` (I5-13030, a
+        // stream being filled from an integration) keeps the bytes as bytes and
+        // hands the headers back too; the body is still parsed for an error.
+        let status, contentType, text, bytes, headers;
+        try {
+            const resp = await globalThis.fetch(url, { ...fetchOpts, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+            status = resp.status;
+            contentType = resp.headers.get('content-type') || '';
+            if (opts.raw) {
+                // Bounded before it is buffered. Prod meters the body mid-stream
+                // and tears the socket down at the first byte past the cap; here
+                // the whole thing lands in memory, so an unbounded read turns a
+                // clean 413 into an OOM'd dev server with nothing naming the
+                // cause. The declared length is the cheap check; the running one
+                // covers a chunked response that declares nothing.
+                const declared = Number(resp.headers.get('content-length'));
+                if (Number.isFinite(declared) && declared > LIMITS.maxUploadBytes) {
+                    throw new RangeError(`The upstream body is ${declared} bytes; the dev server holds at most ${LIMITS.maxUploadBytes} in memory`);
+                }
+                bytes = await readCapped(resp, LIMITS.maxUploadBytes);
+                headers = Object.fromEntries(resp.headers.entries());
+                text = status >= 400 ? bytes.toString('utf8') : '';
+            } else {
+                text = await resp.text();
+            }
+        } catch (err) {
+            // Transport failure or timeout — fetch throws (TypeError 'fetch failed'
+            // with the real reason on err.cause, or a TimeoutError). Return a
+            // synthetic 502 so the dependency layer names it (dep + url + cause)
+            // rather than a bare unhandled "fetch failed".
+            const reason = (err.cause && err.cause.message) || err.message;
+            return { status: 502, body: { message: `fetch to ${url} failed: ${reason}` }, contentType: 'application/json' };
+        }
+        let body;
+        try { body = JSON.parse(text); } catch { body = text; }
+        return opts.raw ? { status, body, contentType, bytes, headers } : { status, body, contentType };
+    }
+
+    async function apiFetch(path, opts = {}) {
+        return await fetchAs(authHeader, path, opts);
+    }
+
+    // Cross-app request() targets /api/apps/<id>/view/_/<path>, whose auth accepts
+    // only the token/session strategies — NOT basic auth. In API-key mode the
+    // INFORMER_API_KEY Bearer already satisfies that, so reuse it; under basic
+    // auth a separate API token (INFORMER_APP_TOKEN) is required, and without one
+    // the app proxy's request() throws a pointed error instead of a bare 401.
+    // appFetch also stamps x-informer-app-depth:1 so the target runs one hop deep
+    // and enforces the same one-hop guard it does in production.
+    const appAuth = appToken
+        ? `Bearer ${appToken}`
+        : (authHeader && authHeader.startsWith('Bearer ') ? authHeader : null);
+    const appFetch = appAuth
+        ? async (path, opts = {}) => await fetchAs(appAuth, path, { ...opts, headers: { ...(opts.headers || {}), 'x-informer-app-depth': '1' } })
+        : null;
+
+    // notify/email — delivery is a console-logged no-op in dev, but the
+    // required-field validation mirrors prod so an app that passes here
+    // won't 500 in production.
+    const { notify, email } = buildDevMessaging(logPrefix);
+    const log = buildDevLog();
+    // Throws the written explanation a real install gives an app type without
+    // the capability, unless the mock platform opts into embeddings; then it
+    // posts to the deployed app's _embed route through apiFetch. See
+    // createDevEmbed.
+    const embed = createDevEmbed({ platform, apiFetch, appId });
+    // markdown helper — passthrough in dev (production uses `marked`)
+    const markdown = (text) => text;
+
+    /**
+     * The shared bag for one invocation. The manifest is parsed per call
+     * (deps, env and channels all come from that one read) so edits to
+     * informer.yaml take effect without a dev-server restart.
+     *
+     * @param {Object} [opts]
+     * @param {Object|null} [opts.forwarding] - the request's stream forwarding
+     *   services (dev-streams.js createStreamServices), so an integration
+     *   request() can send a staged upload or fill a download; only `server/`
+     *   routes have streams, so channel handlers leave it null
+     */
+    async function build({ forwarding = null } = {}) {
+        const manifest = await loadManifest(projectRoot);
+        const deps = manifestBlock(manifest, 'dependencies');
+        const context = buildDevContext({ deps, apiFetch, devBindings, appFetch, forwarding });
+        const env = manifestBlock(manifest, 'env');
+
+        // emit() writes no app_event row in dev, but still relays a listed
+        // event to its `channels:` channel; broadcast() publishes a live
+        // frame to the page (see dev-channels.js).
+        const emit = createDevEmit({ channels, manifestChannels: manifestBlock(manifest, 'channels'), logPrefix: '[app-event]' });
+        const { broadcast } = channels;
+
+        return {
+            manifest,
+            bag: { context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: buildDevCrypto(), markdown, log, env, platform }
+        };
+    }
+
+    return { query, apiFetch, build };
+}