@entrinsik/vite-plugin-informer 2.6.0-beta.1 → 2.6.0

package/bin/publish.js

@@ -4,6 +4,7 @@ import { readFile, access, readdir } from 'node:fs/promises';
 import { resolve, join } from 'node:path';
 import { collectAppFiles } from '../src/assemble.js';
 import { extractNotes } from '../src/changelog.js';
+import { buildLocalOpenApi } from '../src/openapi-local.js';
 import { publish } from '../src/publish.js';
 import { loadEnv, parseModeArg } from '../src/env.js';
 
@@ -63,6 +64,14 @@ try {
     process.exit(1);
 }
 
+// Freeze the API contract with this version: build the OpenAPI doc from the
+// local handlers (see openapi-local.js) and ship it in the archive as root
+// openapi.json — the License Manager extracts it (like informer.yaml), stores
+// it per version, and diffs the public surface against the previous version.
+const { spec: apiSpec, warnings: apiWarnings } = await buildLocalOpenApi({ projectRoot, name, slug, version });
+for (const w of apiWarnings) console.warn(`  warning: ${w}`);
+if (apiSpec) files.push({ rel: 'openapi.json', content: JSON.stringify(apiSpec, null, 2) });
+
 const icon = await resolveIcon(projectRoot, inf.icon);
 const screenshots = await resolveScreenshots(projectRoot, inf.screenshots);
 const channel = version.includes('-') ? 'beta' : 'stable';
@@ -93,6 +102,8 @@ try {
         }
     });
     console.log(`Published ${slug} v${version} (${result.channel || channel}).`);
