harnery 0.35.0 → 0.36.0

package/dist/lib/http/client.d.ts

@@ -9,7 +9,8 @@ import type { CookieJar } from "../cookies/index.js";
  * Used by the `fetch` command and other tooling that wants to share session
  * 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. */
@@ -35,22 +36,27 @@ 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;
 }
 /**
  * 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 declare function fetchWithJar(url: string, opts?: FetchOptions): Promise<FetchResult>;
+export declare function fetchWithJar<TResponseType extends FetchResponseType = "text">(url: string, opts?: FetchOptions<TResponseType>): Promise<FetchResult<FetchBody<TResponseType>>>;
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/http/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;GASG;AAEH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsD7F"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;GASG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM;IAC5E,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,0FAA0F;IAC1F,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,KAAK,SAAS,CAAC,aAAa,SAAS,iBAAiB,IAAI,aAAa,SAAS,OAAO,GACnF,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,MAAM;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM,EACjF,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAY,CAAC,aAAa,CAAM,GACrC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CA8EhD"}

package/dist/lib/http/client.js

@@ -1,7 +1,8 @@
 /**
  * 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.
  */
@@ -21,13 +22,27 @@ export async function fetchWithJar(url, opts = {}) {
                 headers[k] = v;
         }
     }
-    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 = {
         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) {
         const setCookieHeaders = collectSetCookie(response.headers);
@@ -46,12 +61,15 @@ export async function fetchWithJar(url, opts = {}) {
     response.headers.forEach((value, key) => {
         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,
         cookiesSaved,
     };
 }

package/dist/lib/http/index.d.ts

@@ -1,3 +1,3 @@
-export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";
+export { type FetchOptions, type FetchResponseType, type FetchResult, fetchWithJar, } from "./client.js";
 export * from "./request.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/http/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,cAAc,cAAc,CAAC"}

package/dist/lib/http/index.js

@@ -1,2 +1,2 @@
-export { fetchWithJar } from "./client.js";
+export { fetchWithJar, } from "./client.js";
 export * from "./request.js";

package/dist/lib/indexer-exclusions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/** Ensure both editor exclusions exist. Returns init-style action lines. */
+export declare function applyIndexerExclusions(projectRoot: string, dryRun: boolean): string[];
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export declare function removeIndexerExclusions(projectRoot: string, dryRun: boolean): string[];
+//# sourceMappingURL=indexer-exclusions.d.ts.map

package/dist/lib/indexer-exclusions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer-exclusions.d.ts","sourceRoot":"","sources":["../../src/lib/indexer-exclusions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4IH,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAErF;AAED,2FAA2F;AAC3F,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAKtF"}

package/dist/lib/indexer-exclusions.js

@@ -0,0 +1,176 @@
+/**
+ * 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) {
+    const t = line.trim();
+    return (t === ".harnery" ||
+        t === ".harnery/" ||
+        t === "/.harnery" ||
+        t === "/.harnery/" ||
+        t === ".harnery/**" ||
+        t === "/.harnery/**");
+}
+function applyCursorIgnore(projectRoot, dryRun) {
+    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, dryRun) {
+    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;
+    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;
+    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 ?? {};
+    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, dryRun) {
+    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, dryRun) {
+    const path = resolve(projectRoot, VSCODE_SETTINGS);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    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;
+    const watcher = settings[WATCHER_KEY];
+    if (typeof watcher !== "object" || watcher === null || Array.isArray(watcher))
+        return null;
+    const map = watcher;
+    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, dryRun) {
+    return [applyCursorIgnore(projectRoot, dryRun), applyVscodeWatcherExclude(projectRoot, dryRun)];
+}
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export function removeIndexerExclusions(projectRoot, dryRun) {
+    return [
+        removeCursorIgnore(projectRoot, dryRun),
+        removeVscodeWatcherExclude(projectRoot, dryRun),
+    ].filter((line) => line !== null);
+}

package/dist/lib/instructions/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CAqGR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CA0GR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -125,6 +125,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/dist/lib/local-file-url.d.ts

@@ -0,0 +1,9 @@
+/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
+export declare const DEFAULT_WEB_PORT = 4276;
+/** Cookie-isolated host for navigable repo files. */
+export declare const FILES_ORIGIN_HOST = "harnery-files.localhost";
+/** Encode each repo-path segment while preserving slash-based URL resolution. */
+export declare function encodedRepoPath(relPath: string): string;
+export declare function localFilesOriginUrl(relPath: string, port?: number | string, protocol?: string): string;
+export declare function localFileViewerUrl(relPath: string, port?: number | string): string;
+//# sourceMappingURL=local-file-url.d.ts.map

package/dist/lib/local-file-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-url.d.ts","sourceRoot":"","sources":["../../src/lib/local-file-url.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,MAAyB,EACxC,QAAQ,SAAU,GACjB,MAAM,CAGR;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,MAAyB,GACvC,MAAM,CAER"}

package/dist/lib/local-file-url.js

@@ -0,0 +1,20 @@
+/** 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) {
+    return relPath
+        .replace(/^\/+/, "")
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+export function localFilesOriginUrl(relPath, port = DEFAULT_WEB_PORT, protocol = "http:") {
+    const portPart = String(port) === "" ? "" : `:${port}`;
+    return `${protocol}//${FILES_ORIGIN_HOST}${portPart}/${encodedRepoPath(relPath)}`;
+}
+export function localFileViewerUrl(relPath, port = DEFAULT_WEB_PORT) {
+    return `http://localhost:${port}/files?path=${encodeURIComponent(relPath)}`;
+}

package/dist/lib/web-performance.d.ts

@@ -0,0 +1,118 @@
+export declare const WEB_PERFORMANCE_LOG = "web-performance.jsonl";
+interface BaseEvent {
+    event: string;
+    ts: string;
+    pid?: number;
+    mode?: string;
+}
+export interface WebRequestPerformanceEvent extends BaseEvent {
+    event: "request_complete";
+    request_id: string;
+    method: string;
+    route: string;
+    status: number | null;
+    outcome: "finished" | "aborted";
+    stream: boolean;
+    slow: boolean;
+    duration_ms: number;
+    process_cpu_ms_during_request: number;
+    concurrent_requests_at_start: number;
+    max_concurrent_requests: number;
+    event_loop_delay_count: number;
+    event_loop_delay_total_ms: number;
+    max_event_loop_delay_ms: number;
+}
+export interface WebEventLoopDelayEvent extends BaseEvent {
+    event: "event_loop_delay";
+    delay_ms: number;
+    active_request_count: number;
+    active_requests: Array<{
+        request_id: string;
+        method: string;
+        route: string;
+        age_ms: number;
+    }>;
+    active_requests_truncated: number;
+}
+export interface WebMemoryPerformanceEvent extends BaseEvent {
+    event: "memory_sample";
+    reason: "started" | "interval";
+    rss_bytes: number;
+    heap_used_bytes: number;
+    heap_total_bytes: number;
+    heap_limit_bytes: number;
+    heap_used_percent: number;
+    external_bytes: number;
+    array_buffers_bytes: number;
+    native_contexts: number;
+    detached_contexts: number;
+    active_request_count: number;
+    gc_count: number;
+    gc_duration_ms: number;
+    max_gc_pause_ms: number;
+    gc_by_kind: Record<string, {
+        count: number;
+        duration_ms: number;
+    }>;
+}
+export interface WebGcPauseEvent extends BaseEvent {
+    event: "gc_pause";
+    kind: string;
+    duration_ms: number;
+    rss_bytes: number;
+    heap_used_bytes: number;
+    heap_total_bytes: number;
+    heap_limit_bytes: number;
+    heap_used_percent: number;
+    active_request_count: number;
+}
+export interface WebRoutePerformanceSummary {
+    method: string;
+    route: string;
+    requests: number;
+    slow_requests: number;
+    aborted_requests: number;
+    p50_ms: number;
+    p95_ms: number;
+    max_ms: number;
+    max_event_loop_delay_ms: number;
+    max_concurrent_requests: number;
+}
+export interface WebPerformanceReport {
+    state: "ok" | "unavailable";
+    log_path: string;
+    since: string;
+    files_read: number;
+    invalid_lines: number;
+    requests_observed: number;
+    streams_observed: number;
+    slow_requests: number;
+    event_loop_delays: number;
+    memory: {
+        samples: number;
+        latest: WebMemoryPerformanceEvent;
+        peak_rss_bytes: number;
+        peak_heap_used_bytes: number;
+        max_heap_used_percent: number;
+    } | null;
+    garbage_collection: {
+        observed_collections: number;
+        observed_duration_ms: number;
+        recorded_pauses: number;
+        max_pause_ms: number;
+    };
+    routes: WebRoutePerformanceSummary[];
+    slowest_requests: WebRequestPerformanceEvent[];
+    largest_event_loop_delays: WebEventLoopDelayEvent[];
+    largest_gc_pauses: WebGcPauseEvent[];
+    hint?: string;
+}
+export declare function parsePerformanceWindow(input: string): number | null;
+export declare function readWebPerformanceReport(options: {
+    root: string;
+    since: string;
+    limit: number;
+    nowMs?: number;
+}): WebPerformanceReport;
+export {};
+//# sourceMappingURL=web-performance.d.ts.map

package/dist/lib/web-performance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-performance.d.ts","sourceRoot":"","sources":["../../src/lib/web-performance.ts"],"names":[],"mappings":"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"}