infraweaver 0.1.0

package/dist/utils/cloudReport.d.ts

@@ -0,0 +1,114 @@
+import { type Concern } from "#app/mcp/terraform/types";
+export { cyberEssentialsScore } from "#app/mcp/cyberEssentials";
+import type { ToolState } from "#app/toolState";
+import { cloudOidcAudience } from "#app/utils/apiUrl";
+export { cloudOidcAudience };
+/**
+ * Resolve the credential to authenticate the Cloud report with, in order of
+ * preference:
+ *   1. An explicit `tmnd_` org token (the `api_token` input).
+ *   2. A GitHub Actions OIDC token — the tokenless GitHub App path. Requires
+ *      `permissions: id-token: write`; the App installation is the consent gate
+ *      Cloud checks. Returns undefined when neither is available (pure OSS run).
+ */
+export declare function resolveCloudCredential(apiToken: string | undefined): Promise<string | undefined>;
+/**
+ * Ingest seam — POST a finished run's findings/posture to Infraweaver Cloud
+ * so the dashboard reflects this repo. This is the explicit ORG-TOKEN path: the
+ * caller passes the `tmnd_` token (the `api_token` input); the tokenless GitHub
+ * App path reports differently and standalone OSS runs don't report at all.
+ *
+ * The wire shape matches infraweaver-ui `reportSchema`
+ * (src/features/api/schemas.ts) — kept in sync by hand across the action ⇄ cloud
+ * JSON boundary (the two codebases can't share types).
+ */
+export type CloudPosture = "clean" | "advisory" | "action-required";
+/** Posture from the open concern set — any critical/high ⇒ action-required. */
+export declare function derivePosture(concerns: Concern[]): CloudPosture;
+/** the Cloud-bound refactor (modularise) verdict, mirrors infraweaver-ui
+ *  reportSchema.run.refactor.equivalence_verdict. */
+export type RefactorVerdict = "equivalence-proven" | "equivalence-failed" | "proposed-unproven";
+/**
+ * The refactor (modularise) proof for the Cloud report, or undefined on a
+ * non-refactor run (so the wire omits it). Built from the recorded keys-free
+ * EQUIVALENCE proof when one ran (b.1/b.2/b.3), else the b.4 `proposed — unproven`
+ * marker — an equivalence proof always wins, so a change is never both. Asserts
+ * only what the engine proved: a failed/absent proof is reported as such, never
+ * upgraded. Pure over `toolState`. Mirrors infraweaver-ui reportSchema.run.refactor.
+ */
+export declare function buildRefactorReport(toolState: ToolState): {
+    equivalence_verdict: RefactorVerdict;
+    proposed_unproven: boolean;
+    moved_block_count: number;
+    uncovered_moves: number;
+} | undefined;
+/** Build the `/report` request body from the finished run's tool state. Exported
+ *  for tests; pure (reads only `toolState` + GitHub env). */
+export declare function buildReportBody(toolState: ToolState): {
+    commit_sha: string | undefined;
+    posture: CloudPosture;
+    ce_score: number;
+    prs_open: number | undefined;
+    findings: {
+        concern_id: string;
+        concern_key: string;
+        source: "checkov" | "infraweaver" | "reviewer" | "terraform-fmt" | "terraform-validate" | "tflint" | "trivy";
+        rule_id: string;
+        severity: "critical" | "high" | "info" | "low" | "medium";
+        category: "correctness" | "cost" | "security" | "style";
+        evidence: string;
+        file: string;
+        line: number | undefined;
+        remediation_hint: string | undefined;
+        code_snippet: string | undefined;
+        doc_url: string | undefined;
+        compliance: string[];
+        risk_score: number;
+        suppressed?: true;
+        suppression_reason?: string;
+        suppression_source?: "inline" | "policy";
+        suppression_expires?: string | undefined;
+    }[];
+    proven_fixes?: {
+        finding_type: string;
+        source: string | undefined;
+        canonical_class: string | undefined;
+        category: string;
+        title: string;
+        description: string | undefined;
+        remediation_hint: string | undefined;
+        before_example: string | undefined;
+    }[];
+    proven_transforms?: import("#app/mcp/terraform/transformPacks").ProvenTransform[];
+    run: {
+        run_number: number | undefined;
+        external_run_id: string | undefined;
+        mode: string | undefined;
+        trigger: string | undefined;
+        status: "success";
+        engine_crosswalk_version: string;
+        refactor?: {
+            equivalence_verdict: RefactorVerdict;
+            proposed_unproven: boolean;
+            moved_block_count: number;
+            uncovered_moves: number;
+        };
+    };
+};
+/**
+ * Best-effort report of this run to Infraweaver Cloud. No-ops (silently) when:
+ *   - `API_URL` unset — standalone BYOK; don't POST into the marketing host.
+ *   - no scan ran (`lastScanConcerns` undefined) — nothing to report.
+ *   - no credential — neither an `api_token` nor a mintable GitHub Actions OIDC
+ *     token (no `id-token: write`); the run stays pure OSS.
+ * A network/Cloud failure is logged at debug and swallowed — reporting must
+ * never flip an already-successful run outcome.
+ */
+export declare function reportToCloud(input: {
+    toolState: ToolState;
+    repo: {
+        owner: string;
+        name: string;
+    };
+    apiToken: string | undefined;
+}): Promise<void>;

