@blogic-cz/agent-tools 1.3.0 → 1.4.1

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

@@ -29,7 +29,7 @@ import {
   REVIEW_EVENTS,
 } from "#gh/config";
 
-import { mergeStack, readStack } from "./stack";
+import { mergeStack, readStack, unstackStack } from "./stack";
 import {
   closePR,
   collectWithStableState,
@@ -414,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,
@@ -1657,7 +1674,34 @@ const prStackMergeCommand = Command.make(
   ),
 );
 
+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]),
+  Command.withSubcommands([prStackViewCommand, prStackMergeCommand, prStackUnstackCommand]),
   Command.withDescription("Stacked pull request operations"),
 );

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

@@ -19,6 +19,7 @@ import type {
 import type { GitHubAuthError, GitHubNotFoundError } from "#gh/errors";
 import { GitHubCommandError, GitHubMergeError } from "#gh/errors";
 import { GitHubService } from "#gh/service";
+import type { GhResult } from "#gh/service";
 import { logText } from "#shared";
 
 import type { ButStatusJson, PRViewJsonResult } from "./helpers";
@@ -201,6 +202,13 @@ const fetchWorkflowRunFailureContext = Effect.fn("pr.fetchWorkflowRunFailureCont
 // `gh pr checks` exits 1 on an *empty* result ("no checks reported on the 'x' branch"). Zero checks
 // 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;
+// `gh` reports "no checks reported" both for the seconds after a push, before its checks
+// register, and forever for a PR that has none — the message cannot tell them apart. So the
+// wait for registration gets its own short budget: long enough to cover the race (measured
+// at roughly 40s on blogic-cz/agent-tools#134), short enough that a check-less PR is not held
+// for the caller's whole --timeout.
+const CHECK_REGISTRATION_POLL_SECONDS = 5;
+const CHECK_REGISTRATION_GRACE_SECONDS = 60;
 
 export const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr: number | null) {
   const gh = yield* GitHubService;
@@ -1181,6 +1189,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",
@@ -1226,7 +1252,45 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
     // Block for the caller's requested --timeout (no artificial cap — blocking isn't the problem;
     // --timeout is validated >= 1s at the CLI boundary). On timeout return a snapshot, never
     // nothing — that was the actual token-wasting bug.
-    const watchOutcome = yield* gh.runGh(watchArgs).pipe(
+    // A push registers its checks a moment after the ref lands, and `gh pr checks --watch`
+    // exits non-zero in that window. A watch was asked to wait, so keep waiting: the outer
+    // timeout still bounds it, and a PR that genuinely has no checks returns an empty
+    // snapshot at that deadline rather than an error.
+    let watchResult: GhResult | null = null;
+    let registered = false;
+    let graceExpired = false;
+    const watchThroughRegistration = Effect.gen(function* () {
+      const graceStart = yield* Clock.currentTimeMillis;
+      const graceDeadlineMs =
+        Number(graceStart) + Math.min(CHECK_REGISTRATION_GRACE_SECONDS, timeoutSeconds) * 1000;
+      yield* Effect.whileLoop({
+        while: () => !registered && !graceExpired,
+        body: () =>
+          gh.runGh(watchArgs).pipe(
+            Effect.flatMap((result) => {
+              watchResult = result;
+              registered = true;
+              return Effect.void;
+            }),
+            Effect.catchTag("GitHubCommandError", (error) =>
+              NO_CHECKS_REPORTED_RE.test(error.stderr) || NO_CHECKS_REPORTED_RE.test(error.message)
+                ? Effect.gen(function* () {
+                    const now = yield* Clock.currentTimeMillis;
+                    if (Number(now) >= graceDeadlineMs) {
+                      graceExpired = true;
+                      return;
+                    }
+                    yield* Effect.sleep(Duration.seconds(CHECK_REGISTRATION_POLL_SECONDS));
+                  })
+                : Effect.fail(error),
+            ),
+          ),
+        step: () => undefined,
+      });
+      return watchResult;
+    });
+
+    const watchOutcome = yield* watchThroughRegistration.pipe(
       Effect.timeoutOrElse({
         duration: timeoutSeconds * 1000,
         orElse: () => Effect.succeed(null),
@@ -1234,7 +1298,15 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
     );
 
     const results = yield* fetchCheckResults(pr);
-    if (!quiet && watchOutcome === null && results.some((c) => c.bucket === "pending")) {
+    if (!quiet && graceExpired) {
+      const prRef = pr === null ? "<number>" : String(pr);
+      yield* Console.warn(
+        `ℹ️  No checks registered within ${CHECK_REGISTRATION_GRACE_SECONDS}s of watching; ` +
+          `returning the current snapshot. If this PR should have checks, the push event was ` +
+          `likely dropped, and re-watching will find nothing again — dispatch them on the PR ` +
+          `head instead:\n   agent-tools-gh pr trigger-checks --pr ${prRef} --workflow <file.yml>`,
+      );
+    } else if (!quiet && watchOutcome === null && results.some((c) => c.bucket === "pending")) {
       const pending = results.filter((c) => c.bucket === "pending").length;
       yield* Console.warn(
         `ℹ️  Watch timed out after ${timeoutSeconds}s; ${pending} check(s) still pending (snapshot returned). ` +

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

@@ -237,3 +237,48 @@ export const mergeStack = Effect.fn("pr.mergeStack")(function* (opts: {
     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

@@ -68,13 +68,13 @@ const isSafeRetryRead = (args: readonly string[]): boolean => {
   return args.some((a) => READ_VERBS.has(a));
 };
 
-type GhResult = {
+export type GhResult = {
   stdout: string;
   stderr: string;
   exitCode: number;
 };
 
-type GhError = GitHubCommandError | GitHubAuthError | GitHubNotFoundError;
+export type GhError = GitHubCommandError | GitHubAuthError | GitHubNotFoundError;
 
 export class GitHubService extends Context.Service<
   GitHubService,

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,
@@ -524,9 +614,80 @@ const findCommand = Command.make(
     profile: profileOption,
   },
   ({ 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"));
+).pipe(
+  Command.withDescription(
+    "Alias for 'trace get' — resolves an id, and is not the TraceQL search; that is 'trace search'",
+  ),
+);
+
+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;