@blogic-cz/agent-tools 1.2.1 → 1.3.0

package/src/gh-tool/pr/stack-read.ts

@@ -0,0 +1,73 @@
+import { Effect } from "effect";
+
+import { GitHubService } from "#gh/service";
+
+import type { StackMember, StackView } from "#gh/types";
+
+type StacksListResponse = Array<{ number: number }>;
+
+type StackResponse = {
+  number: number;
+  base: { ref: string };
+  open: boolean;
+  pull_requests: Array<{
+    number: number;
+    title: string;
+    state: "open" | "closed";
+    merged_at: string | null;
+    draft: boolean;
+    html_url: string;
+    head: { ref: string };
+    base: { ref: string };
+  }>;
+};
+
+export const readStack = Effect.fn("pr.readStack")(function* (opts: { pr: number }) {
+  const gh = yield* GitHubService;
+  const repo = yield* gh.getRepoInfo();
+  const base = `repos/${repo.owner}/${repo.name}`;
+
+  const unstacked: StackView = {
+    pr: opts.pr,
+    isStacked: false,
+    stackNumber: null,
+    baseRef: null,
+    members: [],
+  };
+
+  // A 404 is the repository having no stacks surface at all, which reads the same as a PR
+  // that belongs to no stack. Every caller gets that reading from here, not its own.
+  const stacks = yield* gh
+    .apiRequest<StacksListResponse>({ path: `${base}/stacks?pull_request=${opts.pr}` })
+    .pipe(Effect.catchTag("GitHubNotFoundError", () => Effect.succeed(null)));
+
+  if (stacks === null) {
+    return unstacked;
+  }
+
+  const stackNumber = stacks.body?.[0]?.number;
+  if (stackNumber === undefined) {
+    return unstacked;
+  }
+
+  const stack = yield* gh.apiRequest<StackResponse>({ path: `${base}/stacks/${stackNumber}` });
+
+  const members: StackMember[] = stack.body.pull_requests.map((member, index) => ({
+    position: index + 1,
+    number: member.number,
+    title: member.title,
+    headRefName: member.head.ref,
+    baseRefName: member.base.ref,
+    state: member.merged_at === null ? member.state : "merged",
+    isDraft: member.draft,
+    url: member.html_url,
+  }));
+
+  return {
+    pr: opts.pr,
+    isStacked: true,
+    stackNumber: stack.body.number,
+    baseRef: stack.body.base.ref,
+    members,
+  } satisfies StackView;
+});

package/src/gh-tool/pr/stack.ts

