dsh-hashline-edit 0.1.0 → 0.1.1

package/README.md

@@ -130,11 +130,12 @@ The plugin installs a `tools/post-execute` listener for the host's `pwsh` and `b
 | 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 |
+| `Get-Content <file> \| Select-Object -First\|-Last\|-Skip <N>` | the bounded slice |
+| `Get-Content <file> \| Select-Object -Skip N -First M` (either order) | disk lines N+1 through N+M |
 | `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.
+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). Every served view is prefixed with the shared `[Bash view: <file> (lines a-b of N total)]` page header, so the positions the raw output used to name are not lost. Anything the view cannot prove — an unknown pipeline, a statement separator (`;`), a variable path (`$f`), a wildcard, 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
 

package/lib/index.js

@@ -2268,8 +2268,156 @@ ${escalationHintMarker("operation")}`,
   }
 };
 
+// src/bash-view-banner.ts
+var BASH_VIEW_LABEL = "Bash view";
+
+// dsh/host-compat.ts
+import { realpath } from "node:fs/promises";
+import { resolve as resolve3 } from "node:path";
+var DEFAULT_MAX_LINES = 2e3;
+var DEFAULT_MAX_BYTES = 50 * 1024;
+function splitLinesForCounting(content) {
+  if (content.length === 0) return [];
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) lines.pop();
+  return lines;
+}
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function truncateHead(content, options = {}) {
+  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const totalBytes = Buffer.byteLength(content, "utf-8");
+  const lines = splitLinesForCounting(content);
+  const totalLines = lines.length;
+  if (totalLines <= maxLines && totalBytes <= maxBytes) {
+    return {
+      content,
+      truncated: false,
+      truncatedBy: null,
+      totalLines,
+      totalBytes,
+      outputLines: totalLines,
+      outputBytes: totalBytes,
+      lastLinePartial: false,
+      firstLineExceedsLimit: false,
+      maxLines,
+      maxBytes
+    };
+  }
+  const firstLineBytes = Buffer.byteLength(lines[0] ?? "", "utf-8");
+  if (firstLineBytes > maxBytes) {
+    return {
+      content: "",
+      truncated: true,
+      truncatedBy: "bytes",
+      totalLines,
+      totalBytes,
+      outputLines: 0,
+      outputBytes: 0,
+      lastLinePartial: false,
+      firstLineExceedsLimit: true,
+      maxLines,
+      maxBytes
+    };
+  }
+  const outputLinesArr = [];
+  let outputBytesCount = 0;
+  let truncatedBy = "lines";
+  for (let index = 0; index < lines.length && index < maxLines; index += 1) {
+    const line = lines[index] ?? "";
+    const lineBytes = Buffer.byteLength(line, "utf-8") + (index > 0 ? 1 : 0);
+    if (outputBytesCount + lineBytes > maxBytes) {
+      truncatedBy = "bytes";
+      break;
+    }
+    outputLinesArr.push(line);
+    outputBytesCount += lineBytes;
+  }
+  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+    truncatedBy = "lines";
+  }
+  const outputContent = outputLinesArr.join("\n");
+  return {
+    content: outputContent,
+    truncated: true,
+    truncatedBy,
+    totalLines,
+    totalBytes,
+    outputLines: outputLinesArr.length,
+    outputBytes: Buffer.byteLength(outputContent, "utf-8"),
+    lastLinePartial: false,
+    firstLineExceedsLimit: false,
+    maxLines,
+    maxBytes
+  };
+}
+var fileMutationQueues = /* @__PURE__ */ new Map();
+var registrationQueue = Promise.resolve();
+function isMissingPathError(error) {
+  return typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
+async function getMutationQueueKey(filePath) {
+  const resolvedPath = resolve3(filePath);
+  try {
+    return await realpath(resolvedPath);
+  } catch (error) {
+    if (isMissingPathError(error)) return resolvedPath;
+    throw error;
+  }
+}
+async function withFileMutationQueue(filePath, run) {
+  const registration = registrationQueue.then(async () => {
+    const key2 = await getMutationQueueKey(filePath);
+    const currentQueue2 = fileMutationQueues.get(key2) ?? Promise.resolve();
+    let releaseNext2 = () => {
+    };
+    const nextQueue = new Promise((resolveQueue) => {
+      releaseNext2 = resolveQueue;
+    });
+    const chainedQueue2 = currentQueue2.then(() => nextQueue);
+    fileMutationQueues.set(key2, chainedQueue2);
+    return { key: key2, currentQueue: currentQueue2, chainedQueue: chainedQueue2, releaseNext: releaseNext2 };
+  });
+  registrationQueue = registration.then(
+    () => void 0,
+    () => void 0
+  );
+  const { key, currentQueue, chainedQueue, releaseNext } = await registration;
+  await currentQueue;
+  try {
+    return await run();
+  } finally {
+    releaseNext();
+    if (fileMutationQueues.get(key) === chainedQueue) fileMutationQueues.delete(key);
+  }
+}
+
+// src/file-content/served-header.ts
+function stopSuffix(stoppedAtBytes) {
+  return stoppedAtBytes === void 0 ? "" : `; stopped at ${formatSize(stoppedAtBytes)}`;
+}
+function rangeOf(shown, totalLines) {
+  if (shown === void 0 || shown.startLine === 1 && shown.endLine === totalLines) {
+    return `${totalLines} lines total`;
+  }
+  return `lines ${shown.startLine}-${shown.endLine} of ${totalLines} total`;
+}
+function formatPageHeader(parts) {
+  const count = rangeOf(parts.shownRange, parts.totalLines);
+  const body = parts.verbatim === true ? `verbatim, ${count}` : count;
+  const label = parts.label === void 0 ? "" : `${parts.label}: `;
+  return `[${label}${parts.file} (${body}${stopSuffix(parts.stoppedAtBytes)})]`;
+}
+function formatSectionHeader(startLine, endLine, totalLines, stoppedAtBytes) {
+  return `[Lines ${startLine}-${endLine} of ${totalLines} total${stopSuffix(stoppedAtBytes)}]`;
+}
+
 // src/hashline/hash-identity.ts
-import { isAbsolute as isAbsolute3, resolve as resolve3 } from "node:path";
+import { isAbsolute as isAbsolute3, resolve as resolve4 } from "node:path";
 
 // src/hashline/hasher.ts
 import xxhash from "xxhash-wasm";
@@ -2408,7 +2556,7 @@ function canonicalAnchorPath(path) {
       message: `Anchor derivation requires an absolute file path, got ${JSON.stringify(path)}.`
     });
   }
