@maccesar/aiskills 1.7.0

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

@@ -0,0 +1,287 @@
+# Extension Architecture
+
+Layered architecture, project structure, and testing strategy for VS Code extensions.
+
+## Directory Structure
+
+```
+my-extension/
+├── .vscode/
+│   ├── extensions.json        # Recommended extensions for contributors
+│   ├── launch.json            # Debug configurations
+│   ├── settings.json          # Workspace settings
+│   └── tasks.json             # Build tasks
+├── src/
+│   ├── extension.ts           # Entry point: activate() and deactivate()
+│   ├── commands/              # Command handlers
+│   │   ├── index.ts           # Re-exports all commands
+│   │   └── runAnalysis.ts     # Individual command
+│   ├── providers/             # VS Code API providers
+│   │   ├── treeProvider.ts    # TreeDataProvider
+│   │   ├── webviewProvider.ts # Webview panel manager
+│   │   └── contentProvider.ts # TextDocumentContentProvider
+│   ├── services/              # Business logic (no vscode imports)
+│   │   ├── apiClient.ts       # External API communication
+│   │   └── dataProcessor.ts   # Data transformation
+│   ├── models/                # TypeScript interfaces and types
+│   │   └── types.ts
+│   └── utils/                 # Shared utilities
+│       └── logger.ts
+├── media/                     # Webview assets
+│   ├── style.css
+│   └── main.js
+├── resources/                 # Icons and images
+│   ├── dark/
+│   │   └── icon.svg
+│   └── light/
+│       └── icon.svg
+├── test/
+│   ├── unit/                  # Unit tests (no VS Code dependency)
+│   │   └── dataProcessor.test.ts
+│   └── integration/           # Integration tests (require VS Code)
+│       └── extension.test.ts
+├── .vscodeignore              # Files to exclude from VSIX package
+├── esbuild.js                 # Bundler configuration
+├── package.json
+├── tsconfig.json
+├── CHANGELOG.md
+└── README.md
+```
+
+## Layered Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│             VS Code Layer                    │
+│  extension.ts, commands/, providers/         │
+│  Imports from 'vscode'. Registers commands,  │
+│  creates UI, manages disposables.            │
+├─────────────────────────────────────────────┤
+│          Business Logic Layer                │
+│  services/                                   │
+│  Pure TypeScript. NO 'vscode' imports.       │
+│  Testable without VS Code runtime.           │
+├─────────────────────────────────────────────┤
+│            Data / API Layer                  │
+│  services/apiClient.ts, models/              │
+│  HTTP clients, data models, storage.         │
+│  Also pure TypeScript.                       │
+└─────────────────────────────────────────────┘
+```
+
+### Why This Layering Matters
+
+- **Business logic** in `services/` has zero `vscode` imports — it can be unit tested with plain Mocha/Jest, no Extension Host needed
+- **VS Code layer** is thin — it wires providers/commands to services
+- **Data layer** is injectable — swap real API for mock in tests
+
+### Example: Keeping Layers Separate
+
+```typescript
+// services/dataProcessor.ts — NO vscode imports
+export interface ProcessResult {
+  total: number;
+  errors: string[];
+}
+
+export function processData(items: string[]): ProcessResult {
+  const errors: string[] = [];
+  for (const item of items) {
+    if (!item.trim()) {
+      errors.push('Empty item found');
+    }
+  }
+  return { total: items.length, errors };
+}
+```
+
+```typescript
+// commands/runAnalysis.ts — thin VS Code wrapper
+import * as vscode from 'vscode';
+import { processData } from '../services/dataProcessor';
+
+export async function runAnalysis(): Promise<void> {
+  const editor = vscode.window.activeTextEditor;
+  if (!editor) {
+    vscode.window.showWarningMessage('No active editor');
+    return;
+  }
+
+  const text = editor.document.getText();
+  const lines = text.split('\n');
+  const result = processData(lines);
+
+  if (result.errors.length > 0) {
+    vscode.window.showWarningMessage(`Found ${result.errors.length} issues`);
+  } else {
+    vscode.window.showInformationMessage(`Processed ${result.total} lines`);
+  }
+}
+```
+
+## Debug Configuration
+
+`.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "preLaunchTask": "npm: compile"
+    },
+    {
+      "name": "Extension Tests",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}",
+        "--extensionTestsPath=${workspaceFolder}/out/test/integration"
+      ],
+      "outFiles": ["${workspaceFolder}/out/**/*.js"],
+      "preLaunchTask": "npm: compile"
+    }
+  ]
+}
+```
+
+## Testing Strategy
+
+### Unit Tests (Business Logic)
+
+Test `services/` with plain Mocha — no VS Code runtime needed.
+
+```typescript
+// test/unit/dataProcessor.test.ts
+import * as assert from 'assert';
+import { processData } from '../../src/services/dataProcessor';
+
+suite('dataProcessor', () => {
+  test('counts items correctly', () => {
+    const result = processData(['a', 'b', 'c']);
+    assert.strictEqual(result.total, 3);
+    assert.strictEqual(result.errors.length, 0);
+  });
+
+  test('reports empty items', () => {
+    const result = processData(['a', '', 'c']);
+    assert.strictEqual(result.errors.length, 1);
+  });
+
+  test('handles empty input', () => {
+    const result = processData([]);
+    assert.strictEqual(result.total, 0);
+  });
+});
+```
+
+### Integration Tests (VS Code API)
+
+Test commands, providers, and UI interactions with `@vscode/test-electron`.
+
+```typescript
+// test/integration/extension.test.ts
+import * as assert from 'assert';
+import * as vscode from 'vscode';
+
+suite('Extension Integration', () => {
+  suiteSetup(async () => {
+    // Wait for extension to activate
+    const ext = vscode.extensions.getExtension('publisher.my-extension');
+    await ext?.activate();
+  });
+
+  test('extension activates', () => {
+    const ext = vscode.extensions.getExtension('publisher.my-extension');
+    assert.ok(ext?.isActive);
+  });
+
+  test('command registers successfully', async () => {
+    const commands = await vscode.commands.getCommands(true);
+    assert.ok(commands.includes('myExt.run'));
+  });
+
+  test('command executes without error', async () => {
+    // Open a test document first
+    const doc = await vscode.workspace.openTextDocument({
+      content: 'line1\nline2\nline3',
+      language: 'plaintext',
+    });
+    await vscode.window.showTextDocument(doc);
+
+    // Execute command — should not throw
+    await vscode.commands.executeCommand('myExt.run');
+  });
+});
+```
+
+### Test Runner Configuration
+
+`.vscode-test.mjs`:
+
+```javascript
+import { defineConfig } from '@vscode/test-cli';
+
+export default defineConfig({
+  files: 'out/test/integration/**/*.test.js',
+  mocha: {
+    timeout: 20000,
+    ui: 'tdd',
+  },
+});
+```
+
+`tsconfig.json` for tests (if separate):
+
+```json
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "outDir": "out",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}
+```
+
+## Extension Entry Point Pattern
+
+```typescript
+// src/extension.ts
+import * as vscode from 'vscode';
+import { runAnalysis } from './commands/runAnalysis';
+import { MyTreeProvider } from './providers/treeProvider';
+
+export function activate(context: vscode.ExtensionContext) {
+  const output = vscode.window.createOutputChannel('My Extension', { log: true });
+  output.info('Activating...');
+
+  // Initialize providers
+  const treeProvider = new MyTreeProvider();
+
+  // Register everything and push to subscriptions
+  context.subscriptions.push(
+    output,
+    vscode.window.createTreeView('myTreeView', { treeDataProvider: treeProvider }),
+    vscode.commands.registerCommand('myExt.run', runAnalysis),
+    vscode.commands.registerCommand('myExt.refresh', () => treeProvider.refresh()),
+  );
+
+  output.info('Activated');
+}
+
+export function deactivate(): void {
+  // Only for async cleanup (network connections, child processes)
+  // Disposables in context.subscriptions are auto-disposed
+}
+```

package/skills/vscode-extension-dev/references/package-json-schema.md

@@ -0,0 +1,345 @@
+# package.json Schema Reference
+
+Complete reference for VS Code extension `package.json` configuration.
+
+## Minimal Valid Extension
+
+```json
+{
+  "name": "my-extension",
+  "displayName": "My Extension",
+  "description": "What it does",
+  "version": "0.0.1",
+  "publisher": "your-publisher-id",
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": ["Other"],
+  "main": "./dist/extension.js",
+  "activationEvents": [],
+  "contributes": {
+    "commands": [
+      {
+        "command": "myExtension.helloWorld",
+        "title": "Hello World",
+        "category": "My Extension"
+      }
+    ]
+  }
+}
+```
+
+## engines.vscode
+
+Specifies the minimum VS Code version your extension supports.
+
+```json
+"engines": {
+  "vscode": "^1.85.0"
+}
+```
+
+- Use `^` prefix for "this version or newer"
+- Check API availability at https://code.visualstudio.com/api/references/vscode-api
+- Common milestones: 1.74 (implicit activation), 1.82 (SecretStorage improvements)
+
+## activationEvents
+
+Controls **when** your extension loads. Less is better — lazy activation improves startup.
+
+```json
+"activationEvents": [
+  "onLanguage:python",
+  "onCommand:myExtension.doSomething",
+  "onView:myTreeView",
+  "onUri",
+  "onFileSystem:myScheme",
+  "onWebviewPanel:myPanel",
+  "workspaceContains:**/tsconfig.json",
+  "onStartupFinished",
+  "*"
+]
+```
+
+### Implicit Activation (VS Code 1.74+)
+Commands declared in `contributes.commands` **automatically** generate `onCommand:` activation events. You do NOT need to list them in `activationEvents`.
+
+```json
+// This is enough — no activationEvents entry needed for this command
+"contributes": {
+  "commands": [
+    { "command": "myExt.run", "title": "Run" }
+  ]
+}
+```
+
+### Event Reference
+
+| Event                        | Fires when                                  |
+| ---------------------------- | ------------------------------------------- |
+| `onLanguage:langId`          | File of that language is opened             |
+| `onCommand:commandId`        | Command is invoked (implicit since 1.74)    |
+| `onView:viewId`              | TreeView with that ID is expanded           |
+| `onUri`                      | Extension URI is opened (deep linking)      |
+| `onFileSystem:scheme`        | File from that scheme is read               |
+| `onWebviewPanel:type`        | Webview panel of that type is restored      |
+| `workspaceContains:pattern`  | Workspace contains matching file            |
+| `onStartupFinished`          | VS Code has fully started                   |
+| `*`                          | On VS Code start — **avoid in production**  |
+
+## contributes
+
+### commands
+
+```json
+"contributes": {
+  "commands": [
+    {
+      "command": "myExt.refresh",
+      "title": "Refresh",
+      "category": "My Extension",
+      "icon": {
+        "light": "resources/light/refresh.svg",
+        "dark": "resources/dark/refresh.svg"
+      },
+      "enablement": "myExt.isConnected"
+    }
+  ]
+}
+```
+
+- `category` groups commands in the Command Palette: "My Extension: Refresh"
+- `icon` is used when the command appears in menus/toolbars
+- `enablement` uses when-clause context for conditional availability
+
+### menus
+
+```json
+"contributes": {
+  "menus": {
+    "view/title": [
+      {
+        "command": "myExt.refresh",
+        "when": "view == myTreeView",
+        "group": "navigation"
+      }
+    ],
+    "view/item/context": [
+      {
+        "command": "myExt.deleteItem",
+        "when": "view == myTreeView && viewItem == deletable",
+        "group": "inline"
+      }
+    ],
+    "editor/context": [
+      {
+        "command": "myExt.formatSelection",
+        "when": "editorHasSelection",
+        "group": "1_modification"
+      }
+    ],
+    "commandPalette": [
+      {
+        "command": "myExt.deleteItem",
+        "when": "false"
+      }
+    ]
+  }
+}
+```
+
+### Menu locations
+
+| Location              | Where it appears                        |
+| --------------------- | --------------------------------------- |
+| `commandPalette`      | Command Palette (Ctrl+Shift+P)          |
+| `editor/context`      | Editor right-click menu                 |
+| `editor/title`        | Editor title bar                        |
+| `view/title`          | View title bar (tree view header)       |
+| `view/item/context`   | Tree view item right-click              |
+| `explorer/context`    | File explorer right-click               |
+| `scm/title`           | Source control title bar                |
+
+### keybindings
+
+```json
+"contributes": {
+  "keybindings": [
+    {
+      "command": "myExt.run",
+      "key": "ctrl+shift+r",
+      "mac": "cmd+shift+r",
+      "when": "editorTextFocus && editorLangId == typescript"
+    }
+  ]
+}
+```
+
+### configuration
+
+```json
+"contributes": {
+  "configuration": {
+    "title": "My Extension",
+    "properties": {
+      "myExt.apiUrl": {
+        "type": "string",
+        "default": "https://api.example.com",
+        "description": "API endpoint URL",
+        "format": "uri"
+      },
+      "myExt.maxResults": {
+        "type": "number",
+        "default": 50,
+        "minimum": 1,
+        "maximum": 500,
+        "description": "Maximum number of results to display"
+      },
+      "myExt.logLevel": {
+        "type": "string",
+        "default": "info",
+        "enum": ["debug", "info", "warn", "error"],
+        "enumDescriptions": [
+          "Verbose debug logging",
+          "Standard information",
+          "Warnings only",
+          "Errors only"
+        ],
+        "description": "Logging verbosity level"
+      },
+      "myExt.features.autoRefresh": {
+        "type": "boolean",
+        "default": true,
+        "description": "Automatically refresh data on file save"
+      }
+    }
+  }
+}
+```
+
+Reading configuration in TypeScript:
+
+```typescript
+const config = vscode.workspace.getConfiguration('myExt');
+const apiUrl = config.get<string>('apiUrl', 'https://api.example.com');
+const maxResults = config.get<number>('maxResults', 50);
+
+// Listen for changes
+vscode.workspace.onDidChangeConfiguration(e => {
+  if (e.affectsConfiguration('myExt.apiUrl')) {
+    // Re-initialize API client
+  }
+});
+```
+
+### views and viewsContainers
+
+```json
+"contributes": {
+  "viewsContainers": {
+    "activitybar": [
+      {
+        "id": "myExtExplorer",
+        "title": "My Extension",
+        "icon": "resources/icon.svg"
+      }
+    ]
+  },
+  "views": {
+    "myExtExplorer": [
+      {
+        "id": "myTreeView",
+        "name": "Items",
+        "icon": "resources/items.svg",
+        "contextualTitle": "My Extension Items"
+      },
+      {
+        "id": "myFavoritesView",
+        "name": "Favorites",
+        "visibility": "collapsed"
+      }
+    ]
+  },
+  "viewsWelcome": [
+    {
+      "view": "myTreeView",
+      "contents": "No items found.\n[Add Item](command:myExt.addItem)"
+    }
+  ]
+}
+```
+
+## scripts (esbuild)
+
+```json
+"scripts": {
+  "vscode:prepublish": "npm run package",
+  "compile": "npm run check-types && node esbuild.js",
+  "check-types": "tsc --noEmit",
+  "watch": "node esbuild.js --watch",
+  "package": "npm run check-types && node esbuild.js --production",
+  "lint": "eslint src",
+  "test": "vscode-test",
+  "deploy": "vsce publish"
+}
+```
+
+### esbuild.js
+
+```javascript
+const esbuild = require('esbuild');
+
+const production = process.argv.includes('--production');
+const watch = process.argv.includes('--watch');
+
+async function main() {
+  const ctx = await esbuild.context({
+    entryPoints: ['src/extension.ts'],
+    bundle: true,
+    format: 'cjs',
+    minify: production,
+    sourcemap: !production,
+    sourcesContent: false,
+    platform: 'node',
+    outfile: 'dist/extension.js',
+    external: ['vscode'],
+    logLevel: 'silent',
+    plugins: [
+      /* add esbuild problem matcher plugin if needed */
+    ],
+  });
+
+  if (watch) {
+    await ctx.watch();
+  } else {
+    await ctx.rebuild();
+    await ctx.dispose();
+  }
+}
+
+main().catch(e => {
+  console.error(e);
+  process.exit(1);
+});
+```
+
+## devDependencies
+
+```json
+"devDependencies": {
+  "@types/vscode": "^1.85.0",
+  "@types/mocha": "^10.0.6",
+  "@types/node": "20.x",
+  "@vscode/test-cli": "^0.0.6",
+  "@vscode/test-electron": "^2.3.8",
+  "esbuild": "^0.20.0",
+  "eslint": "^8.56.0",
+  "@typescript-eslint/eslint-plugin": "^7.0.0",
+  "@typescript-eslint/parser": "^7.0.0",
+  "typescript": "^5.3.0"
+}
+```
+
+- `@types/vscode` version must match your `engines.vscode` range
+- `@vscode/test-cli` provides the `vscode-test` command
+- `@vscode/test-electron` downloads and launches VS Code for integration tests