@blogic-cz/agent-tools 1.11.1 → 1.13.0

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

@@ -0,0 +1,113 @@
+import { Effect } from "effect";
+
+import { GitHubCommandError } from "#gh/errors";
+import {
+  bunMarkdownOutline,
+  findCheckboxLines,
+  validateCheckboxEdit,
+  type CheckboxOutlineParser,
+} from "#gh/pr/checkbox-markdown";
+import { repoSlug } from "#gh/read/keys";
+import { reads, resolveRepo } from "#gh/read/reads";
+import { writes } from "#gh/read/writes";
+import { validateOutboundText } from "#gh/text-input";
+
+type CheckboxState = "checked" | "unchecked";
+
+const readPRBody = Effect.fn("pr.checkbox.readPRBody")(function* (pr: number) {
+  const repo = yield* resolveRepo(null);
+  const body = yield* reads.prBody(repo, pr);
+  return { repo, body };
+});
+
+const checkboxMatchError = (pr: number, count: number) =>
+  new GitHubCommandError({
+    command: "gh-tool pr checkbox",
+    exitCode: 1,
+    stderr: `Found ${count} matching task items in PR #${pr}`,
+    message: `Expected one matching task item in PR #${pr}, found ${count}`,
+    hint: "Use --section to narrow the search or pass a longer --match.",
+  });
+
+export const togglePRCheckbox = Effect.fn("pr.togglePRCheckbox")(function* (
+  opts: {
+    pr: number;
+    match: string;
+    section: string | null;
+    state: CheckboxState;
+  },
+  parseOutline: CheckboxOutlineParser = bunMarkdownOutline,
+) {
+  yield* validateOutboundText(opts.match, "gh-tool pr checkbox");
+  if (opts.section !== null) {
+    yield* validateOutboundText(opts.section, "gh-tool pr checkbox");
+  }
+
+  if (opts.pr <= 0 || opts.match.length === 0 || opts.section === "") {
+    return yield* new GitHubCommandError({
+      command: "gh-tool pr checkbox",
+      exitCode: 1,
+      stderr: "--pr must be positive, --match must be non-empty, and --section must be non-empty",
+      message: "Invalid PR checkbox selection",
+    });
+  }
+
+  const first = yield* readPRBody(opts.pr);
+  const matches = yield* Effect.try({
+    try: () => findCheckboxLines(first.body, opts.match, opts.section, parseOutline),
+    catch: (cause) =>
+      new GitHubCommandError({
+        command: "gh-tool pr checkbox",
+        exitCode: 1,
+        stderr: String(cause),
+        message: "Cannot locate PR checkbox safely",
+        hint: "PR body structure is ambiguous; tick this item in the GitHub UI.",
+      }),
+  });
+  if (matches.length !== 1) return yield* checkboxMatchError(opts.pr, matches.length);
+
+  const selected = matches[0];
+  if (selected === undefined) return yield* checkboxMatchError(opts.pr, 0);
+
+  const alreadyRequested = opts.state === "checked" ? selected.checked : !selected.checked;
+  if (alreadyRequested) {
+    return {
+      pr: opts.pr,
+      state: "unchanged" as const,
+      before: selected.before,
+      after: selected.before,
+    };
+  }
+
+  const box = opts.state === "checked" ? "x" : " ";
+  yield* Effect.try({
+    try: () => validateCheckboxEdit(first.body, selected.offset, box, parseOutline),
+    catch: (cause) =>
+      new GitHubCommandError({
+        command: "gh-tool pr checkbox",
+        exitCode: 1,
+        stderr: String(cause),
+        message: "Cannot locate PR checkbox safely",
+        hint: "PR body structure is ambiguous; tick this item in the GitHub UI.",
+      }),
+  });
+  const after = `${selected.before.slice(0, selected.boxIndex)}${box}${selected.before.slice(selected.boxIndex + 1)}`;
+  yield* writes.prCheckbox(
+    {
+      repo: first.repo,
+      pr: opts.pr,
+      expectedBody: first.body,
+      boxOffset: selected.offset,
+      replacement: box,
+      selectionText: [opts.match, ...(opts.section === null ? [] : [opts.section])],
+    },
+    [`pr:${repoSlug(first.repo)}#${opts.pr}`, `pulls:${repoSlug(first.repo)}`],
+  );
+
+  return {
+    pr: opts.pr,
+    state: "updated" as const,
+    before: selected.before,
+    after,
+  };
+});

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

