dsh-hashline-edit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RimuruW and Yugimob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# dsh-hashline-edit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hash-anchored file editing for [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) on Windows.
+
+`dsh-hashline-edit` is a dsh bundle that shadows the host's built-in `read` and `edit` tools with hashline equivalents and adds `undo_last_edit`. Every line a served read shows carries a stable 4-character base62 anchor (`A–Z`, `a–z`, `0–9`) derived from the file's canonical path and the line's content. An edit names two anchors and new text; it never re-types existing code. Anchors for unchanged lines stay stable across edits, and every successful edit returns fresh anchors for the changed lines, so chained edits need no re-read.
+
+The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-edit) v2.16.0 hashline engine (MIT). The `dsh/` tree is this repository's DeepSeek Harness host layer: tool registration, filesystem bridge, encoding governance, prompt guidance, shell integration, write integration and telemetry. See [`dsh/README.md`](dsh/README.md) for the host-layer map.
+
+## Requirements
+
+| Requirement | Version |
+| --- | --- |
+| OS | Windows — this branch targets Windows only (see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)) |
+| Node.js | ≥ 24.0.0 |
+| pnpm | 12.x |
+| DeepSeek Harness | plugin-capable build; the repository is developed against `@deepseek-ai/dsh-*@0.2.1-rc.2` |
+
+## Install
+
+Build the plugin first: the dsh loader reads the package through `exports`/`main`, and `lib/` is gitignored.
+
+```sh
+pnpm install
+pnpm run build
+dsh plugin add <path-to-repo-or-tgz>
+```
+
+To keep the install isolated, use a throwaway profile:
+
+```sh
+dsh plugin --profile scratch-hashline add <path-to-repo>
+dsh --profile scratch-hashline --dump-config   # the bundle row is composed
+```
+
+For a tarball, pack first and add the archive:
+
+```sh
+pnpm pack
+dsh plugin add ./dsh-hashline-edit-0.1.0.tgz
+```
+
+The bundle ships `lib/index.js` plus `lib/types/**`; `prompts/` must sit next to `lib/` in the installed package (it is in `files`). Guidance override files are materialized under `<DSH_HOME>/plugins/dsh-hashline-edit/guidance/` and are shared between profiles.
+
+## The anchored model
+
+A served read looks like this (`│` is U+2502, the separator):
+
+```text
+ve7x│function calculateTotal(items: CartItem[]): number {
+szJx│  let total = 0;
+kQmx│  for (const item of items) {
+m2zX│    total += item.price;
+d2xX│  }
+p9rX│  return total;
+a1bX│}
+```
+
+Copy only the 4 characters before `│` into `anchor_from` / `anchor_to`. An edit targets an inclusive range and returns a diff whose modified and context rows carry fresh anchors:
+
+```text
+- szJx│  let total = 0;
+- kQmx│  for (const item of items) {
+- m2zX│    total += item.price;
++w4kQ│  let total = items.reduce((sum, item) => sum + item.price, 0);
+  d2xX│  }
+```
+
+Served anchors are leased per session and per file. A stale, unknown, retired or foreign anchor is refused with a `[MODEL] [E_*]` message; range refusals return the current rows as a fresh read (`Current range (fresh read):`) so the model can retry from the rejection alone. An ordinary refusal writes nothing; a foreign-source cut is ordered and repair-backed rather than filesystem-atomic across a crash.
+
+## Tools
+
+### `read`
+
+```ts
+read({
+  path: string,                 // relative or absolute; the dsh tool takes `path`, not `file`
+  offset?: number,              // 1-indexed start; a bare offset reads a window (default limit 50)
+  limit?: number,
+  windows?: Array<                // up to 16 disjoint windows in one call
+    | { offset: number; limit: number }
+    | { around_anchor: string; radius?: number }   // radius defaults to 10
+  >,
+  mode?: "served" | "verbatim", // default "served"
+  encoding?: string,            // reopen a non-UTF-8 file, e.g. "gbk", "big5", "shift_jis", "utf16le"
+})
+```
+
+- **Served mode** returns one `HASH│content` row per line and records every shown row as a lease for this session. A windowed read also includes a `[Lines A-B of N total]` page header. Every row shown is usable by one subsequent edit, even when the windows are far apart.
+- **Verbatim mode** returns the same page as plain text with no anchors and serves nothing; an edit cannot target those lines.
+- A small requested window may widen to its enclosing function, method, class, section or paragraph; a `[widened …]` note names the block that was served. Expansion applies in both modes.
+- `offset`/`limit` and `windows` are page requests, not anchors: only `served` output grants edit leases.
+
+### `edit`
+
+```ts
+edit({
+  file: string,                 // one text file per call
+  edits: [{
+    anchor_from: string,        // bare 4-char anchor of the first range line (inclusive)
+    anchor_to: string,          // bare 4-char anchor of the last range line (inclusive)
+    text?: string,              // by-value content; "" deletes an in-place range
+    text_ref?: {                // by-reference content from a served span
+      anchor_from: string,
+      anchor_to: string,
+      file?: string,            // another served file (foreign-source copy/cut)
+      mode: "copy" | "cut",     // required: copy keeps the source, cut retires the span
+    },
+    at?: "in-place" | "before" | "after",  // default "in-place"
+  }],
+  mode?: "general" | "literal", // "general" refuses served-row echoes; "literal" declares them intended
+})
+```
+
+Each item carries exactly one of `text` or `text_ref`; supplying both or neither is refused. `before`/`after` insert at the range boundary and require a single-line resolved target. A foreign-source `cut` writes both files as one correlated transaction; `undo_last_edit` reverts both members. An edit never silently rewrites submitted text — a refused edit writes nothing.
+
+The result is the core's unified diff with fresh anchors for the changed lines, so the next edit can chain from them without a `read`. The host's built-in `write` is not replaced: the plugin guards it against served-row echoes and appends an anchored auto-read so following edits can use its output.
+
+### `undo_last_edit`
+
+```ts
+undo_last_edit({ path: string })
+```
+
+Restores the previous file content, BOM, line endings and original anchors from a snapshot-pinned undo record. The record survives agent restarts. A file changed externally after the edit is refused with `[E_UNDO_STALE]`. A correlated cut's undo restores every member of the transaction, not only the named path.
+
+## Shell view
+
+The plugin installs a `tools/post-execute` listener for the host's `pwsh` and `bash` tools. When the command is a whitelisted read-only file view, the captured stdout is replaced with the aligned file's `HASH│content` rows, and those rows are served (leased) exactly like a read — a following `edit` can use them with no re-read.
+
+| Command shape | Served as |
+| --- | --- |
+| `Get-Content <file>`, `type <file>`, `cat <file>` | the file's lines |
+| `Get-Content <file> \| Select-Object -First/-Last/-Skip <N>` | the bounded slice |
+| `Select-String <pattern> <file>` | the matched lines, with their line numbers |
+| `rg <pattern> <file>` (explicit single file, no switches) | the matched lines, with their line numbers |
+
+Alignment is strict: stdout lines are mapped to 1-based disk line numbers with a monotonic, unique match (search output's own line numbers are used as hints). Anything the view cannot prove — an unknown pipeline, a wildcard path, formatted output, a truncated capture, a failed command — passes through byte-for-byte. The hook never guesses and never serves the wrong occurrence of a duplicated line.
+
+## Encoding governance
+
+The dsh host reintroduces a VS Code-style encoding model on top of the UTF-8 core. Read admission is deterministic:
+
+1. explicit `read({ encoding })` hint;
+2. BOM sniff (UTF-8, UTF-16LE/BE and UTF-32LE/BE BOMs);
+3. strict UTF-8 decode;
+4. the `autoGuessEncoding` gate (off by default);
+5. Top-3 candidate preview on refusal, e.g. `not readable UTF-8 text — top guesses: gbk("你好"); try read({encoding: "<encoding>"}) or enable autoGuessEncoding to decode automatically`.
+
+Text encodings offered to the model are `gbk`, `big5`, `shift_jis`, `euc-kr`, `windows-1251` and `utf16le` (case-insensitive), in addition to UTF-8 and BOM-detected Unicode.
+
+A governed read records the file's encoding state (encoding, BOM, line ending, file version). Both the `edit` lane and the built-in `write` lane invert that state on save through a single codec:
+
+- a GBK file edited through `read` → `edit` stays GBK on disk (byte comparison, not text equality);
+- a UTF-16LE file with a BOM keeps its BOM and its byte order;
+- a UTF-8 BOM file round-trips byte-for-byte.
+
+When a legacy code page cannot represent the new text, the save degrades to UTF-8 and appends a model-facing warning instead of writing lossy bytes:
+
+> Warning: the file was written as UTF-8 because the recorded gbk encoding cannot represent the edited text. Re-read the file before the next edit.
+
+Undo also inverts the recorded state for every member of a correlated cut — but only when a governed read recorded that file's encoding state in the same plugin process. Without a recorded state, undo keeps the core's UTF-8 behavior; on a legacy file that can surface as `[E_UNDO_STALE]` rather than a guessed re-encode.
+
+## Sandbox behavior
+
+`edit` and `undo_last_edit` carry the host's optional escalation fields `sandbox_permissions` and `justification` only when a confining filesystem backend is mounted. `dsh/sandbox.ts` mirrors the built-in `@deepseek-ai/dsh-tool-fs` controller: it validates the field pairing, repeats the standing mode without approval, and resolves a strictly wider mode through the host's approval channel before touching the filesystem. A provider `FS_SANDBOX_DENIED` error is mapped to the standard model-facing denial marker plus escalation hint; other errors pass through unchanged.
+
+### Host-side `0xC0000142` workspace-write finding
+
+On this Windows host, the default `workspace-write` pwsh sandbox cannot start `pwsh`: `dsh-pwsh-sandbox` launches it through the Windows ACL restricted-token runner, and the child dies at process start with exit code `3221225794` (`0xC0000142`, `STATUS_DLL_INIT_FAILED`). It reproduces in a headless profile with **no hashline plugin installed**, so the failure belongs to `dsh-tool-pwsh` + `dsh-sandbox-windows-acl`, not to this plugin.
+
+The M3/M4 smoke runs therefore used `DSH_PERMISSION_MODE=danger-full-access`; this is an environment setup requirement, not a plugin behavior. Evidence: `dsh/baseline/m4-behaviour.json` (`sandboxFinding`) and `dsh/baseline/m3.json`.
+
+## Build and verify
+
+| Command | What it does |
+| --- | --- |
+| `pnpm install` | install dependencies |
+| `pnpm run build` | `node scripts/build-dsh.mjs`: bundle `lib/index.js` and emit `lib/types/**` from `tsconfig.dsh.json` |
+| `pnpm run typecheck` | `tsc --noEmit` (full upstream program) and `tsc --noEmit -p tsconfig.dsh.json` (dsh build program) |
+| `pnpm run test:win` | the Windows test suite (`vitest.config.windows.ts`); the primary gate for this branch |
+| `pnpm test` | the default vitest suite |
+| `pnpm run format` | `oxfmt --check .` (use `pnpm run format:fix` to write) |
+| `pnpm run lint` | `oxlint .` + `knip --max-issues 0` |
+| `pnpm run verify` | lint + format + typecheck + Windows coverage |
+
+The build enforces its own packaging contract: host packages stay external, the pi utility package is aliased to `dsh/host-compat.ts` (the bundle must not reference pi), and no bare import outside the allowlist can slip in. See [`dsh/README.md`](dsh/README.md#build-and-packaging).
+
+## Error and warning codes
+
+Every refusal carries a bracketed code; `src/domain-errors.ts` is the source of truth. `E_*` are refusals (nothing is written), `W_*` are warnings carried beside an accepted result.
+
+| Code | Meaning |
+| --- | --- |
+| `[E_ACCESS]` | The filesystem denied access to the target path. |
+| `[E_BAD_PAYLOAD]` | Malformed or unknown tool payload; nothing is written. |
+| `[E_BATCH_ABORT]` | A batch item failed; the whole batch was not applied. |
+| `[E_EMPTY_RANGE]` | The edit would empty a non-empty file; use `write`. |
+| `[E_FOREIGN_ANCHOR]` | The anchor belongs to a different file. |
+| `[E_INTERNAL_INVARIANT]` | An internal invariant was violated. |
+| `[E_LARGE_FILE]` | The file exceeds the served line or byte budget. |
+| `[E_LOSSY_TEXT]` | The file's bytes do not round-trip through UTF-8; editing would corrupt it. |
+| `[E_MALFORMED_ANCHOR]` | The anchor token cannot be parsed. |
+| `[E_NOOP_LOOP]` | Repeated identical no-op edits; refused with the current range served. |
+| `[E_NOT_FOUND]` | The target file does not exist or is unreachable. |
+| `[E_STALE_ANCHOR]` | A boundary anchor no longer resolves against the file. |
+| `[E_STALE_RANGE]` | The served range changed between serve and edit. |
+| `[E_SUSPICIOUS_TEXT]` | The replacement reproduces served anchor text (a copied `HASH│` echo). |
+| `[E_TARGET_LOST]` | The target line identity can no longer be resolved. |
+| `[E_UNDO_REVERT_FAILED]` | A correlated revert failed mid-way; a repair run finishes it. |
+| `[E_UNDO_STALE]` | The undo record is stale relative to the file. |
+| `[E_UNDO_UNAVAILABLE]` | There is no undo history for the path. |
+| `[E_UNKNOWN]` | An unclassified failure; the message carries the cause. |
+| `[E_UNKNOWN_ANCHOR]` | The anchor was never served in this session. |
+| `[E_UNSUPPORTED_FILE]` | Binary, image or directory targets are not editable text. |
+| `[E_UNVERIFIED_RANGE]` | The range interior cannot be verified (never served). |
+| `[W_LITERAL_BYPASS]` | Literal `HASH│` bytes were written through `edit` and accepted with a warning. |
+| `[W_NEVER_SERVED_SHAPE]` | A never-served hint was attached to an accepted edit. |
+| `[W_NOOP]` | The edit produced no content change and was accepted as a no-op. |
+| `[W_NOOP_INSERT]` | An insert-shaped edit produced no change. |
+| `[W_REVERSED_ANCHORS]` | Boundaries were reversed and healed. |
+| `[W_SERVED_PREFIX_MISMATCH]` | A served prefix does not match; fresh rows were served. |
+| `[W_UNICODE_LITERAL]` | A Unicode literal in the payload looks like a copied anchor. |
+
+## Current limitations
+
+- **`ctx.fs` is read-only.** The read path can consume a mounted `ctx.fs` through the `CoreReadIo` port, but the mutation seams — `writeAtomic`, the edit engine and undo — remain local-only. `edit` and `undo_last_edit` fail closed with `E_NOT_FOUND` when the target is reachable only through `ctx.fs`.
+- **`edit`, `undo_last_edit` and `writeAtomic` are local-only.** A remote or sandboxed backend needs target-keyed store state and versioned writes; that is deferred to M6 (see [`dsh/README.md`](dsh/README.md#ctxfs-bridge-m5-read-only)).
+- **Undo preserves a legacy encoding only with recorded state.** The encoding memo lives in the plugin process and is version-gated; a fresh process or a file never governed-read in that process has no state to invert, so undo keeps the core's UTF-8 behavior.
+- **Windows-only.** The branch targets Windows; POSIX-only suites are excluded in `vitest.config.windows.ts`, and that exclusion list must shrink, never grow (see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)).
+
+## Repository layout
+
+| Path | Role |
+| --- | --- |
+| `src/` | upstream pi-better-edit core (semantic source; synced from upstream) |
+| `dsh/` | DeepSeek Harness host layer — the only code that differs from upstream; map in [`dsh/README.md`](dsh/README.md) |
+| `dsh/UPSTREAM.md` | upstream sync cursor, policy and Windows adaptation patches |
+| `dsh/baseline/` | milestone measurement baselines (M0–M5) |
+| `scripts/build-dsh.mjs` | dsh bundle builder and packaging guards |
+| `tsconfig.dsh.json` | dsh build typecheck/declaration program |
+
+## Upstream attribution
+
+The hashline engine is [**pi-better-edit**](https://github.com/Rianico/pi-better-edit) by [Rianico](https://github.com/Rianico), used under the MIT license and synced at upstream `673964c` (`v2.16.0`; see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)). This repository keeps the upstream history and tree; the `dsh/` adapter is ours, is never merged upstream, and contains only host wiring.
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-hashline-edit bundle patch: mount the host-plane plugin row.
+# Installed via `dsh plugin --profile <name> add dsh-hashline-edit` (or a
+# profile's bundle list). The plugin hooks agent/created and shadows the
+# built-in read/edit tools on each agent's own scope layer, so no preset
+# editing or user config is needed.
+- insert:
+    - id: dsh-hashline-edit
+      name: dsh-hashline-edit