@blogic-cz/agent-tools 1.2.2 → 1.4.0

package/src/gh-tool/api.ts

@@ -0,0 +1,166 @@
+import { Effect } from "effect";
+
+import { retryTransient } from "#shared/retry-transient";
+
+import { GitHubAuthError, GitHubCommandError, GitHubNotFoundError } from "./errors";
+import type { GitHubApiError } from "./errors";
+
+// Direct HTTP, not `gh api`: the CLI collapses every failure into a non-zero exit and
+// loses the status code, but merge-async answers 202 (accepted), 200 (already merged or
+// queued) and 409 (a request already exists, UUID returned) as three different outcomes.
+const GITHUB_API_ROOT = "https://api.github.com";
+const GITHUB_ACCEPT = "application/vnd.github+json";
+const GITHUB_API_VERSION = "2022-11-28";
+
+export type GitHubApiResponse<T> = {
+  status: number;
+  body: T;
+};
+
+const authFailure = (message: string) =>
+  new GitHubAuthError({
+    message,
+    hint: "Set GITHUB_TOKEN or GH_TOKEN, or authenticate the GitHub CLI with 'gh auth login'.",
+    nextCommand: "gh auth login",
+  });
+
+// Environment first, GH_TOKEN before GITHUB_TOKEN to match the gh CLI: the active gh
+// account is directory-scoped global state and the shell exports the matching token.
+// `gh auth token` only covers shells that export none.
+export const resolveGitHubToken = Effect.fn("gh.resolveGitHubToken")(function* () {
+  const fromEnv = [process.env["GH_TOKEN"], process.env["GITHUB_TOKEN"]].find(
+    (candidate) => candidate !== undefined && candidate.length > 0,
+  );
+  if (fromEnv !== undefined && fromEnv.length > 0) {
+    return fromEnv;
+  }
+
+  // Bun.spawn rather than the ChildProcessSpawner service on purpose: routing it through
+  // the service would put that requirement in the error channel of every command that
+  // reads the API, and token resolution is not what those commands are testing.
+  const token = yield* Effect.tryPromise({
+    try: async () => {
+      const proc = Bun.spawn(["gh", "auth", "token", "--hostname", "github.com"], {
+        stdout: "pipe",
+        stderr: "ignore",
+      });
+      const stdout = await new Response(proc.stdout).text();
+      const exitCode = await proc.exited;
+      return exitCode === 0 ? stdout.trim() : "";
+    },
+    catch: () => authFailure("No GitHub token available."),
+  }).pipe(Effect.orElseSucceed(() => ""));
+  if (token.length === 0) {
+    return yield* authFailure("No GitHub token available.");
+  }
+
+  return token;
+});
+
+export type GitHubApiRequest = {
+  path: string;
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  body?: unknown;
+  alsoAcceptStatus?: number[];
+};
+
+const MAX_API_RETRIES = 2;
+
+const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(opts: GitHubApiRequest) {
+  const token = yield* resolveGitHubToken();
+  const method = opts.method ?? "GET";
+  const url = `${GITHUB_API_ROOT}/${opts.path.replace(/^\//, "")}`;
+
+  const response = yield* Effect.tryPromise({
+    try: () =>
+      fetch(url, {
+        method,
+        headers: {
+          Accept: GITHUB_ACCEPT,
+          Authorization: `Bearer ${token}`,
+          "X-GitHub-Api-Version": GITHUB_API_VERSION,
+          ...(opts.body === undefined ? {} : { "Content-Type": "application/json" }),
+        },
+        ...(opts.body === undefined ? {} : { body: JSON.stringify(opts.body) }),
+      }),
+    catch: (cause) =>
+      new GitHubCommandError({
+        message: `GitHub API request failed: ${String(cause)}`,
+        command: `${method} ${opts.path}`,
+        exitCode: -1,
+        stderr: String(cause),
+        retryable: true,
+        hint: "Check network connectivity and VPN state, then retry.",
+      }),
+  });
+
+  const text = yield* Effect.tryPromise({
+    try: () => response.text(),
+    catch: (cause) =>
+      new GitHubCommandError({
+        message: `GitHub API response could not be read: ${String(cause)}`,
+        command: `${method} ${opts.path}`,
+        exitCode: -1,
+        stderr: String(cause),
+        hint: "The connection dropped mid-response. Re-read the resource before retrying a mutation.",
+      }),
+  });
+  const parsed: unknown = text.length === 0 ? null : safeJsonParse(text);
+
+  const accepted = new Set([200, ...(opts.alsoAcceptStatus ?? [])]);
+  if (accepted.has(response.status)) {
+    return { status: response.status, body: parsed as T };
+  }
+
+  if (response.status === 401) {
+    return yield* authFailure("GitHub credentials rejected (HTTP 401).");
+  }
+
+  if (response.status === 404) {
+    return yield* new GitHubNotFoundError({
+      message: `GitHub API returned 404 for ${opts.path}`,
+      identifier: opts.path,
+      resource: "github-api",
+      hint: "Verify the resource exists, that you have access, and that the feature is enabled for this repository.",
+    });
+  }
+
+  return yield* new GitHubCommandError({
+    message: apiErrorMessage(parsed, response.status),
+    command: `${method} ${opts.path}`,
+    exitCode: response.status,
+    stderr: text,
+    ...(response.status >= 500 ? { retryable: true } : {}),
+  });
+});
+
+// Mirrors GitHubService.runGh: replay a transient failure, and only for an idempotent read.
+export const githubApi = <T>(
+  opts: GitHubApiRequest,
+): Effect.Effect<GitHubApiResponse<T>, GitHubApiError> =>
+  retryTransient({
+    attempt: () => githubApiAttempt<T>(opts),
+    isTransient: (error) =>
+      error._tag === "GitHubCommandError" &&
+      error.retryable === true &&
+      (opts.method ?? "GET") === "GET",
+    maxRetries: MAX_API_RETRIES,
+  });
+
+const safeJsonParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+const apiErrorMessage = (body: unknown, status: number): string => {
+  if (typeof body === "object" && body !== null && "message" in body) {
+    const message = (body as { message?: unknown }).message;
+    if (typeof message === "string") {
+      return `GitHub API error (HTTP ${status}): ${message}`;
+    }
+  }
+  return `GitHub API error (HTTP ${status})`;
+};