package/dist/utils/codexHome.d.ts

@@ -0,0 +1,29 @@
+/** sandbox-hidden home for infraweaver-managed on-disk secrets in CI. bash via
+ * MCP shell tmpfs-overlays this path; opencode's internal auth module
+ * bypasses external_directory and reaches the real file. mirrors the
+ * pattern in action/agents/claude.ts installManagedSettings.
+ *
+ * not used for codex auth in local dev — the sandbox is no-op there, so
+ * the path doesn't matter. local dev keeps the existing $HOME path. */
+export declare const INFRAWEAVER_DATA_DIR = "/var/lib/infraweaver";
+export interface InstalledCodexAuth {
+    /** absolute path of the auth.json we wrote — caller passes this to the
+     * post-hook via core.saveState for refresh-detection later. */
+    authPath: string;
+    /** value to set as XDG_DATA_HOME for the OpenCode subprocess. */
+    xdgDataHome: string;
+    /** refresh_token from the env at materialization time. post-hook
+     * compares against the on-disk file after the run to detect whether
+     * OpenCode refreshed during the session (only happens on long runs
+     * that span >50min — see wiki/codex-auth.md "Concurrency"). */
+    originalRefresh: string;
+}
+/** materialize CODEX_AUTH_JSON from env into a disk path OpenCode reads from.
+ * returns null when the env var is absent, malformed, or wrong auth mode —
+ * caller treats null as "no codex auth, fall through to API key flow".
+ *
+ * The env value is read as-is — we parse + write it here and set
+ * `process.env.XDG_DATA_HOME` so every opencode subprocess discovers the
+ * auth.json; no refresh and no DB interaction. Freshness is the supplier's
+ * responsibility (see the header caveat on static-secret expiry). */
+export declare function installCodexAuth(): InstalledCodexAuth | null;

