ovsx 1.1.1 → 1.2.0

package/src/show.ts

@@ -0,0 +1,328 @@
+/******************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation.
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * https://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *****************************************************************************/
+
+import * as semver from 'semver';
+import { Extension, Registry, VersionReference } from './registry';
+import { formatCount, formatNumber, printRows } from './table';
+import { ShowOptions } from './show-options';
+import { addEnvOptions, matchExtensionId } from './util';
+
+/**
+ * How many versions the history table prints unless `--all-versions` is given. Matches what
+ * `vsce show` lists; the remainder is reported as a count rather than dropped silently.
+ */
+const VERSION_HISTORY_SIZE = 6;
+
+/**
+ * Tags starting with `__` are internal bookkeeping (e.g. `__web_extension`) rather than anything
+ * the publisher wrote, and the web UI hides them too.
+ */
+const INTERNAL_TAG_PREFIX = '__';
+
+/** One row of the version history table. */
+interface VersionSummary {
+    version: string;
+    targetPlatforms: string[];
+}
+
+/**
+ * Page size for the version-reference listing. Versions come back newest first, and each version
+ * contributes one entry per target platform, so a page has to be comfortably larger than the
+ * number of versions shown for the default table to be filled from a single request.
+ */
+const VERSION_PAGE_SIZE = 100;
+
+/**
+ * Prints an extension's metadata.
+ */
+export async function show(options: ShowOptions): Promise<void> {
+    addEnvOptions(options);
+    const { id, version } = splitVersion(options.extensionId);
+    const match = matchExtensionId(id);
+    if (!match) {
+        throw new Error('The extension identifier must have the form `namespace.extension` or `namespace/extension`.');
+    }
+
+    const [, namespace, name] = match;
+    const registry = new Registry(options);
+    const extension = await registry.getMetadata(namespace, name, options.target, version);
+    if (extension.error) {
+        throw new Error(extension.error);
+    }
+
+    if (options.json) {
+        console.log(JSON.stringify(extension, null, 4));
+        return;
+    }
+
+    const allVersions = options.allVersions === true;
+    const versions = await getVersions(registry, namespace, name, options.target, allVersions);
+    printSummary(extension, versions, allVersions);
+}
+
+/**
+ * Splits a trailing `@<version>` off the identifier, the way `vsce show` accepts it. Only the last
+ * `@` is considered, so it stays out of the way of the identifier itself.
+ *
+ * An `@` with nothing after it is rejected rather than read as "no version given". It usually means a
+ * shell variable that did not expand - `ovsx show redhat.java@$VERSION` with `VERSION` unset - and
+ * reporting the latest version for that would answer a question the caller did not ask.
+ */
+function splitVersion(extensionId: string): { id: string; version?: string } {
+    const at = extensionId.lastIndexOf('@');
+    if (at <= 0) {
+        return { id: extensionId };
+    }
+    const version = extensionId.substring(at + 1);
+    if (version.length === 0) {
+        throw new Error('A version must follow `@`, as in `namespace.extension@1.2.3`.');
+    }
+    return { id: extensionId.substring(0, at), version };
+}
+
+/**
+ * Collects the version history, collapsing the one-entry-per-target-platform rows the registry
+ * returns into a single row per version. Fetches one page unless every version is wanted, in which
+ * case it pages to the end - `totalSize` counts version/target-platform pairs, not versions, so
+ * paging has to run on what has actually been returned rather than on a version count.
+ *
+ * Best-effort: a registry that doesn't serve this endpoint still gets everything else, just
+ * without the history table.
+ */
+async function getVersions(
+    registry: Registry,
+    namespace: string,
+    name: string,
+    target: string | undefined,
+    allVersions: boolean
+): Promise<VersionSummary[]> {
+    const references: VersionReference[] = [];
+    let offset = 0;
+    try {
+        for (;;) {
+            const page = await registry.getVersionReferences(namespace, name, target, VERSION_PAGE_SIZE, offset);
+            if (page.error) {
+                return [];
+            }
+            const versions = page.versions ?? [];
+            references.push(...versions);
+            offset += versions.length;
+            if (!allVersions || versions.length === 0 || offset >= page.totalSize) {
+                break;
+            }
+        }
+    } catch {
+        return [];
+    }
+
+    const byVersion = new Map<string, VersionSummary>();
+    for (const reference of references) {
+        let summary = byVersion.get(reference.version);
+        if (!summary) {
+            summary = { version: reference.version, targetPlatforms: [] };
+            byVersion.set(reference.version, summary);
+        }
+        if (reference.targetPlatform && !summary.targetPlatforms.includes(reference.targetPlatform)) {
+            summary.targetPlatforms.push(reference.targetPlatform);
+        }
+    }
+
+    return [...byVersion.values()].sort(byNewestFirst);
+}
+
+/**
+ * Newest version first. Anything that isn't valid semver (the registry accepts such versions from
+ * a mirror) sorts after everything that is, rather than being compared incomparably.
+ *
+ * Deliberately `valid` and not `coerce`: coerce drops prerelease identifiers, so `1.2.0-alpha.1`
+ * and `1.2.0` would compare equal and order unstably, and it accepts inputs semver itself rejects
+ * (`v1.2` becomes `1.2.0`), which would defeat the fallback below.
+ */
+function byNewestFirst(a: VersionSummary, b: VersionSummary): number {
+    const left = semver.valid(a.version);
+    const right = semver.valid(b.version);
+    if (left && right) {
+        return semver.rcompare(left, right);
+    }
+    if (left) {
+        return -1;
+    }
+    if (right) {
+        return 1;
+    }
+    return b.version.localeCompare(a.version);
+}
+
+function printSummary(extension: Extension, versions: VersionSummary[], allVersions: boolean): void {
+    const publisher = extension.namespaceDisplayName || extension.namespace;
+    console.log(extension.displayName || extension.name);
+    console.log(`  ${publisher}${extension.verified ? ' (verified publisher)' : ''}`);
+    console.log(`  ${formatCount(extension.downloadCount, 'download')}  ${formatRating(extension)}`);
+    if (extension.description) {
+        console.log();
+        console.log(`  ${extension.description}`);
+    }
+
+    printNotices(extension);
+    printVersionHistory(versions, allVersions);
+    printList('Categories', extension.categories);
+    printList('Tags', extension.tags?.filter(tag => !tag.startsWith(INTERNAL_TAG_PREFIX)));
+    printTable('More Info', moreInfo(extension));
+    printTable('Registry', registryInfo(extension));
+    printTable('Statistics', statistics(extension));
+}
+
+/**
+ * Anything a consumer of this extension should see before its metadata: deprecation first, since
+ * it changes whether they should install it at all.
+ */
+function printNotices(extension: Extension): void {
+    const notices: string[] = [];
+    if (extension.deprecated) {
+        const replacement = extension.replacement;
+        notices.push(
+            replacement
+                ? `Deprecated - superseded by ${replacement.displayName ?? replacement.url}`
+                : 'Deprecated'
+        );
+    }
+    if (extension.downloadable === false) {
+        notices.push('Not downloadable from this registry');
+    }
+    if (extension.preview) {
+        notices.push('Preview');
+    }
+    if (extension.namespaceOwnershipConflict) {
+        notices.push('The namespace ownership of this extension is disputed');
+    }
+
+    if (notices.length > 0) {
+        console.log();
+        for (const notice of notices) {
+            console.log(`  ! ${notice}`);
+        }
+    }
+}
+
+function printVersionHistory(versions: VersionSummary[], allVersions: boolean): void {
+    if (versions.length === 0) {
+        return;
+    }
+
+    const shown = allVersions ? versions : versions.slice(0, VERSION_HISTORY_SIZE);
+    const rows = shown.map(v => [v.version, v.targetPlatforms.join(', ')]);
+
+    console.log();
+    console.log('Version History:');
+    printRows([['Version', 'Target Platforms'], ...rows]);
+    const remaining = versions.length - shown.length;
+    if (remaining > 0) {
+        console.log(`  ... and ${remaining} more (pass --all-versions to list them)`);
+    }
+}
+
+function moreInfo(extension: Extension): string[][] {
+    const rows: string[][] = [
+        ['Unique Identifier', `${extension.namespace}.${extension.name}`],
+        ['Version', extension.version]
+    ];
+    if (extension.versionAlias?.length > 0) {
+        rows.push(['Version Aliases', extension.versionAlias.join(', ')]);
+    }
+    if (extension.targetPlatform) {
+        rows.push(['Target Platform', extension.targetPlatform]);
+    }
+    rows.push(['Last Updated', extension.timestamp]);
+    rows.push(['Published By', extension.publishedBy?.loginName ?? '']);
+    addIfPresent(rows, 'License', extension.license);
+    addIfPresent(rows, 'Homepage', extension.homepage);
+    addIfPresent(rows, 'Repository', extension.repository);
+    addIfPresent(rows, 'Bugs', extension.bugs);
+    addIfPresent(rows, 'Q&A', extension.qna);
+    addIfPresent(rows, 'Sponsor', extension.sponsorLink);
+    if (extension.engines) {
+        rows.push(['Engines', Object.entries(extension.engines).map(([e, v]) => `${e} ${v}`).join(', ')]);
+    }
+    return rows;
+}
+
+/**
+ * The parts an Open VSX compatible registry reports that the Marketplace has no equivalent for.
+ * Kept in its own block rather than mixed into "More Info" so it's obvious what is registry
+ * specific, and omitted entirely when none of it applies.
+ */
+function registryInfo(extension: Extension): string[][] {
+    const rows: string[][] = [];
+    if (extension.verified !== undefined) {
+        rows.push(['Verified Publisher', yesNo(extension.verified)]);
+    }
+    if (extension.publishedWithTrustedPublishing) {
+        rows.push(['Trusted Publishing', 'yes']);
+    }
+    if (extension.preRelease !== undefined) {
+        rows.push(['Pre-Release', yesNo(extension.preRelease)]);
+    }
+    addIfPresent(rows, 'Extension Kind', extension.extensionKind?.join(', '));
+    addIfPresent(rows, 'Localized', extension.localizedLanguages?.join(', '));
+    addIfPresent(rows, 'Dependencies', extension.dependencies?.map(referenceId).join(', '));
+    addIfPresent(rows, 'Bundled Extensions', extension.bundledExtensions?.map(referenceId).join(', '));
+    return rows;
+}
+
+function statistics(extension: Extension): string[][] {
+    const rows: string[][] = [['Downloads', formatNumber(extension.downloadCount)]];
+    if (extension.averageRating !== undefined) {
+        rows.push(['Average Rating', `${extension.averageRating.toFixed(1)}/5`]);
+    }
+    rows.push(['Reviews', formatNumber(Number(extension.reviewCount ?? 0))]);
+    return rows;
+}
+
+function referenceId(reference: { namespace: string; extension: string }): string {
+    return `${reference.namespace}.${reference.extension}`;
+}
+
+function addIfPresent(rows: string[][], label: string, value?: string): void {
+    if (value) {
+        rows.push([label, value]);
+    }
+}
+
+function printList(title: string, values?: string[]): void {
+    if (!values || values.length === 0) {
+        return;
+    }
+    console.log();
+    console.log(`${title}:`);
+    console.log(`  ${values.join(', ')}`);
+}
+
+function printTable(title: string, rows: string[][]): void {
+    if (rows.length === 0) {
+        return;
+    }
+    console.log();
+    console.log(`${title}:`);
+    printRows(rows);
+}
+
+function formatRating(extension: Extension): string {
+    if (extension.averageRating === undefined) {
+        return 'no ratings';
+    }
+    return `${extension.averageRating.toFixed(1)}/5 from ${formatCount(extension.reviewCount, 'review')}`;
+}
+
+function yesNo(value: boolean): string {
+    return value ? 'yes' : 'no';
+}

