@maccesar/aiskills 1.12.0 → 1.15.0

package/skills/vscode-extension-dev/references/lsp.md

@@ -0,0 +1,175 @@
+# Language Server Protocol (LSP)
+
+Build a language extension by running an out-of-process **language server** and connecting it to VS Code via the `vscode-languageclient` npm package. The server can be written in any language; only the client lives inside the extension.
+
+Official guide: https://code.visualstudio.com/api/language-extensions/language-server-extension-guide
+Protocol spec: https://microsoft.github.io/language-server-protocol/
+
+## When to Use LSP vs Direct API
+
+| Need | Use |
+|---|---|
+| Diagnostics, completion, hover for ONE editor (VS Code only) | Direct API (`vscode.languages.register*Provider`) |
+| Same language features in VS Code + other LSP clients (Neovim, Sublime, etc.) | LSP |
+| Heavy parsing/analysis you want isolated from the extension host | LSP (server runs in its own process) |
+| Sharing logic with a CLI or CI tool | LSP (server is reusable) |
+
+**Rule of thumb**: write LSP if the features are non-trivial OR you want portability. Use direct API for a one-off completion provider in a single language.
+
+## Project Structure
+
+```
+my-language-ext/
+├── client/
+│   ├── src/extension.ts          # The VS Code extension (the client)
+│   └── tsconfig.json
+├── server/
+│   ├── src/server.ts             # Language server (Node-based example)
+│   └── tsconfig.json
+├── package.json                  # Extension manifest (covers both)
+└── tsconfig.json                 # Root, with project references
+```
+
+The extension's `package.json` lists `vscode-languageclient` as a runtime dependency and uses `activationEvents: ["onLanguage:<langId>"]`.
+
+## Client (extension side)
+
+```typescript
+import * as path from 'node:path';
+import * as vscode from 'vscode';
+import {
+  LanguageClient,
+  LanguageClientOptions,
+  ServerOptions,
+  TransportKind,
+} from 'vscode-languageclient/node';
+
+let client: LanguageClient | undefined;
+
+export function activate(context: vscode.ExtensionContext) {
+  const serverModule = context.asAbsolutePath(
+    path.join('server', 'out', 'server.js'),
+  );
+
+  const serverOptions: ServerOptions = {
+    run: { module: serverModule, transport: TransportKind.ipc },
+    debug: {
+      module: serverModule,
+      transport: TransportKind.ipc,
+      options: { execArgv: ['--nolazy', '--inspect=6009'] },
+    },
+  };
+
+  const clientOptions: LanguageClientOptions = {
+    documentSelector: [{ scheme: 'file', language: 'myLang' }],
+    synchronize: {
+      fileEvents: vscode.workspace.createFileSystemWatcher('**/.myLangConfig'),
+    },
+  };
+
+  client = new LanguageClient(
+    'myLangServer',
+    'My Language Server',
+    serverOptions,
+    clientOptions,
+  );
+
+  client.start();
+}
+
+export async function deactivate(): Promise<void> {
+  if (client) {
+    await client.stop();
+  }
+}
+```
+
+`TransportKind.ipc` is the recommended transport for Node-based servers (process IPC). For non-Node servers, spawn with `TransportKind.stdio` or `TransportKind.socket`.
+
+## Server (minimal Node example)
+
+```typescript
+import {
+  createConnection,
+  TextDocuments,
+  ProposedFeatures,
+  InitializeParams,
+  TextDocumentSyncKind,
+  CompletionItem,
+  CompletionItemKind,
+} from 'vscode-languageserver/node';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+
+const connection = createConnection(ProposedFeatures.all);
+const documents = new TextDocuments(TextDocument);
+
+connection.onInitialize((_params: InitializeParams) => ({
+  capabilities: {
+    textDocumentSync: TextDocumentSyncKind.Incremental,
+    completionProvider: { resolveProvider: false, triggerCharacters: ['.'] },
+    hoverProvider: true,
+  },
+}));
+
+connection.onCompletion((_params): CompletionItem[] => [
+  { label: 'hello', kind: CompletionItemKind.Keyword },
+]);
+
+connection.onHover((params) => {
+  const doc = documents.get(params.textDocument.uri);
+  if (!doc) return null;
+  return { contents: { kind: 'markdown', value: 'Hover content' } };
+});
+
+documents.listen(connection);
+connection.listen();
+```
+
+## Capabilities You Typically Register
+
+| Capability | Server method | Client receives |
+|---|---|---|
+| Completion | `onCompletion` | items shown in IntelliSense |
+| Hover | `onHover` | tooltip on hover |
+| Diagnostics | `connection.sendDiagnostics({ uri, diagnostics })` | Problems panel + squiggles |
+| Definition | `onDefinition` | "Go to Definition" target |
+| References | `onReferences` | "Find All References" results |
+| Document symbols | `onDocumentSymbol` | breadcrumbs + outline |
+| Formatting | `onDocumentFormatting` | "Format Document" |
+| Code actions | `onCodeAction` | quick fixes / refactors |
+| Rename | `onRenameRequest` | symbol rename |
+
+Each capability must be declared in the `InitializeResult.capabilities` AND have a matching server handler. Mismatch = silent failure.
+
+## Diagnostics (Push Model)
+
+Send diagnostics whenever a document changes:
+
+```typescript
+documents.onDidChangeContent((event) => {
+  const diagnostics = validate(event.document);
+  connection.sendDiagnostics({
+    uri: event.document.uri,
+    diagnostics,
+  });
+});
+```
+
+Diagnostic structure:
+
+```typescript
+{
+  severity: DiagnosticSeverity.Error, // Error | Warning | Information | Hint
+  range: { start: { line: 0, character: 0 }, end: { line: 0, character: 10 } },
+  message: 'Unexpected token',
+  source: 'my-lang',
+}
+```
+
+## Anti-Patterns
+
+- ❌ Re-parsing the whole document on every keystroke — use `TextDocumentSyncKind.Incremental` and process deltas
+- ❌ Heavy work inside `onInitialize` — it blocks editor startup; do it lazily on first request
+- ❌ Forgetting to `await client.stop()` in `deactivate()` — leaves the server process alive
+- ❌ Hardcoding paths in `serverModule` — always go through `context.asAbsolutePath`
+- ❌ Mixing client and server types — `vscode-languageclient/node` is for the client, `vscode-languageserver/node` is for the server

