ovsx 1.1.0 → 1.2.0

package/src/registry.ts

@@ -10,19 +10,24 @@
 
 import * as http from 'http';
 import * as fs from 'fs';
+import { pipeline, Writable } from 'stream';
 import * as followRedirects from 'follow-redirects';
 import { RegistryOptions } from './registry-options';
-import { rejectError, statusError } from './util';
+import { DEFAULT_TIMEOUT, redactUrl, rejectError, statusError, withStatus } from './util';
 
 export const DEFAULT_URL = 'https://open-vsx.org';
 export const DEFAULT_NAMESPACE_SIZE = 1024;
 export const DEFAULT_PUBLISH_SIZE = 512 * 1024 * 1024;
+export { DEFAULT_TIMEOUT };
+export const DEFAULT_TOKEN_REQUEST_SIZE = 8 * 1024;
+export const DEFAULT_DELETE_SIZE = 64 * 1024;
 
 export class Registry {
 
     readonly url: string;
     readonly maxNamespaceSize: number;
     readonly maxPublishSize: number;
+    readonly timeout: number;
     readonly username?: string;
     readonly password?: string;
 
@@ -36,6 +41,7 @@ export class Registry {
 
         this.maxNamespaceSize = options.maxNamespaceSize ?? DEFAULT_NAMESPACE_SIZE;
         this.maxPublishSize = options.maxPublishSize ?? DEFAULT_PUBLISH_SIZE;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
         this.username = options.username;
         this.password = options.password;
     }
@@ -65,6 +71,14 @@ export class Registry {
         }
     }
 
