pi-hashline-edit-pro 2.7.1 → 2.8.0

package/src/replace-render.ts

@@ -1,8 +1,9 @@
 import { Markdown, Text } from "@earendil-works/pi-tui";
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import { normReq } from "./replace-normalize";
-import type { ReqParams, ReplaceDetails } from "./replace";
-import { isRec } from "./utils";
+import { keyHint, type Theme } from "@earendil-works/pi-coding-agent";
+import type { ReplaceDetails } from "./replace";
+import { withLineNumbers } from "./utils";
+import { getPreviewInput } from "./payload-contract";
+export { getPreviewInput };
 
 export type FgT = Pick<Theme, "fg">;
 export type CallT = Pick<Theme, "fg" | "bold">;
@@ -20,42 +21,12 @@ export type RRState = {
 	previewTimer?: ReturnType<typeof setTimeout>;
 };
 
-export function getPreviewInput(
-	args: unknown,
-): ReqParams | null {
-	let normalized: unknown;
-	try {
-		normalized = normReq(args);
-	} catch {
-		return null;
-	}
-	if (!isRec(normalized) || typeof normalized.path !== "string") {
-		return null;
-	}
-
-	if (
-		typeof normalized.remove_from !== "string" ||
-		typeof normalized.remove_to !== "string" ||
-		!Array.isArray(normalized.replacement_lines) ||
-		normalized.replacement_lines.some((line) => typeof line !== "string")
-	) {
-		return null;
-	}
-
-	const request: ReqParams = {
-		path: normalized.path,
-		remove_from: normalized.remove_from,
-		remove_to: normalized.remove_to,
-		replacement_lines: normalized.replacement_lines,
-	};
-	return request;
-}
-
 type DiffRowKind = "added" | "removed" | "context";
 
 function diffRowKind(line: string): DiffRowKind {
-	if (line.startsWith("+") && !line.startsWith("+++")) return "added";
-	if (line.startsWith("-") && !line.startsWith("---")) return "removed";
+	const stripped = line.replace(/^\s*\d+\s+│\s*/, "");
+	if (stripped.startsWith("+") && !stripped.startsWith("+++")) return "added";
+	if (stripped.startsWith("-") && !stripped.startsWith("---")) return "removed";
 	return "context";
 }
 
@@ -67,6 +38,9 @@ export function colorLines(lines: string[], theme: FgT): string[] {
 		return theme.fg("dim", line);
 	});
 }
+export function toNumberedDiff(diff: string, lineNumbers: (number|undefined)[]): string {
+	return withLineNumbers(diff, lineNumbers);
+}
 
 export function fmtPreview(
 	diff: string,
@@ -145,20 +119,47 @@ export function isApplied(
 	);
 }
 
+const RESULT_PREVIEW_LINES = 16;
+
+function expandHint(): string {
+	try {
+		return keyHint("app.tools.expand", "to expand");
+	} catch {
+		return "ctrl+o to expand";
+	}
+}
+
+function extractSummary(text: string | undefined): string | undefined {
+	if (!text) return undefined;
+	if (text.includes("│")) return undefined;
+	const warningsIdx = text.indexOf("\n\nWarnings:");
+	const summary = warningsIdx >= 0 ? text.slice(0, warningsIdx) : text;
+	return summary.length > 0 ? summary : undefined;
+}
+
 export function buildAppliedText(
 	text: string | undefined,
 	details: ReplaceDetails | undefined,
 	theme: FgT,
+	expanded: boolean,
 ): string | undefined {
 	const sections: string[] = [];
-
+	const summary = extractSummary(text);
+	if (summary) sections.push(summary);
 	if (details?.diff) {
-		sections.push(fmtResult(details.diff, theme));
+		const rawDiff = details.diffLineNumbers ? toNumberedDiff(details.diff, details.diffLineNumbers) : details.diff;
+		const diffLines = details.diff.split("\n");
+		const diffSection = expanded
+			? fmtResult(rawDiff, theme)
+			: fmtPreview(rawDiff, false, theme);
+		const hint =
+			!expanded && diffLines.length > RESULT_PREVIEW_LINES
+				? ` (${expandHint()})`
+				: "";
+		sections.push(`${diffSection}${hint}`);
 	}
-
 	const warnings = extractWarnings(text);
 	if (warnings) sections.push(warnings);
-
 	return sections.length > 0 ? sections.join("\n\n") : undefined;
 }
 
