@maccesar/aiskills 1.11.0 → 1.15.0

package/skills/vscode-extension-dev/references/api-quickpick.md

@@ -0,0 +1,75 @@
+# QuickPick
+
+Modal list with filtering, multi-select, and async items.
+
+## Simple QuickPick
+
+```typescript
+const items: vscode.QuickPickItem[] = [
+  { label: 'Item 1', description: 'First item', detail: 'Additional details' },
+  { label: 'Item 2', description: 'Second item', picked: true },
+  { label: 'Item 3', description: 'Third item' },
+];
+
+const selected = await vscode.window.showQuickPick(items, {
+  placeHolder: 'Select an item',
+  canPickMany: false,
+  matchOnDescription: true,
+  matchOnDetail: true,
+});
+
+if (selected) {
+  vscode.window.showInformationMessage(`Selected: ${selected.label}`);
+}
+```
+
+## QuickPick with Async Loading
+
+```typescript
+async function showAsyncQuickPick(): Promise<void> {
+  const qp = vscode.window.createQuickPick<vscode.QuickPickItem>();
+  qp.placeholder = 'Search items...';
+  qp.matchOnDescription = true;
+
+  // Debounced search
+  let searchTimer: ReturnType<typeof setTimeout> | undefined;
+  const controller = new AbortController();
+
+  qp.onDidChangeValue((value) => {
+    if (searchTimer) {
+      clearTimeout(searchTimer);
+    }
+    searchTimer = setTimeout(async () => {
+      qp.busy = true;
+      try {
+        const results = await fetchItems(value, controller.signal);
+        qp.items = results.map((r) => ({
+          label: r.name,
+          description: r.description,
+        }));
+      } catch (err) {
+        if (err instanceof Error && err.name !== 'AbortError') {
+          vscode.window.showErrorMessage(`Search failed: ${err.message}`);
+        }
+      } finally {
+        qp.busy = false;
+      }
+    }, 300);
+  });
+
+  qp.onDidAccept(() => {
+    const selected = qp.selectedItems[0];
+    if (selected) {
+      vscode.window.showInformationMessage(`Selected: ${selected.label}`);
+    }
+    qp.dispose();
+  });
+
+  qp.onDidHide(() => {
+    controller.abort();
+    qp.dispose();
+  });
+
+  qp.show();
+}
+```

package/skills/vscode-extension-dev/references/api-secretstorage.md

@@ -0,0 +1,57 @@
+# SecretStorage
+
+Secure credential storage using the OS keychain.
+
+```typescript
+class CredentialManager {
+  private static readonly TOKEN_KEY = 'myExt.apiToken';
+
+  constructor(private readonly secrets: vscode.SecretStorage) {}
+
+  async getToken(): Promise<string | undefined> {
+    return this.secrets.get(CredentialManager.TOKEN_KEY);
+  }
+
+  async setToken(token: string): Promise<void> {
+    await this.secrets.store(CredentialManager.TOKEN_KEY, token);
+  }
+
+  async deleteToken(): Promise<void> {
+    await this.secrets.delete(CredentialManager.TOKEN_KEY);
+  }
+
+  onDidChange(callback: (e: vscode.SecretStorageChangeEvent) => void): vscode.Disposable {
+    return this.secrets.onDidChange(callback);
+  }
+}
+
+// In activate():
+export function activate(context: vscode.ExtensionContext) {
+  const credentials = new CredentialManager(context.secrets);
+
+  context.subscriptions.push(
+    vscode.commands.registerCommand('myExt.login', async () => {
+      const token = await vscode.window.showInputBox({
+        prompt: 'Enter your API token',
+        password: true,
+        ignoreFocusOut: true,
+      });
+      if (token) {
+        await credentials.setToken(token);
+        vscode.window.showInformationMessage('Token saved securely.');
+      }
+    }),
+
+    vscode.commands.registerCommand('myExt.logout', async () => {
+      await credentials.deleteToken();
+      vscode.window.showInformationMessage('Token removed.');
+    }),
+
+    credentials.onDidChange((e) => {
+      if (e.key === 'myExt.apiToken') {
+        // React to credential change
+      }
+    }),
+  );
+}
+```

package/skills/vscode-extension-dev/references/api-statusbar.md