package/dist/utils/codexOAuth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure-stdlib (fetch + Buffer) Codex OAuth refresh + JWT exp decoding.
+ *
+ * Lives here (not in codexAuth.ts) so the Next.js server side can import it
+ * via infraweaver/internal without dragging in node:child_process / spawn /
+ * mkdtemp from the rest of codexAuth.ts. Used by:
+ *   - action/utils/codexAuth.ts (re-exports refreshCodexAuthBody)
+ *   - utils/codexSecretRotation.ts (server-side maybeRotate at run-context)
+ *
+ * See wiki/codex-auth.md for the end-to-end refresh lifecycle.
+ */
+export interface CodexAuthBody {
+    auth_mode: "chatgpt";
+    tokens: {
+        access_token: string;
+        refresh_token: string;
+        id_token?: string;
+        account_id?: string;
+    };
+    last_refresh?: string;
+}
+/** OAuth client id Codex CLI and OpenCode both use against `auth.openai.com`.
+ * Same chain — a refresh token minted via `codex login --device-auth` can be
+ * refreshed against this client_id. */
+export declare const CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
+/** thrown when the OAuth provider rejects the refresh token (4xx). callers
+ * can distinguish "race-lost / token revoked" from network errors via
+ * `instanceof OAuthInvalidGrantError`. */
+export declare class OAuthInvalidGrantError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+/** force one refresh round-trip against the OAuth provider. returns the
+ * rotated Codex-shaped blob (the auth.json body verbatim). does NOT persist
+ * — caller is responsible for writing back to wherever the token lives.
+ *
+ * server-side callers (maybeRotateCodexSecret) hold a DB row lock around
+ * this call so concurrent runs serialize: first one rotates, subsequent
+ * ones see the fresh value and skip. The 10s timeout is critical for that
+ * use: it caps how long a stalled auth.openai.com holds the row lock,
+ * keeping us well under the enclosing 30s transaction budget so the lock
+ * always releases and queued callers get a turn instead of timing out on
+ * the tx wrapper. Real OAuth latency is sub-second; 10s is generous. */
+export declare function refreshCodexAuthBody(body: CodexAuthBody): Promise<CodexAuthBody>;
+/** decode the access_token's JWT payload and return its `exp` claim in ms
+ * since epoch. returns null if the token isn't a parseable JWT or has no
+ * `exp` claim — caller falls back to "treat as expired".
+ *
+ * We don't verify the JWT signature (we'd need OpenAI's JWKS); we're only
+ * using the claim as a freshness hint. The actual auth check happens
+ * server-side at OpenAI when the token is used — trusting a fake JWT here
+ * would just delay the inevitable 401 from OpenAI. No security boundary
+ * at this decode step. */
+export declare function decodeJwtExpMs(token: string): number | null;
+/** parse + validate a Codex auth.json body from its JSON-string form.
+ * returns null on any shape mismatch — caller treats as "no codex auth". */
+export declare function parseCodexAuthBody(raw: string): CodexAuthBody | null;
+/** serialize a CodexAuthBody to its canonical on-disk form. */
+export declare function stringifyCodexAuthBody(body: CodexAuthBody): string;

package/dist/utils/diffCoverage.d.ts

@@ -0,0 +1,63 @@
+export type DiffLineRange = {
+    startLine: number;
+    endLine: number;
+};
+export type DiffTocEntry = {
+    filename: string;
+    startLine: number;
+    endLine: number;
+};
+export type DiffCoverageFileBreakdown = {
+    filename: string;
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+    coveredLines: number;
+    coveredRanges: DiffLineRange[];
+    unreadRanges: DiffLineRange[];
+};
+export type DiffCoverageBreakdown = {
+    totalLines: number;
+    coveredLines: number;
+    unreadLines: number;
+    coveragePercent: number;
+    coveredRanges: DiffLineRange[];
+    unreadRanges: DiffLineRange[];
+    files: DiffCoverageFileBreakdown[];
+};
+export type DiffCoverageState = {
+    diffPath: string;
+    totalLines: number;
+    tocEntries: DiffTocEntry[];
+    coveredRanges: DiffLineRange[];
+    coveragePreflightRan: boolean;
+    lastBreakdown?: string | undefined;
+};
+export declare function countLines(params: {
+    content: string;
+}): number;
+export declare function parseDiffTocEntries(params: {
+    toc: string;
+}): DiffTocEntry[];
+export declare function createDiffCoverageState(params: {
+    diffPath: string;
+    totalLines: number;
+    toc: string;
+    previous?: DiffCoverageState | undefined;
+}): DiffCoverageState;
+export declare function recordDiffReadFromToolUse(params: {
+    state: DiffCoverageState | undefined;
+    toolName: string;
+    input: unknown;
+    cwd: string;
+}): boolean;
+export declare function getDiffCoverageBreakdown(params: {
+    state: DiffCoverageState;
+}): DiffCoverageBreakdown;
+export declare function renderDiffCoverageBreakdown(params: {
+    diffPath: string;
+    breakdown: DiffCoverageBreakdown;
+}): string;
+export declare function countLinesInRanges(params: {
+    ranges: DiffLineRange[];
+}): number;