@@ -0,0 +1,239 @@
+import { Effect } from "effect";
+
+import { pollUntilResolved } from "#shared/poll-until-resolved";
+import { GitHubService } from "#gh/service";
+import { GitHubMergeError } from "#gh/errors";
+
+import type { MergeStrategy, StackMember, StackMergeBlocker, StackMergeResult } from "#gh/types";
+
+import { fetchCheckResults, fetchPRView } from "./core";
+import { readStack } from "./stack-read";
+
+export { readStack };
+
+type AsyncMergeDetails = {
+  message?: string;
+  uuid?: string;
+  sha?: string;
+  merge_method?: MergeStrategy;
+};
+
+type AsyncMergeResult = {
+  status: "pending" | "merged" | "enqueued" | "failed";
+  details?: AsyncMergeDetails;
+};
+
+// One request merges every open member, so the server-side work scales with the stack;
+// the single-PR budget in core.ts is deliberately shorter.
+const POLL_INTERVAL_MS = 2000;
+const MAX_WAIT_SECONDS = 300;
+
+const stackMergeFailure = (opts: {
+  stackNumber: number;
+  pr: number;
+  message: string;
+  hint: string;
+  reason?: GitHubMergeError["reason"];
+}) =>
+  new GitHubMergeError({
+    message: `Failed to merge stack #${opts.stackNumber}: ${opts.message}`,
+    reason: opts.reason ?? "unknown",
+    hint: opts.hint,
+    nextCommand: `agent-tools-gh pr stack view --pr ${opts.pr}`,
+  });
+
+const collectBlockers = Effect.fn("pr.collectStackBlockers")(function* (members: StackMember[]) {
+  const blockers: StackMergeBlocker[] = [];
+
+  for (const member of members) {
+    if (member.isDraft) {
+      blockers.push({ number: member.number, reason: "draft", detail: "PR is a draft" });
+      continue;
+    }
+
+    const info = yield* fetchPRView(member.number);
+    if (info.mergeable === "CONFLICTING") {
+      blockers.push({
+        number: member.number,
+        reason: "not_mergeable",
+        detail: "PR has merge conflicts",
+      });
+      continue;
+    }
+
+    if (info.mergeable !== "MERGEABLE") {
+      blockers.push({
+        number: member.number,
+        reason: "mergeability_unknown",
+        detail: `GitHub has not settled mergeability yet (${info.mergeable})`,
+      });
+      continue;
+    }
+
+    const checks = yield* fetchCheckResults(member.number);
+    const failing = checks.filter((check) => check.bucket === "fail");
+    if (failing.length > 0) {
+      blockers.push({
+        number: member.number,
+        reason: "checks_failing",
+        detail: `${failing.length} failing check(s): ${failing.map((c) => c.name).join(", ")}`,
+      });
+      continue;
+    }
+
+    const pending = checks.filter((check) => check.bucket === "pending");
+    if (pending.length > 0) {
+      blockers.push({
+        number: member.number,
+        reason: "checks_pending",
+        detail: `${pending.length} check(s) still running`,
+      });
+    }
+  }
+
+  return blockers;
+});
+
+export const mergeStack = Effect.fn("pr.mergeStack")(function* (opts: {
+  pr: number;
+  strategy: MergeStrategy;
+  confirm: boolean;
+}) {
+  const gh = yield* GitHubService;
+  const repo = yield* gh.getRepoInfo();
+  const view = yield* readStack({ pr: opts.pr });
+
+  if (!view.isStacked || view.stackNumber === null || view.baseRef === null) {
+    return yield* new GitHubMergeError({
+      message: `PR #${opts.pr} is not part of a GitHub stack`,
+      reason: "unknown",
+      hint: "Use 'pr merge' for an unstacked PR. A chain of PRs based on each other is only a stack when GitHub has registered it as one.",
+      nextCommand: `agent-tools-gh pr merge --pr ${opts.pr}`,
+    });
+  }
+
+  const unmerged = view.members.filter((member) => member.state === "open");
+  if (unmerged.length === 0) {
+    return yield* new GitHubMergeError({
+      message: `Stack #${view.stackNumber} has no open pull requests left`,
+      reason: "unknown",
+      hint: "Every member is already merged or closed.",
+    });
+  }
+
+  // merge-async merges every unmerged PR up to and including the requested one, so the
+  // top open member is the request that lands the whole stack.
+  const target = unmerged[unmerged.length - 1] as StackMember;
+
+  const blockers = yield* collectBlockers(unmerged);
+
+  const plan = unmerged.map((member) => ({
+    position: member.position,
+    number: member.number,
+    headRefName: member.headRefName,
+  }));
+
+  const base = {
+    stackNumber: view.stackNumber,
+    baseRef: view.baseRef,
+    target: target.number,
+    plan,
+    blockers,
+  };
+
+  if (!opts.confirm) {
+    return {
+      ...base,
+      strategy: opts.strategy,
+      merged: false,
+      dryRun: true,
+      sha: null,
+      adoptedExistingRequest: false,
+    } satisfies StackMergeResult;
+  }
+
+  if (blockers.length > 0) {
+    return yield* new GitHubMergeError({
+      message:
+        `Stack #${view.stackNumber} is not ready: ` +
+        blockers.map((b) => `#${b.number} ${b.detail}`).join("; "),
+      reason: "unknown",
+      hint: "A partial stack merge leaves a parent on the trunk and a broken child, so nothing was attempted.",
+    });
+  }
+
+  const asyncPath = `repos/${repo.owner}/${repo.name}/pulls/${target.number}/merge-async`;
+
+  const requested = yield* gh.apiRequest<AsyncMergeResult>({
+    path: asyncPath,
+    method: "PUT",
+    body: { merge_method: opts.strategy, merge_action: "direct_merge" },
+    alsoAcceptStatus: [202, 409],
+  });
+
+  // A 409 hands back an existing request whose options may differ from the ones asked
+  // for, so the result reports the strategy GitHub is actually applying.
+  const adoptedExistingRequest = requested.status === 409;
+  let latest = requested.body;
+  const effectiveStrategy = latest.details?.merge_method ?? opts.strategy;
+
+  const uuid = latest.details?.uuid;
+  if (latest.status === "pending" && (uuid === undefined || uuid.length === 0)) {
+    return yield* stackMergeFailure({
+      stackNumber: view.stackNumber,
+      pr: target.number,
+      message: "GitHub reported a pending merge without a request id",
+      hint: "The merge may or may not be running. Re-read the stack before retrying so the merge is not requested twice.",
+    });
+  }
+
+  if (uuid !== undefined) {
+    latest = yield* pollUntilResolved({
+      initial: latest,
+      isPending: (value) => value.status === "pending",
+      fetchLatest: () =>
+        gh
+          .apiRequest<AsyncMergeResult>({ path: `${asyncPath}/${uuid}` })
+          .pipe(Effect.map((response) => response.body)),
+      intervalMs: POLL_INTERVAL_MS,
+      budgetSeconds: MAX_WAIT_SECONDS,
+    });
+  }
+
+  if (latest.status === "merged") {
+    return {
+      ...base,
+      strategy: effectiveStrategy,
+      merged: true,
+      dryRun: false,
+      sha: latest.details?.sha ?? null,
+      adoptedExistingRequest,
+    } satisfies StackMergeResult;
+  }
+
+  if (latest.status === "enqueued") {
+    return yield* stackMergeFailure({
+      stackNumber: view.stackNumber,
+      pr: target.number,
+      reason: "merge_queue",
+      message: latest.details?.message ?? "the stack entered a merge queue",
+      hint: "The merge queue owns the merge from here; it is not merged yet. Watch the PRs until the queue drains.",
+    });
+  }
+
+  if (latest.status === "pending") {
+    return yield* stackMergeFailure({
+      stackNumber: view.stackNumber,
+      pr: target.number,
+      message: `still pending after ${MAX_WAIT_SECONDS}s`,
+      hint: "The asynchronous merge is still running. Re-check the stack before retrying so the merge is not requested twice.",
+    });
+  }
+
+  return yield* stackMergeFailure({
+    stackNumber: view.stackNumber,
+    pr: target.number,
+    message: latest.details?.message ?? "the merge request failed",
+    hint: "Inspect the stack state and branch protections, then retry.",
+  });
+});

