@blogic-cz/agent-tools 1.11.1 → 1.13.0

package/src/gh-tool/read/telemetry.ts

@@ -0,0 +1,191 @@
+import { Context, Effect } from "effect";
+import { redactSensitiveText } from "#shared/content-security";
+
+export type RequestEvent = {
+  ts: string;
+  method: string;
+  endpoint: string;
+  status: number | null;
+  outcome: "cache" | "304" | "200" | "bypass" | "error" | "subprocess";
+  resource: string | null;
+  used: number | null;
+  remaining: number | null;
+  reset: number | null;
+};
+export type RequestRow = RequestEvent & { id: number; invocation: string; command: string };
+export type TelemetryStore = {
+  record: (event: RequestEvent) => void;
+  read: (since: string) => readonly RequestRow[];
+  close: () => void;
+};
+
+export const Telemetry = Context.Reference<TelemetryStore | null>("gh/Telemetry", {
+  defaultValue: () => null,
+});
+export const CacheRequest = Context.Reference<boolean>("gh/CacheRequest", {
+  defaultValue: () => false,
+});
+
+export const templateEndpoint = (path: string): string => {
+  const pathname = path.replace(/^https?:\/\/[^/]+/, "").split(/[?#]/, 1)[0] ?? "";
+  return redactSensitiveText(
+    `/${pathname.replace(/^\//, "")}`
+      .replace(/\b[0-9a-f]{7,64}\b/gi, (part) => (/^\d+$/.test(part) ? ":id" : ":sha"))
+      .replace(/\/\d+(?=\/|$)/g, "/:id"),
+  );
+};
+
+export const recordRequest = (event: RequestEvent): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    const store = yield* Telemetry;
+    try {
+      store?.record({
+        ...event,
+        endpoint:
+          event.outcome === "subprocess" ? event.endpoint : templateEndpoint(event.endpoint),
+      });
+    } catch {
+      /* Best effort. */
+    }
+  });
+
+export const cacheEvent = (operation: string): RequestEvent => ({
+  ts: new Date().toISOString(),
+  method: "CACHE",
+  endpoint: `cache/${operation}`,
+  status: null,
+  outcome: "cache",
+  resource: null,
+  used: null,
+  remaining: null,
+  reset: null,
+});
+
+const API_VALUE_FLAGS = new Set([
+  "-X",
+  "--method",
+  "-H",
+  "--header",
+  "-f",
+  "-F",
+  "--field",
+  "--raw-field",
+  "--jq",
+  "-q",
+  "--template",
+  "-t",
+  "--input",
+  "--cache",
+  "-p",
+  "--preview",
+  "--hostname",
+]);
+
+export const ghSubprocessEvent = (args: readonly string[], exitCode: number): RequestEvent => {
+  const api = args[0] === "api";
+  let endpoint: string | undefined;
+  let method: string | undefined;
+  let hasFields = false;
+  if (api) {
+    for (let index = 1; index < args.length; index++) {
+      const arg = args[index];
+      if (arg === undefined) continue;
+      if (arg === "--") {
+        endpoint ??= args[index + 1];
+        break;
+      }
+      if (!arg.startsWith("-")) {
+        endpoint ??= arg;
+        continue;
+      }
+      const equals = arg.indexOf("=");
+      const flag = equals < 0 ? arg : arg.slice(0, equals);
+      if (!API_VALUE_FLAGS.has(flag)) continue;
+      const value = equals < 0 ? args[++index] : arg.slice(equals + 1);
+      if (flag === "-X" || flag === "--method") method = value;
+      if (flag === "-f" || flag === "-F" || flag === "--field" || flag === "--raw-field")
+        hasFields = true;
+    }
+  }
+  return {
+    ...cacheEvent(""),
+    method: api ? (method ?? (hasFields ? "POST" : "GET")) : "GH",
+    endpoint: api ? templateEndpoint(endpoint ?? "") : args.slice(0, 2).join(" "),
+    status: exitCode >= 100 && exitCode <= 599 ? exitCode : null,
+    outcome: "subprocess",
+  };
+};
+
+const counts = (values: readonly string[]) => {
+  const groups = new Map<string, number>();
+  for (const value of values) groups.set(value, (groups.get(value) ?? 0) + 1);
+  return [...groups]
+    .map(([name, requests]) => ({ name, requests }))
+    .toSorted((a, b) => b.requests - a.requests || a.name.localeCompare(b.name));
+};
+
+const subprocessSpendsResource = (row: RequestRow, resource: string): boolean => {
+  if (row.outcome !== "subprocess") return false;
+  if (row.method === "GH") return true;
+  if (row.method === "GET" && row.endpoint === "/rate_limit") return false;
+  return row.endpoint === "/graphql" ? resource === "graphql" : resource !== "graphql";
+};
+
+export const summarizeRequests = (rows: readonly RequestRow[]) => {
+  const requests = rows.filter((row) => row.outcome !== "cache" && row.outcome !== "subprocess");
+  const subprocesses = rows.filter((row) => row.outcome === "subprocess");
+  const previous = new Map<string, { used: number; index: number }>();
+  let externalUsageEstimate = 0;
+  let intervals = 0;
+  for (const [index, row] of rows.entries()) {
+    if (row.outcome === "cache" || row.outcome === "subprocess") continue;
+    if (row.resource === null || row.used === null || row.reset === null) continue;
+    const resource = row.resource;
+    const key = `${resource}:${row.reset}`;
+    const before = previous.get(key);
+    if (before !== undefined && row.used >= before.used) {
+      const interval = rows.slice(before.index + 1, index + 1);
+      const own = interval.filter(
+        (candidate) =>
+          candidate.resource === resource &&
+          (candidate.reset === null || candidate.reset === row.reset) &&
+          candidate.status !== 304 &&
+          candidate.endpoint !== "/rate_limit",
+      ).length;
+      const subprocessCalls = interval.filter((candidate) =>
+        subprocessSpendsResource(candidate, resource),
+      ).length;
+      externalUsageEstimate += Math.max(0, row.used - before.used - own - subprocessCalls);
+      intervals++;
+    }
+    if (before === undefined || row.used >= before.used)
+      previous.set(key, { used: row.used, index });
+  }
+  const notModified = requests.filter((row) => row.status === 304).length;
+  return {
+    directHttpRequests: requests.length,
+    ghSubprocessCalls: subprocesses.length,
+    cacheHits: rows.filter((row) => row.outcome === "cache").length,
+    subprocessTopCommands: counts(subprocesses.map((row) => redactSensitiveText(row.command)))
+      .slice(0, 20)
+      .map(({ name, requests: calls }) => ({ name, calls })),
+    subprocessTopEndpoints: counts(subprocesses.map((row) => `${row.method} ${row.endpoint}`))
+      .slice(0, 20)
+      .map(({ name, requests: calls }) => ({ name, calls })),
+    directHttpByResource: counts(requests.map((row) => row.resource ?? "unknown")),
+    directHttpTopCommands: counts(requests.map((row) => redactSensitiveText(row.command))).slice(
+      0,
+      20,
+    ),
+    directHttpTopEndpoints: counts(requests.map((row) => `${row.method} ${row.endpoint}`)).slice(
+      0,
+      20,
+    ),
+    notModified,
+    ratio304: requests.length === 0 ? null : notModified / requests.length,
+    externalUsageEstimate: intervals === 0 ? null : externalUsageEstimate,
+    observedIntervals: intervals,
+    caveat:
+      "Estimate within observed reset windows only. Missing headers, concurrent requests, different tokens and dropped telemetry reduce accuracy. Direct HTTP counts are exact. Each gh subprocess call may make zero or more HTTP requests; its HTTP status and quota headers are unavailable. For this estimate, subprocess calls count as one request each. Cache hits count ReadCache only.",
+  };
+};

