better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/debugging.md

@@ -0,0 +1,254 @@
+<!--
+source: https://omp.sh/docs/debugging
+fetched: 2026-09-06
+-->
+
+# Debugging
+
+> Let omp pause a real program, inspect its live state, and explain why it behaves differently from what the source suggests.
+
+## Debug a program with omp
+
+Use the debugger when the answer depends on runtime state: a value changes unexpectedly, a branch is taken only for one input, a process hangs, or several threads interact badly. omp speaks the Debug Adapter Protocol (DAP), so it can launch or attach to a program, stop it, inspect frames and variables, step, and evaluate expressions through a language-specific debug adapter.
+
+The smallest useful workflow is:
+
+1. Install the adapter for the language and make its executable available to omp.
+2. Start `omp` in the project directory.
+3. Describe the program, the stop point, and the question in normal language.
+
+For example, after installing debugpy with `uv add --dev debugpy`:
+
+```text
+Debug etl/transform.py with sample.csv. Break on line 58 when i == 3,
+inspect the locals and running total, and explain where the bad value enters.
+```
+
+omp selects debugpy from the `.py` target and Python project markers, launches the script, and drives the stopped process. You do not need to translate the request into DAP operations or manage frame identifiers yourself.
+
+For questions that only require reading definitions, references, or types, use [code intelligence](/docs/code-intelligence) instead. Debugging executes or attaches to real code and can change the target's state.
+
+## What works automatically
+
+Debugger support is enabled by default. Confirm the setting from a shell with:
+
+```sh
+omp config get debug.enabled
+```
+
+For a launch, omp considers only installed adapters, then ranks them using the target's file extension and nearby project markers such as `pyproject.toml`, `go.mod`, `Cargo.toml`, `package.json`, and `CMakeLists.txt`. For an extensionless native executable it prefers GDB, then LLDB. An adapter named in your request overrides automatic selection.
+
+Most built-in launch configurations stop at program entry. That gives omp a chance to install the breakpoints you requested before it resumes execution. Go is also able to use a package directory as the target; other adapters normally require a file or executable path.
+
+Attaching is less self-describing than launching. Include the adapter when there could be ambiguity, along with either a process ID or the host and port exposed by the target.
+
+## Install an adapter
+
+Install at least one adapter appropriate for the target. omp includes configuration for the following common choices; the adapter itself is a separate program.
+
+| Target | Built-in adapter name | What omp expects |
+| --- | --- | --- |
+| C, C++, Rust | `gdb` | A GDB build with DAP support, available as `gdb` |
+| C, C++, Objective-C, Swift, Rust, Zig | `lldb-dap` | `lldb-dap` on `PATH` |
+| C, C++, Rust, Zig | `codelldb` | `codelldb` on `PATH` |
+| Python | `debugpy` | `python` on `PATH` and `uv add --dev debugpy` in that interpreter |
+| Go | `dlv` | `go install github.com/go-delve/delve/cmd/dlv@latest` and `$GOBIN` (or `~/go/bin`) on `PATH` |
+| Ruby | `rdbg` | `gem install debug` and `rdbg` on `PATH` |
+| JavaScript and TypeScript on Node | `js-debug-adapter` | vscode-js-debug's `dapDebugServer.js`; see below |
+| .NET | `netcoredbg` | `netcoredbg` on `PATH` |
+| Kotlin | `kotlin-debug-adapter` | `kotlin-debug-adapter` on `PATH` |
+| PHP | `php-debug-adapter` | `php-debug-adapter` on `PATH` |
+| Bash | `bash-debug-adapter` | `bash-debug-adapter`, `bash`, and `bashdb` on `PATH` |
+| Dart / Flutter | `dart-debug-adapter` / `flutter-debug-adapter` | The Dart SDK's `dart debug_adapter` command |
+| Elixir | `elixir-ls-debugger` | `elixir-ls-debugger` on `PATH` |
+
+Installation is platform-specific for adapters without a command in the table. After installing one, verify that the process which starts omp can resolve it, for example:
+
+```sh
+command -v dlv
+command -v lldb-dap
+```
+
+### JavaScript and TypeScript
+
+`js-debug-adapter` is omp's adapter name, **not an npm package**. Do not run `npm install -g js-debug-adapter`.
+
+Download a `js-debug-dap-*.tar.gz` archive from the [vscode-js-debug releases](https://github.com/microsoft/vscode-js-debug/releases) and extract it so the server is located here:
+
+```text
+~/.local/opt/js-debug/src/dapDebugServer.js
+```
+
+That path is discovered automatically. A Neovim Mason installation is also discovered at `$XDG_DATA_HOME/nvim/mason/packages/js-debug-adapter/js-debug/src/dapDebugServer.js` (normally under `~/.local/share`). For any other location, export the path before starting omp:
+
+```sh
+export JS_DEBUG_DAP_SERVER=/absolute/path/to/js-debug/src/dapDebugServer.js
+omp
+```
+
+omp runs the server with `node` when available and otherwise uses its Bun host.
+
+## Configure an adapter
+
+You usually do not need a DAP config file. Add one when an adapter is installed outside `PATH`, its built-in defaults do not match the project, or you are adding an adapter that omp does not know yet.
+
+Use `.omp/dap.json` for project-specific configuration or `~/.omp/agent/dap.json` for a personal default. A `dap.json` in the directory where omp starts has higher precedence than `.omp/dap.json`. The equivalent `.dap.json`, `dap.yaml`, `.dap.yaml`, `dap.yml`, and `.dap.yml` names are also accepted. Adapter maps from all applicable files are merged; workspace files override user and plugin defaults.
+
+### Override a built-in adapter
+
+Overrides are merged with the built-in entry, so only specify what changes. This project-level file makes omp use the project's Python environment while preserving debugpy's file extensions and root markers:
+
+```json
+{
+  "adapters": {
+    "debugpy": {
+      "command": ".venv/bin/python",
+      "launchDefaults": {
+        "justMyCode": true,
+        "stopOnEntry": true
+      }
+    }
+  }
+}
+```
+
+Relative commands such as `.venv/bin/python` are resolved from the debug working directory. On Windows, use the interpreter path appropriate to the environment.
+
+### Add a custom adapter
+
+A custom adapter needs a command and enough matching information for automatic selection:
+
+```json
+{
+  "adapters": {
+    "acme-jvm": {
+      "command": "./tools/acme-debug-adapter",
+      "args": ["--stdio"],
+      "languages": ["java", "kotlin"],
+      "fileTypes": [".java", ".kt", ".kts"],
+      "rootMarkers": ["pom.xml", "build.gradle", "build.gradle.kts"],
+      "launchDefaults": {
+        "request": "launch",
+        "stopOnEntry": true,
+        "projectRoot": "."
+      },
+      "attachDefaults": {
+        "request": "attach",
+        "host": "127.0.0.1"
+      }
+    }
+  }
+}
+```
+
+`launchDefaults` and `attachDefaults` are adapter-specific DAP arguments. They are the right place for settings that cannot be inferred from a prompt, such as a JVM main class, source maps, `justMyCode`, or an adapter-specific attach mode. At runtime, the program path, working directory, program arguments, PID, host, and port from your request take precedence over these defaults.
+
+## Ask omp to launch or attach
+
+Give omp concrete paths and describe the evidence you want. A launch target is a path, not a shell command; ask omp to build the target first if necessary.
+
+```text
+Launch build/server with --config test/fixtures/dev.toml. Stop in parseConfig,
+then show me the arguments and the first caller that supplied an empty path.
+```
+
+```text
+Debug the Go package in ./cmd/worker. Break when retryCount reaches 5 and
+compare the current job with the previous stack frame.
+```
+
+```text
+Use lldb-dap to launch ./build/repro with arguments --seed 417. Stop at main,
+then continue until decode_packet and inspect the packet header.
+```
+
+To attach to a local process, include its PID:
+
+```text
+Attach lldb-dap to PID 48120. Pause it, show all threads, and identify which
+thread is holding the process in shutdown.
+```
+
+For a debug server, include both endpoint and adapter:
+
+```text
+Use debugpy to attach to 127.0.0.1:5678. When the request handler is reached,
+inspect request.user and explain why authorization fails.
+```
+
+Only one root debug session can be active in an omp session. Ask omp to end the current debug session before launching or attaching to a different target.
+
+## What you see while stopped
+
+Debug activity appears in the transcript as `Debug` blocks. After a successful launch or attach, the block identifies the selected adapter, status, working directory, and program. When execution stops, it also shows the stop reason, current frame, and source location, for example:
+
+```text
+Adapter: debugpy
+Status: stopped
+Stop reason: breakpoint
+Frame: transform_row
+Location: /workspace/etl/transform.py:58:9
+```
+
+omp can then inspect the stack, threads, scopes, locals, nested values, target output, and supported expressions before it steps or continues. If the target does not stop within the request timeout, the transcript says that it is still running; this is not reported as a crash. Ask omp to pause it, or set a reachable breakpoint and continue.
+
+A stopped process is genuinely paused. It may stop serving requests or holding locks until continued or terminated. Expression evaluation can also call code or mutate state in some adapters, so say “inspect without evaluating expressions” when that distinction matters.
+
+## Troubleshooting
+
+### Debugging is unavailable
+
+Check the feature gate and enable it if necessary:
+
+```sh
+omp config get debug.enabled
+omp config set debug.enabled true
+```
+
+Start a new omp session after changing which tools are enabled.
+
+### omp says the adapter is unavailable
+
+Verify the executable from the same shell that starts omp. If it is installed elsewhere, either update `PATH` before starting omp or set an absolute `command` in `dap.json`. For debugpy, `python` may exist even when the module does not; verify with:
+
+```sh
+python -m debugpy --version
+```
+
+For JavaScript, verify `JS_DEBUG_DAP_SERVER` or one of the automatic `dapDebugServer.js` locations rather than looking for a `js-debug-adapter` executable.
+
+### The wrong adapter is selected
+
+Name the adapter in the request. For a durable fix, correct its `fileTypes` and `rootMarkers` in the project DAP config. File extensions should include the leading dot and are matched lowercase.
+
+### The target path is rejected
+
+Pass a source file or executable path, not a command plus flags in one string. Put program arguments in the request separately. Directory targets require an adapter with `acceptsDirectoryProgram: true`; the built-in Delve configuration enables this for Go packages.
+
+### A breakpoint is pending or never hit
+
+Check that the source path and line belong to the code actually loaded by the target. Rebuild compiled code with debug symbols, disable optimizations if stepping is misleading, and verify source-map settings for generated JavaScript. A conditional expression must use the target language and be supported by that adapter.
+
+### Attach fails
+
+Confirm the PID is still alive or the host and port are reachable. Then name the intended adapter explicitly. Some adapters require additional fields such as a process selector or mode; put those adapter-specific values in `attachDefaults`.
+
+### omp reports another active session
+
+Ask it to terminate the existing debug session, then retry. A launch or attach failure is cleaned up automatically, but a running or stopped session remains active until the debugging work ends.
+
+## DAP adapter configuration reference
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `command` | Yes | Executable name or path. Relative paths resolve from the debug working directory. |
+| `args` | No | Arguments passed to the adapter process, not to the program being debugged. |
+| `languages` | No | Language metadata associated with the adapter. |
+| `fileTypes` | No | Lowercase extensions, including the leading dot, used for launch selection. |
+| `rootMarkers` | No | Files or directories used to recognize and rank matching projects. |
+| `launchDefaults` | No | Adapter-specific arguments merged into every launch before the requested program, working directory, and program arguments. |
+| `attachDefaults` | No | Adapter-specific arguments merged into every attach before the requested PID, host, and port. `skipAttachRequest: true` is available for an adapter that is already attached when its process starts. |
+| `connectMode` | No | `stdio` by default; `socket` for Delve-style adapters; or `tcp` for a local DAP server. In `tcp` mode, `${port}` in `args` is replaced with the allocated port. |
+| `acceptsDirectoryProgram` | No | Set to `true` when the adapter can launch a package or project directory instead of a file. |
+
+The outer `adapters` object is optional: a config file may instead contain the adapter map directly. Invalid new entries without a usable `command` are ignored; an invalid partial override does not erase the built-in adapter it was meant to change.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/editing.md

@@ -0,0 +1,157 @@
+<!--
+source: https://omp.sh/docs/editing
+fetched: 2026-09-06
+-->
+
+# Structural edits
+
+> Change the same code shape safely across a project, review the exact matches before they land, and resolve merge conflicts without brittle search-and-replace.
+
+Structural editing lets omp change syntax rather than matching raw text. It is useful for codemods that must survive different whitespace, comments, or formatting, while a staged preview makes an unexpectedly broad match visible before the change lands.
+
+The smallest useful request is plain language:
+
+> Across `src/**/*.ts`, replace calls to `legacyWrap` with `modernWrap`, preserving every argument. Show the proposed structural edit and apply it only if it changes call expressions.
+
+You specify the outcome, scope, and safety conditions. omp chooses and operates the editing machinery; you do not need to write a pattern or invoke an editing tool yourself.
+
+## Structural, symbol-aware, or text editing?
+
+omp has three related ways to make code changes:
+
+- **Structural editing** matches a syntactic shape. It can find the same function-call form despite formatting differences and rewrite many instances consistently. Use it for API migrations, repeated expression changes, import-form updates, or removal of a particular statement shape.
+- **Symbol-aware editing** follows the identity of a declaration through references, scope, imports, and re-exports. Ask for this when renaming a real symbol rather than every piece of code with the same spelling. See [Code intelligence](/docs/code-intelligence).
+- **Text or line editing** is best for a small, known location, prose, configuration, or code that has no supported parser. See [Files and editing](/docs/files).
+
+A structural match is syntax-aware, not binding-aware. Two unrelated functions named `legacyWrap` can look identical to it. If identity matters, say so:
+
+> Rename the exported `createSession` symbol from `src/session.ts` and update its real references and importers. Do not rename unrelated local functions with the same name.
+
+For a codemod with similarly named code, give omp enough context to narrow it:
+
+> In `packages/api/src/**/*.ts`, migrate only calls to `legacyWrap` imported from `@acme/legacy`. Do not touch test fixtures or locally declared functions. If the import origin cannot be proven, stop and explain the ambiguity.
+
+## Requesting and reviewing a codemod
+
+A strong request includes:
+
+1. **Scope** — files, a directory, or a glob.
+2. **Before and after behavior** — describe the code shape and what must be preserved.
+3. **Exclusions** — generated code, fixtures, a second API with the same spelling, or any other boundary.
+4. **Decision rule** — apply when the preview meets specific conditions, or preview only and stop.
+5. **Verification** — the focused command or behavior omp should check after applying it.
+
+For example:
+
+> In `packages/client/src/**/*.ts`, convert direct `response.data` reads to optional access only where `response` may be absent. Preserve comments and surrounding control flow. Preview first; reject if more than 20 replacements or any file outside that directory is included. After applying, run the client typecheck.
+
+### What the cards mean
+
+Structural rewrites are staged before they touch disk. The TUI shows the affected files, replacement count, and removed/added lines.
+
+- **Proposed** means the preview exists but its changes have not been written.
+- **Accept** means omp accepted the proposal and reports what was actually written.
+- **Reject** means the staged proposal was discarded; that proposal changed no files.
+
+These labels report state; they are not shell commands. Tell omp what you want in natural language, such as “apply this only if every match is in `src/compat`” or “reject this proposal and explain the unexpected test-file matches.”
+
+For an explicit two-pass review, start with:
+
+> Preview this codemod only. Do not apply it.
+
+omp will show the proposal and discard it rather than leave an old action pending. After reviewing the files and counts, ask omp to run the same codemod again with your approval conditions. The second run produces a fresh preview against the current working tree.
+
+### Review safely
+
+Before accepting a broad rewrite:
+
+- Check the total replacement and file counts against your expectation.
+- Expand the proposed card and inspect at least one match from every distinct code shape or package.
+- Watch for same-spelled but unrelated symbols; switch to a symbol-aware rename when necessary.
+- Narrow the path rather than accepting a surprising match and planning to repair it later.
+- Ask omp to inspect the resulting diff and run the smallest relevant typecheck or test after acceptance.
+- Keep unrelated uncommitted work visible in your review. A structural edit changes matched syntax in those files; it is not a substitute for checking the complete working-tree diff.
+
+## If the preview becomes stale
+
+Acceptance reruns the rewrite against the current files instead of blindly replaying old bytes. If another edit changes the matches between preview and acceptance, omp marks the preview as stale and reports the new result.
+
+The outcome depends on what still matches:
+
+- If nothing matches anymore, no replacements are applied.
+- If only some previewed sites still match, those current matches can be applied before omp reports that the accepted result differs from the preview.
+- If new matches appeared, omp can apply more replacements than the preview showed and flags the count mismatch.
+
+Treat a stale result as an error, not as a successful all-or-nothing transaction. Inspect the reported files and current diff, then ask omp to re-read the affected code and generate a fresh, narrower preview. Do not repeatedly accept the old proposal.
+
+Ambiguity is different from staleness: a structural matcher can validly find several syntactically identical sites even when only one is semantically intended. The file list and replacement count are the warning. Refine the request or use symbol-aware editing before applying.
+
+## Resolving merge conflicts
+
+You can ask for the desired result without choosing a side mechanically:
+
+> Resolve the conflicts in `src/session.ts`. Preserve the retry behavior from our branch and the timeout validation from the incoming branch. Show the final diff and run the session tests.
+
+When omp reads a file containing complete Git conflict markers, it assigns each block a session-local reference such as `conflict://1`. You may paste that reference into a follow-up to remove ambiguity:
+
+> For `conflict://2`, combine both sides: keep our validation and their error message. Re-read the surrounding function before changing it.
+
+> Keep ours for `conflict://1`, keep theirs for `conflict://3`, and hand-merge `conflict://4` so neither behavior is lost.
+
+`conflict://*` means every conflict currently registered in the session. Use it cautiously and state whether the same policy really applies to all of them:
+
+> Resolve `conflict://*`, but inspect each block independently. Do not choose one side wholesale; preserve both behaviors where they are compatible.
+
+References appear only after omp has read and registered the marker block. They are session-local, and an ID from an old session should not be reused. If a block was edited or resolved after registration, omp refuses to splice a marker region it can no longer locate and asks for a re-read. Resolving one block does not invalidate unrelated registered blocks.
+
+Conflict resolution is a direct merge operation rather than a structural-edit proposal. For high-risk merges, ask omp to explain the intended resolution first, then request the edit and review the resulting Git diff. A final search for conflict markers and the relevant tests should be part of the request.
+
+## Configuration
+
+Structural editing is enabled by default. Open `/settings`, then go to **Tools → Available Tools → AST Edit** to turn it on or off. The corresponding setting is `astEdit.enabled`; for shell-managed configuration:
+
+```sh
+omp config set astEdit.enabled true
+omp config set astEdit.enabled false
+```
+
+See [Settings](/docs/settings) for configuration precedence and file locations.
+
+A structural pass searches at most 1,000 files by default. Set the positive `PI_MAX_AST_FILES` environment variable before launching omp if a larger repository genuinely needs a different ceiling. Usually the safer response to a limit warning is to narrow the requested directory or glob, not raise the ceiling.
+
+A restricted `--tools` list can also make structural editing unavailable even when the setting is enabled. In that case, restore the normal editing tools or ask omp for a scoped alternative.
+
+## Limitations
+
+- Structural editing understands syntax, not types, runtime behavior, or symbol ownership. Use code intelligence and verification where those matter.
+- Only languages with a supported parser can be rewritten structurally. A file that does not parse cleanly may be skipped with a parse warning.
+- The rewrite must map recognizable syntax to replacement syntax. Cross-file transformations that require generated data, control-flow analysis, or several coordinated statements may be better handled as a purpose-built script plus a reviewed diff.
+- Comments and formatting do not prevent a syntax match, but a rewrite can still change formatting around the replaced node. Review the rendered diff.
+- Large or overly general requests can hit the file ceiling or produce too many valid matches to review safely. Split them by package or code shape.
+- Merge-conflict references recognize complete, well-formed Git marker blocks. Incomplete or hand-damaged markers must be inspected as ordinary text.
+
+## Troubleshooting
+
+### “No replacements made”
+
+Ask omp to inspect one concrete example and explain why it did not match. The code may use a different syntax, the path may be too narrow, or symbol-aware editing may be the better operation. Do not broaden to the whole repository until one representative case previews correctly.
+
+### Parse warnings
+
+Have omp identify the affected files and confirm that they parse in their declared language. Fix broken syntax first, exclude generated or unsupported files, or use a tightly scoped text edit when structural parsing is not appropriate.
+
+### Too many or unexpected matches
+
+Reject the proposal. Add import origin, receiver type, enclosing function, package, file glob, or explicit exclusions to the request. If the distinction is symbol identity, request an [LSP-backed rename](/docs/code-intelligence) instead.
+
+### “Limit reached”
+
+Narrow the scope and rerun. The preview is incomplete when the search ceiling is reached, so its count is not a repository-wide total.
+
+### “Preview is stale”
+
+Inspect the current diff because a subset or a changed set of matches may already have been applied. Then ask omp to re-read the files and create a new preview; accept only when the fresh file and replacement counts are expected.
+
+### A `conflict://` reference is unknown or no longer present
+
+Ask omp to read the conflicted file again. This refreshes the session’s conflict index and avoids applying a decision to a block whose markers or surrounding file have changed.