@entrinsik/vite-plugin-informer 2.7.0 → 2.10.0

package/src/deploy.js

@@ -1,5 +1,7 @@
 import { createClient } from './client.js';
 import { collectAppFiles } from './assemble.js';
+import { describeServer, planDeploy } from './compat.js';
+import { loadManifest } from './dev-dependencies.js';
 import { readFile } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
 
@@ -22,6 +24,20 @@ const CHUNK_THRESHOLD = 512 * 1024; // 512KB
  */
 export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, description, icon, id }) {
     const api = createClient({ baseUrl, apiKey, user, pass });
+    const projectRoot = dirname(distDir);
+
+    // 0. Assemble and version-check before touching the app. Both steps below
+    //    are destructive — the snapshot rotates and _clear empties the library —
+    //    so a missing dist/ or a refused version floor has to surface here,
+    //    while the deployed app is still whole.
+    const collected = await collectAppFiles({ distDir, projectRoot });
+    const server = await describeServer(api);
+    const plan = planDeploy({ server, files: collected, manifest: await loadManifest(projectRoot) });
+
+    for (const warning of plan.warnings) {
+        console.warn(`  ! ${warning}`);
+    }
+    if (plan.refusal) throw new Error(plan.refusal);
 
     let entity = null;
     let naturalId = null;
@@ -104,12 +120,14 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     console.log('Clearing existing files...');
     await api.post(`${entityPath}/files/_clear`);
 
-    // 6. Upload the app-library file set: dist output at the library root, plus
-    //    informer.yaml / data-access.yaml and the server/tools/mcp/migrations/webhooks
-    //    source trees. Sourced from the shared collectAppFiles() so a deploy and a
-    //    marketplace publish package byte-identical contents.
+    // 6. Upload the app-library file set assembled in step 0: dist output at the
+    //    library root, plus informer.yaml / data-access.yaml and the
+    //    server/tools/mcp/migrations/webhooks/embeddings source trees, less any
+    //    tree this server is too old to keep out of browsers (see compat.js).
+    //    Sourced from the shared collectAppFiles() so a deploy and a marketplace
+    //    publish package byte-identical contents.
     console.log('Uploading files...');
-    const files = await collectAppFiles({ distDir, projectRoot: dirname(distDir) });
+    const files = plan.files;
 
     for (const { abs, rel } of files) {
         const content = await readFile(abs);
@@ -136,45 +154,9 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
         }
     }
 
-    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + tools + agents
+    // 12. Deploy: run migrations + scan/bundle server routes + webhooks + embeddings + tools + agents
     if (apiPrefix === 'apps') {
-        try {
-            console.log('Deploying...');
-            const result = await api.post(`${entityPath}/_deploy`);
-            if (result) {
-                if (result.migrated && result.migrated.length > 0) {
-                    console.log(`  Ran ${result.migrated.length} migration(s): ${result.migrated.join(', ')}`);
-                }
-                if (result.routes && result.routes.length > 0) {
-                    console.log(`  Registered ${result.routes.length} server route(s):`);
-                    for (const r of result.routes) {
-                        console.log(`    ${r}`);
-                    }
-                }
-                if (result.webhooks && result.webhooks.length > 0) {
-                    console.log(`  Registered ${result.webhooks.length} webhook(s):`);
-                    for (const r of result.webhooks) {
-                        console.log(`    ${r}`);
-                    }
-                }
-                if (result.tools && result.tools.length > 0) {
-                    console.log(`  Registered ${result.tools.length} tool(s): ${result.tools.join(', ')}`);
-                }
-                if (result.mcpTools && result.mcpTools.length > 0) {
-                    console.log(`  Registered ${result.mcpTools.length} MCP tool(s): ${result.mcpTools.join(', ')}`);
-                }
-                if (result.agents && result.agents.length > 0) {
-                    console.log(`  Deployed ${result.agents.length} agent(s): ${result.agents.join(', ')}`);
-                }
-            }
-        } catch (err) {
-            if (err.status === 404) {
-                // Server may not support _deploy yet — ignore
-            } else {
-                const detail = err.body || err.message;
-                console.error(`  Deploy failed: ${detail}`);
-            }
-        }
+        await runServerDeploy(api, entityPath);
     }
 
     // 13. Print URL and return UUID for saving