package/src/gh-tool/read/transport.ts

@@ -1,10 +1,16 @@
+import { ghSubprocessEvent, recordRequest } from "./telemetry";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
-import { Context, Effect, Layer, Stream } from "effect";
+import { Context, Effect, Layer, Schema, Stream } from "effect";
 
 import type { GitHubRepoConfig } from "#config";
 import type { RepoInfo } from "#gh/types";
 import type { RepoRef } from "./keys";
 
+import {
+  bunMarkdownOutline,
+  findCheckboxLines,
+  validateCheckboxEdit,
+} from "#gh/pr/checkbox-markdown";
 import { GH_BINARY } from "#gh/config";
 import { ghEnvironment } from "#gh/environment";
 import { GitHubAuthError, GitHubCommandError, GitHubNotFoundError } from "#gh/errors";
@@ -79,11 +85,20 @@ export type GhResult = {
 };
 
 export type GhError = GitHubCommandError | GitHubAuthError | GitHubNotFoundError;
+export type PRCheckboxWrite = {
+  readonly repo: RepoRef;
+  readonly pr: number;
+  readonly expectedBody: string;
+  readonly boxOffset: number;
+  readonly replacement: " " | "x";
+  readonly selectionText: readonly string[];
+};
 
 export class GitHubService extends Context.Service<
   GitHubService,
   {
     readonly runGh: (args: string[]) => Effect.Effect<GhResult, GhError>;
+    readonly writePRCheckbox?: (opts: PRCheckboxWrite) => Effect.Effect<GhResult, GhError>;
     readonly runGhJson: <T>(args: string[]) => Effect.Effect<T, GhError>;
     readonly runGraphQL: (
       query: string,
@@ -182,13 +197,17 @@ export class GitHubService extends Context.Service<
 
               const proc = yield* executor.spawn(command);
 
-              const stdoutChunk = yield* proc.stdout.pipe(Stream.decodeText(), Stream.runCollect);
+              const [stdoutChunk, stderrChunk] = yield* Effect.all(
+                [
+                  proc.stdout.pipe(Stream.decodeText(), Stream.runCollect),
+                  proc.stderr.pipe(Stream.decodeText(), Stream.runCollect),
+                ],
+                { concurrency: "unbounded" },
+              );
               const stdout = stdoutChunk.join("");
-
-              const stderrChunk = yield* proc.stderr.pipe(Stream.decodeText(), Stream.runCollect);
               const stderr = stderrChunk.join("");
-
               const exitCode = yield* proc.exitCode;
+              yield* recordRequest(ghSubprocessEvent(args, Number(exitCode)));
 
               return {
                 stdout,
@@ -246,7 +265,7 @@ export class GitHubService extends Context.Service<
               const quotaFilter =
                 resource === undefined
                   ? '.resources | to_entries[] | "\\(.key): reset time: \\(.value.reset | todateiso8601); remaining quota: \\(.value.remaining)"'
-                  : `.resources.${resource} | "reset time: \\(.reset | todateiso8601); remaining quota: \\(.remaining)"`;
+                  : `.resources.${resource} | "resource: ${resource}; reset time: \\(.reset | todateiso8601); remaining quota: \\(.remaining)"`;
               const quota = yield* executeGh(["api", "rate_limit", "--jq", quotaFilter]).pipe(
                 Effect.orElseSucceed(() => null),
               );
@@ -320,6 +339,75 @@ export class GitHubService extends Context.Service<
           });
         };
 
