harnery 0.35.0 → 0.36.0

package/src/lib/docs-metadata-sync.ts

@@ -4,6 +4,7 @@ import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
 import { parseFrontmatter } from "./docs-frontmatter.ts";
 import { managedDocsMetadataType } from "./docs-metadata-managed.ts";
 import { isDocsMetadataV2, validateDocsMetadataV2 } from "./docs-metadata-v2.ts";
+import { createDocsRepositoryView } from "./docs-repository-view.ts";
 import { sh } from "./exec.ts";
 
 let REPO_ROOT = "";
@@ -21,6 +22,7 @@ export interface DocsMetadataSyncOpts {
   repo?: string;
   files?: string[];
   check?: boolean;
+  cached?: boolean;
   reviewed?: boolean;
   now?: string;
 }
@@ -49,15 +51,27 @@ function targets(repo?: string): Target[] {
   return selected;
 }
 
-async function changedFiles(target: Target, explicit: string[]): Promise<string[]> {
-  if (explicit.length > 0) return explicit;
-  const result = await sh("git diff --cached --name-only --diff-filter=ACMR -- '*.md'", {
-    cwd: target.path,
-  });
-  if (result.exitCode !== 0) throw new Error(result.stderr || "git diff failed");
+async function gitMarkdownPaths(target: Target, command: string): Promise<string[]> {
+  const result = await sh(command, { cwd: target.path });
+  if (result.exitCode !== 0) throw new Error(result.stderr || `${command} failed`);
   return result.stdout.split("\n").filter(Boolean);
 }
 
+async function changedFiles(target: Target, explicit: string[], check: boolean): Promise<string[]> {
+  if (explicit.length > 0) return explicit;
+  const staged = await gitMarkdownPaths(
+    target,
+    "git diff --cached --name-only --diff-filter=ACMR -- '*.md'",
+  );
+  if (check) return staged;
+
+  const [unstaged, untracked] = await Promise.all([
+    gitMarkdownPaths(target, "git diff --name-only --diff-filter=ACMR -- '*.md'"),
+    gitMarkdownPaths(target, "git ls-files --others --exclude-standard -- '*.md'"),
+  ]);
+  return [...new Set([...staged, ...unstaged, ...untracked])];
+}
+
 async function headContent(target: Target, path: string): Promise<string | null> {
   const result = await sh(`git show HEAD:${JSON.stringify(path)}`, { cwd: target.path });
   return result.exitCode === 0 ? result.stdout : null;
@@ -107,13 +121,22 @@ function addDays(value: string, days: number): string {
 export async function runDocsMetadataSync(
   opts: DocsMetadataSyncOpts,
 ): Promise<DocsMetadataSyncRow[]> {
+  if (opts.cached && !opts.check) {
+    throw new Error("--cached requires --check because Git index validation is read-only");
+  }
   const now = opts.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
   const rows: DocsMetadataSyncRow[] = [];
   for (const target of targets(opts.repo)) {
-    for (const path of await changedFiles(target, opts.files ?? [])) {
+    const paths = await changedFiles(target, opts.files ?? [], opts.check ?? false);
+    const cachedView = opts.cached ? await createDocsRepositoryView(target.path, "index") : null;
+    const cachedTexts = cachedView ? await cachedView.readTexts(paths) : null;
+    for (const path of paths) {
       const full = join(target.path, path);
-      if (!existsSync(full)) continue;
-      const currentText = readFileSync(full, "utf8");
+      if (cachedView ? !cachedView.has(path) : !existsSync(full)) continue;
+      const currentText = cachedView ? cachedTexts?.get(path) : readFileSync(full, "utf8");
+      if (currentText === undefined) {
+        throw new Error(`Git index content could not be read for ${path}`);
+      }
       const current = parseFrontmatter(currentText);
       if (!managedDocsMetadataType(path, current.data, current.raw !== null)) continue;
       if (!isDocsMetadataV2(current.data)) {

package/src/lib/docs-repository-view.ts

@@ -0,0 +1,220 @@
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { exec } from "./exec.ts";
+
+export type DocsRepositorySource = "worktree" | "index";
+
+interface IndexEntry {
+  oid: string;
+  stage: number;
+}
+
+/**
+ * One coherent repository view for documentation commands.
+ *
+ * Worktree mode preserves the interactive commands' existing behavior. Index
+ * mode reads both path membership and file bytes through Git, so a pre-commit
+ * hook validates the exact index Git handed to it. During a path-scoped commit,
+ * Git exposes its temporary partial-commit index through GIT_INDEX_FILE; the
+ * view deliberately inherits that environment instead of rediscovering the
+ * shared working tree.
+ */
+export interface DocsRepositoryView {
+  readonly root: string;
+  readonly source: DocsRepositorySource;
+  readonly trackedPaths: readonly string[];
+  has(path: string): boolean;
+  directFileNames(directory: string): string[];
+  readTexts(paths: readonly string[]): Promise<Map<string, string>>;
+  byteLength(path: string): Promise<number | null>;
+}
+
+function normalize(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function trackedPathList(stdout: string): string[] {
+  return stdout.split("\0").map(normalize).filter(Boolean);
+}
+
+async function worktreePaths(root: string): Promise<string[]> {
+  const result = await exec(["git", "ls-files", "--cached", "-z"], { cwd: root, trim: false });
+  if (result.exitCode !== 0) {
+    // Worktree lint historically supports non-repository fixtures and simply
+    // has no tracked-file checks to run there. Index mode remains strict.
+    return [];
+  }
+  return trackedPathList(result.stdout);
+}
+
+async function indexEntries(root: string): Promise<Map<string, IndexEntry>> {
+  const result = await exec(["git", "ls-files", "--cached", "--stage", "-z"], {
+    cwd: root,
+    trim: false,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || "git ls-files --stage failed");
+  }
+
+  const entries = new Map<string, IndexEntry>();
+  for (const record of result.stdout.split("\0").filter(Boolean)) {
+    const tab = record.indexOf("\t");
+    if (tab === -1) throw new Error(`invalid git ls-files --stage record: ${record}`);
+    const [mode, oid, stageText] = record.slice(0, tab).split(" ");
+    const path = normalize(record.slice(tab + 1));
+    const stage = Number.parseInt(stageText ?? "", 10);
+    if (!mode || !oid || !Number.isInteger(stage)) {
+      throw new Error(`invalid git ls-files --stage record for ${path}`);
+    }
+    if (stage !== 0) {
+      throw new Error(`cannot validate an index with unmerged entry: ${path}`);
+    }
+    entries.set(path, { oid, stage });
+  }
+  return entries;
+}
+
+function parseBatch(stdout: Buffer, requested: readonly string[]): Map<string, Buffer> {
+  const blobs = new Map<string, Buffer>();
+  let offset = 0;
+  for (const oid of requested) {
+    const newline = stdout.indexOf(0x0a, offset);
+    if (newline === -1) throw new Error(`git cat-file omitted the header for ${oid}`);
+    const header = stdout.subarray(offset, newline).toString("utf8");
+    offset = newline + 1;
+    const [reportedOid, type, sizeText] = header.split(" ");
+    const size = Number.parseInt(sizeText ?? "", 10);
+    if (reportedOid !== oid || type !== "blob" || !Number.isInteger(size) || size < 0) {
+      throw new Error(`git cat-file returned an invalid blob header for ${oid}: ${header}`);
+    }
+    const end = offset + size;
+    if (end > stdout.length) throw new Error(`git cat-file truncated blob ${oid}`);
+    blobs.set(oid, stdout.subarray(offset, end));
+    offset = end;
+    if (stdout[offset] !== 0x0a) throw new Error(`git cat-file omitted the separator for ${oid}`);
+    offset += 1;
+  }
+  return blobs;
+}
+
+function readIndexBlobs(root: string, oids: readonly string[]): Promise<Map<string, Buffer>> {
+  const unique = [...new Set(oids)];
+  if (unique.length === 0) return Promise.resolve(new Map());
+
+  return new Promise((resolveResult, rejectResult) => {
+    const process = spawn("git", ["cat-file", "--batch"], {
+      cwd: root,
+      env: { ...globalThis.process.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    const timer = setTimeout(() => process.kill(), 30_000);
+    process.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+    process.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+    process.on("error", (error) => {
+      clearTimeout(timer);
+      rejectResult(error);
+    });
+    process.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        rejectResult(
+          new Error(Buffer.concat(stderr).toString("utf8").trim() || "git cat-file failed"),
+        );
+        return;
+      }
+      try {
+        resolveResult(parseBatch(Buffer.concat(stdout), unique));
+      } catch (error) {
+        rejectResult(error);
+      }
+    });
+    process.stdin.end(`${unique.join("\n")}\n`);
+  });
+}
+
+function directIndexFiles(paths: readonly string[], directory: string): string[] {
+  const normalizedDirectory = normalize(directory).replace(/\/$/, "");
+  return paths
+    .filter((path) => normalize(dirname(path)) === normalizedDirectory)
+    .map((path) => basename(path));
+}
+
+export async function createDocsRepositoryView(
+  root: string,
+  source: DocsRepositorySource = "worktree",
+): Promise<DocsRepositoryView> {
+  if (source === "worktree") {
+    const trackedPaths = await worktreePaths(root);
+    return {
+      root,
+      source,
+      trackedPaths,
+      has: (path) => existsSync(join(root, path)),
+      directFileNames: (directory) => {
+        try {
+          return readdirSync(join(root, directory)).filter((entry) => {
+            try {
+              return statSync(join(root, directory, entry)).isFile();
+            } catch {
+              return false;
+            }
+          });
+        } catch {
+          return [];
+        }
+      },
+      readTexts: async (paths) => {
+        const texts = new Map<string, string>();
+        for (const path of paths) {
+          try {
+            texts.set(path, readFileSync(join(root, path), "utf8"));
+          } catch {
+            // The caller decides whether a missing tracked path is a finding.
+          }
+        }
+        return texts;
+      },
+      byteLength: async (path) => {
+        try {
+          return statSync(join(root, path)).size;
+        } catch {
+          return null;
+        }
+      },
+    };
+  }
+
+  const entries = await indexEntries(root);
+  const trackedPaths = [...entries.keys()];
+  const textCache = new Map<string, string>();
+  const loadTexts = async (paths: readonly string[]): Promise<Map<string, string>> => {
+    const wanted = [...new Set(paths.map(normalize))].filter((path) => entries.has(path));
+    const missing = wanted.filter((path) => !textCache.has(path));
+    const oids = missing.map((path) => entries.get(path)!.oid);
+    const blobs = await readIndexBlobs(root, oids);
+    for (const path of missing) {
+      const blob = blobs.get(entries.get(path)!.oid);
+      if (blob) textCache.set(path, blob.toString("utf8"));
+    }
+    return new Map(
+      wanted.flatMap((path) => (textCache.has(path) ? [[path, textCache.get(path)!]] : [])),
+    );
+  };
+
+  return {
+    root,
+    source,
+    trackedPaths,
+    has: (path) => entries.has(normalize(path)),
+    directFileNames: (directory) => directIndexFiles(trackedPaths, directory),
+    readTexts: loadTexts,
+    byteLength: async (path) => {
+      const normalized = normalize(path);
+      const text = (await loadTexts([normalized])).get(normalized);
+      return text === undefined ? null : Buffer.byteLength(text, "utf8");
+    },
+  };
+}

package/src/lib/http/client.ts

@@ -11,7 +11,9 @@ import type { Cookie, CookieJar } from "../cookies/index.ts";
  * state with `browse`.
  */
 
-export interface FetchOptions {
+export type FetchResponseType = "text" | "bytes";
+
+export interface FetchOptions<TResponseType extends FetchResponseType = "text"> {
   /** HTTP method. Default GET. */
   method?: string;
   /** Request body. Strings/Buffers/Streams pass through to fetch directly. */
@@ -37,14 +39,20 @@ export interface FetchOptions {
    * only land when the key isn't already set.
    */
   extraHeaders?: (url: string) => Record<string, string>;
+  /** Response body representation. Default `text`; use `bytes` for lossless file output. */
+  responseType?: TResponseType;
 }
 
-export interface FetchResult {
+type FetchBody<TResponseType extends FetchResponseType> = TResponseType extends "bytes"
+  ? Uint8Array
+  : string;
+
+export interface FetchResult<TBody = string> {
   status: number;
   statusText: string;
   url: string;
   headers: Record<string, string>;
-  body: string;
+  body: TBody;
   /** Number of cookies persisted back into the jar (0 if no jar passed). */
   cookiesSaved: number;
 }
@@ -52,11 +60,15 @@ export interface FetchResult {
 /**
  * Fetch a URL with optional cookie-jar attach + persist.
  *
- * Returns the response body as a string (callers handle JSON parsing).
+ * Returns the response body as text by default (callers handle JSON parsing).
+ * Pass `responseType: "bytes"` when the caller must preserve the body exactly.
  * Streams aren't supported; this is a CLI helper, not a streaming HTTP
  * client. Use Bun's `fetch` directly for streaming workloads.
  */
-export async function fetchWithJar(url: string, opts: FetchOptions = {}): Promise<FetchResult> {
+export async function fetchWithJar<TResponseType extends FetchResponseType = "text">(
+  url: string,
+  opts: FetchOptions<TResponseType> = {},
+): Promise<FetchResult<FetchBody<TResponseType>>> {
   const headers: Record<string, string> = { ...(opts.headers ?? {}) };
 
   if (opts.jar) {
@@ -74,13 +86,32 @@ export async function fetchWithJar(url: string, opts: FetchOptions = {}): Promis
     }
   }
 
-  const response = await fetch(url, {
+  // Byte mode is a download boundary, so keep the HTTP representation bytes
+  // aligned with the response headers. Bun otherwise decompresses the body
+  // while retaining Content-Encoding and the encoded Content-Length.
+  if (opts.responseType === "bytes" && !headers["Accept-Encoding"] && !headers["accept-encoding"]) {
+    headers["Accept-Encoding"] = "identity";
+  }
+  const fetchInit: RequestInit & { decompress?: boolean } = {
     method: opts.method ?? "GET",
     body: opts.body,
     headers,
     redirect: opts.redirect ?? "follow",
     signal: opts.signal,
-  });
+  };
+  if (opts.responseType === "bytes") fetchInit.decompress = false;
+
+  const response = await fetch(url, fetchInit);
+
+  if (
+    opts.responseType === "bytes" &&
+    typeof Bun === "undefined" &&
+    response.headers.has("content-encoding")
+  ) {
+    throw new Error(
+      "cannot preserve a content-encoded response under the Node fallback; install Bun or request identity encoding",
+    );
+  }
 
   let cookiesSaved = 0;
   if (opts.jar) {
@@ -102,12 +133,17 @@ export async function fetchWithJar(url: string, opts: FetchOptions = {}): Promis
     headerObj[key] = value;
   });
 
+  const body =
+    opts.responseType === "bytes"
+      ? new Uint8Array(await response.arrayBuffer())
+      : await response.text();
+
   return {
     status: response.status,
     statusText: response.statusText,
     url: response.url,
     headers: headerObj,
-    body: await response.text(),
+    body: body as FetchBody<TResponseType>,
     cookiesSaved,
   };
 }

package/src/lib/http/index.ts

@@ -1,2 +1,7 @@
-export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";
+export {
+  type FetchOptions,
+  type FetchResponseType,
+  type FetchResult,
+  fetchWithJar,
+} from "./client.js";
 export * from "./request.ts";

package/src/lib/indexer-exclusions.ts

@@ -0,0 +1,173 @@
+/**
+ * Editor-indexer exclusions for the `.harnery/` coord root.
+ *
+ * `harn init` already writes `.harnery/.gitignore`, which keeps git-aware
+ * tools out of runtime state. Two high-traffic editor surfaces ignore
+ * gitignore, though: Cursor's codebase indexer (governed by a repo-root
+ * `.cursorindexingignore`) and the VS Code/Cursor file watcher (governed by
+ * `files.watcherExclude` in `.vscode/settings.json`). A busy coord root holds
+ * tens of thousands of ledger events plus working artifacts, so on
+ * session-heavy hosts the missing exclusions turn editor startup into an
+ * indexing storm over machine-local state no editor needs to see.
+ *
+ * `applyIndexerExclusions` is idempotent and non-destructive: it appends a
+ * managed entry to `.cursorindexingignore` (or creates the file) and merges a
+ * single key into `.vscode/settings.json` (or creates it). A settings file it
+ * cannot merge safely (comments, malformed JSON, or a non-object
+ * `files.watcherExclude`) is left byte-identical and reported as a manual
+ * step. `removeIndexerExclusions` reverses exactly what apply wrote: it never
+ * removes a `.harnery/` ignore entry the consumer added themselves (detected
+ * by the absence of the managed comment) and never edits a settings file it
+ * could not have written into.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const CURSOR_IGNORE = ".cursorindexingignore";
+const MANAGED_COMMENT =
+  "# .harnery/ is machine-local harnery runtime state (entry managed by init)";
+const MANAGED_ENTRY = ".harnery/";
+const VSCODE_DIR = ".vscode";
+const VSCODE_SETTINGS = ".vscode/settings.json";
+const WATCHER_KEY = "files.watcherExclude";
+const WATCHER_GLOB = "**/.harnery/**";
+
+/** True when a `.cursorindexingignore` line already excludes the coord root. */
+function coversCoordRoot(line: string): boolean {
+  const t = line.trim();
+  return (
+    t === ".harnery" ||
+    t === ".harnery/" ||
+    t === "/.harnery" ||
+    t === "/.harnery/" ||
+    t === ".harnery/**" ||
+    t === "/.harnery/**"
+  );
+}
+
+function applyCursorIgnore(projectRoot: string, dryRun: boolean): string {
+  const path = resolve(projectRoot, CURSOR_IGNORE);
+  if (existsSync(path)) {
+    const raw = readFileSync(path, "utf8");
+    if (raw.split("\n").some(coversCoordRoot)) {
+      return `· ${CURSOR_IGNORE} already excludes .harnery/`;
+    }
+    if (dryRun) return `+ would append .harnery/ to ${CURSOR_IGNORE}`;
+    const sep = raw === "" || raw.endsWith("\n") ? "" : "\n";
+    writeFileSync(path, `${raw}${sep}${MANAGED_COMMENT}\n${MANAGED_ENTRY}\n`);
+    return `+ appended .harnery/ to ${CURSOR_IGNORE}`;
+  }
+  if (dryRun) return `+ would create ${CURSOR_IGNORE} (excludes .harnery/ from Cursor indexing)`;
+  writeFileSync(path, `${MANAGED_COMMENT}\n${MANAGED_ENTRY}\n`);
+  return `+ created ${CURSOR_IGNORE} (excludes .harnery/ from Cursor indexing)`;
+}
+
+function applyVscodeWatcherExclude(projectRoot: string, dryRun: boolean): string {
+  const path = resolve(projectRoot, VSCODE_SETTINGS);
+  if (!existsSync(path)) {
+    if (dryRun) return `+ would create ${VSCODE_SETTINGS} (file watcher excludes .harnery/)`;
+    mkdirSync(resolve(projectRoot, VSCODE_DIR), { recursive: true });
+    const body = JSON.stringify({ [WATCHER_KEY]: { [WATCHER_GLOB]: true } }, null, 2);
+    writeFileSync(path, `${body}\n`);
+    return `+ created ${VSCODE_SETTINGS} (file watcher excludes .harnery/)`;
+  }
+  const raw = readFileSync(path, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // JSONC (comments, trailing commas) or malformed. A rewrite would drop the
+    // consumer's comments, so leave the file alone and name the one-key merge.
+    return `! ${VSCODE_SETTINGS} is not plain JSON; add "${WATCHER_KEY}": {"${WATCHER_GLOB}": true} manually`;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return `! ${VSCODE_SETTINGS} is not a settings object; add "${WATCHER_KEY}": {"${WATCHER_GLOB}": true} manually`;
+  }
+  const settings = parsed as Record<string, unknown>;
+  const watcher = settings[WATCHER_KEY];
+  if (
+    watcher !== undefined &&
+    (typeof watcher !== "object" || watcher === null || Array.isArray(watcher))
+  ) {
+    return `! ${VSCODE_SETTINGS} has a non-object "${WATCHER_KEY}"; add "${WATCHER_GLOB}": true manually`;
+  }
+  const map = (watcher as Record<string, unknown> | undefined) ?? {};
+  if (map[WATCHER_GLOB] === true) {
+    return `· ${VSCODE_SETTINGS} file watcher already excludes .harnery/`;
+  }
+  if (dryRun) return `+ would add ${WATCHER_GLOB} to ${WATCHER_KEY} in ${VSCODE_SETTINGS}`;
+  map[WATCHER_GLOB] = true;
+  settings[WATCHER_KEY] = map;
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+  return `+ added ${WATCHER_GLOB} to ${WATCHER_KEY} in ${VSCODE_SETTINGS}`;
+}
+
+function removeCursorIgnore(projectRoot: string, dryRun: boolean): string | null {
+  const path = resolve(projectRoot, CURSOR_IGNORE);
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n");
+  // Only the managed pair is ours. A bare `.harnery/` line without the managed
+  // comment is a consumer's own entry and stays.
+  if (!lines.some((line) => line.trim() === MANAGED_COMMENT)) return null;
+  if (dryRun) return `+ would remove the managed .harnery/ entry from ${CURSOR_IGNORE}`;
+  const kept = lines.filter((line) => {
+    const t = line.trim();
+    return t !== MANAGED_COMMENT && t !== MANAGED_ENTRY;
+  });
+  if (kept.every((line) => line.trim() === "")) {
+    rmSync(path);
+    return `+ removed ${CURSOR_IGNORE} (was harnery-only)`;
+  }
+  let out = kept.join("\n");
+  if (!out.endsWith("\n")) out += "\n";
+  writeFileSync(path, out);
+  return `+ removed the managed .harnery/ entry from ${CURSOR_IGNORE}`;
+}
+
+function removeVscodeWatcherExclude(projectRoot: string, dryRun: boolean): string | null {
+  const path = resolve(projectRoot, VSCODE_SETTINGS);
+  if (!existsSync(path)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    // Not plain JSON, so apply never wrote into it.
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const settings = parsed as Record<string, unknown>;
+  const watcher = settings[WATCHER_KEY];
+  if (typeof watcher !== "object" || watcher === null || Array.isArray(watcher)) return null;
+  const map = watcher as Record<string, unknown>;
+  if (!(WATCHER_GLOB in map)) return null;
+  if (dryRun) return `+ would remove ${WATCHER_GLOB} from ${VSCODE_SETTINGS}`;
+  delete map[WATCHER_GLOB];
+  if (Object.keys(map).length === 0) delete settings[WATCHER_KEY];
+  if (Object.keys(settings).length === 0) {
+    rmSync(path);
+    try {
+      // Drop the .vscode/ directory too when the settings file was all it held.
+      rmdirSync(resolve(projectRoot, VSCODE_DIR));
+    } catch {
+      // Non-empty or shared; leave it.
+    }
+    return `+ removed ${VSCODE_SETTINGS} (was harnery-only)`;
+  }
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+  return `+ removed ${WATCHER_GLOB} from ${VSCODE_SETTINGS}`;
+}
+
+/** Ensure both editor exclusions exist. Returns init-style action lines. */
+export function applyIndexerExclusions(projectRoot: string, dryRun: boolean): string[] {
+  return [applyCursorIgnore(projectRoot, dryRun), applyVscodeWatcherExclude(projectRoot, dryRun)];
+}
+
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export function removeIndexerExclusions(projectRoot: string, dryRun: boolean): string[] {
+  return [
+    removeCursorIgnore(projectRoot, dryRun),
+    removeVscodeWatcherExclude(projectRoot, dryRun),
+  ].filter((line): line is string => line !== null);
+}

package/src/lib/instructions/templates.ts

@@ -147,6 +147,11 @@ returned path, then run \`${b} artifacts release <id>\` when active work is done
 Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
 expired cleanup and requires \`--yes\` to delete anything.
 
+**Local file links.** When the operator should open a local repo file, mint the
+URL with \`${b} files url <repo-relative-path>\` instead of guessing it. HTML opens
+as a real page with working scripts and relative assets; other files open in the
+dashboard viewer. Use localhost links only when the operator shares this machine.
+
 **Decision docket.** When you would otherwise stop to ask a human a decision you
 can't resolve from the repo, file it instead. \`${b} decision file "<question>"\`
 records it and lets you proceed on a stated default; \`${b} decision search "<terms>"\`

package/src/lib/local-file-url.ts

@@ -0,0 +1,31 @@
+/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
+export const DEFAULT_WEB_PORT = 4276;
+
+/** Cookie-isolated host for navigable repo files. */
+export const FILES_ORIGIN_HOST = "harnery-files.localhost";
+
+/** Encode each repo-path segment while preserving slash-based URL resolution. */
+export function encodedRepoPath(relPath: string): string {
+  return relPath
+    .replace(/^\/+/, "")
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function localFilesOriginUrl(
+  relPath: string,
+  port: number | string = DEFAULT_WEB_PORT,
+  protocol = "http:",
+): string {
+  const portPart = String(port) === "" ? "" : `:${port}`;
+  return `${protocol}//${FILES_ORIGIN_HOST}${portPart}/${encodedRepoPath(relPath)}`;
+}
+
+export function localFileViewerUrl(
+  relPath: string,
+  port: number | string = DEFAULT_WEB_PORT,
+): string {
+  return `http://localhost:${port}/files?path=${encodeURIComponent(relPath)}`;
+}