@blogic-cz/agent-tools 1.7.5 → 1.9.0

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

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+
+export const resolveTarget = <A extends { number: number }, E, R>(
+  pr: number | null,
+  current: Effect.Effect<A, E, R>,
+) => (pr === null ? current.pipe(Effect.map((value) => value.number)) : Effect.succeed(pr));
+
+export const stableHead = <S, A, E1, R1, E2, R2>(
+  initial: S,
+  collect: (state: S) => Effect.Effect<A, E1, R1>,
+  refresh: (state: S) => Effect.Effect<S, E2, R2>,
+  unchanged: (before: S, after: S) => boolean,
+): Effect.Effect<{ state: S; value: A } | null, E1 | E2, R1 | R2> =>
+  Effect.gen(function* () {
+    let before = initial;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const value = yield* collect(before);
+      const after = yield* refresh(before);
+      if (unchanged(before, after)) return { state: after, value };
+      before = after;
+    }
+    return null;
+  });

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

@@ -1,73 +1 @@
-import { Effect } from "effect";
-
-import { GitHubService } from "#gh/service";
-
-import type { StackMember, StackView } from "#gh/types";
-
-type StacksListResponse = Array<{ number: number }>;
-
-type StackResponse = {
-  number: number;
-  base: { ref: string };
-  open: boolean;
-  pull_requests: Array<{
-    number: number;
-    title: string;
-    state: "open" | "closed";
-    merged_at: string | null;
-    draft: boolean;
-    html_url: string;
-    head: { ref: string };
-    base: { ref: string };
-  }>;
-};
-
-export const readStack = Effect.fn("pr.readStack")(function* (opts: { pr: number }) {
-  const gh = yield* GitHubService;
-  const repo = yield* gh.getRepoInfo();
-  const base = `repos/${repo.owner}/${repo.name}`;
-
-  const unstacked: StackView = {
-    pr: opts.pr,
-    isStacked: false,
-    stackNumber: null,
-    baseRef: null,
-    members: [],
-  };
-
-  // A 404 is the repository having no stacks surface at all, which reads the same as a PR
-  // that belongs to no stack. Every caller gets that reading from here, not its own.
-  const stacks = yield* gh
-    .apiRequest<StacksListResponse>({ path: `${base}/stacks?pull_request=${opts.pr}` })
-    .pipe(Effect.catchTag("GitHubNotFoundError", () => Effect.succeed(null)));
-
-  if (stacks === null) {
-    return unstacked;
-  }
-
-  const stackNumber = stacks.body?.[0]?.number;
-  if (stackNumber === undefined) {
-    return unstacked;
-  }
-
-  const stack = yield* gh.apiRequest<StackResponse>({ path: `${base}/stacks/${stackNumber}` });
-
-  const members: StackMember[] = stack.body.pull_requests.map((member, index) => ({
-    position: index + 1,
-    number: member.number,
-    title: member.title,
-    headRefName: member.head.ref,
-    baseRefName: member.base.ref,
-    state: member.merged_at === null ? member.state : "merged",
-    isDraft: member.draft,
-    url: member.html_url,
-  }));
-
-  return {
-    pr: opts.pr,
-    isStacked: true,
-    stackNumber: stack.body.number,
-    baseRef: stack.body.base.ref,
-    members,
-  } satisfies StackView;
-});
+export { readStack } from "#gh/read/stacks";

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

@@ -1,7 +1,11 @@
 import { Effect } from "effect";
 
-import { pollUntilResolved } from "#shared/poll-until-resolved";
-import { GitHubService } from "#gh/service";
+import { waits } from "#gh/read/waits";
+import { GitHubService } from "#gh/read/transport";
+import { writes } from "#gh/read/writes";
+import { repoSlug } from "#gh/read/keys";
+import { passthrough } from "#gh/read/catalog";
+import type { AsyncMergeResult } from "#gh/read/catalog";
 import { GitHubMergeError } from "#gh/errors";
 
 import type { MergeStrategy, StackMember, StackMergeBlocker, StackMergeResult } from "#gh/types";