package/src/gh-tool/errors.ts

@@ -63,3 +63,5 @@ export type GitHubServiceError =
   | GitHubAuthError
   | GitHubMergeError
   | GitHubTimeoutError;
+
+export type GitHubApiError = GitHubCommandError | GitHubAuthError | GitHubNotFoundError;

package/src/gh-tool/index.ts

@@ -27,6 +27,7 @@ import {
   prEditCommand,
   prMergeCommand,
   prReadyCommand,
+  prStackCommand,
   prRequestReviewCommand,
   prThreadsCommand,
   prCommentsCommand,
@@ -93,6 +94,7 @@ const prCommand = Command.make("pr", {}).pipe(
     prEditCommand,
     prMergeCommand,
     prReadyCommand,
+    prStackCommand,
     prRequestReviewCommand,
     prWaitMergeableCommand,
     prThreadsCommand,

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

@@ -29,6 +29,7 @@ import {
   REVIEW_EVENTS,
 } from "#gh/config";
 
+import { mergeStack, readStack, unstackStack } from "./stack";
 import {
   closePR,
   collectWithStableState,
@@ -413,6 +414,23 @@ export const fetchReviewTriage = Effect.fn("pr.fetchReviewTriage")(function* (
   if (info.reviewDecision !== "" && info.reviewDecision !== "APPROVED") {
     blocking.push(`review=${info.reviewDecision}`);
   }
+
+  // A member of a GitHub stack cannot merge on its own while open members sit below it, so a
+  // verdict that reads only this PR would report ready for a PR nothing can land.
+  const stackView = yield* readStack({ pr: info.number }).pipe(
+    Effect.catch(() => Effect.succeed(null)),
+  );
+  const ownPosition = stackView?.members.find((member) => member.number === info.number)?.position;
+  const openBelow =
+    stackView?.isStacked === true && ownPosition !== undefined
+      ? stackView.members.filter(
+          (member) => member.state === "open" && member.position < ownPosition,
+        )
+      : [];
+  if (openBelow.length > 0) {
+    blocking.push(`stack_members_below=${openBelow.map((member) => member.number).join(",")}`);
+  }
+
   const ready = {
     ready: blocking.length === 0,
     mergeable: info.mergeable,
@@ -1609,3 +1627,81 @@ export const prReplyAndResolveCommand = Command.make(
     "Composite: reply to a review comment and resolve its thread (PR/thread inferred from comment)",
   ),
 );
+
+const prStackViewCommand = Command.make(
+  "view",
+  {
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(Flag.withDescription("PR number to read the stack of")),
+    repo: repoOption,
+  },
+  ({ format, pr, repo }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        const result = yield* readStack({ pr });
+        yield* logFormatted(result, format);
+      }),
+    ),
+).pipe(Command.withDescription("Show every PR in the stack containing this PR, bottom-up"));
+
+const prStackMergeCommand = Command.make(
+  "merge",
+  {
+    confirm: Flag.boolean("confirm").pipe(
+      Flag.withDescription("Actually merge (without this flag, only shows the ordered plan)"),
+      Flag.withDefault(false),
+    ),
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(Flag.withDescription("Any PR in the stack to merge")),
+    repo: repoOption,
+    strategy: Flag.choice("strategy", MERGE_STRATEGIES).pipe(
+      Flag.withDescription("Merge strategy: squash, merge, or rebase"),
+      Flag.withDefault(DEFAULT_MERGE_STRATEGY),
+    ),
+  },
+  ({ confirm, format, pr, repo, strategy }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        const result = yield* mergeStack({ confirm, pr, strategy });
+        yield* logFormatted(result, format);
+      }),
+    ),
+).pipe(
+  Command.withDescription(
+    "Merge every open PR in the stack in one request (dry-run by default, use --confirm)",
+  ),
+);
+
+const prStackUnstackCommand = Command.make(
+  "unstack",
+  {
+    confirm: Flag.boolean("confirm").pipe(
+      Flag.withDescription(
+        "Actually unstack (without this flag, only shows what would be removed)",
+      ),
+      Flag.withDefault(false),
+    ),
+    format: formatOption,
+    pr: Flag.integer("pr").pipe(Flag.withDescription("Any PR in the stack to dissolve")),
+    repo: repoOption,
+  },
+  ({ confirm, format, pr, repo }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        const result = yield* unstackStack({ confirm, pr });
+        yield* logFormatted(result, format);
+      }),
+    ),
+).pipe(
+  Command.withDescription(
+    "Remove every unmerged PR from the stack, dissolving it (dry-run by default)",
+  ),
+);
+
+export const prStackCommand = Command.make("stack", {}).pipe(
+  Command.withSubcommands([prStackViewCommand, prStackMergeCommand, prStackUnstackCommand]),
+  Command.withDescription("Stacked pull request operations"),
+);

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

