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

package/src/fan-out.js

@@ -0,0 +1,129 @@
+import { normalizeMarketplaceUrl, parseMarketplaces } from './marketplaces.js';
+
+/*
+ * The informer-ci fan-out, extracted from the bin so it can be tested. A bin
+ * script with top-level await and process.exit is unreachable to a test
+ * runner, and the contracts here are exactly the ones a refactor would break
+ * silently — see fanOut's doc comment.
+ */
+
+/**
+ * Which marketplaces this run publishes to. Explicit flags replace the
+ * configured list entirely — a workflow_dispatch re-publishing to one target
+ * must not fan back out to everything — and both forms are normalized and
+ * deduped the same way.
+ */
+export function resolveTargets({ explicit = [], configured } = {}) {
+    const flags = explicit.map(normalizeMarketplaceUrl);
+    return flags.length ? [...new Set(flags)] : parseMarketplaces(configured);
+}
+
+/** Display label for a target: the host, or the raw value when it won't parse. */
+export function targetLabel(url) {
+    try {
+        return new URL(url).host;
+    } catch {
+        return url;
+    }
+}
+
+/**
+ * Publish one prepared payload to every target. Returns per-target rows:
+ * `{ label, ok }` or `{ label, ok: false, error }`.
+ *
+ * Three load-bearing contracts:
+ *
+ * - One target failing must not stop the others — a marketplace that is down
+ *   should not withhold the release from the ones that are up. Any failed row
+ *   still fails the run afterwards (the bin exits 1 on any `ok: false`).
+ * - `mint` runs INSIDE the loop, once per target, with that target's URL as
+ *   the token audience — a token minted for one License Manager must not be
+ *   replayable at another. Hoisting the mint out as loop-invariant would
+ *   break that property without failing a single publish against a lax
+ *   verifier, which is why the test suite pins it.
+ * - Reporting cannot unland a publish. The release exists the moment
+ *   `publishOne` resolves; everything after that is narration. `onSuccess`
+ *   therefore gets its own try/catch, and its failure is recorded as
+ *   `reportError` on a row that stays `ok: true`. Letting it reach the outer
+ *   catch would print `✗ <host>` and exit 1 for a version the marketplace had
+ *   already stored — and the re-run would 409 "version already exists",
+ *   sending someone off to debug a publish that succeeded.
+ *
+ * @param {string[]} targets - normalized marketplace URLs
+ * @param {(url: string) => Promise<string>} mint - audience-scoped token minter
+ * @param {(opts: { marketplaceUrl: string, token: string }) => Promise<Object>} publishOne
+ * @param {(label: string, result: Object) => void|Promise<void>} [onSuccess]
+ * @param {(label: string, message: string) => void} [onFailure]
+ */
+export async function fanOut({ targets, mint, publishOne, onSuccess = () => {}, onFailure = () => {} }) {
+    const results = [];
+    for (const marketplaceUrl of targets) {
+        const label = targetLabel(marketplaceUrl);
+        try {
+            const token = await mint(marketplaceUrl);
+            const result = await publishOne({ marketplaceUrl, token });
+            // Past this line the publish has landed, so no path may produce an
+            // `ok: false` row for this target. Awaited so an async reporter's
+            // rejection lands here too rather than escaping unhandled.
+            let reportError;
+            try {
+                await onSuccess(label, result);
+            } catch (err) {
+                reportError = String((err && err.message) ?? err);
+            }
+            results.push(reportError ? { label, ok: true, reportError } : { label, ok: true });
+        } catch (err) {
+            // String() rather than err.message: a non-Error thrown per-target
+            // must land in the results row, not crash the summary writer
+            // after the fact and mask the real publish failure.
+            const message = String((err && err.message) ?? err);
+            onFailure(label, message);
+            results.push({ label, ok: false, error: message });
+        }
+    }
+    return results;
+}
+
+/**
+ * The GitHub job summary table. Without it the Actions UI shows one opaque
+ * step for what is really N independent publishes.
+ *
+ * Failure text is flattened to one line and truncated: PublishError messages
+ * embed multi-line JSON response bodies, and a newline inside a Markdown
+ * table cell breaks the row on exactly the runs where the summary matters.
+ */
+export function summaryTable({ title, rows }) {
+    const cell = s => {
+        const flat = String(s).replace(/\s+/g, ' ').trim();
+        // The ellipsis marks the cut — a message truncated without one reads
+        // as if it were complete.
+        return (flat.length > 300 ? `${flat.slice(0, 300)}…` : flat).replace(/\|/g, '\\|');
+    };
+    return [
+        `### ${title}`,
+        '',
+        '| Marketplace | Result |',
+        '| --- | --- |',
+        ...rows.map(r => `| ${r.label} | ${resultCell(r, cell)} |`),
+        ''
+    ].join('\n');
+}
+
+/** One row's Result cell. A reporting failure annotates a publish, never negates it. */
+function resultCell(row, cell) {
+    if (!row.ok) return `failed — ${cell(row.error)}`;
+    return row.reportError ? `published (reporting failed — ${cell(row.reportError)})` : 'published';
+}
+
+/**
+ * Whether the run failed, i.e. whether the bin exits 1. This is the whole CI
+ * contract — a green run means every target has the version — so it lives here
+ * as a predicate the suite can pin rather than as an inline `.filter` in a bin
+ * that no test runner can reach.
+ *
+ * A row that published but could not be reported is NOT a failure: the release
+ * is live, and exiting 1 would invite a re-run that 409s.
+ */
+export function failedTargets(rows) {
+    return rows.filter(r => !r.ok);
+}

