AGENTS.md

1# src/tools/hashline-edit/ — Hash-Anchored File Edit Tool
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
724 files. Implements the `hashline_edit` tool — hash-anchored file editing where every line reference includes a content hash (`LINE#ID`). Validates hashes before applying edits, rejecting stale references.
8 
9## THREE-OP MODEL
10 
11All edits use exactly 3 operations:
12 
13| Op | pos | end | lines | Effect |
14|----|-----|-----|-------|--------|
15| `replace` | required | optional | required | Replace single line or range pos..end |
16| `append` | optional | optional | required | Insert after anchor (or EOF if no anchor) |
17| `prepend` | optional | optional | required | Insert before anchor (or BOF if no anchor) |
18 
19`lines: null` or `lines: []` with `replace` = delete. `delete: true` at tool level = delete file.
20 
21## EXECUTION PIPELINE
22 
23```
24hashline-edit-executor.ts
25  → normalize-edits.ts       # Parse RawHashlineEdit → HashlineEdit (validate op schema)
26  → validation.ts            # Validate LINE#ID references (hash match, line exists)
27  → edit-ordering.ts         # Sort bottom-up (by line number, descending)
28  → edit-deduplication.ts    # Remove duplicate ops
29  → edit-operations.ts       # Apply each op using edit-operation-primitives.ts
30  → autocorrect-replacement-lines.ts  # Auto-fix indentation/formatting
31  → hashline-edit-diff.ts    # Build diff output using diff-utils.ts
32```
33 
34## KEY FILES
35 
36| File | Purpose |
37|------|---------|
38| `tools.ts` | `createHashlineEditTool()` factory — tool schema + entry point |
39| `hashline-edit-executor.ts` | Main execution: normalize → validate → order → apply → diff |
40| `normalize-edits.ts` | Parse `RawHashlineEdit[]` (allows string `op` variants) → typed `HashlineEdit[]` |
41| `validation.ts` | Validate LINE#ID: parse hash, verify line content matches stored hash |
42| `hash-computation.ts` | `computeLineHash(line)` → 2-char CID from set `ZPMQVRWSNKTXJBYH` |
43| `edit-operations.ts` | Apply replace/append/prepend to file lines array |
44| `edit-operation-primitives.ts` | Low-level line array mutation primitives |
45| `edit-ordering.ts` | Sort edits bottom-up to preserve line numbers during multi-edit |
46| `edit-deduplication.ts` | Deduplicate overlapping/identical operations |
47| `edit-text-normalization.ts` | Normalize line content (CRLF, BOM, trailing whitespace) |
48| `file-text-canonicalization.ts` | Canonicalize full file content before hashing |
49| `autocorrect-replacement-lines.ts` | Auto-restore indentation from original lines |
50| `hashline-edit-diff.ts` | Generate unified diff for error/success messages |
51| `diff-utils.ts` | Thin wrapper around `diff` npm library |
52| `hashline-chunk-formatter.ts` | Format line chunks with `LINE#ID` tags |
53| `tool-description.ts` | `HASHLINE_EDIT_DESCRIPTION` constant |
54| `types.ts` | `HashlineEdit`, `ReplaceEdit`, `AppendEdit`, `PrependEdit` |
55| `constants.ts` | Hash alphabet, separator character (`#`), pipe separator (`|`) |
56 
57## LINE#ID FORMAT
58 
59```
60{line_number}#{hash_id}
61```
62 
63- `hash_id`: two chars from `ZPMQVRWSNKTXJBYH` (CID letters)
64- Example: `42#VK` means line 42 with hash `VK`
65- Validation: recompute hash of current line content → must match stored hash
66- Content separator: `|` (pipe) between hash tag and content in read output
67 
68## AUTOCORRECT BEHAVIORS (built-in)
69 
70- Merged lines auto-expanded back to original count
71- Indentation restored from original lines
72- BOM and CRLF line endings preserved
73- `>>>` prefix and diff markers in `lines` text auto-stripped
74 
75## ERROR CASES
76 
77- Hash mismatch → edit rejected, diff shown with current state
78- Overlapping ranges → detected and rejected
79- Missing `pos` for `replace` → schema error
80- `lines: null` with `append`/`prepend` → schema error
81 
82## HOW LINE HASHES WORK
83 
84```typescript
85// Reading: every line gets tagged
86"42#VK| function hello() {"
87 
88// Editing: reference by tag
89{ op: "replace", pos: "42#VK", lines: "function hello(name: string) {" }
90 
91// If file changed since read: hash won't match → rejected before corruption
92```
93