Initial commit: omp-ast DSH plugin (oh-my-pi port) with docs and tests

README.md

@@ -0,0 +1,73 @@
+# omp-ast
+
+[oh-my-pi](https://github.com/can1357/oh-my-pi)'s `ast_grep` and `ast_edit` tools for the DeepSeek Harness (DSH): **structural code search** and **structural rewrites that are previewed before they are applied**. Both are backed by [ast-grep](https://ast-grep.github.io) (tree-sitter grammars for JS/TS/TSX, Python, Go, Rust, Java, C/C++, C#, Kotlin, Swift, Ruby, PHP, Lua, Bash, HTML, CSS, JSON, YAML, …).
+
+## Tools
+
+### `ast_grep`
+
+| Field | Description |
+| --- | --- |
+| `pat` (required) | One AST pattern, e.g. `console.log($$$ARGS)`, `def $F($$$): $$$BODY` |
+| `path` | File, directory or glob; several separated by `;` (default: session workspace) |
+| `lang` | Language override (`ts`, `tsx`, `python`, `cpp`, …) |
+| `globs` | Include/exclude globs (`!` prefix excludes) |
+| `selector` | AST kind to select inside the pattern (advanced) |
+| `skip` | Paging offset |
+
+Pattern grammar:
+- `$NAME` captures one node; `$$$NAME` captures zero or more nodes.
+- `$_` and `$$$` match without binding.
+- Names are UPPERCASE and stand for whole nodes.
+
+Output is grouped per file as `LINE:TEXT`, with the captured metavariables:
+
+```
+2 matches in 1 file
+src/a.js
+2:  console.log(x)
+  ↳ $$$ARGS=[x]
+3:  console.log(x, 2)
+  ↳ $$$ARGS=[x, 2]
+```
+
+### `ast_edit`
+
+1. **Preview:** `{ops: [{pat, out}, …], paths: [...]}`.
+   - Captures from `pat` are substituted into `out`; an empty `out` deletes the node.
+   - Ops run in order, and each sees the result of the previous one.
+   - The call returns a diff preview and a proposal id. **No file is modified.**
+2. **Apply:** `{apply: "<id>"}` writes the proposal. It's refused if any file changed since the preview.
+3. **Discard:** `{reject: "<id>"}` drops the proposal.
+
+Applied writes go through DSH's filesystem service (sandbox policy, observation tracking), and the Web UI shows a diff card. Proposals expire after `proposalTtlMinutes`.
+
+## Requirements
+
+```bash
+npm i -g @ast-grep/cli            # or: npm i -g --prefix ~/.local @ast-grep/cli
+```
+
+The plugin looks for the `ast-grep` binary on `PATH` and in `~/.local/bin`. It ignores `sg`, which collides with util-linux on many distros.
+
+## Installation
+
+```bash
+dsh plugin --profile web add git+https://git.rizzy.dev/DSH-Plugins/omp-ast.git
+```
+
+Or in the Web UI, go to **Settings → Plugins → Install** and paste the same URL. For development, clone the repo and run `dsh plugin --profile web add link:/path/to/omp-ast`. Restart DSH afterwards (`systemctl --user restart dsh`).
+
+## Configuration
+
+```yaml
+- id: omp-ast
+  config:
+    maxMatches: 200          # ast_grep page size
+    maxFiles: 1000           # ast_edit safety cap
+    proposalTtlMinutes: 30
+```
+
+## Tests
+
+`npm test` runs 4 tests against the real ast-grep CLI and DSH's fs backend.