@@ -0,0 +1,38 @@
+# StatusBarItem
+
+Persistent info in the status bar with click action.
+
+```typescript
+export function activate(context: vscode.ExtensionContext) {
+  const statusBar = vscode.window.createStatusBarItem(
+    vscode.StatusBarAlignment.Right,
+    100, // priority — higher = more to the left
+  );
+
+  statusBar.text = '$(sync) My Extension';
+  statusBar.tooltip = 'Click to refresh';
+  statusBar.command = 'myExt.refresh';
+  statusBar.backgroundColor = undefined; // use new vscode.ThemeColor('statusBarItem.warningBackground') for warnings
+  statusBar.show();
+
+  context.subscriptions.push(statusBar);
+
+  // Update dynamically
+  function updateStatus(count: number): void {
+    statusBar.text = `$(check) ${count} items`;
+    statusBar.tooltip = `${count} items synced`;
+  }
+}
+```
+
+## Codicon Icons in StatusBar
+
+Use `$(icon-name)` syntax. Common icons:
+
+- `$(sync~spin)` — spinning sync (loading)
+- `$(check)` — checkmark
+- `$(warning)` — warning triangle
+- `$(error)` — error circle
+- `$(info)` — info circle
+- `$(cloud-upload)` — upload
+- Full list: https://code.visualstudio.com/api/references/icons-in-labels

package/skills/vscode-extension-dev/references/api-treeview.md

@@ -0,0 +1,78 @@
+# TreeDataProvider
+
+Provides data for a TreeView in the sidebar or panel.
+
+```typescript
+import * as vscode from 'vscode';
+
+interface TreeItem {
+  id: string;
+  label: string;
+  children?: TreeItem[];
+}
+
+class MyTreeProvider implements vscode.TreeDataProvider<TreeItem> {
+  private _onDidChangeTreeData = new vscode.EventEmitter<TreeItem | undefined>();
+  readonly onDidChangeTreeData = this._onDidChangeTreeData.event;
+
+  private items: TreeItem[] = [];
+
+  refresh(): void {
+    this._onDidChangeTreeData.fire(undefined);
+  }
+
+  getTreeItem(element: TreeItem): vscode.TreeItem {
+    const treeItem = new vscode.TreeItem(
+      element.label,
+      element.children?.length
+        ? vscode.TreeItemCollapsibleState.Collapsed
+        : vscode.TreeItemCollapsibleState.None
+    );
+    treeItem.id = element.id;
+    treeItem.contextValue = element.children ? 'parent' : 'leaf';
+    treeItem.iconPath = new vscode.ThemeIcon('symbol-file');
+    // Make leaf items clickable
+    if (!element.children) {
+      treeItem.command = {
+        command: 'myExt.openItem',
+        title: 'Open Item',
+        arguments: [element],
+      };
+    }
+    return treeItem;
+  }
+
+  getChildren(element?: TreeItem): TreeItem[] {
+    if (!element) {
+      return this.items;
+    }
+    return element.children ?? [];
+  }
+
+  setItems(items: TreeItem[]): void {
+    this.items = items;
+    this.refresh();
+  }
+}
+```
+
+## Registering the TreeView
+
+```typescript
+export function activate(context: vscode.ExtensionContext) {
+  const treeProvider = new MyTreeProvider();
+
+  const treeView = vscode.window.createTreeView('myTreeView', {
+    treeDataProvider: treeProvider,
+    showCollapseAll: true,
+  });
+
+  context.subscriptions.push(
+    treeView,
+    vscode.commands.registerCommand('myExt.refresh', () => treeProvider.refresh()),
+    vscode.commands.registerCommand('myExt.openItem', (item: TreeItem) => {
+      vscode.window.showInformationMessage(`Opened: ${item.label}`);
+    }),
+  );
+}
+```

package/skills/vscode-extension-dev/references/api-webview.md