package/dist/utils/env.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Small typed accessors for process env — read once, in one place, instead of
+ * re-implementing the same `process.env.X` guard at every call site. Provider
+ * API-key names live in `models.ts`; the Cloud host/allowlist in
+ * `cloudFetchCore.ts`; this module holds the generic presence/read helpers plus
+ * the shared-temp-dir accessor.
+ */
+/** True when `name` is set to a non-empty string. Folds the copy that lived
+ *  privately in agent.ts / apiKeys.ts / byokFallback.ts / vertex.ts. */
+export declare function hasEnvVar(name: string): boolean;
+/** The trimmed value of `name`, or undefined when unset/blank. */
+export declare function readEnv(name: string): string | undefined;
+/** The action's shared temp dir, or undefined outside a Infraweaver action run
+ *  (created by `createTempDirectory()` in setup.ts, which sets INFRAWEAVER_TEMP_DIR). */
+export declare function readTempDir(): string | undefined;
+/**
+ * The GitHub Actions run context (the `GITHUB_*` env the runner injects), read
+ * through one typed accessor instead of `process.env.GITHUB_*` at ~30 sites.
+ * Every field is optional — the vars are absent outside a GHA runner (local dev,
+ * the stdio server), and callers already treat them as best-effort metadata.
+ */
+export type GitHubContext = {
+    /** `owner/repo`. */
+    repository: string | undefined;
+    /** the commit SHA under test. */
+    sha: string | undefined;
+    /** the short branch/tag name (`GITHUB_REF_NAME`). */
+    refName: string | undefined;
+    /** the full ref (`refs/heads/…`). */
+    ref: string | undefined;
+    runId: string | undefined;
+    runNumber: string | undefined;
+    eventName: string | undefined;
+    actor: string | undefined;
+    workflow: string | undefined;
+    serverUrl: string | undefined;
+    workspace: string | undefined;
+};
+export declare function githubContext(): GitHubContext;
+/**
+ * The action's shared temp dir, throwing when it isn't set — the single home for
+ * the guard that ~9 call sites previously re-implemented with drifting messages.
+ * Pass `context` (a tool name) to keep the "must run in infraweaver action context"
+ * hint the checkout/commit tools surfaced.
+ */
+export declare function getTempDir(context?: string): string;

package/dist/utils/errorReport.d.ts

@@ -0,0 +1,17 @@
+import type { ToolState } from "#app/toolState";
+interface ReportErrorParams {
+    toolState: ToolState;
+    error: string;
+    title?: string;
+    /**
+     * When the run has no pre-existing progress comment to update (silent
+     * IncrementalReview / pull_request_synchronize, mode-less polls), create
+     * a fresh issue comment on `toolState.issueNumber` instead of returning
+     * silently. Used for terminal errors (BillingError, TransientError) where
+     * the GH job summary is the only other surface and most users never open
+     * it. see #775.
+     */
+    createIfMissing?: boolean;
+}
+export declare function reportErrorToComment(ctx: ReportErrorParams): Promise<void>;
+export {};

package/dist/utils/exitHandler.d.ts

@@ -0,0 +1,8 @@
+type ExitSignalHandler = (signal: "SIGINT" | "SIGTERM") => void | Promise<void>;
+/**
+ * Register a handler to run when the process receives SIGINT or SIGTERM.
+ * Returns a dispose function that removes the handler.
+ */
+export declare function onExitSignal(handler: ExitSignalHandler): () => void;
+export declare function exitWithSignal(signal: "SIGINT" | "SIGTERM"): void;
+export {};