+    // Server-side advisories (e.g. "public API changed without a major bump").
+    for (const w of result.warnings || []) console.warn(`  warning: ${w}`);
 } catch (err) {
     console.error(err.message);
     process.exit(1);

package/index.d.ts

@@ -1,9 +1,11 @@
 import type { Plugin } from 'vite';
 
 /**
- * Dev-only binding for a `target: app` dependency slot. Points `request()` at
- * the target app in dev; overrides the manifest `defaultBinding` when both are
- * present.
+ * Dev-only binding for a `target: app` or `target: pack` dependency slot.
+ * Points `request()` at the target app in dev. For app slots it overrides the
+ * manifest `defaultBinding` when both are present; for pack slots it is the
+ * only way to bind — the marketplace pin has no install to resolve against in
+ * dev, so point it at your locally-installed copy of the pack's app.
  *
  * - `app` — the target app (`owner:slug` or UUID). Powers `request()`.
  *

package/package.json

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

package/src/agent-dev.js

@@ -29,21 +29,23 @@ async function loadInformerYaml(projectRoot) {
 }
 
 /**
- * Scan the tools/ directory for .js files that export a handler.
+ * Scan the tools/ and mcp/ directories for .js files that export a handler.
+ * Both share one tool namespace; agents may reference tools from either.
  *
  * @param {string} projectRoot
  * @returns {Promise<Array<{ name: string, filePath: string }>>}
  */
 async function scanLocalTools(projectRoot) {
-    const toolsDir = join(projectRoot, 'tools');
-    try {
-        await access(toolsDir);
-    } catch {
-        return [];
-    }
-
     const tools = [];
-    await walkToolFiles(toolsDir, 'tools', tools);
+    for (const dirName of ['tools', 'mcp']) {
+        const toolsDir = join(projectRoot, dirName);
+        try {
+            await access(toolsDir);
+        } catch {
+            continue;
+        }
+        await walkToolFiles(toolsDir, dirName, tools);
+    }
     return tools;
 }
 
@@ -64,7 +66,7 @@ async function walkToolFiles(dir, basePath, results) {
             await walkToolFiles(full, childPath, results);
         } else if (item.endsWith('.js')) {
             const name = childPath
-                .replace(/^tools\//, '')
+                .replace(/^(tools|mcp)\//, '')
                 .replace(/\.js$/, '')
                 .replace(/\//g, '_');
             results.push({ name, filePath: full });

package/src/assemble.js

@@ -14,8 +14,11 @@ import { join, relative, posix } from 'node:path';
  * (index.html, assets/…), while the source trees keep their directory prefix
  * (server/…, tools/…) — matching how an app's library is structured in Informer.
  */
-const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml'];
-const SOURCE_DIRS = ['migrations', 'tools', 'server', 'webhooks', 'lib', 'shared'];
+// API.md is the author-written integration guide: deployed to the library root
+// (the live openapi.json route folds it into info.description) and tarred into
+// the published archive for the marketplace listing's Integrate surface.
+const ROOT_CONFIG_FILES = ['informer.yaml', 'data-access.yaml', 'API.md'];
+const SOURCE_DIRS = ['migrations', 'tools', 'mcp', 'server', 'webhooks', '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/deploy.js

@@ -105,7 +105,7 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
     await api.post(`${entityPath}/files/_clear`);
 
     // 6. Upload the app-library file set: dist output at the library root, plus
-    //    informer.yaml / data-access.yaml and the server/tools/migrations/webhooks
+    //    informer.yaml / data-access.yaml and the server/tools/mcp/migrations/webhooks
     //    source trees. Sourced from the shared collectAppFiles() so a deploy and a
     //    marketplace publish package byte-identical contents.
     console.log('Uploading files...');
@@ -160,6 +160,9 @@ export async function deploy({ baseUrl, apiKey, user, pass, distDir, name, descr
                 if (result.tools && result.tools.length > 0) {
                     console.log(`  Registered ${result.tools.length} tool(s): ${result.tools.join(', ')}`);
                 }
+                if (result.mcpTools && result.mcpTools.length > 0) {
+                    console.log(`  Registered ${result.mcpTools.length} MCP tool(s): ${result.mcpTools.join(', ')}`);
+                }
                 if (result.agents && result.agents.length > 0) {
                     console.log(`  Deployed ${result.agents.length} agent(s): ${result.agents.join(', ')}`);
                 }

package/src/dev-dependencies.js

@@ -150,11 +150,13 @@ export function buildDevMessaging(logPrefix = '[app]') {
 // reject the same shapes with the same wording. Keep these in lockstep.
 const DEPENDENCY_NAME_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const VALID_TARGETS = new Set(['dataset', 'query', 'datasource', 'integration', 'app']);
+const VALID_TARGETS = new Set(['dataset', 'query', 'datasource', 'integration', 'app', 'pack']);
 const VALID_RUN_AS = new Set(['user', 'owner']);
 
 // Targets that accept `defaultBinding:` in the manifest — mirrors
 // DEFAULT_BINDING_LOOKUP in deploy.js. All resolve the target under read_access.
+// `pack` is deliberately absent: its identity is the marketplace pin
+// (`pack:` + `requires:`), and the installer consents per instance.
 const DEFAULT_BINDABLE_TARGETS = new Set(['dataset', 'query', 'datasource', 'integration', 'app']);
 
 const METHOD_SURFACE = {
@@ -162,7 +164,8 @@ const METHOD_SURFACE = {
     query: ['execute'],
     datasource: ['query'],
     integration: ['request'],
-    app: ['request']
+    app: ['request'],
+    pack: ['request']
 };
 
 // Cross-app request() method allow-list — mirrors REQUEST_METHODS in
@@ -246,6 +249,11 @@ export function validateDependencies(deps) {
         if (!VALID_RUN_AS.has(runAs)) {
             errors.push(`dependency "${name}": runAs must be 'user' or 'owner' (got "${runAs}")`);
         }
+        // `target: pack` pins marketplace identity at the top level of the
+        // declaration — same check (and wording) as deploy.js.
+        if (decl.target === 'pack' && (typeof decl.pack !== 'string' || typeof decl.requires !== 'string')) {
+            errors.push(`dependency "${name}" (pack) requires "pack: <marketplace slug>" and "requires: <semver range>"`);
+        }
         if (decl.defaultBinding != null) {
             if (!DEFAULT_BINDABLE_TARGETS.has(decl.target)) {
                 // Same rejection the deploy performs — surface it at dev boot
@@ -268,9 +276,12 @@ export function validateDependencies(deps) {
  * the first call reports the slot as unbound — telling the developer to add the
  * thing they think they already added.
  *
- * A binding key must name a declared `target: app` dependency; its value must be
- * a non-empty `owner:slug` string (shorthand for `{ app }`) or an object with a
- * non-empty `app` (the target app, for request()).
+ * A binding key must name a declared `target: app` or `target: pack`
+ * dependency; its value must be a non-empty `owner:slug` string (shorthand for
+ * `{ app }`) or an object with a non-empty `app` (the target app, for
+ * request()). For a pack slot the value points at your locally-installed copy
+ * of the pack's app — dev has no marketplace install to resolve the pin
+ * against, so the developer says where it lives.
  *
  * @param {Object} deps - The raw `dependencies:` object from informer.yaml
  * @param {Object} devBindings - The plugin's `devBindings` option
@@ -285,8 +296,8 @@ export function validateDevBindings(deps, devBindings) {
             errors.push(`devBindings."${name}": no dependency "${name}" is declared in informer.yaml`);
             continue;
         }
-        if (decl.target !== 'app') {
-            errors.push(`devBindings."${name}": only "target: app" dependencies take a devBinding (got "${decl.target}")`);
+        if (decl.target !== 'app' && decl.target !== 'pack') {
+            errors.push(`devBindings."${name}": only "target: app" and "target: pack" dependencies take a devBinding (got "${decl.target}")`);
             continue;
         }
         if (typeof binding === 'string') {
@@ -356,17 +367,20 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
         const target = decl.target;
         if (!VALID_TARGETS.has(target)) continue;
 
-        // App slots bind from the plugin's `devBindings` (a human `owner:slug`
-        // pointing request() at the target app), falling back to the manifest
-        // `defaultBinding` UUID like every other target. request() is the only
-        // surface.
-        if (target === 'app') {
-            const fallback = (typeof decl.defaultBinding === 'string' && UUID_PATTERN.test(decl.defaultBinding))
+        // App and pack slots bind from the plugin's `devBindings` (a human
+        // `owner:slug` pointing request() at the target app). App slots fall
+        // back to the manifest `defaultBinding` UUID; pack slots have no
+        // fallback — the pin resolves via marketplace installs, which dev
+        // doesn't have, so the devBinding names the locally-installed app.
+        // request() is the only surface either way.
+        if (target === 'app' || target === 'pack') {
+            const fallback = (target === 'app'
+                && typeof decl.defaultBinding === 'string' && UUID_PATTERN.test(decl.defaultBinding))
                 ? decl.defaultBinding
                 : null;
             const binding = devBindings[name] != null ? devBindings[name] : fallback;
             context[name] = binding
-                ? makeAppDevProxy({ name, binding, appFetch })
+                ? makeAppDevProxy({ name, binding, appFetch, kind: target })
                 : makeUnboundDevProxy({ name, target });
             continue;
         }
@@ -383,7 +397,12 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
 }
 
 /**
- * Dev proxy for a `target: app` slot. `request()` is the only surface.
+ * Dev proxy for a `target: app` or `target: pack` slot. `request()` is the
+ * only surface. Pack slots reuse this wholesale — in production the pack
+ * driver resolves its marketplace pin and then delegates the runtime to the
+ * app driver, and the devBinding IS that resolution done by hand. The prod
+ * version gate (pack_dependency_out_of_range) is not emulated: dev has no
+ * pack_install to read a version from.
  *
  * Production runs `request()` through the target's own /view/_/ dispatch, and
  * dev injects into the same route:
@@ -404,29 +423,31 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
  *   manifest defaultBinding UUID). A bare string is shorthand for `{ app }`.
  * @param {Function|null} args.appFetch - token-authed fetch, or null when
  *   INFORMER_APP_TOKEN is unset.
+ * @param {'app'|'pack'} [args.kind] - slot flavor, for error labels and the
+ *   structured resourceType guest code branches on.
  */
-function makeAppDevProxy({ name, binding, appFetch }) {
+function makeAppDevProxy({ name, binding, appFetch, kind = 'app' }) {
     const { app } = resolveAppBinding(binding);
 
     return {
         async request(payload) {
             if (!app) {
                 throw new Error(
-                    `Dependency "${name}" (app): dev request() needs the target app — set devBindings.${name}.app (e.g. 'admin:kanban')`
+                    `Dependency "${name}" (${kind}): dev request() needs the target app — set devBindings.${name}.app (e.g. 'admin:kanban')`
                 );
             }
             if (!appFetch) {
                 throw new Error(
-                    `Dependency "${name}" (app): dev request() needs a Bearer credential — the target's /view/_/ dispatch does not accept basic auth. Run in API-key mode (INFORMER_API_KEY), or create a token (Admin → Tokens, or POST /api/tokens) and set INFORMER_APP_TOKEN in .env`
+                    `Dependency "${name}" (${kind}): dev request() needs a Bearer credential — the target's /view/_/ dispatch does not accept basic auth. Run in API-key mode (INFORMER_API_KEY), or create a token (Admin → Tokens, or POST /api/tokens) and set INFORMER_APP_TOKEN in .env`
                 );
             }
             const { method = 'GET', url, params, data } = payload || {};
             const httpMethod = String(method).toUpperCase();
             if (!REQUEST_METHODS.includes(httpMethod)) {
-                throw new Error(`Dependency "${name}" (app): unsupported method "${method}"`);
+                throw new Error(`Dependency "${name}" (${kind}): unsupported method "${method}"`);
             }
             if (!url || typeof url !== 'string') {
-                throw new Error(`Dependency "${name}" (app): request({ url }) requires the target route path`);
+                throw new Error(`Dependency "${name}" (${kind}): request({ url }) requires the target route path`);
             }
             const path = url.replace(/^\/+/, '');
             const search = params ? `?${new URLSearchParams(params).toString()}` : '';
@@ -440,17 +461,17 @@ function makeAppDevProxy({ name, binding, appFetch }) {
             try {
                 resolvedPath = new URL(`${targetPrefix}${path}${search}`, 'http://localhost').pathname;
             } catch {
-                throw new Error(`Dependency "${name}" (app): request({ url }) is malformed`);
+                throw new Error(`Dependency "${name}" (${kind}): request({ url }) is malformed`);
             }
             if (!resolvedPath.startsWith(targetPrefix)) {
-                throw new Error(`Dependency "${name}" (app): request({ url }) must not escape the target app with ".." path segments`);
+                throw new Error(`Dependency "${name}" (${kind}): request({ url }) must not escape the target app with ".." path segments`);
             }
             const { status, body, contentType } = await appFetch(
                 `apps/${encodeURIComponent(app)}/view/_/${path}${search}`,
                 { method: httpMethod, body: data }
             );
             if (status >= 400) {
-                throw dependencyCallError(name, 'app', status, body);
+                throw dependencyCallError(name, kind, status, body);
             }
             // Success-envelope contract mirrors entity-type/app.js: JSON → parsed
             // body; non-JSON text/HTML → text envelope; binary → not emulatable
@@ -458,7 +479,7 @@ function makeAppDevProxy({ name, binding, appFetch }) {
             // silently hand back mangled bytes.
             if (isBinaryContentType(contentType)) {
                 throw new Error(
-                    `Dependency "${name}" (app): the dev proxy can't return binary responses yet (upstream content-type "${contentType}"). Test binary endpoints against a deployed build.`
+                    `Dependency "${name}" (${kind}): the dev proxy can't return binary responses yet (upstream content-type "${contentType}"). Test binary endpoints against a deployed build.`
                 );
             }
             // (An empty content-type gets the text envelope too, matching prod.)
@@ -514,10 +535,14 @@ function makeDevProxy({ name, target, targetId, apiFetch }) {
 function makeUnboundDevProxy({ name, target }) {
     const methods = METHOD_SURFACE[target] || [];
     // App slots bind via devBindings (a dev-local owner:slug) or a manifest
-    // defaultBinding UUID, so point at whichever the reader is likelier to want.
+    // defaultBinding UUID; pack slots ONLY via devBindings (the pin has no
+    // marketplace install to resolve against in dev). Point at whichever the
+    // reader is likelier to want.
     const hint = target === 'app'
         ? `add \`devBindings: { ${name}: { app: '<owner:slug>' } }\` to the informer() plugin options in vite.config.js, or \`defaultBinding: <uuid>\` to its entry in informer.yaml`
-        : 'add `defaultBinding: <uuid>` to its entry in informer.yaml';
+        : target === 'pack'
+            ? `add \`devBindings: { ${name}: { app: '<owner:slug>' } }\` to the informer() plugin options in vite.config.js, pointing at your locally-installed copy of the pack`
+            : 'add `defaultBinding: <uuid>` to its entry in informer.yaml';
     const proxy = {};
     for (const method of methods) {
         proxy[method] = async () => {

package/src/index.js

@@ -45,8 +45,10 @@ async function writeAppDepTypes (projectRoot, dts) {
  * @param {Object} [options]
  * @param {{ report?: object, theme?: 'light'|'dark', roles?: string[] }} [options.mock]
  *   window.__INFORMER__ mock injected in dev.
- * @param {Object} [options.devBindings] - dev bindings for `target: app` deps,
- *   which can't be defaultBound in the manifest. See AppDevBinding 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
+ *   binding names the locally-installed app. See AppDevBinding in index.d.ts.
  * @param {Object} [options.proxy] - extra Vite proxy options merged onto /api.
  * @returns {import('vite').Plugin}
  */
@@ -184,9 +186,9 @@ export default function informer(options = {}) {
                 console.error(`[informer] vite.config.js: ${message}`);
             }
 
-            // Generate .d.ts types for bound `target: app` deps from their
-            // published OpenAPI docs, so server/ handlers get typed
-            // context.<slot>.request()/query() autocomplete.
+            // Generate .d.ts types for bound `target: app` / `target: pack`
+            // deps from their published OpenAPI docs, so server/ handlers get
+            // typed context.<slot>.request()/query() autocomplete.
             try {
                 // A bare string devBinding is shorthand for { app } — request()
                 // works under it, so its types must generate too, not just for
@@ -194,7 +196,7 @@ export default function informer(options = {}) {
                 const boundAppRef = (name) =>
                     resolveAppBinding(options.devBindings && options.devBindings[name]).app;
                 const appSlots = Object.entries(deps).filter(
-                    ([name, decl]) => decl && decl.target === 'app' && boundAppRef(name)
+                    ([name, decl]) => decl && (decl.target === 'app' || decl.target === 'pack') && boundAppRef(name)
                 );
                 if (appSlots.length) {
                     const specs = {};
@@ -257,8 +259,9 @@ export default function informer(options = {}) {
                     devWorkspaceId,
                     projectRoot,
                     roles: (options.mock && options.mock.roles) || [],
-                    // Dev-only bindings for `target: app` slots (override the
-                    // manifest defaultBinding for local dev). Shape:
+                    // 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
@@ -266,11 +269,12 @@ export default function informer(options = {}) {
                 server.middlewares.use('/api/_server', serverRoutes);
             }
 
-            // Mount agent dev middleware if tools/ or informer.yaml agents exist
+            // Mount agent dev middleware if tools/, mcp/, or informer.yaml agents exist
             const toolsDir = resolve(projectRoot, 'tools');
+            const mcpDir = resolve(projectRoot, 'mcp');
             const yamlPath = resolve(projectRoot, 'informer.yaml');
 
-            if (existsSync(toolsDir) || existsSync(yamlPath)) {
+            if (existsSync(toolsDir) || existsSync(mcpDir) || existsSync(yamlPath)) {
                 const agentDev = createAgentMiddleware(server, {
                     serverOrigin,
                     authHeader,

package/src/openapi-local.js

@@ -0,0 +1,283 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { filePathToRoute, walkJsFiles } from './server-routes.js';
+
+// Build the app's OpenAPI 3.0.3 document from the LOCAL project at publish
+// time — the frozen, per-version contract the marketplace stores alongside the
+// changelog. CI often has no access to the Informer host an app was developed
+// against, so this cannot fetch the live /apps/{id}/openapi.json; instead the
+// handlers are import()ed (this runs in the author's own project, where
+// executing their code is exactly what vite does anyway) and their real
+// exports — methods, config, schema, description — are read directly.
+//
+// The document-shaping half below is a deliberate port of
+// informer-server/modules/app/lib/openapi-emitter.js (the deploy-time emitter):
+// the frozen doc must match what a live instance serves for the same source.
+// Keep the two in sync when either changes. This package publishes to npm on
+// its own, so importing across the monorepo is not an option.
+
+const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const HTTP_METHOD_KEYS = new Set(VALID_METHODS);
+
+// Fallback when a handler cannot be import()ed (a missing optional dep, a
+// top-level env access that only resolves in dev): the file still contributes
+// skeleton routes (method + path) so the frozen doc doesn't silently lose them.
+const METHOD_EXPORT_RE = /export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\b|export\s+(?:const|let|var)\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
+
+function routePathToOpenApi(path) {
+    return path.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+}
+
+function pathParamNames(path) {
+    const names = new Set();
+    const re = /:([A-Za-z0-9_]+)/g;
+    let m;
+    while ((m = re.exec(path)) !== null) names.add(m[1]);
+    return [...names];
+}
+
+function operationId(method, path) {
+    const slug = path.split('/').filter(Boolean)
+        .map(seg => (seg.startsWith(':') ? `by_${seg.slice(1)}` : seg))
+        .join('_') || 'root';
+    return `${method.toLowerCase()}_${slug}`;
+}
+
+// OpenAPI 3.0.3 Schema Object keywords, by required value type (port of the
+// server emitter's sanitizeSchema — see file header).
+const SCHEMA_STRING_KEYS = new Set(['type', 'format', 'title', 'description', 'pattern']);
+const SCHEMA_NUMBER_KEYS = new Set(['multipleOf', 'maximum', 'minimum', 'maxLength', 'minLength', 'maxItems', 'minItems', 'maxProperties', 'minProperties']);
+const SCHEMA_BOOLEAN_KEYS = new Set(['exclusiveMaximum', 'exclusiveMinimum', 'uniqueItems', 'nullable', 'readOnly', 'writeOnly', 'deprecated']);
+const SCHEMA_ANY_KEYS = new Set(['default', 'example']);
+const SCHEMA_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'array', 'object']);
+const MAX_SCHEMA_DEPTH = 32;
+
+function sanitizeSchema(schema, depth = 0) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return null;
+    if (depth >= MAX_SCHEMA_DEPTH) return null;
+
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (SCHEMA_STRING_KEYS.has(key)) {
+            if (typeof value !== 'string') continue;
+            if (key === 'type' && !SCHEMA_TYPES.has(value)) continue;
+            out[key] = value;
+        } else if (SCHEMA_NUMBER_KEYS.has(key)) {
+            if (typeof value === 'number') out[key] = value;
+        } else if (SCHEMA_BOOLEAN_KEYS.has(key)) {
+            if (typeof value === 'boolean') out[key] = value;
+        } else if (SCHEMA_ANY_KEYS.has(key)) {
+            out[key] = value;
+        } else if (key === 'enum') {
+            if (Array.isArray(value) && value.length) out.enum = value;
+        } else if (key === 'required') {
+            const names = Array.isArray(value) ? value.filter(v => typeof v === 'string') : [];
+            if (names.length) out.required = names;
+        } else if (key === 'properties') {
+            if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
+            const props = {};
+            for (const [name, sub] of Object.entries(value)) {
+                const clean = sanitizeSchema(sub, depth + 1);
+                props[name] = clean || {};
+            }
+            out.properties = props;
+        } else if (key === 'items' || key === 'not') {
+            const clean = sanitizeSchema(value, depth + 1);
+            if (clean) out[key] = clean;
+        } else if (key === 'allOf' || key === 'anyOf' || key === 'oneOf') {
+            const clean = (Array.isArray(value) ? value : []).map(v => sanitizeSchema(v, depth + 1)).filter(Boolean);
+            if (clean.length) out[key] = clean;
+        } else if (key === 'additionalProperties') {
+            if (typeof value === 'boolean') out.additionalProperties = value;
+            else {
+                const clean = sanitizeSchema(value, depth + 1);
+                if (clean) out.additionalProperties = clean;
+            }
+        }
+        // anything else (including $ref) is dropped
+    }
+
+    if (out.type === 'array' && !out.items) out.items = {};
+
+    return Object.keys(out).length ? out : null;
+}
+
+// A method-keyed `export const schema` returns its per-method slice; a flat
+// schema applies to every method (mirror of the server scanner's sliceSchema).
+function sliceSchema(schema, method) {
+    if (!schema || typeof schema !== 'object') return null;
+    const methodKeyed = Object.keys(schema).some(k => HTTP_METHOD_KEYS.has(k));
+    if (!methodKeyed) return schema;
+    return schema[method] || null;
+}
+
+function buildOperation(row) {
+    const cfg = row.config || {};
+    const s = (row.schema && typeof row.schema === 'object') ? row.schema : {};
+    const successDesc = cfg.responseDescription ? String(cfg.responseDescription) : 'Success';
+
+    const op = {
+        operationId: operationId(row.method, row.path),
+        responses: {}
+    };
+
+    if (cfg.summary) op.summary = String(cfg.summary);
+    const desc = cfg.description || row.description;
+    if (desc) op.description = String(desc);
+    if (cfg.deprecated) op.deprecated = true;
+    if (Array.isArray(cfg.tags) && cfg.tags.length) op.tags = cfg.tags.map(String);
+
+    const params = pathParamNames(row.path).map(name => ({
+        name,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' }
+    }));
+    if (s.query && s.query.properties && typeof s.query.properties === 'object') {
+        const required = new Set(Array.isArray(s.query.required) ? s.query.required : []);
+        for (const [name, propSchema] of Object.entries(s.query.properties)) {
+            params.push({
+                name,
+                in: 'query',
+                required: required.has(name),
+                schema: sanitizeSchema(propSchema) || {}
+            });
+        }
+    }
+    if (params.length) op.parameters = params;
+
+    const body = sanitizeSchema(s.body);
+    if (body) {
+        op.requestBody = { content: { 'application/json': { schema: body } } };
+    }
+
+    const response = sanitizeSchema(s.response);
+    if (response) {
+        op.responses['200'] = {
+            description: successDesc,
+            content: { 'application/json': { schema: response } }
+        };
+    } else {
+        op.responses['200'] = { description: successDesc };
+    }
+
+    if (Array.isArray(cfg.roles) && cfg.roles.length) {
+        op['x-informer-roles'] = cfg.roles.map(String);
+    }
+
+    // Curated public surface — see the server emitter for semantics.
+    if (cfg.api === 'public') {
+        op['x-informer-public'] = true;
+    }
+
+    return op;
+}
+
+/**
+ * Import every server/ handler and read its real exports into emitter rows.
+ * Returns { rows, warnings }: a file that fails to import degrades to skeleton
+ * routes (regex-detected methods) with a warning, never a lost route.
+ */
+async function collectLocalRoutes(projectRoot) {
+    const files = await walkJsFiles(join(projectRoot, 'server'), 'server');
+    const rows = [];
+    const warnings = [];
+
+    for (const { relPath, absPath } of files) {
+        const routePath = filePathToRoute(relPath);
+        let mod = null;
+        try {
+            mod = await import(pathToFileURL(absPath).href);
+        } catch (err) {
+            warnings.push(`${relPath}: could not be imported (${err.message}) — frozen doc keeps its routes at skeleton level`);
+        }
+
+        if (mod) {
+            for (const method of VALID_METHODS) {
+                if (typeof mod[method] !== 'function') continue;
+                rows.push({
+                    method,
+                    path: routePath,
+                    handlerPath: relPath,
+                    config: (mod.config && typeof mod.config === 'object') ? mod.config : {},
+                    description: typeof mod.description === 'string' ? mod.description : null,
+                    schema: sliceSchema((mod.schema && typeof mod.schema === 'object') ? mod.schema : null, method)
+                });
+            }
+        } else {
+            const source = await readFile(absPath, 'utf8');
+            const methods = new Set();
+            let m;
+            while ((m = METHOD_EXPORT_RE.exec(source)) !== null) methods.add(m[1] || m[2]);
+            for (const method of methods) {
+                rows.push({ method, path: routePath, handlerPath: relPath, config: {}, description: null, schema: null });
+            }
+        }
+    }
+
+    // Deterministic doc: same ordering the live endpoint uses.
+    rows.sort((a, b) => (a.path === b.path ? a.method.localeCompare(b.method) : a.path.localeCompare(b.path)));
+    return { rows, warnings };
+}
+
+/**
+ * Build the frozen OpenAPI document for a publish.
+ *
+ * The installing tenant's naturalId ({owner}:{slug}) is unknowable at publish
+ * time, so the dispatch base is emitted as an OpenAPI server variable with the
+ * slug as its default.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.name - listing name (info.title)
+ * @param {string} opts.slug - marketplace slug
+ * @param {string} opts.version - the version being published (info.version)
+ * @returns {Promise<{ spec: Object|null, warnings: string[] }>} spec is null
+ *   when the app has no server/ routes at all (nothing to freeze).
+ */
+export async function buildLocalOpenApi({ projectRoot, name, slug, version }) {
+    const { rows, warnings } = await collectLocalRoutes(projectRoot);
+    if (!rows.length) return { spec: null, warnings };
+
+    const paths = {};
+    const usedIds = new Set();
+    for (const row of rows) {
+        const oaPath = routePathToOpenApi(row.path);
+        paths[oaPath] = paths[oaPath] || {};
+        const op = buildOperation(row);
+        while (usedIds.has(op.operationId)) {
+            const m = op.operationId.match(/^(.*?)(?:_(\d+))?$/);
+            op.operationId = `${m[1]}_${(parseInt(m[2], 10) || 1) + 1}`;
+        }
+        usedIds.add(op.operationId);
+        paths[oaPath][row.method.toLowerCase()] = op;
+    }
+
+    let description;
+    try {
+        description = await readFile(join(projectRoot, 'API.md'), 'utf8');
+    } catch {
+        // no API.md — fall through to the generated blurb
+    }
+
+    const spec = {
+        openapi: '3.0.3',
+        info: {
+            title: name || slug,
+            version: String(version),
+            description: description || (
+                `Auto-generated from the server/ routes of "${name || slug}". ` +
+                'Invoke a route through a cross-app dependency: context.<slot>.request({ method, url }).'
+            )
+        },
+        servers: [{
+            url: '/api/apps/{app}/view/_',
+            description: 'App server-route dispatch base ({app} is the installed naturalId, owner:name)',
+            variables: { app: { default: slug } }
+        }],
+        paths
+    };
+
+    return { spec, warnings };
+}

package/src/publish.js

@@ -1,4 +1,4 @@
-import { mkdtemp, mkdir, copyFile, rm, readFile } from 'node:fs/promises';
+import { mkdtemp, mkdir, copyFile, rm, readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { execFile } from 'node:child_process';
@@ -24,17 +24,21 @@ export { PublishError };
  * the server's node-tar expects; COPYFILE_DISABLE suppresses macOS AppleDouble
  * (`._*`) junk from leaking into the archive.
  *
- * @param {Array<{abs: string, rel: string}>} files
+ * Entries carry either `abs` (copied from disk) or `content` (generated at
+ * publish time, e.g. the frozen openapi.json).
+ *
+ * @param {Array<{abs?: string, rel: string, content?: string}>} files
  * @returns {Promise<Buffer>}
  */
 async function buildArchive(files) {
     const stage = await mkdtemp(join(tmpdir(), 'informer-publish-'));
     const archivePath = `${stage}.tgz`;
     try {
-        for (const { abs, rel } of files) {
+        for (const { abs, rel, content } of files) {
             const dest = join(stage, rel);
             await mkdir(dirname(dest), { recursive: true });
-            await copyFile(abs, dest);
+            if (content !== undefined) await writeFile(dest, content);
+            else await copyFile(abs, dest);
         }
         await execFileP('tar', ['-czf', archivePath, '-C', stage, '.'], {
             env: { ...process.env, COPYFILE_DISABLE: '1' }

package/src/server-routes.js

@@ -9,9 +9,21 @@ const VALID_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 // hanging the handler.
 const FETCH_TIMEOUT_MS = 30000;
 
-// Strict base64 — see view-api.js for the rationale. Mirror kept identical
-// to keep dev and prod behavior aligned.
-const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+// Strict base64 — see view-api.js for the rationale. Mirror kept identical to
+// keep dev and prod behavior aligned, down to the scan: the quantified
+// /^[A-Za-z0-9+/]+={0,2}$/ throws "RangeError: Maximum call stack size
+// exceeded" instead of answering once a body passes ~4M characters, so dev
+// would 500 on exactly the large images and PDFs prod serves fine.
+const NON_BASE64 = /[^A-Za-z0-9+/]/;   // unquantified: never backtracks
+
+function isBase64(s) {
+    if (typeof s !== 'string') return false;
+    let end = s.length;
+    while (end > 0 && s.charCodeAt(end - 1) === 0x3d /* '=' */) end--;
+    if (s.length - end > 2) return false;
+    if (end === 0) return true;                  // '', '=', '==' → zero bytes
+    return !NON_BASE64.test(end === s.length ? s : s.slice(0, end));
+}
 
 /**
  * Convert a file path under server/ to a route path.
@@ -120,6 +132,8 @@ async function scanRoutes(serverDir) {
     }));
 }
 
+export { filePathToRoute, walkJsFiles };
+
 async function walkJsFiles(dir, basePath) {
     const results = [];
     let items;
@@ -398,7 +412,7 @@ export function createMiddleware(viteServer, { serverOrigin, authHeader, devWork
             if (responseBody === null) {
                 res.end();
             } else if (encoding === 'base64' && typeof responseBody === 'string') {
-                if (!BASE64_RE.test(responseBody)) {
+                if (!isBase64(responseBody)) {
                     throw new Error('Handler returned malformed base64 body');
                 }
                 res.end(Buffer.from(responseBody, 'base64'));