@smthrs/std 0.0.0-stage → 1.0.0-rc.12

package/dist/cjs/internal/GitWorktree.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Detached checkouts shared by checkpoint reads and baseline test runs.
+ *
+ * ## Host git never reads a file the agent can write that names a program
+ *
+ * The repository is the workspace's, and an agent can write its `.git`: a
+ * containerised agent writes it through the bind mount. Git reads programs out
+ * of that directory in more places than any list of `-c` overrides can close.
+ * Hooks and `core.fsmonitor` can be overridden, but a filter driver
+ * (`filter.<name>.clean`/`.smudge` in `.git/config`, selected by
+ * `.git/info/attributes`) cannot: git has no switch that ignores repository
+ * config or `$GIT_DIR/info/attributes`, and overriding each driver by name
+ * races an agent that keeps rewriting the file.
+ *
+ * So the git that records and checks out trees runs against a **shadow**
+ * `GIT_DIR`: a bare repository this module creates under the host's temporary
+ * directory for one operation and deletes afterwards. Its config, hooks and
+ * `info/attributes` are the ones `git init --template=` writes, which is none.
+ * `GIT_CONFIG_NOSYSTEM` and `GIT_CONFIG_GLOBAL=/dev/null` drop the host's own
+ * config files too, so the only settings are the ones on the command line.
+ * `GIT_OBJECT_DIRECTORY` points at the workspace's object store, because objects
+ * are data: git hashes and inflates them and never runs anything they say.
+ *
+ * What still touches the workspace repository is plain data:
+ *
+ * - `rev-parse` in the workspace, which resolves refs and paths and runs no
+ *   hook, filter, fsmonitor or other configured program;
+ * - `git config --file <workspace config>`, which reads or writes that one file
+ *   and follows no `include`;
+ * - a copy of the workspace index into the shadow, so the recorded tree holds
+ *   what the agent staged without the harness writing the agent's index; and
+ * - a handful of `core.*` settings that change how bytes are hashed
+ *   ({@link dataSettings}), each accepted only as a bare word.
+ *
+ * A materialized checkout gets its own standalone `.git`, written by this
+ * module as files, so a container can still run git in it: `HEAD` names the
+ * commit, `objects/info/alternates` points back at the workspace's objects by a
+ * relative path, and `index` is the one the checkout was written from. Host git
+ * never uses that directory; it is the container's.
+ *
+ * @since 1.0.0
+ */
+import type { ChildProcessSpawner } from "@smthrs/kernel/ChildProcessSpawner";
+import { Effect } from "effect";
+import * as StdError from "../StdError.ts";
+import * as Exec from "./Exec.ts";
+/**
+ * Where one workspace repository keeps what the shadow needs, as its own git
+ * reports it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Repository {
+    /** The root the caller named, without a trailing slash. */
+    readonly root: string;
+    /** The same directory, as git canonicalizes it. */
+    readonly toplevel: string;
+    /** The common git directory, which holds config and objects. */
+    readonly common: string;
+    /** The workspace index. */
+    readonly index: string;
+    readonly objectFormat: string;
+    /** {@link dataSettings} as `-c` arguments. */
+    readonly settings: ReadonlyArray<string>;
+}
+/**
+ * A harness-owned `GIT_DIR` over one workspace's objects.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Shadow {
+    readonly path: string;
+    readonly repository: Repository;
+    /** Runs host git with the shadow as `GIT_DIR`, and `workTree` as its work tree when given. */
+    readonly git: (args: ReadonlyArray<string>, workTree?: string) => Effect.Effect<Exec.ExecResult, StdError.StdError, ChildProcessSpawner>;
+    /**
+     * Copies the workspace index into the shadow, with its modification time, so
+     * the shadow never writes the agent's own.
+     *
+     * The time is part of what git reads. It trusts an entry's recorded stat
+     * unless the entry is at least as new as the index file, in whole seconds;
+     * a copy stamped at the moment of copying made every entry look older, and a
+     * same-size edit from the second the index was written was recorded as the
+     * committed bytes (#3431). The time is taken before the bytes are read, so
+     * an index rewritten meanwhile leaves the copy looking older, never newer.
+     */
+    readonly adoptIndex: Effect.Effect<void, StdError.StdError, ChildProcessSpawner>;
+}
+/**
+ * Internal Git operations used by both checkpoint and baseline leases.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export declare const GitWorktree: {
+    config: (repository: Pick<Repository, "common">, args: ReadonlyArray<string>) => Effect.Effect<Exec.ExecResult, StdError.StdError, ChildProcessSpawner>;
+    git: (root: string, args: ReadonlyArray<string>) => Effect.Effect<Exec.ExecResult, StdError.StdError, ChildProcessSpawner>;
+    open: (root: string) => Effect.Effect<Repository, StdError.StdError, ChildProcessSpawner>;
+    resolveCommit: (root: string, refs: ReadonlyArray<string>) => Effect.Effect<{
+        ref: string;
+        commit: string;
+    }, StdError.StdError, ChildProcessSpawner>;
+    withDetachedWorktree: <A, E, R>(repository: Repository, prefix: string, commit: string, use: (host: string) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | StdError.StdError, R | ChildProcessSpawner>;
+    withShadow: <A, E, R>(root: string | Repository, use: (shadow: Shadow) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | StdError.StdError, R | ChildProcessSpawner>;
+};
+//# sourceMappingURL=GitWorktree.d.ts.map

package/dist/cjs/internal/GitWorktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitWorktree.d.ts","sourceRoot":"","sources":["../../../src/internal/GitWorktree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AAC7E,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC1C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AA+CjC;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACzC;AAuDD;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,8FAA8F;IAC9F,QAAQ,CAAC,GAAG,EAAE,CACZ,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,QAAQ,CAAC,EAAE,MAAM,KACd,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAA;IAC3E;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAA;CACjF;AAmSD;;;;;GAKG;AACH,eAAO,MAAM,WAAW;yBA/WI,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,aAAa,CAAC,MAAM,CAAC;gBA1ChE,MAAM,QAAQ,aAAa,CAAC,MAAM,CAAC;iBA6ClC,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;0BA3CjE,MAAM,QAAQ,aAAa,CAAC,MAAM,CAAC;;;;2BAmXlC,CAAC,EAAE,CAAC,EAAE,CAAC,cACvB,UAAU,UACd,MAAM,UACN,MAAM,OACT,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC5C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,mBAAmB,CAAC;iBA3N/C,CAAC,EAAE,CAAC,EAAE,CAAC,QACnB,MAAM,GAAG,UAAU,OACpB,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC9C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,mBAAmB,CAAC;CAuP8B,CAAA"}

package/dist/cjs/internal/GitWorktree.js

@@ -0,0 +1,276 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var GitWorktree_exports = {};
+__export(GitWorktree_exports, {
+  GitWorktree: () => GitWorktree
+});
+module.exports = __toCommonJS(GitWorktree_exports);
+var import_effect = require("effect");
+var StdError = __toESM(require("../StdError.js"), 1);
+var Exec = __toESM(require("./Exec.js"), 1);
+const failed = (message, code = "command_failed") => new StdError.StdError({ code, message });
+const hostGitSettings = ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false"];
+const isolated = { GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" };
+const dataSettings = /^core\.(autocrlf|eol|safecrlf|filemode|symlinks|ignorecase|precomposeunicode)$/;
+const bareWord = /^[A-Za-z0-9_-]+$/;
+const run = (command, args, env) => Exec.exec(command, { args, ...env === void 0 ? {} : { env } }).pipe(
+  import_effect.Effect.mapError((error) => failed(`${command} could not run: ${error.message}`))
+);
+const git = (root, args) => run("git", [...hostGitSettings, "-C", root, ...args]);
+const resolveCommit = (root, refs) => import_effect.Effect.gen(function* () {
+  for (const ref of refs) {
+    const answer = yield* git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    const commit = answer.stdout.trim();
+    if (answer.exitCode === 0 && commit !== "") return { ref, commit };
+  }
+  return yield* import_effect.Effect.fail(failed(`No commit resolves from ${refs.join(" or ")} in ${root}.`, "not_found"));
+});
+const config = (repository, args) => run("git", ["--git-dir=/dev/null", "config", "--file", `${repository.common}/config`, ...args], isolated);
+const open = (root) => import_effect.Effect.gen(function* () {
+  const stripped = root.replace(/\/+$/, "");
+  const answer = yield* git(stripped, [
+    "rev-parse",
+    "--path-format=absolute",
+    "--show-toplevel",
+    "--git-common-dir",
+    "--git-path",
+    "index",
+    "--show-object-format"
+  ]);
+  const [toplevel, common, index, objectFormat] = answer.stdout.split("\n").map((line) => line.trim());
+  if (answer.exitCode !== 0 || toplevel === void 0 || toplevel === "" || common === void 0 || common === "" || index === void 0 || index === "" || objectFormat === void 0 || !bareWord.test(objectFormat)) {
+    return yield* import_effect.Effect.fail(failed(`${stripped} is not a git work tree: ${answer.stderr.trim()}`));
+  }
+  const found = yield* config({ common }, ["--get-regexp", dataSettings.source]);
+  const settings = found.exitCode === 0 ? found.stdout.split("\n").flatMap((line) => {
+    const [key, value] = line.trim().split(/\s+/);
+    return key !== void 0 && value !== void 0 && dataSettings.test(key) && bareWord.test(value) ? ["-c", `${key}=${value}`] : [];
+  }) : [];
+  return { root: stripped, toplevel, common, index, objectFormat, settings };
+});
+const temporaryRoot = () => {
+  const configured = globalThis.process?.env?.TMPDIR?.replace(/\/+$/, "");
+  return configured === void 0 || configured === "" ? "/tmp" : configured;
+};
+const remove = (path) => run("rm", ["-rf", "--", path]).pipe(
+  import_effect.Effect.flatMap((removed) => removed.exitCode === 0 ? import_effect.Effect.void : import_effect.Effect.fail(failed(removed.stderr.trim())))
+);
+const adoptIndexScript = [
+  "set -C",
+  'if [ -e "$1" ]',
+  'then : > "$2.at" && touch -r "$1" -- "$2.at" && cat -- "$1" > "$2" && touch -r "$2.at" -- "$2" && rm -f -- "$2.at"',
+  "fi"
+].join("; ");
+const shadowOf = (repository, path) => ({
+  path,
+  repository,
+  git: (args, workTree) => run(
+    "git",
+    [
+      `--git-dir=${path}`,
+      ...workTree === void 0 ? [] : [`--work-tree=${workTree}`],
+      ...hostGitSettings,
+      ...repository.settings,
+      ...args
+    ],
+    { ...isolated, GIT_OBJECT_DIRECTORY: `${repository.common}/objects` }
+  ),
+  adoptIndex: run("sh", [
+    "-c",
+    adoptIndexScript,
+    "sh",
+    repository.index,
+    `${path}/index`
+  ]).pipe(
+    import_effect.Effect.flatMap(
+      (copied) => copied.exitCode === 0 ? import_effect.Effect.void : import_effect.Effect.fail(failed(`Could not read the workspace index: ${copied.stderr.trim()}`))
+    )
+  )
+});
+const withShadow = (root, use) => import_effect.Effect.gen(function* () {
+  const repository = typeof root === "string" ? yield* open(root) : root;
+  const path = `${temporaryRoot()}/smithers-git-${globalThis.crypto.randomUUID()}`;
+  return yield* import_effect.Effect.acquireUseRelease(
+    import_effect.Effect.succeed(path),
+    () => import_effect.Effect.gen(function* () {
+      const created = yield* run(
+        "git",
+        ["init", "--quiet", "--bare", "--template=", `--object-format=${repository.objectFormat}`, path],
+        isolated
+      );
+      if (created.exitCode !== 0) {
+        return yield* import_effect.Effect.fail(failed(`Could not create a shadow repository: ${created.stderr.trim()}`));
+      }
+      return yield* use(shadowOf(repository, path));
+    }),
+    () => remove(path).pipe(
+      import_effect.Effect.catch(
+        (error) => import_effect.Effect.logWarning("could not remove a shadow repository").pipe(
+          import_effect.Effect.annotateLogs({ path, reason: error.message })
+        )
+      )
+    )
+  );
+});
+const relative = (from, to) => {
+  const source = from.split("/").filter((part) => part !== "");
+  const target = to.split("/").filter((part) => part !== "");
+  let shared = 0;
+  while (shared < source.length && shared < target.length && source[shared] === target[shared]) shared++;
+  return [...source.slice(shared).map(() => ".."), ...target.slice(shared)].join("/") || ".";
+};
+const checkoutConfig = (repository) => {
+  const sha1 = repository.objectFormat === "sha1";
+  const lines = [
+    "[core]",
+    `	repositoryformatversion = ${sha1 ? 0 : 1}`,
+    "	bare = false",
+    ...repository.settings.filter((_, index) => index % 2 === 1).map((setting) => {
+      const [key, value] = setting.split("=");
+      return `	${key?.slice("core.".length)} = ${value}`;
+    }),
+    ...sha1 ? [] : ["[extensions]", `	objectformat = ${repository.objectFormat}`]
+  ];
+  return `${lines.join("\n")}
+`;
+};
+const succeeded = (result, message) => result.exitCode === 0 ? import_effect.Effect.void : import_effect.Effect.fail(failed(`${message}: ${result.stderr.trim()}`));
+const measure = [
+  "set -e",
+  'mkdir -p -- "$1"',
+  'dev() { stat -c %d -- "$1" 2>/dev/null || stat -f %d -- "$1" 2>/dev/null || echo; }',
+  't=$(dev "$1")',
+  's=$(dev "$2")',
+  'if [ -w "$3" ]; then b=$(dev "$3"); else b=unwritable; fi',
+  "c=",
+  'if [ -n "$t" ] && [ "$t" != "$s" ] && [ "$t" != "$b" ] && [ -n "$4" ] && mkdir -p -m 700 -- "$4" 2>/dev/null; then c=$(dev "$4"); fi',
+  `printf '%s\\n' "$t" "$s" "$b" "$c"`
+].join("; ");
+const cacheRoot = () => {
+  const env = globalThis.process?.env;
+  const xdg = env?.XDG_CACHE_HOME?.replace(/\/+$/, "");
+  if (xdg !== void 0 && xdg.startsWith("/")) return `${xdg}/smithers`;
+  const home = env?.HOME?.replace(/\/+$/, "");
+  return home !== void 0 && home.startsWith("/") ? `${home}/.cache/smithers` : "";
+};
+const publish = [
+  "set -e",
+  'root=$(cd -P -- "$4" && pwd -P)',
+  'cd -P -- "$2"',
+  "here=$(pwd -P)",
+  'case "$here" in "$root"|"$root"/*) ;; *) echo "$2 resolves to $here, outside the workspace $root" >&2; exit 1 ;; esac',
+  'if [ -e "./$3" ] || [ -L "./$3" ]; then echo "$2/$3 already exists" >&2; exit 1; fi',
+  `staged=$(ls -di -- "$1" | awk '{print $1}')`,
+  'mv -- "$1" "./$3"',
+  'if [ -L "./$3" ] || [ ! -d "./$3" ]; then echo "$2/$3 was replaced while it was written" >&2; exit 1; fi',
+  `moved=$(ls -di -- "./$3" | awk '{print $1}')`,
+  'if [ "$staged" != "$moved" ]; then echo "$2/$3 was replaced while it was written" >&2; exit 1; fi'
+].join("; ");
+const checkout = (shadow, host, commit) => import_effect.Effect.gen(function* () {
+  const repository = shadow.repository;
+  const parent = host.slice(0, host.lastIndexOf("/"));
+  const name = host.slice(host.lastIndexOf("/") + 1);
+  const beside = repository.root.slice(0, repository.root.lastIndexOf("/")) || "/";
+  const cache = cacheRoot();
+  const stage = `checkout-${globalThis.crypto.randomUUID()}`;
+  const besideStage = `${beside.replace(/\/+$/, "")}/.smithers-${stage}`;
+  const cacheStage = `${cache}/${stage}`;
+  const measured = yield* run("sh", ["-c", measure, "sh", parent, shadow.path, beside, cache]);
+  yield* succeeded(measured, `Could not check out ${commit}`);
+  const [target, inShadow, besideRoot, inCache] = measured.stdout.split("\n").map((line) => line.trim());
+  const scratch = target === void 0 || target === "" || target === inShadow ? void 0 : target === besideRoot ? besideStage : target === inCache ? cacheStage : void 0;
+  const base = target === void 0 || target === "" ? void 0 : target === inShadow ? shadow.path : scratch;
+  if (base === void 0) {
+    const unwritable = besideRoot === "unwritable" ? " (not writable by this user)" : "";
+    return yield* import_effect.Effect.fail(
+      failed(
+        `Could not check out ${commit}: neither ${shadow.path} nor ${beside}${unwritable} nor ${cache === "" ? "a cache directory" : cache} is on the filesystem of ${parent}`
+      )
+    );
+  }
+  const staged = `${base}/${name}`;
+  const objects = relative(
+    `${repository.toplevel}${host.slice(repository.root.length)}/.git/objects`,
+    `${repository.common}/objects`
+  );
+  const write = import_effect.Effect.gen(function* () {
+    const prepared = yield* run("sh", [
+      "-c",
+      [
+        "set -eC",
+        ...scratch !== void 0 ? ['mkdir -m 700 -- "$1"'] : [],
+        'mkdir -- "$2" "$2/.git" "$2/.git/objects" "$2/.git/objects/info" "$2/.git/refs"',
+        `printf '%s\\n' "$3" > "$2/.git/HEAD"`,
+        `printf '%s\\n' "$4" > "$2/.git/objects/info/alternates"`,
+        `printf '%s' "$5" > "$2/.git/config"`
+      ].join("; "),
+      "sh",
+      base,
+      staged,
+      commit,
+      objects,
+      checkoutConfig(repository)
+    ]);
+    yield* succeeded(prepared, `Could not check out ${commit}`);
+    const written = yield* shadow.git(["read-tree", "--reset", "-u", commit], staged);
+    yield* succeeded(written, `Could not check out ${commit}`);
+    const indexed = yield* run("sh", [
+      "-c",
+      'set -C; cat -- "$1" > "$2"',
+      "sh",
+      `${shadow.path}/index`,
+      `${staged}/.git/index`
+    ]);
+    yield* succeeded(indexed, `Could not check out ${commit}`);
+    const moved = yield* run("sh", ["-c", publish, "sh", staged, parent, name, repository.root]);
+    yield* succeeded(moved, `Could not check out ${commit}`);
+  });
+  return yield* scratch !== void 0 ? write.pipe(import_effect.Effect.ensuring(remove(scratch).pipe(import_effect.Effect.ignore))) : write;
+});
+const withDetachedWorktree = (repository, prefix, commit, use) => import_effect.Effect.gen(function* () {
+  const host = `${repository.root}/${prefix}-${globalThis.crypto.randomUUID()}`;
+  return yield* import_effect.Effect.acquireUseRelease(
+    import_effect.Effect.succeed(host),
+    () => import_effect.Effect.gen(function* () {
+      yield* withShadow(repository, (shadow) => checkout(shadow, host, commit));
+      return yield* use(host);
+    }),
+    // A checkout left behind is a stale copy of the repository inside the
+    // workspace. Walks prune it, but the operator must still hear about it.
+    () => remove(host).pipe(
+      import_effect.Effect.catch(
+        (error) => import_effect.Effect.logWarning("could not remove a scratch checkout").pipe(
+          import_effect.Effect.annotateLogs({ path: host, reason: error.message })
+        )
+      )
+    )
+  );
+});
+const GitWorktree = { config, git, open, resolveCommit, withDetachedWorktree, withShadow };
+//# sourceMappingURL=GitWorktree.js.map

package/dist/cjs/internal/GitWorktree.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/GitWorktree.ts"],
+  "sourcesContent": ["/**\n * Detached checkouts shared by checkpoint reads and baseline test runs.\n *\n * ## Host git never reads a file the agent can write that names a program\n *\n * The repository is the workspace's, and an agent can write its `.git`: a\n * containerised agent writes it through the bind mount. Git reads programs out\n * of that directory in more places than any list of `-c` overrides can close.\n * Hooks and `core.fsmonitor` can be overridden, but a filter driver\n * (`filter.<name>.clean`/`.smudge` in `.git/config`, selected by\n * `.git/info/attributes`) cannot: git has no switch that ignores repository\n * config or `$GIT_DIR/info/attributes`, and overriding each driver by name\n * races an agent that keeps rewriting the file.\n *\n * So the git that records and checks out trees runs against a **shadow**\n * `GIT_DIR`: a bare repository this module creates under the host's temporary\n * directory for one operation and deletes afterwards. Its config, hooks and\n * `info/attributes` are the ones `git init --template=` writes, which is none.\n * `GIT_CONFIG_NOSYSTEM` and `GIT_CONFIG_GLOBAL=/dev/null` drop the host's own\n * config files too, so the only settings are the ones on the command line.\n * `GIT_OBJECT_DIRECTORY` points at the workspace's object store, because objects\n * are data: git hashes and inflates them and never runs anything they say.\n *\n * What still touches the workspace repository is plain data:\n *\n * - `rev-parse` in the workspace, which resolves refs and paths and runs no\n *   hook, filter, fsmonitor or other configured program;\n * - `git config --file <workspace config>`, which reads or writes that one file\n *   and follows no `include`;\n * - a copy of the workspace index into the shadow, so the recorded tree holds\n *   what the agent staged without the harness writing the agent's index; and\n * - a handful of `core.*` settings that change how bytes are hashed\n *   ({@link dataSettings}), each accepted only as a bare word.\n *\n * A materialized checkout gets its own standalone `.git`, written by this\n * module as files, so a container can still run git in it: `HEAD` names the\n * commit, `objects/info/alternates` points back at the workspace's objects by a\n * relative path, and `index` is the one the checkout was written from. Host git\n * never uses that directory; it is the container's.\n *\n * @since 1.0.0\n */\n\nimport type { ChildProcessSpawner } from \"@smthrs/kernel/ChildProcessSpawner\"\nimport { Effect } from \"effect\"\nimport * as StdError from \"../StdError.ts\"\nimport * as Exec from \"./Exec.ts\"\n\nconst failed = (message: string, code: StdError.Code = \"command_failed\") => new StdError.StdError({ code, message })\n\n/**\n * Settings that stop the workspace repository from naming a program for the\n * `rev-parse` this module runs in it. `rev-parse` runs none of them; these keep\n * that true if a later call is added beside it.\n */\nconst hostGitSettings = [\"-c\", \"core.hooksPath=/dev/null\", \"-c\", \"core.fsmonitor=false\"] as const\n\n/** Host config files git would otherwise read, removed from every shadow command. */\nconst isolated = { GIT_CONFIG_NOSYSTEM: \"1\", GIT_CONFIG_GLOBAL: \"/dev/null\" } as const\n\n/**\n * Workspace settings that change how a tree is hashed or compared, carried\n * onto the shadow so a checkpoint records what the agent's own git would.\n * None of them names a program.\n */\nconst dataSettings = /^core\\.(autocrlf|eol|safecrlf|filemode|symlinks|ignorecase|precomposeunicode)$/\n\n/** A setting value this module will repeat to git: a bare word, never a command. */\nconst bareWord = /^[A-Za-z0-9_-]+$/\n\nconst run = (command: string, args: ReadonlyArray<string>, env?: Readonly<Record<string, string>>) =>\n  Exec.exec(command, { args, ...(env === undefined ? {} : { env }) }).pipe(\n    Effect.mapError((error) => failed(`${command} could not run: ${error.message}`))\n  )\n\n/**\n * Runs host git in the workspace at `root`, for `rev-parse` only.\n *\n * @category utilities\n * @since 1.0.0\n */\nconst git = (root: string, args: ReadonlyArray<string>) => run(\"git\", [...hostGitSettings, \"-C\", root, ...args])\n\nconst resolveCommit = (root: string, refs: ReadonlyArray<string>) =>\n  Effect.gen(function*() {\n    for (const ref of refs) {\n      const answer = yield* git(root, [\"rev-parse\", \"--verify\", \"--quiet\", `${ref}^{commit}`])\n      const commit = answer.stdout.trim()\n      if (answer.exitCode === 0 && commit !== \"\") return { ref, commit }\n    }\n    return yield* Effect.fail(failed(`No commit resolves from ${refs.join(\" or \")} in ${root}.`, \"not_found\"))\n  })\n\n/**\n * Where one workspace repository keeps what the shadow needs, as its own git\n * reports it.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Repository {\n  /** The root the caller named, without a trailing slash. */\n  readonly root: string\n  /** The same directory, as git canonicalizes it. */\n  readonly toplevel: string\n  /** The common git directory, which holds config and objects. */\n  readonly common: string\n  /** The workspace index. */\n  readonly index: string\n  readonly objectFormat: string\n  /** {@link dataSettings} as `-c` arguments. */\n  readonly settings: ReadonlyArray<string>\n}\n\n/**\n * Reads or writes the workspace's config file as a file, never as a repository.\n *\n * `--git-dir=/dev/null` stops git discovering any repository around the host's\n * working directory, and `--file` reads the one file without `include`s.\n *\n * @category utilities\n * @since 1.0.0\n */\nconst config = (repository: Pick<Repository, \"common\">, args: ReadonlyArray<string>) =>\n  run(\"git\", [\"--git-dir=/dev/null\", \"config\", \"--file\", `${repository.common}/config`, ...args], isolated)\n\nconst open = (root: string): Effect.Effect<Repository, StdError.StdError, ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    const stripped = root.replace(/\\/+$/, \"\")\n    const answer = yield* git(stripped, [\n      \"rev-parse\",\n      \"--path-format=absolute\",\n      \"--show-toplevel\",\n      \"--git-common-dir\",\n      \"--git-path\",\n      \"index\",\n      \"--show-object-format\"\n    ])\n    const [toplevel, common, index, objectFormat] = answer.stdout.split(\"\\n\").map((line) => line.trim())\n    if (\n      answer.exitCode !== 0 || toplevel === undefined || toplevel === \"\" || common === undefined || common === \"\" ||\n      index === undefined || index === \"\" || objectFormat === undefined || !bareWord.test(objectFormat)\n    ) {\n      return yield* Effect.fail(failed(`${stripped} is not a git work tree: ${answer.stderr.trim()}`))\n    }\n    const found = yield* config({ common }, [\"--get-regexp\", dataSettings.source])\n    const settings = found.exitCode === 0\n      ? found.stdout.split(\"\\n\").flatMap((line) => {\n        const [key, value] = line.trim().split(/\\s+/)\n        return key !== undefined && value !== undefined && dataSettings.test(key) && bareWord.test(value)\n          ? [\"-c\", `${key}=${value}`]\n          : []\n      })\n      : []\n    return { root: stripped, toplevel, common, index, objectFormat, settings }\n  })\n\nconst temporaryRoot = (): string => {\n  const configured = globalThis.process?.env?.TMPDIR?.replace(/\\/+$/, \"\")\n  return configured === undefined || configured === \"\" ? \"/tmp\" : configured\n}\n\nconst remove = (path: string) =>\n  run(\"rm\", [\"-rf\", \"--\", path]).pipe(\n    Effect.flatMap((removed) => removed.exitCode === 0 ? Effect.void : Effect.fail(failed(removed.stderr.trim())))\n  )\n\n/**\n * A harness-owned `GIT_DIR` over one workspace's objects.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Shadow {\n  readonly path: string\n  readonly repository: Repository\n  /** Runs host git with the shadow as `GIT_DIR`, and `workTree` as its work tree when given. */\n  readonly git: (\n    args: ReadonlyArray<string>,\n    workTree?: string\n  ) => Effect.Effect<Exec.ExecResult, StdError.StdError, ChildProcessSpawner>\n  /**\n   * Copies the workspace index into the shadow, with its modification time, so\n   * the shadow never writes the agent's own.\n   *\n   * The time is part of what git reads. It trusts an entry's recorded stat\n   * unless the entry is at least as new as the index file, in whole seconds;\n   * a copy stamped at the moment of copying made every entry look older, and a\n   * same-size edit from the second the index was written was recorded as the\n   * committed bytes (#3431). The time is taken before the bytes are read, so\n   * an index rewritten meanwhile leaves the copy looking older, never newer.\n   */\n  readonly adoptIndex: Effect.Effect<void, StdError.StdError, ChildProcessSpawner>\n}\n\n/** The `adoptIndex` script: `$1` is the workspace index, `$2` the shadow's. */\nconst adoptIndexScript = [\n  \"set -C\",\n  \"if [ -e \\\"$1\\\" ]\",\n  \"then : > \\\"$2.at\\\" && touch -r \\\"$1\\\" -- \\\"$2.at\\\" && cat -- \\\"$1\\\" > \\\"$2\\\" && touch -r \\\"$2.at\\\" -- \\\"$2\\\" && rm -f -- \\\"$2.at\\\"\",\n  \"fi\"\n].join(\"; \")\n\nconst shadowOf = (repository: Repository, path: string): Shadow => ({\n  path,\n  repository,\n  git: (args, workTree) =>\n    run(\n      \"git\",\n      [\n        `--git-dir=${path}`,\n        ...(workTree === undefined ? [] : [`--work-tree=${workTree}`]),\n        ...hostGitSettings,\n        ...repository.settings,\n        ...args\n      ],\n      { ...isolated, GIT_OBJECT_DIRECTORY: `${repository.common}/objects` }\n    ),\n  adoptIndex: run(\"sh\", [\n    \"-c\",\n    adoptIndexScript,\n    \"sh\",\n    repository.index,\n    `${path}/index`\n  ]).pipe(\n    Effect.flatMap((copied) =>\n      copied.exitCode === 0\n        ? Effect.void\n        : Effect.fail(failed(`Could not read the workspace index: ${copied.stderr.trim()}`))\n    )\n  )\n})\n\n/**\n * Runs `use` with a fresh {@link Shadow} over the repository at `root`, and\n * deletes the shadow however `use` ends.\n *\n * @category utilities\n * @since 1.0.0\n */\nconst withShadow = <A, E, R>(\n  root: string | Repository,\n  use: (shadow: Shadow) => Effect.Effect<A, E, R>\n): Effect.Effect<A, E | StdError.StdError, R | ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    const repository = typeof root === \"string\" ? yield* open(root) : root\n    const path = `${temporaryRoot()}/smithers-git-${globalThis.crypto.randomUUID()}`\n    return yield* Effect.acquireUseRelease(\n      Effect.succeed(path),\n      () =>\n        Effect.gen(function*() {\n          const created = yield* run(\n            \"git\",\n            [\"init\", \"--quiet\", \"--bare\", \"--template=\", `--object-format=${repository.objectFormat}`, path],\n            isolated\n          )\n          if (created.exitCode !== 0) {\n            return yield* Effect.fail(failed(`Could not create a shadow repository: ${created.stderr.trim()}`))\n          }\n          return yield* use(shadowOf(repository, path))\n        }),\n      () =>\n        remove(path).pipe(\n          Effect.catch((error) =>\n            Effect.logWarning(\"could not remove a shadow repository\").pipe(\n              Effect.annotateLogs({ path, reason: error.message })\n            )\n          )\n        )\n    )\n  })\n\n/** `to` relative to `from`, both absolute POSIX paths. */\nconst relative = (from: string, to: string): string => {\n  const source = from.split(\"/\").filter((part) => part !== \"\")\n  const target = to.split(\"/\").filter((part) => part !== \"\")\n  let shared = 0\n  while (shared < source.length && shared < target.length && source[shared] === target[shared]) shared++\n  return [...source.slice(shared).map(() => \"..\"), ...target.slice(shared)].join(\"/\") || \".\"\n}\n\n/**\n * The config of a checkout's own `.git`, for the container's git.\n *\n * Only {@link dataSettings}, already restricted to bare words, reach it.\n */\nconst checkoutConfig = (repository: Repository): string => {\n  const sha1 = repository.objectFormat === \"sha1\"\n  const lines = [\n    \"[core]\",\n    `\\trepositoryformatversion = ${sha1 ? 0 : 1}`,\n    \"\\tbare = false\",\n    ...repository.settings.filter((_, index) => index % 2 === 1).map((setting) => {\n      const [key, value] = setting.split(\"=\")\n      return `\\t${key?.slice(\"core.\".length)} = ${value}`\n    }),\n    ...(sha1 ? [] : [\"[extensions]\", `\\tobjectformat = ${repository.objectFormat}`])\n  ]\n  return `${lines.join(\"\\n\")}\\n`\n}\n\n/** Fails with `message` and the command's stderr unless it exited 0. */\nconst succeeded = (result: Exec.ExecResult, message: string) =>\n  result.exitCode === 0 ? Effect.void : Effect.fail(failed(`${message}: ${result.stderr.trim()}`))\n\n/**\n * Measures which staging directory shares the filesystem of the checkout's\n * parent `$1`: the shadow `$2`, the workspace root's parent `$3`, or the host\n * cache directory `$4`. Prints one line each for the parent, the shadow, the\n * root's parent (`unwritable` when the host user cannot create a stage there)\n * and the cache (empty unless both others missed and it could be created).\n * `stat -c` is GNU and BusyBox, `stat -f` is BSD; an empty line means neither\n * answered.\n */\nconst measure = [\n  \"set -e\",\n  \"mkdir -p -- \\\"$1\\\"\",\n  \"dev() { stat -c %d -- \\\"$1\\\" 2>/dev/null || stat -f %d -- \\\"$1\\\" 2>/dev/null || echo; }\",\n  \"t=$(dev \\\"$1\\\")\",\n  \"s=$(dev \\\"$2\\\")\",\n  \"if [ -w \\\"$3\\\" ]; then b=$(dev \\\"$3\\\"); else b=unwritable; fi\",\n  \"c=\",\n  \"if [ -n \\\"$t\\\" ] && [ \\\"$t\\\" != \\\"$s\\\" ] && [ \\\"$t\\\" != \\\"$b\\\" ] && [ -n \\\"$4\\\" ] && mkdir -p -m 700 -- \\\"$4\\\" 2>/dev/null; then c=$(dev \\\"$4\\\"); fi\",\n  \"printf '%s\\\\n' \\\"$t\\\" \\\"$s\\\" \\\"$b\\\" \\\"$c\\\"\"\n].join(\"; \")\n\n/**\n * The host user's cache directory for checkout stages: `$XDG_CACHE_HOME`, or\n * `~/.cache`, under `smithers`. Empty when neither is an absolute path.\n */\nconst cacheRoot = (): string => {\n  const env = globalThis.process?.env\n  const xdg = env?.XDG_CACHE_HOME?.replace(/\\/+$/, \"\")\n  if (xdg !== undefined && xdg.startsWith(\"/\")) return `${xdg}/smithers`\n  const home = env?.HOME?.replace(/\\/+$/, \"\")\n  return home !== undefined && home.startsWith(\"/\") ? `${home}/.cache/smithers` : \"\"\n}\n\n/**\n * Moves the staged checkout `$1` into the directory `$2` under the name `$3`\n * in one `rename`, then proves the directory there is the one that was staged.\n * The staging directory is on the same filesystem, so `mv` renames and never\n * copies.\n *\n * The shell first enters `$2` by its physical path and refuses unless that\n * lies under the real path of the workspace root `$4`. The rename then names\n * the target relative to that directory, so a parent the agent swaps for a\n * symlink, before or after the check, cannot carry the checkout out of the\n * workspace.\n */\nconst publish = [\n  \"set -e\",\n  \"root=$(cd -P -- \\\"$4\\\" && pwd -P)\",\n  \"cd -P -- \\\"$2\\\"\",\n  \"here=$(pwd -P)\",\n  \"case \\\"$here\\\" in \\\"$root\\\"|\\\"$root\\\"/*) ;; *) echo \\\"$2 resolves to $here, outside the workspace $root\\\" >&2; exit 1 ;; esac\",\n  \"if [ -e \\\"./$3\\\" ] || [ -L \\\"./$3\\\" ]; then echo \\\"$2/$3 already exists\\\" >&2; exit 1; fi\",\n  \"staged=$(ls -di -- \\\"$1\\\" | awk '{print $1}')\",\n  \"mv -- \\\"$1\\\" \\\"./$3\\\"\",\n  \"if [ -L \\\"./$3\\\" ] || [ ! -d \\\"./$3\\\" ]; then echo \\\"$2/$3 was replaced while it was written\\\" >&2; exit 1; fi\",\n  \"moved=$(ls -di -- \\\"./$3\\\" | awk '{print $1}')\",\n  \"if [ \\\"$staged\\\" != \\\"$moved\\\" ]; then echo \\\"$2/$3 was replaced while it was written\\\" >&2; exit 1; fi\"\n].join(\"; \")\n\n/**\n * Checks `commit`'s tree out at the new directory `host`, with a standalone\n * `.git` the container's git can use.\n *\n * Host git never writes into an agent-writable directory. The tree and its\n * `.git` are written into a staging directory the agent cannot reach: inside\n * the shadow, or, when the host's temporary directory is another filesystem,\n * beside the workspace root or under the host user's cache directory. One\n * `rename` then gives the finished directory its name under the workspace. A\n * path the agent swaps for a symlink cannot redirect a write: a symlink at\n * `host` fails the call before the rename, and a parent that resolves outside\n * the workspace root fails it before the rename too.\n */\nconst checkout = (shadow: Shadow, host: string, commit: string) =>\n  Effect.gen(function*() {\n    const repository = shadow.repository\n    const parent = host.slice(0, host.lastIndexOf(\"/\"))\n    const name = host.slice(host.lastIndexOf(\"/\") + 1)\n    const beside = repository.root.slice(0, repository.root.lastIndexOf(\"/\")) || \"/\"\n    const cache = cacheRoot()\n    const stage = `checkout-${globalThis.crypto.randomUUID()}`\n    const besideStage = `${beside.replace(/\\/+$/, \"\")}/.smithers-${stage}`\n    const cacheStage = `${cache}/${stage}`\n    const measured = yield* run(\"sh\", [\"-c\", measure, \"sh\", parent, shadow.path, beside, cache])\n    yield* succeeded(measured, `Could not check out ${commit}`)\n    const [target, inShadow, besideRoot, inCache] = measured.stdout.split(\"\\n\").map((line) => line.trim())\n    const scratch = target === undefined || target === \"\" || target === inShadow\n      ? undefined\n      : target === besideRoot\n      ? besideStage\n      : target === inCache\n      ? cacheStage\n      : undefined\n    const base = target === undefined || target === \"\"\n      ? undefined\n      : target === inShadow\n      ? shadow.path\n      : scratch\n    if (base === undefined) {\n      const unwritable = besideRoot === \"unwritable\" ? \" (not writable by this user)\" : \"\"\n      return yield* Effect.fail(\n        failed(\n          `Could not check out ${commit}: neither ${shadow.path} nor ${beside}${unwritable} nor ${\n            cache === \"\" ? \"a cache directory\" : cache\n          } is on the filesystem of ${parent}`\n        )\n      )\n    }\n    const staged = `${base}/${name}`\n    const objects = relative(\n      `${repository.toplevel}${host.slice(repository.root.length)}/.git/objects`,\n      `${repository.common}/objects`\n    )\n    const write = Effect.gen(function*() {\n      const prepared = yield* run(\"sh\", [\n        \"-c\",\n        [\n          \"set -eC\",\n          ...(scratch !== undefined ? [\"mkdir -m 700 -- \\\"$1\\\"\"] : []),\n          \"mkdir -- \\\"$2\\\" \\\"$2/.git\\\" \\\"$2/.git/objects\\\" \\\"$2/.git/objects/info\\\" \\\"$2/.git/refs\\\"\",\n          \"printf '%s\\\\n' \\\"$3\\\" > \\\"$2/.git/HEAD\\\"\",\n          \"printf '%s\\\\n' \\\"$4\\\" > \\\"$2/.git/objects/info/alternates\\\"\",\n          \"printf '%s' \\\"$5\\\" > \\\"$2/.git/config\\\"\"\n        ].join(\"; \"),\n        \"sh\",\n        base,\n        staged,\n        commit,\n        objects,\n        checkoutConfig(repository)\n      ])\n      yield* succeeded(prepared, `Could not check out ${commit}`)\n      const written = yield* shadow.git([\"read-tree\", \"--reset\", \"-u\", commit], staged)\n      yield* succeeded(written, `Could not check out ${commit}`)\n      const indexed = yield* run(\"sh\", [\n        \"-c\",\n        \"set -C; cat -- \\\"$1\\\" > \\\"$2\\\"\",\n        \"sh\",\n        `${shadow.path}/index`,\n        `${staged}/.git/index`\n      ])\n      yield* succeeded(indexed, `Could not check out ${commit}`)\n      const moved = yield* run(\"sh\", [\"-c\", publish, \"sh\", staged, parent, name, repository.root])\n      yield* succeeded(moved, `Could not check out ${commit}`)\n    })\n    return yield* scratch !== undefined\n      ? write.pipe(Effect.ensuring(remove(scratch).pipe(Effect.ignore)))\n      : write\n  })\n\nconst withDetachedWorktree = <A, E, R>(\n  repository: Repository,\n  prefix: string,\n  commit: string,\n  use: (host: string) => Effect.Effect<A, E, R>\n): Effect.Effect<A, E | StdError.StdError, R | ChildProcessSpawner> =>\n  Effect.gen(function*() {\n    // Allocate on execution, including when the same Effect is run twice.\n    // Never remove an existing checkout: another call may still be using it.\n    const host = `${repository.root}/${prefix}-${globalThis.crypto.randomUUID()}`\n    return yield* Effect.acquireUseRelease(\n      Effect.succeed(host),\n      () =>\n        Effect.gen(function*() {\n          yield* withShadow(repository, (shadow) => checkout(shadow, host, commit))\n          return yield* use(host)\n        }),\n      // A checkout left behind is a stale copy of the repository inside the\n      // workspace. Walks prune it, but the operator must still hear about it.\n      () =>\n        remove(host).pipe(\n          Effect.catch((error) =>\n            Effect.logWarning(\"could not remove a scratch checkout\").pipe(\n              Effect.annotateLogs({ path: host, reason: error.message })\n            )\n          )\n        )\n    )\n  })\n\n/**\n * Internal Git operations used by both checkpoint and baseline leases.\n *\n * @category utilities\n * @since 1.0.0\n */\nexport const GitWorktree = { config, git, open, resolveCommit, withDetachedWorktree, withShadow }\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/internal/Grouping.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Match-centric grep results: the limit counts matches, and context rides
+ * inside the match it belongs to.
+ *
+ * A flat list of rows made `limit` a row budget, and a row budget can spend
+ * itself on context and drop the match. That is not a display detail: on
+ * astropy-7166 the clip dropped the match row twice and cost three frames of
+ * guard-bailing, because the agent could see the lines around its hit and not
+ * the hit. Ripgrep's own JSON groups by match for the same reason.
+ *
+ * Both peers group here rather than each in its own way, so the native and
+ * in-process implementations cannot drift on what a limit means or on which
+ * match owns a shared context line.
+ *
+ * @since 1.0.0
+ */
+import type * as Search from "../Search.ts";
+/**
+ * A file's text as the numbered lines both peers count.
+ *
+ * This is `Text.sourceLines` under the name the search peers reach for, not a
+ * second copy of it. There used to be two byte-identical definitions of the
+ * rule, one here and one in `internal/Text.ts`, and a divergence between them
+ * is exactly how `read` came to report one more line than `grep` for every
+ * file ending in a newline. One definition cannot drift from itself.
+ *
+ * @category search
+ * @since 1.0.0
+ */
+export declare const sourceLines: (content: string) => ReadonlyArray<string>;
+/**
+ * Groups a peer's flat rows into matches, each carrying its own context.
+ *
+ * @category search
+ * @since 1.0.0
+ */
+export declare const group: (lines: ReadonlyArray<Search.GrepLine>) => ReadonlyArray<Search.GrepMatch>;
+/**
+ * Attaches each hit's enclosing definition, for the hits actually being
+ * returned.
+ *
+ * `contents` holds a matched file's lines. A peer that does not have them — the
+ * `rg` process reports lines, not files — reads only the files whose hits
+ * survived the limit, so the cost is bounded by what the caller receives rather
+ * than by what the search covered.
+ *
+ * @category search
+ * @since 1.0.0
+ */
+export declare const annotate: (matches: ReadonlyArray<Search.GrepMatch>, contents: ReadonlyMap<string, ReadonlyArray<string>>) => ReadonlyArray<Search.GrepMatch>;
+//# sourceMappingURL=Grouping.d.ts.map

