dsh-better-edit 0.6.3 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/CHANGELOG.md +59 -15
  2. package/README.md +78 -71
  3. package/README.zh.md +83 -83
  4. package/lib/canonical-path.js +4 -1
  5. package/lib/constants.js +5 -1
  6. package/lib/contract.js +127 -33
  7. package/lib/edit-diff.js +1 -5
  8. package/lib/edit-response.js +5 -10
  9. package/lib/encoding.js +23 -6
  10. package/lib/file-encoding-state.js +54 -15
  11. package/lib/file-view.js +42 -53
  12. package/lib/fs-bridge.js +27 -16
  13. package/lib/fs-write.js +1 -1
  14. package/lib/guidance/materialize.js +1 -6
  15. package/lib/guidance/resolve.js +1 -1
  16. package/lib/hash-store.js +133 -43
  17. package/lib/hashline/anchor-pipeline.js +124 -93
  18. package/lib/hashline/hash-assign.js +65 -23
  19. package/lib/hashline/hash.js +6 -6
  20. package/lib/index.js +6 -0
  21. package/lib/mutation/engine.js +89 -31
  22. package/lib/mutation.js +14 -13
  23. package/lib/prompts.js +12 -11
  24. package/lib/read-and-serve.js +105 -19
  25. package/lib/render-text-warning.js +21 -0
  26. package/lib/sandbox.js +2 -5
  27. package/lib/self-heal.js +30 -27
  28. package/lib/session-view.js +161 -24
  29. package/lib/store-config.js +7 -2
  30. package/lib/store-lifecycle.js +7 -2
  31. package/lib/tool-edit.js +10 -6
  32. package/lib/tool-read.js +6 -9
  33. package/lib/tool-str-replace-editor.js +274 -0
  34. package/lib/tool-undo.js +8 -9
  35. package/lib/types/constants.d.ts +2 -0
  36. package/lib/types/contract.d.ts +106 -18
  37. package/lib/types/edit-response.d.ts +4 -0
  38. package/lib/types/encoding.d.ts +1 -1
  39. package/lib/types/file-encoding-state.d.ts +4 -1
  40. package/lib/types/file-view.d.ts +16 -1
  41. package/lib/types/hash-store.d.ts +12 -1
  42. package/lib/types/hashline/anchor-pipeline.d.ts +16 -6
  43. package/lib/types/hashline/hash-assign.d.ts +10 -2
  44. package/lib/types/hashline/index.d.ts +1 -1
  45. package/lib/types/mutation/engine.d.ts +2 -1
  46. package/lib/types/render-text-warning.d.ts +22 -0
  47. package/lib/types/self-heal.d.ts +2 -0
  48. package/lib/types/session-view.d.ts +13 -4
  49. package/lib/types/tool-str-replace-editor.d.ts +27 -0
  50. package/lib/types/undo-edit.d.ts +1 -1
  51. package/lib/types/utils.d.ts +7 -0
  52. package/lib/types/write-hook.d.ts +2 -2
  53. package/lib/undo-edit.js +6 -8
  54. package/lib/utils.js +23 -3
  55. package/lib/workspace-context.js +1 -1
  56. package/lib/write-hook.js +20 -23
  57. package/package.json +63 -57
@@ -23,8 +23,7 @@ export function buildMetrics(args) {
23
23
  return metrics;
24
24
  }
25
25
  export function finalizeResult(input) {
26
- const modelWarnings = input.warnings?.filter((w) => !w.startsWith("Batch drift note:"));
27
- const base = input.diff + warnBlock(modelWarnings);
26
+ const base = input.diff + warnBlock(input.warnings);
28
27
  return base;
29
28
  }
