|
| 1 | +--- |
| 2 | +name: vscode-service-upgrade |
| 3 | +description: 'Upgrade monaco-vscode-api internal VS Code services after a VSCode version bump. Use when missing-services.ts breaks due to service interface changes, when new registerSingleton services must be added, and when service-override modules must be updated for web/common/browser only.' |
| 4 | +argument-hint: 'Target VSCode ref or upgrade context (optional)' |
| 5 | +user-invocable: true |
| 6 | +disable-model-invocation: false |
| 7 | +--- |
| 8 | + |
| 9 | +# VSCode Service Upgrade |
| 10 | + |
| 11 | +## What This Skill Produces |
| 12 | +- A fully updated `src/missing-services.ts` aligned with current VSCode service interfaces. |
| 13 | +- New services introduced between two VSCode refs, wired into this library for web builds. |
| 14 | +- Updated `service-override` modules that dispatch real VSCode implementations for newly added services. |
| 15 | +- Updated `src/services.ts` exports for all newly introduced service identifiers. |
| 16 | +- Mandatory dual wiring for each added service: |
| 17 | + - a fake implementation in `src/missing-services.ts`, |
| 18 | + - the real implementation in the relevant `src/service-override/*.ts` module. |
| 19 | +- Validation signals that unsupported stubs are explicitly marked and type-safe. |
| 20 | + |
| 21 | +## When To Use |
| 22 | +- After updating `config.vscode.ref` in `package.json`. |
| 23 | +- When TypeScript errors indicate service interface drift in `src/missing-services.ts`. |
| 24 | +- When upstream VSCode added service singletons and this project now misses overrides. |
| 25 | + |
| 26 | +## Inputs And Assumptions |
| 27 | +- Repository root is the current working directory. |
| 28 | +- Upstream VSCode source is located at `../vscode`. |
| 29 | +- Built/transformed VSCode sources exist under `./vscode` where service identifiers were split into `*.service.js` next to original modules. |
| 30 | +- Only web, common, and browser services are in scope. |
| 31 | +- Services from electron, electron-browser, and session code paths are out of scope. |
| 32 | + |
| 33 | +## Procedure |
| 34 | +0. Run preflight dependency sync first (mandatory). |
| 35 | +- Before any ref analysis or code migration, run: |
| 36 | + - npm run update-local-dependencies && npm i |
| 37 | +- Do not continue until this command succeeds. |
| 38 | + |
| 39 | +1. Resolve refs and scope. |
| 40 | +- Read the new ref from `package.json` at `config.vscode.ref`. |
| 41 | +- Determine previous ref from git history of `package.json` (for example: `git log -p -- package.json`, then extract prior `config.vscode.ref`). |
| 42 | +- Confirm target scope: include only `common` and `browser` services. |
| 43 | + |
| 44 | +2. Update missing-services first. |
| 45 | +- Open `src/missing-services.ts` and align each fake service implementation with current interface signatures. |
| 46 | +- For methods and fields that are straightforward: implement a minimal functional behavior. |
| 47 | +- For methods and fields that are too complex or not meaningful in this runtime: |
| 48 | + - use `unsupported` implementation, |
| 49 | + - add the `@Unsupported` annotation. |
| 50 | +- Ensure every method declaration is typed by the interface member type pattern so future removals/renames fail at compile time. |
| 51 | +- Keep conventions already used in this file (naming, ordering, decorators, helper usage). |
| 52 | + |
| 53 | +3. Discover newly registered services upstream. |
| 54 | +- In `../vscode`, diff old and new refs and list newly registered singletons. |
| 55 | +- Preferred command pattern: |
| 56 | + - `git diff <oldRef> <newRef> -G'registerSingleton\('` |
| 57 | +- Filter findings: |
| 58 | + - keep services defined in `common` or `browser`, |
| 59 | + - ignore entries from `electron`, `session`, `electron-browser`, and similar non-web layers. |
| 60 | + |
| 61 | +4. Add new services to this library. |
| 62 | +- Introduce missing service identifiers/imports based on transformed modules in `./vscode` (`module.js` and sibling `module.service.js`). |
| 63 | +- For each newly in-scope service, first add a fake implementation in `src/missing-services.ts` using the same decision rules from Step 2. |
| 64 | +- Then wire the same service into every relevant `service-override` module. |
| 65 | +- In `service-override` modules, use the actual VSCode implementation (not a fake fallback) whenever available and compatible with web scope. |
| 66 | +- Export every newly added service identifier from `src/services.ts`. |
| 67 | +- Do not consider a service migration complete unless both sides are implemented: fake in `missing-services.ts` and real in `service-override`. |
| 68 | + |
| 69 | +5. Validate changes. |
| 70 | +- Run type/lint checks for touched files. |
| 71 | +- Run unsupported coverage check: |
| 72 | + - `npm run check-unsupported-decorator` |
| 73 | +- Ensure no unsupported fallback is left without `@Unsupported`. |
| 74 | +- Ensure all interface-typed methods compile. |
| 75 | + |
| 76 | +## Decision Rules |
| 77 | +- Implement vs unsupported: |
| 78 | + - Implement if behavior is deterministic, low-risk, and feasible in browser runtime. |
| 79 | + - This skill uses a pragmatic default: do a minimal implementation for simple web-safe behavior, and reserve `unsupported` for complex or runtime-incompatible behavior. |
| 80 | + - Mark unsupported if behavior depends on desktop/session-only capabilities or heavy runtime coupling. |
| 81 | +- Add service override vs skip: |
| 82 | + - Add when service is registered upstream in web-relevant layers and used by bundled code. |
| 83 | + - Skip when service exists only in non-web layers. |
| 84 | + - Keep override-module coverage checks generic (do not require a fixed hardcoded module list). |
| 85 | + |
| 86 | +## Completion Checklist |
| 87 | +- Preflight dependency sync completed successfully: |
| 88 | + - npm run update-local-dependencies && npm i |
| 89 | +- `src/missing-services.ts` updated before any other service migration work. |
| 90 | +- Every newly added service has both: |
| 91 | + - a fake registration in `src/missing-services.ts`, |
| 92 | + - a real registration in a relevant `src/service-override/*.ts` module. |
| 93 | +- Every newly added service identifier is exported from `src/services.ts`. |
| 94 | +- Every new/changed member follows interface-member typing convention. |
| 95 | +- Every unsupported member uses both `unsupported` and `@Unsupported`. |
| 96 | +- New upstream services between refs are reviewed and triaged by layer. |
| 97 | +- Relevant `service-override` modules include all newly in-scope services. |
| 98 | +- Required validation commands pass: |
| 99 | + - `npm run check-unsupported-decorator` |
| 100 | + - `npm run build` |
| 101 | + |
| 102 | +## Suggested Prompt Examples |
| 103 | +- `/vscode-service-upgrade upgrade services after vscode ref bump from 1.123.0 to 1.124.0` |
| 104 | +- `/vscode-service-upgrade update missing-services.ts and add new browser/common services` |
| 105 | +- `/vscode-service-upgrade find registerSingleton additions and wire service-overrides` |
0 commit comments