package/dist/cjs/internal/Grouping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Grouping.d.ts","sourceRoot":"","sources":["../../../src/internal/Grouping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,MAAM,MAAM,cAAc,CAAA;AAI3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,aAAa,CAAC,MAAM,CAAoB,CAAA;AAgBvF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAChB,OAAO,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,KACpC,aAAa,CAAC,MAAM,CAAC,SAAS,CA0BhC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GACnB,SAAS,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,EACxC,UAAU,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,KACnD,aAAa,CAAC,MAAM,CAAC,SAAS,CAK7B,CAAA"}

package/dist/cjs/internal/Grouping.js

@@ -0,0 +1,83 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Grouping_exports = {};
+__export(Grouping_exports, {
+  annotate: () => annotate,
+  group: () => group,
+  sourceLines: () => sourceLines
+});
+module.exports = __toCommonJS(Grouping_exports);
+var Symbols = __toESM(require("./Symbols.js"), 1);
+var Text = __toESM(require("./Text.js"), 1);
+const sourceLines = Text.sourceLines;
+const owner = (matches, line) => {
+  let best = 0;
+  let distance = Number.POSITIVE_INFINITY;
+  for (let index = 0; index < matches.length; index++) {
+    const candidate = Math.abs(matches[index] - line);
+    if (candidate < distance) {
+      best = index;
+      distance = candidate;
+    }
+  }
+  return best;
+};
+const group = (lines) => {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const line of lines) {
+    const existing = byFile.get(line.file);
+    if (existing === void 0) byFile.set(line.file, [line]);
+    else existing.push(line);
+  }
+  const grouped = [];
+  for (const [file, rows] of byFile) {
+    const matches = rows.filter((row) => row.kind === "match");
+    if (matches.length === 0) continue;
+    const numbers = matches.map((row) => row.line);
+    const before = matches.map(() => []);
+    const after = matches.map(() => []);
+    for (const row of rows) {
+      if (row.kind !== "context") continue;
+      const index = owner(numbers, row.line);
+      const bucket = row.line < numbers[index] ? before[index] : after[index];
+      bucket.push({ line: row.line, text: row.text });
+    }
+    for (let index = 0; index < matches.length; index++) {
+      const row = matches[index];
+      grouped.push({ file, line: row.line, text: row.text, before: before[index], after: after[index] });
+    }
+  }
+  return grouped;
+};
+const annotate = (matches, contents) => matches.map((match) => {
+  const source = contents.get(match.file);
+  const symbol = source === void 0 ? void 0 : Symbols.enclosing(source, match.line);
+  return symbol === void 0 ? match : { ...match, symbol };
+});
+//# sourceMappingURL=Grouping.js.map

