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

package/bin/ci.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+/**
+ * informer-ci — publish one build to every configured marketplace, using
+ * GitHub Actions OIDC instead of a stored publish key.
+ *
+ * The workflow step is deliberately inert:
+ *
+ *     permissions:
+ *       id-token: write
+ *     ...
+ *     - run: npx informer-ci
+ *       env:
+ *         INFORMER_MARKETPLACES: ${{ vars.INFORMER_MARKETPLACES }}
+ *
+ * Everything interesting lives here rather than in YAML, so fixing it is an
+ * npm release rather than a pull request into every customer's repo.
+ *
+ * For a single marketplace with a `lmpub_` key — locally, or on CI that is not
+ * GitHub Actions — use `informer-publish` instead. This command needs the OIDC
+ * endpoint only GitHub's runner provides.
+ */
+
+import { appendFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { publish } from '../src/publish.js';
+import { preparePublish, tagVersion } from '../src/publish-payload.js';
+import { parseMarketplaces, normalizeMarketplaceUrl } from '../src/marketplaces.js';
+import { canMintIdToken, mintIdToken } from '../src/github-oidc.js';
+import { loadEnv, parseModeArg } from '../src/env.js';
+
+const mode = parseModeArg(process.argv);
+loadEnv({ mode });
+
+const projectRoot = resolve('.');
+
+// --- Targets: explicit flags replace the configured list entirely, so a
+//     workflow_dispatch can re-publish to a subset without editing config. ---
+let targets;
+try {
+    const explicit = argValues('--marketplace').map(normalizeMarketplaceUrl);
+    targets = explicit.length ? [...new Set(explicit)] : parseMarketplaces(process.env.INFORMER_MARKETPLACES);
+} catch (err) {
+    fail(err.message);
+}
+
+if (!targets.length) {
+    fail(
+        'No marketplaces configured. Set the INFORMER_MARKETPLACES repo variable to one cloud-api URL per line, e.g.\n' +
+        '    https://lm.example.com/cloud-api\n' +
+        '  or pass --marketplace <url>.'
+    );
+}
+
+if (!canMintIdToken()) {
+    fail(
+        'informer-ci needs GitHub Actions OIDC, which is not available here.\n' +
+        '  In a workflow, give the job `permissions: id-token: write`.\n' +
+        '  Outside GitHub Actions, publish with a key instead: informer-publish.'
+    );
+}
+
+// --- Build the payload ONCE. Every marketplace gets identical bytes. ---
+let payload;
+try {
+    payload = await preparePublish({
+        projectRoot,
+        version: argValue('--version') || tagVersion(process.env.GITHUB_REF_NAME)
+    });
+} catch (err) {
+    fail(err.message);
+}
+
+for (const w of payload.warnings || []) console.warn(`  warning: ${w}`);
+
+const { name, slug, version, channel, files, icon, screenshots } = payload;
+console.log(
+    `Publishing ${name} v${version} (${channel}) to ${targets.length} marketplace${targets.length === 1 ? '' : 's'} — ` +
+    `${files.length} files${screenshots.length ? `, ${screenshots.length} screenshot${screenshots.length === 1 ? '' : 's'}` : ''}`
+);
+
+// --- Fan out. One target failing must not stop the others: a marketplace that
+//     is down should not withhold the release from the ones that are up. ---
+const results = [];
+for (const marketplaceUrl of targets) {
+    const label = hostOf(marketplaceUrl);
+    try {
+        // Audience is the marketplace itself, so a token minted for one
+        // License Manager is not replayable at another.
+        const token = await mintIdToken(marketplaceUrl);
+        const result = await publish({ marketplaceUrl, token, files, icon, screenshots, fields: payload.fields });
+        for (const w of result.warnings || []) console.warn(`  warning (${label}): ${w}`);
+        console.log(`  ✓ ${label} — published ${slug} v${version} (${result.channel || channel})`);
+        results.push({ label, ok: true });
+    } catch (err) {
+        console.error(`  ✗ ${label} — ${err.message}`);
+        results.push({ label, ok: false, error: err.message });
+    }
+}
+
+await writeSummary(results);
+
+const failed = results.filter(r => !r.ok);
+if (failed.length) {
+    console.error(`\n${failed.length} of ${results.length} marketplaces failed.`);
+    process.exit(1);
+}
+
+// --- helpers ---
+
+function argValue(flag) {
+    const i = process.argv.indexOf(flag);
+    return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : undefined;
+}
+
+/** Every occurrence of a repeatable flag, e.g. --marketplace a --marketplace b. */
+function argValues(flag) {
+    const out = [];
+    process.argv.forEach((arg, i) => {
+        if (arg === flag && process.argv[i + 1]) out.push(process.argv[i + 1]);
+    });
+    return out;
+}
+
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    } catch {
+        return url;
+    }
+}
+
+/**
+ * A per-target line in the job summary. Without this the Actions UI shows one
+ * opaque step for what is really N independent publishes — the observability
+ * the old matrix-of-jobs gave up when fan-out moved in here.
+ */
+async function writeSummary(rows) {
+    const path = process.env.GITHUB_STEP_SUMMARY;
+    if (!path || !rows.length) return;
+    const body = [
+        `### ${name} v${version} (${channel})`,
+        '',
+        '| Marketplace | Result |',
+        '| --- | --- |',
+        ...rows.map(r => `| ${r.label} | ${r.ok ? 'published' : `failed — ${r.error.replace(/\|/g, '\\|')}`} |`),
+        ''
+    ].join('\n');
+    await appendFile(path, body).catch(() => {
+        // A summary is a nicety; never fail a good publish over it.
+    });
+}
+
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}

