[S5b] Remove obsolete package identities and document source-only consumption #146

Goal and plan placement

The former npm identity @vscode/common-python-lsp and Python distribution identity vscode-common-python-lsp must no longer be used as supported package identities or consumption APIs.

Add S5b: source-only identity and consumption cleanup after typed definitions and before the activation facade:

S5 typed definitions -> S5b source-only identities -> S6 activation facade -> S7 narrow hooks

The deferred source-build/provenance work remains independent. This is not a request to resume it, publish replacement packages, or move directories.

Inspection baseline: 459caa508d57919d904d72d584e89ad79d32add0. Start from current main. The typed-definition work is separately in progress: coordinate its new documentation/examples when integrating, without modifying that worktree.

What was found

Inventory the current tree, including lock metadata and examples, rather than only replacing README text.

Important distinction

The repository is still named microsoft/vscode-common-python-lsp. Its GitHub URLs, checkout/submodule paths, project references and historical release links are legitimate and must not be mechanically renamed.

Likewise, the Python import package vscode_common_python_lsp is different from the hyphenated distribution identity. Preserve that import namespace in this increment. Do not turn this into a module/repository rename or rewrite historical releases.

Acceptance means no active use as the obsolete npm/Python package identities, not a zero-result search for the repository slug.

Bounded implementation

1. Supported consumption is pinned source

Document a complete source-only path:

• Pin the repository checkout/submodule.
• Install/build the TypeScript side from that checkout using its local tool manifest.
• Import its supported built public entry point by an explicit source-relative path, rather than the former registry module specifier.
• Install/bundle the Python side from the same local checkout, preserving its import module and the consumer's existing runtime dependency policy.

For example, after building the checkout under external/, an extension's src/extension.ts can import from:

import { createToolContext } from '../external/vscode-common-python-lsp/typescript/dist';

Validate the example and explain required build order. Keep any source-build/install commands explicitly local. Do not replace the old names with a new bare registry install command or advertise a newly published product.

2. Local build metadata is implementation detail

npm and setuptools may still need manifests/build metadata. Keep the ability to run existing tests, compile declarations, install from a filesystem path and produce local artifacts.

Remove obsolete identities from that metadata. Omit an unnecessary identity where the tool supports it; where a name is required, use a clearly internal/source-only local identity (for example vscode-python-tool-runtime-internal), not a new registry-facing API. Preserve npm private: true; make Python's source-only intent clear.

Use the smallest validated approach. Do not remove required PEP 621 metadata and break local installation merely to remove a string. Do not add a compatibility alias for either prohibited identity.

If a manifest changes, update lock metadata with existing package-manager tooling. Do not upgrade dependencies or reinstate version synchronization, weekly bumps or publishing. Existing informational local version values need not change.

3. Remove runtime reliance on the former distribution

The default ToolServer constructor must not look up the former Python distribution, even if an obsolete editable/registry installation happens to exist in the environment.

If version lookup remains necessary, use only the selected source's valid internal build metadata. Preserve the current server-name construction, version formatting and 0.0.0-dev fallback, and leave an explicitly supplied LanguageServer unchanged. Do not add source/version fields to settings or redesign bootstrap.

Make the metadata identity change explicit and test it; never silently fall back to the old distribution identity.

4. Align active docs, examples and tests

Update current source-consumption instructions, package-branded headings/prose, applicable imports/identifiers and directly dependent tests. Keep public symbols, settings, interpreter behavior, formatters and lifecycle semantics unchanged.

The pending typed-definition documentation may introduce new imports using the former npm name. Record the integration requirement and reconcile those examples once available; do not copy, reset or edit another worktree's uncommitted changes.

Compatibility and adoption limits

• Preserve the TypeScript public entry point/API and Python module namespace.
• Preserve local build/install/test capability and runtime dependency closure.
• No settings payload/default, tool-policy or lifecycle changes.
• Preserve default-server version formatting/fallback; only its source of package identity is intentionally changed.
• Existing external consumers may still use the old npm alias/locks. A source-integration cutover may require reviewed consumer dependency/import/lock updates. Describe the migration instead of pretending metadata renaming proves all consumers compatible or downloading an old registry artifact to make a smoke test pass.
• The deferred provenance PR may have artifact/metadata assumptions to reconcile when resumed; it is not this PR's implementation base.

Validation and acceptance

• Search/classify both old names across active manifests, lockfiles, runtime/tests and documentation. No supported package-identity use remains; legitimate repository/path/history references are preserved.
• The documented TS source-entry import type-checks and its local build resolves without the former npm module identity.
• A clean local Python path install/build works, imports the expected checkout/artifact, and default-server tests prove there is no lookup/fallback to the former distribution identity.
• Missing internal distribution metadata retains v0.0.0-dev; provided server instances remain unchanged.
• Existing TS tests/build/lint and Python tests/lint/format checks pass. Use .nvmrc; reference Node is 24.17.0, current main baseline is 160 TS tests.
• The dependency graph/versions are unchanged; any lock edits are limited to directly required project metadata.
• No changes to fixtures, settings wire shape, Python import paths, physical layout, source-build framework or unrelated code.
• Consumer migration limits and pending typed-definition-doc integration are reported accurately.

Suggested checks include npm --prefix .\typescript test, npm --prefix .\typescript run build, npm --prefix .\typescript run lint, the existing Python test/lint commands and git diff --check, plus focused installation/import/constructor smoke checks.

Bind unit-test imports to the correct worktree: a global editable Python installation may point at another checkout. Conversely, an installation smoke must really import its staged artifact, not pass because PYTHONPATH redirects it to source.

Non-goals

No new registry distribution, complete elimination of local packaging/build tooling, repo/module rename, directory consolidation, dependency modernization, consumer repository edits, activation facade, typed-definition redesign or broad formatting.