@entrinsik/vite-plugin-informer 2.6.0 → 2.7.0

package/bin/ci.js

@@ -0,0 +1,158 @@
+#!/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. And
+ * everything testable lives in src/fan-out.js rather than here — this file
+ * is only argv/env handling, console output, and the exit code.
+ *
+ * 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, isVersionTag, looksLikeVersion } from '../src/publish-payload.js';
+import { resolveTargets, fanOut, summaryTable, failedTargets } from '../src/fan-out.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('.');
+
+let targets;
+try {
+    targets = resolveTargets({
+        explicit: argValues('--marketplace'),
+        configured: 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.'
+    );
+}
+
+// The version comes from the tag that triggered the run. On a branch push or
+// a workflow_dispatch against a branch, GITHUB_REF_NAME is the branch name —
+// and without this guard the run would publish a version literally called
+// "main", on the STABLE channel (no prerelease dash), to every marketplace.
+// The predicate is shared with informer-publish (src/publish-payload.js).
+const explicitVersion = argValue('--version');
+if (explicitVersion && !looksLikeVersion(explicitVersion)) {
+    fail(`--version "${explicitVersion}" doesn't look like a version (x.y.z, or x.y.z-beta.n).`);
+}
+if (!explicitVersion && !isVersionTag(process.env.GITHUB_REF_TYPE, process.env.GITHUB_REF_NAME)) {
+    fail(
+        `informer-ci publishes the version named by the tag that triggered the run, ` +
+        `but this run's ref is ${process.env.GITHUB_REF_TYPE || 'ref'} "${process.env.GITHUB_REF_NAME || '(unset)'}" — not a version tag.\n` +
+        '  Run the workflow against a vX.Y.Z tag, or pass --version <x.y.z>.'
+    );
+}
+const refVersion = tagVersion(process.env.GITHUB_REF_NAME);
+
+// --- Build the payload once: every marketplace gets the same file set. ---
+let payload;
+try {
+    payload = await preparePublish({ projectRoot, version: explicitVersion || refVersion });
+} 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'}` : ''}`
+);
+
+const results = await fanOut({
+    targets,
+    mint: mintIdToken,
+    publishOne: ({ marketplaceUrl, token }) =>
+        publish({ marketplaceUrl, token, files, icon, screenshots, fields: payload.fields }),
+    onSuccess: (label, result) => {
+        for (const w of result.warnings || []) console.warn(`  warning (${label}): ${w}`);
+        console.log(`  ✓ ${label} — published ${slug} v${version} (${result.channel || channel})`);
+    },
+    onFailure: (label, message) => {
+        console.error(`  ✗ ${label} — ${message}`);
+    }
+});
+
+await writeSummary(results);
+
+// A row that published but whose reporting threw: the ✓ line above is missing
+// for it, so say what happened rather than leaving a silent gap. Not a failure
+// — the release is live, and exiting 1 here invites a re-run that 409s.
+for (const r of results.filter(r => r.reportError)) {
+    console.warn(`  warning (${r.label}): published, but reporting failed — ${r.reportError}`);
+}
+
+const failed = failedTargets(results);
+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;
+}
+
+async function writeSummary(rows) {
+    const path = process.env.GITHUB_STEP_SUMMARY;
+    if (!path || !rows.length) return;
+    const body = summaryTable({ title: `${name} v${version} (${channel})`, rows });
+    await appendFile(path, body).catch(err => {
+        // A summary is a nicety; never fail a good publish over it — but say
+        // why it's missing rather than leaving its absence a mystery.
+        console.warn(`  warning: could not write the job summary: ${err.message}`);
+    });
+}
+
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}

package/bin/publish.js

@@ -1,11 +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';
-import { buildLocalOpenApi } from '../src/openapi-local.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, isVersionTag } from '../src/publish-payload.js';
 import { loadEnv, parseModeArg } from '../src/env.js';
 
 const mode = parseModeArg(process.argv);
@@ -20,87 +25,48 @@ 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);
+// 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.');
 }
 
-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;
+const projectRoot = resolve('.');
 
-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);
+// Prefer an explicit --version, then the git tag (CI: GITHUB_REF_NAME=vX.Y.Z),
+// then package.json. A branch ref is NOT a version tag: without the gate, a
+// branch push on Actions published a version literally called "main" — so a
+// non-tag ref falls through to package.json, and says so.
+const refIsTag = isVersionTag(process.env.GITHUB_REF_TYPE, process.env.GITHUB_REF_NAME);
+if (process.env.GITHUB_REF_NAME && !refIsTag && !argValue('--version')) {
+    console.warn(`Note: ref "${process.env.GITHUB_REF_NAME}" is not a version tag — using the package.json version.`);
 }
 
-// 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;
-
-// Assemble the same file set a deploy produces.
-let files;
+let payload;
 try {
-    files = await collectAppFiles({ distDir: join(projectRoot, 'dist'), projectRoot });
+    payload = await preparePublish({
+        version: argValue('--version') || (refIsTag ? tagVersion(process.env.GITHUB_REF_NAME) : undefined),
+        projectRoot
+    });
 } catch (err) {
     console.error(err.message);
     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) });
+for (const w of payload.warnings || []) console.warn(`  warning: ${w}`);
 
-const icon = await resolveIcon(projectRoot, inf.icon);
-const screenshots = await resolveScreenshots(projectRoot, inf.screenshots);
-const channel = version.includes('-') ? 'beta' : 'stable';
+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'}` : ''}${changeNotes ? '' : ' — no release notes found'}`);
+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}`);
@@ -115,44 +81,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",
+    "version": "2.7.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

@@ -17,7 +17,11 @@ import { join, relative, posix } from 'node:path';
 // 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'];
+// 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
@@ -32,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/fan-out.js

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

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

package/src/publish-payload.js

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

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