package/src/gh-tool/service.ts

@@ -1,11 +1,14 @@
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { Context, Duration, Effect, Layer, Stream } from "effect";
+import { Context, Effect, Layer, Stream } from "effect";
 
 import type { GitHubRepoConfig } from "#config";
 import type { RepoInfo } from "./types";
 
 import { GH_BINARY } from "./config";
 import { GitHubAuthError, GitHubCommandError, GitHubNotFoundError } from "./errors";
+import { retryTransient } from "#shared/retry-transient";
+import { githubApi } from "./api";
+import type { GitHubApiRequest, GitHubApiResponse } from "./api";
 import { ConfigService, getGitHubConfig, resolveGitHubRepoTarget } from "#config";
 
 // Transient GitHub-side failures worth a silent retry (vs. a hard error the agent must act on).
@@ -34,6 +37,11 @@ const KNOWN_STDERR_HINTS: ReadonlyArray<{
     re: /already exists/i,
     hint: "The resource already exists. Fetch the existing one and update it instead of creating another.",
   },
+  {
+    re: /Can not (?:approve|request changes on) your own pull request/i,
+    hint: "GitHub refuses a verdict review on your own PR. Post the findings with --event comment, or have the reviewing account submit the verdict.",
+    nextCommand: "agent-tools-gh pr review --pr <number> --event comment --body <text>",
+  },
   {
     re: /pending review/i,
     hint: "A pending (unsubmitted) review blocks this mutation. Inspect its contents and submit or discard it before retrying.",
@@ -77,6 +85,9 @@ export class GitHubService extends Context.Service<
       query: string,
       variables: Record<string, string | number | null>,
     ) => Effect.Effect<unknown, GhError>;
+    readonly apiRequest: <T>(
+      opts: GitHubApiRequest,
+    ) => Effect.Effect<GitHubApiResponse<T>, GhError>;
     readonly getRepoConfig: () => Effect.Effect<GitHubRepoConfig | undefined, never>;
     readonly getRepoInfo: () => Effect.Effect<RepoInfo, GhError>;
     readonly withRepoTarget: <A, E, R>(
@@ -256,20 +267,12 @@ export class GitHubService extends Context.Service<
         // Auto-retry transient failures, but only for idempotent reads (never replay a mutation).
         const runGh = (args: string[]): Effect.Effect<GhResult, GhError> => {
           const canRetry = isSafeRetryRead(args);
-          const loop = (attempt: number): Effect.Effect<GhResult, GhError> =>
-            runGhAttempt(args).pipe(
-              Effect.catch((err) => {
-                const retryable =
-                  err instanceof GitHubCommandError && err.retryable === true && canRetry;
-                if (retryable && attempt < MAX_GH_RETRIES) {
-                  return Effect.sleep(Duration.millis(500 * 2 ** attempt)).pipe(
-                    Effect.flatMap(() => loop(attempt + 1)),
-                  );
-                }
-                return Effect.fail(err);
-              }),
-            );
-          return loop(0);
+          return retryTransient({
+            attempt: () => runGhAttempt(args),
+            isTransient: (err) =>
+              err instanceof GitHubCommandError && err.retryable === true && canRetry,
+            maxRetries: MAX_GH_RETRIES,
+          });
         };
 
         const runGhJson = <T>(args: string[]) =>
@@ -360,7 +363,15 @@ export class GitHubService extends Context.Service<
           return repoInfo;
         });
 