package/bin/publish.js

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 
-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';
+/**
+ * informer-publish — publish this app to ONE marketplace using a vendor
+ * publish key. Works anywhere: locally, GitHub Actions, or any other CI.
+ *
+ * For fanning one build out to several marketplaces from GitHub Actions
+ * without storing a key, see `informer-ci` (OIDC trusted publishing).
+ */
+
+import { resolve } from 'node:path';
 import { publish } from '../src/publish.js';
+import { preparePublish, tagVersion } from '../src/publish-payload.js';
 import { loadEnv, parseModeArg } from '../src/env.js';
 
 const mode = parseModeArg(process.argv);
@@ -19,80 +25,44 @@ if (!marketplaceUrl || !token) {
     console.error('Missing required environment variables.');
     console.error('  INFORMER_MARKETPLACE_URL=https://<license-manager-host>/cloud-api');
     console.error('  INFORMER_PUBLISH_TOKEN=lmpub_<vendor publish key>');
+    if (process.env.INFORMER_MARKETPLACES) {
+        console.error('\nINFORMER_MARKETPLACES is set — for a multi-marketplace CI publish, run `informer-ci` instead.');
+    }
     process.exit(1);
 }
 
-// --- App + listing metadata from package.json "informer" block ---
-const projectRoot = resolve('.');
-let pkg;
-try {
-    pkg = JSON.parse(await readFile(join(projectRoot, 'package.json'), 'utf8'));
-} catch {
-    console.error('Could not read package.json in current directory.');
-    process.exit(1);
-}
-
-const inf = pkg.informer || {};
-const name = inf.name || pkg.name;
-const slug = inf.slug || defaultSlug(name);
-
-// Version: prefer the git tag (CI: GITHUB_REF_NAME=vX.Y.Z), then --version, then package.json.
-const version = argValue('--version') || tagVersion(process.env.GITHUB_REF_NAME) || pkg.version;
-
-if (!name || !slug || !version) {
-    console.error('Need a name, slug, and version. Set package.json "informer.name"/"informer.slug" and tag a release (vX.Y.Z) or pass --version.');
-    process.exit(1);
+// A repo mid-migration to trusted publishing can have both configured. Publish
+// what it was asked to publish, but say that only one target is being used.
+if (process.env.INFORMER_MARKETPLACES && process.env.GITHUB_ACTIONS) {
+    console.warn('Note: INFORMER_MARKETPLACES is set but ignored here — `informer-ci` is the multi-marketplace command.');
 }
 
-// Release notes: the section for this version, else the cumulative Unreleased block.
-const changeNotes = await extractNotes(join(projectRoot, 'CHANGELOG.md'), version);
-
-// 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}`
-    : undefined;
+const projectRoot = resolve('.');
 
-// Assemble the same file set a deploy produces.
-let files;
+let payload;
 try {
-    files = await collectAppFiles({ distDir: join(projectRoot, 'dist'), projectRoot });
+    payload = await preparePublish({
+        // Prefer an explicit --version, then the git tag (CI: GITHUB_REF_NAME=vX.Y.Z),
+        // then package.json.
+        version: argValue('--version') || tagVersion(process.env.GITHUB_REF_NAME),
+        projectRoot
+    });
 } catch (err) {
     console.error(err.message);
     process.exit(1);
 }
 
-const icon = await resolveIcon(projectRoot, inf.icon);
-const screenshots = await resolveScreenshots(projectRoot, inf.screenshots);
-const channel = version.includes('-') ? 'beta' : 'stable';
+for (const w of payload.warnings || []) console.warn(`  warning: ${w}`);
 
-console.log(`Publishing ${name} v${version} (${channel}) — ${files.length} files${screenshots.length ? `, ${screenshots.length} screenshot${screenshots.length === 1 ? '' : 's'}` : ''}${changeNotes ? '' : ' — no release notes found'}`);
+const { name, slug, version, channel, files, icon, screenshots, fields } = payload;
+
+console.log(`Publishing ${name} v${version} (${channel}) — ${files.length} files${screenshots.length ? `, ${screenshots.length} screenshot${screenshots.length === 1 ? '' : 's'}` : ''}${fields.changeNotes ? '' : ' — no release notes found'}`);
 
 try {
-    const result = await publish({
-        marketplaceUrl,
-        token,
-        files,
-        icon,
-        screenshots,
-        fields: {
-            name,
-            slug,
-            version,
-            shortDescription: inf.shortDescription,
-            description: inf.description || pkg.description,
-            categories: inf.categories,
-            documentationUrl: inf.documentationUrl,
-            requires: inf.requires,
-            metadata: inf.metadata,
-            changeNotes,
-            sourceRepo,
-            sourceCommit,
-            ciRun
-        }
-    });
+    const result = await publish({ marketplaceUrl, token, files, icon, screenshots, fields });
     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);
@@ -104,44 +74,3 @@ function argValue(flag) {
     const i = process.argv.indexOf(flag);
     return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : undefined;
 }
-
-function tagVersion(ref) {
-    return ref ? ref.replace(/^v/, '') : undefined;
-}
-
-function defaultSlug(value) {
-    if (!value) return undefined;
-    const base = value.startsWith('@') && value.includes('/') ? value.split('/')[1] : value;
-    return base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-}
-
-async function resolveIcon(root, configured) {
-    const candidates = [configured, 'favicon.svg', join('public', 'favicon.svg'), join('dist', 'favicon.svg')].filter(Boolean);
-    for (const rel of candidates) {
-        const abs = resolve(root, rel);
-        try {
-            await access(abs);
-            return { abs, filename: rel.split(/[/\\]/).pop() };
-        } catch {
-            // try next candidate
-        }
-    }
-    return undefined;
-}
-
-// Collect listing screenshots from a `screenshots/` directory (override via
-// package.json informer.screenshots), ordered by filename. Returns
-// [{abs, filename}] for the publisher to upload; empty when none exist.
-async function resolveScreenshots(root, configuredDir) {
-    const dir = resolve(root, configuredDir || 'screenshots');
-    let names;
-    try {
-        names = await readdir(dir);
-    } catch {
-        return []; // no screenshots directory — nothing to upload
-    }
-    return names
-        .filter(n => /\.(png|jpe?g|webp|gif)$/i.test(n))
-        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
-        .map(n => ({ abs: join(dir, n), filename: n }));
-}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@entrinsik/vite-plugin-informer",
-    "version": "2.6.0-beta.2",
+    "version": "2.7.0-beta.0",
     "description": "Vite plugin and deploy tool for Informer App development",
     "scripts": {
         "test": "node --test"
@@ -30,6 +30,7 @@
     "bin": {
         "informer-deploy": "./bin/deploy.js",
         "informer-publish": "./bin/publish.js",
+        "informer-ci": "./bin/ci.js",
         "informer-init": "./bin/init.js",
         "informer-workspace": "./bin/workspace.js",
         "create-magic-report": "./bin/init.js"

package/src/assemble.js

@@ -14,7 +14,14 @@ 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.
+// README.md is the docs fallback the gallery/app-menu Documentation surfaces
+// already honor server-side (docs.html is preferred — ship that via public/ so
+// 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'];
 
 // Entries never worth shipping in an app's server-side library: OS/editor
@@ -29,8 +36,12 @@ async function exists(path) {
     try {
         await access(path);
         return true;
-    } catch {
-        return false;
+    } catch (err) {
+        // Only genuine absence is a quiet skip. Anything else (EACCES, EIO)
+        // means the file is there but unreadable — silently dropping it would
+        // publish an incomplete archive with no signal, so fail the build.
+        if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return false;
+        throw new Error(`Cannot read "${path}" (${err.code}) — fix permissions or remove the file.`);
     }
 }
 

package/src/github-oidc.js

@@ -0,0 +1,58 @@
+/**
+ * GitHub Actions OIDC — "trusted publishing".
+ *
+ * The runner exposes a token-minting endpoint to jobs that declare
+ * `permissions: id-token: write`. The token it returns asserts which repository
+ * and workflow asked for it, signed by GitHub; the License Manager verifies it
+ * and maps the `repository` claim to a vendor account. Nothing long-lived is
+ * stored in the customer's repo, which is the whole point.
+ *
+ * The audience is requested PER MARKETPLACE, so a token minted for one License
+ * Manager cannot be replayed against another.
+ */
+
+const REQUEST_URL = 'ACTIONS_ID_TOKEN_REQUEST_URL';
+const REQUEST_TOKEN = 'ACTIONS_ID_TOKEN_REQUEST_TOKEN';
+
+/** True when the two runner-injected OIDC variables are present. */
+export function canMintIdToken() {
+    return Boolean(process.env[REQUEST_URL] && process.env[REQUEST_TOKEN]);
+}
+
+/**
+ * Mint an OIDC token for one marketplace.
+ *
+ * @param {string} audience the marketplace URL this token may be spent at
+ * @returns {Promise<string>} the JWT
+ */
+export async function mintIdToken(audience) {
+    const base = process.env[REQUEST_URL];
+    const requestToken = process.env[REQUEST_TOKEN];
+
+    if (!base || !requestToken) {
+        // Nearly always a missing permissions block: the variables are injected
+        // only for jobs that asked for the capability, so name the fix.
+        throw new Error(
+            'No GitHub OIDC token endpoint available. Add to the job:\n' +
+            '    permissions:\n' +
+            '      id-token: write\n' +
+            '  (or publish with a key using `informer-publish`).'
+        );
+    }
+
+    const url = `${base}&audience=${encodeURIComponent(audience)}`;
+    let res;
+    try {
+        res = await fetch(url, { headers: { Authorization: `Bearer ${requestToken}` } });
+    } catch (err) {
+        throw new Error(`Could not reach the GitHub OIDC token endpoint: ${err.message}`);
+    }
+
+    if (!res.ok) {
+        throw new Error(`GitHub refused to mint an OIDC token (${res.status} ${res.statusText}).`);
+    }
+
+    const body = await res.json().catch(() => ({}));
+    if (!body.value) throw new Error('GitHub OIDC token response contained no token.');
+    return body.value;
+}

package/src/marketplaces.js

@@ -0,0 +1,61 @@
+/**
+ * The list of marketplaces a CI publish fans out to.
+ *
+ * Fan-out lives in the CLI rather than the workflow, so the value never has to
+ * survive a YAML `fromJSON()` — which means it does not have to BE json. People
+ * edit this by hand in a repo-variable textarea, so accept the forms they
+ * actually type: a json array, or one URL per line, or comma-separated.
+ *
+ * Bare URLs on purpose, no labels. Nothing that writes this list (Studio, a
+ * human) knows whether an instance is dev, qa, or prod — only the person
+ * reading the hostname does.
+ */
+export function parseMarketplaces(raw) {
+    if (!raw) return [];
+
+    const trimmed = String(raw).trim();
+    let values;
+
+    if (trimmed.startsWith('[')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        } catch (err) {
+            throw new Error(`INFORMER_MARKETPLACES looks like JSON but does not parse: ${err.message}`);
+        }
+        if (!Array.isArray(parsed)) throw new Error('INFORMER_MARKETPLACES must be an array of marketplace URLs.');
+        values = parsed;
+    } else {
+        values = trimmed.split(/[\s,]+/);
+    }
+
+    const urls = values.map(v => String(v).trim()).filter(Boolean).map(normalizeMarketplaceUrl);
+
+    // A duplicate would publish the same version twice to one marketplace, and
+    // the second attempt 409s — turning a working config into a red build.
+    return [...new Set(urls)];
+}
+
+/**
+ * Canonical form for comparison and display.
+ *
+ * A trailing slash makes two spellings of one marketplace look like two
+ * marketplaces — which matters most to whatever is checking "am I already in
+ * this list?" before appending.
+ */
+export function normalizeMarketplaceUrl(value) {
+    let url;
+    try {
+        url = new URL(String(value).trim());
+    } catch {
+        throw new Error(`Not a valid marketplace URL: ${value}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`Marketplace URL must be http(s): ${value}`);
+    }
+    url.hostname = url.hostname.toLowerCase();
+    url.pathname = url.pathname.replace(/\/+$/, '');
+    url.hash = '';
+    url.search = '';
+    return url.toString();
+}

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-payload.js

@@ -0,0 +1,125 @@
+import { readFile, access, readdir } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { collectAppFiles } from './assemble.js';
+import { extractNotes } from './changelog.js';
+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.
+ *
+ * Throws on anything that should stop a publish; the bins print and exit.
+ */
+export async function preparePublish({ projectRoot = resolve('.'), version: versionOverride } = {}) {
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(join(projectRoot, 'package.json'), 'utf8'));
+    } catch {
+        throw new Error('Could not read package.json in current directory.');
+    }
+
+    const inf = pkg.informer || {};
+    const name = inf.name || pkg.name;
+    const slug = inf.slug || defaultSlug(name);
+    const version = versionOverride || pkg.version;
+
+    if (!name || !slug || !version) {
+        throw new Error('Need a name, slug, and version. Set package.json "informer.name"/"informer.slug" and tag a release (vX.Y.Z) or pass --version.');
+    }
+
+    // Release notes: the section for this version, else the cumulative Unreleased block.
+    const changeNotes = await extractNotes(join(projectRoot, 'CHANGELOG.md'), version);
+
+    // Assemble the same file set a deploy produces.
+    const files = await collectAppFiles({ distDir: join(projectRoot, 'dist'), projectRoot });
+
+    // Freeze the API contract with this version: build the OpenAPI doc from the
+    // local handlers and ship it in the archive as root openapi.json — the
+    // License Manager extracts it, stores it per version, and diffs the public
+    // surface against the previous version.
+    const { spec: apiSpec, warnings } = await buildLocalOpenApi({ projectRoot, name, slug, version });
+    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);
+
+    // 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}`
+        : undefined;
+
+    return {
+        name,
+        slug,
+        version,
+        // The server derives the channel too; this copy is for local reporting.
+        channel: version.includes('-') ? 'beta' : 'stable',
+        files,
+        icon,
+        screenshots,
+        warnings,
+        fields: {
+            name,
+            slug,
+            version,
+            shortDescription: inf.shortDescription,
+            description: inf.description || pkg.description,
+            categories: inf.categories,
+            documentationUrl: inf.documentationUrl,
+            requires: inf.requires,
+            metadata: inf.metadata,
+            changeNotes,
+            sourceRepo,
+            sourceCommit,
+            ciRun
+        }
+    };
+}
+
+/** `vX.Y.Z` (GITHUB_REF_NAME) → `X.Y.Z`. */
+export function tagVersion(ref) {
+    return ref ? ref.replace(/^v/, '') : undefined;
+}
+
+export function defaultSlug(value) {
+    if (!value) return undefined;
+    const base = value.startsWith('@') && value.includes('/') ? value.split('/')[1] : value;
+    return base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+async function resolveIcon(root, configured) {
+    const candidates = [configured, 'favicon.svg', join('public', 'favicon.svg'), join('dist', 'favicon.svg')].filter(Boolean);
+    for (const rel of candidates) {
+        const abs = resolve(root, rel);
+        try {
+            await access(abs);
+            return { abs, filename: rel.split(/[/\\]/).pop() };
+        } catch {
+            // try next candidate
+        }
+    }
+    return undefined;
+}
+
+// Collect listing screenshots from a `screenshots/` directory (override via
+// package.json informer.screenshots), ordered by filename. Returns
+// [{abs, filename}] for the publisher to upload; empty when none exist.
+async function resolveScreenshots(root, configuredDir) {
+    const dir = resolve(root, configuredDir || 'screenshots');
+    let names;
+    try {
+        names = await readdir(dir);
+    } catch {
+        return []; // no screenshots directory — nothing to upload
+    }
+    return names
+        .filter(n => /\.(png|jpe?g|webp|gif)$/i.test(n))
+        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+        .map(n => ({ abs: join(dir, n), filename: n }));
+}

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