package/src/index.js

@@ -1,13 +1,70 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { createClient } from './client.js';
-import { loadDependencies, validateDependencies, validateDevBindings, resolveAppBinding } from './dev-dependencies.js';
+import { loadDependencies, loadChannels, validateDependencies, validateDevBindings, resolveAppBinding } from './dev-dependencies.js';
 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 { renderDevChannelScript } from './dev-channel-shim.js';
+import { createStreamStore, createUploadsMiddleware, createDownloadsMiddleware } from './dev-streams.js';
+import { streamsClientSource } from './streams-client.js';
 import { init, migrate } from './workspace.js';
+import { devPlatform } from './dev-platform.js';
+
+/**
+ * The dev `window.__INFORMER__` context: defaults overlaid with the plugin's
+ * `mock` option. Shared by the page injection and the dev channels hub (whose
+ * frames carry `report.id` as the app id).
+ */
+function buildMock(options) {
+    return {
+        report: {
+            id: 'dev-local',
+            name: 'Local Development'
+        },
+        theme: 'light',
+        roles: [],
+        // The viewer identity the server injects (window.__INFORMER__.user);
+        // override with mock.user to test @user/<username> channels as someone else.
+        user: { username: 'dev', displayName: 'Local Developer' },
+        ...options.mock,
+        // What the platform offers, as the server injects it; a mock
+        // override merges into the dev defaults (see dev-platform.js).
+        platform: devPlatform(options.mock && options.mock.platform)
+    };
+}
+
+/**
+ * Occupied-spot check for the dev /api mount: does informer.yaml's
+ * access.apis declare this method+path? Mirrors the server's matchWhitelist
+ * semantics — segment-aware, `*` matches exactly one segment.
+ */
+function manifestOccupies (projectRoot, req) {
+    let entries;
+    try {
+        const raw = parseYaml(readFileSync(resolve(projectRoot, 'informer.yaml'), 'utf8')) || {};
+        entries = (raw.access && Array.isArray(raw.access.apis)) ? raw.access.apis : [];
+    } catch {
+        return false; // no/invalid manifest: nothing is occupied
+    }
+    // Connect strips the mount prefix, so re-add it for whole-path matching.
+    const path = `/api${(req.url || '').split('?')[0]}`;
+    const segments = path.split('/').filter(Boolean);
+    const method = (req.method || 'GET').toUpperCase();
+    return entries.some(entry => {
+        const spec = typeof entry === 'string'
+            ? entry
+            : `${(entry && entry.method) || 'GET'} ${(entry && (entry.url || entry.path)) || ''}`;
+        const parsed = /^([A-Za-z]+)\s+(\S+)$/.exec(String(spec).trim());
+        if (!parsed || parsed[1].toUpperCase() !== method) return false;
+        const want = parsed[2].split('/').filter(Boolean);
+        return want.length === segments.length && want.every((s, i) => s === '*' || s === segments[i]);
+    });
+}
 
 /**
  * Write generated app-dependency type declarations under .informer/ and keep the
@@ -39,7 +96,8 @@ 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
+ * - Injects window.__INFORMER__ context mock in dev mode, including a
+ *   `channel()` mock fed by handler broadcast() over Vite's dev websocket
  * - Sets base to './' so built assets use relative paths
  *
  * @param {Object} [options]
@@ -101,7 +159,12 @@ export default function informer(options = {}) {
                                     Authorization: authHeader
                                 },
                                 ...options.proxy
-                            }
+                            },
+                            // NOTE: no /informer-api mount. The server
+                            // retired that spelling — /api is ONE namespace
+                            // with manifest-driven precedence (a whitelisted
+                            // access.apis path OCCUPIES its spot; everything
+                            // else is the app's own routes), mirrored below.
                         }
                     };
                 }
@@ -185,6 +248,27 @@ export default function informer(options = {}) {
             for (const message of validateDevBindings(deps, options.devBindings || {})) {
                 console.error(`[informer] vite.config.js: ${message}`);
             }
+            // Same for the `channels:` relay block — the deploy 400s on a bad
+            // channel or event name; say so now instead of dropping relays.
+            try {
+                for (const message of validateChannels(await loadChannels(projectRoot))) {
+                    console.error(`[informer] informer.yaml: ${message}`);
+                }
+            } catch (err) {
+                console.warn(`[informer] Could not read informer.yaml channels: ${err.message}`);
+            }
+
+            // App Channels in dev. Handlers' broadcast() (and the `channels:`
+            // relay behind emit()) publish frames on this hub; each frame goes
+            // to the page as a custom event on Vite's own dev websocket, which
+            // the injected `__INFORMER__.channel` mock listens to via
+            // 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 });
+            channels.emitter.on(BROADCAST_EVENT, (frame) => {
+                server.ws.send({ type: 'custom', event: DEV_CHANNEL_EVENT, data: frame });
+            });
 
             // Generate .d.ts types for bound `target: app` / `target: pack`
             // deps from their published OpenAPI docs, so server/ handlers get
@@ -249,6 +333,16 @@ export default function informer(options = {}) {
                 console.warn(`[informer] app-dependency type generation skipped: ${err.message}`);
             }
 
+            // App streams (I5-12979): the dev origin's /_uploads and /_downloads
+            // — the same protocol the deployed app speaks on its own origin —
+            // backed by one in-memory store the server routes' `uploads` /
+            // `downloads` services share. Mounted regardless of server/: the
+            // client helper is always on __INFORMER__, so a page may stage an
+            // upload before any handler exists to consume it.
+            const streamStore = createStreamStore();
+            server.middlewares.use('/_uploads', createUploadsMiddleware(streamStore));
+            server.middlewares.use('/_downloads', createDownloadsMiddleware(streamStore));
+
             // Mount server-side route handlers if a server/ directory exists
             const serverDir = resolve(projectRoot, 'server');
 
@@ -259,14 +353,31 @@ export default function informer(options = {}) {
                     devWorkspaceId,
                     projectRoot,
                     roles: (options.mock && options.mock.roles) || [],
+                    user: buildMock(options).user,
                     // Dev-only bindings for `target: app` / `target: pack`
                     // slots (app: overrides the manifest defaultBinding; pack:
                     // names the locally-installed pack app). Shape:
                     //   devBindings: { kanban: { app: 'admin:kanban' } }
                     devBindings: options.devBindings || {},
-                    appToken
+                    appToken,
+                    channels,
+                    streamStore
                 });
                 server.middlewares.use('/api/_server', serverRoutes);
+                // Occupied-spot precedence (App API v2, matches production
+                // dispatch in view-api.js): a platform API declared in
+                // informer.yaml's access.apis OCCUPIES its /api path — those
+                // requests skip the local handlers (next() falls through to
+                // the /api proxy above); every unclaimed path dispatches the
+                // app's own routes. The manifest is re-read per request so
+                // edits apply without a restart. Dev limitation: only raw
+                // access.apis entries are consulted (dependency-derived
+                // grants proxy through their typed context slots anyway).
+                // /api/_server stays as the legacy exclusive spelling.
+                server.middlewares.use('/api', (req, res, next) => {
+                    if (manifestOccupies(projectRoot, req)) return next();
+                    return serverRoutes(req, res, next);
+                });
             }
 
             // Mount agent dev middleware if tools/, mcp/, or informer.yaml agents exist
@@ -281,7 +392,8 @@ export default function informer(options = {}) {
                     devWorkspaceId,
                     projectRoot,
                     devBindings: options.devBindings || {},
-                    appToken
+                    appToken,
+                    channels
                 });
                 server.middlewares.use('/api/_agent', agentDev);
             }
@@ -293,22 +405,25 @@ export default function informer(options = {}) {
             handler(html) {
                 if (!isDev) return html;
 
-                const mock = {
-                    report: {
-                        id: 'dev-local',
-                        name: 'Local Development'
-                    },
-                    theme: 'light',
-                    roles: [],
-                    ...options.mock
-                };
+                const mock = buildMock(options);
 
+                // The context is a classic script (synchronous, so it exists
+                // before anything else runs). The streams client (upload /
+                // downloadUrl) rides inside it: the one piece of the mock that is
+                // code, not data, the same helper the deployed page gets,
+                // speaking to the /_uploads and /_downloads mounted in
+                // configureServer. The channel mock follows as a module script
+                // because only a Vite-processed module gets import.meta.hot.
                 const script = `<script>
 (function() {
     'use strict';
     window.__INFORMER__ = ${JSON.stringify(mock)};
+    var __streams = ${streamsClientSource()};
+    window.__INFORMER__.upload = __streams.upload;
+    window.__INFORMER__.downloadUrl = __streams.downloadUrl;
 })();
-</script>`;
+</script>
+${renderDevChannelScript({ hub: Boolean(serverOrigin) })}`;
 
                 // Insert after <head> tag, matching server behavior
                 const headIdx = html.indexOf('<head>');

package/src/marketplaces.js

@@ -53,9 +53,35 @@ export function normalizeMarketplaceUrl(value) {
     if (url.protocol !== 'http:' && url.protocol !== 'https:') {
         throw new Error(`Marketplace URL must be http(s): ${value}`);
     }
+    // This URL is both the OIDC audience and the endpoint that receives
+    // `Authorization: Bearer <jwt>`. The audience binding stops a token minted
+    // for one marketplace being replayed at another, but does nothing about an
+    // on-path observer at the target itself — over http: a vendor-publishing
+    // token crosses the wire in cleartext. Loopback is exempt so an on-prem or
+    // local LM can still be developed against.
+    if (url.protocol === 'http:' && !isLoopback(url.hostname)) {
+        throw new Error(`Marketplace URL must be https (a publish token is sent to it): ${value}`);
+    }
     url.hostname = url.hostname.toLowerCase();
-    url.pathname = url.pathname.replace(/\/+$/, '');
     url.hash = '';
     url.search = '';
-    return url.toString();
+    // Strip trailing slashes on the serialized string, NOT via the pathname
+    // setter — WHATWG re-normalizes an empty path back to '/', so a root-path
+    // URL like https://api.informer.cloud would keep a slash that the publish
+    // URL strips. This string is also the OIDC audience, and the License
+    // Manager compares `aud` as an exact string: one character of drift fails
+    // verification on any LM that enforces its audience.
+    return url.toString().replace(/\/+$/, '');
+}
+
+/**
+ * Whether a hostname is this machine. WHATWG keeps IPv6 hosts bracketed
+ * (`[::1]`), and 127.0.0.0/8 is loopback in full, not just 127.0.0.1.
+ */
+function isLoopback(hostname) {
+    const host = String(hostname).toLowerCase();
+    return host === 'localhost'
+        || host === '[::1]'
+        || host === '::1'
+        || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
 }