@@ -0,0 +1,149 @@
+# Webview Panel
+
+Full HTML rendering with CSP and bidirectional messaging.
+
+```typescript
+import * as vscode from 'vscode';
+
+class MyWebviewPanel {
+  public static readonly viewType = 'myExt.webview';
+  private readonly _panel: vscode.WebviewPanel;
+  private readonly _extensionUri: vscode.Uri;
+  private _disposables: vscode.Disposable[] = [];
+
+  public static create(extensionUri: vscode.Uri): MyWebviewPanel {
+    const panel = vscode.window.createWebviewPanel(
+      MyWebviewPanel.viewType,
+      'My Panel',
+      vscode.ViewColumn.One,
+      {
+        enableScripts: true,
+        retainContextWhenHidden: false, // saves memory; set true if state is expensive
+        localResourceRoots: [vscode.Uri.joinPath(extensionUri, 'media')],
+      },
+    );
+
+    return new MyWebviewPanel(panel, extensionUri);
+  }
+
+  private constructor(panel: vscode.WebviewPanel, extensionUri: vscode.Uri) {
+    this._panel = panel;
+    this._extensionUri = extensionUri;
+
+    this._panel.webview.html = this._getHtml(this._panel.webview);
+
+    // Handle messages FROM the webview
+    this._panel.webview.onDidReceiveMessage(
+      (message: { command: string; data?: unknown }) => {
+        switch (message.command) {
+          case 'save':
+            this._handleSave(message.data);
+            return;
+          case 'requestData':
+            this._sendData();
+            return;
+        }
+      },
+      null,
+      this._disposables,
+    );
+
+    this._panel.onDidDispose(() => this.dispose(), null, this._disposables);
+  }
+
+  /** Send data TO the webview */
+  public sendMessage(command: string, data: unknown): void {
+    this._panel.webview.postMessage({ command, data });
+  }
+
+  private _handleSave(data: unknown): void {
+    vscode.window.showInformationMessage('Data saved!');
+  }
+
+  private _sendData(): void {
+    this.sendMessage('loadData', { items: ['a', 'b', 'c'] });
+  }
+
+  private _getHtml(webview: vscode.Webview): string {
+    const styleUri = webview.asWebviewUri(
+      vscode.Uri.joinPath(this._extensionUri, 'media', 'style.css'),
+    );
+    const scriptUri = webview.asWebviewUri(
+      vscode.Uri.joinPath(this._extensionUri, 'media', 'main.js'),
+    );
+    const nonce = getNonce();
+
+    return /*html*/ `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="Content-Security-Policy"
+    content="default-src 'none';
+      style-src ${webview.cspSource};
+      script-src 'nonce-${nonce}';
+      img-src ${webview.cspSource} https:;
+      font-src ${webview.cspSource};">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link href="${styleUri}" rel="stylesheet">
+  <title>My Panel</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script nonce="${nonce}" src="${scriptUri}"></script>
+</body>
+</html>`;
+  }
+
+  public dispose(): void {
+    this._panel.dispose();
+    while (this._disposables.length) {
+      const d = this._disposables.pop();
+      d?.dispose();
+    }
+  }
+}
+
+function getNonce(): string {
+  let text = '';
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  for (let i = 0; i < 32; i++) {
+    text += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return text;
+}
+```
+
+## Webview Script (media/main.js)
+
+```javascript
+// Inside the webview — communicates with the extension via postMessage
+(function () {
+  // @ts-ignore
+  const vscode = acquireVsCodeApi();
+
+  // Send message TO the extension
+  function save(data) {
+    vscode.postMessage({ command: 'save', data });
+  }
+
+  // Receive messages FROM the extension
+  window.addEventListener('message', (event) => {
+    const message = event.data;
+    switch (message.command) {
+      case 'loadData':
+        renderData(message.data);
+        break;
+    }
+  });
+
+  function renderData(data) {
+    const app = document.getElementById('app');
+    if (app) {
+      app.textContent = JSON.stringify(data, null, 2);
+    }
+  }
+
+  // Request initial data
+  vscode.postMessage({ command: 'requestData' });
+})();
+```

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

