vscode skill

2026-06-19 16:56:45 -05:00
parent 45d8beda8a
commit 75b0c8d192
9 changed files with 434 additions and 1 deletions
@@ -0,0 +1,101 @@
+# Debug Launch Configurations in VS Code
+
+This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`.
+
+## Core Structure
+
+A minimal launch file:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": []
+}
+```
+
+Useful fields for Python configs:
+
+- `type`: Use `debugpy`.
+- `request`: Usually `launch`, sometimes `attach`.
+- `name`: Friendly profile name shown in the Run and Debug panel.
+- `program`: Script path for script-based entry.
+- `module`: Module name for `python -m ...` style launches.
+- `args`: CLI arguments.
+- `cwd`: Working directory.
+- `env` / `envFile`: Environment variables.
+- `console`: `integratedTerminal` is usually most practical.
+- `justMyCode`: `true` by default; set `false` when stepping into dependencies.
+
+## Launch vs Attach
+
+Use `launch` when VS Code should start the process.
+Use `attach` when the process already runs with debugpy listening.
+
+Attach profile example:
+
+```json
+{
+  "name": "Python: Attach (debugpy :5678)",
+  "type": "debugpy",
+  "request": "attach",
+  "connect": {
+    "host": "127.0.0.1",
+    "port": 5678
+  },
+  "justMyCode": true
+}
+```
+
+Remote process side command example:
+
+```bash
+python -m debugpy --listen 5678 -m your_package.main
+```
+
+## Script and Module Patterns
+
+Script pattern:
+
+```json
+{
+  "name": "Python: Script",
+  "type": "debugpy",
+  "request": "launch",
+  "program": "${workspaceFolder}/src/app.py",
+  "cwd": "${workspaceFolder}",
+  "console": "integratedTerminal",
+  "justMyCode": true
+}
+```
+
+Module pattern:
+
+```json
+{
+  "name": "Python: Module",
+  "type": "debugpy",
+  "request": "launch",
+  "module": "your_package.main",
+  "cwd": "${workspaceFolder}",
+  "console": "integratedTerminal",
+  "justMyCode": true
+}
+```
+
+Prefer module mode when imports depend on package layout.
+
+## Environment and Interpreter Notes
+
+- Use `envFile` for shared local variables, commonly `${workspaceFolder}/.env`.
+- Keep secrets out of committed launch configs.
+- Ensure the selected VS Code interpreter matches project tooling.
+
+## Troubleshooting
+
+If breakpoints do not hit:
+
+1. Confirm the right profile is selected.
+2. Confirm the file path/module path is correct.
+3. Disable `justMyCode` temporarily to inspect call flow.
+4. Confirm no stale background process is occupying the expected port.
+5. Confirm workspace root and `cwd` align with imports.
@@ -0,0 +1,98 @@
+# FastAPI Debug Launch with debugpy
+
+This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn.
+
+## Launch FastAPI via Module
+
+Preferred profile:
+
+```json
+{
+  "name": "FastAPI: Uvicorn (debug)",
+  "type": "debugpy",
+  "request": "launch",
+  "module": "uvicorn",
+  "args": [
+    "your_package.main:app",
+    "--host",
+    "127.0.0.1",
+    "--port",
+    "8000",
+    "--reload",
+    "--log-level",
+    "debug"
+  ],
+  "cwd": "${workspaceFolder}",
+  "envFile": "${workspaceFolder}/.env",
+  "console": "integratedTerminal",
+  "justMyCode": true,
+  "jinja": true
+}
+```
+
+Why module mode: it matches `python -m uvicorn ...` behavior and avoids path ambiguity.
+
+## Launch with Factory Pattern
+
+If app is created via factory function:
+
+```json
+{
+  "name": "FastAPI: Uvicorn factory (debug)",
+  "type": "debugpy",
+  "request": "launch",
+  "module": "uvicorn",
+  "args": [
+    "your_package.main:create_app",
+    "--factory",
+    "--host",
+    "127.0.0.1",
+    "--port",
+    "8000",
+    "--reload"
+  ],
+  "cwd": "${workspaceFolder}",
+  "console": "integratedTerminal",
+  "justMyCode": true
+}
+```
+
+## Attach to an Existing FastAPI Process
+
+If the app is launched externally, start with debugpy:
+
+```bash
+python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload
+```
+
+Attach profile:
+
+```json
+{
+  "name": "FastAPI: Attach (5678)",
+  "type": "debugpy",
+  "request": "attach",
+  "connect": {
+    "host": "127.0.0.1",
+    "port": 5678
+  },
+  "justMyCode": true
+}
+```
+
+## Common FastAPI Debug Pitfalls
+
+1. Wrong import target in `your_package.main:app` or factory symbol.
+2. `cwd` does not match source layout.
+3. Auto-reload creating confusion about active process when breakpoints are set in startup code.
+4. Port collisions from old uvicorn processes.
+5. Environment variables not loaded because `envFile` path is wrong.
+
+## Practical Quality Gate
+
+A profile is considered valid when:
+
+1. Server starts from VS Code Run and Debug.
+2. A breakpoint inside an endpoint is hit on request.
+3. A breakpoint in startup/lifespan logic is hit at app boot.
+4. Terminal output appears in integrated terminal with expected log level.
@@ -0,0 +1,92 @@
+# Configure Project Tasks in tasks.json
+
+Use `.vscode/tasks.json` to define repeatable project commands and optional hooks for debugging.
+
+## Minimal File
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": []
+}
+```
+
+## Task Fields You Will Use Most
+
+- `label`: Task name shown in VS Code.
+- `type`: Usually `shell`.
+- `command`: Executable to run.
+- `args`: Command arguments.
+- `options.cwd`: Working directory.
+- `group`: Mark default build or test tasks.
+- `problemMatcher`: Parse errors into the Problems panel.
+- `isBackground`: `true` for long-running tasks (for example dev server watch).
+
+## Python Project Example
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "App: Run",
+      "type": "shell",
+      "command": "uv",
+      "args": ["run", "uvicorn", "personal_mcp.main:app", "--host", "127.0.0.1", "--port", "8000", "--reload"],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Tests: Pytest",
+      "type": "shell",
+      "command": "uv",
+      "args": ["run", "pytest"],
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "group": "test",
+      "problemMatcher": []
+    }
+  ]
+}
+```
+
+## Connect Tasks to Debug Profiles
+
+In `launch.json`, you can run a task first:
+
+```json
+{
+  "name": "FastAPI: Attach",
+  "type": "debugpy",
+  "request": "attach",
+  "connect": {
+    "host": "127.0.0.1",
+    "port": 5678
+  },
+  "preLaunchTask": "App: Run"
+}
+```
+
+Use this only when startup sequencing is needed.
+
+## Task Design Guidelines
+
+1. Keep labels stable and descriptive.
+2. Prefer one task per intent instead of monolithic shell commands.
+3. Keep shell portability in mind if teammates use multiple OSes.
+4. Avoid embedding secrets directly in task definitions.
+5. Mark long-running tasks with `isBackground` and keep matchers explicit.
+
+## Troubleshooting
+
+If a task fails unexpectedly:
+
+1. Run the underlying command directly in terminal.
+2. Confirm `options.cwd` points to expected workspace root.
+3. Confirm tool availability in environment path.
+4. Confirm quoting and argument boundaries in `args`.
+5. Confirm the task is not blocked by an outdated background process.