toolroll 0.9.60 → 0.9.62

package/dist/landed-cleanup.d.ts

@@ -0,0 +1,170 @@
+import { type ExecResult } from "./exec.js";
+import type { RemoteMainRead, RemoteMains } from "./remote-main.js";
+import type { Store } from "./store.js";
+import { type Runner, type WorktreePool } from "./worktree.js";
+/** `storage clean --landed` takes only what has waited at least this long. */
+export declare const BACKLOG_DAYS = 7;
+/** The local branches the one-time pass looks at: Toolroll's build and plan branches, under either name. */
+export declare const BACKLOG_PREFIXES: readonly string[];
+/** The ledger action that closes a teardown. */
+export declare const LANDED_CLEANED_ACTION = "landed work cleaned up";
+/** Reconcile looks at most this many results and finishes at most this many items a pass; the pass by hand has no cap. */
+export declare const AUTO_LOOKS = 20;
+export declare const AUTO_ITEMS = 40;
+export type Git = (cwd: string, args: readonly string[]) => Promise<ExecResult>;
+export declare function gitOf(runner?: Runner): Git;
+export type LandedHow = "merged" | "in-main" | "content-in-main";
+/** `trusted`: it may complete a task automatically (a recorded merge, or the recorded remote's main). */
+export type LandedProof = {
+    landed: true;
+    how: LandedHow;
+    reason: string;
+    trusted: boolean;
+} | {
+    landed: false;
+    why: string;
+};
+/** What Toolroll last saw of the result's pull request. */
+export type PullRequestFact = {
+    merged: boolean;
+    headSha: string | null;
+    number: number | null;
+};
+/**
+ * Whether this commit's work landed, read from what Toolroll recorded and the local repository. Fails closed: every
+ * doubt is "not proven", with the reason in a few words. Only a recorded merge is trusted to complete a task: a build
+ * can write the local main.
+ */
+export declare function landedProof(git: Git, repo: string, head: string | null, pullRequest?: PullRequestFact | null): Promise<LandedProof>;
+/**
+ * The proof automatic completion trusts: a recorded merge of this exact commit, or its work in the main of the
+ * project's recorded remote, compared only in the private directory that main was fetched into. `remote` is read only
+ * when no recorded merge settles it.
+ */
+export declare function remoteLandedProof(remote: () => Promise<RemoteMainRead>, repo: string, head: string | null, pullRequest?: PullRequestFact | null): Promise<LandedProof>;
+export type LandedTarget = {
+    kind: "checkout" | "branch";
+    target: string;
+    expect: string;
+};
+export type LandedKeep = {
+    repo: string;
+    what: string;
+    why: string;
+};
+export type LandedCandidate = {
+    repo: string;
+    taskId: string;
+    rootId: string;
+    runId: number;
+    receipt: string;
+    head: string;
+    finishedAt: string;
+    /** False when it is already complete: only its teardown is left. */
+    completes: boolean;
+    how: LandedHow;
+    reason: string;
+    /** Proven by a recorded merge or the recorded remote's main: only then may it complete. */
+    trusted: boolean;
+    targets: LandedTarget[];
+    keeps: LandedKeep[];
+};
+/**
+ * Results in a project whose work landed, with what their teardown would remove and what stays. Reads only.
+ * `limit` caps how many results are read against git (reconcile's bound; results read before and unchanged since
+ * don't count); `before` takes only results finished before it (the one-time pass's seven days).
+ */
+export declare function landedResults(store: Store, git: Git, remotes: RemoteMains, repo: string, root: string, now: Date, options?: {
+    limit?: number;
+    before?: string;
+    memo?: boolean;
+}): Promise<{
+    found: LandedCandidate[];
+    kept: LandedKeep[];
+}>;
+/**
+ * Mark a landed result complete (unless it already is) and record its teardown, in one transaction, bound to the
+ * exact result read: refused when the result changed since. The completion's ledger entry says why. Returns the
+ * teardown's id; a result already taken returns its existing teardown.
+ */
+export declare function recordLandedIntent(store: Store, candidate: LandedCandidate, now: Date, root: string, actor?: string): {
+    ok: true;
+    id: number;
+    completed: boolean;
+} | {
+    ok: false;
+    why: string;
+};
+/** A landed branch no task names: its teardown, on its own. */
+export type LandedBranch = {
+    repo: string;
+    branch: string;
+    oid: string;
+    how: LandedHow;
+    reason: string;
+    checkout: string | null;
+};
+export declare function recordBranchIntent(store: Store, branch: LandedBranch, now: Date, actor: string): number;
+export type LandedStep = {
+    kind: "checkout" | "branch";
+    repo: string;
+    target: string;
+    taskId: string | null;
+    outcome: "removed" | "already gone" | "waits" | "kept";
+    why: string | null;
+};
+/**
+ * Finish what teardowns intended: pending items, oldest first (checkouts before branches). Each is checked again
+ * right before it goes, and recorded right after. Doubt leaves it pending for the next pass; a branch that moved, or
+ * a result that has newer work, is kept for good. `limit` caps the items settled (removed, already gone or kept), so
+ * items left waiting never crowd out later ones. `only` limits it to these teardowns.
+ */
+export declare function finishLanded(store: Store, pool: WorktreePool, git: Git, remotes: RemoteMains, now: () => Date, options?: {
+    repo?: string;
+    limit?: number;
+    only?: ReadonlySet<number>;
+}): Promise<LandedStep[]>;
+/**
+ * Reconcile's part: finish teardowns a crash cut short, then find newly landed results (a bounded few), mark them
+ * complete and tear them down.
+ */
+export declare function reconcileLanded(store: Store, pool: WorktreePool, git: Git, remotes: RemoteMains, repo: string, root: string, now: () => Date): Promise<{
+    completed: string[];
+    steps: LandedStep[];
+}>;
+export type LandedSummary = {
+    completed: number;
+    checkouts: number;
+    branches: number;
+    /** What a teardown still waits on, and why. */
+    waiting: {
+        target: string;
+        why: string | null;
+    }[];
+};
+/** What landed-work teardowns did so far, and what they still wait on (Settings → Storage). Reads only. */
+export declare function landedSummary(store: Store): LandedSummary;
+export type LandedPlan = {
+    at: string;
+    cutoff: string;
+    results: LandedCandidate[];
+    branches: LandedBranch[];
+    kept: LandedKeep[];
+    /** Items an earlier teardown still has to finish. */
+    pending: number;
+};
+/**
+ * What `storage clean --landed` would do now, across every project: landed results finished at least a week ago,
+ * and branches Toolroll created (toolroll/, toolroll-plan/, standing-orders/) at least a week ago that no task uses
+ * and that landed in main. Reads only.
+ */
+export declare function landedBacklog(store: Store, git: Git, remotes: RemoteMains, root: string, now: Date, options?: {
+    repos?: readonly string[];
+}): Promise<LandedPlan>;
+/** Act on a preview: record every teardown first, then carry them out. Refuses nothing it previewed silently: what
+ * changed since is reported as kept. */
+export declare function cleanLandedBacklog(store: Store, pool: WorktreePool, git: Git, remotes: RemoteMains, root: string, now: () => Date, plan: LandedPlan, actor: string): Promise<{
+    completed: string[];
+    steps: LandedStep[];
+    refused: LandedKeep[];
+}>;