package/dist/utils/fixDoubleEscapedString.d.ts

@@ -0,0 +1 @@
+export declare function fixDoubleEscapedString(str: string): string;

package/dist/utils/gitAuth.d.ts

@@ -0,0 +1,84 @@
+/**
+ * git authentication via GIT_ASKPASS.
+ *
+ * a localhost HTTP server serves tokens via UUID codes whose lifetime is
+ * bounded by the parent $git() invocation: register() makes the code active,
+ * the script (and any sibling subprocess — e.g. git-lfs pre-push) can fetch
+ * the token any number of times, and $git()'s finally calls revoke() to
+ * close the window. each $git() call writes a unique askpass script with
+ * the server port+code baked into the file body — no secrets in subprocess
+ * env. a replay of a revoked code trips a 409 and revokes the underlying
+ * github installation token.
+ *
+ * see wiki/askpass.md for full security documentation.
+ */
+import type { GitAuthServer } from "#app/utils/gitAuthServer";
+type SafeGitSubcommand = "fetch" | "push";
+type GitAuthOptions = {
+    token: string;
+    cwd?: string;
+    disableHooks?: boolean;
+};
+type GitResult = {
+    stdout: string;
+    stderr: string;
+};
+/**
+ * resolve and fingerprint the git binary. must be called once at startup
+ * (in main()) before any agent code runs, so the path and hash reflect
+ * the untampered binary.
+ *
+ * resolves symlinks via realpath so the hash is of the actual binary.
+ * a malicious agent with sudo could replace the binary later, which is
+ * caught by verifyGitBinary() before each authenticated call.
+ */
+export declare function resolveGit(): void;
+export declare function setGitAuthServer(server: GitAuthServer): void;
+/**
+ * execute authenticated git command via ASKPASS.
+ *
+ * subcommand is restricted to "fetch" | "push" — operations that talk to
+ * a remote and need credentials. working-tree operations (checkout, merge)
+ * use $() from shell.ts which has no token.
+ *
+ * per call: registers a code with the auth server (valid for the lifetime
+ * of this invocation), writes a unique askpass script with port+code baked
+ * in, spawns git with GIT_ASKPASS pointing to the script. on completion,
+ * revokes the code and deletes the script in finally. multiple sibling
+ * askpass calls within one invocation (e.g. git itself + git-lfs pre-push)
+ * all see a valid code; replay attempts after finally trip a 409 and the
+ * server revokes the underlying github token as a tamper signal.
+ *
+ * @example
+ * await $git("fetch", ["origin", "main"], { token });
+ * await $git("push", ["-u", "origin", "feature"], { token });
+ */
+export declare function $git(subcommand: SafeGitSubcommand, args: string[], options: GitAuthOptions): Promise<GitResult>;
+/**
+ * shallow-clone unreachable: when an existing local depth is too shallow for
+ * git to traverse to the requested ref's ancestry, the remote walk fails with
+ * one of these wordings (git emits the full OID via oid_to_hex, so the bound
+ * is 40 for SHA-1 or 64 for SHA-256). detecting both lets a single deepen
+ * retry recover before the error reaches the agent — see issue #564 for the
+ * original `git_fetch` precedent and #656 for the `checkout_pr` follow-up.
+ */
+export declare const SHALLOW_UNREACHABLE_PATTERNS: RegExp[];
+/**
+ * large enough to clear the merge base on most real-world PRs without
+ * downloading the full history; matches the fallback used by
+ * `checkoutPrBranch` when the GitHub compare API is unavailable.
+ */
+export declare const DEEPEN_RETRY_DEPTH = 1000;
+/**
+ * authenticated `git fetch` that recovers from shallow-unreachable errors
+ * by retrying once with `--deepen=1000`. callers pass the same args they
+ * would to `$git("fetch", ...)`; on shallow-unreachable failures in a
+ * shallow repo, the second attempt prepends `--deepen=N` and strips any
+ * caller-supplied `--depth=` (the two flags are mutually exclusive, and
+ * the caller's depth is what got us into this mess).
+ *
+ * non-shallow-unreachable errors and non-shallow repos rethrow unchanged,
+ * so this is safe to wrap any fetch without changing fast-path behavior.
+ */
+export declare function $gitFetchWithDeepen(args: string[], options: GitAuthOptions, label?: string): Promise<GitResult>;
+export {};