package/src/table.ts

@@ -0,0 +1,53 @@
+/******************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation.
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * https://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *****************************************************************************/
+
+/**
+ * Prints rows as an aligned table, indented by two spaces. Every column but the last is padded,
+ * so a trailing empty cell doesn't leave ragged whitespace behind.
+ */
+export function printRows(rows: string[][]): void {
+    const widths: number[] = [];
+    for (const row of rows) {
+        row.forEach((cell, i) => widths[i] = Math.max(widths[i] ?? 0, cell.length));
+    }
+    for (const row of rows) {
+        const line = row
+            .map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i])))
+            .join('  ')
+            .trimEnd();
+        console.log(`  ${line}`);
+    }
+}
+
+/** Formats a count with thousands separators, and the noun pluralised to match. */
+export function formatCount(count: number | undefined, noun: string): string {
+    const value = count ?? 0;
+    return `${formatNumber(value)} ${value === 1 ? noun : noun + 's'}`;
+}
+
+export function formatNumber(value: number | undefined): string {
+    return (value ?? 0).toLocaleString('en-US');
+}
+
+/**
+ * Shortens `text` to at most `max` characters, marking that it was cut. A `max` of zero or less
+ * leaves no room for the marker either, so it yields nothing rather than an ellipsis wider than the
+ * budget it was given.
+ */
+export function truncate(text: string, max: number): string {
+    if (max <= 0) {
+        return '';
+    }
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= max ? collapsed : `${collapsed.substring(0, max - 1)}…`;
+}