+    getRegistryVersion(): Promise<RegistryVersion> {
+        try {
+            return this.getJson(this.getUrl(['api', 'version']));
+        } catch (err) {
+            return rejectError(err);
+        }
+    }
+
     publish(file: string, pat: string): Promise<Extension> {
         try {
             const url = this.getUrl(['api', '-', 'publish'], { token: pat });
@@ -76,41 +90,180 @@ export class Registry {
         }
     }
 
-    getMetadata(namespace: string, extension: string, target?: string): Promise<Extension> {
+    requestTrustedPublishingToken(namespace: string, extension: string, idToken: string): Promise<AccessToken> {
+        try {
+            const url = this.getUrl(['api', '-', 'trusted-publishing', 'token']);
+            const request = { namespace, extension, token: idToken };
+            return this.post(JSON.stringify(request), url, {
+                'Content-Type': 'application/json'
+            }, DEFAULT_TOKEN_REQUEST_SIZE);
+        } catch (err) {
+            return rejectError(err);
+        }
+    }
+
+    /**
+     * Deletes extension versions. Omitting `targetVersions` deletes the extension as a whole,
+     * i.e. all versions the personal access token's user is allowed to delete.
+     */
+    deleteExtension(
+        namespace: string,
+        extension: string,
+        targetVersions: TargetPlatformVersion[] | undefined,
+        pat: string
+    ): Promise<Response> {
+        try {
+            if (!targetVersions) {
+                const url = this.getUrl(['api', namespace, extension, 'delete'], { token: pat, allVersions: 'true' });
+                return this.post('', url, undefined, DEFAULT_DELETE_SIZE);
+            }
+
+            const url = this.getUrl(['api', namespace, extension, 'delete'], { token: pat });
+            return this.post(JSON.stringify(targetVersions), url, {
+                'Content-Type': 'application/json'
+            }, DEFAULT_DELETE_SIZE);
+        } catch (err) {
+            return rejectError(err);
+        }
+    }
+
+    getMetadata(namespace: string, extension: string, target?: string, version?: string): Promise<Extension> {
         try {
             const segments = ['api', namespace, extension];
             if (target) {
                 segments.push(target);
             }
+            if (version) {
+                segments.push(version);
+            }
             return this.getJson(this.getUrl(segments));
         } catch (err) {
             return rejectError(err);
         }
     }
 
+    /**
+     * Returns a page of an extension's published versions, newest first, one entry per version and
+     * target platform. `allVersions` on the metadata response carries version numbers and links
+     * only, so this is what makes the target platforms of each version available.
+     */
+    getVersionReferences(
+        namespace: string,
+        extension: string,
+        target: string | undefined,
+        size: number,
+        offset: number
+    ): Promise<VersionReferences> {
+        try {
+            const segments = ['api', namespace, extension];
+            if (target) {
+                segments.push(target);
+            }
+            segments.push('version-references');
+            return this.getJson(this.getUrl(segments, {
+                size: String(size),
+                offset: String(offset)
+            }));
+        } catch (err) {
+            return rejectError(err);
+        }
+    }
+
+    /**
+     * Full-text search across the registry. Returns the purpose-built summary shape rather than
+     * whole extension records, so a page of results stays small.
+     */
+    search(options: SearchQuery): Promise<SearchResult> {
+        try {
+            const query: Record<string, string> = {
+                size: String(options.size),
+                offset: String(options.offset)
+            };
+            if (options.query) {
+                query.query = options.query;
+            }
+            if (options.category) {
+                query.category = options.category;
+            }
+            if (options.targetPlatform) {
+                query.targetPlatform = options.targetPlatform;
+            }
+            if (options.sortBy) {
+                query.sortBy = options.sortBy;
+            }
+            if (options.sortOrder) {
+                query.sortOrder = options.sortOrder;
+            }
+            return this.getJson(this.getUrl(['api', '-', 'search'], query));
+        } catch (err) {
+            return rejectError(err);
+        }
+    }
+
+    /** Returns a namespace and the extensions published in it. */
+    getNamespace(namespace: string): Promise<Namespace> {
+        try {
+            return this.getJson(this.getUrl(['api', namespace]));
+        } catch (err) {
+            return rejectError(err);
+        }
+    }
+
     download(file: string, url: URL): Promise<void> {
         return new Promise((resolve, reject) => {
-            const stream = fs.createWriteStream(file);
+            // Written beside the target and renamed into place on success, so the caller's path holds
+            // either what it held before or the whole download, never part of one. Deferring the open
+            // until the status is known is not enough on its own: a connection dropped mid-body has
+            // already truncated the file by then, and `get` is handed a path the user chose.
+            const partial = `${file}.part`;
+            let stream: fs.WriteStream | undefined;
+
+            // Claimed synchronously, before the cleanup that has to happen before rejecting. A timeout
+            // mid-body drives both the request's error handler and pipeline's callback, and each used
+            // to wait on its own fs.rm - so whichever landed first decided what the caller was told,
+            // and the partial was removed twice.
+            let failed = false;
+            const fail = (err: Error) => {
+                if (failed) {
+                    return;
+                }
+                failed = true;
+                stream?.destroy();
+                fs.rm(partial, { force: true }, () => reject(err));
+            };
+
             const requestOptions = this.getRequestOptions();
             const request = this.getProtocol(url)
                                 .request(url, requestOptions, response => {
-                response.on('end', () => {
-                    if (response.statusCode !== undefined && (response.statusCode < 200 || response.statusCode > 299)) {
-                        reject(statusError(response));
+                if (response.statusCode !== undefined && (response.statusCode < 200 || response.statusCode > 299)) {
+                    response.resume();
+                    reject(statusError(response));
+                    return;
+                }
+
+                stream = fs.createWriteStream(partial);
+
+                // pipeline rather than response.pipe: pipe installs its own error handler on the
+                // source, so a connection dropped mid-body is swallowed - the write stream is never
+                // ended, nothing settles, and the caller waits for a file that will never arrive.
+                // pipeline propagates that error and tears both ends down. Its callback also waits
+                // for the file to close, which matters in its own right: a write stream opens and
+                // flushes asynchronously, so the last byte having arrived says nothing about the
+                // file being on disk.
+                pipeline(response, stream, (err: NodeJS.ErrnoException | null) => {
+                    if (err) {
+                        fail(err);
+                    } else if (!response.complete) {
+                        // A body cut short still ends the stream cleanly; `complete` is what tells
+                        // that apart from having received all of it.
+                        fail(new Error(`The connection closed before the whole of ${redactUrl(url)} was received.`));
                     } else {
-                        resolve();
+                        fs.rename(partial, file, renameErr => renameErr ? fail(renameErr) : resolve());
                     }
                 });
-                response.pipe(stream);
-            });
-            stream.on('error', (err: Error) => {
-                request.abort();
-                reject(err);
-            });
-            request.on('error', (err: Error) => {
-                stream.close();
-                reject(err);
             });
+            request.on('error', (err: Error) => fail(err));
+            this.failOnTimeout(request, url, fail);
             request.end();
         });
     }
@@ -121,6 +274,7 @@ export class Registry {
             const request = this.getProtocol(url)
                                 .request(url, requestOptions, this.getJsonResponse<T>(resolve, reject));
             request.on('error', reject);
+            this.failOnTimeout(request, url, reject);
             request.end();
         });
     }
@@ -131,6 +285,7 @@ export class Registry {
             const request = this.getProtocol(url)
                                 .request(url, requestOptions, this.getJsonResponse<T>(resolve, reject));
             request.on('error', reject);
+            this.failOnTimeout(request, url, reject);
             request.write(content);
             request.end();
         });
@@ -143,13 +298,14 @@ export class Registry {
             const request = this.getProtocol(url)
                                 .request(url, requestOptions, this.getJsonResponse<T>(resolve, reject));
             stream.on('error', (err: Error) => {
-                request.abort();
+                request.destroy();
                 reject(err);
             });
             request.on('error', (err: Error) => {
                 stream.close();
                 reject(err);
             });
+            this.failOnTimeout(request, url, reject);
             stream.on('open', () => stream.pipe(request));
         });
     }