@@ -296,10 +297,12 @@ export function makeRenderCall(
 
 export function renderEditResult(
 	result: { content?: Array<{ type: string; text?: string }>; details?: ReplaceDetails },
-	isPartial: boolean,
+	options: { isPartial: boolean; expanded?: boolean } | boolean,
 	theme: FgT,
 	context: any,
 ): Text | Markdown {
+	const isPartial = typeof options === "boolean" ? options : options.isPartial;
+	const optionsExpanded = typeof options === "boolean" ? undefined : options.expanded;
 	if (isPartial) return reuseText(context, theme.fg("warning", "Editing..."));
 	const renderedText = getResultText(result);
 	const renderState = context.state as RRState | undefined;
@@ -317,7 +320,8 @@ export function renderEditResult(
 			: new Text("", 0, 0);
 	}
 	if (isApplied(result.details)) {
-		const appliedText = buildAppliedText(renderedText, result.details, theme);
+		const isExpanded = optionsExpanded === true || context.expanded === true;
+		const appliedText = buildAppliedText(renderedText, result.details, theme, isExpanded);
 		return appliedText ? reuseText(context, appliedText) : new Text("", 0, 0);
 	}
 	if (!renderedText) return new Text("", 0, 0);

package/src/replace-response.ts

@@ -153,15 +153,18 @@ export function buildChanged(input: SuccessInput, verb = "replaced"): TResult {
     removedLines,
   });
 
+  const patchResult = genPatch(path, originalNormalized, result);
   return {
     content: [{ type: "text", text }],
     details: {
       diff: diffResult.diff,
-      patch: genPatch(path, originalNormalized, result),
+      patch: patchResult.patch,
+      ...(patchResult.truncated ? { patchTruncated: true as const } : {}),
       firstChangedLine:
         editMeta.firstChangedLine ?? diffResult.firstChangedLine,
       snapshotId,
       metrics,
+      diffLineNumbers: diffResult.lineNumbers,
     },
   };
 }

package/src/replace-undo.ts

@@ -2,15 +2,14 @@ import { readFile } from "fs/promises";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { loadHashStore, upsertSnapshot, upsertUndo, getUndoEntry, deleteUndo, type UndoRecord } from "./hash-store";
+import { loadHashStore, persistSnapshot, upsertUndo, getUndoEntry, deleteUndo, type UndoRecord } from "./hash-store";
 import { recordServedDiff } from "./served";
-import { contentChecksum } from "./hashline/hasher";
-import { resolveTarget, writeAtomic } from "./fs-write";
-import { toCwd } from "./paths";
+import { resolveInCwd, writeAtomic } from "./fs-write";
 import { toLF, stripBOM, genDiff, genPatch, restoreEndings, type LineEnding } from "./replace-diff";
-import { cntDiff, splitLines, errCode, makePrepareArguments } from "./utils";
+import { cntDiff, errCode, makePrepareArguments } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { buildMetrics } from "./replace-response";
+import { renderEditResult } from "./replace-render";
 import { changedRange, lineHashes } from "./hashline";
 export interface UndoEntry {
   content: string;
@@ -98,11 +97,13 @@ export function regUndo(pi: ExtensionAPI): void {
         description: "Path to the file to undo",
       }),
     }),