@@ -22,7 +22,9 @@ import { GitHubService } from "#gh/service";
 import { logText } from "#shared";
 
 import type { ButStatusJson, PRViewJsonResult } from "./helpers";
+import { pollUntilResolved } from "#shared/poll-until-resolved";
 import { runLocalCommand } from "./helpers";
+import { readStack } from "./stack-read";
 import {
   diagnoseLogEntries,
   discoverDispatchedRun,
@@ -200,7 +202,7 @@ const fetchWorkflowRunFailureContext = Effect.fn("pr.fetchWorkflowRunFailureCont
 // is an ordinary state, so map it to [] and keep the zero-check paths downstream reachable.
 export const NO_CHECKS_REPORTED_RE = /no checks reported/i;
 
-const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr: number | null) {
+export const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr: number | null) {
   const gh = yield* GitHubService;
 
   const args = ["pr", "checks"];
@@ -763,26 +765,13 @@ const mergeViaAsyncApi = Effect.fn("pr.mergeViaAsyncApi")(function* (opts: {
   ]);
 
   const uuid = latest.details?.uuid;
-  if (latest.status === "pending" && uuid !== undefined) {
-    const start = yield* Clock.currentTimeMillis;
-    const deadlineMs = Number(start) + MAX_ASYNC_MERGE_WAIT_SECONDS * 1000;
-    let timedOut = false;
-
-    // Effect.whileLoop (not recursion) so TestClock.adjust can advance Effect.sleep without real waits.
-    yield* Effect.whileLoop({
-      while: () => latest.status === "pending" && !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(ASYNC_MERGE_POLL_INTERVAL_MS, remaining)));
-          latest = yield* gh.runGhJson<AsyncMergeResult>(["api", `${asyncPath}/${uuid}`]);
-        }),
-      step: () => undefined,
+  if (uuid !== undefined) {
+    latest = yield* pollUntilResolved({
+      initial: latest,
+      isPending: (value) => value.status === "pending",
+      fetchLatest: () => gh.runGhJson<AsyncMergeResult>(["api", `${asyncPath}/${uuid}`]),
+      intervalMs: ASYNC_MERGE_POLL_INTERVAL_MS,
+      budgetSeconds: MAX_ASYNC_MERGE_WAIT_SECONDS,
     });
   }
 
@@ -832,6 +821,57 @@ export const mergePR = Effect.fn("pr.mergePR")(function* (opts: {
 
   const repo = opts.deleteBranch ? yield* gh.getRepoInfo() : null;
 
+  // merge-async lands the requested PR AND every unmerged PR below it in its stack, and
+  // `gh pr merge` falls back to that endpoint for a stacked PR. Merging one member can
+  // therefore land members this command never named. Refuse instead of merging silently.
+  // Fail closed: readStack already reports a repository without a stacks surface as
+  // unstacked, so a failure here leaves membership genuinely unknown, and proceeding
+  // would land whatever sits below this PR without naming it.
+  const stackView = yield* readStack({ pr: opts.pr }).pipe(
+    Effect.catch((error) =>
+      Effect.fail(
+        new GitHubMergeError({
+          message: `Could not determine whether PR #${opts.pr} belongs to a stack: ${error.message}`,
+          reason: "unknown",
+          hint: "Merging a stack member lands every open PR below it, so the merge is refused while membership is unknown. Retry, or read the stack with 'pr stack view'.",
+          nextCommand: `agent-tools-gh pr stack view --pr ${opts.pr}`,
+        }),
+      ),
+    ),
+  );
+  const ownPosition = stackView.members.find((entry) => entry.number === opts.pr)?.position;
+
+  // The stack was fetched by querying this PR, so it must be among its own members. If it
+  // is not, the PR left the stack between the list call and the detail call and membership
+  // is unknown again — the same reason the lookup failure above refuses.
+  if (stackView.isStacked && ownPosition === undefined) {
+    return yield* new GitHubMergeError({
+      message: `PR #${opts.pr} is missing from stack #${stackView.stackNumber}, which was read for that PR`,
+      reason: "unknown",
+      hint: "The stack changed while it was being read. Re-read it with 'pr stack view' before merging.",
+      nextCommand: `agent-tools-gh pr stack view --pr ${opts.pr}`,
+    });
+  }
+
+  const openBelow =
+    !stackView.isStacked || ownPosition === undefined
+      ? []
+      : stackView.members.filter(
+          (member) => member.state === "open" && member.position < ownPosition,
+        );
+
+  if (openBelow.length > 0) {
+    return yield* new GitHubMergeError({
+      message:
+        `PR #${opts.pr} sits above ${openBelow.length} open PR(s) in stack #${stackView.stackNumber}: ` +
+        openBelow.map((member) => `#${member.number}`).join(", ") +
+        ". Merging it would land them too.",
+      reason: "unknown",
+      hint: "Use 'pr stack merge' to merge a stack: it checks every member first and reports the whole plan.",
+      nextCommand: `agent-tools-gh pr stack merge --pr ${opts.pr}`,
+    });
+  }
+
   // A long-lived branch (default/env branch) as PR head means a promotion PR
   // (e.g. main -> staging). PRs based on it are unrelated work, not a stack —
   // retargeting them would mass-rewrite their base — and the branch itself
@@ -1141,6 +1181,24 @@ export const editPR = Effect.fn("pr.editPR")(function* (opts: {
 
   const repo = yield* gh.getRepoInfo();
 
+  // GitHub rejects a base change on a stacked PR with a bare 422. Say what the state is and
+  // which operation changes it, rather than letting the validation error through.
+  if (opts.base !== null) {
+    const stackView = yield* readStack({ pr: opts.pr }).pipe(
+      Effect.catch(() => Effect.succeed(null)),
+    );
+    if (stackView?.isStacked === true) {
+      return yield* new GitHubCommandError({
+        command: "pr edit --base",
+        exitCode: 1,
+        stderr: `PR #${opts.pr} belongs to GitHub stack #${stackView.stackNumber}`,
+        message: `Cannot retarget PR #${opts.pr}: it belongs to GitHub stack #${stackView.stackNumber}, whose members' bases GitHub owns`,
+        hint: "Dissolve the stack first with 'pr stack unstack', which removes every unmerged member, then retarget. Merging the stack instead needs no retarget at all.",
+        nextCommand: `agent-tools-gh pr stack view --pr ${opts.pr}`,
+      });
+    }
+  }
+
   const editArgs = [
     "api",
     "--method",

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

@@ -14,6 +14,7 @@ export {
   prListCommand,
   prMergeCommand,
   prReadyCommand,
+  prStackCommand,
   prRequestReviewCommand,
   prReplyCommand,
   prRerunChecksCommand,

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;
+});