@blogic-cz/agent-tools 1.2.2 → 1.4.0

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

@@ -0,0 +1,284 @@
+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.",
+  });
+});
+
+export const unstackStack = Effect.fn("pr.unstackStack")(function* (opts: {
+  pr: number;
+  confirm: boolean;
+}) {
+  const gh = yield* GitHubService;
+  const repo = yield* gh.getRepoInfo();
+  const view = yield* readStack({ pr: opts.pr });
+
+  if (!view.isStacked || view.stackNumber === null) {
+    return yield* new GitHubMergeError({
+      message: `PR #${opts.pr} is not part of a GitHub stack`,
+      reason: "unknown",
+      hint: "There is no stack to dissolve.",
+      nextCommand: `agent-tools-gh pr stack view --pr ${opts.pr}`,
+    });
+  }
+
+  const unmerged = view.members.filter((member) => member.state === "open");
+
+  const plan = {
+    stackNumber: view.stackNumber,
+    pr: opts.pr,
+    removes: unmerged.map((member) => member.number),
+  };
+
+  if (!opts.confirm) {
+    return { ...plan, dissolved: false, unstacked: false, dryRun: true };
+  }
+
+  // The endpoint removes every unmerged member at once; it has no per-PR form. A 204 means
+  // nothing was left and the stack is gone, a 200 means some members could not be removed.
+  const result = yield* gh.apiRequest<unknown>({
+    path: `repos/${repo.owner}/${repo.name}/stacks/${view.stackNumber}/unstack`,
+    method: "POST",
+    alsoAcceptStatus: [204],
+  });
+
+  return {
+    ...plan,
+    dissolved: result.status === 204,
+    unstacked: true,
+    dryRun: false,
+  };
+});

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).
@@ -82,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>(
@@ -261,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[]) =>
@@ -365,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/observability-tool/shared.ts

@@ -26,6 +26,11 @@ export function formatObservabilityError(error: unknown): string {
     return error.message;
   }
 
+  // Structured causes carry their text in `message`; String() would render "[object Object]".
+  if (typeof error === "object" && error !== null && "message" in error) {
+    return String((error as { message: unknown }).message);
+  }
+
   return String(error);
 }
 

package/src/observability-tool/trace.ts

@@ -25,6 +25,7 @@ import type {
   SpanResolution,
   TempoSearchResponse,
   TempoTraceResponse,
+  TraceSearchHit,
   TraceSummary,
 } from "./types";
 
@@ -355,6 +356,95 @@ function resolveTraceFromId(
   });
 }
 