package/src/trusted-publishing-options.ts

@@ -0,0 +1,30 @@
+/******************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation.
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * https://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *****************************************************************************/
+
+export interface TrustedPublishingOptions {
+    /**
+     * Obtain a short-lived publishing token by exchanging an OIDC ID token. If unset, trusted
+     * publishing is used whenever an ID token source is detected and no access token is available.
+     */
+    trustedPublishing?: boolean;
+    /**
+     * The OIDC ID token to exchange. Only needed for CI systems that expose the token directly,
+     * such as GitLab CI; on GitHub Actions the token is requested from the workflow runtime.
+     */
+    idToken?: string;
+    /**
+     * The audience to request for the OIDC ID token. Defaults to the registry URL and must match
+     * the audience the registry expects.
+     */
+    oidcAudience?: string;
+}

package/src/trusted-publishing.ts

@@ -0,0 +1,148 @@
+/******************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation.
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * https://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *****************************************************************************/
+
+import { getIdToken, hasIdTokenSource } from './oidc';
+import { AccessToken, Registry } from './registry';
+import { StatusError } from './util';
+import { TrustedPublishingOptions } from './trusted-publishing-options';
+
+const tokens = new Map<string, Promise<string>>();
+
+// The value each cached exchange resolved to, so a token a publish was refused with can be told from one
+// another publish has already replaced. Cleared while an exchange is in flight.
+const issued = new Map<string, string>();
+
+/**
+ * Whether the given options ask for trusted publishing. If the user did not decide explicitly,
+ * it is used whenever the surrounding CI system can provide an OIDC ID token.
+ */
+export function useTrustedPublishing(options: TrustedPublishingOptions): boolean {
+    return options.trustedPublishing ?? hasIdTokenSource(options);
+}
+
+/**
+ * Exchanges an OIDC ID token for a short-lived access token that can publish the given extension.
+ * The token is not stored, it is only valid for a few minutes.
+ */
+export function getTrustedPublishingToken(
+    registry: Registry,
+    namespace: string,
+    extension: string,
+    options: TrustedPublishingOptions
+): Promise<string> {
+    // publishing fans out over targets and package paths, but one token is enough per extension
+    const key = `${namespace}.${extension}`;
+    return tokens.get(key) ?? exchange(key, registry, namespace, extension, options);
+}
+
+/**
+ * Exchanges the ID token again after the registry refused the one this extension was publishing with.
+ * The issued token is short-lived and shared by every target platform of a release, so a slow fan-out
+ * can outlive it and be refused partway through.
+ *
+ * `stale` is the token that was refused. If the cache no longer holds it, another target has already
+ * replaced it and that exchange is awaited instead, so one expiry costs one exchange however many
+ * targets hit it at once.
+ */
+export function refreshTrustedPublishingToken(
+    registry: Registry,
+    namespace: string,
+    extension: string,
+    options: TrustedPublishingOptions,
+    stale: string
+): Promise<string> {
+    const key = `${namespace}.${extension}`;
+    const current = tokens.get(key);
+    if (current && issued.get(key) !== stale) {
+        return current;
+    }
+
+    return exchange(key, registry, namespace, extension, options);
+}
+
+function exchange(
+    key: string,
+    registry: Registry,
+    namespace: string,
+    extension: string,
+    options: TrustedPublishingOptions
+): Promise<string> {
+    // Dropped up front, so a refresh that is still in flight does not look like the stale token to the
+    // next caller and start a second exchange of its own.
+    issued.delete(key);
+    const token = requestToken(registry, namespace, extension, options).then(value => {
+        issued.set(key, value);
+        return value;
+    });
+    tokens.set(key, token);
+    return token;
+}
+
+// The registry answers 503 when it could not reach the identity provider to check the token, as opposed
+// to checking it and refusing. That is worth another go: publishing runs unattended on CI, and a blip
+// reaching GitHub or GitLab should not fail a release build. A refusal is never retried.
+const RETRYABLE_STATUS = [502, 503, 504];
+const RETRY_DELAYS_MS = [1000, 4000];
+
+async function requestToken(
+    registry: Registry,
+    namespace: string,
+    extension: string,
+    options: TrustedPublishingOptions
+): Promise<string> {
+    const audience = options.oidcAudience ?? registry.url;
+    const idToken = await getIdToken(audience, options);
+
+    let result: AccessToken;
+    try {
+        result = await exchangeWithRetry(registry, namespace, extension, idToken);
+    } catch (err) {
+        throw new Error(`${err.message}\n${registrationHint(registry, namespace, extension)}`);
+    }
+    if (result.error) {
+        throw new Error(`${result.error}\n${registrationHint(registry, namespace, extension)}`);
+    }
+    if (!result.value) {
+        throw new Error('The registry did not return a publishing token.');
+    }
+
+    const expires = result.expiresTimestamp ? `, expires at ${result.expiresTimestamp}` : '';
+    console.log(`\ud83d\udd10  Trusted publishing token issued for ${namespace}.${extension}${expires}`);
+    return result.value;
+}
+
+async function exchangeWithRetry(
+    registry: Registry,
+    namespace: string,
+    extension: string,
+    idToken: string
+): Promise<AccessToken> {
+    for (let attempt = 0; ; attempt++) {
+        try {
+            return await registry.requestTrustedPublishingToken(namespace, extension, idToken);
+        } catch (err) {
+            const status = (err as StatusError)?.status;
+            if (attempt >= RETRY_DELAYS_MS.length || status === undefined || !RETRYABLE_STATUS.includes(status)) {
+                throw err;
+            }
+            const delay = RETRY_DELAYS_MS[attempt];
+            console.log(`The registry could not verify the token (${status}), retrying in ${delay / 1000}s`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+}
+
+function registrationHint(registry: Registry, namespace: string, extension: string): string {
+    return `Check the trusted publishers registered for '${namespace}.${extension}' at `
+        + `${registry.url}/user-settings/trusted-publishers.`;
+}

package/src/unpublish-options.ts

@@ -0,0 +1,35 @@
+/******************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation.
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * https://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *****************************************************************************/
+
+import { RegistryOptions } from './registry-options';
+
+export interface UnpublishOptions extends RegistryOptions {
+    /**
+     * Identifier in the form `namespace.extension` or `namespace/extension`.
+     * Read from the `package.json` in the current directory if omitted.
+     */
+    extensionId?: string;
+    /**
+     * Versions to delete. All versions are deleted if omitted.
+     */
+    versions?: string[];
+    /**
+     * Target platforms to delete. All target platforms of the selected versions
+     * are deleted if omitted. Can only be used together with `versions`.
+     */
+    targets?: string[];
+    /**
+     * Delete without asking for confirmation.
+     */
+    force?: boolean;
+}