@@ -169,6 +325,28 @@ export class Registry {
         return url.protocol === 'https:' ? followRedirects.https : followRedirects.http;
     }
 
+    /**
+     * Node's `timeout` option only raises an event - the request stays open, which is why a server
+     * that accepts a connection and then says nothing used to hold a command open indefinitely.
+     * Destroying the request with an error routes through the error handling each caller already
+     * has, so a stalled request rejects the way any other failure does. With a timeout of zero the
+     * event never fires and this does nothing.
+     */
+    // Typed on Writable because both http.ClientRequest and follow-redirects' wrapper are ones, and
+    // all this needs is the timeout event and destroy.
+    private failOnTimeout(request: Writable, url: URL, fail: (err: Error) => void): void {
+        request.on('timeout', () => {
+            // Reported before the request is torn down, rather than by destroying it with the error.
+            // Destroying raises errors of its own - ECONNRESET on the response, a premature close
+            // from pipeline - and node guarantees no order between those and the request's own. In
+            // practice the request's arrives first, so this is belt and braces rather than the thing
+            // that stops the wrong error being reported; that is the caller claiming the failure
+            // before it does any asynchronous cleanup.
+            fail(new Error(`No response from ${redactUrl(url)} for ${this.timeout} ms.`));
+            request.destroy();
+        });
+    }
+
     private getRequestOptions(method?: string, headers?: http.OutgoingHttpHeaders, maxBodyLength?: number): http.RequestOptions {
         if (this.username && this.password) {
             headers ??= {};
@@ -178,7 +356,8 @@ export class Registry {
         return {
             method,
             headers,
-            maxBodyLength
+            maxBodyLength,
+            timeout: this.timeout
         } as http.RequestOptions;
     }
 
@@ -186,6 +365,11 @@ export class Registry {
         return response => {
             response.setEncoding('utf-8');
             let json = '';
+            // A connection lost after the headers have arrived ends the response without 'end' ever
+            // firing, so without this the promise is never settled and the command waits on a body
+            // that is not coming. The configured timeout would eventually rescue it, but rejecting
+            // here reports what actually happened instead of thirty seconds of silence.
+            response.on('error', reject);
             response.on('data', chunk => json += chunk);
             response.on('end', () => {
                 if (response.statusCode !== undefined && (response.statusCode < 200 || response.statusCode > 299)) {
@@ -194,7 +378,8 @@ export class Registry {
                             const parsed = JSON.parse(json) as ErrorResponse;
                             const message = parsed.message || parsed.error;
                             if (message) {
-                                reject(new Error(message));
+                                // keep the status: the message alone cannot say whether retrying is worth it
+                                reject(withStatus(new Error(message), response.statusCode));
                                 return;
                             }
                         } catch (err) {
@@ -245,8 +430,18 @@ export interface Extension extends Response {
     versionAlias: string[];
     timestamp: string;
     preview?: boolean;
+    preRelease?: boolean;
     displayName?: string;
+    namespaceDisplayName?: string;
     description?: string;
+    deprecated?: boolean;
+    replacement?: ExtensionReplacement;
+    downloadable?: boolean;
+    publishedWithTrustedPublishing?: boolean;
+    namespaceOwnershipConflict?: boolean;
+    extensionKind?: string[];
+    localizedLanguages?: string[];
+    sponsorLink?: string;
 
     // key: engine, value: version constraint
     engines?: { [engine: string]: string };
@@ -265,6 +460,26 @@ export interface Extension extends Response {
     bundledExtensions?: ExtensionReference[];
 }
 
+export interface RegistryVersion extends Response {
+    version: string;
+    maxExtensionSize: number;
+    trustedPublishingAudience?: string;
+}
+
+export interface AccessToken extends Response {
+    id: number;
+    value?: string;
+    description: string;
+    createdTimestamp: string;
+    accessedTimestamp?: string;
+    expiresTimestamp?: string;
+}
+
+export interface TargetPlatformVersion {
+    version: string;
+    targetPlatform?: string;
+}
+
 export interface UserData {
     loginName: string;
     fullName?: string;
@@ -278,6 +493,64 @@ export interface Badge {
     description: string;
 }
 
+export interface ExtensionReplacement {
+    url: string;
+    displayName?: string;
+}
+
+export interface VersionReference {
+    url: string;
+    files: { [type: string]: string };
+    version: string;
+    targetPlatform?: string;
+    engines?: { [engine: string]: string };
+}
+
+export interface VersionReferences extends Response {
+    offset: number;
+    totalSize: number;
+    versions?: VersionReference[];
+}
+
+export interface SearchQuery {
+    query?: string;
+    category?: string;
+    targetPlatform?: string;
+    sortBy?: string;
+    sortOrder?: string;
+    size: number;
+    offset: number;
+}
+
+export interface SearchEntry {
+    url: string;
+    files: { [type: string]: string };
+    name: string;
+    namespace: string;
+    version: string;
+    timestamp: string;
+    verified?: boolean;
+    averageRating?: number;
+    reviewCount?: number;
+    downloadCount: number;
+    displayName?: string;
+    description?: string;
+    deprecated?: boolean;
+}
+
+export interface SearchResult extends Response {
+    offset: number;
+    totalSize: number;
+    extensions?: SearchEntry[];
+}
+
+export interface Namespace extends Response {
+    name: string;
+    verified?: boolean;
+    // key: extension name, value: url
+    extensions?: { [name: string]: string };
+}
+
 export interface ExtensionReference {
     url: string;
     namespace: string;

package/src/search-options.ts

@@ -0,0 +1,49 @@
+/******************************************************************************
+ * 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 SearchOptions extends RegistryOptions {
+    /**
+     * Text to search for. Omit to browse, which is what makes `--category` useful on its own.
+     */
+    text?: string;
+    /**
+     * Restrict results to a category, e.g. `Programming Languages`.
+     */
+    category?: string;
+    /**
+     * Restrict results to extensions published for a target platform.
+     */
+    target?: string;
+    /**
+     * Sort key: `relevance`, `timestamp`, `rating` or `downloadCount`.
+     */
+    sortBy?: string;
+    /**
+     * `asc` or `desc`.
+     */
+    sortOrder?: string;
+    /**
+     * Number of results to return.
+     */
+    size?: number;
+    /**
+     * Index of the first result, for paging through a large result set.
+     */
+    offset?: number;
+    /**
+     * Print the raw results as JSON instead of a table.
+     */
+    json?: boolean;
+}

package/src/search.ts

@@ -0,0 +1,95 @@
+/******************************************************************************
+ * 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 { Registry, SearchEntry } from './registry';
+import { SearchOptions } from './search-options';
+import { formatNumber, printRows, truncate } from './table';
+import { addEnvOptions } from './util';
+
+/** Sort keys the registry accepts, for an up-front check with a better message than a 400. */
+export const SORT_KEYS = ['relevance', 'timestamp', 'rating', 'downloadCount'];
+
+export const SORT_ORDERS = ['asc', 'desc'];
+
+export const DEFAULT_SEARCH_SIZE = 20;
+
+/** Keeps a row from wrapping on a normal terminal, where the other columns take about half of it. */
+const DESCRIPTION_WIDTH = 60;
+
+/**
+ * Searches the registry for extensions.
+ */
+export async function search(options: SearchOptions): Promise<void> {
+    addEnvOptions(options);
+    if (options.sortBy && !SORT_KEYS.includes(options.sortBy)) {
+        throw new Error(`Sort key must be one of ${SORT_KEYS.join(', ')}.`);
+    }
+    if (options.sortOrder && !SORT_ORDERS.includes(options.sortOrder)) {
+        throw new Error(`Sort order must be one of ${SORT_ORDERS.join(', ')}.`);
+    }
+
+    const size = options.size ?? DEFAULT_SEARCH_SIZE;
+    const offset = options.offset ?? 0;
+    const registry = new Registry(options);
+    const result = await registry.search({
+        query: options.text,
+        category: options.category,
+        targetPlatform: options.target,
+        sortBy: options.sortBy,
+        sortOrder: options.sortOrder,
+        size,
+        offset
+    });
+    if (result.error) {
+        throw new Error(result.error);
+    }
+
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 4));
+        return;
+    }
+
+    printResults(result.extensions ?? [], result.totalSize, offset);
+}
+
+function printResults(entries: SearchEntry[], totalSize: number, offset: number): void {
+    if (entries.length === 0) {
+        console.log('No extensions found.');
+        return;
+    }
+
+    const rows = entries.map(entry => [
+        `${entry.namespace}.${entry.name}`,
+        entry.version,
+        formatNumber(entry.downloadCount),
+        entry.averageRating !== undefined ? entry.averageRating.toFixed(1) : '-',
+        describe(entry)
+    ]);
+    printRows([['Extension', 'Version', 'Downloads', 'Rating', 'Description'], ...rows]);
+
+    const last = offset + entries.length;
+    console.log();
+    console.log(`Showing ${offset + 1}-${last} of ${formatNumber(totalSize)}.`);
+    if (last < totalSize) {
+        console.log(`Pass --offset ${last} for the next page.`);
+    }
+}
+
+/**
+ * The description, prefixed with anything a reader should weigh before installing. Deprecation is
+ * the one flag worth spending row width on here; `show` reports the rest.
+ */
+function describe(entry: SearchEntry): string {
+    const description = truncate(entry.description ?? '', DESCRIPTION_WIDTH);
+    return entry.deprecated ? `(deprecated) ${description}`.trimEnd() : description;
+}

package/src/show-options.ts

@@ -0,0 +1,34 @@
+/******************************************************************************
+ * 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 ShowOptions extends RegistryOptions {
+    /**
+     * Identifier in the form `namespace.extension` or `namespace/extension`, optionally suffixed
+     * with `@<version>` - an exact version, or one of the `latest` / `pre-release` aliases.
+     */
+    extensionId: string;
+    /**
+     * Target platform to report on. Defaults to whichever the registry considers current.
+     */
+    target?: string;
+    /**
+     * Print the raw metadata as JSON instead of a readable summary.
+     */
+    json?: boolean;
+    /**
+     * List every published version rather than the most recent few.
+     */
+    allVersions?: boolean;
+}