infraweaver 0.1.0

package/src/utils/keylessOidc.ts

@@ -0,0 +1,47 @@
+/**
+ * Stash for the GitHub Actions OIDC request creds used by KEYLESS (Sigstore)
+ * evidence signing.
+ *
+ * The `terraform_emit_evidence` / `terraform_emit_vex` tools run DURING the agent
+ * loop — after `main.ts` scrubs `ACTIONS_ID_TOKEN_REQUEST_*` from the env (in
+ * every shell mode) — so they can't call `core.getIDToken()` / read those vars
+ * themselves. Infraweaver already snapshots the request creds early (see
+ * `resolveTokens` in `utils/token.ts`, which reads them for mid-run token
+ * re-mints); this module lets that same snapshot feed a `sigstore`-audience OIDC
+ * token to Fulcio at emit time.
+ *
+ * Fulcio requires the OIDC token's `aud` to be exactly `sigstore` (its configured
+ * audience), distinct from Infraweaver Cloud's own `cloudOidcAudience()`.
+ */
+
+import { fetchOidcIdToken, type OidcCreds } from "#app/utils/github";
+
+/** Fulcio's required OIDC audience for the public-good instance. */
+export const SIGSTORE_OIDC_AUDIENCE = "sigstore" as const;
+
+let stashedCreds: OidcCreds | undefined;
+
+/** Record the OIDC request creds for later keyless signing. Call once at startup
+ *  (before the restricted-mode env scrub), passing `readOidcCreds()`. `undefined`
+ *  off-CI, which simply disables keyless signing (there is no ambient identity). */
+export function stashKeylessOidcCreds(creds: OidcCreds | undefined): void {
+  stashedCreds = creds;
+}
+
+/** True when an ambient GitHub Actions OIDC identity was captured — i.e. keyless
+ *  signing is possible (running in CI with `id-token: write`). */
+export function keylessOidcAvailable(): boolean {
+  return stashedCreds !== undefined;
+}
+
+/** Fetch a fresh `sigstore`-audience OIDC JWT for Fulcio from the stashed creds.
+ *  Throws when no creds were stashed (off-CI, or the workflow lacks id-token:write). */
+export async function fetchSigstoreOidcToken(): Promise<string> {
+  if (!stashedCreds) {
+    throw new Error(
+      "keyless signing needs a GitHub Actions OIDC identity, but none was captured — " +
+        "run inside GitHub Actions with `permissions: id-token: write`.",
+    );
+  }
+  return fetchOidcIdToken(stashedCreds, SIGSTORE_OIDC_AUDIENCE);
+}

package/src/utils/leapingComment.ts

@@ -0,0 +1,20 @@
+import { stripExistingFooter } from "#app/utils/buildInfraweaverFooter";
+
+/**
+ * The prefix text for the initial "leaping into action" comment.
+ * Used to detect whether a progress comment is still in its initial state
+ * and hasn't been updated with real progress or error messages.
+ *
+ * Lives in `utils/` (not `mcp/`) so it can be re-exported via `infraweaver/internal`
+ * without dragging the MCP server's transitive imports into the Next.js app's
+ * type-check graph.
+ */
+export const LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
+
+export function isLeapingIntoActionCommentBody(body: string): boolean {
+  const content = stripExistingFooter(body).trimStart();
+  const firstLine = content.split(/\r?\n/, 1)[0]?.trimEnd() ?? "";
+  return new RegExp(`(^|\\s)${LEAPING_INTO_ACTION_PREFIX}(\\.\\.\\.)?$`).test(
+    firstLine,
+  );
+}

package/src/utils/learnings.ts

