@blogic-cz/agent-tools 1.7.5 → 1.8.0

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

@@ -0,0 +1,310 @@
+import { Effect } from "effect";
+import { GitHubService } from "#gh/read/transport";
+import { GitHubCommandError } from "#gh/errors";
+
+type OrgRepo = {
+  name: string;
+  description: string | null;
+  visibility: string;
+  updatedAt: string;
+  url: string;
+  isArchived: boolean;
+};
+
+type CodeSearchResponse = {
+  items: Array<{
+    repository: {
+      full_name: string;
+    };
+    path: string;
+    html_url: string;
+  }>;
+};
+
+// ---------------------------------------------------------------------------
+// Internal handlers
+// ---------------------------------------------------------------------------
+
+export const listOrgRepos = Effect.fn("repo.listOrgRepos")(function* (opts: {
+  org: string;
+  limit: number;
+  visibility: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = [
+    "repo",
+    "list",
+    opts.org,
+    "--json",
+    "name,description,visibility,updatedAt,url,isArchived",
+    "--limit",
+    String(opts.limit),
+  ];
+
+  if (opts.visibility !== null) {
+    args.push("--visibility", opts.visibility);
+  }
+
+  return yield* gh.runGhJson<OrgRepo[]>(args);
+});
+
+export const searchOrgCode = Effect.fn("repo.searchOrgCode")(function* (opts: {
+  org: string;
+  query: string;
+  limit: number;
+}) {
+  const gh = yield* GitHubService;
+
+  const trimmedQuery = opts.query.trim();
+  if (trimmedQuery.length === 0) {
+    return yield* new GitHubCommandError({
+      message: "Search query cannot be empty",
+      command: "repo search-code",
+      exitCode: 1,
+      stderr: "Search query cannot be empty",
+    });
+  }
+
+  const searchQuery = encodeURIComponent(`${trimmedQuery} org:${opts.org}`);
+  const args = ["api", `/search/code?q=${searchQuery}&per_page=${opts.limit}`];
+
+  const response = yield* gh.runGhJson<CodeSearchResponse>(args);
+
+  return response.items.map((item) => ({
+    repo: item.repository.full_name,
+    path: item.path,
+    url: item.html_url,
+  }));
+});
+
+export type ReleaseListItem = {
+  tagName: string;
+  name: string;
+  isDraft: boolean;
+  isPrerelease: boolean;
+  createdAt: string;
+  publishedAt: string | null;
+};
+
+export type ReleaseAuthor = {
+  login: string;
+};
+
+export type ReleaseAsset = {
+  name: string;
+  size: number;
+  downloadCount: number;
+  contentType: string;
+  createdAt: string;
+  updatedAt: string;
+  url: string;
+};
+
+export type ReleaseDetail = {
+  tagName: string;
+  name: string;
+  isDraft: boolean;
+  isPrerelease: boolean;
+  createdAt: string;
+  publishedAt: string | null;
+  url: string;
+  body: string;
+  targetCommitish: string;
+  author: ReleaseAuthor | null;
+  assets: ReleaseAsset[];
+};
+
+export type ReleaseCreateResult = {
+  created: true;
+  tagName: string;
+  name: string;
+  url: string;
+  isDraft: boolean;
+  isPrerelease: boolean;
+};
+
+export type ReleaseEditResult = {
+  edited: true;
+  tagName: string;
+  name: string;
+  url: string;
+  isDraft: boolean;
+  isPrerelease: boolean;
+};
+
+export type ReleaseDeleteResult = {
+  deleted: boolean;
+  tagName: string;
+  tagCleaned: boolean;
+  dryRun?: true;
+  message?: string;
+};
+
+export type LatestRelease = {
+  tagName: string;
+  name: string;
+  createdAt: string;
+  publishedAt: string | null;
+  isLatest: boolean;
+};
+
+export type ReleaseStatusResult = {
+  latestRelease: LatestRelease | null;
+  repo: {
+    owner: string;
+    name: string;
+    defaultBranch: string;
+    url: string;
+  };
+};
+
+export const listReleases = Effect.fn("release.listReleases")(function* (opts: {
+  limit: number;
+  repo: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = [
+    "release",
+    "list",
+    "--json",
+    "tagName,name,isDraft,isPrerelease,createdAt,publishedAt",
+    "--limit",
+    String(opts.limit),
+  ];
+
+  if (opts.repo !== null) {
+    args.push("--repo", opts.repo);
+  }
+
+  return yield* gh.runGhJson<ReleaseListItem[]>(args);
+});
+
+export const viewRelease = Effect.fn("release.viewRelease")(function* (opts: {
+  tag: string;
+  repo: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = [
+    "release",
+    "view",
+    opts.tag,
+    "--json",
+    "tagName,name,isDraft,isPrerelease,createdAt,publishedAt,url,body,targetCommitish,author,assets",
+  ];
+
+  if (opts.repo !== null) {
+    args.push("--repo", opts.repo);
+  }
+
+  return yield* gh.runGhJson<ReleaseDetail>(args);
+});
+
+export const releaseStatus = Effect.fn("release.releaseStatus")(function* (repo: string | null) {
+  const gh = yield* GitHubService;
+
+  const args = [
+    "release",
+    "list",
+    "--json",
+    "tagName,name,createdAt,publishedAt,isLatest",
+    "--limit",
+    "1",
+  ];
+  if (repo !== null) {
+    args.push("--repo", repo);
+  }
+
+  const [repoInfo, releases] = yield* Effect.all([
+    gh.getRepoInfo(),
+    gh.runGhJson<LatestRelease[]>(args),
+  ]);
+
+  const result: ReleaseStatusResult = {
+    latestRelease: releases.length > 0 ? releases[0] : null,
+    repo: {
+      owner: repoInfo.owner,
+      name: repoInfo.name,
+      defaultBranch: repoInfo.defaultBranch,
+      url: repoInfo.url,
+    },
+  };
+
+  return result;
+});
+export type GistApiFile = {
+  filename: string;
+  language: string | null;
+  type: string;
+  size: number;
+  truncated?: boolean;
+  content?: string;
+};
+
+export type GistApi = {
+  id: string;
+  description: string | null;
+  public: boolean;
+  html_url: string;
+  created_at: string;
+  updated_at: string;
+  owner: { login: string } | null;
+  files: Record<string, GistApiFile>;
+};
+
+const gistList = Effect.fn("reads.gistList")(function* (limit: number) {
+  const gh = yield* GitHubService;
+  return yield* gh.runGhJson<GistApi[]>(["api", `gists?per_page=${limit}`]);
+});
+const gistView = Effect.fn("reads.gistView")(function* (id: string) {
+  const gh = yield* GitHubService;
+  return yield* gh.runGhJson<GistApi>(["api", `gists/${id}`]);
+});
+export type AsyncMergeResult = {
+  status: "pending" | "merged" | "enqueued" | "failed";
+  details?: {
+    message?: string;
+    uuid?: string;
+    sha?: string;
+    merge_method?: "squash" | "merge" | "rebase";
+  };
+};
+const baseSha = Effect.fn("reads.baseSha")(function* (
+  repo: { owner: string; name: string },
+  pr: number,
+) {
+  const gh = yield* GitHubService;
+  return yield* gh.runGh([
+    "api",
+    `repos/${repo.owner}/${repo.name}/pulls/${pr}`,
+    "--jq",
+    ".base.sha",
+  ]);
+});
+const asyncMergeStatus = Effect.fn("reads.asyncMergeStatus")(function* (path: string) {
+  const gh = yield* GitHubService;
+  return yield* gh.runGhJson<AsyncMergeResult>(["api", path]);
+});
+const stackMergeStatus = Effect.fn("reads.stackMergeStatus")(function* (path: string) {
+  const gh = yield* GitHubService;
+  return yield* gh.apiRequest<AsyncMergeResult>({ path });
+});
+const repoInfo = Effect.fn("reads.repoInfo")(function* () {
+  const gh = yield* GitHubService;
+  return yield* gh.getRepoInfo();
+});
+export const passthrough = {
+  repoInfo,
+  listOrgRepos,
+  searchOrgCode,
+  listReleases,
+  viewRelease,
+  releaseStatus,
+  gistList,
+  gistView,
+  baseSha,
+  asyncMergeStatus,
+  stackMergeStatus,
+};

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

@@ -0,0 +1,30 @@
+import type { Op } from "./keys";
+
+export type CacheClass =
+  | { readonly kind: "immutable" }
+  | { readonly kind: "ttl" | "etag"; readonly ttlMs: number }
+  | { readonly kind: "gated"; readonly ttlMs: number; readonly maxAgeMs: number }
+  | { readonly kind: "passthrough" };
+
+export const OPS = {
+  prHead: { kind: "etag", ttlMs: 5000 },
+  checkSignal: { kind: "etag", ttlMs: 5000 },
+  prView: { kind: "gated", ttlMs: 5000, maxAgeMs: 15000 },
+  prChecks: { kind: "gated", ttlMs: 5000, maxAgeMs: 60000 },
+  prList: { kind: "ttl", ttlMs: 15000 },
+  prComments: { kind: "etag", ttlMs: 15000 },
+  prReviews: { kind: "etag", ttlMs: 15000 },
+  reviewThreads: { kind: "gated", ttlMs: 5000, maxAgeMs: 60000 },
+  lastHumanReviewer: { kind: "ttl", ttlMs: 15000 },
+  issueView: { kind: "ttl", ttlMs: 30000 },
+  issueList: { kind: "ttl", ttlMs: 15000 },
+  issueComments: { kind: "etag", ttlMs: 15000 },
+  runList: { kind: "ttl", ttlMs: 15000 },
+  runView: { kind: "ttl", ttlMs: 15000 },
+  runJobs: { kind: "ttl", ttlMs: 15000 },
+  completedAttemptJobs: { kind: "immutable" },
+  runLog: { kind: "ttl", ttlMs: 15000 },
+  jobLog: { kind: "passthrough" },
+  annotations: { kind: "passthrough" },
+  jobIdentity: { kind: "immutable" },
+} as const satisfies Record<Op, CacheClass>;

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

@@ -0,0 +1,25 @@
+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";
+
+const stats = Command.make("stats", { format: formatOption }, ({ format }) =>
+  Effect.gen(function* () {
+    yield* logFormatted(yield* cacheStats, format);
+  }),
+);
+const clear = Command.make(
+  "clear",
+  { repo: Flag.String("repo").pipe(Flag.optional), format: formatOption },
+  ({ repo, format }) =>
+    Effect.gen(function* () {
+      const target = Option.isSome(repo) ? yield* resolveRepo(repo.value) : null;
+      const cleared = yield* clearCache(target);
+      yield* logFormatted({ cleared, repo: Option.getOrNull(repo) }, format);
+    }),
+);
+export const cacheCommand = Command.make("cache", {}).pipe(
+  Command.withDescription("Inspect or clear the shared GitHub read cache"),
+  Command.withSubcommands([stats, clear]),
+);

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

@@ -0,0 +1,56 @@
+import { Effect, Schema } from "effect";
+import { cachedRead, ReadCache } from "./cache";
+import { OPS } from "./classes";
+import type { ReadKey } from "./keys";
+import { parsePreserving } from "./porcelain";
+
+const Envelope = Schema.Struct({
+  data: Schema.Unknown,
+  originFetchedAt: Schema.Number,
+  signal: Schema.String,
+});
+type Envelope<A> = { data: A; originFetchedAt: number; signal: string };
+
+export const gatedRead = <A, E, R, E2, R2>(opts: {
+  readonly key: ReadKey & { op: "prView" | "prChecks" | "reviewThreads" };
+  readonly decode: (value: unknown) => A;
+  readonly fetch: Effect.Effect<A, E, R>;
+  readonly signal: Effect.Effect<string, E2, R2>;
+  readonly maxAgeMs: (value: A) => number;
+  readonly consistency?: "cached" | "origin";
+  readonly cacheableWhen?: (value: A) => boolean;
+}) =>
+  Effect.gen(function* () {
+    const session = yield* ReadCache;
+    if (session === null || session.store === null || opts.consistency === "origin")
+      return yield* opts.fetch;
+    const value = yield* cachedRead({
+      key: opts.key,
+      policy: OPS[opts.key.op],
+      cacheableWhen: (envelope: Envelope<A>) => opts.cacheableWhen?.(envelope.data) !== false,
+      decode: (raw): Envelope<A> => {
+        const envelope = parsePreserving(Envelope)(raw);
+        return { ...envelope, data: opts.decode(envelope.data) };
+      },
+      fetch: (previous: { value: Envelope<A>; valid: boolean } | null) =>
+        Effect.gen(function* () {
+          const signal = yield* opts.signal.pipe(Effect.orElseSucceed(() => null));
+          const now = Date.now();
+          if (
+            previous !== null &&
+            signal !== null &&
+            previous.valid &&
+            previous.value.signal === signal &&
+            now >= previous.value.originFetchedAt &&
+            now - previous.value.originFetchedAt < opts.maxAgeMs(previous.value.data)
+          )
+            return { kind: "fresh" as const, value: previous.value };
+          const data = yield* opts.fetch;
+          return {
+            kind: "fresh" as const,
+            value: { data, originFetchedAt: now, signal: signal ?? "" },
+          };
+        }),
+    });
+    return value.data;
+  });

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

@@ -0,0 +1,4 @@
+export { reads, resolveRepo } from "./reads";
+export { writes } from "./writes";
+export { withReadCache } from "./cache";
+export { waits } from "./waits";

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

@@ -0,0 +1,107 @@
+import { Effect, Schema } from "effect";
+import { GitHubService } from "#gh/read/transport";
+import { restSnapshot } from "./rest";
+import { cachedRead } from "./cache";
+import { OPS } from "./classes";
+import { repoSlug } from "./keys";
+import type { RepoRef } from "./keys";
+import { parsePreserving } from "./porcelain";
+
+const Label = Schema.Struct({ name: Schema.String });
+const Login = Schema.Struct({ login: Schema.String });
+const IssueListItem = Schema.Struct({
+  number: Schema.Number,
+  title: Schema.String,
+  state: Schema.String,
+  url: Schema.String,
+  labels: Schema.mutable(Schema.Array(Label)),
+  createdAt: Schema.String,
+});
+const IssueView = Schema.Struct({
+  ...IssueListItem.fields,
+  assignees: Schema.mutable(Schema.Array(Login)),
+  author: Login,
+  body: Schema.String,
+  closedAt: Schema.NullOr(Schema.String),
+});
+const IssueComment = Schema.Struct({
+  id: Schema.Number,
+  user: Login,
+  body: Schema.String,
+  created_at: Schema.String,
+  html_url: Schema.String,
+});
+export type IssueView = typeof IssueView.Type;
+export type IssueListFilter = { state: string; labels: string | null; limit: number };
+export const ISSUE_LIST_FIELDS = "number,title,state,url,labels,createdAt";
+export const ISSUE_VIEW_FIELDS =
+  "number,title,state,url,labels,assignees,author,body,createdAt,closedAt";
+
+export const issueView = Effect.fn("reads.issueView")(function* (
+  repo: RepoRef,
+  issue: number,
+  consistency: "cached" | "origin" = "cached",
+) {
+  const gh = yield* GitHubService;
+  return yield* cachedRead({
+    key: { op: "issueView", repo, issue },
+    policy: OPS.issueView,
+    consistency,
+    decode: parsePreserving(IssueView),
+    fetch: () =>
+      gh
+        .runGhJson<IssueView>([
+          "issue",
+          "view",
+          String(issue),
+          "--repo",
+          repoSlug(repo),
+          "--json",
+          ISSUE_VIEW_FIELDS,
+        ])
+        .pipe(Effect.map((value) => ({ kind: "fresh" as const, value }))),
+  });
+});
+
+export const issueList = Effect.fn("reads.issueList")(function* (
+  repo: RepoRef,
+  filter: IssueListFilter,
+) {
+  const gh = yield* GitHubService;
+  const args = [
+    "issue",
+    "list",
+    "--state",
+    filter.state,
+    "--limit",
+    String(filter.limit),
+    "--json",
+    ISSUE_LIST_FIELDS,
+    "--repo",
+    repoSlug(repo),
+  ];
+  if (filter.labels !== null) args.push("--label", filter.labels);
+  return yield* cachedRead({
+    key: { op: "issueList", repo, filter },
+    policy: OPS.issueList,
+    decode: parsePreserving(Schema.mutable(Schema.Array(IssueListItem))),
+    fetch: () =>
+      gh
+        .runGhJson<Array<typeof IssueListItem.Type>>(args)
+        .pipe(Effect.map((value) => ({ kind: "fresh" as const, value }))),
+  });
+});
+
+export const issueComments = Effect.fn("reads.issueComments")(function* (
+  repo: RepoRef,
+  issue: number,
+) {
+  const snapshot = yield* restSnapshot({ op: "issueComments", repo, issue }, [
+    {
+      kind: "pages",
+      path: `repos/${repoSlug(repo)}/issues/${issue}/comments`,
+      items: Schema.decodeUnknownSync(Schema.Array(Schema.Unknown)),
+    },
+  ]);
+  return snapshot.pages.flatMap((page) => page.body as Array<typeof IssueComment.Type>);
+});

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

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+
+export type RepoRef = { readonly owner: string; readonly name: string };
+export type RunFilter = {
+  readonly workflow: string | null;
+  readonly branch: string | null;
+  readonly status: string | null;
+  readonly event: string | null;
+  readonly limit: number;
+};
+export type ReadKey = { readonly repo: RepoRef } & (
+  | {
+      readonly op:
+        | "prView"
+        | "prHead"
+        | "prComments"
+        | "prReviews"
+        | "reviewThreads"
+        | "lastHumanReviewer";
+      readonly pr: number;
+    }
+  | { readonly op: "prChecks"; readonly pr: number; readonly headSha: string }
+  | { readonly op: "checkSignal"; readonly sha: string }
+  | {
+      readonly op: "prList" | "issueList";
+      readonly filter: Readonly<Record<string, string | number | boolean | null>>;
+    }
+  | { readonly op: "issueView" | "issueComments"; readonly issue: number }
+  | { readonly op: "runList"; readonly filter: RunFilter }
+  | { readonly op: "runView"; readonly runId: number; readonly attempt?: number }
+  | { readonly op: "runJobs"; readonly runId: number; readonly attempt: number }
+  | { readonly op: "completedAttemptJobs"; readonly runId: number; readonly attempt: number }
+  | {
+      readonly op: "runLog";
+      readonly runId: number;
+      readonly attempt: number;
+      readonly failedOnly: boolean;
+      readonly jobId: number | null;
+    }
+  | { readonly op: "jobLog" | "annotations" | "jobIdentity"; readonly jobId: number }
+);
+export type Op = ReadKey["op"];
+export type Tag =
+  `${"pr" | "reviews" | "review-comments" | "threads" | "issue" | "issue-comments" | "run" | "checks" | "pulls" | "issues" | "runs" | "repo"}:${string}`;
+
+const canonical = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value !== null && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value)
+        .toSorted(([a], [b]) => a.localeCompare(b))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  return value;
+};
+export const digest = (value: string): string => createHash("sha256").update(value).digest("hex");
+export const repoSlug = (repo: RepoRef): string => `${repo.owner}/${repo.name}`.toLowerCase();
+export const entryKey = (identity: string, key: ReadKey): string =>
+  digest(JSON.stringify(canonical({ schema: 1, identity, ...key, repo: repoSlug(key.repo) })));
+export const tagsFor = (key: ReadKey): readonly Tag[] => {
+  const repo = repoSlug(key.repo);
+  const fallback: Tag = `repo:${repo}`;
+  switch (key.op) {
+    case "prView":
+    case "prHead":
+    case "lastHumanReviewer":
+      return [fallback, `pr:${repo}#${key.pr}`];
+    case "prChecks":
+      return [fallback, `pr:${repo}#${key.pr}`, `checks:${repo}#${key.pr}`];
+    case "checkSignal":
+      return [fallback, `checks:${repo}@${key.sha}`];
+    case "prComments":
+      return [fallback, `review-comments:${repo}#${key.pr}`];
+    case "prReviews":
+      return [fallback, `reviews:${repo}#${key.pr}`];
+    case "reviewThreads":
+      return [fallback, `threads:${repo}#${key.pr}`];
+    case "prList":
+      return [fallback, `pulls:${repo}`];
+    case "issueList":
+      return [fallback, `issues:${repo}`];
+    case "issueView":
+      return [fallback, `issue:${repo}#${key.issue}`];
+    case "issueComments":
+      return [fallback, `issue-comments:${repo}#${key.issue}`];
+    case "runView":
+    case "runJobs":
+    case "completedAttemptJobs":
+    case "runLog":
+      return [fallback, `run:${repo}/${key.runId}`];
+    case "runList":
+      return [fallback, `runs:${repo}`];
+    case "jobLog":
+    case "annotations":
+    case "jobIdentity":
+      return [fallback];
+    default: {
+      const exhaustive: never = key;
+      return exhaustive;
+    }
+  }
+};

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

@@ -0,0 +1,58 @@
+import { Schema } from "effect";
+
+const Step = Schema.Struct({
+  name: Schema.String,
+  status: Schema.String,
+  conclusion: Schema.NullOr(Schema.String),
+  number: Schema.Number,
+  startedAt: Schema.optional(Schema.NullOr(Schema.String)),
+  completedAt: Schema.optional(Schema.NullOr(Schema.String)),
+});
+export const WorkflowJob = Schema.Struct({
+  databaseId: Schema.Number,
+  name: Schema.String,
+  status: Schema.String,
+  conclusion: Schema.NullOr(Schema.String),
+  startedAt: Schema.String,
+  completedAt: Schema.NullOr(Schema.String),
+  url: Schema.String,
+  steps: Schema.Array(Step),
+});
+export const WorkflowRun = Schema.Struct({
+  databaseId: Schema.Number,
+  displayTitle: Schema.String,
+  status: Schema.String,
+  conclusion: Schema.NullOr(Schema.String),
+  headBranch: Schema.String,
+  headSha: Schema.String,
+  createdAt: Schema.String,
+  event: Schema.String,
+  url: Schema.String,
+  workflowName: Schema.String,
+});
+export const WorkflowRunDetail = Schema.Struct({
+  ...WorkflowRun.fields,
+  jobs: Schema.Array(WorkflowJob),
+  attempt: Schema.Number,
+});
+export type WorkflowJob = typeof WorkflowJob.Type;
+export type WorkflowRun = typeof WorkflowRun.Type;
+export type WorkflowRunDetail = typeof WorkflowRunDetail.Type;
+export const RUN_LIST_FIELDS =
+  "databaseId,displayTitle,status,conclusion,headBranch,headSha,createdAt,event,url,workflowName";
+export const RUN_VIEW_FIELDS = `${RUN_LIST_FIELDS},jobs,attempt`;
+
+export const parsePreserving =
+  <A>(schema: Schema.Codec<A>) =>
+  (value: unknown): A => {
+    if (Schema.is(schema)(value)) return value;
+    return Schema.decodeUnknownSync(schema)(value);
+  };
+
+export const project = <A extends object, K extends keyof A>(
+  value: A,
+  fields: readonly K[],
+): Pick<A, K> =>
+  Object.fromEntries(
+    Object.entries(value).filter(([key]) => fields.some((field) => field === key)),
+  ) as Pick<A, K>;