fix: address API packaging review feedback; decouple API/extension versions

Co-authored-by: edvilme <5952839+edvilme@users.noreply.github.com>

Author: Copilot

CONTRIBUTING.md

@@ -96,7 +96,7 @@ The npm package under [`api/`](./api) is the public API facade other extensions
 - Edit the public API only in `src/api.ts` (the runtime facade: `PythonEnvironments.api()` helper and `EXTENSION_ID`), `src/types.ts` (public contracts: interfaces, types, enums), and `src/publicErrors.ts` (concrete public error classes and type guards). `api/src/*.ts` files are build artifacts — never edit or commit them.
 - `api/src/main.ts`, `api/src/types.ts`, and `api/src/publicErrors.ts` are produced by the publish pipeline ([`build/azure-pipeline.npm.yml`](./build/azure-pipeline.npm.yml)), which copies `src/api.ts` to `api/src/main.ts`, `src/types.ts` to `api/src/types.ts`, and `src/publicErrors.ts` to `api/src/publicErrors.ts` before compiling. The api package is therefore built in CI only; to build it locally, copy the files first (e.g. `cp src/api.ts api/src/main.ts && cp src/types.ts api/src/types.ts && cp src/publicErrors.ts api/src/publicErrors.ts`).
 - `src/api.ts`, `src/types.ts`, and `src/publicErrors.ts` are validated on every PR by the extension's own lint and TypeScript compile.
-- **Versioning:** the published package version in [`api/package.json`](./api/package.json) must always match the extension version in [`package.json`](./package.json). CI enforces this via [`scripts/compare_package_versions.py`](./scripts/compare_package_versions.py). Additionally, any PR that edits `src/api.ts`, `src/types.ts`, or `src/publicErrors.ts` must bump `api/package.json` (use the `skip api version` label to bypass) and add an entry to [`api/CHANGELOG.md`](./api/CHANGELOG.md) (use the `skip api changelog` label to bypass). When bumping, update both `package.json` files so they stay in sync.
+- **Versioning:** the published package version in [`api/package.json`](./api/package.json) is maintained independently of the extension version in [`package.json`](./package.json) — the two do not need to match. Any PR that edits `src/api.ts`, `src/types.ts`, or `src/publicErrors.ts` must bump `api/package.json` (use the `skip api version` label to bypass) and add an entry to [`api/CHANGELOG.md`](./api/CHANGELOG.md) (use the `skip api changelog` label to bypass).
 
 ## Questions or Issues?
 

api/package.json

@@ -39,7 +39,8 @@
     "scripts": {
         "prepublishOnly": "echo \"⛔ Can only publish from a secure pipeline ⛔\" && node -e \"process.exitCode = 1\"",
         "prepack": "npm run all:publish",
-        "all:publish": "git clean -xfd . && npm install && npm run compile",
+        "all:publish": "git clean -xfd . && npm install && npm run copy:sources && npm run compile",
+        "copy:sources": "node ./scripts/copy-sources.cjs",
         "compile": "npm run compile:esm && npm run compile:cjs",
         "compile:esm": "tsc -b ./tsconfig.esm.json && mve out/esm/main.js out/esm/main.mjs && node -e \"require('fs').writeFileSync('out/esm/package.json', '{\\\"type\\\":\\\"module\\\"}')\"",
         "compile:cjs": "tsc -b ./tsconfig.cjs.json && mve out/cjs/main.js out/cjs/main.cjs",

api/scripts/copy-sources.cjs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// Repopulates the package's generated `src` sources from the single sources of
+// truth in `../src`. These files are gitignored and are removed by the
+// `git clean -xfd .` step in `all:publish`, so they must be copied back before
+// TypeScript can compile. Mirrors the copy step in build/azure-pipeline.npm.yml.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(packageRoot, '..');
+const srcDir = path.join(packageRoot, 'src');
+
+const sources = [
+    { from: path.join(repoRoot, 'src', 'api.ts'), to: path.join(srcDir, 'main.ts') },
+    { from: path.join(repoRoot, 'src', 'types.ts'), to: path.join(srcDir, 'types.ts') },
+    { from: path.join(repoRoot, 'src', 'publicErrors.ts'), to: path.join(srcDir, 'publicErrors.ts') },
+];
+
+fs.mkdirSync(srcDir, { recursive: true });
+for (const { from, to } of sources) {
+    fs.copyFileSync(from, to);
+}

build/azure-pipeline.npm.yml

@@ -75,7 +75,7 @@ extends:
                 workingDirectory: $(Build.SourcesDirectory)/api
                 displayName: Install package dependencies
 
-              - script: mkdir -p src && cp ../src/api.ts src/main.ts && cp ../src/types.ts src/types.ts && cp ../src/publicErrors.ts src/publicErrors.ts
+              - script: npm run copy:sources
                 workingDirectory: $(Build.SourcesDirectory)/api
                 displayName: Copy src/api.ts, src/types.ts, src/publicErrors.ts to API package sources
 

examples/sample1/package-lock.json

@@ -12,6 +12,9 @@
     "activationEvents": [],
     "main": "./dist/extension.js",
     "contributes": {},
+    "dependencies": {
+        "@renovatebot/pep440": "^4.2.4"
+    },
     "scripts": {
         "vscode:prepublish": "npm run package",
         "compile": "webpack",