30
29
  export function finalizeToolResult(details) {
@@ -63,8 +62,7 @@ export function buildNoop(input) {
63
62
  const noopDetailsText = noopEdit
64
63
  ? `Edit for ${noopEdit.loc} is identical to current content:\n ${noopEdit.loc}: ${clipLine(noopEdit.currentContent)}`
65
64
  : "The edit produced identical content.";
66
- const modelWarnings = warnings?.filter((w) => !w.startsWith("Batch drift note:"));
67
- const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}${warnBlock(modelWarnings)}`;
65
+ const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}${warnBlock(warnings)}`;
68
66
  const metrics = buildMetrics({
69
67
  classification: "noop",
70
68
  editsAttempted: editMeta.editsAttempted,
@@ -90,8 +88,7 @@ export function buildChanged(input) {
90
88
  const diffResult = genDiff(originalNormalized, result, 1, resultHashes, originalHashes);
91
89
  const addedLines = editMeta.addedLines;
92
90
  const removedLines = editMeta.removedLines;
93
- const modelWarnings = warnings?.filter((w) => !w.startsWith("Batch drift note:"));
94
- const warningsBlock = warnBlock(modelWarnings);
91
+ const warningsBlock = warnBlock(warnings);
95
92
  const successPrefix = `Successfully edited in ${path}.`;
96
93
  const lineSummary = addedLines > 0 || removedLines > 0
97
94
  ? ` Added ${addedLines} line(s), removed ${removedLines} line(s).`
@@ -144,8 +141,7 @@ export function buildBatchResult(sections) {
144
141
  .filter((d) => d !== undefined)
145
142
  .join("\n\n");
146
143
  if (allNoop) {
147
- const modelWarnings = warnings.filter((w) => !w.startsWith("Batch drift note:"));
148
- const text = `No changes made. All ${totalEdits} edit(s) in the batch produced identical content.\nClassification: noop${warnBlock(modelWarnings)}`;
144
+ const text = `No changes made. All ${totalEdits} edit(s) in the batch produced identical content.\nClassification: noop${warnBlock(warnings)}`;
149
145
  return {
150
146
  content: [{ type: "text", text }],
151
147
  details: {
@@ -180,8 +176,7 @@ export function buildBatchResult(sections) {
180
176
  ? ` Added ${addedLines} line(s), removed ${removedLines} line(s).`
181
177
  : "";
182
178
  const summary = `Successfully edited ${appliedFiles.length} file(s) — ${appliedTotal} of ${totalEdits} edit(s) applied${noopTotal > 0 ? ` (${noopTotal} noop)` : ""}.${lineSummary}`;
183
- const modelWarnings = warnings.filter((w) => !w.startsWith("Batch drift note:"));
184
- const baseText = `${summary}${warnBlock(modelWarnings)}`;
179
+ const baseText = `${summary}${warnBlock(warnings)}`;
185
180
  const diffSection = formatDiffCard(diff);
186
181
  const text = `${baseText}${diffSection}`;
187
182
  return {
package/lib/encoding.js CHANGED
@@ -55,14 +55,23 @@ export function isSupportedEncoding(enc) {
55
55
  const norm = normalizeEncoding(enc);
56
56
  if (!norm)
57
57
  return false;
58
- return SUPPORTED_ENCODINGS.includes(norm) || ["utf8", "utf8bom", "utf16le", "utf16be", "utf32le", "utf32be"].includes(norm);
58
+ return (SUPPORTED_ENCODINGS.includes(norm) ||
59
+ ["utf8", "utf8bom", "utf16le", "utf16be", "utf32le", "utf32be"].includes(norm));
59
60
  }
60
61
  export function detectBom(bytes) {
61
62
  if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
62
63
  return { encoding: "utf8bom", bomLen: 3, hasBOM: true };
63
- if (bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xfe && bytes[2] === 0x00 && bytes[3] === 0x00)
64
+ if (bytes.length >= 4 &&
65
+ bytes[0] === 0xff &&
66
+ bytes[1] === 0xfe &&
67
+ bytes[2] === 0x00 &&
68
+ bytes[3] === 0x00)
64
69
  return { encoding: "utf32le", bomLen: 4, hasBOM: true };
65
- if (bytes.length >= 4 && bytes[0] === 0x00 && bytes[1] === 0x00 && bytes[2] === 0xfe && bytes[3] === 0xff)
70
+ if (bytes.length >= 4 &&
71
+ bytes[0] === 0x00 &&
72
+ bytes[1] === 0x00 &&
73
+ bytes[2] === 0xfe &&
74
+ bytes[3] === 0xff)
66
75
  return { encoding: "utf32be", bomLen: 4, hasBOM: true };
67
76
  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe)
68
77
  return { encoding: "utf16le", bomLen: 2, hasBOM: true };
@@ -248,7 +257,7 @@ export async function detectWithChardet(bytes, allowlist) {
248
257
  }
249
258
  }
250
259
  /**
251
- * Chardet-based Top-3 for E_NOT_TEXT (primary) and autoGuess.
260
+ * Chardet-based Top-3 for E_UNSUPPORTED_FILE (primary) and autoGuess.
252
261
  * Returns chardet candidates filtered by allowlist and decodable, else empty.
253
262
  */
254
263
  export async function chardetTop3Candidates(bytes, allowlist) {
@@ -287,7 +296,11 @@ export async function chardetTop3Candidates(bytes, allowlist) {
287
296
  if (idx === -1)
288
297
  return text.slice(0, 50);
289
298
  const start = Math.max(0, idx - 32);
290
- return text.slice(start, start + 64).slice(0, 50).replace(/\s+/g, " ").trim();
299
+ return text
300
+ .slice(start, start + 64)
301
+ .slice(0, 50)
302
+ .replace(/\s+/g, " ")
303
+ .trim();
291
304
  })();
292
305
  out.push({ encoding: norm, confidence: r.confidence, sample });
293
306
  if (out.length >= 3)
@@ -302,7 +315,11 @@ export async function chardetTop3Candidates(bytes, allowlist) {
302
315
  export async function getTop3Candidates(bytes, allowlist) {
303
316
  const chardetCands = await chardetTop3Candidates(bytes, allowlist);
304
317
  if (chardetCands.length > 0) {
305
- return chardetCands.map((c) => ({ encoding: c.encoding, sample: c.sample, score: c.confidence }));
318
+ return chardetCands.map((c) => ({
319
+ encoding: c.encoding,
320
+ sample: c.sample,
321
+ score: c.confidence,
322
+ }));
306
323
  }
307
324
  return top3Candidates(bytes, allowlist);
308
325
  }
@@ -14,8 +14,8 @@
14
14
  *
15
15
  * @module dsh-better-edit/file-encoding-state
16
16
  */
17
- import { detectBom, isValidUtf8, decodeBytes, normalizeEncoding, top3Candidates, chardetTop3Candidates } from "./encoding.js";
18
- import { detectEnding } from "./edit-diff.js";
17
+ import { detectBom, isValidUtf8, decodeBytes, normalizeEncoding, top3Candidates, chardetTop3Candidates, } from "./encoding.js";
18
+ import { detectEnding, restoreEndings, toLF } from "./edit-diff.js";
19
19
  const encodingMemo = new Map();
20
20
  const autoGuessFooterMemo = new Map();
21
21
  export function getEncodingState(targetKey) {
@@ -52,19 +52,29 @@ export function invalidateIfStale(targetKey, currentVersion) {
52
52
  // Pure helpers — no IO
53
53
  // ---------------------------------------------------------------------------
54
54
  export function buildTop3ErrorMessage(displayPath, candidates) {
55
- const candStr = candidates.map((c) => `${c.encoding}("${c.sample.slice(0, 20).replace(/"/g, "'")}")`).join(", ");
56
- return `[E_NOT_TEXT] Path is not a readable UTF-8 text file: ${displayPath}. Hashline editing only supports text files. Top-3 guesses: ${candStr}. Try read({encoding: "<encoding>"}) or set DSH_BETTER_EDIT_AUTO_GUESS_ENCODING=true to auto-decode.`;
55
+ const candStr = candidates
56
+ .map((c) => `${c.encoding}("${c.sample.slice(0, 20).replace(/"/g, "'")}")`)
57
+ .join(", ");
58
+ return `[MODEL] [E_UNSUPPORTED_FILE] Path is not a readable UTF-8 text file: ${displayPath}. Hashline editing only supports text files. Top-3 guesses: ${candStr}. Try read({encoding: "<encoding>"}) or set DSH_BETTER_EDIT_AUTO_GUESS_ENCODING=true to auto-decode.`;
57
59
  }
58
60
  function buildAutoGuessFooterFromCandidates(candidates) {
59
61
  // chardet path vs heuristic path share same footer shape, just score vs confidence
60
62
  const candsStr = candidates
61
63
  .map((c) => {
62
- const score = c.confidence !== undefined ? String(c.confidence) : c.score !== undefined ? c.score.toFixed(0) : "0";
64
+ const score = c.confidence !== undefined
65
+ ? String(c.confidence)
66
+ : c.score !== undefined
67
+ ? c.score.toFixed(0)
68
+ : "0";
63
69
  return `${c.encoding} ${score}`;
64
70
  })
65
71
  .join(", ");
66
72
  const top = candidates[0];
67
- const topScore = top.confidence !== undefined ? String(top.confidence) : top.score !== undefined ? top.score.toFixed(0) : "0";
73
+ const topScore = top.confidence !== undefined
74
+ ? String(top.confidence)
75
+ : top.score !== undefined
76
+ ? top.score.toFixed(0)
77
+ : "0";
68
78
  return `\n\n[Auto-guessed: ${top.encoding} ${topScore}, candidates: ${candsStr} — re-read with read({encoding}) if garbled]`;
69
79
  }
70
80
  function isMidConfidenceChardet(top, second) {
@@ -76,7 +86,7 @@ function isMidConfidenceHeuristic(best, second) {
76
86
  /**
77
87
  * Deterministic admission for a raw byte buffer. No IO, no side effects
78
88
  * except Top-3 scoring. Caller owns recording the returned state via
79
- * `recordOpenState` and handling the footer vs E_NOT_TEXT split.
89
+ * `recordOpenState` and handling the footer vs E_UNSUPPORTED_FILE split.
80
90
  *
81
91
  * Order is fixed: BOM sniff always precedes strict UTF-8, which always
82
92
  * precedes guessing. Probabilistic encodings are last resort, gated by
@@ -95,7 +105,12 @@ export async function decodeForOpen(bytes, config, opts = {}) {
95
105
  const slice = bom ? bytes.subarray(off) : bytes;
96
106
  // For BOM encodings, decode the full bytes (including BOM) via helper; otherwise hint
97
107
  let decoded;
98
- if (bom && (bom.encoding === "utf8bom" || bom.encoding === "utf16le" || bom.encoding === "utf16be" || bom.encoding === "utf32le" || bom.encoding === "utf32be")) {
108
+ if (bom &&
109
+ (bom.encoding === "utf8bom" ||
110
+ bom.encoding === "utf16le" ||
111
+ bom.encoding === "utf16be" ||
112
+ bom.encoding === "utf32le" ||
113
+ bom.encoding === "utf32be")) {
99
114
  // When hint differs from BOM, hint takes precedence for decoding the slice
100
115
  // but we preserve hasBOM from BOM sniff. For utf variants, BOM encoding
101
116
  // already handled; for explicit hint we decode slice with hint.
@@ -166,7 +181,11 @@ export async function decodeForOpen(bytes, config, opts = {}) {
166
181
  hasBOM: false,
167
182
  lineEnding: detectEnding(dec),
168
183
  footer,
169
- candidates: chardetCands.map((c) => ({ encoding: c.encoding, sample: c.sample, score: c.confidence })),
184
+ candidates: chardetCands.map((c) => ({
185
+ encoding: c.encoding,
186
+ sample: c.sample,
187
+ score: c.confidence,
188
+ })),
170
189
  };
171
190
  }
172
191
  }
@@ -196,15 +215,19 @@ export async function decodeForOpen(bytes, config, opts = {}) {
196
215
  };
197
216
  }
198
217
  }
199
- // No candidate succeeded — fall through to E_NOT_TEXT with Top-3
218
+ // No candidate succeeded — fall through to E_UNSUPPORTED_FILE with Top-3
200
219
  }
201
- // 5) E_NOT_TEXT + Top-3 always pushed (even when autoGuess off)
220
+ // 5) E_UNSUPPORTED_FILE + Top-3 always pushed (even when autoGuess off)
202
221
  // Use chardet Top-3 when available, else heuristic Top-3 — same as fs-bridge fallback
203
222
  let candidates = [];
204
223
  try {
205
224
  const chardetCands = await chardetTop3Candidates(bytes, config.supportedEncodings);
206
225
  if (chardetCands.length > 0) {
207
- candidates = chardetCands.map((c) => ({ encoding: c.encoding, sample: c.sample, score: c.confidence }));
226
+ candidates = chardetCands.map((c) => ({
227
+ encoding: c.encoding,
228
+ sample: c.sample,
229
+ score: c.confidence,
230
+ }));
208
231
  }
209
232
  else {
210
233
  candidates = top3Candidates(bytes, config.supportedEncodings);
@@ -233,6 +256,9 @@ export function recordFooter(targetKey, footer) {
233
256
  if (footer)
234
257
  setAutoGuessFooter(targetKey, footer);
235
258
  }
259
+ /** Shared UTF-8 BOM marker — single source for the BOM round-trip seam.
260
+ * Prefer `prepareForSave` / `stripBOM` over re-implementing this check. */
261
+ export const UTF8_BOM = "\uFEFF";
236
262
  /**
237
263
  * Decide what bytes (as text, since provider expects string) to write and
238
264
  * what new state to record. BOM and lineEnding are restored here when a
@@ -253,11 +279,24 @@ export function prepareForSave(content, existingState, opts = {}) {
253
279
  newState: { encoding: norm, hasBOM, lineEnding, version: undefined },
254
280
  };
255
281
  }
256
- if (existingState && !opts.normalizeToUtf8 && existingState.encoding !== "utf8" && existingState.encoding !== "utf8bom") {
282
+ if (existingState &&
283
+ !opts.normalizeToUtf8 &&
284
+ existingState.encoding !== "utf8" &&
285
+ existingState.encoding !== "utf8bom") {
257
286
  // Legacy file, normalize false — preserve memo on wire (no transcode),
258
287
  // provider writes UTF-8 string, version bump will invalidate on next read.
259
288
  return { textToWrite: content };
260
289
  }
261
- // Default: UTF-8 without BOM, preserve lineEnding if known
262
- return { textToWrite: content };
290
+ // Default: restore recorded BOM + lineEnding via the shared seam so
291
+ // governed writers (e.g. the str_replace_editor shadow) don't re-implement
292
+ // the round-trip locally and diverge on future utf16le/lineEnding evolution.
293
+ // Only add, never strip: a missing memo means UTF-8 without BOM + LF.
294
+ let textToWrite = content;
295
+ if (existingState?.lineEnding) {
296
+ textToWrite = restoreEndings(toLF(textToWrite), existingState.lineEnding);
297
+ }
298
+ if (existingState?.hasBOM && !textToWrite.startsWith(UTF8_BOM)) {
299
+ textToWrite = `${UTF8_BOM}${textToWrite}`;
300
+ }
301
+ return { textToWrite };
263
302
  }
package/lib/file-view.js CHANGED
@@ -21,7 +21,7 @@ import { constants } from "node:fs";
21
21
  import { open as fsOpen, stat as fsStat } from "fs/promises";
22
22
  import { access as fsAccess } from "fs/promises";
23
23
  import { fileTypeFromBuffer } from "file-type";
24
- import { SNIFF_BYTES, MAX_BYTES, MAX_READ_LINE_BYTES } from "./constants.js";
24
+ import { SNIFF_BYTES, MAX_BYTES, MAX_READ_LINE_BYTES, eLargeFileMsg } from "./constants.js";
25
25
  import { lineHashes, fmtRegion, HASH_SEP } from "./hashline/index.js";
26
26
  import { HASH_SPACE } from "./hashline/hash-assign.js";
27
27
  import { visLines, abortIf, errCode } from "./utils.js";
@@ -33,8 +33,8 @@ export const DEFAULT_MAX_BYTES = 50 * 1024;
33
33
  function splitLinesForCounting(content) {
34
34
  if (content.length === 0)
35
35
  return [];
36
- const lines = content.split('\n');
37
- if (content.endsWith('\n'))
36
+ const lines = content.split("\n");
37
+ if (content.endsWith("\n"))
38
38
  lines.pop();
39
39
  return lines;
40
40
  }
@@ -48,7 +48,7 @@ export function formatSize(bytes) {
48
48
  export function truncateHead(content, options = {}) {
49
49
  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
50
50
  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
51
- const totalBytes = Buffer.byteLength(content, 'utf-8');
51
+ const totalBytes = Buffer.byteLength(content, "utf-8");
52
52
  const lines = splitLinesForCounting(content);
53
53
  const totalLines = lines.length;
54
54
  if (totalLines <= maxLines && totalBytes <= maxBytes) {
@@ -66,12 +66,12 @@ export function truncateHead(content, options = {}) {
66
66
  maxBytes,
67
67
  };
68
68
  }
69
- const firstLineBytes = Buffer.byteLength(lines[0] ?? '', 'utf-8');
69
+ const firstLineBytes = Buffer.byteLength(lines[0] ?? "", "utf-8");
70
70
  if (firstLineBytes > maxBytes) {
71
71
  return {
72
- content: '',
72
+ content: "",
73
73
  truncated: true,
74
- truncatedBy: 'bytes',
74
+ truncatedBy: "bytes",
75
75
  totalLines,
76
76
  totalBytes,
77
77
  outputLines: 0,
@@ -84,22 +84,22 @@ export function truncateHead(content, options = {}) {
84
84
  }
85
85
  const outputLinesArr = [];
86
86
  let outputBytesCount = 0;
87
- let truncatedBy = 'lines';
87
+ let truncatedBy = "lines";
88
88
  for (let i = 0; i < lines.length && i < maxLines; i++) {
89
89
  const line = lines[i];
90
- const lineBytes = Buffer.byteLength(line, 'utf-8') + (i > 0 ? 1 : 0);
90
+ const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0);
91
91
  if (outputBytesCount + lineBytes > maxBytes) {
92
- truncatedBy = 'bytes';
92
+ truncatedBy = "bytes";
93
93
  break;
94
94
  }
95
95
  outputLinesArr.push(line);
96
96
  outputBytesCount += lineBytes;
97
97
  }
98
98
  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
99
- truncatedBy = 'lines';
99
+ truncatedBy = "lines";
100
100
  }
101
- const outputContent = outputLinesArr.join('\n');
102
- const finalOutputBytes = Buffer.byteLength(outputContent, 'utf-8');
101
+ const outputContent = outputLinesArr.join("\n");
102
+ const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
103
103
  return {
104
104
  content: outputContent,
105
105
  truncated: true,
@@ -115,12 +115,7 @@ export function truncateHead(content, options = {}) {
115
115
  };
116
116
  }
117
117
  // --- File kind (from file-kind.ts, private) ---
118
- const IMG_TYPES = new Set([
119
- "image/jpeg",
120
- "image/png",
121
- "image/gif",
122
- "image/webp",
123
- ]);
118
+ const IMG_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
124
119
  const TEXT_TYPES = new Set([
125
120
  "application/rtf",
126
121
  "application/xml",
@@ -181,8 +176,7 @@ export async function loadFileKindAndText(filePath, options) {
181
176
  };
182
177
  }
183
178
  const detectedMimeType = (await fileTypeFromBuffer(sample))?.mime;
184
- if (detectedMimeType !== undefined &&
185
- !isTextType(detectedMimeType)) {
179
+ if (detectedMimeType !== undefined && !isTextType(detectedMimeType)) {
186
180
  if (IMG_TYPES.has(detectedMimeType)) {
187
181
  return { kind: "image", mimeType: detectedMimeType };
188
182
  }
@@ -206,7 +200,7 @@ export async function loadFileKindAndText(filePath, options) {
206
200
  newlineCount++;
207
201
  }
208
202
  if (newlineCount > options.maxLines) {
209
- throw new Error(`[E_FILE_TOO_LARGE] ${options.displayPath ?? filePath} has more than ${options.maxLines} lines, exceeding the ${options.maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`);
203
+ throw new Error(eLargeFileMsg(options.displayPath ?? filePath, newlineCount, options.maxLines));
210
204
  }
211
205
  }
212
206
  return decoded;
@@ -241,27 +235,27 @@ export async function valAccess(absolutePath, path, accessMode = constants.R_OK)
241
235
  catch (error) {
242
236
  const code = errCode(error);
243
237
  if (code === "ENOENT") {
244
- throw new Error(`[E_NOT_FOUND] File not found: ${path}`);
238
+ throw new Error(`[MODEL] [E_NOT_FOUND] File not found: ${path}`);
245
239
  }
246
240
  if (code === "EACCES" || code === "EPERM") {
247
241
  const accessLabel = accessMode & constants.W_OK ? "not writable" : "not readable";
248
- throw new Error(`[E_ACCESS] File is ${accessLabel}: ${path}`);
242
+ throw new Error(`[MODEL] [E_ACCESS] File is ${accessLabel}: ${path}`);
249
243
  }
250
244
  if (code === "ELOOP") {
251
- throw new Error(`[E_ACCESS] Too many symbolic links while resolving: ${path}`);
245
+ throw new Error(`[MODEL] [E_ACCESS] Too many symbolic links while resolving: ${path}`);
252
246
  }
253
- throw new Error(`[E_ACCESS] Cannot access file: ${path}`);
247
+ throw new Error(`[MODEL] [E_ACCESS] Cannot access file: ${path}`);
254
248
  }
255
249
  }
256
250
  export function valKind(file, path) {
257
251
  if (file.kind === "directory") {
258
- throw new Error(`[E_NOT_TEXT] Path is a directory: ${path}. Use ls to inspect directories.`);
252
+ throw new Error(`[MODEL] [E_UNSUPPORTED_FILE] Path is a directory: ${path}.`);
259
253
  }
260
254
  if (file.kind === "binary") {
261
- throw new Error(`[E_NOT_TEXT] Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`);
255
+ throw new Error(`[MODEL] [E_UNSUPPORTED_FILE] Path is a binary file: ${path} (${file.description}). Hashline edit only supports text files.`);
262
256
  }
263
257
  if (file.kind === "image") {
264
- throw new Error(`[E_NOT_TEXT] Path is an image file: ${path}. Hashline edit only supports text files.`);
258
+ throw new Error(`[MODEL] [E_UNSUPPORTED_FILE] Path is an image file: ${path}. Hashline edit only supports text files.`);
265
259
  }
266
260
  }
267
261
  function fmtSnapId(canonicalPath, info) {
@@ -287,10 +281,10 @@ export async function normFromText(input) {
287
281
  if (input.maxLines !== undefined) {
288
282
  const lineCount = visLines(normalized).length;
289
283
  if (lineCount > input.maxLines) {
290
- throw new Error(`[E_FILE_TOO_LARGE] ${displayPath} has ${lineCount} lines, exceeding the ${input.maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`);
284
+ throw new Error(eLargeFileMsg(displayPath, lineCount, input.maxLines));
291
285
  }
292
286
  }
293
- const fileHashes = await lineHashes(normalized, absolutePath, undefined, input.store, input.noPersist !== true, input.reservedHashes, input.retiredHashes);
287
+ const fileHashes = await lineHashes(normalized, absolutePath, input.previous, input.store, input.noPersist !== true, input.reservedHashes, input.retiredHashes);
294
288
  return {
295
289
  absolutePath,
296
290
  normalized,
@@ -325,6 +319,7 @@ export async function readNormFile(path, cwd, options) {
325
319
  reservedHashes: options?.reservedHashes,
326
320
  retiredHashes: options?.retiredHashes,
327
321
  hadUtf8DecodeErrors: file.hadUtf8DecodeErrors,
322
+ previous: options?.previous,
328
323
  });
329
324
  }
330
325
  // --- Read render (from read-render.ts, private) ---
@@ -332,22 +327,21 @@ function normPosInt(value, name) {
332
327
  if (value === undefined)
333
328
  return undefined;
334
329
  if (!Number.isInteger(value) || value < 1) {
335
- throw new Error(`[E_BAD_SHAPE] Read request field "${name}" must be a positive integer.`);
330
+ throw new Error(`[MODEL] [E_BAD_PAYLOAD] Read request field "${name}" must be a positive integer.`);
336
331
  }
337
332
  return value;
338
333
  }
339
334
  export function formatPaginationHint(startLine, endLine, totalLines, nextOffset, byteLimit) {
340
- const sizeSuffix = byteLimit !== undefined ? ` (${formatSize(byteLimit)} limit)` : '';
335
+ const sizeSuffix = byteLimit !== undefined ? ` (${formatSize(byteLimit)} limit)` : "";
341
336
  return `[Showing lines ${startLine}-${endLine} of ${totalLines}${sizeSuffix}. Use offset=${nextOffset} to continue.]`;
342
337
  }
343
338
  export async function fmtReadPreview(text, options, precomputedHashes, path, maxLineBytes = MAX_READ_LINE_BYTES, maxTruncLines = DEFAULT_MAX_LINES) {
344
339
  const allLines = visLines(text);
345
340
  const totalLines = allLines.length;
346
- const startLine = normPosInt(options.offset, 'offset') ?? 1;
341
+ const startLine = normPosInt(options.offset, "offset") ?? 1;
347
342
  if (totalLines === 0) {
348
343
  if (startLine === 1) {
349
- const allHashes = precomputedHashes ??
350
- (await (path ? lineHashes(text, path) : lineHashes(text)));
344
+ const allHashes = precomputedHashes ?? (await (path ? lineHashes(text, path) : lineHashes(text)));
351
345
  const emptyLineHash = allHashes[0];
352
346
  return {
353
347
  text: `${emptyLineHash}${HASH_SEP}\n[File is empty. Use edit to insert content.]`,
@@ -365,43 +359,37 @@ export async function fmtReadPreview(text, options, precomputedHashes, path, max
365
359
  served: [],
366
360
  };
367
361
  }
368
- const limit = normPosInt(options.limit, 'limit');
369
- const endIdx = limit
370
- ? Math.min(startLine - 1 + limit, totalLines)
371
- : totalLines;
362
+ const limit = normPosInt(options.limit, "limit");
363
+ const endIdx = limit ? Math.min(startLine - 1 + limit, totalLines) : totalLines;
372
364
  const selected = allLines.slice(startLine - 1, endIdx);
373
- const allHashes = precomputedHashes ??
374
- (await (path ? lineHashes(text, path) : lineHashes(text)));
365
+ const allHashes = precomputedHashes ?? (await (path ? lineHashes(text, path) : lineHashes(text)));
375
366
  const selectedHashes = allHashes.slice(startLine - 1, endIdx);
376
367
  const formatted = fmtRegion(selectedHashes, selected);
377
368
  const maxBytes = maxLineBytes;
378
369
  const rowSizes = selected.map((line, index) => ({
379
370
  lineNumber: startLine + index,
380
- bytes: Buffer.byteLength(`${selectedHashes[index]}${HASH_SEP}${line}`, 'utf-8'),
371
+ bytes: Buffer.byteLength(`${selectedHashes[index]}${HASH_SEP}${line}`, "utf-8"),
381
372
  }));
382
373
  if (rowSizes.some((row) => row.bytes > maxBytes)) {
383
374
  const oversized = rowSizes.filter((row) => row.bytes > maxBytes);
384
375
  const rows = rowSizes.map((row, index) => row.bytes > maxBytes
385
376
  ? `[Line ${row.lineNumber} is ${formatSize(row.bytes)}, exceeds ${formatSize(maxBytes)}; content not shown. Use bash: sed -n '${row.lineNumber}p' <path> | head -c ${maxBytes}]`
386
377
  : fmtRegion([selectedHashes[index]], [selected[index]]));
387
- const skippedTruncation = truncateHead(rows.join('\n'), {
378
+ const skippedTruncation = truncateHead(rows.join("\n"), {
388
379
  maxBytes,
389
380
  maxLines: maxTruncLines,
390
381
  });
391
- const shownRowCount = skippedTruncation.content === ''
392
- ? 0
393
- : skippedTruncation.content.split('\n').length;
382
+ const shownRowCount = skippedTruncation.content === "" ? 0 : skippedTruncation.content.split("\n").length;
394
383
  const lastShownLine = shownRowCount > 0 ? startLine + shownRowCount - 1 : startLine - 1;
395
384
  const lineLabel = oversized.length === 1
396
385
  ? `Line ${oversized[0].lineNumber}`
397
- : `Lines ${oversized.map((row) => row.lineNumber).join(', ')}`;
398
- const verb = oversized.length === 1 ? 'exceeds' : 'exceed';
399
- const addresses = oversized.map((row) => `${row.lineNumber}p`).join(';');
386
+ : `Lines ${oversized.map((row) => row.lineNumber).join(", ")}`;
387
+ const verb = oversized.length === 1 ? "exceeds" : "exceed";
388
+ const addresses = oversized.map((row) => `${row.lineNumber}p`).join(";");
400
389
  const warning = `[${lineLabel} ${verb} ${formatSize(maxBytes)}; content not shown because hashline anchors require full lines. Inspect with bash: sed -n '${addresses}' <path> | head -c ${maxBytes}]`;
401
390
  let preview = skippedTruncation.content;
402
391
  let nextOffset;
403
- if (shownRowCount > 0 &&
404
- (skippedTruncation.truncated || lastShownLine < totalLines)) {
392
+ if (shownRowCount > 0 && (skippedTruncation.truncated || lastShownLine < totalLines)) {
405
393
  nextOffset = lastShownLine + 1;
406
394
  preview += `\n\n${warning}\n${formatPaginationHint(startLine, lastShownLine, totalLines, nextOffset, skippedTruncation.truncated ? skippedTruncation.maxBytes : undefined)}`;
407
395
  }
@@ -433,7 +421,7 @@ export async function fmtReadPreview(text, options, precomputedHashes, path, max
433
421
  if (truncation.truncated) {
434
422
  const endLineDisplay = startLine + truncation.outputLines - 1;
435
423
  nextOffset = endLineDisplay + 1;
436
- if (truncation.truncatedBy === 'lines') {
424
+ if (truncation.truncatedBy === "lines") {
437
425
  preview += `\n\n${formatPaginationHint(startLine, endLineDisplay, totalLines, nextOffset)}`;
438
426
  }
439
427
  else {
@@ -473,6 +461,7 @@ export async function readView(io, path, cwd, opts = {}) {
473
461
  maxLines: MAX_HASH_LINES,
474
462
  reservedHashes: opts.reservedHashes,
475
463
  retiredHashes: opts.retiredHashes,
464
+ previous: opts.previous,
476
465
  });
477
466
  const r = await fmtReadPreview(normalized, { offset: opts.offset, limit: opts.limit }, fileHashes, absolutePath);
478
467
  return {
package/lib/fs-bridge.js CHANGED
@@ -20,6 +20,7 @@ import { loadConfig } from "./store-config.js";
20
20
  import { fileSnap } from "./file-reader.js";
21
21
  import { resolveTarget, toCwd } from "./paths.js";
22
22
  import { decodeForOpen, recordOpenState, recordFooter, getEncodingState as _getEncodingState, setEncodingState as _setEncodingState, clearEncodingState as _clearEncodingState, getAutoGuessFooter as _getAutoGuessFooter, setAutoGuessFooter as _setAutoGuessFooter, clearAutoGuessFooter as _clearAutoGuessFooter, invalidateIfStale, prepareForSave, } from "./file-encoding-state.js";
23
+ import { codeOf } from "./utils.js";
23
24
  export { _getEncodingState as getEncodingState, _setEncodingState as setEncodingState, _clearEncodingState as clearEncodingState, _getAutoGuessFooter as getAutoGuessFooter, _setAutoGuessFooter as setAutoGuessFooter, _clearAutoGuessFooter as clearAutoGuessFooter, };
24
25
  // Keep alias for tests that import getAutoGuessFooter via fs-bridge
25
26
  export function getAutoGuessFooterCompat(k) {
@@ -33,17 +34,16 @@ export function getAutoGuessFooterCompat(k) {
33
34
  * @returns the mapped error, rethrown.
34
35
  */
35
36
  export function mapFsError(error, displayPath) {
36
- if (error instanceof Error &&
37
- typeof error.code === "string") {
37
+ if (error instanceof Error && typeof error.code === "string") {
38
38
  const code = error.code;
39
39
  if (code === "FS_NOT_FOUND") {
40
- throw new Error(`[E_NOT_FOUND] File not found: ${displayPath}`);
40
+ throw new Error(`[MODEL] [E_NOT_FOUND] File not found: ${displayPath}`);
41
41
  }
42
42
  if (code === "FS_PERMISSION_DENIED") {
43
- throw new Error(`[E_ACCESS] Cannot access file: ${displayPath}`);
43
+ throw new Error(`[MODEL] [E_ACCESS] Cannot access file: ${displayPath}`);
44
44
  }
45
45
  if (code === "FS_NOT_TEXT" || code === "FS_NOT_REGULAR_FILE") {
46
- throw new Error(`[E_NOT_TEXT] Path is not a readable UTF-8 text file: ${displayPath}. Hashline editing only supports text files. Try read({encoding: "gbk"}) or enable autoGuessEncoding.`);
46
+ throw new Error(`[MODEL] [E_UNSUPPORTED_FILE] Path is not a readable UTF-8 text file: ${displayPath}. Hashline editing only supports text files. Try read({encoding: "gbk"}) or enable autoGuessEncoding.`);
47
47
  }
48
48
  if (code === "FS_BAD_ENCODING") {
49
49
  throw new Error(`[E_BAD_ENCODING] Unknown encoding for ${displayPath}. Supported: utf8, gbk, big5, shift_jis, euc-kr, windows-1251, iso-8859-1`);
@@ -52,7 +52,7 @@ export function mapFsError(error, displayPath) {
52
52
  throw new Error(`[E_DECODE_FAILED] Bytes in ${displayPath} cannot be decoded with requested encoding.`);
53
53
  }
54
54
  if (code === "FS_STALE_VERSION") {
55
- throw new Error(`[E_RANGE_STALE] The file changed on disk since it was read (version guard rejected the write). Call read() to get fresh anchors, then retry.`);
55
+ throw new Error(`[MODEL] [E_STALE_RANGE] The file changed on disk since it was read (version guard rejected the write). Call read() to get fresh anchors, then retry.`);
56
56
  }
57
57
  if (code === "FS_NOT_OBSERVED") {
58
58
  throw new Error(`[E_NOT_OBSERVED] The file has not been observed in this session (read-before-write policy). Call read() first, then retry the edit.`);
@@ -82,8 +82,7 @@ async function restoreStrippedUtf8Bom(fs, target, text, signal) {
82
82
  if (text.startsWith(UTF8_BOM))
83
83
  return text;
84
84
  const info = await fs.stat(target, signal);
85
- if (info?.size === undefined ||
86
- info.size !== Buffer.byteLength(text, "utf-8") + UTF8_BOM_LEN) {
85
+ if (info?.size === undefined || info.size !== Buffer.byteLength(text, "utf-8") + UTF8_BOM_LEN) {
87
86
  return text;
88
87
  }
89
88
  const bytes = await fs.readBytes(target, signal, info.size);
@@ -113,12 +112,17 @@ export function ctxFsIO(fs, ctx) {
113
112
  async readText(absolutePath, signal, encodingHint) {
114
113
  // explicit encoding override (Reopen with Encoding) — bytes + seam
115
114
  if (encodingHint) {
116
- const target = await fs.resolve(absolutePath, { ...(signal === undefined ? {} : { signal }) });
115
+ const target = await fs.resolve(absolutePath, {
116
+ ...(signal === undefined ? {} : { signal }),
117
+ });
117
118
  const info = await fs.stat(target, signal);
118
119
  const maxBytes = info?.size ?? 10 * 1024 * 1024;
119
120
  const bytes = await fs.readBytes(target, signal, maxBytes);
120
121
  const cfg = loadConfig();
121
- const decoded = await decodeForOpen(bytes, cfg, { encodingHint, displayPath: absolutePath });
122
+ const decoded = await decodeForOpen(bytes, cfg, {
123
+ encodingHint,
124
+ displayPath: absolutePath,
125
+ });
122
126
  const targetKey = String(target.targetKey ?? absolutePath);
123
127
  recordOpenState(targetKey, decoded.text, decoded.encoding, decoded.hasBOM, info?.version);
124
128
  if (decoded.footer)
@@ -153,7 +157,9 @@ export function ctxFsIO(fs, ctx) {
153
157
  const isNotText = error instanceof Error && error.code === "FS_NOT_TEXT";
154
158
  if (isNotText) {
155
159
  const cfg = loadConfig();
156
- const target = await fs.resolve(absolutePath, { ...(signal === undefined ? {} : { signal }) });
160
+ const target = await fs.resolve(absolutePath, {
161
+ ...(signal === undefined ? {} : { signal }),
162
+ });
157
163
  const info = await fs.stat(target, signal);
158
164
  const maxBytes = info?.size ?? 10 * 1024 * 1024;
159
165
  if (info && info.size !== undefined && info.size > maxBytes)
@@ -173,7 +179,9 @@ export function ctxFsIO(fs, ctx) {
173
179
  async writeText(absolutePath, content, signal, exec, sandboxPolicy) {
174
180
  // handle drift invalidation before encode — seam owns version check
175
181
  try {
176
- const targetTmp = await fs.resolve(absolutePath, { ...(signal === undefined ? {} : { signal }) });
182
+ const targetTmp = await fs.resolve(absolutePath, {
183
+ ...(signal === undefined ? {} : { signal }),
184
+ });
177
185
  const key = String(targetTmp.targetKey ?? absolutePath);
178
186
  const info = await fs.stat(targetTmp, signal).catch(() => undefined);
179
187
  invalidateIfStale(key, info?.version);
@@ -247,14 +255,17 @@ export function localIO() {
247
255
  if (encodingHint) {
248
256
  const bytes = await readFile(absolutePath);
249
257
  const cfg = loadConfig();
250
- const decoded = await decodeForOpen(bytes, cfg, { encodingHint, displayPath: absolutePath });
258
+ const decoded = await decodeForOpen(bytes, cfg, {
259
+ encodingHint,
260
+ displayPath: absolutePath,
261
+ });
251
262
  const info = await fileSnap(absolutePath).catch(() => undefined);
252
263
  recordOpenState(absolutePath, decoded.text, decoded.encoding, decoded.hasBOM, info?.snapshotId);
253
264
  if (decoded.footer)
254
265
  recordFooter(absolutePath, decoded.footer);
255
266
  return decoded.text;
256
267
  }
257
- // Deterministic path via seam, with local fallback for E_NOT_TEXT when autoGuess off
268
+ // Deterministic path via seam, with local fallback for E_UNSUPPORTED_FILE when autoGuess off
258
269
  try {
259
270
  const bytes = await readFile(absolutePath);
260
271
  const cfgL = loadConfig();
@@ -266,8 +277,8 @@ export function localIO() {
266
277
  return decoded.text;
267
278
  }
268
279
  catch (error) {
269
- // Local fallback: when autoGuess off, E_NOT_TEXT should fall back to raw UTF-8 with � (no throw)
270
- if (error instanceof Error && error.message.includes("[E_NOT_TEXT]")) {
280
+ // Local fallback: when autoGuess off, E_UNSUPPORTED_FILE should fall back to raw UTF-8 with � (no throw)
281
+ if (codeOf(error) === "E_UNSUPPORTED_FILE") {
271
282
  return readFile(absolutePath, "utf-8");
272
283
  }
273
284
  throw error;
package/lib/fs-write.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { mkdir, open, readdir, rename, rm, stat, writeFile, } from "fs/promises";
2
+ import { mkdir, open, readdir, rename, rm, stat, writeFile } from "fs/promises";
3
3
  import { dirname, join } from "node:path";
4
4
  import { errCode } from "./utils.js";
5
5
  import { resolveTarget } from "./paths.js";