toolroll 0.9.75 → 0.9.77

package/dist/teardown-git.d.ts

@@ -6,14 +6,24 @@ export declare const TEARDOWN_FLAGS: readonly string[];
 /** Exit code of a refused command (git's own fatal code, so no caller reads it as "not found" or "no"). */
 export declare const REFUSED_CODE = 128;
 /** The command-running setting a `git config --list --show-scope -z` listing sets, or null. Only local and worktree
- * scope count: teardown commands never read system or global config. */
-export declare function commandSetting(listing: string): string | null;
+ * scope count: teardown commands never read system or global config. `lfsChecked`: the caller refuses a checkout whose
+ * `.lfsconfig` names a git-lfs extension (lfsExtensionIn), so git-lfs's own exact filters may stand (runsCommand).
+ * Fails closed: a listing that can't be classified names a setting. */
+export declare function commandSetting(listing: string, options?: {
+    lfsChecked?: boolean;
+}): string | null;
 /** The `-c` settings that carry the operator's own values (CARRIED_VALUES, LFS_FILTER) from a global/system listing. */
 export declare function carriedSettings(listing: string): string[];
 /** Why a teardown command was refused, or null when `result` isn't a refusal. */
 export declare function refusal(result: ExecResult): string | null;
-/** The one way teardown runs git, including the target checkout immediately before removal. */
-export declare function teardownGit(runner?: Runner): Git;
+/** The one way teardown runs git, including the target checkout immediately before removal. Every command runs
+ * against a write view of its repository (gitView), whose config is the one inspected and whose info is a copy, so a
+ * setting or attributes file an agent adds after the inspection is never read (a build's process can outlive its turn:
+ * on macOS containment is observational, src/containment.ts, and a sibling build shares the repository). A removal's
+ * target is bound to the same repository as the folder it is removed from. A removal without --force runs under the
+ * target's own view (its own config.worktree folded in), so git's last check of whether it is clean reads it as the
+ * target itself would. `binding.repo`: the project's main checkout, from the plane's records, when the caller has it. */
+export declare function teardownGit(runner?: Runner, binding?: GitBinding): Git;
 /**
  * Git on a build's checkout, as the plane runs it outside every fence (staging, committing and inspecting the build's
  * work): the same fixed hardening as teardown (no hooks, fsmonitor, ext transport, credential helpers or automatic
@@ -28,15 +38,25 @@ export declare function teardownGit(runner?: Runner): Git;
  * git at any file, a pipe that never ends among them. Each file is read only as the regular file it is, bounded; one
  * that can't be read so counts as including.
  */
-export declare function checkoutIncludes(checkout: string): boolean;
+export declare function checkoutIncludes(checkout: string, gitFile?: string): boolean;
+export type GitBinding = {
+    repo?: string | null;
+};
+/** Settings fixed on every write through a view: `worktree add` records absolute paths (relative ones would need a
+ * config write, which a view keeps); no transport at all (a caller that fetches allows its one protocol by name, as the
+ * nightly check's local fetch does with protocol.file.allow); and no split index (its shared index files would be
+ * written in the plane's GIT_DIR). */
+export declare const WRITE_VIEW_FLAGS: readonly string[];
 /** Whether the checkout's .lfsconfig (read as git parses it, that file only) sets any git-lfs key that could name a
  * program (anything but INERT_LFS). A file that
  * isn't a plain one, or doesn't parse, counts as naming one. */
-export declare function lfsExtensionIn(checkout: string): boolean;
-/** `mode` "read" is for reading a checkout an agent may still be writing (the code page): every command also takes
- * readFlags() and runs against the checkout's readView, so neither its config nor its info/attributes can change
- * between the inspection and the run. */
-export declare function checkoutGit(inner?: Runner, mode?: "build" | "read"): Runner;
+export declare function lfsExtensionIn(checkout: string, gitFile?: string): boolean;
+/** Every command runs against a view of the checkout's repository (gitView) whose config and info are copies the
+ * plane made, inspected there, so neither can change between the inspection and the run. `mode` "read" is for reading
+ * a checkout an agent may still be writing (the code page): every command also takes readFlags(), and the view holds
+ * no info/attributes. "build" is the plane's staging and committing of a build's work, which writes the repository
+ * through the view (gitView). */
+export declare function checkoutGit(inner?: Runner, mode?: "build" | "read", binding?: GitBinding): Runner;
 /**
  * Flags for reading a checkout an agent writes while a page waits (docs/plans/get-side-effects.md). Command-line
  * settings win over anything the checkout's config says, even one changed after it was inspected: no fsmonitor, hooks,
@@ -47,16 +67,73 @@ export declare const PAGE_READ_FLAGS: readonly string[];
 /** The read flags, for every read of an agent-written checkout, whatever the HTTP method (security review of
  * 01bf3114): the worktree's attributes come from the empty tree. Git still reads the repository's info/attributes and
  * its config as it starts, so the flags alone don't stop a filter planted in both after the inspection: every read
- * also runs against the checkout's readView (checkoutGitSync, checkoutGit "read"), whose config and info are the plane's. The cost is cosmetic: a checkout's line-ending or encoding rules are not applied, so
+ * also runs against a view of the checkout's repository (gitView; checkoutGitSync, checkoutGit "read"), whose config and info are the plane's. The cost is cosmetic: a checkout's line-ending or encoding rules are not applied, so
  * a file they would normalize can read as changed (fail closed: shipping then asks for a clean commit). */
