infraweaver 0.1.0

package/dist/utils/apiKeys.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Validate that the resolved model can actually be served by the chosen
+ * agent. For routing slugs (Bedrock / Vertex) the auth shape is multi-var
+ * (auth + region/location + model-id) and `opencode models` doesn't catch
+ * gaps in the latter two — keep dedicated setup validators. For the
+ * opencode path, the authoritative answer comes from OpenCode's own model
+ * introspection (`authorized` set captured in `openCodeModels.ts`). For
+ * the claude path, fall back to the static check (`ANTHROPIC_API_KEY` /
+ * `CLAUDE_CODE_OAUTH_TOKEN`).
+ */
+export declare function validateAgentApiKey(params: {
+    agent: {
+        name: string;
+    };
+    model: string | undefined;
+    authorized: Set<string>;
+    owner: string;
+    name: string;
+}): void;
+/**
+ * Detect agent-runtime auth failures that should be reformatted as an actionable
+ * key-fix CTA before being shown to the user. Covers the shapes we see:
+ *   - missing key (validateAgentApiKey throw): contains MISSING_KEY_MARKER
+ *   - revoked / invalid key (Claude CLI 401 surfaced via api_error_status):
+ *     "Invalid API key · Fix external API key" + similar provider variants
+ *   - direct-Anthropic 401 (`Failed to authenticate. API Error: 401 ...
+ *     {"type":"error","error":{"type":"authentication_error", ...
+ *     "Invalid bearer token"}}`) emitted by the Claude CLI for revoked /
+ *     mistyped / rotated `ANTHROPIC_API_KEY`. see #782.
+ */
+export declare function isApiKeyAuthError(text: string): boolean;
+/**
+ * A subscription/OAuth credential (Claude `CLAUDE_CODE_OAUTH_TOKEN`, Codex OAuth, or a
+ * short-lived Bedrock bearer) that has EXPIRED — distinct from a rejected/mistyped key.
+ * The fix is to refresh/re-mint the credential, not rotate an API key, so it gets its
+ * own CTA in {@link formatApiKeyErrorSummary}.
+ */
+export declare function isOAuthCredentialExpiredError(text: string): boolean;
+/**
+ * Friendly Markdown summary for both the missing-key and invalid-key cases.
+ * Used in the catch / result-failure paths in `main.ts` to overwrite the raw
+ * agent error before it's posted to the PR progress comment.
+ */
+export declare function formatApiKeyErrorSummary(params: {
+    owner: string;
+    name: string;
+    raw: string;
+}): string;

package/dist/utils/apiUrl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * resolve the Infraweaver API base URL. validation (https enforcement, the
+ * bearer-credential host allowlist, API_ALLOWED_HOSTS) lives in
+ * cloudFetchCore.ts so the stdlib-only post hook enforces the same policy.
+ */
+export declare function getApiUrl(): string;
+/**
+ * Whether a real Infraweaver backend is configured.
+ *
+ * Standalone BYOK runs (the OSS default) leave `API_URL` unset — `getApiUrl`
+ * then falls back to the marketing host, which serves no API. The dormant
+ * open-core persistence seams (repo learnings, run-field PATCHes) must no-op
+ * in that case rather than POST into the void and surface the host's 404 as a
+ * CI warning. A real backend — the hosted SaaS, or local dev with
+ * `API_URL=http://localhost:3000` — sets `API_URL` explicitly.
+ */
+export declare function isBackendConfigured(): boolean;
+/**
+ * The OIDC audience the tokenless path requests via `core.getIDToken(...)`.
+ *
+ * The default `"infraweaver-api"` is NOT the security boundary (the GitHub App
+ * install-consent gate is — Cloud only mints for an owner that installed the App). It
+ * is defence-in-depth, and is operator-overridable per deployment: set
+ * `GITHUB_OIDC_AUDIENCE` on BOTH the Cloud (its `expectedOidcAudience()` reads the same
+ * var) AND the engine's Action job env. Both must agree or OIDC auth fails closed.
+ * Single-source so all three engine call sites can never drift from the Cloud default.
+ */
+export declare function cloudOidcAudience(): string;