package/dist/cjs/internal/Grouping.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/Grouping.ts"],
+  "sourcesContent": ["/**\n * Match-centric grep results: the limit counts matches, and context rides\n * inside the match it belongs to.\n *\n * A flat list of rows made `limit` a row budget, and a row budget can spend\n * itself on context and drop the match. That is not a display detail: on\n * astropy-7166 the clip dropped the match row twice and cost three frames of\n * guard-bailing, because the agent could see the lines around its hit and not\n * the hit. Ripgrep's own JSON groups by match for the same reason.\n *\n * Both peers group here rather than each in its own way, so the native and\n * in-process implementations cannot drift on what a limit means or on which\n * match owns a shared context line.\n *\n * @since 1.0.0\n */\n\nimport type * as Search from \"../Search.ts\"\nimport * as Symbols from \"./Symbols.ts\"\nimport * as Text from \"./Text.ts\"\n\n/**\n * A file's text as the numbered lines both peers count.\n *\n * This is `Text.sourceLines` under the name the search peers reach for, not a\n * second copy of it. There used to be two byte-identical definitions of the\n * rule, one here and one in `internal/Text.ts`, and a divergence between them\n * is exactly how `read` came to report one more line than `grep` for every\n * file ending in a newline. One definition cannot drift from itself.\n *\n * @category search\n * @since 1.0.0\n */\nexport const sourceLines: (content: string) => ReadonlyArray<string> = Text.sourceLines\n\n/** Every context line belongs to exactly one match: the nearest, earliest on a tie. */\nconst owner = (matches: ReadonlyArray<number>, line: number): number => {\n  let best = 0\n  let distance = Number.POSITIVE_INFINITY\n  for (let index = 0; index < matches.length; index++) {\n    const candidate = Math.abs(matches[index]! - line)\n    if (candidate < distance) {\n      best = index\n      distance = candidate\n    }\n  }\n  return best\n}\n\n/**\n * Groups a peer's flat rows into matches, each carrying its own context.\n *\n * @category search\n * @since 1.0.0\n */\nexport const group = (\n  lines: ReadonlyArray<Search.GrepLine>\n): ReadonlyArray<Search.GrepMatch> => {\n  const byFile = new Map<string, Array<Search.GrepLine>>()\n  for (const line of lines) {\n    const existing = byFile.get(line.file)\n    if (existing === undefined) byFile.set(line.file, [line])\n    else existing.push(line)\n  }\n  const grouped: Array<Search.GrepMatch> = []\n  for (const [file, rows] of byFile) {\n    const matches = rows.filter((row) => row.kind === \"match\")\n    if (matches.length === 0) continue\n    const numbers = matches.map((row) => row.line)\n    const before = matches.map((): Array<Search.ContextLine> => [])\n    const after = matches.map((): Array<Search.ContextLine> => [])\n    for (const row of rows) {\n      if (row.kind !== \"context\") continue\n      const index = owner(numbers, row.line)\n      const bucket = row.line < numbers[index]! ? before[index]! : after[index]!\n      bucket.push({ line: row.line, text: row.text })\n    }\n    for (let index = 0; index < matches.length; index++) {\n      const row = matches[index]!\n      grouped.push({ file, line: row.line, text: row.text, before: before[index]!, after: after[index]! })\n    }\n  }\n  return grouped\n}\n\n/**\n * Attaches each hit's enclosing definition, for the hits actually being\n * returned.\n *\n * `contents` holds a matched file's lines. A peer that does not have them \u2014 the\n * `rg` process reports lines, not files \u2014 reads only the files whose hits\n * survived the limit, so the cost is bounded by what the caller receives rather\n * than by what the search covered.\n *\n * @category search\n * @since 1.0.0\n */\nexport const annotate = (\n  matches: ReadonlyArray<Search.GrepMatch>,\n  contents: ReadonlyMap<string, ReadonlyArray<string>>\n): ReadonlyArray<Search.GrepMatch> =>\n  matches.map((match) => {\n    const source = contents.get(match.file)\n    const symbol = source === undefined ? undefined : Symbols.enclosing(source, match.line)\n    return symbol === undefined ? match : { ...match, symbol }\n  })\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,cAAyB;AACzB,WAAsB;AAcf,MAAM,cAA0D,KAAK;AAG5E,MAAM,QAAQ,CAAC,SAAgC,SAAyB;AACtE,MAAI,OAAO;AACX,MAAI,WAAW,OAAO;AACtB,WAAS,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS;AACnD,UAAM,YAAY,KAAK,IAAI,QAAQ,KAAK,IAAK,IAAI;AACjD,QAAI,YAAY,UAAU;AACxB,aAAO;AACP,iBAAW;AAAA,IACb;AAAA,EACF;AACA,SAAO;AACT;AAQO,MAAM,QAAQ,CACnB,UACoC;AACpC,QAAM,SAAS,oBAAI,IAAoC;AACvD,aAAW,QAAQ,OAAO;AACxB,UAAM,WAAW,OAAO,IAAI,KAAK,IAAI;AACrC,QAAI,aAAa,OAAW,QAAO,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC;AAAA,QACnD,UAAS,KAAK,IAAI;AAAA,EACzB;AACA,QAAM,UAAmC,CAAC;AAC1C,aAAW,CAAC,MAAM,IAAI,KAAK,QAAQ;AACjC,UAAM,UAAU,KAAK,OAAO,CAAC,QAAQ,IAAI,SAAS,OAAO;AACzD,QAAI,QAAQ,WAAW,EAAG;AAC1B,UAAM,UAAU,QAAQ,IAAI,CAAC,QAAQ,IAAI,IAAI;AAC7C,UAAM,SAAS,QAAQ,IAAI,MAAiC,CAAC,CAAC;AAC9D,UAAM,QAAQ,QAAQ,IAAI,MAAiC,CAAC,CAAC;AAC7D,eAAW,OAAO,MAAM;AACtB,UAAI,IAAI,SAAS,UAAW;AAC5B,YAAM,QAAQ,MAAM,SAAS,IAAI,IAAI;AACrC,YAAM,SAAS,IAAI,OAAO,QAAQ,KAAK,IAAK,OAAO,KAAK,IAAK,MAAM,KAAK;AACxE,aAAO,KAAK,EAAE,MAAM,IAAI,MAAM,MAAM,IAAI,KAAK,CAAC;AAAA,IAChD;AACA,aAAS,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS;AACnD,YAAM,MAAM,QAAQ,KAAK;AACzB,cAAQ,KAAK,EAAE,MAAM,MAAM,IAAI,MAAM,MAAM,IAAI,MAAM,QAAQ,OAAO,KAAK,GAAI,OAAO,MAAM,KAAK,EAAG,CAAC;AAAA,IACrG;AAAA,EACF;AACA,SAAO;AACT;AAcO,MAAM,WAAW,CACtB,SACA,aAEA,QAAQ,IAAI,CAAC,UAAU;AACrB,QAAM,SAAS,SAAS,IAAI,MAAM,IAAI;AACtC,QAAM,SAAS,WAAW,SAAY,SAAY,QAAQ,UAAU,QAAQ,MAAM,IAAI;AACtF,SAAO,WAAW,SAAY,QAAQ,EAAE,GAAG,OAAO,OAAO;AAC3D,CAAC;",
+  "names": []
+}

package/dist/cjs/internal/Html.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Small, dependency-free HTML renderers for web retrieval.
+ *
+ * @since 1.0.0
+ */
+/**
+ * Extracts readable text while dropping executable and presentation-only elements.
+ *
+ * @category rendering
+ * @since 1.0.0
+ */
+export declare const toText: (html: string) => string;
+/**
+ * Converts a conservative subset of HTML into readable Markdown.
+ *
+ * @category rendering
+ * @since 1.0.0
+ */
+export declare const toMarkdown: (html: string) => string;
+//# sourceMappingURL=Html.d.ts.map