@@ -188,6 +170,97 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     return { id: entity.id, url: entityUrl };
 }
 
+/**
+ * POST `_deploy`: run migrations, scan/bundle server routes, webhooks, tools and
+ * agents, and claim the app as platform-managed.
+ *
+ * Exported for its own tests. This is the step whose failure modes are silent —
+ * everything it does is invisible in the CLI output when it doesn't happen.
+ *
+ * @param {{post: (path: string, body?: unknown) => Promise<unknown>}} api
+ * @param {string} entityPath e.g. `apps/my-app`
+ */
+export async function runServerDeploy(api, entityPath) {
+    try {
+        console.log('Deploying...');
+        // `managed: true` claims the app as platform-managed (origin
+        // 'deployed'), which locks builder editing so a UI edit can't drift
+        // from this project. Opt-in: the server leaves an app editable when the
+        // flag is absent, so the GO admin panel's Redeploy and the builder's
+        // Save can share this route without converting user-built apps. See
+        // app/routes/deploy.js.
+        const result = await api.post(`${entityPath}/_deploy`, { managed: true });
+        if (result === null) {
+            // api.post turns a 404 into null instead of throwing, so this is the
+            // only place it can be caught. Files uploaded, but migrations, server
+            // routes, webhooks and the managed claim did NOT run — and a missing
+            // route is far more often a wrong app id or a proxy path rewrite than
+            // a server too old to have _deploy. Falling through here prints
+            // "Published ..." and exits 0 on a half-finished deploy.
+            throw new Error(
+                `Deploy endpoint not found at ${entityPath}/_deploy. The app may not exist on this server, `
+                + `the path may be rewritten by a proxy, or the server may predate _deploy. `
+                + `Files were uploaded, but migrations, server routes and the managed claim did not run.`
+            );
+        }
+        if (result.migrated && result.migrated.length > 0) {
+            console.log(`  Ran ${result.migrated.length} migration(s): ${result.migrated.join(', ')}`);
+        }
+        if (result.routes && result.routes.length > 0) {
+            console.log(`  Registered ${result.routes.length} server route(s):`);
+            for (const r of result.routes) {
+                console.log(`    ${r}`);
+            }
+        }
+        if (result.webhooks && result.webhooks.length > 0) {
+            console.log(`  Registered ${result.webhooks.length} webhook(s):`);
+            for (const r of result.webhooks) {
+                console.log(`    ${r}`);
+            }
+        }
+        if (result.channelHandlers && result.channelHandlers.length > 0) {
+            console.log(`  Registered ${result.channelHandlers.length} channel handler(s):`);
+            for (const c of result.channelHandlers) {
+                console.log(`    ${c}`);
+            }
+        }
+        if (result.channels && result.channels.length > 0) {
+            console.log(`  Relaying events to ${result.channels.length} channel(s): ${result.channels.join(', ')}`);
+        }
+        if (result.tools && result.tools.length > 0) {
+            console.log(`  Registered ${result.tools.length} tool(s): ${result.tools.join(', ')}`);
+        }
+        if (result.mcpTools && result.mcpTools.length > 0) {
+            console.log(`  Registered ${result.mcpTools.length} MCP tool(s): ${result.mcpTools.join(', ')}`);
+        }
+        if (result.agents && result.agents.length > 0) {
+            console.log(`  Deployed ${result.agents.length} agent(s): ${result.agents.join(', ')}`);
+        }
+        // Advisory findings the server accumulated. The deploy still
+        // succeeded — but silently dropping these leaves authors debugging
+        // mystery responses the server already diagnosed for them.
+        if (result.routeShadowWarnings && result.routeShadowWarnings.length > 0) {
+            console.warn(`  ⚠ ${result.routeShadowWarnings.length} route shadow warning(s):`);
+            for (const w of result.routeShadowWarnings) {
+                console.warn(`    ${w}`);
+            }
+        }
+        if (result.partialFailures && result.partialFailures.length > 0) {
+            console.warn(`  ⚠ ${result.partialFailures.length} non-fatal deploy phase failure(s):`);
+            for (const f of result.partialFailures) {
+                console.warn(`    [${f.phase}] ${f.error}`);
+            }
+        }
+        return result;
+    } catch (err) {
+        // Rethrow: a failed deploy is a failed publish. Logging and falling
+        // through prints "Published ... files" and exits 0, so CI goes green on
+        // an app whose migrations never ran. bin/deploy.js turns this into exit 1.
+        const detail = err.body || err.message;
+        throw new Error(`Deploy failed: ${detail}`);
+    }
+}
+
 function formatSize(bytes) {
     if (bytes < 1024) return `${bytes} B`;
     if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;

package/src/dev-channel-shim.js

@@ -0,0 +1,150 @@
+import { CHANNEL_NAME, CHANNEL_NAME_MAX_LENGTH, DEV_CHANNEL_EVENT } from './dev-channels.js';
+
+/**
+ * The dev `__INFORMER__.channel(name)` mock: the App Channels client surface
+ * (App API v2 §1.9) with the same synchronous name check, `on(event, fn)` →
+ * `fn(payload, frame)` dispatch by `frame.event`, unsubscribe fn, `error`
+ * codes (`join_refused` | `disconnected` | `not_supported`; `rate_limited`
+ * never happens locally), phase-1 `send()` rejection and idempotent
+ * `close()` as the origin-mode shim in html-utils.js generateChannelShim.
+ *
+ * Transport: production subscribes each channel over a nes socket minted
+ * from `/_socket`. Dev has no such socket, and opening one would mean a
+ * second websocket, a `ws: true` proxy and a credential the dev server
+ * cannot mint. Frames instead ride Vite's own dev websocket as the custom
+ * event DEV_CHANNEL_EVENT (`server.ws.send({ type: 'custom', ... })` on the
+ * node side, `import.meta.hot.on(...)` here) and are filtered by channel
+ * name on the page. Vite owns reconnection; a drop surfaces to every open
+ * channel as `disconnected`, the way a lost nes socket does.
+ *
+ * Returned as source (an `installDevChannels(hot, informer)` function
+ * declaration) so it can be evaluated in a test `vm` against a fake hot
+ * context, the same way the server spec drives the production shim.
+ */
+export function generateDevChannelShim() {
+    return `
+    // --- App Channels (dev): frames arrive on Vite's dev websocket ---
+    function installDevChannels(hot, informer, unavailableReason) {
+        var CHANNEL_NAME = /${CHANNEL_NAME.source}/;
+        var CHANNEL_NAME_MAX_LENGTH = ${CHANNEL_NAME_MAX_LENGTH};
+        var FRAME_EVENT = '${DEV_CHANNEL_EVENT}';
+        var open = [];          // channels holding at least one handler
+
+        function channelError(code, message) {
+            var e = new Error(message);
+            e.code = code;
+            return e;
+        }
+
+        function deliver(frame) {
+            if (!frame || typeof frame.channel !== 'string') return;
+            open.slice().forEach(function (ch) {
+                if (ch.name === frame.channel) ch._deliver(frame);
+            });
+        }
+
+        function dropAll() {
+            open.slice().forEach(function (ch) {
+                ch._emitError(channelError('disconnected', 'The dev server connection was lost'));
+            });
+        }
+
+        if (hot) {
+            hot.on(FRAME_EVENT, deliver);
+            hot.on('vite:ws:disconnect', dropAll);
+        }
+
+        function Channel(name) {
+            this.name = name;
+            this._handlers = {};
+            this._closed = false;
+            this._unavailable = false;
+        }
+
+        Channel.prototype._deliver = function (frame) {
+            if (this._closed) return;
+            var list = this._handlers[frame.event];
+            if (!list) return;
+            list.slice().forEach(function (fn) {
+                try { fn(frame.payload, frame); }
+                catch (e) { console.error('[Informer] channel handler failed:', e); }
+            });
+        };
+
+        Channel.prototype._emitError = function (err) {
+            if (this._closed) return;
+            var list = this._handlers.error;
+            if (!list || !list.length) {
+                console.warn('[Informer] channel "' + this.name + '" ' + err.code + ': ' + err.message);
+                return;
+            }
+            list.slice().forEach(function (fn) {
+                try { fn(err); }
+                catch (e) { console.error('[Informer] channel error handler failed:', e); }
+            });
+        };
+
+        Channel.prototype.on = function (event, fn) {
+            if (this._closed) throw channelError('disconnected', 'The channel is closed');
+            if (typeof event !== 'string' || !event) throw new TypeError('channel.on: event name required');
+            if (typeof fn !== 'function') throw new TypeError('channel.on: handler must be a function');
+            var list = this._handlers[event] || (this._handlers[event] = []);
+            list.push(fn);
+            if (open.indexOf(this) === -1) open.push(this);
+            if (!hot && !this._unavailable) {
+                // Not served by the Vite dev server: no frames can ever arrive.
+                // Reported once, asynchronously, like a failed connection.
+                this._unavailable = true;
+                var self = this;
+                Promise.resolve().then(function () {
+                    self._emitError(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available'));
+                });
+            }
+            return function () {
+                var i = list.indexOf(fn);
+                if (i !== -1) list.splice(i, 1);
+            };
+        };
+
+        Channel.prototype.send = function () {
+            return Promise.reject(channelError('not_supported', 'Sending on a channel is not supported yet'));
+        };
+
+        Channel.prototype.close = function () {
+            if (this._closed) return;
+            this._closed = true;
+            var i = open.indexOf(this);
+            if (i !== -1) open.splice(i, 1);
+            this._handlers = {};
+        };
+
+        informer.channel = function (name) {
+            if (typeof name !== 'string' || name.length > CHANNEL_NAME_MAX_LENGTH || !CHANNEL_NAME.test(name)) {
+                throw channelError('join_refused', 'Invalid channel name: ' + name);
+            }
+            return new Channel(name);
+        };
+    }`;
+}
+
+/**
+ * The `<script type="module">` tag that installs the mock on the dev page.
+ * Vite turns an inline module script into an `?html-proxy` module, which is
+ * what gives it a live `import.meta.hot`. Module scripts run in document
+ * order after parsing, so placed at the top of <head> this installs
+ * `channel()` before the app's own module executes.
+ */
+export function renderDevChannelScript({ hub = true } = {}) {
+    // Without INFORMER_URL, configureServer returns before building the channel
+    // hub, so nothing can ever push a frame — but import.meta.hot is still live,
+    // which would leave the shim silent and the author staring at a channel that
+    // simply never delivers. Passing no `hot` routes it through the same
+    // report-once diagnostic, with the reason that actually applies.
+    const install = hub
+        ? 'installDevChannels(import.meta.hot, window.__INFORMER__);'
+        : `installDevChannels(null, window.__INFORMER__, 'Dev channels need INFORMER_URL set for the dev server to relay frames');`;
+    return `<script type="module">
+${generateDevChannelShim()}
+${install}
+</script>`;
+}

package/src/dev-channels.js

@@ -0,0 +1,191 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * App Channels in dev: the `broadcast(channel, event, payload)` verb for
+ * in-process handlers, and the `channels:` manifest relay that mirrors
+ * `emitAppEvent` on the server.
+ *
+ * A broadcast validates exactly like the server's `broadcastAppMessage`
+ * (app-channel-broadcast.js) — same regexes, limits and error messages — and
+ * publishes one frame on a plugin-local emitter. The plugin forwards every
+ * frame to the page over Vite's own dev websocket (see index.js); nothing
+ * here touches the network. Rate limiting and the `enabled` switch are
+ * server-cluster concerns and have no dev counterpart.
+ */
+
+// Mirrors of app-channel-broadcast.js: `orders`, `orders/east`, `@user/brad`.
+// Everything after `@user/` is one username, verbatim — the server compares the
+// whole remainder to the socket's own.
+export const CHANNEL_NAME = /^(@user\/\S+|[\w.-]+(\/[\w.-]+)*)$/;
+export const CHANNEL_NAME_MAX_LENGTH = 128;
+// `created`, `order_created`
+export const EVENT_NAME = /^[\w.-]+$/;
+export const EVENT_NAME_MAX_LENGTH = 64;
+// config-factory.js app.channels.maxFrameBytes default
+export const MAX_FRAME_BYTES = 65536;
+// deploy.js CHANNELS_SCHEMA description cap
+const DESCRIPTION_MAX_LENGTH = 500;
+
+// The Vite custom event a frame rides to the page (`hot.on(DEV_CHANNEL_EVENT, ...)`).
+export const DEV_CHANNEL_EVENT = 'informer:channel';
+// The plugin has no tenant identity; frames carry this until it does.
+export const DEV_TENANT = 'dev';
+
+/** A short, single-line preview of a payload for the dev console (frames may be 64 KiB). */
+export function previewPayload(value, max = 200) {
+    let text;
+    try { text = JSON.stringify(value); } catch { text = String(value); }
+    if (text === undefined) text = 'undefined';
+    return text.length > max ? `${text.slice(0, max)}… (${text.length} chars)` : text;
+}
+
+/** The emitter event a published frame is raised on. */
+export const BROADCAST_EVENT = 'broadcast';
+
+export function isChannelName(name) {
+    return typeof name === 'string' && name.length <= CHANNEL_NAME_MAX_LENGTH && CHANNEL_NAME.test(name);
+}
+
+export function isEventName(name) {
+    return typeof name === 'string' && name.length <= EVENT_NAME_MAX_LENGTH && EVENT_NAME.test(name);
+}
+
+// Shaped like the boom error the server throws: message === code, plus the
+// HTTP status it would carry, so a handler can branch on either in dev.
+function channelError(code, statusCode) {
+    const err = new Error(code);
+    err.code = code;
+    err.statusCode = statusCode;
+    return err;
+}
+
+/**
+ * Validate the shape of a parsed `channels:` block. Returns human-readable
+ * error strings (empty when valid). Mirrors deploy.js CHANNELS_SCHEMA so an
+ * author sees at boot what the deploy would 400 on.
+ *
+ * @param {*} block - The raw `channels:` value
+ * @returns {string[]} Error messages, one per problem
+ */
+export function validateChannels(block) {
+    const errors = [];
+    if (block === undefined || block === null) return errors;
+    if (typeof block !== 'object' || Array.isArray(block)) {
+        return ['channels: must be a map of channel name → { description?, on? }'];
+    }
+    for (const [name, def] of Object.entries(block)) {
+        if (!isChannelName(name)) {
+            errors.push(`channels: invalid channel name "${name}" (use segments of letters, digits, _ . -, joined by /, max ${CHANNEL_NAME_MAX_LENGTH} chars)`);
+            continue;
+        }
+        if (def === null || def === undefined) continue;
+        if (typeof def !== 'object' || Array.isArray(def)) {
+            errors.push(`channels.${name}: must be a map with optional "description" and "on"`);
+            continue;
+        }
+        for (const key of Object.keys(def)) {
+            if (key !== 'description' && key !== 'on') errors.push(`channels.${name}: unknown key "${key}"`);
+        }
+        if (def.description !== undefined && (typeof def.description !== 'string' || def.description.length > DESCRIPTION_MAX_LENGTH)) {
+            errors.push(`channels.${name}.description: must be a string of at most ${DESCRIPTION_MAX_LENGTH} chars`);
+        }
+        if (def.on !== undefined) {
+            const events = Array.isArray(def.on) ? def.on : [def.on];
+            for (const event of events) {
+                if (!isEventName(event)) {
+                    errors.push(`channels.${name}.on: invalid event name ${JSON.stringify(event)} (letters, digits, _ . -, max ${EVENT_NAME_MAX_LENGTH} chars)`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+
+/**
+ * Create the dev channels hub shared by every dev handler bag.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.tenant] - frame tenant (the plugin knows none; defaults to 'dev')
+ * @param {string} [opts.appId] - the dev app id (the mocked `report.id`)
+ * @param {string} [opts.logPrefix] - console prefix
+ * @returns {{ emitter: EventEmitter, broadcast: Function, relay: Function, tenant: string, appId: string }}
+ */
+export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', logPrefix = '[app-channel]' } = {}) {
+    const emitter = new EventEmitter();
+
+    // Validate and publish one §1.1 frame. Synchronous so the manifest relay
+    // can run inside a synchronous emit(); throws the server's error codes.
+    function publish(channel, event, payload) {
+        if (!isChannelName(channel)) throw channelError('app_channel_invalid_name', 400);
+        if (!isEventName(event)) throw channelError('app_channel_invalid_event', 400);
+
+        const message = payload === undefined ? null : payload;
+        let serialized;
+        try {
+            serialized = JSON.stringify(message);
+        } catch {
+            throw channelError('app_channel_invalid_payload', 400);
+        }
+        // A function/symbol serializes to nothing at all; the sandbox membrane
+        // would have refused it before the server ever saw it.
+        if (serialized === undefined) throw channelError('app_channel_invalid_payload', 400);
+        if (Buffer.byteLength(serialized) > MAX_FRAME_BYTES) throw channelError('app_channel_frame_too_large', 413);
+
+        const frame = { tenant, appId, channel, event, payload: message, at: Date.now() };
+        emitter.emit(BROADCAST_EVENT, frame);
+        return frame;
+    }
+
+    // The bag member. Async like the sandbox's, so a bad name/event/payload
+    // rejects rather than throws, exactly as it does in production.
+    async function broadcast(channel, event, payload) {
+        const frame = publish(channel, event, payload);
+        console.log(`${logPrefix} broadcast("${channel}", "${event}", ${previewPayload(frame.payload)})`);
+        return { ok: true };
+    }
+
+    /**
+     * The `channels:` relay (mirror of emitAppEvent): an emit() of an event
+     * listed in a channel's `on` is also broadcast to that channel, same event
+     * name and payload. A dropped relay warns and never fails the emit.
+     *
+     * @param {Object} manifestChannels - the parsed `channels:` block
+     * @param {string} event
+     * @param {*} payload
+     */
+    function relay(manifestChannels, event, payload) {
+        if (!manifestChannels || typeof manifestChannels !== 'object') return;
+        for (const [channel, def] of Object.entries(manifestChannels)) {
+            if (![].concat((def && def.on) || []).includes(event)) continue;
+            try {
+                publish(channel, event, payload);
+                console.log(`${logPrefix} relayed emit("${event}") → channel "${channel}"`);
+            } catch (err) {
+                console.warn(`${logPrefix} relay dropped: channel "${channel}" event "${event}": ${err.message}`);
+            }
+        }
+    }
+
+    return { emitter, broadcast, relay, tenant, appId };
+}
+
+/**
+ * Build the dev `emit(event, payload)` bag member: a console-logged no-op
+ * (no app_event row in dev) that still runs the manifest relay, so a page
+ * subscribed to a relayed channel sees the frame locally.
+ *
+ * @param {Object} opts
+ * @param {ReturnType<typeof createDevChannels>} opts.channels
+ * @param {Object} opts.manifestChannels - the parsed `channels:` block
+ * @param {string} [opts.logPrefix]
+ * @returns {(event: string, payload?: *) => { ok: true }}
+ */
+export function createDevEmit({ channels, manifestChannels, logPrefix = '[app-event]' }) {
+    return (event, payload) => {
+        // The sandbox bootstrap sends `payload || {}` across the membrane.
+        const body = payload || {};
+        console.log(`${logPrefix} emit("${event}", ${previewPayload(body)})`);
+        channels.relay(manifestChannels, event, body);
+        return { ok: true };
+    };
+}

package/src/dev-dependencies.js

@@ -173,14 +173,16 @@ const METHOD_SURFACE = {
 const REQUEST_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 
 /**
- * Load the `dependencies:` map from informer.yaml. Returns `{}` if the file
- * is missing or the section is absent — both are valid (an app may have no
- * declared dependencies).
+ * Read and parse informer.yaml once. Returns `{}` when the file is missing or
+ * its top level is not a map, so callers can select blocks without guarding.
+ * Per-request callers (server routes, agent tools) load it fresh on every
+ * request so edits take effect without a dev-server restart, and select every
+ * block they need from this one parse via manifestBlock().
  *
  * @param {string} projectRoot
- * @returns {Promise<Object>} The raw dependencies object as authored
+ * @returns {Promise<Object>} The parsed manifest document
  */
-export async function loadDependencies(projectRoot) {
+export async function loadManifest(projectRoot) {
     const yamlPath = join(projectRoot, 'informer.yaml');
     try {
         await access(yamlPath);
@@ -189,8 +191,42 @@ export async function loadDependencies(projectRoot) {
     }
     const content = await readFile(yamlPath, 'utf8');
     const parsed = parseYaml(content);
-    if (!parsed || typeof parsed !== 'object') return {};
-    return (parsed.dependencies && typeof parsed.dependencies === 'object') ? parsed.dependencies : {};
+    return (parsed && typeof parsed === 'object') ? parsed : {};
+}
+
+/**
+ * One top-level map block of a parsed manifest, or {} when absent or not a map.
+ *
+ * @param {Object} manifest - A document from loadManifest()
+ * @param {string} key - Top-level block name (`dependencies`, `channels`, `env`, ...)
+ * @returns {Object}
+ */
+export function manifestBlock(manifest, key) {
+    const block = manifest && manifest[key];
+    return (block && typeof block === 'object' && !Array.isArray(block)) ? block : {};
+}
+
+/**
+ * Load the `dependencies:` map from informer.yaml. Returns `{}` if the file
+ * is missing or the section is absent — both are valid (an app may have no
+ * declared dependencies).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Object>} The raw dependencies object as authored
+ */
+export async function loadDependencies(projectRoot) {
+    return manifestBlock(await loadManifest(projectRoot), 'dependencies');
+}
+
+/**
+ * Read the `channels:` relay block from informer.yaml: channel name →
+ * { description?, on? }. Returns {} when there is no manifest or no block.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<Object>}
+ */
+export async function loadChannels(projectRoot) {
+    return manifestBlock(await loadManifest(projectRoot), 'channels');
 }
 
 /**
@@ -203,16 +239,7 @@ export async function loadDependencies(projectRoot) {
  * @returns {Promise<Object>} The raw env object as authored
  */
 export async function loadAppEnv(projectRoot) {
-    const yamlPath = join(projectRoot, 'informer.yaml');
-    try {
-        await access(yamlPath);
-    } catch {
-        return {};
-    }
-    const content = await readFile(yamlPath, 'utf8');
-    const parsed = parseYaml(content);
-    if (!parsed || typeof parsed !== 'object') return {};
-    return (parsed.env && typeof parsed.env === 'object') ? parsed.env : {};
+    return manifestBlock(await loadManifest(projectRoot), 'env');
 }
 
 /**

package/src/dev-platform.js

@@ -0,0 +1,41 @@
+/**
+ * The `platform` descriptor the dev mirror hands to app code — the same shape
+ * the server injects on `window.__INFORMER__.platform` and on the server
+ * handler / tool bag: the Informer build version and the capability flags.
+ *
+ * Every capability the dev server mirrors is on. `embeddings` is off: the
+ * pump and query-time `embed()` need a real Informer, so an app that
+ * feature-detects on it sees locally exactly what it sees on an install
+ * without the feature. `version` is `'dev'` (not semver) so a floor check
+ * treats the dev mirror as "unknown" rather than as any particular release.
+ *
+ * Override any of it per project with `informer({ mock: { platform: {…} } })`.
+ */
+export const DEV_CAPABILITIES = Object.freeze({
+    serverRoutes: true,
+    webhooks: true,
+    tools: true,
+    mcp: true,
+    agents: true,
+    automations: true,
+    messages: true,
+    storage: true,
+    snapshots: true,
+    customApis: true,
+    integrationDependencies: true,
+    datasourceDependencies: true,
+    aiCompletions: true,
+    // live channels: broadcast() in the sandbox, the `channels:` relay block,
+    // and channels/ join/leave handlers — the dev server mirrors all three.
+    channels: true,
+    embeddings: false
+});
+
+export function devPlatform(overrides = {}) {
+    const { capabilities = {}, ...rest } = overrides || {};
+    return {
+        version: 'dev',
+        ...rest,
+        capabilities: { ...DEV_CAPABILITIES, ...capabilities }
+    };
+}