@@ -33,6 +33,7 @@ import {
 } from "#gh/config";
 
 import { mergeStack, readStack, unstackStack } from "./stack";
+import { togglePRCheckbox } from "./checkbox";
 import {
   closePR,
   collectWithStableState,
@@ -524,8 +525,15 @@ export const prStatusCommand = Command.make(
     withRepo(
       repo,
       Effect.gen(function* () {
-        const result: PRStatusResult = yield* detectPRStatus();
-        yield* logFormatted(result, format);
+        const [result, rateLimit] = yield* Effect.all([
+          detectPRStatus(),
+          reads.getPRStatusRateLimit(),
+        ]);
+        const status: PRStatusResult & { readonly rateLimit: typeof rateLimit } = {
+          ...result,
+          rateLimit,
+        };
+        yield* logFormatted(status, format);
       }),
     ),
 ).pipe(
@@ -714,6 +722,51 @@ export const prEditCommand = Command.make(
     ),
 ).pipe(Command.withDescription("Edit an existing PR's title, body, or other metadata"));
 
+export const prCheckboxCommand = Command.make(
+  "checkbox",
+  {
+    check: Flag.Boolean("check").pipe(
+      Flag.withDescription("Mark the matching task item as checked"),
+      Flag.withDefault(false),
+    ),
+    format: formatOption,
+    match: Flag.String("match").pipe(
+      Flag.withDescription("Plain text that identifies one task item"),
+    ),
+    pr: Flag.Int("pr").pipe(Flag.withDescription("PR number to update")),
+    repo: repoOption,
+    section: Flag.String("section").pipe(
+      Flag.withDescription("Limit the search to a Markdown heading"),
+      Flag.optional,
+    ),
+    uncheck: Flag.Boolean("uncheck").pipe(
+      Flag.withDescription("Mark the matching task item as unchecked"),
+      Flag.withDefault(false),
+    ),
+  },
+  ({ check, format, match, pr, repo, section, uncheck }) =>
+    withRepo(
+      repo,
+      Effect.gen(function* () {
+        if (check === uncheck) {
+          return yield* new GitHubCommandError({
+            command: "gh-tool pr checkbox",
+            exitCode: 1,
+            stderr: "Provide exactly one of --check or --uncheck",
+            message: "Provide exactly one of --check or --uncheck",
+          });
+        }
+        const result = yield* togglePRCheckbox({
+          pr,
+          match,
+          section: Option.getOrNull(section),
+          state: check ? "checked" : "unchecked",
+        });
+        yield* logFormatted(result, format);
+      }),
+    ),
+).pipe(Command.withDescription("Check or uncheck one task item in a PR body"));
+
 export const prCloseCommand = Command.make(
   "close",
   {

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

@@ -248,12 +248,12 @@ 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 it is not an error, but it is also not an empty list: a PR with green
-// checks (sabservis/nexus-be#1396) once came back empty.
+// checks (example/example-be#1396) once came back empty.
 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
+// at roughly 40 seconds), 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;

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

@@ -9,6 +9,7 @@ export {
   prDiscussionSummaryCommand,
   prDraftCommand,
   prEditCommand,
+  prCheckboxCommand,
   prFeedbackCommand,
   prIssueCommentsCommand,
   prIssueCommentsLatestCommand,

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

@@ -1,3 +1,5 @@
+import { CacheRequest, recordRequest } from "./telemetry";
+
 import { Clock, Context, Effect } from "effect";
 
 import { registerResolvedSecret } from "#shared/content-security";
@@ -24,6 +26,36 @@ export type GitHubApiResponse<T> = {
   rateLimitUsed?: string;
 };
 
+export type GitHubRateLimitHeaders = {
+  readonly resource?: string;
+  readonly limit?: number;
+  readonly used?: number;
+  readonly remaining?: number;
+  readonly reset?: number;
+};
+
+const headerInteger = (headers: Headers, name: string) => {
+  const value = headers.get(name);
+  if (value === null || !/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+};
+
+export const parseRateLimitHeaders = (headers: Headers): GitHubRateLimitHeaders => {
+  const resource = headers.get("x-ratelimit-resource");
+  const limit = headerInteger(headers, "x-ratelimit-limit");
+  const used = headerInteger(headers, "x-ratelimit-used");
+  const remaining = headerInteger(headers, "x-ratelimit-remaining");
+  const reset = headerInteger(headers, "x-ratelimit-reset");
+  return {
+    ...(resource === null ? {} : { resource }),
+    ...(limit === undefined ? {} : { limit }),
+    ...(used === undefined ? {} : { used }),
+    ...(remaining === undefined ? {} : { remaining }),
+    ...(reset === undefined ? {} : { reset }),
+  };
+};
+
 const authFailure = (message: string) =>
   new GitHubAuthError({
     message,
@@ -106,6 +138,8 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
   const token = yield* resolveGitHubToken();
   const url = `${GITHUB_API_ROOT}/${opts.path.replace(/^\//, "")}`;
 
+  const cached = yield* CacheRequest;
+  const started = new Date().toISOString();
   const response = yield* Effect.tryPromise({
     try: () =>
       fetch(url, {
@@ -128,8 +162,41 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
         retryable: true,
         hint: "Check network connectivity and VPN state, then retry.",
       }),
-  });
+  }).pipe(
+    Effect.tapError(() =>
+      recordRequest({
+        ts: started,
+        method,
+        endpoint: opts.path,
+        status: null,
+        outcome: "error",
+        resource: null,
+        used: null,
+        remaining: null,
+        reset: null,
+      }),
+    ),
+  );
 
+  const quota = parseRateLimitHeaders(response.headers);
+  yield* recordRequest({
+    ts: started,
+    method,
+    endpoint: opts.path,
+    status: response.status,
+    outcome:
+      response.status === 304
+        ? "304"
+        : response.status >= 400
+          ? "error"
+          : cached
+            ? "200"
+            : "bypass",
+    resource: quota.resource ?? null,
+    used: quota.used ?? null,
+    remaining: quota.remaining ?? null,
+    reset: quota.reset ?? null,
+  });
   const text = yield* Effect.tryPromise({
     try: () => response.text(),
     catch: (cause) =>
@@ -176,7 +243,8 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
   }
 
   const now = yield* Clock.currentTimeMillis;
-  const resetSeconds = Number(response.headers.get("x-ratelimit-reset"));
+  const rateLimitHeaders = parseRateLimitHeaders(response.headers);
+  const resetSeconds = rateLimitHeaders.reset ?? Number.NaN;
   const resetDelay =
     Number.isFinite(resetSeconds) && resetSeconds > 0
       ? Math.max(0, resetSeconds * 1000 - now + 1000)
@@ -200,18 +268,17 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
         /rate limit|secondary rate limit|abuse detection/i.test(
           apiErrorMessage(parsed, response.status),
         )));
-
   const error = new GitHubCommandError({
     message: rateLimit
-      ? `${apiErrorMessage(parsed, response.status)}; reset time: ${resetDelay === undefined ? "unavailable" : new Date(resetSeconds * 1000).toISOString()}; remaining quota: ${response.headers.get("x-ratelimit-remaining") ?? "unavailable"}`
+      ? `${apiErrorMessage(parsed, response.status)}; resource: ${rateLimitHeaders.resource ?? "unavailable"}; reset time: ${rateLimitHeaders.reset === undefined ? "unavailable" : new Date(resetSeconds * 1000).toISOString()}; remaining quota: ${rateLimitHeaders.remaining ?? "unavailable"}`
       : apiErrorMessage(parsed, response.status),
     command: `${method} ${opts.path}`,
     exitCode: response.status,
     stderr: text,
     ...(rateLimit
       ? {
-          hint: "Wait for the reset before retrying. Check the remaining quota once with the shown command; it does not consume the quota.",
-          nextCommand: "gh api rate_limit",
+          hint: "Wait for the reset before retrying. Check the named resource with the shown command; the lookup does not consume quota.",
+          nextCommand: "gh-tool rate-limit",
         }
       : {}),
     ...(response.status >= 500 || (rateLimit && canWait) ? { retryable: true } : {}),

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

@@ -1,3 +1,4 @@
+import { CacheRequest, cacheEvent, recordRequest } from "./telemetry";
 import { Console, Context, Effect } from "effect";
 import { resolveGitHubToken, SessionCredential } from "#gh/read/api";
 import { GitHubCommandError } from "#gh/errors";
@@ -86,16 +87,23 @@ export const cachedRead = <A, E, R>(opts: {
       ),
     );
     if (prepared === null) return yield* direct();
-    if (prepared.kind === "hit") return prepared.value;
+    if (prepared.kind === "hit") {
+      yield* recordRequest(cacheEvent(opts.key.op));
+      return prepared.value;
+    }
     return yield* Effect.gen(function* () {
       yield* safe(session, () => store.record(opts.key.op, "fetch"));
       const previousValid =
         prepared.previous === null
           ? false
           : yield* safe(session, () => store.canServeStale(prepared));
-      const fetched = yield* opts.fetch(
-        prepared.previous === null ? null : { ...prepared.previous, valid: previousValid === true },
-      );
+      const fetched = yield* opts
+        .fetch(
+          prepared.previous === null
+            ? null
+            : { ...prepared.previous, valid: previousValid === true },
+        )
+        .pipe(Effect.provideService(CacheRequest, true));
       if (fetched.kind === "unchanged") {
         if (prepared.previous === null)
           return yield* Effect.die(new Error("304 without a cached value"));
@@ -131,6 +139,7 @@ export const cachedRead = <A, E, R>(opts: {
             session.staleWarned = true;
             yield* Console.error(`gh-tool: served cached ${opts.key.op} (rate limited)`);
           }
+          yield* recordRequest(cacheEvent(opts.key.op));
           yield* safe(session, () => store.record(opts.key.op, "stale"));
           return prepared.previous.value;
         }),

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

@@ -2,7 +2,23 @@ import { Effect, Option } from "effect";
 import { Command, Flag } from "effect/cli";
 import { formatOption, logFormatted } from "#shared";
 import { cacheStats, clearCache } from "./cache";
-import { resolveRepo } from "./reads";
+import { getRateLimit, resolveRepo } from "./reads";
+
+export const rateLimitCommand = Command.make(
+  "rate-limit",
+  {
+    resource: Flag.String("resource").pipe(
+      Flag.withDescription("Show one GitHub rate-limit resource"),
+      Flag.optional,
+    ),
+    format: formatOption,
+  },
+  ({ resource, format }) =>
+    Effect.gen(function* () {
+      const summary = yield* getRateLimit(Option.getOrUndefined(resource));
+      yield* logFormatted(summary, format);
+    }),
+).pipe(Command.withDescription("Show GitHub API rate-limit resources and reset times"));
 
 const stats = Command.make("stats", { format: formatOption }, ({ format }) =>
   Effect.gen(function* () {

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

@@ -101,6 +101,25 @@ export const prHead = Effect.fn("reads.prHead")(function* (
   return { headSha: head.head.sha, baseSha: head.base.sha, signature: snapshotDigest(snapshot) };
 });
 
+const PRBody = Schema.Struct({ body: Schema.NullOr(Schema.String) });
+
+export const prBody = Effect.fn("reads.prBody")(function* (repo: RepoRef, pr: number) {
+  const gh = yield* GitHubService;
+  const path = `repos/${repoSlug(repo)}/pulls/${pr}`;
+  const response = yield* gh.apiRequest<unknown>({ path });
+  const parsed = yield* Effect.try({
+    try: () => Schema.decodeUnknownSync(PRBody)(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)}`,
+      }),
+  });
+  return parsed.body ?? "";
+});
+
 export const checkSignal = Effect.fn("reads.checkSignal")(function* (repo: RepoRef, sha: string) {
   const snapshot = yield* restSnapshot({ op: "checkSignal", repo, sha }, [
     {

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

@@ -1,4 +1,4 @@
-import { Effect, Schema } from "effect";
+import { Clock, Effect, Result, Schema } from "effect";
 import { GitHubService } from "#gh/read/transport";
 import { GitHubCommandError } from "#gh/errors";
 import type { CheckRunAnnotation } from "#gh/types";
@@ -6,7 +6,7 @@ import { cachedRead, ReadCache } from "./cache";
 import { OPS } from "./classes";
 import { repoSlug } from "./keys";
 import { issueView, issueList, issueComments } from "./issues";
-import { prView, prList, prChecks, prHead, checkSignal } from "./pulls";
+import { prView, prList, prChecks, prHead, prBody, checkSignal } from "./pulls";
 import { prComments, prReviews, reviewThreads, lastHumanReviewer } from "./reviews";
 import { reviewGuards } from "./review-guards";
 import type { RepoRef, RunFilter } from "./keys";
@@ -21,6 +21,87 @@ import {
 
 export type JobRef = { readonly id: number; readonly status: string };
 
+const RateLimitResponse = Schema.Struct({
+  resources: Schema.Record(
+    Schema.String,
+    Schema.Struct({
+      limit: Schema.Int,
+      used: Schema.Int,
+      remaining: Schema.Int,
+      reset: Schema.Int,
+    }),
+  ),
+});
+
+export type RateLimitResource = {
+  readonly limit: number;
+  readonly used: number;
+  readonly remaining: number;
+  readonly reset: string;
+  readonly secondsUntilReset: number;
+};
+
+export type RateLimitSummary = Readonly<Record<string, RateLimitResource>>;
+export type PRStatusRateLimit =
+  | Readonly<{ core: RateLimitResource; graphql: RateLimitResource }>
+  | Readonly<{ error: string }>;
+
+export const getRateLimit = Effect.fn("reads.getRateLimit")(function* (resource?: string) {
+  const gh = yield* GitHubService;
+  const response = yield* gh.runGhJson<unknown>(["api", "rate_limit"]);
+  const parsed = yield* Effect.try({
+    try: () => parsePreserving(RateLimitResponse)(response),
+    catch: (cause) =>
+      new GitHubCommandError({
+        message: `GitHub rate-limit response was invalid: ${String(cause)}`,
+        command: "gh-tool rate-limit",
+        exitCode: 1,
+        stderr: String(cause),
+      }),
+  });
+  const names = Object.keys(parsed.resources).toSorted();
+  const now = (yield* Clock.currentTimeMillis) / 1000;
+  const selected = resource === undefined ? names : [resource];
+  const entries: Array<[string, RateLimitResource]> = [];
+  for (const name of selected) {
+    const bucket = parsed.resources[name];
+    if (bucket === undefined) {
+      return yield* new GitHubCommandError({
+        message: `Unknown rate-limit resource '${name}'. Available resources: ${names.join(", ")}`,
+        command: "gh-tool rate-limit",
+        exitCode: 1,
+        stderr: "",
+        hint: "Select a resource returned by GitHub, or omit --resource to show all resources.",
+      });
+    }
+    entries.push([
+      name,
+      {
+        limit: bucket.limit,
+        used: bucket.used,
+        remaining: bucket.remaining,
+        reset: new Date(bucket.reset * 1000).toISOString(),
+        secondsUntilReset: Math.max(0, Math.ceil(bucket.reset - now)),
+      },
+    ]);
+  }
+  return Object.fromEntries(entries) satisfies RateLimitSummary;
+});
+
+export const getPRStatusRateLimit = Effect.fn("reads.getPRStatusRateLimit")(function* () {
+  const result = yield* getRateLimit().pipe(Effect.result);
+  if (Result.isFailure(result))
+    return { error: result.failure.message } satisfies PRStatusRateLimit;
+
+  const { core, graphql } = result.success;
+  if (core === undefined || graphql === undefined) {
+    return {
+      error: "GitHub rate-limit response omitted the core or graphql resource.",
+    } satisfies PRStatusRateLimit;
+  }
+  return { core, graphql } satisfies PRStatusRateLimit;
+});
+
 const completedAttemptJobs = Effect.fn("reads.completedAttemptJobs")(function* (
   repo: RepoRef,
   runId: number,
@@ -282,6 +363,8 @@ const jobIdentity = Effect.fn("reads.jobIdentity")(function* (repo: RepoRef, job
 });
 
 export const reads = {
+  getRateLimit,
+  getPRStatusRateLimit,
   completedAttemptJobs,
   jobIdentity,
   reviewGuards,
@@ -293,6 +376,7 @@ export const reads = {
   prList,
   prChecks,
   prHead,
+  prBody,
   checkSignal,
   runList,
   runView,

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

@@ -0,0 +1,45 @@
+import { Effect } from "effect";
+import { Command, Flag } from "effect/cli";
+import { formatOption, logFormatted } from "#shared";
+import { GitHubCommandError } from "#gh/errors";
+import { getRateLimit } from "./reads";
+import { summarizeRequests, Telemetry } from "./telemetry";
+
+export const telemetryCommand = Command.make(
+  "telemetry",
+  {
+    hours: Flag.Int("hours").pipe(
+      Flag.withDefault(1),
+      Flag.withDescription("Report window in hours, up to 168"),
+    ),
+    format: formatOption,
+  },
+  ({ hours, format }) =>
+    Effect.gen(function* () {
+      const store = yield* Telemetry;
+      const report = yield* Effect.try({
+        try: () => {
+          if (!Number.isFinite(hours) || hours <= 0 || hours > 168)
+            throw new Error("hours must be greater than 0 and at most 168");
+          if (store === null) throw new Error("Telemetry database unavailable");
+          const since = new Date(Date.now() - hours * 3600000).toISOString();
+          return { since, ...summarizeRequests(store.read(since)) };
+        },
+        catch: (error) =>
+          new GitHubCommandError({
+            message: String(error),
+            command: "gh-tool telemetry",
+            exitCode: 1,
+            stderr: String(error),
+          }),
+      });
+      const current = yield* getRateLimit().pipe(
+        Effect.catch((error) => Effect.succeed({ error: error.message })),
+      );
+      yield* logFormatted({ ...report, current }, format);
+    }),
+).pipe(
+  Command.withDescription(
+    "Report direct HTTP requests, gh subprocess calls, ReadCache hits and estimated external quota use",
+  ),
+);

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

@@ -0,0 +1,85 @@
+import { Database } from "bun:sqlite";
+
+import { redactSensitiveText } from "#shared/content-security";
+import type { RequestEvent, RequestRow, TelemetryStore } from "./telemetry";
+
+const telemetryCommand = (args: readonly string[]): string => {
+  const commandGroups = new Set([
+    "pr",
+    "issue",
+    "repo",
+    "label",
+    "branch",
+    "workflow",
+    "release",
+    "gist",
+    "cache",
+  ]);
+  const pathLength = commandGroups.has(args[0]) ? 2 : 1;
+  const path = args.slice(0, pathLength).filter((arg) => !arg.startsWith("-"));
+  if (path.join(" ") === "pr stack" && args[2] && !args[2].startsWith("-")) {
+    path.push(args[2]);
+  }
+  const flags: string[] = [];
+
+  for (const arg of args.slice(path.length)) {
+    if (arg === "--") break;
+    if (arg.startsWith("-")) flags.push(arg.split("=", 1)[0]);
+  }
+
+  return [...path, ...flags.toSorted()].join(" ");
+};
+
+export const openRequestTelemetry = (dbPath: string): TelemetryStore => {
+  const db = new Database(dbPath, { create: true, strict: true });
+  try {
+    db.run("PRAGMA busy_timeout=0");
+    db.run(`CREATE TABLE IF NOT EXISTS github_requests (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT NOT NULL, invocation TEXT NOT NULL,
+      command TEXT NOT NULL, method TEXT NOT NULL, endpoint TEXT NOT NULL,
+      status INTEGER, outcome TEXT NOT NULL, resource TEXT, used INTEGER,
+      remaining INTEGER, reset INTEGER
+    ) STRICT`);
+    db.run("CREATE INDEX IF NOT EXISTS idx_github_requests_ts ON github_requests(ts)");
+    db.run(
+      "DELETE FROM github_requests WHERE ts < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-7 days')",
+    );
+  } catch (error) {
+    db.close(false);
+    throw error;
+  }
+  const invocation = crypto.randomUUID();
+  const command = telemetryCommand(process.argv.slice(2));
+  return {
+    record: (event: RequestEvent) => {
+      try {
+        db.run(
+          `INSERT INTO github_requests
+          (ts, invocation, command, method, endpoint, status, outcome, resource, used, remaining, reset)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          [
+            event.ts,
+            invocation,
+            redactSensitiveText(command),
+            event.method,
+            event.endpoint,
+            event.status,
+            event.outcome,
+            event.resource,
+            event.used,
+            event.remaining,
+            event.reset,
+          ],
+        );
+      } catch {
+        /* Never wait for a writer or change command behavior. */
+      }
+    },
+    read: (since) =>
+      db
+        .query<RequestRow, [string]>("SELECT * FROM github_requests WHERE ts >= ? ORDER BY ts, id")
+        .all(since)
+        .map((row) => Object.assign(row, { command: redactSensitiveText(row.command) })),
+    close: () => db.close(false),
+  };
+};