-export declare function readFlags(): readonly string[];
+export declare function readFlags(gitFile?: string): readonly string[];
 /**
  * checkoutGit, synchronously, for reads a page shows from a checkout an agent writes (docs/plans/get-side-effects.md):
  * the same refusals (an include, an .lfsconfig extension, a config key that can run a command), no system or global
- * config, the operator's own values carried, PAGE_READ_FLAGS and the checkout's readView (which hold even if its config
+ * config, the operator's own values carried, PAGE_READ_FLAGS and a view of the checkout's repository (gitView: they hold even if its config
  * or info/attributes change after they were read), submodules skipped, bounded. A refusal throws.
  */
 export declare function checkoutGitSync(cwd: string, args: readonly string[], options?: {
     timeoutMs?: number;
     maxBuffer?: number;
+    binding?: GitBinding;
 }): string;
+/**
+ * checkoutGitSync's run, answering git's exit status instead of throwing on a non-zero one (a refusal, or a repository
+ * that changed while git ran, still throws): for reads whose "no" is an exit code (`merge-base --is-ancestor`), and,
+ * with `buffer`, for blobs read as bytes (their output is never rewritten).
+ */
+export declare function viewedGitSync(cwd: string, args: readonly string[], options: {
+    timeoutMs?: number;
+    maxBuffer?: number;
+    binding?: GitBinding;
+}): {
+    status: number | null;
+    stdout: string;
+};
+export declare function viewedGitSync(cwd: string, args: readonly string[], options: {
+    timeoutMs?: number;
+    maxBuffer?: number;
+    binding?: GitBinding;
+    buffer: true;
+    input?: Buffer;
+    git?: string;
+}): {
+    status: number | null;
+    stdout: Buffer;
+};
+/**
+ * checkoutGit ("build": the repository written through its view) for callers that name the repository with a leading
+ * `git -C <dir>` instead of a cwd: worktree add and remove in a project's repository, a merge in a checkout of it.
+ * The project's repository is shared with every build, which can write its config, info and hooks; nothing here runs
+ * what they name. Anything but git goes to `inner` as given.
+ */
+export declare function hardenedGit(inner?: Runner, mode?: "build" | "read", binding?: GitBinding): Runner;
+/** Asked once per git executable (eval-harness review 2, follow-up): a fixed git given to viewedGitSync is probed
+ * itself, never answered for by the one PATH names. */
+export declare function lazyFetchSupported(gitFile?: string): boolean;
+/** For tests: forget the probes' answers, or set one for every executable (null forgets). */
+export declare function setLazyFetchSupportedForTest(value: boolean | null): void;
+/** The words for a partial clone refused on a git without `--no-lazy-fetch`. */
+export declare const PARTIAL_CLONE_REFUSAL = "this project is a partial clone; protected reads need git 2.45 or newer";
+/** `--no-lazy-fetch` where the installed git has it, else nothing (and lazyFetchSetting refuses partial clones). */
+export declare function noLazyFetch(): readonly string[];
+/**
+ * The repository setting (local or worktree scope of a `git config --list --show-scope -z` listing) that makes lazy
+ * fetching possible, or null: `extensions.partialClone` set at all, any `remote.<name>.promisor` not plainly false, or
+ * any `remote.<name>.partialCloneFilter` set (git makes that remote a promisor). Fails closed: a listing that can't be
+ * read names a setting. `remote.<name>.vcs` (a foreign-VCS helper) is named too, though the classifier already refuses
+ * it (commandSetting: not in the remote allowlist), as it does every `protocol.*` key and every include.
+ */
+export declare function lazyFetchSetting(listing: string): string | null;
+/**
+ * For the reads that run git directly on a repository rather than through a view: with `--no-lazy-fetch` they run as
+ * they always have (the flag stops any fetch). Without it, they must not check a repository's config and then run git
+ * on it (the config could change in between, or an include could set what the check never saw): `inner`, wrapped so
+ * every git command runs through a frozen read view (checkoutGit "read"), whose own config listing (includes refused,
+ * command and protocol settings refused, a partial clone refused) is the config git then runs with.
+ */
+export declare function lazyFetchSafeGit(inner?: Runner): Runner;