package/dist/utils/gitAuthServer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ASKPASS-based git authentication server.
+ *
+ * serves tokens via a localhost HTTP server with per-$git()-call UUID codes.
+ * each $git() call gets a unique askpass script with the port+code baked in.
+ * the token never appears in subprocess env — only the script file path.
+ *
+ * lifetime: the code is valid for as long as the $git() invocation is
+ * running. multiple askpass calls within one invocation (e.g. git's own
+ * fetch/push + a git-lfs pre-push hook that also authenticates) all
+ * succeed. $git() calls revoke(code) in finally; subsequent requests for
+ * a revoked code trigger immediate token revocation via the GitHub API
+ * as a tamper-evidence precaution (an agent replaying the code after the
+ * legitimate window has closed is the realistic attack we still catch).
+ */
+export type GitAuthServer = {
+    port: number;
+    register: (token: string) => string;
+    revoke: (code: string) => void;
+    writeAskpassScript: (code: string) => string;
+    close: () => Promise<void>;
+    [Symbol.asyncDispose]: () => Promise<void>;
+};
+export declare function startGitAuthServer(tmpdir: string): Promise<GitAuthServer>;

package/dist/utils/github.d.ts

@@ -0,0 +1,104 @@
+import { throttling } from "@octokit/plugin-throttling";
+import { Octokit } from "@octokit/rest";
+export interface InstallationToken {
+    token: string;
+    expires_at: string;
+    installation_id: number;
+    repository: string;
+    ref: string;
+    runner_environment: string;
+    owner?: string;
+}
+/**
+ * Snapshot the GHA OIDC request creds from the env. Returns undefined off-CI or
+ * once they have been scrubbed. Call this BEFORE main.ts's restricted-mode env
+ * scrub so a mid-run token re-mint can still fetch a fresh OIDC JWT afterwards.
+ */
+export declare function readOidcCreds(): OidcCreds | undefined;
+/**
+ * Fetch a fresh OIDC JWT from the GHA token service using stashed creds — the
+ * env-independent equivalent of `core.getIDToken(audience)` (same
+ * `${url}&audience=` shape + bearer request token). Lets a re-mint succeed after
+ * the ACTIONS_ID_TOKEN_REQUEST_* env vars `core.getIDToken` reads are scrubbed.
+ */
+export declare function fetchOidcIdToken(creds: OidcCreds, audience: string): Promise<string>;
+type ReadWrite = "read" | "write";
+type WriteOnly = "write";
+/**
+ * GitHub App installation access token permissions.
+ * passed to `POST /app/installations/{id}/access_tokens` to scope the token.
+ * fields and allowed values come from the `app-permissions` OpenAPI schema.
+ * @see https://docs.github.com/en/rest/apps/installations#create-an-installation-access-token-for-an-app
+ * @see https://github.com/github/rest-api-description — components.schemas.app-permissions
+ */
+type GitHubAppPermissions = {
+    actions?: ReadWrite;
+    artifact_metadata?: ReadWrite;
+    attestations?: ReadWrite;
+    checks?: ReadWrite;
+    contents?: ReadWrite;
+    deployments?: ReadWrite;
+    discussions?: ReadWrite;
+    issues?: ReadWrite;
+    packages?: ReadWrite;
+    pages?: ReadWrite;
+    pull_requests?: ReadWrite;
+    security_events?: ReadWrite;
+    statuses?: ReadWrite;
+    workflows?: WriteOnly;
+};
+/**
+ * Stashed GitHub Actions OIDC request credentials (`ACTIONS_ID_TOKEN_REQUEST_URL`
+ * + `_TOKEN`). Captured by {@link readOidcCreds} while the env vars are still
+ * present so a mid-run token re-mint can fetch a fresh OIDC JWT even after main.ts
+ * scrubs those vars from the env (which it does in every shell mode).
+ */
+export type OidcCreds = {
+    requestUrl: string;
+    requestToken: string;
+};
+type AcquireTokenOptions = {
+    repos?: string[];
+    permissions?: GitHubAppPermissions;
+    /** when set, mint via OIDC using these stashed creds instead of reading the
+     *  (possibly already-scrubbed) ACTIONS_ID_TOKEN_REQUEST_* env vars. */
+    oidc?: OidcCreds;
+};
+/**
+ * ensure a GitHub token is available in the environment.
+ *
+ * when OIDC is available (CI), always mints a fresh token scoped to
+ * GITHUB_REPOSITORY — overriding any inherited GITHUB_TOKEN that may
+ * be scoped to the wrong repo.
+ *
+ * otherwise falls back to GitHub App credentials for local development.
+ *
+ * only called from dev-run.ts (test/dev path) — the live action calls
+ * main() directly and never calls this.
+ */
+export declare function ensureGitHubToken(): Promise<void>;
+export declare function acquireNewToken(opts?: AcquireTokenOptions): Promise<string>;
+export interface RepoContext {
+    owner: string;
+    name: string;
+}
+/**
+ * Parse repository context from GITHUB_REPOSITORY environment variable.
+ */
+export declare function parseRepoContext(): RepoContext;
+export type OctokitWithPlugins = InstanceType<ReturnType<typeof Octokit.plugin<typeof Octokit, [typeof throttling]>>>;
+export interface ResourceUsage {
+    requestCount: number;
+    rateLimitRemaining: number | null;
+    rateLimitResetMs: number | null;
+}
+export interface UsageSummary {
+    version: 1;
+    github: {
+        core: ResourceUsage;
+        graphql: ResourceUsage;
+    };
+}
+export declare function writeGitHubUsageSummaryToFile(path: string): Promise<void>;
+export declare function createOctokit(token: string, refreshAuth?: (stale: string) => Promise<string>): OctokitWithPlugins;
+export {};