@@ -11,21 +15,9 @@ 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 POLL_INTERVAL_MS = 5000;
 const MAX_WAIT_SECONDS = 300;
 
 const stackMergeFailure = (opts: {
@@ -164,12 +156,15 @@ export const mergeStack = Effect.fn("pr.mergeStack")(function* (opts: {
 
   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],
-  });
+  const requested = yield* writes.api<AsyncMergeResult>(
+    {
+      path: asyncPath,
+      method: "PUT",
+      body: { merge_method: opts.strategy, merge_action: "direct_merge" },
+      alsoAcceptStatus: [202, 409],
+    },
+    [`repo:${repoSlug(repo)}`],
+  );
 
   // 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.
@@ -188,16 +183,19 @@ export const mergeStack = Effect.fn("pr.mergeStack")(function* (opts: {
   }
 
   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,
-    });
+    const outcome = yield* waits.until(
+      passthrough
+        .stackMergeStatus(`${asyncPath}/${uuid}`)
+        .pipe(Effect.map((response) => response.body)),
+      (value) => value.status !== "pending",
+      {
+        initial: { value: latest },
+        intervalMs: POLL_INTERVAL_MS,
+        timeoutMs: MAX_WAIT_SECONDS * 1000,
+        readAtDeadline: true,
+      },
+    );
+    latest = outcome.kind === "done" ? outcome.value : outcome.last;
   }
 
   if (latest.status === "merged") {
@@ -269,11 +267,14 @@ export const unstackStack = Effect.fn("pr.unstackStack")(function* (opts: {
 
   // 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],
-  });
+  const result = yield* writes.api<unknown>(
+    {
+      path: `repos/${repo.owner}/${repo.name}/stacks/${view.stackNumber}/unstack`,
+      method: "POST",
+      alsoAcceptStatus: [204],
+    },
+    [`repo:${repoSlug(repo)}`],
+  );
 
   return {
     ...plan,

package/src/gh-tool/{api.ts → read/api.ts}

@@ -1,11 +1,12 @@
-import { Clock, Effect } from "effect";
+import { Clock, Context, Effect } from "effect";
 
+import { registerResolvedSecret } from "#shared/content-security";
 import { retryTransient } from "#shared/retry-transient";
 
-import { GitHubAuthError, GitHubCommandError, GitHubNotFoundError } from "./errors";
-import type { GitHubApiError } from "./errors";
-import { ghEnvironment } from "./environment";
-import { validateOutboundText } from "./text-input";
+import { GitHubAuthError, GitHubCommandError, GitHubNotFoundError } from "#gh/errors";
+import type { GitHubApiError } from "#gh/errors";
+import { ghEnvironment } from "#gh/environment";
+import { validateOutboundText } from "#gh/text-input";
 
 // Direct HTTP, not `gh api`: the CLI collapses every failure into a non-zero exit and
 // loses the status code, but merge-async answers 202 (accepted), 200 (already merged or
@@ -17,6 +18,10 @@ const GITHUB_API_VERSION = "2022-11-28";
 export type GitHubApiResponse<T> = {
   status: number;
   body: T;
+  etag?: string;
+  link?: string;
+  rateLimitResource?: string;
+  rateLimitUsed?: string;
 };
 
 const authFailure = (message: string) =>
@@ -29,7 +34,16 @@ const authFailure = (message: string) =>
 // Environment first, GH_TOKEN before GITHUB_TOKEN to match the gh CLI: the active gh
 // account is directory-scoped global state and the shell exports the matching token.
 // `gh auth token` only covers shells that export none.
+export const SessionCredential = Context.Reference<string | null>(
+  "@agent-tools/SessionCredential",
+  {
+    defaultValue: () => null,
+  },
+);
+
 export const resolveGitHubToken = Effect.fn("gh.resolveGitHubToken")(function* () {
+  const pinned = yield* SessionCredential;
+  if (pinned !== null) return pinned;
   const fromEnv = [process.env["GH_TOKEN"], process.env["GITHUB_TOKEN"]].find(
     (candidate) => candidate !== undefined && candidate.length > 0,
   );
@@ -57,6 +71,7 @@ export const resolveGitHubToken = Effect.fn("gh.resolveGitHubToken")(function* (
     return yield* authFailure("No GitHub token available.");
   }
 
+  registerResolvedSecret(token);
   return token;
 });
 
@@ -65,6 +80,7 @@ export type GitHubApiRequest = {
   method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
   body?: unknown;
   alsoAcceptStatus?: number[];
+  ifNoneMatch?: string;
 };
 
 const MAX_API_RETRIES = 2;
@@ -98,6 +114,7 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
           Accept: GITHUB_ACCEPT,
           Authorization: `Bearer ${token}`,
           "X-GitHub-Api-Version": GITHUB_API_VERSION,
+          ...(opts.ifNoneMatch === undefined ? {} : { "If-None-Match": opts.ifNoneMatch }),
           ...(serializedBody === undefined ? {} : { "Content-Type": "application/json" }),
         },
         ...(serializedBody === undefined ? {} : { body: serializedBody }),
@@ -126,9 +143,23 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
   });
   const parsed: unknown = text.length === 0 ? null : safeJsonParse(text);
 
-  const accepted = new Set([200, ...(opts.alsoAcceptStatus ?? [])]);
+  const accepted = new Set([
+    200,
+    ...(opts.alsoAcceptStatus ?? []),
+    ...(method === "GET" && opts.ifNoneMatch !== undefined ? [304] : []),
+  ]);
   if (accepted.has(response.status)) {
-    return { status: response.status, body: parsed as T };
+    const metadata = {
+      etag: response.headers.get("etag"),
+      link: response.headers.get("link"),
+      rateLimitResource: response.headers.get("x-ratelimit-resource"),
+      rateLimitUsed: response.headers.get("x-ratelimit-used"),
+    };
+    return {
+      status: response.status,
+      body: parsed as T,
+      ...Object.fromEntries(Object.entries(metadata).filter(([, value]) => value !== null)),
+    };
   }
 
   if (response.status === 401) {
@@ -193,10 +224,12 @@ export const githubApi = <T>(
         const path = opts.path;
         const method = opts.method ?? "GET";
         const alsoAcceptStatus = opts.alsoAcceptStatus;
+        const ifNoneMatch = opts.ifNoneMatch;
         const request = {
           path,
           method,
           ...(alsoAcceptStatus === undefined ? {} : { alsoAcceptStatus: [...alsoAcceptStatus] }),
+          ...(ifNoneMatch === undefined ? {} : { ifNoneMatch }),
         };
         const body = opts.body;
         if (body === undefined) return { request, serialized: undefined, decoded: "" };

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

@@ -0,0 +1,192 @@
+import { Console, Context, Effect } from "effect";
+import { resolveGitHubToken, SessionCredential } from "#gh/read/api";
+import { GitHubCommandError } from "#gh/errors";
+import { digest } from "./keys";
+import type { ReadKey, RepoRef, Tag } from "./keys";
+import type { CacheClass } from "./classes";
+import { FileStore } from "./store";
+import type { ReadFence } from "./store";
+
+type CacheSession = { store: FileStore | null; warned: boolean; staleWarned?: boolean };
+export const ReadCache = Context.Reference<CacheSession | null>("@agent-tools/ReadCache", {
+  defaultValue: () => null,
+});
+
+const disable = (session: CacheSession, error: unknown) =>
+  Effect.gen(function* () {
+    session.store = null;
+    if (session.warned) return;
+    session.warned = true;
+    yield* Console.error(
+      `gh-tool: cache off (${error instanceof Error ? error.message : String(error)})`,
+    );
+  });
+const safe = <A>(session: CacheSession, io: () => Promise<A>) =>
+  Effect.tryPromise({ try: io, catch: (error) => error }).pipe(
+    Effect.catch((error) => disable(session, error).pipe(Effect.as(null))),
+  );
+
+export const withReadCache = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.gen(function* () {
+    if (process.env["GH_TOOL_CACHE"] === "off") return yield* effect;
+    const token = yield* resolveGitHubToken().pipe(Effect.orElseSucceed(() => null));
+    if (token === null) return yield* effect;
+    const session: CacheSession = { store: null, warned: false };
+    session.store = yield* safe(session, () => FileStore.open(digest(token)));
+    return yield* effect.pipe(
+      Effect.provideService(ReadCache, session),
+      Effect.provideService(SessionCredential, token),
+    );
+  });
+
+export type Fetched<A> =
+  | { readonly kind: "fresh"; readonly value: A; readonly etag?: string }
+  | { readonly kind: "unchanged" };
+export const cachedRead = <A, E, R>(opts: {
+  readonly key: ReadKey;
+  readonly policy: CacheClass;
+  readonly decode: (value: unknown) => A;
+  readonly fetch: (
+    previous: { value: A; etag?: string; valid: boolean } | null,
+  ) => Effect.Effect<Fetched<A>, E, R>;
+  readonly immutableWhen?: (value: A) => boolean;
+  readonly policyForValue?: (value: A) => CacheClass;
+  readonly consistency?: "cached" | "origin";
+  readonly validateOrigin?: boolean;
+  readonly cacheableWhen?: (value: A) => boolean;
+}): Effect.Effect<A, E, R> =>
+  Effect.gen(function* () {
+    const session = yield* ReadCache;
+    const store = session?.store;
+    const direct = () =>
+      opts
+        .fetch(null)
+        .pipe(
+          Effect.flatMap((fetched) =>
+            fetched.kind === "fresh"
+              ? Effect.succeed(fetched.value)
+              : Effect.die(new Error("304 without a cached value")),
+          ),
+        );
+    if (
+      session === null ||
+      store === null ||
+      store === undefined ||
+      opts.policy.kind === "passthrough" ||
+      (opts.consistency === "origin" && opts.validateOrigin !== true)
+    )
+      return yield* direct();
+    const prepared = yield* safe(session, () =>
+      store.prepare(
+        opts.key,
+        opts.policy,
+        opts.decode,
+        opts.policyForValue,
+        opts.consistency === "origin",
+      ),
+    );
+    if (prepared === null) return yield* direct();
+    if (prepared.kind === "hit") 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 },
+      );
+      if (fetched.kind === "unchanged") {
+        if (prepared.previous === null)
+          return yield* Effect.die(new Error("304 without a cached value"));
+        const previous = prepared.previous;
+        yield* safe(session, () => store.record(opts.key.op, "notModified"));
+        yield* safe(session, () =>
+          store.put(prepared, previous.value, previous.immutable, previous.etag),
+        );
+        return previous.value;
+      }
+      if (opts.cacheableWhen?.(fetched.value) !== false)
+        yield* safe(session, () =>
+          store.put(
+            prepared,
+            fetched.value,
+            opts.immutableWhen?.(fetched.value) ?? opts.policy.kind === "immutable",
+            fetched.etag,
+          ),
+        );
+      return fetched.value;
+    }).pipe(
+      Effect.catch((error) =>
+        Effect.gen(function* () {
+          const rateLimited =
+            error instanceof GitHubCommandError &&
+            (error.exitCode === 429 ||
+              /rate limit|abuse detection/i.test(`${error.message}\n${error.stderr}`));
+          if (opts.consistency === "origin" || !rateLimited || prepared.previous === null)
+            return yield* Effect.fail(error);
+          const valid = yield* safe(session, () => store.canServeStale(prepared));
+          if (valid !== true) return yield* Effect.fail(error);
+          if (!session.staleWarned) {
+            session.staleWarned = true;
+            yield* Console.error(`gh-tool: served cached ${opts.key.op} (rate limited)`);
+          }
+          yield* safe(session, () => store.record(opts.key.op, "stale"));
+          return prepared.previous.value;
+        }),
+      ),
+      Effect.ensuring(safe(session, () => store.release(prepared.key, prepared.owner))),
+    );
+  });
+
+export const readFence = Effect.gen(function* () {
+  const session = yield* ReadCache;
+  if (session === null || session.store === null) return null;
+  const store = session.store;
+  return yield* safe(session, () => store.readClock());
+});
+
+export const seedRead = <A>(key: ReadKey, value: A, clock: ReadFence | null) =>
+  Effect.gen(function* () {
+    const session = yield* ReadCache;
+    if (session === null || session.store === null || clock === null) return;
+    const store = session.store;
+    yield* safe(session, async () => {
+      const prepared = await store.prepare(
+        key,
+        { kind: "passthrough" },
+        (raw) => raw,
+        undefined,
+        true,
+      );
+      if (prepared.kind !== "fetch") return;
+      try {
+        await store.put({ ...prepared, startedAtClock: clock }, value, false);
+      } finally {
+        await store.release(prepared.key, prepared.owner);
+      }
+    });
+  });
+
+export const invalidate = (tags: readonly Tag[]) =>
+  Effect.gen(function* () {
+    const session = yield* ReadCache;
+    const store = session?.store;
+    if (session !== null && store !== null && store !== undefined)
+      yield* safe(session, () => store.bump(tags));
+  });
+
+export const cacheStats = Effect.gen(function* () {
+  const session = yield* ReadCache;
+  const store = session?.store;
+  if (session === null || store === null || store === undefined) return {};
+  return (yield* safe(session, () => store.stats())) ?? {};
+});
+
+export const clearCache = (repo: RepoRef | null) =>
+  Effect.gen(function* () {
+    const session = yield* ReadCache;
+    const store = session?.store;
+    if (session === null || store === null || store === undefined) return false;
+    return (yield* safe(session, () => store.clear(repo))) !== null;
+  });