@blogic-cz/agent-tools 1.5.2 → 1.5.4

package/src/gh-tool/main.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env bun
+import { Command } from "effect/unstable/cli";
+import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { Effect, Layer } from "effect";
+
+import { makeSchemaCommand, renderCauseToStderr, VERSION } from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
+import { ConfigServiceLayer } from "#config";
+import {
+  issueCloseCommand,
+  issueCommentCommand,
+  issueCommentsCommand,
+  issueCreateCommand,
+  issueEditCommand,
+  issueListCommand,
+  issueReopenCommand,
+  issueSnapshotBatchCommand,
+  issueTriageCommand,
+  issueViewCommand,
+} from "./issue";
+import {
+  prViewCommand,
+  prStatusCommand,
+  prListCommand,
+  prCreateCommand,
+  prCloseCommand,
+  prEditCommand,
+  prMergeCommand,
+  prReadyCommand,
+  prStackCommand,
+  prRequestReviewCommand,
+  prThreadsCommand,
+  prCommentsCommand,
+  prIssueCommentsCommand,
+  prIssueCommentsLatestCommand,
+  prCommentCommand,
+  prDiscussionSummaryCommand,
+  prFeedbackCommand,
+  prReplyCommand,
+  prResolveCommand,
+  prReviewCommand,
+  prReviewsCommand,
+  prLastHumanReviewerCommand,
+  prSubmitReviewCommand,
+  prChecksCommand,
+  prChecksFailedCommand,
+  prRerunChecksCommand,
+  prTriggerChecksCommand,
+  prReplyAndResolveCommand,
+  prReviewTriageBatchCommand,
+  prReviewTriageCommand,
+  prWaitMergeableCommand,
+  prWatchCommand,
+} from "./pr/index";
+import { branchRenameCommand } from "./branch";
+import {
+  gistCreateCommand,
+  gistDeleteCommand,
+  gistEditCommand,
+  gistListCommand,
+  gistViewCommand,
+} from "./gist";
+import {
+  releaseCreateCommand,
+  releaseDeleteCommand,
+  releaseEditCommand,
+  releaseListCommand,
+  releaseStatusCommand,
+  releaseViewCommand,
+} from "./release";
+import { repoInfoCommand, repoListCommand, repoSearchCodeCommand } from "./repo";
+import { GitHubService } from "./service";
+import {
+  workflowAnnotationsCommand,
+  workflowCancelCommand,
+  workflowJobLogsCommand,
+  workflowJobsCommand,
+  workflowListCommand,
+  workflowLogsCommand,
+  workflowRerunCommand,
+  workflowRunCommand,
+  workflowViewCommand,
+  workflowWatchCommand,
+} from "./workflow";
+
+const prCommand = Command.make("pr", {}).pipe(
+  Command.withDescription("Pull request operations (view, create, merge, reviews, checks)"),
+  Command.withSubcommands([
+    prViewCommand,
+    prStatusCommand,
+    prListCommand,
+    prCreateCommand,
+    prCloseCommand,
+    prEditCommand,
+    prMergeCommand,
+    prReadyCommand,
+    prStackCommand,
+    prRequestReviewCommand,
+    prWaitMergeableCommand,
+    prThreadsCommand,
+    prCommentsCommand,
+    prReviewsCommand,
+    prLastHumanReviewerCommand,
+    prFeedbackCommand,
+    prIssueCommentsCommand,
+    prIssueCommentsLatestCommand,
+    prCommentCommand,
+    prDiscussionSummaryCommand,
+    prReplyCommand,
+    prResolveCommand,
+    prReviewCommand,
+    prSubmitReviewCommand,
+    prChecksCommand,
+    prChecksFailedCommand,
+    prWatchCommand,
+    prRerunChecksCommand,
+    prTriggerChecksCommand,
+    prReplyAndResolveCommand,
+    prReviewTriageCommand,
+    prReviewTriageBatchCommand,
+  ]),
+);
+
+const issueCommand = Command.make("issue", {}).pipe(
+  Command.withDescription(
+    "Issue operations (list, view, comments, triage, snapshot-batch, create, close, reopen, comment, edit)",
+  ),
+  Command.withSubcommands([
+    issueListCommand,
+    issueViewCommand,
+    issueCommentsCommand,
+    issueTriageCommand,
+    issueSnapshotBatchCommand,
+    issueCreateCommand,
+    issueCloseCommand,
+    issueReopenCommand,
+    issueCommentCommand,
+    issueEditCommand,
+  ]),
+);
+
+const branchCommand = Command.make("branch", {}).pipe(
+  Command.withDescription("Branch operations (rename)"),
+  Command.withSubcommands([branchRenameCommand]),
+);
+
+const repoCommand = Command.make("repo", {}).pipe(
+  Command.withDescription("Repository operations"),
+  Command.withSubcommands([repoInfoCommand, repoListCommand, repoSearchCodeCommand]),
+);
+
+const workflowCommand = Command.make("workflow", {}).pipe(
+  Command.withDescription(
+    "GitHub Actions workflow operations (run, list, view, jobs, logs, job-logs, annotations, rerun, cancel, watch)",
+  ),
+  Command.withSubcommands([
+    workflowRunCommand,
+    workflowListCommand,
+    workflowViewCommand,
+    workflowJobsCommand,
+    workflowLogsCommand,
+    workflowJobLogsCommand,
+    workflowAnnotationsCommand,
+    workflowRerunCommand,
+    workflowCancelCommand,
+    workflowWatchCommand,
+  ]),
+);
+
+const releaseCommand = Command.make("release", {}).pipe(
+  Command.withDescription("Release operations (create, list, view, edit, delete, status)"),
+  Command.withSubcommands([
+    releaseCreateCommand,
+    releaseListCommand,
+    releaseViewCommand,
+    releaseEditCommand,
+    releaseDeleteCommand,
+    releaseStatusCommand,
+  ]),
+);
+
+const gistCommand = Command.make("gist", {}).pipe(
+  Command.withDescription("Gist operations (list, view, create, edit, delete)"),
+  Command.withSubcommands([
+    gistListCommand,
+    gistViewCommand,
+    gistCreateCommand,
+    gistEditCommand,
+    gistDeleteCommand,
+  ]),
+);
+
+const commandsCommand = makeSchemaCommand(() => mainCommand);
+
+const mainCommand = Command.make("gh-tool", {}).pipe(
+  Command.withDescription(
+    `GitHub CLI Tool for Coding Agents
+
+Wraps the GitHub CLI (gh) with structured output for AI agents.
+Supports PR management, issue management, reviews, CI checks, and repo info.
+
+WORKFLOW FOR AI AGENTS:
+  1. Use 'pr view' to inspect current PR
+  2. Use 'pr discussion-summary' for overview (counts + latest discussion comment)
+  3. Use 'pr threads' and 'pr issue-comments-latest --author <username> --body-contains "Review"' for review context
+  4. Use 'pr reply', 'pr comment' and 'pr resolve' to handle feedback
+  4b. Use 'pr review --event request-changes|approve|comment --confirm' to post a verdict, or 'pr submit-review' for a pending one
+  5. Use 'pr checks' to monitor CI status; 'pr trigger-checks --workflow <file.yml>' when zero checks were reported
+  6. Use 'pr merge' to merge (dry-run by default)
+  7. Use 'issue list' to list open/closed issues
+  8. Use 'issue triage --issue N --verbosity full' to inspect one issue in one call
+  9. Use 'issue comments --issue N' to read issue discussion comments separately
+  10. Use 'issue close --issue N --comment "reason"' to close issues
+  11. Use 'issue comment --issue N --body "text"' to comment on issues
+  12. Use 'repo info' to get repository metadata
+  13. Use 'workflow run' to dispatch workflow_dispatch workflows
+  14. Use 'workflow list' to list recent workflow runs
+  15. Use 'workflow view --run N' to inspect a specific run with jobs/steps
+  16. Use 'workflow logs --run N' to get logs (failed jobs by default)
+  17. Use 'workflow job-logs --run N --job "build-web-app"' to get clean parsed logs for a specific job
+  18. Use 'workflow annotations --run N' to list CI annotations (errors, warnings, notices)
+  19. Use 'workflow watch --run N' to watch until completion
+  20. Use 'release status' to inspect latest release + repository context
+  21. Use 'release create --tag vX.Y.Z --generate-notes' to publish a release
+  22. Use 'release edit/view/list/delete' to maintain existing releases
+  23. Use 'branch rename --old-name X --new-name Y --confirm' to rename a branch
+  24. Use 'gist list/view' to read gists and 'gist create --files a.ts --desc "..."' to share snippets`,
+  ),
+  Command.withSubcommands([
+    prCommand,
+    issueCommand,
+    repoCommand,
+    branchCommand,
+    workflowCommand,
+    releaseCommand,
+    gistCommand,
+    commandsCommand,
+  ]),
+);
+
+const cli = Command.run(mainCommand, {
+  version: VERSION,
+});
+
+const MainLayer = GitHubService.layer.pipe(
+  Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
+  Layer.provideMerge(ConfigServiceLayer),
+);
+
+const program = withAudit("gh", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
+
+BunRuntime.runMain(program, {
+  disableErrorReporting: true,
+});

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

@@ -40,6 +40,8 @@ const CHECK_JSON_FIELDS = "name,state,bucket,link";
 const LONG_LIVED_BRANCHES = new Set(["main", "master", "develop", "staging", "production"]);
 const STABLE_SNAPSHOT_ATTEMPTS = 3;
 const GITHUB_ACTIONS_RUN_ID_RE = /github\.com\/[^/]+\/[^/]+\/actions\/runs\/(\d+)/;
+const MERGE_SHA_POLL_INTERVAL_MS = 1000;
+const MERGE_SHA_WAIT_SECONDS = 5;
 
 const validatePRTitle = Effect.fn("pr.validatePRTitle")(function* (title: string) {
   const gh = yield* GitHubService;
@@ -80,6 +82,52 @@ const validatePRTitle = Effect.fn("pr.validatePRTitle")(function* (title: string
   });
 });
 
+const resolveMergeSha = Effect.fn("pr.resolveMergeSha")(function* (
+  pr: number,
+  knownSha: string | null,
+) {
+  if (knownSha !== null) {
+    return knownSha;
+  }
+
+  const gh = yield* GitHubService;
+  const readMergeSha = () =>
+    gh
+      .runGhJson<{ mergeCommit: { oid: string } | null }>([
+        "pr",
+        "view",
+        String(pr),
+        "--json",
+        "mergeCommit",
+      ])
+      .pipe(Effect.map((result) => result.mergeCommit?.oid ?? null));
+  const result = yield* readMergeSha().pipe(
+    Effect.andThen((initial) =>
+      pollUntilResolved({
+        initial,
+        isPending: (value) => value === null,
+        fetchLatest: readMergeSha,
+        intervalMs: MERGE_SHA_POLL_INTERVAL_MS,
+        budgetSeconds: MERGE_SHA_WAIT_SECONDS,
+      }),
+    ),
+    Effect.map((sha) => ({ sha, failed: false as const })),
+    Effect.catch((error) =>
+      Console.error(
+        `Warning: PR #${pr} was merged, but its merge commit SHA could not be read: ${error.message}`,
+      ).pipe(Effect.as({ sha: null, failed: true as const })),
+    ),
+  );
+
+  if (result.sha === null && !result.failed) {
+    yield* Console.error(
+      `Warning: PR #${pr} was merged, but its merge commit SHA is still unknown after ${MERGE_SHA_WAIT_SECONDS}s.`,
+    );
+  }
+
+  return result.sha;
+});
+
 const buildChecksCommand = (pr: number | null, includeWatch: boolean): string =>
   `bun agent-tools-gh pr checks${pr !== null ? ` --pr ${pr}` : ""}${includeWatch ? " --watch" : ""}`;
 
@@ -1005,10 +1053,10 @@ export const mergePR = Effect.fn("pr.mergePR")(function* (opts: {
 
   const mergeArgs = ["pr", "merge", String(opts.pr), `--${opts.strategy}`];
 
-  const mergedSha = yield* gh
+  const shaFromAsyncMerge = yield* gh
     .runGh(mergeArgs)
     .pipe(
-      Effect.map((result) => result.stdout.match(/([0-9a-f]{7,40})/)?.[1] ?? null),
+      Effect.map(() => null),
       Effect.catchTag("GitHubCommandError", (error) =>
         ASYNC_MERGE_REQUIRED_RE.test(error.stderr)
           ? mergeViaAsyncApi({ pr: opts.pr, strategy: opts.strategy })
@@ -1092,6 +1140,8 @@ export const mergePR = Effect.fn("pr.mergePR")(function* (opts: {
       ),
     );
 
+  const mergedSha = yield* resolveMergeSha(opts.pr, shaFromAsyncMerge);
+
   // `gh pr merge --delete-branch` aborts its remote delete when the head branch is checked out in a
   // worktree; deleting the remote ref explicitly is worktree-independent. Local cleanup is separate.
   if (willDeleteBranch && repo && info.headRefName) {

package/src/gh-tool/service.ts

@@ -10,6 +10,7 @@ import { retryTransient } from "#shared/retry-transient";
 import { githubApi } from "./api";
 import type { GitHubApiRequest, GitHubApiResponse } from "./api";
 import { ConfigService, getGitHubConfig, resolveGitHubRepoTarget } from "#config";
+import { validateOutboundText } from "#gh/text-input";
 
 // Transient GitHub-side failures worth a silent retry (vs. a hard error the agent must act on).
 const NETWORK_ERROR_RE =
@@ -267,11 +268,14 @@ 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);
-          return retryTransient({
-            attempt: () => runGhAttempt(args),
-            isTransient: (err) =>
-              err instanceof GitHubCommandError && err.retryable === true && canRetry,
-            maxRetries: MAX_GH_RETRIES,
+          return Effect.gen(function* () {
+            yield* validateOutboundText(args.join("\n"), "gh-tool");
+            return yield* retryTransient({
+              attempt: () => runGhAttempt(args),
+              isTransient: (err) =>
+                err instanceof GitHubCommandError && err.retryable === true && canRetry,
+              maxRetries: MAX_GH_RETRIES,
+            });
           });
         };
 

package/src/gh-tool/text-input.ts

@@ -1,6 +1,7 @@
 import { Effect, Schema } from "effect";
 
 import { GitHubCommandError } from "#gh/errors";
+import { detectSecrets } from "#guard";
 
 const STDIN_SENTINEL = "-";
 const SENSITIVE_PATH_PATTERNS = [
@@ -16,6 +17,62 @@ const readTextFromStdin = () => Bun.stdin.text();
 export const isSensitivePath = (filePath: string) =>
   SENSITIVE_PATH_PATTERNS.some((pattern) => pattern.test(filePath));
 
+/** Inspect the final text, after shell expansion and after reading files or stdin. */
+export function unsafeOutboundTextReason(
+  text: string,
+  environment: Record<string, string | undefined> = process.env,
+): string | null {
+  if (detectSecrets(text)) return "a credential pattern";
+
+  const sensitiveName =
+    /(?:KEY|TOKEN|SECRET|PASS(?:WORD)?|PWD|CREDENTIAL|AUTH|COOKIE|SESSION|PSK)/i;
+  const isSensitiveName = (name: string) =>
+    name !== "PWD" && name !== "OLDPWD" && sensitiveName.test(name);
+  for (const [name, value] of Object.entries(environment)) {
+    if (isSensitiveName(name) && value && value.length >= 8 && text.includes(value)) {
+      return "a credential from the process environment";
+    }
+  }
+
+  const assignments = text.match(/^[A-Za-z_][A-Za-z0-9_]*=.*$/gm) ?? [];
+  if (
+    assignments.length >= 5 &&
+    assignments.some((line) => isSensitiveName(line.split("=", 1)[0] ?? ""))
+  ) {
+    return "an environment dump";
+  }
+  return null;
+}
+
+export const validateOutboundText = (text: string, command: string) => {
+  const reason = unsafeOutboundTextReason(text);
+  return reason === null
+    ? Effect.succeed(text)
+    : Effect.fail(
+        new GitHubCommandError({
+          command,
+          exitCode: 1,
+          stderr: `Refusing to publish text containing ${reason}`,
+          message: `Refusing to publish text containing ${reason}`,
+        }),
+      );
+};
+
+export const validateOutboundFile = (filePath: string, command: string) =>
+  Effect.tryPromise({
+    try: () => readTextFile(filePath),
+    catch: () =>
+      new GitHubCommandError({
+        command,
+        exitCode: 1,
+        stderr: `Refusing to publish unreadable or sensitive file: ${filePath}`,
+        message: `Refusing to publish unreadable or sensitive file: ${filePath}`,
+      }),
+  }).pipe(
+    Effect.flatMap((text) => validateOutboundText(text, command)),
+    Effect.asVoid,
+  );
+
 const readTextFile = (filePath: string) => {
   if (isSensitivePath(filePath)) {
     return Promise.reject(new Error(`Refusing to read sensitive file: ${filePath}`));
@@ -80,13 +137,13 @@ const resolveTextInputInternal = Effect.fn("gh.resolveTextInputInternal")(functi
   }
 
   if (value !== null) {
-    return value;
+    return yield* validateOutboundText(value, command);
   }
 
   if (fileValue !== null) {
     const source = fileValue === STDIN_SENTINEL ? "stdin" : fileValue;
 
-    return yield* Effect.tryPromise({
+    const text = yield* Effect.tryPromise({
       try: () => (fileValue === STDIN_SENTINEL ? readTextFromStdin() : readTextFile(fileValue)),
       catch: (error) =>
         new GitHubCommandError({
@@ -96,10 +153,11 @@ const resolveTextInputInternal = Effect.fn("gh.resolveTextInputInternal")(functi
           message: `Failed to read ${label} from ${source}: ${error instanceof Error ? error.message : String(error)}`,
         }),
     });
+    return yield* validateOutboundText(text, command);
   }
 
   if (stdin) {
-    return yield* Effect.tryPromise({
+    const text = yield* Effect.tryPromise({
       try: () => readTextFromStdin(),
       catch: (error) =>
         new GitHubCommandError({
@@ -109,6 +167,7 @@ const resolveTextInputInternal = Effect.fn("gh.resolveTextInputInternal")(functi
           message: `Failed to read ${label} from stdin: ${error instanceof Error ? error.message : String(error)}`,
         }),
     });
+    return yield* validateOutboundText(text, command);
   }
 
   if (missingMode === "null") {
@@ -116,7 +175,7 @@ const resolveTextInputInternal = Effect.fn("gh.resolveTextInputInternal")(functi
   }
 
   if (missingMode === "default") {
-    return missingValue ?? "";
+    return yield* validateOutboundText(missingValue ?? "", command);
   }
 
   return yield* Effect.fail(

package/src/gh-tool/workflow.ts

@@ -877,6 +877,7 @@ export const workflowWatchCommand = Command.make(
       Flag.withDescription(
         "Include the raw watch progress frames (large); omitted by default — final status/conclusion/jobs are always returned",
       ),
+      Flag.withDefault(false),
     ),
     repo: repoOption,
     run: Flag.Int("run").pipe(Flag.withDescription("Workflow run ID to watch")),