package/dist/utils/globals.d.ts

@@ -0,0 +1,3 @@
+export declare const isCloudflareSandbox: boolean;
+export declare const isGitHubActions: boolean;
+export declare const isInsideDocker: boolean;

package/dist/utils/infraweaverConfig.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Repo-committed `.infraweaver.yml` / `.infraweaver.json` config (the follow-up
+ * to the unified `tools_enabled` input). A thin layer that sits **under** the
+ * action inputs: an
+ * explicit workflow input always wins; the file only fills the gaps. It versions
+ * the toolchain + scoping policy *with the code* (and doubles as the auditable
+ * record of which non-permissive tools the repo owner opted into), so the
+ * workflow file can stay minimal and the policy lives next to the Terraform.
+ *
+ * Scope is deliberate — only repo-level **policy** knobs live here. Each maps
+ * 1:1 to the matching action input and flows through the SAME parser, so the file
+ * and the input validate identically. Secrets (`module_fetch_token`) and
+ * per-run/workflow knobs (`mode`, `max_prs`, `base_branch`, `allow_replace`) are
+ * intentionally NOT read from the file: a committed file is the wrong place for a
+ * credential, and the run's shape belongs to the workflow that dispatches it.
+ *
+ * Trust boundary: `.infraweaver.yml` is controlled by whoever can push to the repo
+ * — the same surface as the Terraform being remediated. It can only RELAX within
+ * the licence gate's structure (naming a non-permissive tool is the repo owner's
+ * licence acknowledgement, exactly as on the input) and it can never disable the
+ * required substrate. A workflow author who needs to *enforce* a policy sets the
+ * action input, which wins over the file.
+ *
+ * Degrade-green: a missing file is silent; malformed YAML, a non-mapping
+ * document, an unknown key, or a value of the wrong shape yields a warning and is
+ * ignored — never a hard failure.
+ */
+/** filenames checked, in order; the first that exists wins. `.infraweaver.json` is
+ * listed first so the JSON form takes precedence if a repo (mis)commits both. */
+export declare const INFRAWEAVER_CONFIG_FILENAMES: readonly [".infraweaver.json", ".infraweaver.yml", ".infraweaver.yaml"];
+/** the repo-level keys `.infraweaver.yml` may set. Each is the snake_case name of
+ * the matching action input, so the file value can be fed straight through the
+ * input's own parser in `resolvePayload`. */
+export declare const INFRAWEAVER_CONFIG_KEYS: readonly ["tools_enabled", "protected_paths", "allowed_paths", "scan_scope", "iac_languages", "language", "severity_threshold", "grouping", "autonomy_threshold", "module_catalogue", "required_controls"];
+export type InfraweaverConfigKey = (typeof INFRAWEAVER_CONFIG_KEYS)[number];
+/** normalized string values (lists newline-joined), keyed by input name. */
+export type InfraweaverFileValues = Partial<Record<InfraweaverConfigKey, string>>;
+export interface ParsedInfraweaverConfig {
+    values: InfraweaverFileValues;
+    /** non-fatal problems (malformed value, unknown key) for the caller to log. */
+    warnings: string[];
+}
+/**
+ * Parse raw `.infraweaver.yml`/`.infraweaver.json` text into normalized string values
+ * + warnings. Pure — no I/O, no logging — so the parsing/validation is
+ * unit-testable. `format` selects the syntax (and shapes the warning wording);
+ * everything after the document is parsed is identical, since JSON and YAML both
+ * yield a plain object here.
+ */
+export declare function parseInfraweaverConfig(raw: string, format?: "yaml" | "json"): ParsedInfraweaverConfig;
+/**
+ * Read + parse the repo's `.infraweaver.yml` (first of the supported filenames
+ * found under `cwd`). Returns the normalized values, logging any warnings. A
+ * missing file resolves to `{}` silently — the common, valid case.
+ */
+export declare function loadInfraweaverConfig(cwd: string | undefined): InfraweaverFileValues;

