@entrinsik/vite-plugin-informer 2.6.0-beta.2 → 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/package.json

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

package/src/assemble.js

@@ -14,7 +14,10 @@ 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'];
+// 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

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'));