package/dist/utils/assets.d.ts

@@ -0,0 +1,8 @@
+/**
+ * downloads any github-hosted image/video assets referenced in `markdown` to
+ * `<tmpdir>/assets` and rewrites the urls to the local file paths, so the agent can
+ * read screenshots directly instead of relying on remote (often short-lived, signed)
+ * urls. unique urls are downloaded once and every occurrence is rewritten. assets that
+ * fail to download are left untouched.
+ */
+export declare function downloadAssetsInMarkdown(markdown: string, tmpdir: string, githubToken: string): Promise<string>;

package/dist/utils/baseRefConfig.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Trust boundary for the repo-committed `.infraweaver.yml` on a PULL-REQUEST run.
+ *
+ * THE PROBLEM. `.infraweaver.yml` is read from the checked-out ref, which on a PR
+ * run is the PR's own head. Most of the run's shape is already out of reach —
+ * `push`, `shell`, `allow_replace` and the `*_instructions` are deliberately not
+ * file-readable, because "the run's shape belongs to the workflow that
+ * dispatches it" ([[infraweaverConfig]]). But several keys that ARE file-readable
+ * decide how strictly the run judges the code, and a PR that edits them is
+ * editing the gates that judge that same PR:
+ *
+ *   allowed_paths / protected_paths  → what the fix loop may write
+ *   required_controls                → which controls must be clean to pass
+ *   severity_threshold               → what counts as reportable at all
+ *   autonomy_threshold               → what escalates to a human
+ *   tools_enabled                    → which scanners run
+ *   scan_scope / iac_languages       → how much of the tree is looked at
+ *   suppressions                     → which findings are silenced outright
+ *
+ * None of these is an arbitrary-code-execution hole, and GitHub already defangs
+ * the fork case (read-only token, no secrets on `pull_request`). A workflow
+ * input also always wins over the file. But "the workflow author remembered to
+ * pin it" is not a control, and a same-repo PR silencing the finding that would
+ * have blocked it is a plausible, quiet failure.
+ *
+ * THE RULE. On a PR-triggered run these come from the BASE ref — the reviewed
+ * state of the branch being merged into. Everything else (prose language,
+ * grouping, the advisory module catalogue) still comes from the head, because
+ * none of it can weaken a verdict.
+ *
+ * This is the same principle as the shipped two-person SoD on waivers (§5.3): a
+ * suppression takes effect once someone other than its author has accepted it —
+ * here, by merging it. A PR that adds a waiver still SEES the finding it waives;
+ * the waiver applies from the next run on the merged base.
+ *
+ * HONEST DEGRADE. When the base ref can't be read (a shallow clone with no
+ * `origin/<base>`, a non-PR run, no git at all), the head value is used and the
+ * fact is stated for the run summary. Failing the run would turn a hardening
+ * measure into an outage on every shallow-checkout workflow; silently preferring
+ * the head with no record would be the dishonesty this codebase avoids
+ * everywhere else. So: use it, and say so.
+ *
+ * DIRECTION IS NOT INSPECTED. A PR that *tightens* a gate also defers to the
+ * base value — not because tightening is dangerous, but because "which value
+ * applies" must not depend on a per-key notion of stricter/looser that we would
+ * have to get right for every key forever. The new value takes effect on merge,
+ * which is when the reviewed state actually changes.
+ */
+import { type InfraweaverFileValues } from "#app/utils/infraweaverConfig";
+/**
+ * The file-readable keys that can weaken a verdict. Deliberately enumerated
+ * rather than derived by exclusion, and paired with
+ * {@link PRESENTATIONAL_CONFIG_KEYS} so that every key in
+ * `INFRAWEAVER_CONFIG_KEYS` is classified exactly once — `baseRefConfig.test.ts`
+ * asserts that partition, so a key added later cannot silently default to
+ * "PR-controllable".
+ */
+export declare const GATE_RELEVANT_CONFIG_KEYS: readonly ["allowed_paths", "protected_paths", "required_controls", "severity_threshold", "autonomy_threshold", "tools_enabled", "scan_scope", "iac_languages"];
+/**
+ * Keys a PR may set from its own head: none can hide a finding, relax a
+ * guardrail, or shrink what is scanned. `language` is prose only; `grouping` is
+ * presentation; `module_catalogue` is an advisory list the fixer may prefer
+ * from, never a gate.
+ */
+export declare const PRESENTATIONAL_CONFIG_KEYS: readonly ["language", "grouping", "module_catalogue"];
+/** What the base ref had to say about `.infraweaver.*`. */
+export type BaseConfigSource = 
+/** the base ref itself could not be resolved (shallow clone, no git, non-PR). */
+{
+    kind: "unavailable";
+}
+/** the base ref resolved and carries NO config file — so no file-level policy. */
+ | {
+    kind: "absent";
+    ref: string;
+} | {
+    kind: "file";
+    ref: string;
+    raw: string;
+    format: "yaml" | "json";
+};
+/** Drop the base-ref read cache — tests only. */
+export declare function resetBaseConfigCache(): void;
+/**
+ * Read `.infraweaver.*` as it exists on the PR's base ref.
+ *
+ * The `absent` / `unavailable` distinction is load-bearing: "the base has no
+ * config" legitimately means *no file-level policy applies*, so a PR that ADDS
+ * one is correctly ignored. "We could not look" must never be read that way, or
+ * a shallow clone would silently drop a real policy.
+ */
+export declare function readConfigAtBaseRef(cwdOrUndefined: string | undefined, baseRef: string | undefined): BaseConfigSource;
+export interface BaseRefConfigResult {
+    /** the config to use, gate keys taken from the base ref where available. */
+    values: InfraweaverFileValues;
+    /** human-readable notes for the run log: what was overridden, or why not. */
+    notes: string[];
+}
+/**
+ * Layer the base ref's gate-relevant keys over the head's config. `headValues`
+ * is what `loadInfraweaverConfig` already read from the checked-out tree; on a
+ * non-PR run (or when the base can't be resolved) it comes back unchanged.
+ */
+export declare function resolveConfigAcrossRefs(args: {
+    cwd: string | undefined;
+    headValues: InfraweaverFileValues;
+    /** the PR's base branch — `GITHUB_BASE_REF`; empty/undefined on a non-PR run. */
+    baseRef: string | undefined;
+    /** injectable for tests; defaults to the real git read. */
+    readBase?: (cwd: string | undefined, baseRef: string | undefined) => BaseConfigSource;
+}): BaseRefConfigResult;
+/**
+ * `resolveConfigAcrossRefs` + logging, for the one call site in `resolvePayload`.
+ * Notes are warnings, not info: a divergence belongs in the run summary rather
+ * than buried in debug output.
+ */
+export declare function applyBaseRefConfigPolicy(args: {
+    cwd: string | undefined;
+    headValues: InfraweaverFileValues;
+    baseRef: string | undefined;
+}): InfraweaverFileValues;