package/skills/vscode-extension-dev/references/notebooks.md

@@ -0,0 +1,208 @@
+# Notebook Extensions
+
+VS Code supports notebooks (Jupyter-style) through three independent extension points: **serializers** (read/write file format), **controllers** (execute cells), and **renderers** (display rich output). You can implement any combination.
+
+Official guide: https://code.visualstudio.com/api/extension-guides/notebook
+
+## The Three Roles
+
+| Role | What it does | API |
+|---|---|---|
+| Serializer | Converts file bytes ↔ in-memory `NotebookData` | `NotebookSerializer` |
+| Controller | Runs a cell, produces outputs | `NotebookController` |
+| Renderer | Webview that displays a specific output mime type | `package.json#contributes.notebookRenderer` |
+
+A `.ipynb`-style extension typically provides serializer + controller. A renderer-only extension can extend ANY notebook (e.g., render a custom plot mime type).
+
+## Notebook Serializer
+
+Used to load and save the notebook file format.
+
+```typescript
+import * as vscode from 'vscode';
+
+class MyNotebookSerializer implements vscode.NotebookSerializer {
+  async deserializeNotebook(
+    content: Uint8Array,
+    _token: vscode.CancellationToken,
+  ): Promise<vscode.NotebookData> {
+    const text = new TextDecoder().decode(content);
+    const parsed = JSON.parse(text);
+
+    const cells = parsed.cells.map((c: any) =>
+      new vscode.NotebookCellData(
+        c.kind === 'code'
+          ? vscode.NotebookCellKind.Code
+          : vscode.NotebookCellKind.Markup,
+        c.source,
+        c.language ?? 'plaintext',
+      ),
+    );
+
+    return new vscode.NotebookData(cells);
+  }
+
+  async serializeNotebook(
+    data: vscode.NotebookData,
+    _token: vscode.CancellationToken,
+  ): Promise<Uint8Array> {
+    const out = {
+      cells: data.cells.map((c) => ({
+        kind: c.kind === vscode.NotebookCellKind.Code ? 'code' : 'markdown',
+        language: c.languageId,
+        source: c.value,
+      })),
+    };
+    return new TextEncoder().encode(JSON.stringify(out, null, 2));
+  }
+}
+
+export function activate(context: vscode.ExtensionContext) {
+  context.subscriptions.push(
+    vscode.workspace.registerNotebookSerializer(
+      'my-notebook',           // notebook type id (see package.json)
+      new MyNotebookSerializer(),
+      { transientOutputs: false }, // false = persist outputs in file
+    ),
+  );
+}
+```
+
+`package.json`:
+
+```json
+"contributes": {
+  "notebooks": [
+    {
+      "type": "my-notebook",
+      "displayName": "My Notebook",
+      "selector": [{ "filenamePattern": "*.mynb" }]
+    }
+  ]
+}
+```
+
+## Notebook Controller
+
+Runs cells and produces outputs.
+
+```typescript
+class MyController {
+  readonly controllerId = 'my-controller';
+  readonly notebookType = 'my-notebook';
+  readonly label = 'My Kernel';
+  readonly supportedLanguages = ['python', 'plaintext'];
+
+  private readonly _controller: vscode.NotebookController;
+  private _executionOrder = 0;
+
+  constructor() {
+    this._controller = vscode.notebooks.createNotebookController(
+      this.controllerId,
+      this.notebookType,
+      this.label,
+    );
+    this._controller.supportedLanguages = this.supportedLanguages;
+    this._controller.supportsExecutionOrder = true;
+    this._controller.executeHandler = this._execute.bind(this);
+  }
+
+  private async _execute(
+    cells: vscode.NotebookCell[],
+    _notebook: vscode.NotebookDocument,
+    _controller: vscode.NotebookController,
+  ): Promise<void> {
+    for (const cell of cells) {
+      const exec = this._controller.createNotebookCellExecution(cell);
+      exec.executionOrder = ++this._executionOrder;
+      exec.start(Date.now());
+
+      try {
+        const result = await this._runCell(cell);
+        await exec.replaceOutput([
+          new vscode.NotebookCellOutput([
+            vscode.NotebookCellOutputItem.text(result, 'text/plain'),
+          ]),
+        ]);
+        exec.end(true, Date.now());
+      } catch (err) {
+        await exec.replaceOutput([
+          new vscode.NotebookCellOutput([
+            vscode.NotebookCellOutputItem.error(err as Error),
+          ]),
+        ]);
+        exec.end(false, Date.now());
+      }
+    }
+  }
+
+  private async _runCell(cell: vscode.NotebookCell): Promise<string> {
+    // Real kernels: send cell.document.getText() to a backend, await result
+    return `Echo: ${cell.document.getText()}`;
+  }
+
+  dispose(): void {
+    this._controller.dispose();
+  }
+}
+```
+
+Register the controller in `activate()` and push to `context.subscriptions`.
+
+## Output Mime Types
+
+Common mime types VS Code knows how to render natively:
+
+- `text/plain`
+- `text/markdown`
+- `text/html`
+- `image/png`, `image/jpeg`, `image/svg+xml`
+- `application/json`
+- `application/x.notebook.error` (use `NotebookCellOutputItem.error(err)`)
+- `application/vnd.code.notebook.stdout` / `.stderr` (use `.stdout(str)` / `.stderr(str)`)
+
+For anything else, ship a notebook renderer (next section).
+
+## Notebook Renderer
+
+A renderer is a webview that takes a typed output and produces DOM. Declared entirely in `package.json` + a script that exports `activate`:
+
+```json
+"contributes": {
+  "notebookRenderer": [
+    {
+      "id": "my-plot-renderer",
+      "displayName": "My Plot",
+      "entrypoint": "./out/renderer.js",
+      "mimeTypes": ["application/x.my-plot+json"]
+    }
+  ]
+}
+```
+
+`renderer.ts` — build the DOM with safe APIs, never inject untrusted strings as HTML:
+
+```typescript
+import type { ActivationFunction } from 'vscode-notebook-renderer';
+
+export const activate: ActivationFunction = () => ({
+  renderOutputItem(outputItem, element) {
+    const data = outputItem.json();
+
+    const pre = document.createElement('pre');
+    pre.textContent = JSON.stringify(data, null, 2);
+    element.replaceChildren(pre);
+  },
+});
+```
+
+Renderers run in a separate iframe — they cannot call `vscode.*` directly. Communicate with the controller via the messaging API exposed in `renderer.activate`.
+
+## Anti-Patterns
+
+- ❌ Writing to disk synchronously in the serializer — VS Code calls it on the main thread
+- ❌ Forgetting `exec.end(success, endTime)` — the cell stays in "running" state forever
+- ❌ Reusing `executionOrder` numbers — must monotonically increase per notebook session
+- ❌ Heavy DOM building in the renderer without batching — laggy scroll on large notebooks
+- ❌ Bundling a notebook renderer with `vscode` as a dependency — renderers run in an iframe, not the extension host; they have NO `vscode` import
+- ❌ Setting `innerHTML` from untrusted output data — XSS in the notebook viewer. Build DOM with `createElement` + `textContent`