package/dist/utils/install.d.ts

@@ -0,0 +1,37 @@
+export interface InstallFromNpmTarballParams {
+    packageName: string;
+    version: string;
+    executablePath: string;
+    installDependencies?: boolean;
+}
+/**
+ * The `dist` block npm returns for a published version. `integrity` is a
+ * Subresource-Integrity string (`sha512-<base64>`); `shasum` is the legacy hex
+ * SHA-1. Every public-registry version carries at least one.
+ */
+export interface NpmDist {
+    integrity?: string;
+    shasum?: string;
+}
+/**
+ * Verify a downloaded tarball against the digest the registry published for
+ * that exact version, and throw if it doesn't match.
+ *
+ * This is what makes a consumer's `uses: infraweaver@<sha>` pin mean something:
+ * the action itself is pinned by SHA, but it then fetches an agent CLI at
+ * runtime. Without this check a compromised registry/CDN — or anything able to
+ * intercept the download — could serve arbitrary code into a run that reads the
+ * customer's repository. The version is already pinned by `package.json` (see
+ * `getDevDependencyVersion`, which refuses a range); this pins the *bytes*.
+ *
+ * Fails **closed**: no digest published ⇒ we refuse to install, rather than
+ * silently degrading to unverified. A registry that serves no digest is exactly
+ * the case worth stopping on.
+ */
+export declare function verifyTarballIntegrity(tarballPath: string, dist: NpmDist | undefined, descriptor: string): void;
+/**
+ * Install a CLI tool from an npm package tarball
+ * Downloads the tarball, extracts it to a temp directory, and returns the path to the CLI executable
+ * The temp directory will be cleaned up by the OS automatically
+ */
+export declare function installFromNpmTarball(params: InstallFromNpmTarballParams): Promise<string>;