package/dist/utils/billingErrors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Billing-error classification + user-facing copy for `/api/proxy-token`
+ * failures and OpenRouter mid-run exhaustion. Two error classes (Billing vs.
+ * Transient) keep the framing honest: a card decline is *not* the same UX as
+ * a 503 from the proxy service. Both originate in `utils/proxy.ts` (mint
+ * failures) and `utils/runErrorRenderer.ts` (mid-run keylimit reclassify).
+ *
+ * Renderers return markdown bodies that are written into both the GitHub
+ * Actions job summary and the PR progress comment.
+ *
+ * Lives outside `main.ts` so adding a new error `code` branch is a one-file
+ * edit that does not retrigger the full LLM CI matrix (`action/main.ts` is
+ * in `action/test/coverage.ts::ALWAYS_RUN_ALL`).
+ */
+/**
+ * Billing-layer error surfaced from `/api/proxy-token` as a 402. User-actionable
+ * — distinct from TransientError (503 / transient sync issue) so the job
+ * summary + PR comment can use affirmative "you need to do X" copy rather than
+ * the ambiguous "billing error" label that makes transient outages look like
+ * the user's fault.
+ *
+ * `code` is a server-side discriminator: `router_requires_card` (no card + no
+ * wallet balance on Router), or null for unclassified. `declineCode` is
+ * Stripe's more specific sub-reason on `card_declined` (e.g.
+ * `insufficient_funds`, `lost_card`). `needsReauthentication` is the 3DS case
+ * broken out for convenience.
+ */
+export declare class BillingError extends Error {
+    code: string | null;
+    declineCode: string | null;
+    needsReauthentication: boolean;
+    constructor(message: string, opts?: {
+        code?: string | null;
+        declineCode?: string | null;
+        needsReauthentication?: boolean;
+    });
+}
+/**
+ * Transient service failures from `/api/proxy-token` (503: partial OpenRouter
+ * usage sync, DB flake, in-flight payment intent). Not the user's fault — the
+ * summary uses "temporarily unavailable" framing, and the non-zero exit lets
+ * GH Actions apply whatever retry policy the workflow has configured.
+ */
+export declare class TransientError extends Error {
+    constructor(message: string);
+}
+/**
+ * Render a BillingError as user-facing markdown (shared between GH job summary
+ * and the PR progress comment). Goals:
+ *
+ *   - quiet, not alarmist — bold first line instead of an `### ❌` H3, since
+ *     the comment already has Infraweaver branding in the footer
+ *   - actionable — every branch ends in a single CTA deep-linked to the
+ *     correct section of the owner's console
+ *   - honest — say what actually went wrong (card declined vs. balance
+ *     empty vs. 3DS required), don't lump them under "billing error"
+ *
+ * Branches:
+ *   - `router_requires_card`: user is on Router mode with no card AND no
+ *     wallet balance (signup credit exhausted or not granted). Frame as
+ *     "add a card to continue", link to `#model-access` where the Add
+ *     Card flow lives.
+ *   - `router_balance_exhausted`: user has a card on file but auto-reload is
+ *     disabled and they've spent past their $5 overdraft buffer. Frame as
+ *     "balance ran out" and surface both remediation paths (top up, or flip
+ *     on auto-reload).
+ *   - `router_keylimit_exhausted`: OpenRouter rejected mid-run because the
+ *     per-run key budget was exhausted while the agent was working. The
+ *     wallet is now negative; same remediation as `router_balance_exhausted`
+ *     but framed for the after-the-fact case ("this run was cut short").
+ *   - `needsReauthentication`: issuer requires 3DS on every off-session
+ *     charge. Re-adding the card won't help — the only escape is a manual
+ *     top-up where 3DS runs interactively in Stripe Checkout.
+ *   - `declineCode` set: Stripe declined a real charge. Show the sub-code
+ *     so support can act on it; tell the user we'll retry on next dispatch.
+ *   - default: balance hit zero with no in-flight charge (auto-reload off
+ *     or amount below threshold). Direct them to top up or enable auto-reload.
+ */
+export declare function formatBillingErrorSummary(error: BillingError, owner: string): string;
+/**
+ * Render a TransientError as user-facing markdown. Distinct framing from
+ * BillingError so the user doesn't read an alarm and assume their card
+ * failed — this branch is "our fault, retry shortly", not theirs.
+ */
+export declare function formatTransientErrorSummary(error: TransientError, owner: string): string;

