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

package/bin/ci.js

@@ -14,7 +14,9 @@
  *         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.
+ * 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
@@ -24,8 +26,8 @@
 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 { 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';
 
@@ -34,12 +36,12 @@ 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);
+    targets = resolveTargets({
+        explicit: argValues('--marketplace'),
+        configured: process.env.INFORMER_MARKETPLACES
+    });
 } catch (err) {
     fail(err.message);
 }
@@ -60,13 +62,28 @@ if (!canMintIdToken()) {
     );
 }
 
-// --- Build the payload ONCE. Every marketplace gets identical bytes. ---
+// 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: argValue('--version') || tagVersion(process.env.GITHUB_REF_NAME)
-    });
+    payload = await preparePublish({ projectRoot, version: explicitVersion || refVersion });
 } catch (err) {
     fail(err.message);
 }
@@ -79,28 +96,30 @@ console.log(
     `${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 });
+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})`);
-        results.push({ label, ok: true });
-    } catch (err) {
-        console.error(`  ✗ ${label} — ${err.message}`);
-        results.push({ label, ok: false, error: err.message });
+    },
+    onFailure: (label, message) => {
+        console.error(`  ✗ ${label} — ${message}`);
     }
-}
+});
 
 await writeSummary(results);
 
-const failed = results.filter(r => !r.ok);
+// 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);
@@ -122,32 +141,14 @@ function argValues(flag) {
     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.
+    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}`);
     });
 }
 

package/bin/publish.js

@@ -10,7 +10,7 @@
 
 import { resolve } from 'node:path';
 import { publish } from '../src/publish.js';
-import { preparePublish, tagVersion } from '../src/publish-payload.js';
+import { preparePublish, tagVersion, isVersionTag } from '../src/publish-payload.js';
 import { loadEnv, parseModeArg } from '../src/env.js';
 
 const mode = parseModeArg(process.argv);
@@ -39,12 +39,19 @@ if (process.env.INFORMER_MARKETPLACES && process.env.GITHUB_ACTIONS) {
 
 const projectRoot = resolve('.');
 
+// 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.`);
+}
+
 let payload;
 try {
     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),
+        version: argValue('--version') || (refIsTag ? tagVersion(process.env.GITHUB_REF_NAME) : undefined),
         projectRoot
     });
 } catch (err) {

package/package.json

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

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/marketplaces.js

@@ -53,9 +53,35 @@ export function normalizeMarketplaceUrl(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.pathname = url.pathname.replace(/\/+$/, '');
     url.hash = '';
     url.search = '';
-    return url.toString();
+    // 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

@@ -8,9 +8,11 @@ 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.
+ * 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.
  */
@@ -44,14 +46,32 @@ export async function preparePublish({ projectRoot = resolve('.'), version: vers
     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;
-    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}`
+    // 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 {
@@ -82,11 +102,36 @@ export async function preparePublish({ projectRoot = resolve('.'), version: vers
     };
 }
 
-/** `vX.Y.Z` (GITHUB_REF_NAME) → `X.Y.Z`. */
+/**
+ * `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;
@@ -99,7 +144,10 @@ async function resolveIcon(root, configured) {
         const abs = resolve(root, rel);
         try {
             await access(abs);
-            return { abs, filename: rel.split(/[/\\]/).pop() };
+            // `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
         }

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 {};
+    }
 }