-
+    executionMode: "sequential",
+    renderResult(result, opts, theme, context) {
+      return renderEditResult(result as never, opts as { isPartial: boolean; expanded?: boolean }, theme as never, context as never);
+    },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const path = params.path;
-      const absolutePath = toCwd(path, ctx.cwd);
-      const mutationTargetPath = await resolveTarget(absolutePath);
+      const { resolved: mutationTargetPath } = await resolveInCwd(path, ctx.cwd);
 
       const undo = await getUndo(mutationTargetPath);
       if (!undo) {
@@ -149,15 +150,16 @@ export function regUndo(pi: ExtensionAPI): void {
 
         const currentNormalized = currentRaw === undefined ? "" : toLF(stripBOM(currentRaw).text);
         const currentHashes = await lineHashes(currentNormalized, mutationTargetPath);
-        const diffResult = genDiff(undo.content, undo.resultContent, 0, undefined, undo.hashes);
+        const diffResult = genDiff(undo.content, undo.resultContent, 0, undefined, undo.hashes, { unlimited: true });
         const linesAddedByReplace = cntDiff(diffResult.diff, "+");
         const linesRemovedByReplace = cntDiff(diffResult.diff, "-");
         const restoredRange = changedRange(currentNormalized, undo.content);
-        const undoDiff = genDiff(currentNormalized, undo.content, 1, undo.hashes, currentHashes).diff;
+        const undoDiffResult = genDiff(currentNormalized, undo.content, 1, undo.hashes, currentHashes);
+        const undoDiff = undoDiffResult.diff;
 
         try {
           const store = await loadHashStore();
-          upsertSnapshot(store, mutationTargetPath, contentChecksum(undo.content), splitLines(undo.content).length, undo.hashes);
+          persistSnapshot(store, mutationTargetPath, undo.content, undo.hashes);
           recordServedDiff(store, mutationTargetPath, undoDiff, new Set(undo.hashes));
         } catch (error) {
           console.error("Failed to restore hash store snapshot after undo:", error);
@@ -180,6 +182,7 @@ export function regUndo(pi: ExtensionAPI): void {
           "Call read for fresh anchors.",
         );
 
+        const patchResult = genPatch(path, currentNormalized, undo.content);
         return {
           content: [
             {
@@ -189,7 +192,9 @@ export function regUndo(pi: ExtensionAPI): void {
           ],
           details: {
             diff: undoDiff,
-            patch: genPatch(path, currentNormalized, undo.content),
+            diffLineNumbers: undoDiffResult.lineNumbers,
+            patch: patchResult.patch,
+            ...(patchResult.truncated ? { patchTruncated: true as const } : {}),
             metrics: buildMetrics({
               classification: "applied",
               editsAttempted: 1,

package/src/replace.ts

@@ -3,16 +3,16 @@ import type {
   ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 import { constants } from "fs";
 import {
   genDiff,
   type LineEnding,
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
-import { normReq } from "./replace-normalize";
-import { isRec, rejectUnknownFields, abortIf, makePrepareArguments } from "./utils";
-import { resolveTarget } from "./fs-write";
+import { editToolSchema, type ReqParams, assertReq, normReq } from "./payload-contract";
+import { isRec, abortIf, makePrepareArguments } from "./utils";
+import { loadP, loadGuide } from "./prompts";
+import { resolveInCwd } from "./fs-write";
 import { applyEdit,
   lineHashes,
   resEdit,
@@ -23,7 +23,7 @@ import { applyEdit,
   type HEdit,
   type NEdit,
 } from "./hashline";
-import { toCwd } from "./paths";
+import { commitEdit } from "./commit";
 import type { RMetrics } from "./replace-response";
 import {
   makeRenderCall,
@@ -31,54 +31,21 @@ import {
   type RPreview,
   type RRState,
 } from "./replace-render";
-import { loadP, loadGuide } from "./prompts";
 import { loadHashStore, findSnapshotPaths, findServedPaths, type HashStore } from "./hash-store";
 import { getServed, recordServedSafe } from "./served";
 import { noopPayloadKey, markBoundaryNoop, consumeBoundaryBypass, clearBoundaryBypass } from "./boundary-bypass";
-import { commitEdit } from "./commit";
-
-const replacementLinesSchema = Type.Array(
-  Type.String({
-    description:
-      "One replacement line. Each element is exactly one line; do not embed \\n inside an element: use separate elements.",
-  }),
-  {
-    description:
-      "Replacement lines as an array of strings, one element per line. Use [] to delete the range."
-  }
-);
-
-const removeFromSchema = Type.String({
-  description: "Bare 3-char HASH only (e.g. \"aB3\"): copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the FIRST line to remove (inclusive)",
-});
-
-const removeToSchema = Type.String({
-  description: "Bare 3-char HASH only (e.g. \"aB3\"): copy just the hash from the leftmost column of a read row like `aB3│content`; never the line content. Marks the LAST line to remove (inclusive)",
-});
 
-export const editToolSchema = Type.Object(
-  {
-    path: Type.Optional(Type.String({ description: "Path to edit. Required: always provide it explicitly; it is only auto-resolved from the anchors as a fallback when omitted by mistake." })),
-    remove_from: removeFromSchema,
-    remove_to: removeToSchema,
-    replacement_lines: replacementLinesSchema,
-  },
-  { additionalProperties: false },
-);
-export type ReqParams = {
-  path: string;
-  remove_from: string;
-  remove_to: string;
-  replacement_lines: string[];
-};
+export { editToolSchema, type ReqParams, assertReq };
 
 export type ReplaceDetails = {
   diff: string;
   patch?: string;
+  patchTruncated?: boolean;
   firstChangedLine?: number;
   snapshotId?: string;
   classification?: "noop";
   metrics?: RMetrics;
+  diffLineNumbers?: (number|undefined)[];
 };
 
 export interface PipelineResult {
@@ -100,33 +67,6 @@ export interface PipelineResult {
   boundaryRemovedLines: number;
 }
 
-const ROOT_KS = new Set(["path", "remove_from", "remove_to", "replacement_lines"]);
-
-export function assertReq(
-  request: unknown,
-): asserts request is ReqParams {
-  if (!isRec(request)) {
-    throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
-  }
-
-  rejectUnknownFields(request, ROOT_KS, "Edit request");
-
-  if (typeof request.path !== "string" || request.path.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "path" string.');
-  }
-
-  if (
-    typeof request.remove_from !== "string" ||
-    typeof request.remove_to !== "string" ||
-    !Array.isArray(request.replacement_lines) ||
-    request.replacement_lines.some((line) => typeof line !== "string")
-  ) {
-    throw new Error(
-      '[E_BAD_SHAPE] Edit request requires "remove_from", "remove_to", and "replacement_lines" (array of strings, one per line; use [] to delete).',
-    );
-  }
-}
-
 async function resolveMissingPath(
   request: Record<string, unknown>,
 ): Promise<{ path: string; warning: string } | undefined> {
@@ -172,21 +112,26 @@ export interface ExecPipelineOptions {
   preloadedNorm?: NormFile;
 }
 
+function hashSpan(hashes: string[], from: string, to: string): [number, number] | undefined {
+  const a = hashes.indexOf(from);
+  const b = hashes.indexOf(to);
+  if (a < 0 || b < 0) return undefined;
+  return [Math.min(a, b), Math.max(a, b)];
+}
+async function noteAnchorError(absolutePath: string, error: unknown, scopeHashes: string[], noPersist?: boolean): Promise<void> {
+  if (noPersist === true) return;
+  if (error instanceof RangeStaleError) await recordServedSafe(absolutePath, error.rangeHashes, "range-stale feedback", new Set(scopeHashes));
+  else if (error instanceof AnchorMismatchError) await recordServedSafe(absolutePath, error.feedbackHashes, "anchor-mismatch feedback", new Set(scopeHashes));
+}
+
 function collectRemovedHashes(
   edit: HEdit,
   originalHashes: string[],
 ): Set<string> {
+  const span = hashSpan(originalHashes, edit.hash_bounds[0].hash, edit.hash_bounds[1].hash);
   const removedHashes = new Set<string>();
-  const startHash = edit.hash_bounds[0].hash;
-  const endHash = edit.hash_bounds[1].hash;
-  const startLine = originalHashes.indexOf(startHash);
-  const endLine = originalHashes.indexOf(endHash);
-  if (startLine >= 0 && endLine >= 0) {
-    const firstLine = Math.min(startLine, endLine);
-    const lastLine = Math.max(startLine, endLine);
-    for (let i = firstLine; i <= lastLine; i++) {
-      removedHashes.add(originalHashes[i]!);
-    }
+  if (span) {
+    for (let i = span[0]; i <= span[1]; i++) removedHashes.add(originalHashes[i]!);
   }
   return removedHashes;
 }
@@ -198,12 +143,8 @@ function countLineChanges(
   removedAutoFixes: number,
 ): { totalAddedLines: number; totalRemovedLines: number } {
   if (isNoop) return { totalAddedLines: 0, totalRemovedLines: 0 };
-  let totalRemovedLines = 0;
-  const startLine = originalHashes.indexOf(edit.hash_bounds[0].hash);
-  const endLine = originalHashes.indexOf(edit.hash_bounds[1].hash);
-  if (startLine >= 0 && endLine >= 0) {
-    totalRemovedLines = Math.abs(endLine - startLine) + 1;
-  }
+  const span = hashSpan(originalHashes, edit.hash_bounds[0].hash, edit.hash_bounds[1].hash);
+  const totalRemovedLines = span ? span[1] - span[0] + 1 : 0;
   return {
     totalAddedLines: Math.max(0, edit.content_lines.length - removedAutoFixes),
     totalRemovedLines,
@@ -246,13 +187,7 @@ export async function execPipeline(
       options?.skipBoundaryDedup,
     );
   } catch (error) {
-    if (options?.noPersist !== true) {
-      if (error instanceof RangeStaleError) {
-        await recordServedSafe(absolutePath, error.rangeHashes, "range-stale feedback", new Set(originalHashes));
-      } else if (error instanceof AnchorMismatchError) {
-        await recordServedSafe(absolutePath, error.feedbackHashes, "anchor-mismatch feedback", new Set(originalHashes));
-      }
-    }
+    await noteAnchorError(absolutePath, error, originalHashes, options?.noPersist);
     throw error;
   }
 
@@ -295,6 +230,17 @@ export async function execPipeline(
   };
 }
 
+export function previewFromPipe(pipe: PipelineResult): RPreview {
+  if (pipe.originalNormalized === pipe.result) {
+    return {
+      error: `No changes made to ${pipe.path}. The edit produced identical content.`,
+    };
+  }
+  return { diff: genDiff(pipe.originalNormalized, pipe.result, 4, pipe.resultHashes, pipe.originalHashes).diff };
+}
+export function previewError(error: unknown): RPreview {
+  return { error: error instanceof Error ? error.message : String(error) };
+}
 export async function compPreview(
   request: unknown,
   cwd: string,
@@ -302,20 +248,14 @@ export async function compPreview(
   try {
     const normalized = normReq(request);
     assertReq(normalized);
-    const { path, originalNormalized, result, resultHashes, originalHashes } = await execPipeline(
+    const pipe = await execPipeline(
       normalized,
       cwd,
       { accessMode: constants.R_OK, noPersist: true },
     );
-    if (originalNormalized === result) {
-      return {
-        error: `No changes made to ${path}. The edit produced identical content.`,
-      };
-    }
-
-    return { diff: genDiff(originalNormalized, result, 4, resultHashes, originalHashes).diff };
+    return previewFromPipe(pipe);
   } catch (error: unknown) {
-    return { error: error instanceof Error ? error.message : String(error) };
+    return previewError(error);
   }
 }
 
@@ -325,12 +265,10 @@ type ToolDef = ToolDefinition<
   RRState
 > & { renderShell?: "default" | "self" };
 
-
 export function buildToolDef(): ToolDef {
   const E_DESC = loadP("../prompts/replace.md");
   const E_SNIPPET = loadP("../prompts/replace-snippet.md");
   const E_GUIDE = loadGuide("../prompts/replace-guidelines.md");
-
   const parameters = editToolSchema;
   return {
     name: "replace",
@@ -340,15 +278,16 @@ export function buildToolDef(): ToolDef {
     promptSnippet: E_SNIPPET,
     promptGuidelines: E_GUIDE,
     prepareArguments: makePrepareArguments(),
+    executionMode: "sequential",
     renderShell: "default",
     renderCall: makeRenderCall(compPreview),
-    renderResult(result, { isPartial }, theme, context) {
+    renderResult(result, { isPartial, expanded }, theme, context) {
       return renderEditResult(
         result as {
           content?: Array<{ type: string; text?: string }>;
           details?: ReplaceDetails;
         },
-        isPartial,
+        { isPartial, expanded },
         theme,
         context,
       );
@@ -364,8 +303,7 @@ export function buildToolDef(): ToolDef {
 
       const normalizedParams = canonical;
       const path = normalizedParams.path;
-      const absolutePath = toCwd(path, ctx.cwd);
-      const mutationTargetPath = await resolveTarget(absolutePath);
+      const { absolute: absolutePath, resolved: mutationTargetPath } = await resolveInCwd(path, ctx.cwd);
       const noopPayload = noopPayloadKey(mutationTargetPath, normalizedParams.remove_from, normalizedParams.remove_to, normalizedParams.replacement_lines);
       const boundaryBypass = consumeBoundaryBypass(mutationTargetPath, noopPayload);
       return withFileMutationQueue(mutationTargetPath, async () => {

package/src/served.ts

@@ -1,4 +1,4 @@
-import { loadHashStore, parseStoredHashes, type HashStore } from "./hash-store";
+import { loadHashStore, parseStoredHashes, STORE_NOT_OPEN_MESSAGE, withStore, type HashStore } from "./hash-store";
 import { HASH_CLASS } from "./hashline/alphabet";
 
 const SERVED_DIFF_ROW_RE = new RegExp(`^[+ ](${HASH_CLASS})│`);
@@ -19,14 +19,14 @@ export function getServed(store: HashStore, path: string): Set<string> | undefin
   return new Set(parsed);
 }
 
-export function recordServed(
+function computeUpdate(
   store: HashStore,
   path: string,
   hashes: string[],
   scope?: ReadonlySet<string>,
-): void {
+): Set<string> | undefined {
   const existing = getServed(store, path);
-  if (!existing && hashes.length === 0) return;
+  if (!existing && hashes.length === 0) return undefined;
   const set = existing ?? new Set<string>();
   let changed = false;
   if (scope) {
@@ -43,7 +43,28 @@ export function recordServed(
       changed = true;
     }
   }
-  if (!changed) return;
+  if (!changed) return undefined;
+  return set;
+}
+
+export function recordServed(
+  store: HashStore,
+  path: string,
+  hashes: string[],
+  scope?: ReadonlySet<string>,
+): void {
+  try {
+    withStore(() => {
+      const set = computeUpdate(store, path, hashes, scope);
+      if (!set) return;
+      store.stmts.servedUpsert(path, JSON.stringify([...set]), Date.now());
+    });
+    return;
+  } catch (error) {
+    if (!(error instanceof Error && error.message === STORE_NOT_OPEN_MESSAGE)) throw error;
+  }
+  const set = computeUpdate(store, path, hashes, scope);
+  if (!set) return;
   store.stmts.servedUpsert(path, JSON.stringify([...set]), Date.now());
 }
 

package/src/utils.ts

@@ -93,7 +93,78 @@ export function firstNonEmpty(lines: string[]): string | undefined {
 	return idx >= 0 ? lines[idx] : undefined;
 }
 
+export function truncateToBytes(s: string, maxBytes: number): string {
+	if (Buffer.byteLength(s, "utf-8") <= maxBytes) return s;
+	let out = "";
+	let bytes = 0;
+	for (const ch of s) {
+		const chBytes = Buffer.byteLength(ch, "utf-8");
+		if (bytes + chBytes > maxBytes) break;
+		out += ch;
+		bytes += chBytes;
+	}
+	return out;
+}
+
+export function getCached<K, V>(map: Map<K, V>, key: K, compute: (key: K) => V): V {
+	if (map.has(key)) return map.get(key)!;
+	const v = compute(key);
+	map.set(key, v);
+	return v;
+}
+
+export function isHashRow(line: string): boolean {
+	return /^[A-Za-z0-9]{3}│/.test(line);
+}
+
+function gutterWidth(max: number, fallback: number): number {
+	return String(max || fallback).length;
+}
+
+function formatGutter(n: number, width: number): string {
+	return String(n).padStart(width) + " │ ";
+}
+
+function blankGutter(width: number): string {
+	return " ".repeat(width) + " │ ";
+}
+
+export function numberedRead(text: string, offset: number): string {
+	const lines = text.split("\n");
+	const hashLines = lines.filter(isHashRow).length;
+	const max = hashLines > 0 ? offset + hashLines - 1 : offset;
+	const width = gutterWidth(max, offset);
+	let n = offset;
+	return lines.map((line) => {
+		if (!isHashRow(line)) return line;
+		const prefix = formatGutter(n++, width);
+		return prefix + line;
+	}).join("\n");
+}
+
+export function withLineNumbers(text: string, numbers: (number|undefined)[]): string {
+	const lines = text.split("\n");
+	const nums = numbers ?? [];
+	const max = nums.reduce<number>((m, n) => n !== undefined && n > m ? n : m, 0);
+	const width = gutterWidth(max, lines.length);
+	return lines.map((line, i) => {
+		const n = nums[i];
+		const prefix = n !== undefined ? formatGutter(n, width) : blankGutter(width);
+		return prefix + line;
+	}).join("\n");
+}
 export function clipLine(line: string, maxLen = 200): string {
 	const flat = line.replace(/\n/g, "\\n");
 	return flat.length > maxLen ? `${flat.slice(0, maxLen)}...` : flat;
 }
+export function assertLineLimit(content: string, displayPath: string, limit: number): void {
+	const count = splitLines(content).length;
+	if (count > limit) throw new Error(formatLineLimit(displayPath, limit, count));
+}
+export function lineLimitMoreThanMessage(displayPath: string, limit: number): string {
+	return formatLineLimit(displayPath, limit, undefined);
+}
+function formatLineLimit(displayPath: string, limit: number, count: number | undefined): string {
+	const detail = count === undefined ? `has more than ${limit}` : `has ${count}`;
+	return `[E_FILE_TOO_LARGE] ${displayPath} ${detail} lines, exceeding the ${limit}-line hashline limit. For very large files, use write.`;
+}