package/dist/utils/body.d.ts

@@ -0,0 +1,34 @@
+import type { PayloadEvent } from "#app/external";
+import type { OctokitWithPlugins } from "#app/utils/github";
+import type { RunContextData } from "#app/utils/runContextData";
+interface ResolveBodyContext {
+    event: PayloadEvent;
+    octokit: OctokitWithPlugins;
+    repo: RunContextData["repo"];
+    tmpdir: string;
+    githubToken: string;
+}
+/**
+ * resolves the body of an event by fetching body_html and converting to markdown.
+ * only fetches body_html if the body contains images (to avoid unnecessary API calls).
+ * this ensures agents receive markdown with working signed image URLs instead of
+ * broken user-attachments URLs.
+ */
+export declare function resolveBody(ctx: ResolveBodyContext): Promise<string | null>;
+interface ResolveBodyAssetsContext {
+    body: string | null | undefined;
+    bodyHtml: string | null | undefined;
+    tmpdir: string;
+    githubToken: string;
+}
+/**
+ * downloads github-hosted image assets in a body to disk and rewrites the urls to local
+ * paths so the agent can read them. when the body has images and a rendered `bodyHtml`
+ * is supplied, the html is turndowned first: github only exposes attachments as signed,
+ * self-authenticating `*.githubusercontent.com` urls through body_html — the raw
+ * `github.com/user-attachments/...` urls in unrendered markdown 404 for the installation
+ * token. callers that fetch a body should request it with the `application/vnd.github.full+json`
+ * media type and pass `body_html` here.
+ */
+export declare function resolveBodyAssets(ctx: ResolveBodyAssetsContext): Promise<string | null>;
+export {};

