harnery 0.34.1 → 0.36.0

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/apply.ts

@@ -99,6 +99,7 @@ function blockSkills(projectRoot: string, adapter: string): BlockSkills {
     decide: supported && !exclude.has("harn-decide"),
     council: supported && !exclude.has("harn-council"),
     end: supported && !exclude.has("harn-end"),
+    team: supported && !exclude.has("harn-team"),
   };
 }
 

package/src/lib/instructions/templates.ts

@@ -34,6 +34,8 @@ export interface BlockSkills {
   council: boolean;
   /** the `harn-end` skill file is present */
   end: boolean;
+  /** the `harn-team` skill file is present */
+  team: boolean;
 }
 
 /**
@@ -50,7 +52,7 @@ export interface BlockSkills {
  */
 export function renderInstructionsBlock(
   binName: string,
-  skills: BlockSkills = { decide: true, council: true, end: true },
+  skills: BlockSkills = { decide: true, council: true, end: true, team: true },
 ): string {
   const b = binName;
 
@@ -58,6 +60,7 @@ export function renderInstructionsBlock(
     skills.decide && "`harn-decide`",
     skills.council && "`harn-council`",
     skills.end && "`harn-end`",
+    skills.team && "`harn-team`",
   ].filter(Boolean) as string[];
   const deeper =
     named.length > 0
@@ -72,6 +75,9 @@ export function renderInstructionsBlock(
   const endPointer = skills.end
     ? "When the whole session is genuinely finished, use the `harn-end` skill as the final workflow."
     : `When the whole session is genuinely finished, run \`${b} agents status --end-turn --end-session\` as the final tool action.`;
+  const teamPointer = skills.team
+    ? "The `harn-team` skill owns the tier choice, the governor artifacts, and the drive loop."
+    : `See \`${b} governor --help\` for the tier choice and the drive loop.`;
   // Render the journal categories from the canonical enum so this prose can
   // never drift from what `journal add` actually accepts (the "note, plan…" list
   // silently lagged the tool by two categories before this).
@@ -115,6 +121,7 @@ first when one pass will do, the second when the objective must outlive the
 attempt, and the third when a human would otherwise have to babysit the loop. A
 run that needs authorization parks durably instead of failing, so check
 \`${b} approval list\` when one appears to be waiting rather than stuck.
+${teamPointer}
 
 **Durable role handoff.** When you are replacing a prior session in the same
 named role, run \`${b} agents identity assume <name>\` before declaring your task.
@@ -123,9 +130,10 @@ live process still holds the name; never hand-edit Harnery's history, heartbeat,
 or derived identity cache.
 
 **Declare intent on shell commands.** Every command you run is captured to the
-coordination ledger. Lead a shell command with a \`# intent: <why>\` comment (or set
-the tool's description) so the recorded event carries a reason instead of
-\`(no intent)\`.
+coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
+\`# intent: <why>\` comment (or set the tool's description) so the recorded event
+carries a reason instead of \`(no intent)\`; the [tool-intent
+guide](https://harnery.com/guides/tool-intent/) owns the details.
 
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
@@ -139,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>"\`
@@ -370,6 +383,131 @@ explicitly identifies it. Use the web control or \`${b} agents end --instance-id
 durably queues the end for its current turn.`;
 }
 
+function teamBody(b: string): string {
+  return `Harnery gives you three ways to put more than one agent on a job. They differ
+by how long the objective outlives a single execution, and picking the wrong one
+is the usual reason a team spins. This skill owns that choice, the files a
+governed team needs, and the drive loop.
+
+## Step 0: do not build a second team
+
+Run this before anything else, every time:
+
+\`\`\`bash
+${b} governor list
+\`\`\`
+
+If a goal already covers the objective, **you are done building** — drive the
+existing one (Step 3). A second team pointed at the same tree fights the first:
+both hold the same files and their frozen missions contradict each other. It is
+the most expensive mistake available here, and it looks like progress while you
+make it. Listings are tolerant: an unreadable record prints a warning row with
+its id, which is evidence the goal *exists* — inspect it before creating a
+replacement. Treat stale or suffixed experiment goals as shared runtime state;
+archiving them is an operator call, not yours.
+
+## Step 1: pick the tier
+
+Match the tier to how long the objective must survive, not to how big it feels.
+
+| Surface | Use when | Dies when |
+|---|---|---|
+| \`${b} run <script>\` | One bounded pass: deterministic JS stages fan out to headless subagents. | The pass ends. Nothing remembers it. |
+| \`${b} work create <title> <workflow>\` | The objective must outlive the attempt: retries, failures, review rounds. | You accept or cancel it. |
+| \`${b} governor create\` | A graph of interdependent work with distinct roles, where a human would otherwise babysit the loop. | You accept the root or it exhausts its bounds. |
+
+When unsure, start with \`${b} run\`: it is the only tier you can throw away for
+free, and iterating a script there before freezing it is how you avoid
+invalidating a durable work item later. And check the sizing first: a single
+agent often matches a team on a task that does not truly decompose — reliability
+is multiplicative across steps, and the metric that decides is cost per
+completed task, not agent count.
+
+## Step 2: build the governor team
+
+Four artifacts, kept in a managed workspace
+(\`${b} artifacts create <slug> --purpose "<why>"\`), then frozen:
+
+**team.json** maps specialist id to profile: \`instructions\` (the role's whole
+charter) plus optional \`adapter\`, \`effort\`, \`maxAttempts\`. Two role rules
+carry most of the value: **split producing evidence from judging it** (a
+verifier that runs gates, a separate reviewer that accepts or refuses — no agent
+grades its own homework), and **add a standing scope-auditor** that reports at
+each milestone whether the finish line moved, since no one else is positioned to
+notice a rising bar. Write each role's hard boundaries explicitly, in the
+negative: name every act that is somebody else's. Write every brief as a
+four-part contract — objective, output (the named artifact that proves it),
+tools, boundaries — and pass references, not pasted content. \`timeoutMs\` and
+\`maxTurns\` are workflow-script options, never specialist-profile keys; the
+create command rejects unsupported keys with the offending key and the allowed
+set.
+
+**mission.json** carries \`objective\`, \`acceptance\` (criteria), and
+\`max_milestones\`. Write acceptance so **refusing is a representable outcome**
+("X exists, or the blocker is stated with its citation") — a criterion an agent
+cannot satisfy by correctly refusing gets reissued forever. Every criterion
+names the artifact that satisfies it (a path, a passing command, a review
+record); a criterion satisfiable by prose will eventually be satisfied exactly
+that way.
+
+**replanning.json** freezes the planner policy: \`planner_specialist\`,
+\`auto_apply\`, \`max_replans\`, \`max_work_items_per_plan\`,
+\`max_total_work_items\`, a \`templates\` catalog, and \`review\` with
+\`reviewer_specialists\` and \`max_revision_rounds\`. Keep \`auto_apply: false\`
+and proof auto-acceptance off for anything that can touch public state.
+
+**Workflow templates** are the plain-JS scripts the planner may choose from;
+route product decisions to a decision-brief template, never an implement one.
+Authoring traps (frozen script hashes, the five-minute \`timeoutMs\` default,
+schema caps, child sandboxes) live in the
+[workflow-authoring guide](https://harnery.com/guides/workflow-authoring/).
+
+\`\`\`bash
+${b} governor create --id <goal-id> --title "<title>" \\
+  --team <ws>/team.json --mission <ws>/mission.json \\
+  --replanning <ws>/replanning.json --max-parallel-work 2 --json
+\`\`\`
+
+## Step 3: drive it
+
+\`${b} governor show <goal-id> --json\` — the \`projection\` object is the whole
+dashboard: read \`state\`, \`reason\`, and \`next_action\`, then do exactly that
+action. Useful fields: \`ready_work\` / \`retryable_work\` / \`attention_work\`,
+\`decision_blocked_work\` (parked on a docket entry, not broken),
+\`replans_used\` / \`replans_remaining\`, and the milestone counters.
+
+\`\`\`bash
+${b} governor tick <goal-id>   # at most one scheduling cycle
+${b} governor run <goal-id>    # cycles until success, attention, or budget
+${b} approval list             # a run needing authorization parks, not fails
+\`\`\`
+
+Rules that prevent stranded work:
+
+- **Never drive a governed item with \`${b} work retry\` or \`${b} work run\`.**
+  Only the governor supplies the frozen specialist map; a bare retry starts a
+  run with no team, dies at the first specialist stage, and still burns the
+  attempt. \`${b} work retry\` is for standalone work only.
+- **A blocked item cannot be accepted.** When its objective was met out of band,
+  the door back is \`${b} work reopen\` plus a fresh governor cycle, not accept.
+- **Read the spin signals before retrying.** Zero milestones with climbing
+  \`replans_used\` and repeated reviewer rejections means the mission prose or
+  acceptance criteria are wrong, not the agents. Replans are capped; diagnose
+  first.
+- **A frozen mission cannot be edited** — deliberately. Pass corrections as
+  retry context on individual items, or create a new goal and cancel the old
+  one. Do not keep re-planning against prose you know is stale.
+- **"ended without terminal evidence"** means the child died before writing its
+  proof, not that the work failed. Check whether the outcome landed before
+  redoing it.
+
+## Reporting back
+
+Tell the operator which tier you chose and why, the goal id, the roles, and the
+single next action. If you declined to build a team because one already existed,
+say that first; it is the most useful sentence in the reply.`;
+}
+
 export const SKILLS: SkillTemplate[] = [
   {
     id: "harn-decide",
@@ -407,4 +545,16 @@ export const SKILLS: SkillTemplate[] = [
         body: endBody(binName),
       }),
   },
+  {
+    id: "harn-team",
+    relPath: "harn-team/SKILL.md",
+    render: (binName) =>
+      buildOwnedSkill({
+        name: "harn-team",
+        description:
+          "Stand up and drive a multi-agent team on an objective: pick between a bounded run, durable work, and a governed role team; build the governor artifacts; drive off projection.next_action. Use when asked to put a team of agents on a job, orchestrate agents, or check on a goal already running. Refuses to build a second team when one already covers the objective.",
+        binName,
+        body: teamBody(binName),
+      }),
+  },
 ];

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)}`;
+}