@entrinsik/vite-plugin-informer 2.7.0 → 2.11.0

package/README.md

@@ -0,0 +1,131 @@
+# @entrinsik/vite-plugin-informer
+
+Vite plugin and deploy tool for Informer App development: a local dev server wired to a live Informer, and a deploy pipeline that assembles your project and ships it to an App's library.
+
+## Quick start
+
+```bash
+npm create vite@latest my-app -- --template react
+cd my-app
+npm install -D @entrinsik/vite-plugin-informer
+npx informer-init                          # wires vite config, informer.yaml, .env, deploy scripts
+npm run dev                                # local dev against the Informer in .env
+npm run deploy                             # assemble + upload + deploy
+```
+
+## What a deploy ships
+
+The assembler uploads your built frontend plus these source trees, matching how an App's library is structured in Informer:
+
+| Folder | Becomes |
+|---|---|
+| `server/` | API routes, dispatched under the App's `/api` surface |
+| `webhooks/` | Publicly callable webhook routes |
+| `tools/` | AI tools, private to the App's agents |
+| `mcp/` | Tools exposed over the App's MCP endpoint |
+| `channels/` | Live channel handlers: `join` / `joined` / `leave` and event-named handlers for `channel.send()`; `npm run dev` runs them locally, and the `channels:` block in `informer.yaml` declares relays only (each entry needs `on`) |
+| `migrations/` | Workspace database migrations, run in order on deploy |
+| `embeddings/` | Declarative embedding use cases (see below) |
+| `lib/`, `shared/` | Modules importable by the trees above |
+
+`informer.yaml` declares dependencies, raw API access, roles, and (optionally) a minimum Informer version.
+
+## Server compatibility
+
+A deploy begins by asking the target server what it is (`GET /api/about`, one unauthenticated request) and adapts to the answer, so one version of this plugin can drive a fleet on mixed releases.
+
+Everything below needs **Informer 2026.1.3**: App Channels (`channels/`, the `channels:` block, `broadcast()`), the embedding pump (`embeddings/`, `embed()`), staged uploads/downloads (`uploads`/`downloads` on the handler bag, `__INFORMER__.upload()`), and the `platform` descriptor itself.
+
+Against an older server the CLI:
+
+- **Leaves `channels/` and `embeddings/` on your disk.** Those releases don't recognise the folders as server-side, so anything uploaded there is served to any App viewer — your workspace SQL and channel authorization logic included. The rest of the App deploys normally; the warning names what was skipped and why.
+- **Names every feature that would be inert**, so a green deploy can't be mistaken for a working one.
+- **Enforces `requires: { informer: … }` itself.** Releases before 2026.1.3 ignore the block, so without this an App that declared a floor would deploy clean onto a server that can't run it. The deploy is refused before the App's library is touched.
+
+A server whose version isn't comparable (a `dev` build, or an `/about` behind a proxy) is treated as current and warned about — gating it would break deploys to builds made from source.
+
+App Channels phase 2 (plugin 2.11.0: `channel.send()`, the `joined` export and event-named exports in `channels/` files, wildcard subscriptions, frame `seq` and replay, `connected`) needs a 2026.1.3 server that carries I5-13027. The version probe cannot tell such a server from an earlier 2026.1.3 build, so the deploy is not gated: an earlier build refuses a `channels/` file that exports `joined` or an event name, and accepts a `channels:` entry without `on` that a current server rejects. The dev server runs the phase 2 contract regardless.
+
+Feature-detect at runtime with optional chaining, since `platform` is absent entirely before 2026.1.3:
+
+```javascript
+if (platform?.capabilities?.channels) broadcast('tickets', { … });
+```
+
+A marketplace publish is unaffected: the archive always carries every source tree, because the server that installs it isn't known at publish time.
+
+## Embeddings
+
+Apps can maintain vector embeddings over their own workspace data declaratively. You ship an `embeddings/` folder with **one file per use case**; the Informer platform acts as an *embedding pump* that asks your App what is pending, chunks and embeds the content in billed batches, and hands the vectors back for your App to store in its own workspace tables. You never call an embedding provider yourself, and the platform never keeps a copy of your corpus — your own tables are the ledger.
+
+Each use case file exports `GET` and `POST` (a missing handler fails the deploy) and, optionally, a `config` literal; omitted keys take the defaults below, and a use case with no triggers in its config only runs on deploy and on a manual run:
+
+```javascript
+// embeddings/tickets.js
+export const config = { chunking: 'prose', on: ['ticket.created'], cron: '0 * * * *', revision: 1 };
+
+// GET: the rows that still need embedding. The query IS the watermark:
+// never embedded, stale, or written under an older revision.
+export async function GET({ query, batch }) {
+  return await query(`
+    SELECT t.id, t.subject || ' ' || t.body AS content
+    FROM tickets t
+    LEFT JOIN ticket_embeddings e ON e.ticket_id = t.id AND e.seq = 0
+    WHERE e.ticket_id IS NULL OR e.embedded_at < t.updated_at OR e.revision <> $2
+    ORDER BY t.id
+    LIMIT $1
+  `, [batch.limit, batch.revision]);
+}
+
+// POST: store the finished vectors wherever your migrations put them.
+export async function POST({ query, batch }) {
+  for (const doc of batch.docs) {
+    await query('DELETE FROM ticket_embeddings WHERE ticket_id = $1', [doc.id]);
+    for (const c of doc.chunks) {
+      await query(
+        'INSERT INTO ticket_embeddings (ticket_id, seq, embedding, content, revision) VALUES ($1, $2, $3::vector, $4, $5)',
+        [doc.id, c.seq, JSON.stringify(c.embedding), c.content, batch.revision]
+      );
+    }
+  }
+  return { stored: batch.docs.length };
+}
+```
+
+How it works, briefly:
+
+- **Your storage is the ledger.** Because `GET` anti-joins your own embedding table, the pump is idempotent and crash-tolerant: a run that dies mid-way finds the same rows pending next time.
+- **Triggers converge.** Deploy pokes each use case (initial backfill), `emit()` events matching `on:` poke, `cron` desugars into a scheduled poke, and the platform sweep runs whatever is poked. A manual run claims the same single-flight lease directly, so nothing double-embeds.
+- **Failures are bounded.** A run that fails for a reason the next attempt might not hit (a provider blip, a handler timeout) retries with a doubling delay and is parked after five consecutive failures; a run that cannot succeed as-is (a rejected key, an exhausted budget, a contract violation) is parked at once. Every park keeps the error on the use case's status row; the next trigger gives it one more attempt, and a successful run resets the count.
+- **`revision` is the invalidation.** The string the pump hands you couples your config (chunking profile, budgets, `config.revision`) to the resolved platform embedding model. Store it beside each vector and compare it in `GET`: bumping the config, changing chunking, or an admin repointing the embedding model all surface as pending re-embed work automatically.
+- **Unembeddable documents are tombstoned** platform-side by content hash and re-reported with `skipped: true` on every run — stamp them in your own table and exclude them from `GET`.
+- **Workspace pgvector.** Apps with the embeddings capability get the `vector` extension provisioned where the server may create extensions (otherwise the deploy log names the cause and a migration using the `vector` type fails), so migrations can declare real `vector(...)` columns; `ON DELETE CASCADE` foreign keys are the cleanup story.
+- **Query time.** Every handler bag (`server/`, `webhooks/`, `tools/`, `mcp/`) gets `embed(name, text)`, which returns `{ embedding, revision }`. `name` must be a declared use case. Filter on the revision as well as ordering by distance — an admin repointing the embedding model puts your query vectors in a new space while the stored rows are still in the old one, and an unfiltered `ORDER BY` then returns near-random neighbours with no error:
+
+```javascript
+const { embedding, revision } = await embed('tickets', q);
+const hits = await query(
+  `SELECT ticket_id, content
+     FROM ticket_embeddings
+    WHERE revision = $2
+    ORDER BY embedding <=> $1::vector
+    LIMIT 10`,
+  [JSON.stringify(embedding), revision]
+);
+```
+- **Billing.** Embedding calls bill to the App, one usage entry per batch of up to 128 chunks regardless of how many provider requests run underneath; pump compute meters against the App's compute budget.
+- **`config` is read as a literal.** Deploy lifts `export const config = { … }` out of the source and evaluates it with none of the file's imports in scope, so it must be self-contained: no imported constants, no spreads of imported objects, no `export { config }` re-export. Other modules may import the literal from the use-case file; the reverse fails the deploy. The same self-contained-literal rule applies to `export const config`, `schema`, and `description` in `server/`, `webhooks/`, `tools/`, and `mcp/`; there a `config` violation fails the deploy while a `schema` or `description` violation is a deploy warning (nothing is published for that export).
+
+### Dev loop
+
+`npm run deploy` uploads `embeddings/` like any other source tree — there is no manifest block to add (plugin ≥ 2.10.0; earlier versions never upload the folder, so the use case silently does not exist on the server). `npm run dev` never runs the pump, and its `embed()` throws an explanation rather than embedding (the dev mirror reports `platform.capabilities.embeddings: false`), so a search route is exercised against a deployed App. Feature-detect with `platform?.capabilities?.embeddings` — `typeof embed === 'function'` is true on both, since the binding exists either way. Then, in the App admin panel, the **Embeddings** tab lists each use case with its pump status (queued, running, up to date, last run, last error, skipped docs) and a **Run now** action; the same surface exists as API routes (`GET /apps/{id}/embeddings`, `POST /apps/{id}/embeddings/{name}/_run`). Deploy, run, read the error, fix, repeat.
+
+### Upgrading an App that already has an `embeddings/` folder
+
+`embeddings/` is a server-side folder from this release on, like `server/`: its files are uploaded with the library, never served to browsers, and scanned as pump handlers. An App that kept anything else there (assets, data files) loses those files in the browser after redeploying with plugin 2.10.0 or later. A `.js` file there that exports `GET` or `POST` but not both fails the deploy; one that exports neither is never scanned as a use case at all and lands as a warning on an otherwise successful deploy. Move such content elsewhere before upgrading; the deploy names every stray entry as a warning.
+
+### Older Informer releases
+
+The `embeddings/` folder, `embed()`, and the pump routes exist only on Informer releases that ship the feature. An App that must also run on older servers feature-detects with optional chaining (`platform?.capabilities?.embeddings` on the handler bag, `window.__INFORMER__.platform?.capabilities?.embeddings` in the browser) — releases before 2026.1.3 inject no `platform` descriptor at all, so a bare `platform.capabilities.embeddings` throws there instead of reporting `false`. It gates its vector DDL with a `-- requires: embeddings` header so the migration is skipped where pgvector is absent, and states a floor in `informer.yaml` (`requires: { informer: '>=…' }`) only if it cannot work without the feature.
+
+Full reference: the **Embeddings** article under Developer → API → App in the Informer docs.