package/dist/utils/buildInfraweaverFooter.d.ts

@@ -0,0 +1,29 @@
+import type { UserFacingLanguage } from "#app/utils/payload";
+export declare const INFRAWEAVER_DIVIDER = "<!-- INFRAWEAVER_DIVIDER_DO_NOT_REMOVE_PLZ -->";
+export interface BuildInfraweaverFooterParams {
+    /** add "via Infraweaver" link */
+    triggeredBy?: boolean;
+    /** arbitrary custom parts (e.g., action links) */
+    customParts?: string[] | undefined;
+    /** model slug from payload (e.g., "anthropic/claude-opus"). shown in footer as "Using `Model Name`" */
+    model?: string | undefined;
+    /**
+     * When the action engaged the BYOK fallback, this is the slug the user
+     * had configured (e.g. "anthropic/claude-opus") — the footer renders
+     * `Using <free model> (credentials for <configured> not configured)`
+     * so the substitution is visible in PR comments + reviews.
+     */
+    fallbackFrom?: string | undefined;
+    /** user-facing language for the fixed "Using" verb (default English); the
+     * model name + product attribution stay verbatim regardless. */
+    language?: UserFacingLanguage | undefined;
+}
+/**
+ * build a infraweaver footer with configurable parts
+ * order: action links (customParts) > model > attribution
+ */
+export declare function buildInfraweaverFooter(params: BuildInfraweaverFooterParams): string;
+/**
+ * strip any existing infraweaver footer from a comment body
+ */
+export declare function stripExistingFooter(body: string): string;

package/dist/utils/byokFallback.d.ts

