@entrinsik/vite-plugin-informer 2.7.0-beta.0 → 2.10.0

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 }
+    };
+}