Supplement Packages pane with metadata from Posit Package Manager (p3m)

[bricestacey]

See #12928

Adds package metadata from Posit Package Manager (P3M) to the Packages pane for Python environments (except conda). Packages that have a newer version available now show an up arrow indicator.

This adds support for fetching package metadata to supplement the packages pane. There are two methods:

1. Anytime the Packages service refreshes the packages list, it will refresh the metadata for any uncached packages.
2. There is an action that appears in its own group in the overflow menu: "Refresh Metadata". This doesn't wipe the cache, but it will force refetching the metadata for the provided packages.

Here is a demo with an added up arrow next to any outdated package.

Note that the code has support for fetching additional metadata, which I had started to implement. However, this simple up arrow icon was the most subtle and simple solution to prove out the basic data flows, when to automatically fetch metadata, and manually supporting the action.

Details

P3M Integration:

• New p3mSearch.ts module in positron-python extension calls POST https://p3m.dev/__api__/filter/packages
• Parses NDJSON response format
• Metadata includes: summary, license, latest version, available versions

UI Changes:

• Up arrow (↑) indicator appears next to package version when latestVersion !== version
• Hover tooltip shows "Update available: {version}"

Architecture:

• Metadata stored in separate cache from package list in PositronPackagesInstance
• Package list refresh preserves cached metadata; only fetches metadata for new packages
• Guard prevents concurrent metadata fetch calls
• New IPC protocol method $getPackageMetadata for extension host communication

Release Notes

New Features

• Add support for supplementing Packages pane with metadata from p3m.

Bug Fixes

• N/A

QA Notes

This only supports PIP and UV projects. So be sure you're not in a conda session.

@:packages-pane

[github-actions]

E2E Tests 🚀
This PR will run tests tagged with: @:critical @:packages-pane

^{readme  valid tags}

[cindyytong]

Newbie question - How is the Refresh Packages button different than the Refresh Metadata button?

[cindyytong]

Nonblocking comments

1. Can we test out an edge case where the name of the package overflows beyond the width of the package pane, will the text just get cut off ..., and then we still see version and up arrow. May want to check this with the min width of the packages pane before it collapses

2. Thoughts on using an existing icon tied with extension updates like the codeicon cloud-upload instead of the arrow which is a bit easy to miss

https://microsoft.github.io/vscode-codicons/dist/codicon.html

[softwarenerd]

Looking at refreshMetadata:

refreshMetadata's cache clear races with the background _fetchAndMergeMetadata from refreshPackages, causing the forced refresh to silently no-op (guard bails early) while the old in-flight fetch repopulates the cache with stale data keyed to the previous package list — fix by tracking the fetch as a CancelablePromise<void> and cancel-and-restart instead of guarding.

[softwarenerd]

Everything in P3MPackageMetadata should be readonly.

interface P3MPackageMetadata {
    readonly name: string;
    readonly version: string;
    readonly summary: string | null;
    readonly license: string | null;
    readonly licenses?: readonly string[];
    readonly license_types?: readonly string[];
    readonly package_date: string | null;
    readonly package_size: number | null;
    readonly downloads: number | null;
    readonly available_versions?: readonly string[];
    readonly dependencies?: {
        readonly imports?: ReadonlyArray<{ readonly name: string; readonly version?: string; readonly operator?: string }>;
        readonly suggests?: ReadonlyArray<{ readonly name: string; readonly version?: string; readonly operator?: string }>;
    };
}

[softwarenerd]

Everything in P3MFilterRequest should be readonly.

interface P3MFilterRequest {
    readonly names: readonly string[];
    readonly repo: string;
    readonly omit_downloads?: boolean;
    readonly omit_dependencies?: boolean;
    readonly omit_package_details?: boolean;
}

[softwarenerd]

I'm curious as to why this is a generic when it's used only once as:

const packages = parseNDJSON<P3MPackageMetadata>(text);

Do you expect there to be other uses in the future?

[bricestacey]

This was just what Claude did originally.

The generic implementation makes sense to me and could be reused if necessary. It's all compile time and has no bearing on its actual functionality.

IMO the non-generic version is kinda weird because it's so specific to a given type, when the functionality doesn't care about the type.

[softwarenerd]

const controller = new AbortController();
const cancelSubscription = token?.onCancellationRequested(() => controller.abort());

Seems simpler.

[softwarenerd]

No-op in TS modules (already strict).

[softwarenerd]

Race between refreshMetadata's cache clear and the background fetch.

refreshPackages fires off _fetchAndMergeMetadata as a background task with CancellationToken.None (intentional, so it isn't killed by the caller's token). If the user invokes refreshMetadata while that background fetch is in flight, the current code:

1. Clears _metadataCache.
2. Calls _fetchAndMergeMetadata, which hits the _metadataFetchInProgress guard and returns early.
3. Resolves, so the caller thinks the forced refresh succeeded.
4. The original background fetch eventually completes and repopulates the cache — with data keyed against the earlier package list, not the current one.

The "force refresh" contract isn't met, and the final cache state depends on whichever request was in flight.

Suggested fix: replace the _metadataFetchInProgress boolean with a tracked in-flight handle so callers can cancel it explicitly, and use cancel-and-restart instead of a guard.

private _metadataFetch?: CancelablePromise<void>;

• _fetchAndMergeMetadata wraps its body in createCancelablePromise, stores the handle on this._metadataFetch, and cancels any prior value at the top (so re-entrance supersedes rather than no-ops).
• Pass the internal token into packageManager.getPackageMetadata and re-check token.isCancellationRequested after the await, before writing to the cache — guarantees a cancelled fetch can't pollute the cache after a caller has cleared it.
• Propagate the external caller's token: externalToken.onCancellationRequested(() => fetch.cancel()), and dispose the subscription in a .finally.
• Swallow CancellationError (via isCancellationError); keep logging for genuine failures.
• In refreshMetadata, call this._metadataFetch?.cancel() before this._metadataCache.clear() — closes the race.
• Override dispose() to cancel any in-flight fetch so background work doesn't outlive the instance.

Net effect: the _metadataFetchInProgress flag goes away, and refreshMetadata reliably performs a full re-fetch regardless of what else is in flight.