@@ -0,0 +1,85 @@
+import type { AgentId } from "#app/external";
+/**
+ * Slug we fall back to when a BYOK-required model is configured but the
+ * runner has no provider key in env. Picked because it's free, stable, and
+ * currently served by OpenCode Zen without a key.
+ *
+ * The slug is intentionally hard-coded and not a config knob — the
+ * fallback is a safety net, not a user-facing preference, and adding a
+ * config surface here would just push the same "what to fall back to"
+ * decision into another setting that goes stale the same way.
+ */
+export declare const FREE_FALLBACK_SLUG = "opencode/big-pickle";
+/**
+ * Outcome of the BYOK model gate.
+ *
+ *   - `use-resolved`: run the configured model as-is.
+ *   - `fallback`: the runner has NO provider key for this model's provider,
+ *     so swap to the free OpenCode slug — a genuine no-key safety net.
+ *   - `unavailable`: a provider key IS present but the configured model is
+ *     not one OpenCode can route with it. This is almost always a wrong or
+ *     mistyped model id (or a key scoped to other models). We must NOT
+ *     silently downgrade to the free model — that hides the misconfiguration
+ *     and produces a free run the user didn't ask for (see PR #2). The caller
+ *     fails loudly with the authorized-model list instead.
+ */
+export type FallbackDecision = {
+    kind: "use-resolved";
+} | {
+    kind: "fallback";
+    from: string;
+    to: string;
+} | {
+    kind: "unavailable";
+    model: string;
+};
+/**
+ * Does the runner have a provider credential for `resolvedModel`'s provider?
+ *
+ * Uses the provider→envVars map in `models.ts` (provider-level, since a
+ * resolved specifier like `google/gemini-3.5-flash-lite` won't match a catalog
+ * model key and correctly falls through to the provider's env vars). A present
+ * key is what distinguishes the two not-authorized situations: key present =
+ * wrong/unavailable model id (fail loudly); no key = genuine BYOK gap (free
+ * fallback).
+ */
+export declare function hasProviderKeyForModel(resolvedModel: string): boolean;
+/**
+ * Decide whether to run the configured model, fall back to the free model, or
+ * fail because the model is unavailable to the present key.
+ *
+ * `authorized` is OpenCode's authoritative "what can I route right now"
+ * snapshot, captured after Codex auth.json is in place.
+ *
+ * Skip cases (always `use-resolved`, without consulting `authorized`):
+ *   - No resolved model: auto-select handles it downstream.
+ *   - Resolved model is the free fallback already.
+ *   - Resolved model is a raw Bedrock / Vertex ID (no `/`): the routing
+ *     validators (`validateBedrockSetup` / `validateVertexSetup`) cover
+ *     auth + region/location/model-id; `opencode models` does not.
+ *   - The selected agent is `claude`: the Claude Code harness brings its own
+ *     auth and `resolveAgent` only returns it when that auth is present.
+ *     `opencode models` can't see `CLAUDE_CODE_OAUTH_TOKEN`, so without this
+ *     an OAuth-subscription run on an Anthropic model would land in
+ *     `unavailable` (the token counts as a present provider key) and fail a
+ *     run the claude harness serves fine. `validateAgentApiKey` still covers
+ *     the claude path with its own Anthropic auth check.
+ */
+export declare function selectFallbackModelIfNeeded(input: {
+    resolvedModel: string | undefined;
+    authorized: Set<string>;
+    /** whether a provider key for the resolved model's provider is present in env */
+    providerKeyPresent: boolean;
+    /** which agent harness `resolveAgent` picks for the resolved model */
+    agentName: AgentId;
+}): FallbackDecision;
+/**
+ * Loud, actionable error for the `unavailable` decision: a provider key is
+ * present but the configured model isn't one the key can serve. Lists the
+ * models OpenCode CAN route (same-provider first) so the user can copy a valid
+ * slug instead of getting a silent free downgrade.
+ */
+export declare function buildUnavailableModelError(input: {
+    model: string;
+    authorized: Set<string>;
+}): string;