+/**
+ * Strict counterpart of relativeToEpoch for user-supplied windows: an unparseable bound is
+ * refused rather than silently collapsed to "now", which would report a zero-width window as
+ * "no traces found".
+ */
+function strictRelativeToEpoch(value: string, nowEpoch: number): number | undefined {
+  const trimmed = value.trim();
+  if (trimmed === "now") return nowEpoch;
+  return /^now-\d+[smhd]$/.test(trimmed) ? relativeToEpoch(trimmed, nowEpoch) : undefined;
+}
+
+/** Tempo rejects a search window wider than this, so the CLI says so before the API does. */
+const MAX_SEARCH_RANGE_SECONDS = 168 * 3600;
+
+export function summarizeSearchHits(response: TempoSearchResponse): TraceSearchHit[] {
+  return (response.traces ?? [])
+    .filter((trace) => trace.traceID !== undefined)
+    .map((trace) => {
+      const startedNano = nanoToBigInt(trace.startTimeUnixNano);
+
+      return {
+        traceId: trace.traceID as string,
+        startedAt:
+          startedNano === undefined
+            ? undefined
+            : new Date(Number(startedNano / 1_000_000n)).toISOString(),
+        rootServiceName: trace.rootServiceName,
+        rootTraceName: trace.rootTraceName,
+        durationMs: trace.durationMs,
+        matchedSpans: trace.spanSets?.reduce(
+          (total, spanSet) => total + (spanSet.matched ?? spanSet.spans?.length ?? 0),
+          0,
+        ),
+      };
+    })
+    .toSorted((left, right) => (right.startedAt ?? "").localeCompare(left.startedAt ?? ""));
+}
+
+export function searchTempoByQuery(
+  config: ObservabilityEnvConfig,
+  query: string,
+  window: SearchWindow,
+  limit: number,
+): Effect.Effect<TempoSearchResponse, ObservabilityToolError> {
+  return Effect.gen(function* () {
+    const tempoUid = yield* requireTempoUid(config);
+    const now = Math.floor(Date.now() / 1000);
+    const startEpoch = strictRelativeToEpoch(window.start, now);
+    const endEpoch = strictRelativeToEpoch(window.end, now);
+
+    if (startEpoch === undefined || endEpoch === undefined) {
+      const rejected = startEpoch === undefined ? window.start : window.end;
+      return yield* new ObservabilityToolError({
+        cause: {
+          message: `Unparseable time "${rejected}" — use "now" or "now-<number><s|m|h|d>", e.g. now-6h`,
+          code: "INVALID_TIME_RANGE",
+          retryable: false,
+        },
+      });
+    }
+
+    if (startEpoch >= endEpoch) {
+      return yield* new ObservabilityToolError({
+        cause: {
+          message: `Search window ${window.start} → ${window.end} ends at or before it starts`,
+          code: "INVALID_TIME_RANGE",
+          retryable: false,
+        },
+      });
+    }
+
+    if (endEpoch - startEpoch > MAX_SEARCH_RANGE_SECONDS) {
+      return yield* new ObservabilityToolError({
+        cause: {
+          message: `Search window ${window.start} → ${window.end} exceeds the 168h Tempo limit — query a narrower range`,
+          code: "SEARCH_RANGE_TOO_WIDE",
+          retryable: false,
+        },
+      });
+    }
+
+    const searchUrl =
+      `/api/datasources/proxy/uid/${tempoUid}/api/search` +
+      `?q=${encodeURIComponent(query)}&start=${startEpoch}&end=${endEpoch}&limit=${limit}`;
+
+    return yield* observabilityFetch<TempoSearchResponse>(config, searchUrl);
+  });
+}
+
 function handleTraceGet(
   id: string,
   format: OutputFormat,
@@ -526,7 +616,74 @@ const findCommand = Command.make(
   ({ id, format, env, profile }) => handleTraceGet(id, format, env, profile),
 ).pipe(Command.withDescription("Alias for 'trace get' — resolve a trace by trace ID or span ID"));
 
+const searchCommand = Command.make(
+  "search",
+  {
+    query: Argument.string("query"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Max traces to return (default: 20)"),
+      Flag.withDefault(20),
+    ),
+    start: Flag.string("start").pipe(
+      Flag.withDescription("Start time (default: now-1h, max span now-168h)"),
+      Flag.withDefault("now-1h"),
+    ),
+    end: Flag.string("end").pipe(
+      Flag.withDescription("End time (default: now)"),
+      Flag.withDefault("now"),
+    ),
+  },
+  ({ query, format, env, profile, limit, start, end }) => {
+    const startedAt = Date.now();
+
+    return Effect.gen(function* () {
+      const config = yield* resolveConfig(env, profile);
+      const response = yield* searchTempoByQuery(config, query, { start, end }, limit);
+      const traces = summarizeSearchHits(response);
+
+      const result = {
+        success: true,
+        message: `Found ${traces.length} trace(s) matching the TraceQL query`,
+        data: {
+          environment: env,
+          grafanaUrl: config.url,
+          tempoDatasourceUid: config.tempoUid ?? null,
+          query,
+          start,
+          end,
+          limit,
+          traceCount: traces.length,
+          traces,
+        },
+        executionTimeMs: Date.now() - startedAt,
+      };
+
+      yield* logText(formatOutput(result, format));
+    }).pipe(
+      Effect.catch((error) =>
+        Effect.gen(function* () {
+          const result = {
+            success: false,
+            message: "Failed to search Tempo",
+            error: formatObservabilityError(error),
+            hint: 'Query is TraceQL, e.g. { name = "GraphQL Document Validation" && status = error }. The window may not exceed 168h',
+            executionTimeMs: Date.now() - startedAt,
+          };
+          yield* logText(formatOutput(result, format));
+        }),
+      ),
+    );
+  },
+).pipe(
+  Command.withDescription(
+    "Search Tempo with a TraceQL query — find traces when no trace or span ID is known yet",
+  ),
+);
+
 export const traceCommand = Command.make("trace", {}).pipe(
   Command.withDescription("Tempo trace operations"),
-  Command.withSubcommands([getCommand, logsCommand, findCommand]),
+  Command.withSubcommands([getCommand, searchCommand, logsCommand, findCommand]),
 );

package/src/observability-tool/types.ts

@@ -127,6 +127,15 @@ export type TempoSearchResponse = {
   readonly metrics?: Record<string, unknown>;
 };
 
+export type TraceSearchHit = {
+  readonly traceId: string;
+  readonly startedAt?: string;
+  readonly rootServiceName?: string;
+  readonly rootTraceName?: string;
+  readonly durationMs?: number;
+  readonly matchedSpans?: number;
+};
+
 export const IdKind = Schema.Literals(["trace_id", "span_id"]);
 export type IdKind = typeof IdKind.Type;
 

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