package/src/publish-payload.js

@@ -8,9 +8,11 @@ import { buildLocalOpenApi } from './openapi-local.js';
  * Everything a publish needs, assembled once.
  *
  * Split out of bin/publish.js so `informer-ci` can build the payload a single
- * time and hand the SAME files to several marketplaces — a version has to be
- * byte-identical everywhere it lands, and re-assembling per target would only
- * create opportunities for it not to be.
+ * time and hand the SAME file set to several marketplaces — a version's
+ * contents have to be identical everywhere it lands, and re-assembling per
+ * target would only create opportunities for them not to be. (The upload
+ * archive itself is still built per target inside publish(), so archive
+ * bytes — tar mtimes — differ; the files inside do not.)
  *
  * Throws on anything that should stop a publish; the bins print and exit.
  */
@@ -44,14 +46,32 @@ export async function preparePublish({ projectRoot = resolve('.'), version: vers
     const { spec: apiSpec, warnings } = await buildLocalOpenApi({ projectRoot, name, slug, version });
     if (apiSpec) files.push({ rel: 'openapi.json', content: JSON.stringify(apiSpec, null, 2) });
 
+    // An explicitly configured icon or screenshots dir that doesn't resolve
+    // must not degrade silently: the publish "succeeds", the listing ships
+    // visually wrong to every marketplace in a fan-out, and a human notices
+    // weeks later. Speculative defaults may miss quietly; config may not.
     const icon = await resolveIcon(projectRoot, inf.icon);
+    if (inf.icon && (!icon || icon.abs !== resolve(projectRoot, inf.icon))) {
+        warnings.push(
+            `informer.icon "${inf.icon}" was not found — ` +
+            (icon ? `falling back to ${icon.rel}.` : 'publishing without a listing icon.')
+        );
+    }
     const screenshots = await resolveScreenshots(projectRoot, inf.screenshots);
+    if (inf.screenshots && !screenshots.length) {
+        warnings.push(`informer.screenshots "${inf.screenshots}" has no readable screenshots — the listing will have none.`);
+    }
 
     // Provenance (GitHub Actions). All optional — best-effort audit trail.
     const sourceRepo = process.env.GITHUB_REPOSITORY || undefined;
     const sourceCommit = process.env.GITHUB_SHA || undefined;
-    const ciRun = process.env.GITHUB_RUN_ID
-        ? `${process.env.GITHUB_SERVER_URL || 'https://github.com'}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+    // Both halves must be present: the URL interpolates the repo as well as the
+    // run id, so guarding only the run id records
+    // `https://github.com/undefined/actions/runs/123` as the audit trail — a
+    // link that resolves nowhere, in the one field whose entire job is to be
+    // followable later.
+    const ciRun = sourceRepo && process.env.GITHUB_RUN_ID
+        ? `${process.env.GITHUB_SERVER_URL || 'https://github.com'}/${sourceRepo}/actions/runs/${process.env.GITHUB_RUN_ID}`
         : undefined;
 
     return {
@@ -82,11 +102,36 @@ export async function preparePublish({ projectRoot = resolve('.'), version: vers
     };
 }
 
-/** `vX.Y.Z` (GITHUB_REF_NAME) → `X.Y.Z`. */
+/**
+ * `vX.Y.Z` (GITHUB_REF_NAME) → `X.Y.Z`.
+ *
+ * A non-tag ref passes through unchanged — `main` stays `main` — so a caller
+ * feeding this from CI must gate on isVersionTag() before publishing with the
+ * result (informer-ci refuses outright; informer-publish falls back to the
+ * package.json version).
+ */
 export function tagVersion(ref) {
     return ref ? ref.replace(/^v/, '') : undefined;
 }
 
+/** Semver-ish: x.y.z with optional prerelease/build. What the LM will accept. */
+export function looksLikeVersion(value) {
+    return typeof value === 'string' && /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/.test(value);
+}
+
+/**
+ * Does this CI ref name a publishable version? Only a tag-shaped ref counts:
+ * GITHUB_REF_TYPE must not say otherwise, and the version the ref yields must
+ * look like a version. Without this gate, a workflow_dispatch against a
+ * branch has GITHUB_REF_NAME=main — publishing a version literally called
+ * "main", on the STABLE channel (no prerelease dash). Both bins share this
+ * predicate so they can't drift.
+ */
+export function isVersionTag(refType, refName) {
+    if (refType && refType !== 'tag') return false;
+    return looksLikeVersion(tagVersion(refName));
+}
+
 export function defaultSlug(value) {
     if (!value) return undefined;
     const base = value.startsWith('@') && value.includes('/') ? value.split('/')[1] : value;
@@ -99,7 +144,10 @@ async function resolveIcon(root, configured) {
         const abs = resolve(root, rel);
         try {
             await access(abs);
-            return { abs, filename: rel.split(/[/\\]/).pop() };
+            // `rel` rides along for warnings: every default candidate shares
+            // the basename favicon.svg, so filename alone can't say WHICH
+            // file was picked.
+            return { abs, rel, filename: rel.split(/[/\\]/).pop() };
         } catch {
             // try next candidate
         }

package/src/publish.js

@@ -93,6 +93,26 @@ export async function publish({ marketplaceUrl, token, files, fields, icon, scre
         body: form
     });
 
+    return await readPublishResponse(res, url);
+}
+
+/**
+ * Turn the `/packs/publish` response into a result object, or throw
+ * PublishError. Exported so the parse contract is testable without staging an
+ * archive and stubbing fetch.
+ *
+ * Both directions tolerate a body they can't read, and for the same reason:
+ * whether the version landed is decided by the status, never by our ability to
+ * parse what came back. An unguarded `res.json()` here meant a 204 or an empty
+ * 2xx threw SyntaxError *after* the marketplace had stored the version, which
+ * the caller could only read as a publish failure — CI exits 1, the re-run
+ * 409s "version already exists", and someone debugs a publish that succeeded.
+ *
+ * `{}` (rather than null/undefined) keeps the shape callers destructure —
+ * `result.warnings`, `result.channel` — which is also why a literal `null`
+ * body, valid JSON that parses to null, is normalized away.
+ */
+export async function readPublishResponse(res, url) {
     if (!res.ok) {
         let body = '';
         try {
@@ -103,5 +123,9 @@ export async function publish({ marketplaceUrl, token, files, fields, icon, scre
         throw new PublishError(res.status, body, url);
     }
 
-    return await res.json();
+    try {
+        return (await res.json()) ?? {};
+    } catch {
+        return {};
+    }
 }