# DETAILED.md — pi-engineering-services detailed notes

> Concise overview lives in [README.md](./README.md); this file holds the details.
> 中文详细说明见 [DETAILED.zh-CN.md](./DETAILED.zh-CN.md).

## 1. Structure

```
pi-engineering-services/
├── lsp/                      @narumitw/pi-lsp fork (src/ + LICENSE + README)
├── dap/                      @piex-dev/dap fork
│   ├── extensions/           DAP client/session/config (defaults.json: 17 adapter entries)
│   ├── js-debug/             vendored vscode-js-debug runtime (dapDebugServer.js, CJS)
│   ├── debugpy/              debugpy config / version pin / health check (runtime NOT vendored)
│   └── MAINTENANCE-NOTES.md  all changes, gotchas, verification records (Chinese)
├── task/                     task toolchain (task/discovery/runner/non-interactive-env)
├── skills/ide-three-pillars/ usage guide skill (Chinese)
├── README.md / README.zh-CN.md
├── DETAILED.md / DETAILED.zh-CN.md
└── THIRD-PARTY-NOTICES.md    upstream sources & licenses
```

Layout principle: **group by pillar (lsp/dap/task), not by language** — the shared
client/session/config system is language-agnostic; per-language differences are just
config entries (`adapters.ts` / `defaults.json`). Only **runtime assets** that need
isolation get their own directory (`js-debug/`, `debugpy/`).

## 2. Tested vs configured

| Pillar | Verified | Configured, not verified |
|---|---|---|
| LSP | pyright (Python), tsserver (TS/JS) | rust-analyzer (diagnostics + declaration hover OK; call-site navigation gap) |
| DAP | **debugpy** (Python), **js-debug** (JS/TS): launch/attach/breakpoints/step/evaluate/terminate | gdb, lldb-dap, codelldb, dlv, netcoredbg, kotlin-debug-adapter, rdbg, php-debug-adapter, bash-debug-adapter, dart/flutter, elixir-ls-debugger |
| Task | npm scripts / Makefile / justfile | — |

Unverified adapters use standard VSCode defaults — **treat as experimental**.
LSP catches type/regression errors and navigation; it does **not** catch logic bugs
(runtime/data-flow problems need real-session probing).

## 3. Runtime notes

- **debugpy is not vendored** (pip-installable, 33MB native, needs an interpreter).
  `dap/debugpy/` only holds config, version pin (`requirements.txt`: `debugpy==1.8.21`),
  and a health check (`verify.mjs`).
- **Python must be 3.13**: debugpy 1.8.21 is deeply incompatible with 3.14
  ([#1893](https://github.com/microsoft/debugpy/issues/1893)) — `stopOnEntry` never fires
  `stopped`. `defaults.json` uses `${env:PI_DEBUGPY_PYTHON|python3.13}` to locate the
  interpreter: set `PI_DEBUGPY_PYTHON` to your 3.13 interpreter, or have `python3.13` on PATH.
- **js-debug is vendored** (not on npm), a CommonJS runtime isolated from the ESM package
  root by its own `package.json` `{"type":"commonjs"}`.
- The js-debug `dapDebugServer.js` path in `defaults.json` is package-relative; `resolveAdapter`
  resolves it against the config directory, so it works from any checkout.

## 4. Usage policy

`~/.pi/agent/APPEND_SYSTEM.md` (official APPEND_SYSTEM mechanism — appended to the system
prompt at startup):

```
# IDE tool usage policy (auto-applied)
- After editing .ts/.js/.py → lsp_diagnostics (expect 0 new errors)
- On crash / error / step-through need → debug
- For build/test/lint → task list → task run
- Key: debug actions serial; debugpy uses Python 3.13
- Details: skill ide-three-pillars
```

The `ide-three-pillars` skill (loaded on demand) covers the "how": per-tool gotchas,
boundaries, self-debug recipe.

## 5. Verify

```bash
npm run check                        # tsc --noEmit (lsp+dap+task)
PI_DEBUGPY_PYTHON=<python3.13> bun dap/debugpy/verify.mjs   # debugpy health check
```

## 6. Development

- pi auto-loads local extensions from `~/.pi/agent/extensions/<name>/` (or via `pi install`);
  source edits take effect after a reload.
- `node_modules` is only for local tsc to resolve peerDependencies (gitignored, not committed).
- After editing → `npm run check` + `lsp_diagnostics` (dogfood) → reload pi for a real-session regression.
- DAP self-debug recipe: `dap/MAINTENANCE-NOTES.md` §4.5.

## 7. Upstream & license

MIT. Upstream sources and their license texts: [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md) —
`@narumitw/pi-lsp`, `@piex-dev/dap`, `vscode-js-debug`, `vscode-workspace-tasks`, `debugpy`.