package/dist/utils/changeImpact.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Deterministic change-impact leads for Terraform review.
+ *
+ * On `checkout_pr` we hand the reviewer a supplemental, EXPLICITLY INCOMPLETE
+ * list of where the PR's changed HCL declarations are referenced elsewhere in
+ * the repo — the blast radius the raw diff alone doesn't show. It is a lead
+ * list, never a coverage source: an empty artifact is not evidence of no wider
+ * impact, and the authoritative diff read still governs the review.
+ *
+ * IaC-specific (vs. pullfrog's generic symbol grep): we extract only unambiguous
+ * HCL declarations from the diff and grep their canonical REFERENCE form, so the
+ * hits are real dependency edges rather than incidental identifier collisions:
+ *   variable "x"        → `var.x`
+ *   output   "x"        → `module.<caller>.x` (regex; same-repo callers only)
+ *   resource "t" "n"    → `t.n`
+ *   data     "t" "n"    → `data.t.n`
+ *   module   "x"        → `module.x`
+ *
+ * All greps are word-bounded (`git grep -w`) so `var.env` doesn't match
+ * `var.environment` and `aws_s3_bucket.this` doesn't match `..._this_backup`.
+ *
+ * The whole thing is best-effort: any failure degrades to "no artifact", never
+ * a failed checkout.
+ */
+export type ChangeKind = "added" | "removed";
+export interface ChangeLocation {
+    path: string;
+    line: number;
+    kind: ChangeKind;
+}
+export interface ChangeImpactAtom {
+    /** the declaration kind, for the artifact heading. */
+    declaration: "variable" | "output" | "resource" | "data" | "module";
+    /** human label, e.g. `var.instance_type` or `aws_s3_bucket.this`. */
+    label: string;
+    /** the pattern grepped (word-bounded) across `*.tf` / `*.tfvars`; also the dedup key. */
+    ref: string;
+    /** when true, `ref` is a POSIX regex (`git grep -E`); otherwise a fixed string (`-F`). */
+    regex?: boolean;
+    /** where in the diff this declaration was touched (first added or removed). */
+    where: ChangeLocation;
+}
+export interface GrepHit {
+    path: string;
+    line: number;
+    text: string;
+}
+/** a changed file, as returned by the GitHub pulls.listFiles API. */
+export interface ChangedFile {
+    filename: string;
+    patch?: string | undefined;
+    previous_filename?: string | undefined;
+}
+/**
+ * Walk each changed file's unified-diff patch, pulling out the HCL declarations
+ * that were added or removed and the set of added-line keys (so grep hits that
+ * land on the PR's own new lines can be excluded — impact means EXISTING code
+ * that references the changed thing).
+ */
+export declare function extractTerraformAtoms(files: ChangedFile[]): {
+    atoms: ChangeImpactAtom[];
+    addedLines: Set<string>;
+};
+/**
+ * Render the artifact from already-collected grep hits. Pure: the caller
+ * supplies the reference hits per atom (via a real `git grep` at runtime, or a
+ * stub in tests). Bounded by MAX_REFS_PER_ATOM and MAX_BYTES.
+ */
+export declare function renderChangeImpactArtifact(params: {
+    atoms: ChangeImpactAtom[];
+    hitsByRef: Map<string, GrepHit[]>;
+    addedLines: Set<string>;
+    baseSha: string;
+    headSha: string;
+    fileCount: number;
+    lookupError?: string | undefined;
+}): {
+    content: string;
+    atomCount: number;
+    referenceCount: number;
+};
+/** parse `git grep -n` porcelain (`path:line:text`) into hits. */
+export declare function parseGrepHits(output: string): GrepHit[];
+/**
+ * Runtime entry point: extract the changed declarations, grep the checked-out
+ * head for pre-existing references to each, and write the artifact to tmpdir.
+ * Returns null when there's nothing worth writing (no TF declarations changed).
+ * Callers treat a thrown error as "no artifact" — this must never fail checkout.
+ */
+export declare function createChangeImpactArtifact(params: {
+    files: ChangedFile[];
+    tmpdir: string;
+    pullNumber: number;
+    baseSha: string;
+    headSha: string;
+}): {
+    path: string;
+    atomCount: number;
+    referenceCount: number;
+    bytes: number;
+} | null;

package/dist/utils/claudeSubscription.d.ts

@@ -0,0 +1,30 @@
+export type SubscriptionPreflight = {
+    usable: true;
+} | {
+    usable: false;
+    reason: string;
+};
+/**
+ * preflight a Claude subscription OAuth token (`CLAUDE_CODE_OAUTH_TOKEN`)
+ * with a 1-token Messages call, so the agent can fall back to
+ * `ANTHROPIC_API_KEY` when the subscription is exhausted or revoked instead
+ * of failing the whole run at its first model call. rides the same de-facto
+ * OAuth surface Claude Code itself uses: Bearer auth + the
+ * `claude-code-20250219,oauth-2025-04-20` betas + the identity system prompt.
+ *
+ * probes the run's own model when known — subscription limits can be
+ * per-model ("You've hit your Opus limit"), so a cheaper stand-in could pass
+ * preflight and still leave the run dead on arrival.
+ *
+ * fail-open by design: only 401 (revoked/expired token) and 429
+ * (session/weekly/per-model limit) mark the token unusable. network errors,
+ * 5xx, and request-shape drift (400) all keep today's subscription-first
+ * behavior, so the preflight can never fail a run that would have worked —
+ * the worst wrong answer is a run that bills the API key instead of the
+ * subscription.
+ */
+export declare function preflightClaudeSubscription(params: {
+    token: string;
+    /** bare Anthropic model id the run will use (e.g. "claude-fable-5") */
+    model: string | undefined;
+}): Promise<SubscriptionPreflight>;

package/dist/utils/cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI utilities
+ */
+export { formatIndentedField, formatJsonValue, formatUsageSummary, log, writeSummary, } from "#app/utils/log";
+/**
+ * Finds a CLI executable path by checking if it's installed globally
+ * @param name The name of the CLI executable to find
+ * @returns The path to the CLI executable, or null if not found
+ */
+export declare function findCliPath(name: string): string | null;

package/dist/utils/cloudClient.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Thin typed seam over `apiFetch` for the Infraweaver Cloud routes.
+ *
+ * Consumers previously hand-built each request: the `Authorization: Bearer`
+ * header (with `Authorization`/`authorization` casing drift), JSON serialization
+ * + content-type, and the timeout were re-inlined at every call site. This owns
+ * those three pieces once and returns the raw `Response`, so each caller keeps
+ * its own status/JSON/retry handling.
+ *
+ * The stdlib-only post hook (`entryPost.ts`) intentionally does NOT use this —
+ * it calls `cloudFetchCore` directly to stay free of node_modules imports.
+ */
+/** The one home for the bearer header — the org JWT (`apiToken`), a GitHub App
+ *  installation token, or an OIDC id-token, depending on the route. */
+export declare function bearer(credential: string): {
+    Authorization: string;
+};
+export type CloudRequest = {
+    path: string;
+    method?: string | undefined;
+    /** bearer token for the `Authorization` header; omit for an unauthenticated call. */
+    credential?: string | undefined;
+    /** extra headers beyond `Authorization` (e.g. `X-GitHub-OIDC-Token`). */
+    headers?: Record<string, string> | undefined;
+    /** a JSON body — serialized here, with `content-type: application/json` set. */
+    json?: unknown;
+    /** a pre-serialized body (used when the body is not JSON). */
+    body?: string | undefined;
+    /** request timeout in ms; defaults to the shared cloud ceiling. */
+    timeoutMs?: number | undefined;
+};
+/** Issue an authenticated Cloud API request; returns the raw `Response`. */
+export declare function cloudRequest(req: CloudRequest): Promise<Response>;

package/dist/utils/cloudFetchCore.d.ts

@@ -0,0 +1,42 @@
+/**
+ * stdlib-only Infraweaver API fetch core (no node_modules) — shared by
+ * `apiFetch` (the main runtime wrapper) and `entryPost.ts` (the GHA `post:`
+ * hook, which runs directly from the action checkout without node_modules;
+ * see entryPost.stdlibOnly.test.ts). Owns everything the two callers
+ * previously kept in lockstep by hand: the default API host, the
+ * bearer-credential host allowlist, the Vercel bypass secret, and the
+ * default request timeout.
+ */
+import { DEFAULT_API_URL } from "#app/brand";
+export { DEFAULT_API_URL };
+/**
+ * Ceiling for Cloud API calls that don't bring their own AbortSignal — a
+ * stalled backend must never hang the action (or its post hook) indefinitely.
+ * Callers with tighter or looser needs pass an explicit `signal`.
+ */
+export declare const DEFAULT_CLOUD_TIMEOUT_MS = 30000;
+/**
+ * resolve the Infraweaver API base URL.
+ *
+ * in the action: API_URL is not explicitly set, so this falls back to
+ * DEFAULT_API_URL. in local dev: API_URL=http://localhost:3000 (from .env).
+ *
+ * enforces https:// for non-local URLs to prevent cleartext credential
+ * transmission.
+ */
+export declare function resolveApiUrl(): string;
+export type CloudFetchOptions = {
+    path: string;
+    method?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    body?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+/**
+ * fetch against the Infraweaver API with Vercel deployment protection bypass.
+ *
+ * adds the bypass secret as BOTH a query parameter and a header for maximum
+ * reliability. the server-side forwarding code uses query params, and the
+ * Vercel docs say both work, so we do both as belt-and-suspenders.
+ */
+export declare function cloudFetch(options: CloudFetchOptions): Promise<Response>;