@entrinsik/vite-plugin-informer 2.10.0 → 2.12.0

package/src/dev-streams.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { extname } from 'node:path';
+import { extname, basename } from 'node:path';
 
 /**
  * Dev-mode app streams (I5-12979) — the local stand-in for the production
@@ -151,6 +151,47 @@ export function createStreamStore(limits = LIMITS) {
     return { create, get, bytes, remove, reserve, seal, sweep, touch, items, limits };
 }
 
+/**
+ * The staged streams of one type, oldest first (I5-13030). Dev has a single
+ * user, so the store IS their ledger — no per-user filter to apply.
+ */
+export function listStreams(store, type) {
+    store.sweep();
+    return [...store.items.values()].filter(item => item.type === type).sort((a, b) => a.createdAt - b.createdAt);
+}
+
+/** Where the dev origin serves a download: the same shape the bag's download.url takes. */
+export function downloadUrl(item, base = '') {
+    return `${base}/_downloads/${encodeURIComponent(item.id)}${item.filename ? `/${encodeURIComponent(item.filename)}` : ''}`;
+}
+
+/**
+ * MIRRORED from modules/app/lib/app-stream-forwarding.js (I5-13030) and pinned
+ * by the parity test: how a filled stream is named when the guest did not
+ * name it — the upstream's Content-Disposition, else the request path.
+ */
+export function filenameFromDisposition(header) {
+    if (typeof header !== 'string') return null;
+    const utf8 = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/.exec(header);
+    if (utf8) {
+        try { return decodeURIComponent(utf8[1].trim()); } catch { /* fall through to the plain form */ }
+    }
+    const plain = /filename\s*=\s*"?([^";]+)"?/.exec(header);
+    return plain ? plain[1].trim() : null;
+}
+
+export function filenameFor(headers, url) {
+    const named = filenameFromDisposition(headers && headers['content-disposition']);
+    if (named) return basename(named);
+    if (typeof url === 'string') {
+        try {
+            const last = basename(new URL(url, 'http://upstream.invalid').pathname);
+            if (last && last !== '/') return last;
+        } catch { /* not a URL we can name a file after */ }
+    }
+    return 'download';
+}
+
 /** Guest-facing handle: never the store item itself. */
 export function toHandle(item, extra = {}) {
     return {
@@ -402,35 +443,38 @@ export function createStreamServices({ store, query, base = '' }) {
         return { rowCount };
     }
 
+    /** A live upload handle — what uploads.get() and a filled `into: 'upload'` both hand out. */
+    function uploadHandle(item) {
+        return {
+            ...toHandle(item),
+            text: async (encoding) => {
+                if (encoding !== undefined && encoding !== null && !Buffer.isEncoding(encoding)) throw httpError(422, `Unknown text encoding "${encoding}"`);
+                return inline(item).toString(encoding || 'utf8');
+            },
+            json: async () => {
+                const text = inline(item).toString('utf8');
+                try {
+                    return JSON.parse(text);
+                } catch (err) {
+                    throw httpError(422, `Upload is not valid JSON: ${err.message}`);
+                }
+            },
+            base64: async () => inline(item).toString('base64'),
+            extractText: async () => { throw httpError(501, 'upload.extractText() is not available in dev — the platform text extractor runs on the Informer server; test it against a deployed app'); },
+            copyInto: async (table, opts) => await copyInto(item, table, opts || {}),
+            discard: async () => { store.remove(item.id); return true; }
+        };
+    }
+
     const uploads = {
         async get(id) {
-            const item = ownedUpload(id);
-            return {
-                ...toHandle(item),
-                text: async (encoding) => {
-                    if (encoding !== undefined && encoding !== null && !Buffer.isEncoding(encoding)) throw httpError(422, `Unknown text encoding "${encoding}"`);
-                    return inline(item).toString(encoding || 'utf8');
-                },
-                json: async () => {
-                    const text = inline(item).toString('utf8');
-                    try {
-                        return JSON.parse(text);
-                    } catch (err) {
-                        throw httpError(422, `Upload is not valid JSON: ${err.message}`);
-                    }
-                },
-                base64: async () => inline(item).toString('base64'),
-                extractText: async () => { throw httpError(501, 'upload.extractText() is not available in dev — the platform text extractor runs on the Informer server; test it against a deployed app'); },
-                copyInto: async (table, opts) => await copyInto(item, table, opts || {}),
-                discard: async () => { store.remove(item.id); return true; }
-            };
+            return uploadHandle(ownedUpload(id));
         }
     };
 
     function downloadHandle(item) {
-        const url = `${base}/_downloads/${encodeURIComponent(item.id)}${item.filename ? `/${encodeURIComponent(item.filename)}` : ''}`;
         const handle = {
-            ...toHandle(item, { url }),
+            ...toHandle(item, { url: downloadUrl(item, base) }),
             async write(chunk) {
                 writableDownload(item.id);
                 const buf = toBytes(chunk);
@@ -504,7 +548,93 @@ export function createStreamServices({ store, query, base = '' }) {
         }
     }
 
-    return { uploads, downloads, resolveQueryParams, endDownload, finalize };
+    /**
+     * Forwarding to an integration (I5-13030). Prod streams the bytes between
+     * the staging store and the upstream; the dev proxy reaches the real
+     * request route over HTTP with a JSON body, so here the bytes ride that
+     * route's base64 envelope instead — the same semantics, under the
+     * envelope's own cap (dev-dependencies.js names the gap when a file is
+     * over it). What the store does is identical: an outbound handle is read,
+     * an `into` target is claimed before the call and filled after it.
+     */
+    const forwarding = {
+        /** The bytes behind an owned, sealed upload reference, with what describes them. */
+        body(ref) {
+            const item = ownedUpload(ref.id);
+            return { bytes: store.bytes(item), contentType: item.contentType || 'application/octet-stream', filename: item.filename, size: item.size };
+        },
+        /**
+         * Claim an `into` target now — a download the guest created (unsealed,
+         * unwritten) or 'upload' for a fresh one — and return fill(), which
+         * lands the upstream body and seals it. Over the byte cap, fill() fails
+         * 413 and leaves a download empty and unsealed, a fresh upload gone.
+         */
+        receiver(target, url) {
+            if (target === 'upload') {
+                store.reserve(limits.maxUploadBytes);
+                const item = store.create('upload', { filename: null, contentType: null, size: 0, chunks: 0, reserved: limits.maxUploadBytes });
+                let settled = false;
+                return {
+                    // Prod's appStream.release: the upstream delivered no body,
+                    // so give the claim back rather than leaving an upload
+                    // nobody holds a handle to until the TTL.
+                    release() {
+                        if (settled) return;
+                        settled = true;
+                        store.remove(item.id);
+                    },
+                    fill(bytes, headers = {}) {
+                        settled = true;
+                        if (bytes.length > limits.maxUploadBytes) {
+                            store.remove(item.id);
+                            throw httpError(413, `The upstream body exceeds the ${limits.maxUploadBytes} byte limit`, { maxUploadBytes: limits.maxUploadBytes });
+                        }
+                        item.contentType = (headers['content-type'] || 'application/octet-stream').split(';')[0].trim();
+                        item.filename = filenameFor(headers, url);
+                        // An `into` fill is the append producer, which never sets
+                        // a chunk size — prod reports null, and so must the
+                        // listing below, not just the handle returned here.
+                        item.chunkSize = null;
+                        item.chunks = 1;
+                        item.chunkData.set(1, Buffer.from(bytes));
+                        item.size = bytes.length;
+                        item.complete = true;
+                        store.seal(item);
+                        // The same extra KEYS prod's handle carries for a filled
+                        // upload. Dev is one in-memory buffer, so chunks is always
+                        // 1 where prod reports the real append-producer count.
+                        return { ...uploadHandle(item), complete: true, chunks: 1, chunkSize: null };
+                    }
+                };
+            }
+            if (isStreamRef(target, 'download')) {
+                const item = writableDownload(target.id);
+                if (item.parts.length) throw httpError(409, 'Download already has bytes; `into` fills a download from empty and seals it');
+                return {
+                    // The guest still owns this one, so there is nothing to
+                    // reclaim — it stays empty and unsealed, as prod leaves it.
+                    release() {},
+                    fill(bytes, headers = {}) {
+                        if (bytes.length > limits.maxUploadBytes) {
+                            item.parts = [];
+                            item.size = 0;
+                            throw httpError(413, `The upstream body exceeds the ${limits.maxUploadBytes} byte limit`, { maxUploadBytes: limits.maxUploadBytes });
+                        }
+                        if (!item.contentType) item.contentType = (headers['content-type'] || 'application/octet-stream').split(';')[0].trim();
+                        if (!item.filename) item.filename = filenameFor(headers, url);
+                        item.parts = [Buffer.from(bytes)];
+                        item.size = bytes.length;
+                        pending.delete(item.id);
+                        store.seal(item);
+                        return { ...downloadHandle(item), complete: true };
+                    }
+                };
+            }
+            throw httpError(400, `request(): \`into\` must be a download handle or 'upload'`);
+        }
+    };
+
+    return { uploads, downloads, resolveQueryParams, endDownload, finalize, forwarding };
 }
 
 // What a guest hands write(): a string or bytes. Anything else is a 422 in
@@ -591,7 +721,7 @@ async function readBody(req) {
 
 function uploadSummary(item) {
     const { received, missing } = missingChunks(item);
-    return toHandle(item, { chunkSize: item.chunkSize, chunks: item.chunks, complete: item.complete, received, missing });
+    return toHandle(item, { chunkSize: Number(item.chunkSize) || null, chunks: item.chunks, complete: item.complete, received, missing });
 }
 
 /**
@@ -612,6 +742,11 @@ export function createUploadsMiddleware(store) {
                 res.setHeader('Location', `/_uploads/${item.id}`);
                 return sendJson(res, 201, uploadSummary(item));
             }
+            // GET /_uploads — what is staged (I5-13030). Dev has one user, so
+            // the store's uploads are all theirs, oldest first like prod.
+            if (parts.length === 0 && method === 'GET') {
+                return sendJson(res, 200, listStreams(store, 'upload').map(item => toHandle(item, { chunkSize: Number(item.chunkSize) || null, chunks: item.chunks, complete: item.complete })));
+            }
             if (parts.length === 0) return next();
 
             const item = store.get('upload', parts[0]);
@@ -639,14 +774,28 @@ export function createUploadsMiddleware(store) {
     };
 }
 
-/** Connect middleware for GET /_downloads/{id}/{filename?}?keep&inline. */
+/**
+ * Connect middleware for GET /_downloads/{id}/{filename?}?keep&inline, plus
+ * (I5-13030) GET /_downloads to list what is staged and DELETE /_downloads/{id}
+ * to drop one unserved.
+ */
 export function createDownloadsMiddleware(store) {
     return function downloadsMiddleware(req, res, next) {
         try {
-            if (req.method.toUpperCase() !== 'GET') return next();
+            const method = req.method.toUpperCase();
             const url = new URL(req.url, 'http://dev.local');
             const [id] = url.pathname.split('/').filter(Boolean);
+            if (!id && method === 'GET') {
+                return sendJson(res, 200, listStreams(store, 'download').map(item => toHandle(item, { complete: item.complete, url: downloadUrl(item) })));
+            }
             if (!id) return next();
+            if (method === 'DELETE') {
+                if (!store.get('download', id)) throw httpError(404, 'Not Found');
+                store.remove(id);
+                res.statusCode = 204;
+                return res.end();
+            }
+            if (method !== 'GET') return next();
             const item = store.get('download', id);
             if (!item || !item.complete) throw httpError(404, 'Not Found');
             return serveDownload(store, item, res, {

package/src/env.js

@@ -1,5 +1,5 @@
 import dotenv from 'dotenv';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, parse as parsePath } from 'node:path';
 
 /**
@@ -71,6 +71,22 @@ export function envWritePath({ mode, cwd } = {}) {
     return resolve(dir, useMode ? `.env.${mode}` : '.env');
 }
 
+/**
+ * A variable as defined in the app's OWN env file (the one envWritePath
+ * names), ignoring the shell and any parent .env loadEnv walked up to. Null
+ * when the file is missing or leaves the variable unset or empty.
+ *
+ * @param {string} name
+ * @param {{ mode?: string, cwd?: string }} options
+ * @returns {string|null}
+ */
+export function localEnvValue(name, { mode, cwd } = {}) {
+    const path = envWritePath({ mode, cwd });
+    if (!existsSync(path)) return null;
+    const value = dotenv.parse(readFileSync(path, 'utf8'))[name];
+    return value ? value : null;
+}
+
 /**
  * Parse --mode <name> from a process.argv array.
  *

package/src/index.js

@@ -8,7 +8,8 @@ import { buildDeclarations } from './openapi-to-dts.js';
 import { loadEnv, envWritePath } from './env.js';
 import { createMiddleware as createServerRoutes } from './server-routes.js';
 import { createAgentMiddleware } from './agent-dev.js';
-import { createDevChannels, validateChannels, BROADCAST_EVENT, DEV_CHANNEL_EVENT } from './dev-channels.js';
+import { createDevChannels, validateChannels, BROADCAST_EVENT, DEV_CHANNEL_EVENT, DEV_CHANNEL_API } from './dev-channels.js';
+import { createDevChannelHandlers, validateChannelHandlers } from './dev-channel-handlers.js';
 import { renderDevChannelScript } from './dev-channel-shim.js';
 import { createStreamStore, createUploadsMiddleware, createDownloadsMiddleware } from './dev-streams.js';
 import { streamsClientSource } from './streams-client.js';
@@ -38,6 +39,36 @@ function buildMock(options) {
     };
 }
 
+/**
+ * The app id dev surfaces address on the server (the opt-in dev `embed()`
+ * posts to its `_embed` route). `informer-init` generates it locally into
+ * package.json `informer.id` and the first deploy creates the app under it.
+ * Absent, the surface says so at call time rather than the dev server
+ * refusing to start.
+ */
+function readAppId(projectRoot) {
+    const pkgPath = resolve(projectRoot, 'package.json');
+    let raw;
+    try {
+        raw = readFileSync(pkgPath, 'utf8');
+    } catch (err) {
+        // Unreadable is not the same as "no id set", and the two want
+        // different fixes. Saying which one it is beats telling someone to
+        // set a field in a file they are already looking at — or that the
+        // dev server never found.
+        if (err.code !== 'ENOENT') console.warn(`[informer] Could not read ${pkgPath}: ${err.message}`);
+        else console.warn(`[informer] No package.json at ${pkgPath}; dev surfaces that address the deployed app are unavailable.`);
+        return null;
+    }
+    try {
+        const pkg = JSON.parse(raw);
+        return (pkg.informer && pkg.informer.id) || null;
+    } catch (err) {
+        console.warn(`[informer] Could not parse ${pkgPath}: ${err.message}`);
+        return null;
+    }
+}
+
 /**
  * Occupied-spot check for the dev /api mount: does informer.yaml's
  * access.apis declare this method+path? Mirrors the server's matchWhitelist
@@ -96,13 +127,16 @@ async function writeAppDepTypes (projectRoot, dts) {
  *
  * - Proxies /api requests to the Informer server with Basic auth
  * - Runs server/ route handlers locally via ssrLoadModule (if server/ dir exists)
- * - Injects window.__INFORMER__ context mock in dev mode, including a
- *   `channel()` mock fed by handler broadcast() over Vite's dev websocket
+ * - Runs channels/ handlers locally (join / joined / leave / send) behind
+ *   the `channel()` mock injected with the window.__INFORMER__ context in
+ *   dev mode, whose frames arrive over Vite's dev websocket
  * - Sets base to './' so built assets use relative paths
  *
  * @param {Object} [options]
- * @param {{ report?: object, theme?: 'light'|'dark', roles?: string[] }} [options.mock]
- *   window.__INFORMER__ mock injected in dev.
+ * @param {{ report?: object, theme?: 'light'|'dark', roles?: string[], user?: object, platform?: object }} [options.mock]
+ *   window.__INFORMER__ mock injected in dev. `platform` merges into the dev
+ *   descriptor, so `{ capabilities: { embeddings: true } }` opts one capability
+ *   in and leaves the rest. See InformerPluginOptions in index.d.ts.
  * @param {Object} [options.devBindings] - dev bindings for `target: app` and
  *   `target: pack` deps. App slots can't be defaultBound in the manifest; pack
  *   slots resolve their marketplace pin via installs dev doesn't have, so the
@@ -179,6 +213,15 @@ export default function informer(options = {}) {
             const projectRoot = process.cwd();
             const migrationsDir = resolve(projectRoot, 'migrations');
 
+            // One merged descriptor for the whole dev server. Built once
+            // rather than per consumer so "the channel hub, the handler bags
+            // and the browser all see the same mock" is structural — which is
+            // the property the embeddings opt-in depends on, since the flag
+            // the app reads and the flag that binds embed() must be the same
+            // flag. (transformIndexHtml is a separate hook and builds its own.)
+            const mock = buildMock(options);
+            const appId = readAppId(projectRoot);
+
             // One API client for the whole dev-server setup — createClient just
             // builds an auth header (no I/O), so it's hoisted out of the two
             // branches that each used to rebuild an identical one.
@@ -257,6 +300,15 @@ export default function informer(options = {}) {
             } catch (err) {
                 console.warn(`[informer] Could not read informer.yaml channels: ${err.message}`);
             }
+            // And for channels/ files — the deploy 400s on a stray export or a
+            // path no page can subscribe to.
+            try {
+                for (const message of await validateChannelHandlers(projectRoot)) {
+                    console.error(`[informer] ${message}`);
+                }
+            } catch (err) {
+                console.warn(`[informer] Could not read channels/: ${err.message}`);
+            }
 
             // App Channels in dev. Handlers' broadcast() (and the `channels:`
             // relay behind emit()) publish frames on this hub; each frame goes
@@ -265,10 +317,26 @@ export default function informer(options = {}) {
             // import.meta.hot. Riding the HMR socket means no second websocket,
             // no `ws: true` on the /api proxy and no socket credential to mint
             // — the dev server already owns a live connection to every page.
-            const channels = createDevChannels({ appId: buildMock(options).report.id });
+            // Every page receives every frame; the subscribe loop mounted below
+            // (join / joined / leave / send against channels/ files) is what
+            // tells a page which channels it may dispatch.
+            const channels = createDevChannels({ appId: mock.report.id });
             channels.emitter.on(BROADCAST_EVENT, (frame) => {
                 server.ws.send({ type: 'custom', event: DEV_CHANNEL_EVENT, data: frame });
             });
+            server.middlewares.use(DEV_CHANNEL_API, createDevChannelHandlers(server, {
+                serverOrigin,
+                authHeader,
+                devWorkspaceId,
+                projectRoot,
+                devBindings: options.devBindings || {},
+                appToken,
+                channels,
+                user: mock.user,
+                roles: (options.mock && options.mock.roles) || [],
+                platform: mock.platform,
+                appId
+            }));
 
             // Generate .d.ts types for bound `target: app` / `target: pack`
             // deps from their published OpenAPI docs, so server/ handlers get
@@ -343,6 +411,11 @@ export default function informer(options = {}) {
             server.middlewares.use('/_uploads', createUploadsMiddleware(streamStore));
             server.middlewares.use('/_downloads', createDownloadsMiddleware(streamStore));
 
+            // The merged platform descriptor (dev defaults + mock.platform) is
+            // what the handler bags see too, not only the browser: an app that
+            // opts into `embeddings` there must find embed() bound, not throwing.
+            const platform = mock.platform;
+
             // Mount server-side route handlers if a server/ directory exists
             const serverDir = resolve(projectRoot, 'server');
 
@@ -353,7 +426,7 @@ export default function informer(options = {}) {
                     devWorkspaceId,
                     projectRoot,
                     roles: (options.mock && options.mock.roles) || [],
-                    user: buildMock(options).user,
+                    user: mock.user,
                     // Dev-only bindings for `target: app` / `target: pack`
                     // slots (app: overrides the manifest defaultBinding; pack:
                     // names the locally-installed pack app). Shape:
@@ -361,7 +434,9 @@ export default function informer(options = {}) {
                     devBindings: options.devBindings || {},
                     appToken,
                     channels,
-                    streamStore
+                    streamStore,
+                    platform,
+                    appId
                 });
                 server.middlewares.use('/api/_server', serverRoutes);
                 // Occupied-spot precedence (App API v2, matches production
@@ -393,7 +468,9 @@ export default function informer(options = {}) {
                     projectRoot,
                     devBindings: options.devBindings || {},
                     appToken,
-                    channels
+                    channels,
+                    platform,
+                    appId
                 });
                 server.middlewares.use('/api/_agent', agentDev);
             }
@@ -421,6 +498,7 @@ export default function informer(options = {}) {
     var __streams = ${streamsClientSource()};
     window.__INFORMER__.upload = __streams.upload;
     window.__INFORMER__.downloadUrl = __streams.downloadUrl;
+    window.__INFORMER__.streams = __streams.streams;
 })();
 </script>
 ${renderDevChannelScript({ hub: Boolean(serverOrigin) })}`;