terramend 0.2.0

package/src/utils/prSummary.ts

@@ -0,0 +1,147 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ToolContext } from "#app/mcp/server";
+import { apiFetch } from "#app/utils/apiFetch";
+import { log } from "#app/utils/cli";
+import { patchWorkflowRunFields } from "#app/utils/patchWorkflowRunFields";
+
+/**
+ * The PR-level summary snapshot is a markdown file the agent edits in place
+ * during a Review / IncrementalReview run. The server seeds the file with
+ * either the previous run's snapshot (incremental) or a stub scaffold (first
+ * run), lets the agent edit it with its native file-editing tools, then
+ * reads it back at end-of-run and persists it to `WorkflowRun.summarySnapshot`.
+ *
+ * The snapshot is an internal artifact — it is consumed by future agent runs
+ * as durable cross-run context, not surfaced to humans. User-visible summary
+ * content lives in the Review / IncrementalReview review bodies, governed by
+ * `action/modes.ts`.
+ *
+ * Edit-in-place avoids the output-token tax of a tool call that regurgitates
+ * the full snapshot, and gives incremental runs a clean surface that
+ * range-diffs cleanly across runs because the section headings are stable.
+ */
+
+export const SUMMARY_FILE_NAME = "terramend-summary.md";
+
+/**
+ * minimal seed for first-run PRs. just a header + a one-line note about
+ * what this file is for. structure is intentionally NOT prescribed —
+ * different PRs warrant different organization, and the agent should pick
+ * a shape that fits this PR. the agent's prompt (see selectMode.ts
+ * `buildSummaryAddendum`) carries the actual instructions for what to
+ * capture and how.
+ *
+ * keeping the seed short also makes the unchanged-from-seed gate more
+ * sensitive — any meaningful edit moves the file off the seed, so
+ * `persistSummary` can reliably skip the DB write when the agent didn't
+ * touch the file.
+ */
+export const SUMMARY_SCAFFOLD = `# PR summary
+
+<!-- durable cross-run context. edit in place; the next agent run reads this
+     before reviewing new commits. structure however serves the PR best. -->
+`;
+
+const MIN_SNAPSHOT_LENGTH = 60;
+/** PG TEXT can hold ~1GB but a sane cap protects the DB / API payloads. */
+const MAX_SNAPSHOT_LENGTH = 32_768;
+
+export function summaryFilePath(tmpdir: string): string {
+  return join(tmpdir, SUMMARY_FILE_NAME);
+}
+
+/** seed the summary file with previous snapshot (incremental) or scaffold (first run). */
+export async function seedSummaryFile(params: {
+  tmpdir: string;
+  previousSnapshot: string | null;
+}): Promise<string> {
+  const path = summaryFilePath(params.tmpdir);
+  await mkdir(dirname(path), { recursive: true });
+  const seed =
+    params.previousSnapshot && params.previousSnapshot.trim().length >= MIN_SNAPSHOT_LENGTH
+      ? params.previousSnapshot
+      : SUMMARY_SCAFFOLD;
+  await writeFile(path, seed, "utf8");
+  return path;
+}
+
+/** read + validate the summary file written by the agent.
+ * returns null when the file is missing or fails sanity checks. */
+export async function readSummaryFile(path: string): Promise<string | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length < MIN_SNAPSHOT_LENGTH) return null;
+  if (trimmed.length > MAX_SNAPSHOT_LENGTH) return trimmed.slice(0, MAX_SNAPSHOT_LENGTH);
+  return trimmed;
+}
+
+/**
+ * Fetch the most recent persisted PR summary snapshot for this PR.
+ * Returns null on first-time PRs, when summary is disabled, or on any error.
+ * Best-effort: a transient API failure should not block the run.
+ */
+export async function fetchPreviousSnapshot(
+  ctx: ToolContext,
+  prNumber: number,
+): Promise<string | null> {
+  if (!ctx.githubInstallationToken) return null;
+  try {
+    const response = await apiFetch({
+      path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/pr/${prNumber}/summary-comment`,
+      method: "GET",
+      headers: { authorization: `Bearer ${ctx.githubInstallationToken}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return null;
+    const data = (await response.json()) as { snapshot?: string | null };
+    return typeof data.snapshot === "string" && data.snapshot.length > 0 ? data.snapshot : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the agent-edited PR summary tmpfile and persist to
+ * `WorkflowRun.summarySnapshot`.
+ *
+ * Best-effort: any failure is logged and does not affect the run's success
+ * status. Skips the PATCH when the file is byte-identical to its seed —
+ * persisting the seed verbatim would either re-write what the DB already has
+ * (on incremental runs) or serialize the placeholder scaffold (on first
+ * runs), neither of which is useful.
+ *
+ * Funnels through both the success path and the SIGINT/SIGTERM handler;
+ * `summaryPersistAttempted` guards against double-execution.
+ */
+export async function persistSummary(ctx: ToolContext): Promise<void> {
+  const filePath = ctx.toolState.summaryFilePath;
+  if (!filePath) return;
+  if (ctx.toolState.summaryPersistAttempted) return;
+  ctx.toolState.summaryPersistAttempted = true;
+  const snapshot = await readSummaryFile(filePath);
+  if (!snapshot) {
+    log.debug(`pr summary tmpfile missing or invalid at ${filePath} — skipping persist`);
+    return;
+  }
+  // soft gate: agent never touched the seeded file. saving the seed back
+  // is a no-op at best (incremental run — DB already has it) and a bug at
+  // worst (first run — serializes the placeholder italics). log a warning
+  // so the failure mode is visible in CI without flipping the run to
+  // failed.
+  const seed = ctx.toolState.summarySeed?.trim();
+  if (seed !== undefined && snapshot === seed) {
+    log.warning(
+      "» pr summary tmpfile unchanged from seed — skipping persist (agent did not edit it)",
+    );
+    return;
+  }
+  await patchWorkflowRunFields(ctx, { summarySnapshot: snapshot }).catch((err) => {
+    log.debug(`pr summary persist failed: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}

package/src/utils/progressComment.ts

@@ -0,0 +1,261 @@
+/**
+ * Single source of truth for reading, updating, deleting, and creating "progress comments" —
+ * the GitHub comments Terramend uses to surface a run's status.
+ *
+ * A progress comment can be one of two distinct GitHub entities with non-overlapping IDs and
+ * distinct REST endpoints:
+ *   - "issue":  a top-level issue/PR timeline comment (octokit.rest.issues.*Comment)
+ *   - "review": an inline PR review-thread comment   (octokit.rest.pulls.*ReviewComment)
+ *
+ * Callers carry a `ProgressComment` (id + type) value end-to-end so the right endpoint is always
+ * picked. Adding a third comment type later means one new branch in this file, not six.
+ */
+
+export type ProgressCommentType = "issue" | "review";
+
+export type ProgressComment = {
+  id: number;
+  type: ProgressCommentType;
+};
+
+/**
+ * Parse the on-the-wire `{ id: string; type }` shape (the form carried in `JsonPayload`)
+ * into the in-memory `ProgressComment` shape. Returns undefined when the id isn't a
+ * positive integer so callers can short-circuit cleanly. Callers handle logging.
+ */
+export function parseProgressComment(
+  raw: { id: string; type: ProgressCommentType } | null | undefined,
+): ProgressComment | undefined {
+  if (!raw?.id) return undefined;
+  const id = parseInt(raw.id, 10);
+  if (Number.isNaN(id) || id <= 0) return undefined;
+  return { id, type: raw.type };
+}
+
+// minimal Octokit shape needed by the progress-comment helpers. structural so the helper
+// can be called from both the action package (@octokit/rest v22) and the root project
+// (@octokit/rest v21) without a nominal type clash. only the methods used here are listed.
+interface CommentResponse {
+  data: { id: number; body?: string | null | undefined; html_url: string; node_id?: string };
+}
+export interface ProgressCommentOctokit {
+  rest: {
+    issues: {
+      createComment: (params: {
+        owner: string;
+        repo: string;
+        issue_number: number;
+        body: string;
+      }) => Promise<CommentResponse>;
+      getComment: (params: {
+        owner: string;
+        repo: string;
+        comment_id: number;
+      }) => Promise<CommentResponse>;
+      updateComment: (params: {
+        owner: string;
+        repo: string;
+        comment_id: number;
+        body: string;
+      }) => Promise<CommentResponse>;
+      deleteComment: (params: {
+        owner: string;
+        repo: string;
+        comment_id: number;
+      }) => Promise<unknown>;
+    };
+    pulls: {
+      createReplyForReviewComment: (params: {
+        owner: string;
+        repo: string;
+        pull_number: number;
+        comment_id: number;
+        body: string;
+      }) => Promise<CommentResponse>;
+      getReviewComment: (params: {
+        owner: string;
+        repo: string;
+        comment_id: number;
+      }) => Promise<CommentResponse>;
+      updateReviewComment: (params: {
+        owner: string;
+        repo: string;
+        comment_id: number;
+        body: string;
+      }) => Promise<CommentResponse>;
+      deleteReviewComment: (params: {
+        owner: string;
+        repo: string;
+        comment_id: number;
+      }) => Promise<unknown>;
+    };
+  };
+}
+
+interface ApiCtx {
+  octokit: ProgressCommentOctokit;
+  owner: string;
+  repo: string;
+}
+
+/**
+ * Fetch a progress comment via the appropriate REST endpoint for its type.
+ * Returns the common subset of fields callers actually use.
+ */
+export async function getProgressComment(
+  ctx: ApiCtx,
+  comment: ProgressComment,
+): Promise<{ id: number; body: string | undefined; html_url: string }> {
+  const result = await (comment.type === "review"
+    ? ctx.octokit.rest.pulls.getReviewComment({
+        owner: ctx.owner,
+        repo: ctx.repo,
+        comment_id: comment.id,
+      })
+    : ctx.octokit.rest.issues.getComment({
+        owner: ctx.owner,
+        repo: ctx.repo,
+        comment_id: comment.id,
+      }));
+  return {
+    id: result.data.id,
+    body: result.data.body ?? undefined,
+    html_url: result.data.html_url,
+  };
+}
+
+/**
+ * Update a progress comment in place via the appropriate REST endpoint.
+ * Returns the common subset of fields callers actually use.
+ */
+export async function updateProgressComment(
+  ctx: ApiCtx,
+  comment: ProgressComment,
+  body: string,
+): Promise<{
+  id: number;
+  body: string | undefined;
+  html_url: string;
+  node_id: string | undefined;
+}> {
+  const result = await (comment.type === "review"
+    ? ctx.octokit.rest.pulls.updateReviewComment({
+        owner: ctx.owner,
+        repo: ctx.repo,
+        comment_id: comment.id,
+        body,
+      })
+    : ctx.octokit.rest.issues.updateComment({
+        owner: ctx.owner,
+        repo: ctx.repo,
+        comment_id: comment.id,
+        body,
+      }));
+  return {
+    id: result.data.id,
+    body: result.data.body ?? undefined,
+    html_url: result.data.html_url,
+    node_id: result.data.node_id,
+  };
+}
+
+/**
+ * Delete a progress comment via the appropriate REST endpoint.
+ * Lower-level than `deleteProgressComment` in mcp/comment.ts — that one also clears
+ * tool state. Callers that don't have a ToolContext (post cleanup, error handlers)
+ * should use this directly; the higher-level wrapper delegates here.
+ */
+export async function deleteProgressCommentApi(
+  ctx: ApiCtx,
+  comment: ProgressComment,
+): Promise<void> {
+  if (comment.type === "review") {
+    await ctx.octokit.rest.pulls.deleteReviewComment({
+      owner: ctx.owner,
+      repo: ctx.repo,
+      comment_id: comment.id,
+    });
+    return;
+  }
+  await ctx.octokit.rest.issues.deleteComment({
+    owner: ctx.owner,
+    repo: ctx.repo,
+    comment_id: comment.id,
+  });
+}
+
+/**
+ * Discriminated target for `createLeapingProgressComment`. The two variants map to the two
+ * distinct GitHub create endpoints; review-reply additionally needs the parent comment ID.
+ */
+export type CreateProgressCommentTarget =
+  | { kind: "issue"; issueNumber: number }
+  | { kind: "reviewReply"; pullNumber: number; replyToCommentId: number };
+
+export interface CreatedProgressComment {
+  comment: ProgressComment;
+  body: string | undefined;
+  html_url: string;
+}
+
+/**
+ * Create the initial "Leaping into action..." progress comment.
+ *
+ * Reliability: when `kind: "reviewReply"` fails (e.g. the parent comment was deleted or the
+ * thread is otherwise unreachable), falls back to a top-level issue comment on the same PR
+ * rather than leaving the run with no progress surface. The fallback is logged.
+ *
+ * (PR # === issue # in GitHub's number space, so `pullNumber` doubles as the fallback target.)
+ */
+export async function createLeapingProgressComment(
+  ctx: ApiCtx,
+  target: CreateProgressCommentTarget,
+  body: string,
+): Promise<CreatedProgressComment> {
+  if (target.kind === "reviewReply") {
+    try {
+      const result = await ctx.octokit.rest.pulls.createReplyForReviewComment({
+        owner: ctx.owner,
+        repo: ctx.repo,
+        pull_number: target.pullNumber,
+        comment_id: target.replyToCommentId,
+        body,
+      });
+      return {
+        comment: { id: result.data.id, type: "review" },
+        body: result.data.body ?? undefined,
+        html_url: result.data.html_url,
+      };
+    } catch (error) {
+      // console.warn (not the action-flavored log.warning) because this helper runs in
+      // both the action runtime and the Next.js webhook context, and we don't want a
+      // ::warning:: GitHub Actions annotation leaking into Vercel logs.
+      console.warn(
+        `[progressComment] review reply failed (parent ${target.replyToCommentId} on PR #${target.pullNumber}), falling back to issue comment:`,
+        error,
+      );
+      const fallback = await ctx.octokit.rest.issues.createComment({
+        owner: ctx.owner,
+        repo: ctx.repo,
+        issue_number: target.pullNumber,
+        body,
+      });
+      return {
+        comment: { id: fallback.data.id, type: "issue" },
+        body: fallback.data.body ?? undefined,
+        html_url: fallback.data.html_url,
+      };
+    }
+  }
+  const result = await ctx.octokit.rest.issues.createComment({
+    owner: ctx.owner,
+    repo: ctx.repo,
+    issue_number: target.issueNumber,
+    body,
+  });
+  return {
+    comment: { id: result.data.id, type: "issue" },
+    body: result.data.body ?? undefined,
+    html_url: result.data.html_url,
+  };
+}