package/bin/workspace.js

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

package/package.json

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

package/src/agent-dev.js

@@ -2,7 +2,18 @@ import { readFile, readdir, stat, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parse as parseUrl } from 'node:url';
 import yaml from 'yaml';
-import { loadDependencies, buildDevContext, loadAppEnv, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
+import { manifestBlock, buildDevContext, buildDevCrypto, buildDevMessaging, normalizeFetchPath } from './dev-dependencies.js';
+import { createDevChannels, createDevEmit } from './dev-channels.js';
+import { devPlatform } from './dev-platform.js';
+
+// embed() is present on a real install even without the embeddings
+// capability, where it throws a written explanation. Mirroring that here
+// keeps the dev failure the same lesson as the deployed one, instead of a
+// bare "embed is not a function" that reads like a missing binding.
+const embed = async () => {
+    throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
+};
+
 const parseYaml = yaml.parse;
 
 const MAX_STEPS = 20;
@@ -149,9 +160,11 @@ async function readSSE(response) {
  *
  * @param {Object} viteServer - Vite dev server instance
  * @param {Object} opts - Configuration
+ * @param {ReturnType<typeof createDevChannels>} [opts.channels] - the dev channels hub
+ *   behind `broadcast()` and the `channels:` relay (a private one when omitted)
  * @returns {Function} Connect middleware
  */
-export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken }) {
+export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, devWorkspaceId, projectRoot, devBindings, appToken, channels = createDevChannels() }) {
 
     // query() — proxies to the workspace _sql endpoint (same as server-routes.js)
     async function query(sql, params) {
@@ -226,12 +239,6 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
         ? async (path, opts = {}) => await fetchAs(appAuth, path, { ...opts, headers: { ...(opts.headers || {}), 'x-informer-app-depth': '1' } })
         : null;
 
-    // emit() — no-op in dev mode (logs to console)
-    function emit(event, payload) {
-        console.log(`[agent-dev] emit("${event}",`, JSON.stringify(payload), ')');
-        return { ok: true };
-    }
-
     // notify/email — delivery is a console-logged no-op in dev, but required-field
     // validation mirrors prod so a tool that passes here won't 500 in production.
     const { notify, email } = buildDevMessaging('[agent-dev]');
@@ -319,10 +326,17 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
                 // Build the typed dependency context + env the same way the
                 // server-routes dev middleware does, so tools using
                 // `context.<slot>.<method>(...)` and `env` work locally and match
-                // the prod sandbox bag.
-                const deps = await loadDependencies(projectRoot);
+                // the prod sandbox bag. The manifest is already in hand.
+                const deps = manifestBlock(yaml, 'dependencies');
                 const context = buildDevContext({ deps, apiFetch, devBindings, appFetch });
-                const env = await loadAppEnv(projectRoot);
+                const env = manifestBlock(yaml, 'env');
+
+                // emit() writes no app_event row in dev, but still relays a
+                // listed event to its `channels:` channel; broadcast() publishes
+                // a live frame to the page (see dev-channels.js).
+                const manifestChannels = manifestBlock(yaml, 'channels');
+                const emit = createDevEmit({ channels, manifestChannels, logPrefix: '[agent-dev]' });
+                const { broadcast } = channels;
 
                 // Load tool handlers via ssrLoadModule
                 const localTools = await scanLocalTools(projectRoot);
@@ -441,7 +455,7 @@ export function createAgentMiddleware(viteServer, { serverOrigin, authHeader, de
 
                         if (tool) {
                             try {
-                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, notify, email, crypto: cryptoHelper, markdown, log, env });
+                                result = await tool.handler({ args: tc.input, run: { agentName, trigger: triggerEvent }, context, query, fetch: apiFetch, emit, broadcast, notify, email, embed, crypto: cryptoHelper, markdown, log, env, platform: devPlatform() });
                             } catch (err) {
                                 console.error(`[agent-dev] Tool "${tc.name}" failed:`, err.message);
                                 result = { error: err.message };

package/src/assemble.js

@@ -22,7 +22,11 @@ import { join, relative, posix } from 'node:path';
 // the Vite build lands it at the library root). Without README.md here, a
 // CLI-deployed app could never light those surfaces up via its README.
 const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml', 'API.md', 'README.md'];
-const SOURCE_DIRS = ['migrations', 'tools', 'mcp', 'server', 'webhooks', 'lib', 'shared'];
+// channels/ holds live-channel join/leave handlers (App Channels); the server
+// scans and bundles it like server/ and webhooks/. `embeddings` holds the pump
+// use-case files: server-side like server/, so they ship with the library and
+// the platform can scan them.
+const SOURCE_DIRS = ['migrations', 'tools', 'mcp', 'server', 'webhooks', 'channels', 'embeddings', 'lib', 'shared'];
 
 // Entries never worth shipping in an app's server-side library: OS/editor
 // dotfiles (.DS_Store, .env), nested dependency trees, and test files. Applied

package/src/compat.js

@@ -0,0 +1,252 @@
+/**
+ * What the CLI needs to know about the Informer it is deploying to.
+ *
+ * The server exposes no route that reports its capability flags —
+ * describePlatform() rides on the app page and on the handler bag, never on the
+ * API — so compatibility is decided from the build version that GET /api/about
+ * reports. That route is `open: true` and has been unchanged across every
+ * release this plugin supports, which makes it the one probe that cannot itself
+ * be a compatibility problem.
+ *
+ * Floors, not probes: each feature names the release that introduced it
+ * server-side. Comparison mirrors the server's own versionSatisfies()
+ * (app/lib/platform-descriptor.js) — hotfix and RC builds carry a prerelease tag
+ * (`2026.1.3-hot2026…`) that plain semver ranks BELOW its base, which would
+ * refuse a feature on the very release that ships it, so only the numeric base
+ * is ever compared.
+ */
+
+/** The release that introduced each app feature server-side. */
+export const FEATURE_FLOORS = Object.freeze({
+    // App Channels: the `channels:` relay block, channels/ handlers, broadcast().
+    channels: '2026.1.3',
+    // The embedding pump: embeddings/ use cases and embed() on the handler bag.
+    embeddings: '2026.1.3',
+    // Staged uploads/downloads: the uploads/downloads services, /view/_uploads
+    // and /view/_downloads, and __INFORMER__.upload() in the page.
+    streams: '2026.1.3',
+    // The platform descriptor itself (window.__INFORMER__.platform and the
+    // handler bag's `platform`). Absent entirely below this floor, which is why
+    // feature detection has to be optional-chained.
+    platform: '2026.1.3',
+    // Server-side enforcement of the manifest's `requires:` block. Below this
+    // floor the CLI is the only thing in the loop that can honour a declared
+    // Informer floor, so it enforces it itself.
+    requiresGate: '2026.1.3'
+});
+
+/**
+ * Source trees whose contents must never reach a browser, paired with the
+ * release whose FOLDER_GATES list first covered them (app/routes/deploy.js).
+ *
+ * A server below the floor does not recognise the directory as server-side, so
+ * isServerSidePath() returns false for it and view-assets.js serves the file to
+ * anyone who can open the app. Uploading these to such a server would publish
+ * the App's workspace SQL and channel authorization logic, so the deploy leaves
+ * them behind instead.
+ *
+ * server/, webhooks/, tools/, mcp/ and migrations/ were gated long before any
+ * release this plugin supports and so need no floor here.
+ */
+export const GATED_SOURCE_DIRS = Object.freeze([
+    Object.freeze({ dir: 'channels', feature: 'channels', holds: 'channel join/leave handlers' }),
+    Object.freeze({ dir: 'embeddings', feature: 'embeddings', holds: 'embedding pump handlers (and the workspace SQL in them)' })
+]);
+
+/**
+ * The leading numeric triple of a build version, as semver.coerce() would read
+ * it: `2026.1.3-hot20260904` -> `2026.1.3`. Returns null when the string is not
+ * a version at all (`dev`), which callers treat as "unknown".
+ *
+ * @param {string} version
+ * @returns {{ major: number, minor: number, patch: number, version: string }|null}
+ */
+export function baseVersion(version) {
+    const match = /^\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(version == null ? '' : version));
+    if (!match) return null;
+    const [major, minor, patch] = [match[1], match[2], match[3]].map(part => Number(part || 0));
+    return { major, minor, patch, version: `${major}.${minor}.${patch}` };
+}
+
+/** -1, 0 or 1, comparing two parsed bases field by field. */
+function compareBase(a, b) {
+    for (const field of ['major', 'minor', 'patch']) {
+        if (a[field] !== b[field]) return a[field] < b[field] ? -1 : 1;
+    }
+    return 0;
+}
+
+/**
+ * Is `version` at or above `floor`? Unknown versions answer `true` — a build
+ * whose version is not semver is a developer build, and gating those would
+ * break the very people who build Informer from source.
+ *
+ * @param {string} version - a build version, as /about reports it
+ * @param {string} floor - a plain `X.Y.Z`
+ * @returns {boolean}
+ */
+export function atLeast(version, floor) {
+    const actual = baseVersion(version);
+    if (!actual) return true;
+    return compareBase(actual, baseVersion(floor)) >= 0;
+}
+
+// The comparator subset a manifest floor realistically uses. Full semver range
+// syntax would mean taking on the `semver` dependency, which this package
+// deliberately does without; anything outside this subset is reported as
+// unevaluated rather than guessed at.
+const RANGE = /^\s*(>=|<=|>|<|\^|~|=)?\s*v?(\d+(?:\.\d+){0,2})\s*$/;
+
+/**
+ * Evaluate a manifest `requires.informer` range against a build version, with
+ * the same coerced-base semantics the server uses.
+ *
+ * @param {string} version - the running build version
+ * @param {string} range - a range from informer.yaml
+ * @returns {{ ok: boolean, unknown: boolean, reason?: string }} `unknown` marks
+ *   a verdict the caller must not act on: an unparseable range, or a build
+ *   version that is not semver.
+ */
+export function satisfiesRange(version, range) {
+    const actual = baseVersion(version);
+    if (!actual) return { ok: true, unknown: true, reason: 'the server did not report a comparable version' };
+
+    const match = RANGE.exec(String(range == null ? '' : range));
+    if (!match) return { ok: true, unknown: true, reason: `"${range}" is not a range this CLI can evaluate` };
+
+    const [, operator = '=', literal] = match;
+    const wanted = baseVersion(literal);
+    const cmp = compareBase(actual, wanted);
+
+    switch (operator) {
+        case '>=': return { ok: cmp >= 0, unknown: false };
+        case '>': return { ok: cmp > 0, unknown: false };
+        case '<=': return { ok: cmp <= 0, unknown: false };
+        case '<': return { ok: cmp < 0, unknown: false };
+        // ^ allows the rest of the major, ~ the rest of the minor. Both still
+        // need the floor met, so a too-old server fails either way.
+        case '^': return { ok: cmp >= 0 && actual.major === wanted.major, unknown: false };
+        case '~': return { ok: cmp >= 0 && actual.major === wanted.major && actual.minor === wanted.minor, unknown: false };
+        default: return { ok: cmp === 0, unknown: false };
+    }
+}
+
+/**
+ * Ask a server what it is. Never throws: a probe that fails leaves the version
+ * unknown, and every gate built on it fails open with a warning rather than
+ * turning an unreachable /about into a failed deploy.
+ *
+ * @param {{ get: (path: string) => Promise<unknown> }} api
+ * @returns {Promise<{ version: string|null, base: string|null, unknown: boolean, supports: (feature: string) => boolean }>}
+ */
+export async function describeServer(api) {
+    let about = null;
+    try {
+        about = await api.get('about');
+    } catch {
+        // A proxy, a WAF, or an auth strategy in front of /about — none of which
+        // say anything about the server's age.
+    }
+
+    const version = (about && typeof about === 'object' && about.version) || null;
+    const base = baseVersion(version);
+
+    return {
+        version,
+        base: base ? base.version : null,
+        unknown: !base,
+        supports: (feature) => atLeast(version, FEATURE_FLOORS[feature] || '0.0.0')
+    };
+}
+
+/** The top-level library directory a collected file belongs to. */
+function topSegment(rel) {
+    return String(rel || '').replace(/^\/+/, '').split('/')[0].toLowerCase();
+}
+
+/**
+ * Decide what a deploy to this server may upload and what the developer has to
+ * be told. Pure, so the whole compatibility matrix is testable without a server.
+ *
+ * @param {Object} opts
+ * @param {{ version: string|null, base: string|null, unknown: boolean, supports: Function }} opts.server
+ * @param {Array<{ abs: string, rel: string }>} opts.files - from collectAppFiles()
+ * @param {Object} opts.manifest - the parsed informer.yaml, or {}
+ * @returns {{ files: Array, warnings: string[], refusal: string|null }}
+ */
+export function planDeploy({ server, files, manifest }) {
+    const warnings = [];
+    const where = server.version ? `Informer ${server.version}` : 'this Informer';
+
+    if (server.unknown) {
+        warnings.push(
+            `Could not read a comparable version from ${server.version ? `"${server.version}"` : 'GET /api/about'}. `
+            + 'Deploying everything on the assumption the server is current — if it is older than 2026.1.3, '
+            + `${GATED_SOURCE_DIRS.map(d => `${d.dir}/`).join(' and ')} will be readable from the App's view URL.`
+        );
+    }
+
+    // 1. Leave behind source trees this server would serve to browsers.
+    let kept = files;
+    for (const { dir, feature, holds } of GATED_SOURCE_DIRS) {
+        if (server.supports(feature)) continue;
+        const dropped = kept.filter(file => topSegment(file.rel) === dir);
+        if (dropped.length === 0) continue;
+        kept = kept.filter(file => topSegment(file.rel) !== dir);
+        warnings.push(
+            `Skipped ${dropped.length} file(s) in ${dir}/ — ${where} predates ${FEATURE_FLOORS[feature]} and does not treat `
+            + `${dir}/ as server-side, so uploading your ${holds} would leave them readable from the App's view URL. `
+            + `The App deploys without them; upgrade the server to ${FEATURE_FLOORS[feature]} to use this feature.`
+        );
+    }
+
+    // 2. Name every feature the App uses that is simply inert here, so a
+    //    successful deploy can't be mistaken for a working one.
+    const uploaded = new Set(kept.map(file => topSegment(file.rel)));
+    if (!server.supports('channels') && isMap(manifest.channels)) {
+        warnings.push(
+            `informer.yaml declares a channels: block, which ${where} ignores (App Channels needs ${FEATURE_FLOORS.channels}). `
+            + 'Nothing is relayed and broadcast() does not reach the page.'
+        );
+    }
+    if (!server.supports('streams') && uploaded.has('server')) {
+        warnings.push(
+            `${where} predates ${FEATURE_FLOORS.streams}: if a handler destructures uploads/downloads from its bag, or the page `
+            + 'calls __INFORMER__.upload() / downloadUrl(), those are undefined here and the staged stream routes answer 404.'
+        );
+    }
+    if (!server.supports('platform')) {
+        warnings.push(
+            `${where} injects no platform descriptor. Feature-detect with optional chaining `
+            + '(`platform?.capabilities?.x`, `window.__INFORMER__.platform?.capabilities?.x`) — a bare '
+            + '`platform.capabilities.x` throws here rather than reporting false.'
+        );
+    }
+
+    return { files: kept, warnings, refusal: refuseOnRequires({ server, manifest, where }) };
+}
+
+/** True for a YAML mapping (not a list, not a scalar). */
+function isMap(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * The manifest's `requires.informer` floor, enforced by the CLI on servers that
+ * do not enforce it themselves. Below FEATURE_FLOORS.requiresGate the server
+ * ignores the block entirely, so without this an App that declared a floor
+ * deploys clean onto a server that cannot run it and fails at runtime instead.
+ *
+ * @returns {string|null} the refusal message, or null to proceed
+ */
+function refuseOnRequires({ server, manifest, where }) {
+    const range = isMap(manifest.requires) && manifest.requires.informer;
+    if (!range || server.supports('requiresGate')) return null;
+
+    const verdict = satisfiesRange(server.version, range);
+    if (verdict.unknown || verdict.ok) return null;
+
+    // No "Deploy refused:" lead-in — bin/deploy.js already prints "Deploy failed:".
+    return `this app requires Informer ${range}, but this server is ${server.version}. `
+        + `Update Informer, or remove the requires.informer floor from informer.yaml if the app can run on ${where}.`;
+}