@@ -285,3 +285,70 @@ export function deactivate(): void {
   // Disposables in context.subscriptions are auto-disposed
 }
 ```
+
+## Extension Host Runtime
+
+The extension host is a **single Node.js process shared by every extension** in the window. Two consequences shape the code you write:
+
+- **Synchronous file I/O blocks the UI.** Calls like `fs.readFileSync` or `fs.writeFileSync` stall the host event loop, which freezes responses from every extension AND the editor's command handling. Always prefer async APIs:
+  - Node: `import { readFile } from 'node:fs/promises'` — `await readFile(path, 'utf8')`
+  - VS Code abstraction: `await vscode.workspace.fs.readFile(uri)` — works across remote, virtual, and local file systems
+- **CPU-heavy work in the host blocks too.** For long parsing/analysis, move work to a worker thread (`node:worker_threads`) or a language server (LSP), not a tight loop on the host.
+- The Webview runs in a separate process; messaging is async by construction. Don't try to "call" the host synchronously from the webview.
+
+```typescript
+// BAD — blocks the extension host
+import * as fs from 'node:fs';
+const text = fs.readFileSync('/tmp/big-file.txt', 'utf8');
+
+// GOOD — async, yields back to the event loop
+import { readFile } from 'node:fs/promises';
+const text = await readFile('/tmp/big-file.txt', 'utf8');
+
+// GOOD — workspace-aware (preferred when reading user files)
+const uri = vscode.Uri.file('/tmp/big-file.txt');
+const bytes = await vscode.workspace.fs.readFile(uri);
+const text2 = new TextDecoder('utf-8').decode(bytes);
+```
+
+## Workspace Folders (`rootPath` is deprecated)
+
+`vscode.workspace.rootPath` is **deprecated** and returns only the *first* folder in multi-root workspaces, silently dropping the rest. Use `vscode.workspace.workspaceFolders` instead — it returns `readonly WorkspaceFolder[] | undefined`.
+
+```typescript
+// BAD — deprecated, fails silently in multi-root workspaces
+const root = vscode.workspace.rootPath;
+
+// GOOD — iterate all workspace folders
+const folders = vscode.workspace.workspaceFolders;
+if (!folders || folders.length === 0) {
+  vscode.window.showWarningMessage('Open a folder first.');
+  return;
+}
+for (const folder of folders) {
+  // folder.uri.fsPath is the absolute path
+  // folder.name is the display name
+  // folder.index is its position in the list
+}
+
+// GOOD — find the folder that owns a given file
+const fileUri = vscode.window.activeTextEditor?.document.uri;
+if (fileUri) {
+  const owner = vscode.workspace.getWorkspaceFolder(fileUri);
+  // owner is the WorkspaceFolder containing the file, or undefined
+}
+
+// GOOD — react to folders being added or removed
+context.subscriptions.push(
+  vscode.workspace.onDidChangeWorkspaceFolders((event) => {
+    for (const added of event.added) {
+      // ...
+    }
+    for (const removed of event.removed) {
+      // ...
+    }
+  }),
+);
+```
+
+Relative paths in extension code should resolve against a specific `WorkspaceFolder`, never against `process.cwd()` (which is unrelated to the user's workspace).

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

@@ -0,0 +1,179 @@
+# Debugger Extensions (Debug Adapter Protocol)
+
+Add a new debugger by implementing the **Debug Adapter Protocol** (DAP). The debug adapter is a separate process that translates between VS Code's generic debug UI and the language/runtime's actual debugging facilities.
+
+Official guide: https://code.visualstudio.com/api/extension-guides/debugger-extension
+Protocol spec: https://microsoft.github.io/debug-adapter-protocol/
+
+## Three Components
+
+| Component | Job | Where |
+|---|---|---|
+| Debug adapter | Speaks DAP over stdio/socket, drives the underlying debugger | Separate process (any language) |
+| `DebugAdapterDescriptorFactory` | Tells VS Code how to launch the adapter | In the extension |
+| `DebugConfigurationProvider` | Resolves/validates `launch.json` entries | In the extension |
+
+Plus declarations in `package.json` under `contributes.debuggers`.
+
+## package.json Manifest
+
+```json
+"contributes": {
+  "debuggers": [
+    {
+      "type": "mydebug",
+      "label": "My Debugger",
+      "languages": ["mylang"],
+      "configurationAttributes": {
+        "launch": {
+          "required": ["program"],
+          "properties": {
+            "program": {
+              "type": "string",
+              "description": "Path to program to debug"
+            },
+            "stopOnEntry": {
+              "type": "boolean",
+              "default": true
+            }
+          }
+        }
+      },
+      "initialConfigurations": [
+        {
+          "type": "mydebug",
+          "request": "launch",
+          "name": "Launch program",
+          "program": "${workspaceFolder}/main.mylang",
+          "stopOnEntry": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+- `type` is the debugger identifier — referenced in user `launch.json`
+- `configurationAttributes` powers IntelliSense inside `launch.json`
+- `initialConfigurations` is what "Add Configuration" inserts
+
+## Descriptor Factory
+
+Tells VS Code how to start the adapter process for a debug session.
+
+```typescript
+import * as vscode from 'vscode';
+
+class MyDebugAdapterDescriptorFactory
+  implements vscode.DebugAdapterDescriptorFactory {
+
+  createDebugAdapterDescriptor(
+    _session: vscode.DebugSession,
+    _executable: vscode.DebugAdapterExecutable | undefined,
+  ): vscode.ProviderResult<vscode.DebugAdapterDescriptor> {
+    // Option 1: launch a separate Node executable
+    return new vscode.DebugAdapterExecutable('node', [
+      this._extensionPath + '/dist/debug-adapter.js',
+    ]);
+
+    // Option 2: run the adapter inline in the extension host
+    // return new vscode.DebugAdapterInlineImplementation(new MyDebugSession());
+
+    // Option 3: connect to a server on a TCP port (for development)
+    // return new vscode.DebugAdapterServer(4711);
+  }
+
+  constructor(private readonly _extensionPath: string) {}
+}
+
+export function activate(context: vscode.ExtensionContext) {
+  context.subscriptions.push(
+    vscode.debug.registerDebugAdapterDescriptorFactory(
+      'mydebug',
+      new MyDebugAdapterDescriptorFactory(context.extensionPath),
+    ),
+  );
+}
+```
+
+**Choose the right form**:
+
+- `DebugAdapterExecutable` — production. Adapter is a separate Node script.
+- `DebugAdapterInlineImplementation` — testing, or very simple debuggers. Runs in extension host (so it shares the event loop — beware blocking).
+- `DebugAdapterServer` — development convenience. Run the adapter in a debugger yourself, point VS Code at the port.
+
+## Configuration Provider
+
+Resolves user `launch.json` BEFORE the session starts. Useful for filling in defaults, validating, or generating configs dynamically.
+
+```typescript
+class MyDebugConfigurationProvider
+  implements vscode.DebugConfigurationProvider {
+
+  resolveDebugConfiguration(
+    folder: vscode.WorkspaceFolder | undefined,
+    config: vscode.DebugConfiguration,
+    _token?: vscode.CancellationToken,
+  ): vscode.ProviderResult<vscode.DebugConfiguration> {
+    // Called when "Debug" is hit with no launch.json — supply a default
+    if (!config.type && !config.request && !config.name) {
+      const editor = vscode.window.activeTextEditor;
+      if (editor && editor.document.languageId === 'mylang') {
+        config.type = 'mydebug';
+        config.request = 'launch';
+        config.name = 'Launch';
+        config.program = '${file}';
+      }
+    }
+
+    if (!config.program) {
+      return vscode.window
+        .showInformationMessage('Cannot find a program to debug')
+        .then(() => undefined);
+    }
+    return config;
+  }
+}
+
+context.subscriptions.push(
+  vscode.debug.registerDebugConfigurationProvider(
+    'mydebug',
+    new MyDebugConfigurationProvider(),
+  ),
+);
+```
+
+## DAP — What the Adapter Has to Implement
+
+Minimum lifecycle:
+
+| Request | Response | When |
+|---|---|---|
+| `initialize` | capabilities (e.g., `supportsConfigurationDoneRequest`) | Session start |
+| `launch` or `attach` | empty success | After initialize |
+| `setBreakpoints` | array of verified breakpoints | When breakpoints change |
+| `configurationDone` | empty success | After initial setup |
+| `threads` | list of thread ids/names | UI refresh |
+| `stackTrace` | call frames | Thread is stopped |
+| `scopes` | scopes per frame | Frame selected |
+| `variables` | variables in a scope | Scope expanded |
+| `continue` / `next` / `stepIn` / `stepOut` | empty success | User clicks step button |
+| `disconnect` | empty success | Session ends |
+
+Events the adapter must SEND to the UI:
+
+- `initialized` (after responding to `initialize`)
+- `stopped` (with reason: `breakpoint`, `step`, `exception`, etc.)
+- `terminated` (debugging finished)
+- `output` (console output for the Debug Console)
+- `thread` (thread started/exited)
+
+Use the `vscode-debugadapter` npm package to handle the protocol plumbing — implement just the verbs you support.
+
+## Anti-Patterns
+
+- ❌ Sending `stopped` without a previous `initialized` event — UI shows nothing
+- ❌ Returning ad-hoc thread/frame ids — must be stable integers within the session
+- ❌ Sending `output` events without a `category` (`stdout` | `stderr` | `console` | `important`)
+- ❌ Long-running synchronous work in `DebugAdapterInlineImplementation` — blocks the extension host
+- ❌ Forgetting to send `terminated` — session never closes and "Stop" hangs