Merge extension-provided policy (#306874)

* Add merge script for extension configuration policies from distro

Adds build/lib/policies/mergeExtensionPolicies.ts which fetches the
distro's product.json (at the commit pinned in package.json) and merges
extensionConfigurationPolicy entries into policyData.jsonc.

The --export-policy-data step only captures policies from the OSS
configuration registry. Extension policies (e.g., Copilot settings)
are defined in vscode-distro's product.json and are not available in
the OSS dev build. This merge script bridges that gap.

Workflow: ./scripts/code.sh --export-policy-data && node build/lib/policies/mergeExtensionPolicies.ts

Also updates:
- policyExport integration test to run the merge step
- add-policy skill documentation with extension policy lifecycle

* Simplify extension policy format: drop localization block from distro

- mergeExtensionPolicies.ts now reads only description/category from
  the distro and synthesizes localization key/value pairs internally
- Integration test gracefully skips merge step when distro is unavailable
- Updated SKILL.md to document the simplified distro format

* docs: use gh auth token in policy export command

* Handle old distro format missing description/category fields

* docs: add troubleshooting section for merge step in policy skill

* Require description and category fields in extension policy entries

* Add extension configuration policies to policyData.jsonc

* Address PR feedback: fix disclaimer, log targetPath, strip GITHUB_TOKEN from test

* fix: revert extension policies from policyData.jsonc, remove console.log from test

Extension policies should only be added after the distro PR merges.
Test runner disallows console output in tests.

* Add mock distro test for mergeExtensionPolicies, remove merge from export test

- mergeExtensionPolicies.ts: add DISTRO_PRODUCT_JSON env var to
  override the distro path (for testing without private repo access)
- New test: creates a mock product.json, runs the merge script,
  verifies policies are added correctly and idempotently
- Export test: no longer runs the merge step (avoids needing
  distro access or GITHUB_TOKEN in CI)

* Update distro and regenerate policyData.jsonc with extension policies

* Fix CI: add extension policy fixture for export test

The export test now runs mergeExtensionPolicies using a checked-in
fixture file instead of requiring distro access or GITHUB_TOKEN.
When extension policies change in the distro, regenerate both
policyData.jsonc and the fixture file.

* Integrate extension policy merge into --export-policy-data

- Removed mergeExtensionPolicies.ts — no separate CLI tool needed
- --export-policy-data now reads build/lib/policies/extensionPolicies.json
  and merges extension policies into the output automatically
- Single command workflow: ./scripts/code.sh --export-policy-data
- Simplified test — no merge step, no GITHUB_TOKEN, no distro access
- Updated SKILL.md to document the simplified workflow

* Dynamic distro reading: --export-policy-data fetches from distro directly

- policyExport.contribution.ts reads distro product.json dynamically:
  1. DISTRO_PRODUCT_JSON env var (for testing)
  2. .build/distro/mixin/stable/product.json (local checkout)
  3. GitHub API with GITHUB_TOKEN (remote fetch)
- New scripts/export-policy-data.sh wrapper: sets up GITHUB_TOKEN
  via gh CLI and runs the export
- Deleted build/lib/policies/extensionPolicies.json (no static copy)
- Test uses DISTRO_PRODUCT_JSON with a fixture file
- Uses sandbox process.env and VSBuffer (renderer-safe)

* Replace bash wrapper with cross-platform TS script

- New build/lib/policies/exportPolicyData.ts: handles transpilation,
  GITHUB_TOKEN setup via gh CLI, and runs --export-policy-data
- Added 'npm run export-policy-data' script to package.json
- Removed scripts/export-policy-data.sh
- Updated SKILL.md and test error message

* Use OAuth device flow for GitHub token acquisition

exportPolicyData.ts now acquires tokens via:
1. GITHUB_TOKEN env var (if set)
2. gh CLI (fast, non-interactive)
3. GitHub OAuth device flow (interactive, no dependencies)

Based on vscode-copilot-chat's getToken.mts pattern.

* Fix error messages to reference npm run export-policy-data

* Fix disclaimer to reference npm run export-policy-data, clean up stale refs

* Clarify test fixture is static and not expected to track distro changes

* Add inline comment in test clarifying fixture is static

* SKILL.md: add step to update distro commit hash in package.json

* Remove inline comment per PR feedback

* Remove local .build/distro/ fallback path per PR feedback

.github/skills/add-policy/SKILL.md

@@ -124,15 +124,62 @@ npm run compile-check-ts-native
 Regenerate the auto-generated policy catalog:
 
 ```bash
-npm run transpile-client && ./scripts/code.sh --export-policy-data
+npm run export-policy-data
 ```
 
+This script handles transpilation, sets up `GITHUB_TOKEN` (via `gh` CLI or GitHub OAuth device flow), and runs `--export-policy-data`. The export command reads extension configuration policies from the distro's `product.json` via the GitHub API and merges them into the output.
+
 This updates `build/lib/policies/policyData.jsonc`. **Never edit this file manually.** Verify your new policy appears in the output.  You will need code review from a codeowner to merge the change to main.
 
 
 ## Policy for extension-provided settings
 
-For an extension author to provide policies for their extension's settings, a change must be made in `vscode-distro` to the `product.json`.
+Extension authors cannot add `policy:` fields directly—their settings are defined in the extension's `package.json`, not in VS Code core. Instead, policies for extension settings are defined in `vscode-distro`'s `product.json` under the `extensionConfigurationPolicy` key.
+
+### How it works
+
+1. **Source of truth**: The `extensionConfigurationPolicy` map lives in `vscode-distro` under `mixin/{quality}/product.json` (stable, insider, exploration).
+2. **Runtime**: When VS Code starts with a distro-mixed `product.json`, `configurationExtensionPoint.ts` reads `extensionConfigurationPolicy` and attaches matching `policy` objects to extension-contributed configuration properties.
+3. **Export/build**: The `--export-policy-data` command fetches the distro's `product.json` at the commit pinned in `package.json` and merges extension policies into the output. Use `npm run export-policy-data` which sets up authentication automatically.
+
+### Distro format
+
+Each entry in `extensionConfigurationPolicy` must include:
+
+```json
+"extensionConfigurationPolicy": {
+    "publisher.extension.settingName": {
+        "name": "PolicyName",
+        "category": "InteractiveSession",
+        "minimumVersion": "1.99",
+        "description": "Human-readable description."
+    }
+}
+```
+
+- `name`: PascalCase policy name, unique across all policies
+- `category`: Must be a valid `PolicyCategory` enum value (e.g., `InteractiveSession`, `Extensions`)
+- `minimumVersion`: The VS Code version that first shipped this policy
+- `description`: Human-readable description string used to generate localization key/value pairs for ADMX/ADML/macOS/Linux policy artifacts
+
+### Adding a new extension policy
+
+1. Add the entry to `extensionConfigurationPolicy` in **all three** quality `product.json` files in `vscode-distro` (`mixin/stable/`, `mixin/insider/`, `mixin/exploration/`)
+2. Update the `distro` commit hash in `package.json` to point to the distro commit that includes your new entry — the export command fetches extension policies from the pinned distro commit
+3. Regenerate `policyData.jsonc` by running `npm run export-policy-data` (see Step 4 above)
+4. Update the test fixture at `src/vs/workbench/contrib/policyExport/test/node/extensionPolicyFixture.json` with the new entry
+
+### Test fixtures
+
+The file `src/vs/workbench/contrib/policyExport/test/node/extensionPolicyFixture.json` is a test fixture that must stay in sync with the extension policies in the checked-in `policyData.jsonc`. When extension policies are added or changed in the distro, this fixture must be updated to match — otherwise the integration test will fail because the test output (generated from the fixture) won't match the checked-in file (generated from the real distro).
+
+### Downstream consumers
+
+| Consumer | What it reads | Output |
+|----------|--------------|--------|
+| `policyGenerator.ts` | `policyData.jsonc` | ADMX/ADML (Windows GP), `.mobileconfig` (macOS), `policy.json` (Linux) |
+| `vscode-website` (`gulpfile.policies.js`) | `policyData.jsonc` | Enterprise policy reference table at code.visualstudio.com/docs/enterprise/policies |
+| `vscode-docs` | Generated from website build | `docs/enterprise/policies.md` |
 
 ## Examples