@entrinsik/vite-plugin-informer 2.6.0 → 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,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 } from '../src/publish-payload.js';
 import { loadEnv, parseModeArg } from '../src/env.js';
 
 const mode = parseModeArg(process.argv);
@@ -20,87 +25,41 @@ 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);
 }
 
-// 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 +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",
+    "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

@@ -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/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/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 }));
+}