@@ -0,0 +1,145 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { LEARNINGS_FILE } from "#app/brand";
+import type { ToolContext } from "#app/mcp/server";
+import { cloudRequest } from "#app/utils/cloudClient";
+import { isBackendConfigured } from "#app/utils/apiUrl";
+import { log } from "#app/utils/cli";
+import {
+  MAX_LEARNINGS_LENGTH,
+  truncateAtLineBoundary,
+} from "#app/utils/learningsTruncate";
+
+export { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary };
+
+/**
+ * Repo-level learnings — operational facts about a repo (setup steps, test
+ * commands, conventions, gotchas) that accumulate across agent runs and feed
+ * back into future runs as durable context. Modeled on the PR-summary tmpfile
+ * pattern (see action/utils/prSummary.ts):
+ *
+ *   1. server seeds `infraweaver-learnings.md` with the verbatim body of
+ *      `Repo.learnings` (or empty for fresh repos), and parses headings
+ *      server-side (`utils/learningsToc.ts`) — the parsed TOC is rendered
+ *      into the LEARNINGS prompt section, not into the file
+ *   2. the agent reads the TOC in the prompt and uses listed line ranges
+ *      to read just the sections relevant to the current task — file can
+ *      grow large, but only targeted ranges hit the agent's context
+ *   3. agent edits the file in place at end-of-run during the reflection
+ *      turn (see action/agents/postRun.ts buildLearningsReflectionPrompt)
+ *   4. main.ts reads the file back at end-of-run and PATCHes
+ *      `/api/repo/[owner]/[repo]/learnings` if the body changed
+ *
+ * Edit-in-place avoids stuffing the entire learnings list into both the
+ * prompt context and an `update_learnings` MCP tool call (which previously
+ * required passing the FULL merged list as a string parameter — an
+ * output-token tax that grew linearly with the learnings size).
+ *
+ * Section structure is agent-curated. The reflection prompt teaches
+ * hierarchy + a soft 300-line-per-section cap to keep TOC ranges
+ * agent-targetable on long-lived repos; there is no fixed taxonomy.
+ */
+
+export const LEARNINGS_FILE_NAME = LEARNINGS_FILE;
+
+export function learningsFilePath(tmpdir: string): string {
+  return join(tmpdir, LEARNINGS_FILE_NAME);
+}
+
+/** seed the rolling learnings tmpfile with the verbatim DB body (or empty
+ * string for fresh repos). returns the absolute path. the parsed TOC is
+ * carried separately via `RepoSettings.learningsHeadings` and rendered
+ * into the prompt by `resolveInstructions`, so the file on disk is just
+ * the body — no markers, no scaffold, no in-file TOC. */
+export async function seedLearningsFile(params: {
+  tmpdir: string;
+  current: string | null;
+}): Promise<string> {
+  const path = learningsFilePath(params.tmpdir);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, params.current ?? "", "utf8");
+  return path;
+}
+
+/** read the agent-edited learnings file. returns null when the file is
+ * missing or unreadable (treated as "no change"). caps content at the
+ * server's max length to avoid a 400 round-trip. */
+export async function readLearningsFile(path: string): Promise<string | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  return truncateAtLineBoundary(raw.trim(), MAX_LEARNINGS_LENGTH);
+}
+
+/**
+ * Read the agent-edited repo-level learnings tmpfile and PATCH it to
+ * `Repo.learnings`.
+ *
+ * Best-effort: any failure is logged and does not affect the run's success
+ * status. Skips the PATCH when the file is byte-trim-identical to its seed —
+ * the agent didn't touch it, so writing the same content back would just
+ * burn a `LearningsRevision` row and an API round-trip.
+ *
+ * `ctx.toolState.model` is forwarded so `LearningsRevision.model` keeps
+ * populating; it powers the per-revision attribution badge in the UI
+ * history view.
+ *
+ * `learningsPersistAttempted` guards against double-execution between the
+ * normal end-of-run path and the SIGINT/SIGTERM handler.
+ */
+export async function persistLearnings(ctx: ToolContext): Promise<void> {
+  const filePath = ctx.toolState.learningsFilePath;
+  if (!filePath) return;
+  if (ctx.toolState.learningsPersistAttempted) return;
+  ctx.toolState.learningsPersistAttempted = true;
+  // dormant open-core seam: with no backend configured (standalone BYOK), there
+  // is nowhere to persist repo learnings — no-op silently instead of PATCHing
+  // the default marketing host and warning on its 404.
+  if (!isBackendConfigured()) {
+    log.debug(
+      "no backend configured (API_URL unset) — skipping learnings persist",
+    );
+    return;
+  }
+  const current = await readLearningsFile(filePath);
+  if (current === null) {
+    log.debug(
+      `learnings tmpfile missing or unreadable at ${filePath} — skipping persist`,
+    );
+    return;
+  }
+  const seed = ctx.toolState.learningsSeed?.trim() ?? "";
+  if (current === seed) {
+    log.debug("learnings tmpfile unchanged from seed — skipping persist");
+    return;
+  }
+  try {
+    const response = await cloudRequest({
+      path: `/api/repo/${ctx.repo.owner}/${ctx.repo.name}/learnings`,
+      method: "PATCH",
+      credential: ctx.apiToken,
+      json: {
+        learnings: current,
+        model: ctx.toolState.model,
+      },
+      timeoutMs: 10_000,
+    });
+    if (!response.ok) {
+      const error = await response.text().catch(() => "(no body)");
+      // promoted from debug → warning: this path means the agent edited the
+      // file (we already short-circuited the unchanged-from-seed case above)
+      // but the PATCH dropped it on the floor. silently losing real work is
+      // worse than the noise of a CI warning.
+      log.warning(`learnings persist failed (${response.status}): ${error}`);
+      return;
+    }
+    log.info("» learnings updated");
+  } catch (err) {
+    log.warning(
+      `learnings persist failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

package/src/utils/learningsTruncate.ts

@@ -0,0 +1,42 @@
+/**
+ * pure string helpers for capping and line-boundary-truncating the
+ * `Repo.learnings` body. lives in its own module (vs alongside
+ * `learnings.ts`) so the proprietary root app can re-export it through
+ * `action/internal/index.ts` without dragging the entire MCP type graph
+ * along — `learnings.ts` imports `ToolContext` for its runtime helpers,
+ * and pulling that into the SDK-facing `internal` barrel expands the
+ * type graph reachable from root `tsc` and `cf-worker-indexing` to every
+ * tool module under `action/mcp/`. keeping these helpers MCP-free is the
+ * cheap structural fix.
+ *
+ * see `action/utils/learnings.ts` for the full learnings-file lifecycle.
+ */
+
+/** maximum size of `Repo.learnings` body in chars. action truncates the
+ * read-back BEFORE the PATCH to avoid sending an oversized payload; the
+ * server applies the same truncation as a defense-in-depth backstop (any
+ * caller that misses the client-side step would otherwise persist a
+ * mid-line tail, breaking the next-run TOC parse).
+ *
+ * raised from 10k → 100k once the TOC affordance landed: with line-range
+ * reads via the server-parsed TOC the agent doesn't ingest the whole
+ * file, so the cap is governed by curation discipline rather than a
+ * tight byte ceiling. 100k holds ~400-500 short bullets. */
+export const MAX_LEARNINGS_LENGTH = 100_000;
+
+/** truncate at the last newline boundary before `cap` so we don't leave
+ * a partial line at the tail (a half-truncated `## Headi` confuses the
+ * server's next-seed TOC parse and shrinks visible structure). falls
+ * back to a hard `slice` when the line boundary would discard a large
+ * run of content — i.e. when the tail of `head` is one giant line (rare:
+ * minified pastes, fenced log dumps). losing a partial last line is
+ * preferable to losing kilobytes of body. */
+const TRUNCATION_LINE_BOUNDARY_TOLERANCE = 4096;
+export function truncateAtLineBoundary(body: string, cap: number): string {
+  if (body.length <= cap) return body;
+  const head = body.slice(0, cap);
+  const lastNewline = head.lastIndexOf("\n");
+  if (lastNewline <= 0) return head;
+  if (cap - lastNewline > TRUNCATION_LINE_BOUNDARY_TOLERANCE) return head;
+  return head.slice(0, lastNewline);
+}

package/src/utils/lifecycle.ts

@@ -0,0 +1,198 @@
+import { LIFECYCLE_HOOK_TIMEOUT_MS } from "#app/lifecycle";
+import { log } from "#app/utils/cli";
+import {
+  SPAWN_ACTIVITY_TIMEOUT_CODE,
+  SPAWN_TIMEOUT_CODE,
+  SpawnTimeoutError,
+  spawn,
+} from "#app/utils/subprocess";
+
+export interface ExecuteLifecycleHookParams {
+  event: string;
+  script: string | null;
+  /**
+   * when true, after the hook runs (success or failure), discard tracked-file
+   * mods so the agent doesn't see hook-generated drift (e.g. `pnpm install`
+   * rewriting a lockfile). untracked files are preserved — hooks that
+   * intentionally materialize files (e.g. a `.env` from a template) stay
+   * visible to the agent. skipped (with a warning) if the tree had
+   * pre-existing tracked changes before the hook ran, so we never clobber
+   * pre-existing work; pre-existing untracked files are ignored for this
+   * gate because `git restore --staged --worktree .` doesn't touch them
+   * anyway. no-op when no script was configured.
+   */
+  normalizeWorkingTreeAfter?: boolean;
+}
+
+/** structured failure info — `output` on the `exit` variant is trimmed
+ * stderr, falling back to stdout when stderr is empty. */
+export type LifecycleHookFailure =
+  | { kind: "exit"; exitCode: number; output: string }
+  | { kind: "timeout" }
+  | { kind: "spawn"; spawnError: string };
+
+/** one-line, agent-facing description of a hook failure. empty string when
+ * there was no failure, so callers can pass the result straight through to a
+ * prompt section that omits itself on empty. */
+export function describeSetupFailure(failure: LifecycleHookFailure | undefined): string {
+  if (!failure) return "";
+  switch (failure.kind) {
+    case "exit":
+      return `It exited with code ${failure.exitCode}. Output:\n\n${failure.output || "(empty)"}`;
+    case "timeout":
+      return "It timed out and was killed before completing.";
+    case "spawn":
+      return `It failed to start: ${failure.spawnError}`;
+    default: {
+      const _exhaustive: never = failure;
+      return _exhaustive satisfies never;
+    }
+  }
+}
+
+export interface LifecycleHookResult {
+  /**
+   * human-readable warning when the hook failed. includes retry guidance:
+   * transient spawn/exit errors are worth retrying, timeouts and
+   * persistent failures are not. absent when the hook succeeded or was
+   * skipped. setup/post-checkout callers surface this verbatim; prepush
+   * builds its own message from `failure` instead.
+   */
+  warning?: string;
+  /**
+   * structured failure info — undefined when the hook succeeded or was
+   * skipped. lets callers compose their own messaging without parsing the
+   * `warning` string.
+   */
+  failure?: LifecycleHookFailure;
+}
+
+/**
+ * execute a lifecycle hook script if one is configured.
+ *
+ * soft-fails: instead of throwing on hook errors, returns a warning string
+ * (and structured failure info) so callers can choose how to surface it
+ * (mcp tools relay it to the agent; setup logs it and adds a prompt banner).
+ * timeouts are flagged as non-retryable in the warning text.
+ */
+export async function executeLifecycleHook(
+  params: ExecuteLifecycleHookParams,
+): Promise<LifecycleHookResult> {
+  if (!params.script) return {};
+
+  log.info(`» executing ${params.event} lifecycle hook...`);
+
+  // snapshot tracked-file mods BEFORE the hook runs so we can distinguish
+  // hook-generated drift from pre-existing work. both hook windows should
+  // start clean in normal operation (setup runs before any working-tree
+  // writes; checkout_pr refuses to run with a dirty tree), but if that
+  // invariant breaks we'd rather warn than discard whatever was there.
+  // pre-existing untracked files don't matter here — `git restore --staged
+  // --worktree .` never touches untracked files, so they're never at risk.
+  const preHookTrackedCount = params.normalizeWorkingTreeAfter
+    ? (await runGitLines(["diff", "--name-only", "HEAD"])).length
+    : 0;
+
+  // single try/finally so normalization fires on success AND failure paths.
+  // a hook that fails partway through (e.g. `pnpm install` updates the
+  // lockfile then explodes on a peer-dep conflict) leaves the same kind of
+  // drift a successful run does, and the agent will see it next regardless
+  // of which path we took. failure-mode messaging is unchanged; the only
+  // delta is that we don't return tracked drift to the agent.
+  let result: LifecycleHookResult;
+  try {
+    try {
+      const spawnResult = await spawn({
+        cmd: "bash",
+        args: ["-c", params.script],
+        env: process.env,
+        timeout: LIFECYCLE_HOOK_TIMEOUT_MS,
+        activityTimeout: 0,
+        onStdout: (chunk) => process.stdout.write(chunk),
+        onStderr: (chunk) => process.stderr.write(chunk),
+      });
+
+      if (spawnResult.exitCode !== 0) {
+        const output = (spawnResult.stderr || spawnResult.stdout).trim();
+        result = {
+          failure: { kind: "exit", output, exitCode: spawnResult.exitCode },
+          warning:
+            `lifecycle hook '${params.event}' failed with exit code ${spawnResult.exitCode}. ` +
+            `output: ${output || "(empty)"}. ` +
+            `retry the operation if the failure looks flaky (network blips, transient rate limits). ` +
+            `do NOT retry if the script is broken (missing commands, syntax errors) or the error is persistent.`,
+        };
+      } else {
+        log.info(`» ${params.event} lifecycle hook completed successfully`);
+        result = {};
+      }
+    } catch (err) {
+      const isTimeout =
+        err instanceof SpawnTimeoutError &&
+        (err.code === SPAWN_TIMEOUT_CODE || err.code === SPAWN_ACTIVITY_TIMEOUT_CODE);
+      if (isTimeout) {
+        const minutes = Math.round(LIFECYCLE_HOOK_TIMEOUT_MS / 60000);
+        result = {
+          failure: { kind: "timeout" },
+          warning:
+            `lifecycle hook '${params.event}' timed out after ${minutes}min. ` +
+            `do NOT retry — the script is likely hung or doing too much work. ` +
+            `ask the repo owner to simplify the hook (e.g. move long-running work out of the hook, add caching, or split it).`,
+        };
+      } else {
+        const msg = err instanceof Error ? err.message : String(err);
+        result = {
+          failure: { kind: "spawn", spawnError: msg },
+          warning:
+            `lifecycle hook '${params.event}' failed to spawn: ${msg}. ` +
+            `this is likely a transient failure — retry the operation.`,
+        };
+      }
+    }
+  } finally {
+    if (params.normalizeWorkingTreeAfter) {
+      await normalizeWorkingTreeAfterHook({ event: params.event, preHookTrackedCount });
+    }
+  }
+  return result;
+}
+
+/**
+ * discard tracked-file mods left by a lifecycle hook so the agent's next
+ * `git status` matches the pre-hook state. untracked files (e.g. a `.env`
+ * the hook materialized from a template) are left alone — the agent decides
+ * what to do with them. skipped (with a warning) when the tree had
+ * pre-existing tracked changes before the hook ran, so pre-existing work
+ * is never clobbered. idempotent: a second call on a clean tree is a no-op
+ * and stays quiet.
+ */
+async function normalizeWorkingTreeAfterHook(params: {
+  event: string;
+  preHookTrackedCount: number;
+}): Promise<void> {
+  if (params.preHookTrackedCount > 0) {
+    log.warning(
+      `» working tree had ${params.preHookTrackedCount} pre-existing tracked changes before ${params.event} hook; ` +
+        `skipping post-hook normalization to avoid clobbering pre-existing work`,
+    );
+    return;
+  }
+  const trackedCount = (await runGitLines(["diff", "--name-only", "HEAD"])).length;
+  if (trackedCount === 0) return;
+  await runGit(["restore", "--staged", "--worktree", "."]);
+  log.info(`» discarded ${trackedCount} tracked changes from ${params.event} hook`);
+}
+
+async function runGit(args: string[]): Promise<string> {
+  const result = await spawn({ cmd: "git", args, env: process.env, activityTimeout: 0 });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `git ${args.join(" ")} failed (exit ${result.exitCode}): ${result.stderr.trim() || "(no stderr)"}`,
+    );
+  }
+  return result.stdout;
+}
+
+async function runGitLines(args: string[]): Promise<string[]> {
+  return (await runGit(args)).split("\n").filter(Boolean);
+}