-        return { runGh, runGhJson, runGraphQL, getRepoConfig, getRepoInfo, withRepoTarget };
+        return {
+          runGh,
+          runGhJson,
+          runGraphQL,
+          apiRequest: githubApi,
+          getRepoConfig,
+          getRepoInfo,
+          withRepoTarget,
+        };
       }),
     ),
   );

package/src/gh-tool/types.ts

@@ -314,3 +314,41 @@ export type JobAnnotations = {
   jobName: string;
   annotations: CheckRunAnnotation[];
 };
+
+export type StackMember = {
+  position: number;
+  number: number;
+  title: string;
+  headRefName: string;
+  baseRefName: string;
+  state: "open" | "closed" | "merged";
+  isDraft: boolean;
+  url: string;
+};
+
+export type StackView = {
+  pr: number;
+  isStacked: boolean;
+  stackNumber: number | null;
+  baseRef: string | null;
+  members: StackMember[];
+};
+
+export type StackMergeBlocker = {
+  number: number;
+  reason: "draft" | "not_mergeable" | "mergeability_unknown" | "checks_failing" | "checks_pending";
+  detail: string;
+};
+
+export type StackMergeResult = {
+  stackNumber: number;
+  baseRef: string;
+  target: number;
+  strategy: MergeStrategy;
+  plan: Array<{ position: number; number: number; headRefName: string }>;
+  merged: boolean;
+  dryRun: boolean;
+  blockers: StackMergeBlocker[];
+  sha: string | null;
+  adoptedExistingRequest: boolean;
+};

package/src/shared/index.ts

@@ -35,3 +35,5 @@ export {
 } from "./transform";
 
 export { transformLogOutput } from "./log-transform";
+export { retryTransient } from "./retry-transient";
+export { pollUntilResolved } from "./poll-until-resolved";

package/src/shared/poll-until-resolved.ts

@@ -0,0 +1,39 @@
+import { Clock, Duration, Effect } from "effect";
+
+export const pollUntilResolved = <A, E, R>(opts: {
+  initial: A;
+  isPending: (value: A) => boolean;
+  fetchLatest: () => Effect.Effect<A, E, R>;
+  intervalMs: number;
+  budgetSeconds: number;
+}): Effect.Effect<A, E, R> =>
+  Effect.gen(function* () {
+    let latest = opts.initial;
+
+    if (!opts.isPending(latest)) {
+      return latest;
+    }
+
+    const start = yield* Clock.currentTimeMillis;
+    const deadlineMs = Number(start) + opts.budgetSeconds * 1000;
+    let timedOut = false;
+
+    // Effect.whileLoop (not recursion) so TestClock.adjust can advance Effect.sleep without real waits.
+    yield* Effect.whileLoop({
+      while: () => opts.isPending(latest) && !timedOut,
+      body: () =>
+        Effect.gen(function* () {
+          const now = yield* Clock.currentTimeMillis;
+          if (Number(now) >= deadlineMs) {
+            timedOut = true;
+            return;
+          }
+          const remaining = deadlineMs - Number(now);
+          yield* Effect.sleep(Duration.millis(Math.min(opts.intervalMs, remaining)));
+          latest = yield* opts.fetchLatest();
+        }),
+      step: () => undefined,
+    });
+
+    return latest;
+  });

package/src/shared/retry-transient.ts

@@ -0,0 +1,24 @@
+import { Duration, Effect } from "effect";
+
+const BASE_DELAY_MS = 500;
+
+export const retryTransient = <A, E, R>(opts: {
+  attempt: () => Effect.Effect<A, E, R>;
+  isTransient: (error: E) => boolean;
+  maxRetries: number;
+}): Effect.Effect<A, E, R> => {
+  const loop = (attempt: number): Effect.Effect<A, E, R> =>
+    opts
+      .attempt()
+      .pipe(
+        Effect.catch((error: E) =>
+          opts.isTransient(error) && attempt < opts.maxRetries
+            ? Effect.sleep(Duration.millis(BASE_DELAY_MS * 2 ** attempt)).pipe(
+                Effect.flatMap(() => loop(attempt + 1)),
+              )
+            : Effect.fail(error),
+        ),
+      );
+
+  return loop(0);
+};