@repo-os/repoos 0.5.45

package/dist/server/integration-orchestrator.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Orchestrates individual close-out jobs through their lifecycle. Each job:
+ *   1. Validates the candidate away from live main (temporary worktree/branch)
+ *   2. Checks for main SHA drift and rebuilds if needed
+ *   3. Publishes only a green candidate while holding the repo lock
+ *   4. Cleans up the candidate and task resources
+ *
+ * Phases track recovery: if interrupted mid-flight, retry resumes from the current phase.
+ */
+import type { RepoOSConfig, Task } from "../core/types.js";
+import type { JobCoordinator } from "./integration-job.js";
+import type { RepositoryLock, RootLock } from "./repo-lock.js";
+import type { Logger } from "../core/logger.js";
+import type { DoneStep } from "./done.js";
+import type { RemoteValidator } from "./remote-validation.js";
+import type { TaskCheckManager, TaskCheckListener } from "./task-check.js";
+/**
+ * The merge that just ran left the candidate at exactly base main — it added
+ * nothing. That is legitimate when the feature branch was already fully
+ * integrated (a re-run of a close-out, a branch cherry-picked onto main
+ * earlier): the close-out is idempotent and the task genuinely has nothing
+ * left to land.
+ *
+ * It is a BUG when the branch still carries commits main lacks and the merge —
+ * or, far more often, the conflict auto-resolution in `mergeBranch` — silently
+ * dropped them. Left unguarded, the gate then runs `build` + `check` against
+ * what is effectively bare main (which trivially passes) and the task publishes
+ * as `done` with none of its code integrated. This bit #0306/#0307/#0309/#0312.
+ *
+ * Returns an actionable failure reason in the bug case, `null` when the no-op
+ * is legitimate (or when git errored and a downstream step should surface it).
+ */
+export declare function detectDroppedMerge(root: string, mainBranch: string, featureBranch: string, postMergeHead: string, baseMainSha: string): Promise<string | null>;
+/**
+ * Make main's `<workDir>/*.md` state authoritative for every task file the
+ * merged candidate changed that is NOT the closing task's own file, and commit
+ * the restore.
+ *
+ * A feature branch can carry stale edits to other tasks' files — a concurrent
+ * board write, a `repoos` CLI call in the worktree, a partial merge — that git
+ * folds in without a conflict (main untouched since the merge-base), so the
+ * close-out's conflict-only `autoResolveOurs` never catches them and the stale
+ * version publishes to main. This closes that gap: a foreign file modified or
+ * deleted by the branch is restored to main's copy; one the branch newly added
+ * is removed (a close-out never creates another task's file). Returns the paths
+ * touched (empty when there were none); throws only if the git ops fail.
+ *
+ * Exported for tests.
+ */
+export declare function resetForeignWorkFiles(opts: {
+    candidateWtPath: string;
+    baseMainSha: string;
+    workDir: string;
+    ownWorkFile: string | null;
+}): Promise<string[]>;
+/**
+ * Whether a candidate's merged diff is documentation-only, so the expensive
+ * build + check gate in `validateCandidate` can be skipped (#0355).
+ *
+ * Deliberately literal and mechanical: a path qualifies only if it lives under
+ * `docs/` or `user-docs/`, or ends in `.md`. The closing task's own
+ * `work/<id>-*.md` file is the common `.md` case — it always changes, and
+ * `resetForeignWorkFiles` has already restored every OTHER task's work file to
+ * main's copy before this runs, so no foreign task file reaches this check.
+ * Anything else — `repoos.toml`, `package.json`, `src/`, `scripts/`,
+ * `.github/`, … — disqualifies the fast path. No scoring, no "mostly docs".
+ *
+ * An empty path list is vacuously docs-only: a legitimate no-op merge (the
+ * branch was already fully integrated) leaves nothing for build/test to
+ * examine, and the dropped-merge guard in `validateCandidate` runs earlier and
+ * already rejects an empty merge that actually swallowed real branch work.
+ */
+export declare function isDocsOnlyChange(paths: string[]): boolean;
+/**
+ * The useful part of a failed command's combined output. bun/npm wrap a child
+ * failure with a generic trailing line (`error: script "repoos" exited with
+ * code 1`) that is useless as a reason on its own, so keep the last several
+ * meaningful lines — the real cause (a failing test, a compiler error) sits
+ * just above the wrapper.
+ *
+ * The reason is persisted to `.repoos/integration-jobs/<id>.json` and shown
+ * verbatim in the UI, so it must be free of ANSI escapes (the gate's test
+ * output is colored) and of anything that looks like a credential. When the
+ * excerpt exceeds the character cap it is cut from the front at a WORD
+ * boundary — cutting mid-word produced reasons like `check failed: …eletion
+ * detected by…` (0215) that read as garbage.
+ */
+export declare function tailLine(stdout: string, stderr: string): string;
+/** Candidate validation and publication orchestrator for one job. */
+export declare class CloseOutOrchestrator {
+    private config;
+    private coordinator;
+    private repoLock?;
+    private rootLock?;
+    private getTask?;
+    private onProgress?;
+    private logger?;
+    /**
+     * Fired when `validating` fails on a REAL, named merge conflict (never
+     * for the task's own bookkeeping file or generated paths, which
+     * auto-resolve; never for infra failures). The job itself is still
+     * marked `failed` as before — this is a separate, best-effort trigger
+     * to auto-resume the engineer to fix it and resubmit (#0271 follow-up).
+     */
+    private onMergeConflict?;
+    /**
+     * Runs the expensive half of the gate (build + test) on a cloud VM when
+     * `config.remoteValidation.enabled` — see validateCandidate. Undefined
+     * disables remote validation regardless of config.
+     */
+    private remoteValidator?;
+    /** Records the MTD merge-gate `repoos check` run for the Debug tab (0310). */
+    private taskChecks?;
+    private onTaskCheckEvent?;
+    constructor(config: RepoOSConfig, coordinator: JobCoordinator, repoLock?: RepositoryLock | undefined, rootLock?: RootLock | undefined, getTask?: ((taskId: string) => Task | null) | undefined, onProgress?: ((step: DoneStep) => void) | undefined, logger?: Logger | undefined, 
+    /**
+     * Fired when `validating` fails on a REAL, named merge conflict (never
+     * for the task's own bookkeeping file or generated paths, which
+     * auto-resolve; never for infra failures). The job itself is still
+     * marked `failed` as before — this is a separate, best-effort trigger
+     * to auto-resume the engineer to fix it and resubmit (#0271 follow-up).
+     */
+    onMergeConflict?: ((taskId: string, reason: string) => void) | undefined, 
+    /**
+     * Runs the expensive half of the gate (build + test) on a cloud VM when
+     * `config.remoteValidation.enabled` — see validateCandidate. Undefined
+     * disables remote validation regardless of config.
+     */
+    remoteValidator?: RemoteValidator | undefined, 
+    /** Records the MTD merge-gate `repoos check` run for the Debug tab (0310). */
+    taskChecks?: TaskCheckManager | undefined, onTaskCheckEvent?: TaskCheckListener | undefined);
+    /**
+     * Whether the task is, on disk, already `done`. The live index is an
+     * in-memory cache that can lag the actual file (a duplicate/stale close-out
+     * — #0289 — can run right after the first successful publish, before the
+     * index rebuilds), so this reads the authoritative task file directly,
+     * falling back to the index only when the file cannot be located or parsed.
+     */
+    private taskIsDone;
+    /**
+     * Record a close-out job failure, OR reconcile it away when it is moot.
+     *
+     * A failure is moot when the task is already `done`: the failing job is a
+     * duplicate/stale enqueue against a task that already finished successfully
+     * through an earlier job (#0289). That earlier close-out's cleanup deleted
+     * the worktree/branch, which is exactly why a later redundant enqueue fails
+     * (e.g. "worktree not found"). There is no gate failure here needing a
+     * human's attention, and the failed job record would otherwise sit forever
+     * with no path to resolution, so it is dropped instead.
+     *
+     * Returns the `{ ok, reason }` the caller should return: `ok: true` for a
+     * reconciled (moot) failure so the pipeline treats it as a normal completion
+     * and never surfaces it as an actionable error; `ok: false` for a genuine
+     * failure, which is recorded as `failed` (and `onRecorded`, e.g. the merge-
+     * conflict retry, runs) so the UI and status bar can surface it.
+     */
+    /**
+     * Tear down the `repoos/integrate/<id>` candidate worktree + branch. Safe to
+     * call whether or not the candidate exists. The candidate is a throwaway
+     * scratch area rebuilt from scratch on the next run, so its branch is
+     * force-deleted (git will not see it as merged after a failed job).
+     *
+     * Runs on EVERY terminal job outcome — success (`cleanup`), genuine failure,
+     * and moot/reconciled — so a candidate never outlives its job. Without this,
+     * every failed close-out leaked a worktree that inflated cold-boot `git
+     * status` fan-out until someone ran gc.
+     */
+    private removeCandidate;
+    private failOrReconcile;
+    /**
+     * Process the next job in the queue: validate and publish it.
+     * Phases are atomic; a retry at any phase resumes from that phase.
+     * May return early if the job transitions back to an earlier phase (e.g., on main drift).
+     */
+    processNext(): Promise<{
+        ok: boolean;
+        reason?: string;
+        requiresRetry?: boolean;
+    }>;
+    private processJob;
+    /**
+     * Cheap, non-destructive pre-flight (#0358): would merging the task's feature
+     * branch into current main hit a REAL (non-auto-resolvable) conflict?
+     *
+     * Runs BEFORE any candidate worktree exists, in the feature branch's own
+     * worktree (`worktreePathForBranch`, already checked out and cheap to use)
+     * against the CURRENT main SHA, reusing `mergeBranch`'s dry-run mode so the
+     * classification is literally the real merge's — never a second, drifting
+     * definition of "a real conflict". Returns the conflict reason in the exact
+     * format `validateCandidate` uses, or `null` when there is no real conflict.
+     *
+     * Fail-open by construction: a missing feature worktree, any git error, or a
+     * dry-run that cannot run cleanly all return `null`, so the caller falls
+     * through to the existing sync/validate flow rather than blocking on a broken
+     * optimization.
+     */
+    private preflightConflict;
+    private syncCandidate;
+    /**
+     * Merge the feature branch into the candidate, then run the gate on it.
+     *
+     * `retryable: false` marks a failure that cannot possibly resolve on a second
+     * identical run — a merge conflict is the same conflict every time — so the
+     * caller can skip its retry instead of spending another few minutes proving
+     * the point. Everything else defaults to retryable: build and check failures
+     * are where genuine flakiness lives.
+     */
+    private validateCandidate;
+    private publishCandidate;
+    private cleanup;
+}