+        const writePRCheckbox = Effect.fn("GitHubService.writePRCheckbox")(function* (
+          opts: PRCheckboxWrite,
+        ) {
+          const path = `repos/${opts.repo.owner}/${opts.repo.name}/pulls/${opts.pr}`;
+          const response = yield* githubApi<unknown>({ path });
+          const parsed = yield* Effect.try({
+            try: () =>
+              Schema.decodeUnknownSync(Schema.Struct({ body: Schema.NullOr(Schema.String) }))(
+                response.body,
+              ),
+            catch: (error) =>
+              new GitHubCommandError({
+                command: `GET ${path}`,
+                exitCode: 0,
+                message: `GitHub returned an invalid PR body: ${String(error)}`,
+                stderr: `GitHub returned an invalid PR body: ${String(error)}`,
+              }),
+          });
+          const body = parsed.body ?? "";
+          if (body !== opts.expectedBody) {
+            return yield* new GitHubCommandError({
+              command: "gh-tool pr checkbox",
+              exitCode: 1,
+              stderr: `PR #${opts.pr} body changed before the checkbox update`,
+              message: `Refusing to update PR #${opts.pr}: its body changed after the first read`,
+              hint: "Re-read the pull request and retry with the current task text.",
+            });
+          }
+
+          const checkboxes = findCheckboxLines(
+            body,
+            opts.selectionText[0] ?? "",
+            null,
+            bunMarkdownOutline,
+          );
+          if (
+            !checkboxes.some((checkbox) => checkbox.offset === opts.boxOffset) ||
+            body[opts.boxOffset] === opts.replacement
+          ) {
+            return yield* new GitHubCommandError({
+              command: "gh-tool pr checkbox",
+              exitCode: 1,
+              stderr: "Refusing an invalid PR checkbox position",
+              message: "Refusing to update a character that is not a task checkbox",
+            });
+          }
+
+          yield* Effect.try({
+            try: () => validateCheckboxEdit(body, opts.boxOffset, opts.replacement),
+            catch: () =>
+              new GitHubCommandError({
+                command: "gh-tool pr checkbox",
+                exitCode: 1,
+                stderr: "PR body structure is ambiguous; tick this item in the GitHub UI",
+                message: "Refusing to update the PR checkbox because its source is ambiguous",
+                hint: "PR body structure is ambiguous; tick this item in the GitHub UI.",
+              }),
+          });
+
+          const updatedBody =
+            body.slice(0, opts.boxOffset) + opts.replacement + body.slice(opts.boxOffset + 1);
+          const args = ["api", "--method", "PATCH", path, "-f", `body=${updatedBody}`];
+          const outboundText = [...args];
+          outboundText[5] = "body=[GitHub PR body]";
+          outboundText.push(...opts.selectionText);
+          yield* validateOutboundText(outboundText.join("\n"), "gh-tool pr checkbox");
+          return yield* runGhAttempt(args);
+        });
+
         const runGhJson = <T>(args: string[]) =>
           Effect.gen(function* () {
             const result = yield* runGh(args);
@@ -410,6 +498,7 @@ export class GitHubService extends Context.Service<
 
         return {
           runGh,
+          writePRCheckbox,
           runGhJson,
           runGraphQL,
           apiRequest: githubApi,

package/src/gh-tool/read/writes.ts

@@ -1,8 +1,9 @@
 import { Effect } from "effect";
+import { GitHubCommandError } from "#gh/errors";
 import { GitHubService } from "#gh/read/transport";
 import { invalidate } from "./cache";
 import type { Tag } from "./keys";
-import type { GhError } from "#gh/read/transport";
+import type { GhError, PRCheckboxWrite } from "#gh/read/transport";
 import type { GitHubApiRequest } from "#gh/read/api";
 
 const mutate = <A, R>(effect: Effect.Effect<A, GhError, R>, touched: readonly Tag[]) =>
@@ -15,6 +16,22 @@ const run = Effect.fn("writes.run")(function* (argv: string[], touched: readonly
   const gh = yield* GitHubService;
   return yield* mutate(gh.runGh(argv), touched);
 });
+const prCheckbox = Effect.fn("writes.prCheckbox")(function* (
+  opts: PRCheckboxWrite,
+  touched: readonly Tag[],
+) {
+  const gh = yield* GitHubService;
+  if (gh.writePRCheckbox === undefined) {
+    return yield* new GitHubCommandError({
+      command: "gh-tool pr checkbox",
+      exitCode: 1,
+      stderr: "PR checkbox writes are unavailable",
+      message:
+        "Refusing to update the PR checkbox because the GitHub service cannot verify the body",
+    });
+  }
+  return yield* mutate(gh.writePRCheckbox(opts), touched);
+});
 const json = <A>(argv: string[], touched: readonly Tag[]) =>
   Effect.gen(function* () {
     const gh = yield* GitHubService;
@@ -34,4 +51,4 @@ const api = <A>(request: GitHubApiRequest, touched: readonly Tag[]) =>
     const gh = yield* GitHubService;
     return yield* mutate(gh.apiRequest<A>(request), touched);
   });
-export const writes = { run, json, graphql, api };
+export const writes = { run, prCheckbox, json, graphql, api };

package/src/gh-tool/workflow.ts

@@ -298,7 +298,7 @@ const fetchAnnotations = Effect.fn("workflow.fetchAnnotations")(function* (opts:
     const parts = opts.repo.split("/");
     if (parts.length !== 2 || !parts[0] || !parts[1]) {
       return yield* new GitHubCommandError({
-        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "blogic-cz/agent-tools").`,
+        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "example-org/example-repo").`,
         command: "workflow annotations",
         exitCode: 1,
         stderr: "",
@@ -574,7 +574,7 @@ export const fetchJobLogs = Effect.fn("workflow.fetchJobLogs")(function* (
     const parts = opts.repo.split("/");
     if (parts.length !== 2 || !parts[0] || !parts[1]) {
       return yield* new GitHubCommandError({
-        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "blogic-cz/agent-tools").`,
+        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "example-org/example-repo").`,
         command: "workflow job-logs",
         exitCode: 1,
         stderr: "",