-  return resolve3(path);
+  return resolve4(path);
 }
 function contentBaseIndex(canonText) {
   return (xxh32(canonText) >>> 14) % HASH_SPACE;
@@ -6224,131 +6372,6 @@ async function anchorWalkFor(normalized, absolutePath, options) {
   });
 }
 
-// dsh/host-compat.ts
-import { realpath } from "node:fs/promises";
-import { resolve as resolve4 } from "node:path";
-var DEFAULT_MAX_LINES = 2e3;
-var DEFAULT_MAX_BYTES = 50 * 1024;
-function splitLinesForCounting(content) {
-  if (content.length === 0) return [];
-  const lines = content.split("\n");
-  if (content.endsWith("\n")) lines.pop();
-  return lines;
-}
-function formatSize(bytes) {
-  if (bytes < 1024) return `${bytes}B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-function truncateHead(content, options = {}) {
-  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
-  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-  const totalBytes = Buffer.byteLength(content, "utf-8");
-  const lines = splitLinesForCounting(content);
-  const totalLines = lines.length;
-  if (totalLines <= maxLines && totalBytes <= maxBytes) {
-    return {
-      content,
-      truncated: false,
-      truncatedBy: null,
-      totalLines,
-      totalBytes,
-      outputLines: totalLines,
-      outputBytes: totalBytes,
-      lastLinePartial: false,
-      firstLineExceedsLimit: false,
-      maxLines,
-      maxBytes
-    };
-  }
-  const firstLineBytes = Buffer.byteLength(lines[0] ?? "", "utf-8");
-  if (firstLineBytes > maxBytes) {
-    return {
-      content: "",
-      truncated: true,
-      truncatedBy: "bytes",
-      totalLines,
-      totalBytes,
-      outputLines: 0,
-      outputBytes: 0,
-      lastLinePartial: false,
-      firstLineExceedsLimit: true,
-      maxLines,
-      maxBytes
-    };
-  }
-  const outputLinesArr = [];
-  let outputBytesCount = 0;
-  let truncatedBy = "lines";
-  for (let index = 0; index < lines.length && index < maxLines; index += 1) {
-    const line = lines[index] ?? "";
-    const lineBytes = Buffer.byteLength(line, "utf-8") + (index > 0 ? 1 : 0);
-    if (outputBytesCount + lineBytes > maxBytes) {
-      truncatedBy = "bytes";
-      break;
-    }
-    outputLinesArr.push(line);
-    outputBytesCount += lineBytes;
-  }
-  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
-    truncatedBy = "lines";
-  }
-  const outputContent = outputLinesArr.join("\n");
-  return {
-    content: outputContent,
-    truncated: true,
-    truncatedBy,
-    totalLines,
-    totalBytes,
-    outputLines: outputLinesArr.length,
-    outputBytes: Buffer.byteLength(outputContent, "utf-8"),
-    lastLinePartial: false,
-    firstLineExceedsLimit: false,
-    maxLines,
-    maxBytes
-  };
-}
-var fileMutationQueues = /* @__PURE__ */ new Map();
-var registrationQueue = Promise.resolve();
-function isMissingPathError(error) {
-  return typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
-}
-async function getMutationQueueKey(filePath) {
-  const resolvedPath = resolve4(filePath);
-  try {
-    return await realpath(resolvedPath);
-  } catch (error) {
-    if (isMissingPathError(error)) return resolvedPath;
-    throw error;
-  }
-}
-async function withFileMutationQueue(filePath, run) {
-  const registration = registrationQueue.then(async () => {
-    const key2 = await getMutationQueueKey(filePath);
-    const currentQueue2 = fileMutationQueues.get(key2) ?? Promise.resolve();
-    let releaseNext2 = () => {
-    };
-    const nextQueue = new Promise((resolveQueue) => {
-      releaseNext2 = resolveQueue;
-    });
-    const chainedQueue2 = currentQueue2.then(() => nextQueue);
-    fileMutationQueues.set(key2, chainedQueue2);
-    return { key: key2, currentQueue: currentQueue2, chainedQueue: chainedQueue2, releaseNext: releaseNext2 };
-  });
-  registrationQueue = registration.then(
-    () => void 0,
-    () => void 0
-  );
-  const { key, currentQueue, chainedQueue, releaseNext } = await registration;
-  await currentQueue;
-  try {
-    return await run();
-  } finally {
-    releaseNext();
-    if (fileMutationQueues.get(key) === chainedQueue) fileMutationQueues.delete(key);
-  }
-}
-
 // src/served-session/serve-render.ts
 function buildRangeServeRows(startLine, endLine, fileHashes) {
   const total = endLine - startLine + 1;
@@ -7517,14 +7540,6 @@ function changedRange(original, result) {
   };
 }
 
-// src/file-content/served-header.ts
-function stopSuffix(stoppedAtBytes) {
-  return stoppedAtBytes === void 0 ? "" : `; stopped at ${formatSize(stoppedAtBytes)}`;
-}
-function formatSectionHeader(startLine, endLine, totalLines, stoppedAtBytes) {
-  return `[Lines ${startLine}-${endLine} of ${totalLines} total${stopSuffix(stoppedAtBytes)}]`;
-}
-
 // src/file-content/preview.ts
 function normPosInt(value, name2) {
   if (value === void 0) {
@@ -10861,6 +10876,7 @@ function usablePath(value) {
   if (value === void 0) return void 0;
   const path = value.trim();
   if (path.length === 0 || path.startsWith("-")) return void 0;
+  if (path.startsWith("$")) return void 0;
   if (/[*?[\]]/u.test(path)) return void 0;
   return path;
 }
@@ -10922,26 +10938,37 @@ function aliasPath(stage) {
   if (stage.length !== 2) return void 0;
   return usablePath(stage[1]);
 }
-function selectObjectBound(stage) {
+function selectObjectBounds(stage) {
   if (stage[0] === void 0 || !eq(stage[0], "select-object")) return void 0;
-  let bound;
+  const seen = {};
   for (let index = 1; index < stage.length; index += 1) {
     const token = stage[index];
-    if (token === void 0 || bound !== void 0) return void 0;
+    if (token === void 0) return void 0;
     const lower = token.toLowerCase();
-    let kind;
-    if (lower === "-first") kind = "first";
-    else if (lower === "-last") kind = "last";
-    else if (lower === "-skip") kind = "skip";
+    let key;
+    if (lower === "-first") key = "first";
+    else if (lower === "-last") key = "last";
+    else if (lower === "-skip") key = "skip";
     else return void 0;
     const raw = stage[index + 1];
     index += 1;
     if (raw === void 0 || !/^\d+$/u.test(raw)) return void 0;
+    if (seen[key] !== void 0) return void 0;
     const count = Number(raw);
     if (!Number.isSafeInteger(count)) return void 0;
-    bound = { kind, count };
+    seen[key] = count;
+  }
+  const skip = seen.skip;
+  const firstBound = seen.first;
+  const lastBound = seen.last;
+  if (lastBound !== void 0 && (skip !== void 0 || firstBound !== void 0)) {
+    return void 0;
   }
-  return bound;
+  if (skip !== void 0 && firstBound !== void 0) return { skip, first: firstBound };
+  if (skip !== void 0) return { skip };
+  if (firstBound !== void 0) return { first: firstBound };
+  if (lastBound !== void 0) return { last: lastBound };
+  return void 0;
 }
 function selectStringPath(stage) {
   if (stage[0] === void 0 || !eq(stage[0], "select-string")) return void 0;
@@ -11030,9 +11057,23 @@ function parse2(command) {
   const second = stages[1];
   if (stages.length !== 2 || second === void 0 || !eq(head, "get-content")) return void 0;
   const path = getContentPath(first);
-  const bound = selectObjectBound(second);
-  if (path === void 0 || bound === void 0) return void 0;
-  return { kind: bound.kind, path, count: bound.count };
+  const bounds = selectObjectBounds(second);
+  if (path === void 0 || bounds === void 0) return void 0;
+  const firstBound = bounds.first;
+  const lastBound = bounds.last;
+  if (bounds.skip !== void 0 && firstBound !== void 0) {
+    return { kind: "window", path, skip: bounds.skip, count: firstBound };
+  }
+  if (bounds.skip !== void 0 && firstBound === void 0 && lastBound === void 0) {
+    return { kind: "skip", path, count: bounds.skip };
+  }
+  if (firstBound !== void 0 && bounds.skip === void 0 && lastBound === void 0) {
+    return { kind: "first", path, count: firstBound };
+  }
+  if (lastBound !== void 0 && bounds.skip === void 0 && firstBound === void 0) {
+    return { kind: "last", path, count: lastBound };
+  }
+  return void 0;
 }
 function firstGreater(sorted, after) {
   let low = 0;
@@ -11148,6 +11189,11 @@ function alignTransform(command, fileLines, stdoutLines) {
     return stdoutLines.length === total ? aligned : void 0;
   }
   if (command.kind === "search") return aligned;
+  if (command.kind === "window") {
+    const window = Math.min(command.count, Math.max(0, total - command.skip));
+    if (stdoutLines.length !== window) return void 0;
+    return aligned[0] === command.skip + 1 ? aligned : void 0;
+  }
   const expected = command.kind === "skip" ? Math.max(0, total - command.count) : Math.min(command.count, total);
   if (stdoutLines.length !== expected) return void 0;
   if (command.kind === "first") return aligned[0] === 1 ? aligned : void 0;
@@ -11189,7 +11235,16 @@ async function plan(deps, request) {
       if (row === void 0) return void 0;
       rows.push(`${row.hash}${HASH_SEP}${row.text}`);
     }
-    return { path: command.path, cwd: request.cwd, lineNumbers, rows };
+    const startLine = lineNumbers[0];
+    const endLine = lineNumbers[lineNumbers.length - 1];
+    if (startLine === void 0 || endLine === void 0) return void 0;
+    const header = formatPageHeader({
+      label: BASH_VIEW_LABEL,
+      file: command.path,
+      totalLines: fileLines.length,
+      shownRange: { startLine, endLine }
+    });
+    return { path: command.path, cwd: request.cwd, lineNumbers, header, rows };
   } catch (error) {
     reportDiagnostic("shell-view", "Could not serve the shell view; passing through:", error);
     return void 0;
@@ -11284,7 +11339,8 @@ function createShellHooks(deps) {
         return decision;
       }
       if (planned === void 0 || planned.rows.length === 0) return decision;
-      const anchoredText = `${planned.rows.join("\n")}
+      const anchoredText = `${planned.header}
+${planned.rows.join("\n")}
 `;
       deps.metrics?.record({
         tool: "shell_view",

package/lib/types/dsh/shell-view.d.ts

@@ -4,13 +4,14 @@
  *
  * Three steps, each fail-closed:
  * - {@link parse} admits only commands whose output is the file's own lines
- *   (`Get-Content`/`type`/`cat`, an optional `Select-Object -First/-Last/-Skip`
- *   bound, `Select-String`, and `rg` with an explicit single file);
+ *   (`Get-Content`/`type`/`cat`, a `Select-Object -First|-Last|-Skip` bound or
+ *   the `-Skip N -First M` window, `Select-String`, and `rg` with one explicit file);
  * - {@link align} maps the stdout lines back to disk lines with a monotonic
  *   match that must be unique — duplicate content without a unique position is
  *   ambiguous and refuses;
  * - {@link plan} serves the aligned lines through the read tool's seam (governed
- *   decode, stat adoption, snapshot materialization, leases) and returns
+ *   decode, stat adoption, snapshot materialization, leases), prints the shared
+ *   `[Bash view: …]` page header naming the served range, and returns
  *   `HASH│content` rows.
  *
  * Anything unmodelled — an unknown pipe, redirection, a wildcard path, formatted
@@ -24,10 +25,17 @@ export type ParsedShellCommand = {
     readonly kind: "full";
     readonly path: string;
 } | {
+    /** One `Select-Object` bound. */
     readonly kind: "first" | "last" | "skip";
     readonly path: string;
     /** The `-First`/`-Last`/`-Skip` argument. */
     readonly count: number;
+} | {
+    /** `Select-Object -Skip N -First M`: disk lines N+1 through N+M. */
+    readonly kind: "window";
+    readonly path: string;
+    readonly skip: number;
+    readonly count: number;
 } | {
     readonly kind: "search";
     readonly path: string;
@@ -49,6 +57,8 @@ export interface ShellViewPlan {
     readonly cwd: string;
     /** 1-based disk line numbers, ascending. */
     readonly lineNumbers: number[];
+    /** The shared `[Bash view: …]` page header naming the served range. */
+    readonly header: string;
     /** `HASH│content` rows for those lines, in line order. */
     readonly rows: string[];
 }

package/lib/types/src/bash-view-banner.d.ts

@@ -0,0 +1,20 @@
+/**
+ * WHY: one definition site for the bash seams' bracket roots (#150, read-chrome): `view`, `search`,
+ * WHY: `file list` and `auto-read` each carry a kind word — the kind word IS the completeness claim —
+ * WHY: and that literal used to be copied at seven call sites in `src/lifecycle-hooks/index.ts`. Every
+ * WHY: site names its kind here instead, so the text below is the single definition site spec §3.4
+ * WHY: names. The `---` banner is gone: a page's chrome is its header, and only these two roots
+ * WHY: (a search's match list, a path list) have no page to name.
+ */
+export declare const BASH_SEARCH_ROOT = "[Bash search (anchors)]";
+export declare const BASH_FILE_LIST_ROOT = "[Bash file list (no anchors)]";
+/**
+ * WHY: `view` and `auto-read` merged into their page headers (`[Bash view: f (40 lines total)]`), so
+ * WHY: their frozen text is the label, not a line of its own — the completeness claim moves into the
+ * WHY: header's bracket and a page can no longer carry two of them.
+ */
+export declare const BASH_VIEW_LABEL = "Bash view";
+export declare const BASH_AUTO_READ_LABEL = "Auto-read";
+export type BashBannerKind = "search" | "file-list";
+/** The bracket root that introduces a result with no page header of its own. */
+export declare function bashBanner(kind: BashBannerKind): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hashline-edit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Hash-anchored read/edit/undo_last_edit tools for DeepSeek Harness (dsh). Every line gets a unique 4-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "keywords": [
     "anchors",