package/skills/vscode-extension-dev/references/testing.md

@@ -0,0 +1,208 @@
+# Testing Extensions (Advanced)
+
+Beyond the basic Mocha setup covered in `architecture.md`: configuring `.vscode-test.mjs` for multiple suites, isolating unit tests from the VS Code runtime, mocking the `vscode` module, running tests in CI, and measuring coverage.
+
+Official guide: https://code.visualstudio.com/api/working-with-extensions/testing-extension
+
+## Two Test Layers
+
+| Layer | Runs in | Imports `vscode`? | Speed |
+|---|---|---|---|
+| Unit | Plain Node (Mocha/Vitest) | No — only `services/`, pure logic | Fast |
+| Integration | VS Code Extension Host (Electron) via `@vscode/test-electron` | Yes | Slow |
+
+Keep `services/` free of `vscode` imports so unit tests don't need the Electron runtime. Integration tests cover wiring (commands registered, providers connected, activation works).
+
+## `.vscode-test.mjs` (Multi-Suite)
+
+The default file in `architecture.md` runs one suite. For real extensions, split by concern:
+
+```javascript
+import { defineConfig } from '@vscode/test-cli';
+
+export default defineConfig([
+  {
+    label: 'integration',
+    files: 'out/test/integration/**/*.test.js',
+    workspaceFolder: './test/fixtures/workspace-basic',
+    mocha: { timeout: 20000, ui: 'tdd' },
+  },
+  {
+    label: 'multi-root',
+    files: 'out/test/multi-root/**/*.test.js',
+    workspaceFolder: './test/fixtures/workspace-multi.code-workspace',
+    mocha: { timeout: 30000, ui: 'tdd' },
+  },
+  {
+    label: 'insiders',
+    version: 'insiders',
+    files: 'out/test/integration/**/*.test.js',
+    workspaceFolder: './test/fixtures/workspace-basic',
+  },
+]);
+```
+
+Run a specific suite: `vscode-test --label integration`.
+
+## Workspace Fixtures
+
+Integration tests need a real folder on disk because the editor expects a workspace:
+
+```
+test/fixtures/
+├── workspace-basic/
+│   ├── .vscode/
+│   │   └── settings.json
+│   ├── src/
+│   │   └── sample.txt
+│   └── package.json
+└── workspace-multi.code-workspace
+```
+
+```json
+// workspace-multi.code-workspace
+{
+  "folders": [
+    { "path": "workspace-basic" },
+    { "path": "workspace-secondary" }
+  ]
+}
+```
+
+Mutating fixtures in a test? Copy to a temp dir in `suiteSetup` and point the test there — leaving committed fixtures dirty between runs causes flakes.
+
+## Mocking the `vscode` Module (Unit Tests)
+
+`vscode` is provided by the Electron host — it has no npm package. Unit tests outside the host can't `import 'vscode'` directly. Two ways around this:
+
+**1. Dependency injection** (preferred): never import `vscode` in `services/`. Pass the bits you need as parameters.
+
+```typescript
+// services/processor.ts — pure, no vscode import
+export interface FileReader {
+  read(path: string): Promise<string>;
+}
+
+export async function process(reader: FileReader, path: string): Promise<number> {
+  const text = await reader.read(path);
+  return text.split('\n').length;
+}
+```
+
+Test it with a fake reader. The VS Code layer adapts `vscode.workspace.fs` to the `FileReader` interface.
+
+**2. Module aliasing** (when DI isn't feasible): map `vscode` to a stub via the test runner.
+
+```javascript
+// vitest.config.ts (or jest moduleNameMapper)
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    alias: {
+      vscode: new URL('./test/stubs/vscode.ts', import.meta.url).pathname,
+    },
+  },
+});
+```
+
+```typescript
+// test/stubs/vscode.ts — just enough surface to compile
+export const window = {
+  showInformationMessage: (..._args: unknown[]) => Promise.resolve(undefined),
+  showErrorMessage: (..._args: unknown[]) => Promise.resolve(undefined),
+  activeTextEditor: undefined,
+};
+export const workspace = {
+  workspaceFolders: undefined as readonly unknown[] | undefined,
+  getConfiguration: () => ({ get: () => undefined }),
+};
+export const Uri = { file: (p: string) => ({ fsPath: p }) };
+// add more as needed
+```
+
+Aliasing is brittle — keep the stub minimal and prefer DI for non-trivial logic.
+
+## CI: GitHub Actions
+
+VS Code tests need a display. On Linux runners, wrap with `xvfb`:
+
+```yaml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run compile
+      - name: Run tests (Linux)
+        if: runner.os == 'Linux'
+        run: xvfb-run -a npm test
+      - name: Run tests (non-Linux)
+        if: runner.os != 'Linux'
+        run: npm test
+```
+
+## Coverage
+
+`@vscode/test-electron` runs in a real Electron process, so traditional Istanbul instrumentation can't simply wrap `node`. Use `c8` against the compiled output:
+
+```json
+// package.json
+"scripts": {
+  "test:coverage": "c8 --reporter=text --reporter=lcov vscode-test"
+}
+```
+
+`c8` reads V8's native coverage and produces an `lcov.info` you can upload to Codecov/Coveralls. Coverage of integration-test execution paths only — unit tests should be measured separately and merged.
+
+## Stable Test Patterns
+
+```typescript
+import * as assert from 'assert';
+import * as vscode from 'vscode';
+
+suite('Activation', () => {
+  suiteSetup(async () => {
+    const ext = vscode.extensions.getExtension('publisher.my-extension');
+    assert.ok(ext, 'Extension not found — check publisher and name in package.json');
+    await ext!.activate();
+  });
+
+  test('registers expected commands', async () => {
+    const commands = await vscode.commands.getCommands(true);
+    for (const id of ['myExt.run', 'myExt.refresh']) {
+      assert.ok(commands.includes(id), `Missing command: ${id}`);
+    }
+  });
+
+  test('respects user setting', async () => {
+    const config = vscode.workspace.getConfiguration('myExt');
+    await config.update('mode', 'strict', vscode.ConfigurationTarget.Workspace);
+
+    // ...exercise the feature
+
+    await config.update('mode', undefined, vscode.ConfigurationTarget.Workspace);
+  });
+});
+```
+
+Always restore mutated settings/state in `teardown` or `suiteTeardown` — workspace state persists across test files.
+
+## Anti-Patterns
+
+- ❌ Putting business logic that doesn't touch the editor inside `extension.ts` — forces every test to spin up Electron
+- ❌ Sharing state between tests via module-level variables — order-dependent failures
+- ❌ `setTimeout`/`sleep` to "wait for activation" — use `await ext.activate()` and the `onDidStartDebugSession` (or similar) events
+- ❌ Hardcoding absolute paths in fixtures — breaks on CI runners
+- ❌ Running `xvfb-run` on macOS/Windows — only needed on Linux
+- ❌ Trusting that a fresh test instance is clean — clear workspace state and SecretStorage explicitly when behavior depends on them