infraweaver 0.1.0

package/dist/utils/runStartupLog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Startup log formatting for the resolver pipeline. Computes the
+ * "model / agent / push / shell / timeout" block that main.ts prints
+ * after resolving the agent + model + payload.
+ */
+import type { ResolvedPayload } from "#app/utils/payload";
+/**
+ * Emit the startup block ("» model / agent / push / shell / timeout") after
+ * the agent and model are resolved. Single side-effect; no return.
+ */
+export declare function logRunStartup(ctx: {
+    payload: ResolvedPayload;
+    resolvedModel: string | undefined;
+    agentName: string;
+}): void;

package/dist/utils/secrets.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Secret detection and env filtering utilities
+ *
+ * subprocess env filtering: default-deny allowlist model.
+ * only vars in the safe set or user allowlist are passed to child processes.
+ *
+ * log redaction: SENSITIVE_PATTERNS are used to identify secret values
+ * for redaction in logs and GHA masking (independent of subprocess filtering).
+ */
+export declare const SENSITIVE_PATTERNS: RegExp[];
+export declare function isSensitiveEnvName(key: string): boolean;
+export declare function setEnvAllowlist(raw: string): void;
+/** filter env vars using default-deny allowlist: safe set + user allowlist */
+export declare function filterEnv(): Record<string, string>;
+/**
+ * env for "inherit" mode: everything in process.env EXCEPT secret-bearing names.
+ *
+ * inherit exists to widen the *command* surface (arbitrary toolchain vars the
+ * restricted allowlist can't enumerate), not to hand the agent credentials — so
+ * this is a denylist over the full env rather than the restricted allowlist. A
+ * specific var can still be opted back in explicitly via the user allowlist.
+ *
+ * Without this, `shell: "enabled"` would let the agent read INPUT_*_TOKEN, a BYO
+ * model key, or the OIDC minting creds straight out of `env`.
+ */
+export declare function inheritEnv(): Record<string, string>;
+export type EnvMode = "restricted" | "inherit" | Record<string, string>;
+/**
+ * resolve env mode to actual env object
+ * - "restricted" (default): filterEnv() — only safe set + user allowlist
+ * - "inherit": full process.env minus secret-bearing names
+ * - object: custom env merged with restricted base
+ */
+export declare function resolveEnv(mode: EnvMode | undefined): Record<string, string | undefined>;

package/dist/utils/setup.d.ts

@@ -0,0 +1,90 @@
+import type { ShellPermission } from "#app/external";
+import type { ToolState } from "#app/toolState";
+import type { OctokitWithPlugins } from "#app/utils/github";
+export interface SetupOptions {
+    tempDir: string;
+}
+/**
+ * Create a shared temp directory for the action
+ */
+export declare function createTempDirectory(): string;
+/**
+ * snapshot-and-delete the GHA runner's known credential leak surfaces inside
+ * `$RUNNER_TEMP` before the agent spawns. without this, a shell-capable agent
+ * can grep:
+ *   - `_runner_file_commands/set_output_*` for `core.setOutput('token', ghs_…)`
+ *     calls made by earlier composite-action steps (e.g.
+ *     infraweaver-io/infraweaver-action/get-installation-token);
+ *   - `<uuid>.sh` rendered step scripts whose `run: |` body embeds
+ *     `${{ steps.token.outputs.token }}` literally (GHA expands BEFORE writing);
+ *   - `git-credentials-*.config` written by `actions/checkout@v6` for the
+ *     workflow GITHUB_TOKEN.
+ *
+ * the running bash process already has its own `.sh` open via fd, so the
+ * unlink is safe — `unlink` removes the dirent, the kernel keeps reading.
+ *
+ * preserves every `_runner_file_commands/` file path the runner pre-allocated
+ * for OUR step — `$GITHUB_OUTPUT`, `$GITHUB_ENV`, `$GITHUB_PATH`,
+ * `$GITHUB_STATE`, `$GITHUB_STEP_SUMMARY`. those are read by the runner
+ * AFTER we exit (or by our own `post:` hook), and wiping them would break
+ * infraweaver's `result` output, `post:` state handoff, and job summary.
+ *
+ * silent no-op when `$RUNNER_TEMP` is unset (local dev, `pnpm dev:run`).
+ * per-file errors are tolerated — the runner may delete files between
+ * our readdir and our unlink.
+ */
+export declare function wipeRunnerLeakSurface(): void;
+/**
+ * Setup the test repository for running actions
+ */
+export declare function setupTestRepo(options: SetupOptions): void;
+/**
+ * remove any `[includeIf ...]` entries from the local git config so that
+ * actions/checkout-persisted credentials don't ride alongside ASKPASS-provided
+ * auth for subsequent git operations.
+ *
+ * SECURITY: git config subsection values can contain arbitrary characters
+ * including `$(...)` command substitutions, and `${IFS}` spacing tricks defeat
+ * naive split-on-space filtering. we read keys via the `-z` (null-terminated)
+ * output format and feed them to a spawn-array `git config --unset-all` so
+ * the shell never interpolates key contents — closing the RCE path that a
+ * string-interpolated `execSync(...)` would expose.
+ */
+export declare function removeIncludeIfEntries(repoDir: string): void;
+export interface GitContext {
+    gitToken: string;
+    owner: string;
+    name: string;
+    octokit: OctokitWithPlugins;
+    toolState: ToolState;
+    shell: ShellPermission;
+    postCheckoutScript: string | null;
+}
+export type SetupGitParams = GitContext;
+/**
+ * setup git configuration and authentication for the repository.
+ * - configures git identity (user.email, user.name)
+ * - sets up authentication via gitToken (minimal contents:write)
+ *
+ * gitToken is a minimal-permission token (contents + workflows) used for git operations.
+ * it is assumed to be potentially exfiltratable, so it has limited scope.
+ */
+export declare function setupGit(params: SetupGitParams): Promise<void>;
+/**
+ * snapshot the current HEAD as either a branch name (when on a named branch)
+ * or a literal SHA (when detached). used by setupGit to pin the run-entry
+ * position and by checkout_pr to compare the live HEAD against it.
+ *
+ * splitting the two cases is load-bearing: `git rev-parse --abbrev-ref HEAD`
+ * returns the sentinel string `"HEAD"` on detached entry — which is the
+ * default `actions/checkout` state for `pull_request` events. storing that
+ * raw string would make any future detached state (including a subagent's
+ * `git checkout --detach <sha>`) compare equal.
+ */
+export declare function captureInitialHead(repoDir: string): {
+    kind: "branch";
+    name: string;
+} | {
+    kind: "detached";
+    sha: string;
+};

package/dist/utils/shell.d.ts

@@ -0,0 +1,44 @@
+import { type EnvMode } from "#app/utils/secrets";
+interface ShellOptions {
+    cwd?: string;
+    encoding?: "utf-8" | "utf8" | "ascii" | "base64" | "base64url" | "hex" | "latin1" | "ucs-2" | "ucs2" | "utf16le";
+    log?: boolean;
+    /**
+     * env mode: "restricted" (default) filters secrets, "inherit" passes full env,
+     * or provide a custom env object (merged with restricted base)
+     */
+    env?: EnvMode;
+    onError?: (result: {
+        status: number;
+        stdout: string;
+        stderr: string;
+    }) => void;
+    /** wall-clock cap in ms; defaults to DEFAULT_TIMEOUT_MS. a stalled remote or
+     * wedged repo hook would otherwise hang until the run-level idle watchdog. */
+    timeoutMs?: number;
+    /** stdout/stderr cap in bytes; defaults to DEFAULT_MAX_BUFFER. node's 1 MiB
+     * spawnSync default silently truncates large `git diff` output into a
+     * generic failure. */
+    maxBuffer?: number;
+}
+/** every `$` caller is a git invocation; the longest legitimate one is a
+ * clone/fetch of a large repo, well under this. */
+export declare const DEFAULT_TIMEOUT_MS: number;
+/** big-PR `git diff` output can far exceed node's 1 MiB default. */
+export declare const DEFAULT_MAX_BUFFER: number;
+/**
+ * Execute a shell command safely using spawnSync with argument arrays.
+ * Prevents shell injection by avoiding string interpolation in shell commands.
+ *
+ * SECURITY: by default, env vars are filtered to remove secrets (tokens, keys, passwords).
+ * this prevents malicious code (git hooks, npm scripts, etc.) from exfiltrating credentials.
+ * use env: "inherit" only when absolutely necessary.
+ *
+ * @param cmd - The command to execute
+ * @param args - Array of arguments to pass to the command
+ * @param options - Optional configuration (cwd, encoding, onError)
+ * @returns The trimmed stdout output
+ * @throws Error if command fails and no onError handler is provided
+ */
+export declare function $(cmd: string, args: string[], options?: ShellOptions): string;
+export {};

package/dist/utils/skills.d.ts

@@ -0,0 +1,10 @@
+/**
+ * write all bundled skills into the fake HOME so OpenCode / Claude Code discover
+ * them via their auto-scan directories.
+ *
+ * called once per agent run from each agent's `run()`. cheap (small file
+ * writes), no network, idempotent.
+ */
+export declare function installBundledSkills(params: {
+    home: string;
+}): void;

package/dist/utils/subprocess.d.ts

@@ -0,0 +1,81 @@
+import { type ChildProcess } from "node:child_process";
+export type TrackChildOptions = {
+    child: ChildProcess;
+    killGroup?: boolean;
+};
+export declare const SPAWN_TIMEOUT_CODE = "E_SPAWN_TIMEOUT";
+export declare const SPAWN_ACTIVITY_TIMEOUT_CODE = "E_SPAWN_ACTIVITY_TIMEOUT";
+export declare class SpawnTimeoutError extends Error {
+    readonly code: typeof SPAWN_TIMEOUT_CODE | typeof SPAWN_ACTIVITY_TIMEOUT_CODE;
+    constructor(message: string, code: typeof SPAWN_TIMEOUT_CODE | typeof SPAWN_ACTIVITY_TIMEOUT_CODE);
+}
+export type SignalHandler = (signal: NodeJS.Signals) => void;
+export declare function trackChild(options: TrackChildOptions): void;
+export declare function untrackChild(child: ChildProcess): void;
+export declare function setSignalHandler(handler: SignalHandler | null): void;
+export declare function killTrackedChildren(): void;
+/**
+ * Controls what the wrapper retains in memory across the child's lifetime
+ * for the post-hoc `SpawnResult.stdout` / `SpawnResult.stderr` snapshots.
+ *
+ * Streaming callbacks (`onStdout` / `onStderr`) fire regardless — `retain`
+ * only governs the buffered snapshot returned in `SpawnResult`.
+ *
+ * - `"tail"` (default): keep the last `maxRetainedBytes` UTF-16 code units
+ *   of each stream. Once the cap is exceeded, oldest bytes are sliced off
+ *   and the result is prefixed with a `... [N MiB truncated] ...` sentinel.
+ *   Right default for short-lived commands whose failure mode is in their
+ *   final output (git errors, install failures, hook scripts).
+ * - `"none"`: skip the buffer entirely. `SpawnResult.stdout` / `.stderr`
+ *   are empty strings. Use this for long-lived streaming agents that already
+ *   drain via `onStdout` / `onStderr` and never read the buffered snapshot.
+ *
+ * Default cap is 8 MiB — well below V8's ~1 GiB `kMaxLength` so `+= chunk`
+ * can never throw `RangeError: Invalid string length`.
+ */
+export type RetainMode = "tail" | "none";
+export declare const DEFAULT_MAX_RETAINED_BYTES: number;
+export interface SpawnOptions {
+    cmd: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    input?: string;
+    timeout?: number;
+    activityTimeout?: number;
+    onActivityTimeout?: (() => void) | undefined;
+    abortSignal?: AbortSignal | undefined;
+    cwd?: string;
+    stdio?: ("pipe" | "ignore" | "inherit")[];
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    killGroup?: boolean;
+    retain?: RetainMode;
+    maxRetainedBytes?: number;
+}
+/**
+ * Bounded string accumulator that keeps the tail of appended chunks.
+ * Once the cap is exceeded, oldest bytes are sliced off and `toString()`
+ * prefixes the survivors with a sentinel describing the elided byte count.
+ *
+ * Exported because long-lived agent runtimes (opencode, claude) also
+ * accumulate per-run narration strings independently of the spawn wrapper
+ * and need the same protection against V8's `kMaxLength`.
+ */
+export declare class TailBuffer {
+    private readonly cap;
+    private buffer;
+    private truncatedBytes;
+    constructor(cap: number);
+    append(chunk: string): void;
+    toString(): string;
+}
+export interface SpawnResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+}
+/**
+ * Spawn a subprocess with streaming callbacks and buffered results
+ */
+export declare function spawn(options: SpawnOptions): Promise<SpawnResult>;

package/dist/utils/terraformMcp.d.ts

@@ -0,0 +1,46 @@
+/**
+ * HashiCorp terraform-mcp-server integration.
+ *
+ * When the `terraform_mcp` input is on, the agent harness registers a SECOND
+ * MCP server next to infraweaver's: HashiCorp's terraform-mcp-server, run as a
+ * Docker container over stdio. It gives the fixing agent live Terraform
+ * Registry knowledge — current module versions, provider argument shapes —
+ * which directly powers module-source-aware fixes and generation.
+ *
+ * Security posture:
+ *   - the image is VERSION+DIGEST-PINNED (`TERRAFORM_MCP_IMAGE`): the `:0.5.2`
+ *     tag is human-readable, the `@sha256:` digest is the authoritative pin, so
+ *     a re-tagged or compromised `0.5.2` upstream can never be pulled. Bump both
+ *     deliberately (resolve the new digest with `docker buildx imagetools inspect
+ *     hashicorp/terraform-mcp-server:<ver>` or the Docker Hub tags API).
+ *   - only the read-only `registry` toolset is enabled — no TFE operations,
+ *     and no TFE_TOKEN is ever passed.
+ *   - degrades green: docker absent → a log note, never a failed run.
+ */
+import { type ToolSelectionFlags } from "#app/utils/toolSelection";
+/** pinned release of hashicorp/terraform-mcp-server — tag for humans, digest for
+ * integrity (the multi-arch index digest of `0.5.2`). Bump both deliberately. */
+export declare const TERRAFORM_MCP_IMAGE = "hashicorp/terraform-mcp-server:0.5.2@sha256:67b4d3d39aa2c32c5ee280b21d67fb6513dab463af6c93c2ae0cdd4af09d4603";
+/** the registry name the server is registered under in agent MCP configs —
+ * matches HashiCorp's own client-config examples, so agent guidance written
+ * against "the terraform MCP server" finds it under the expected key. */
+export declare const TERRAFORM_MCP_SERVER_NAME = "terraform";
+export type TerraformMcpResolution = {
+    kind: "disabled";
+} | {
+    kind: "docker_missing";
+    note: string;
+} | {
+    kind: "available";
+    command: "docker";
+    args: string[];
+};
+/** test hook — the docker probe is cached per process. */
+export declare function _clearDockerProbeCache(): void;
+/**
+ * Decide whether the run gets the terraform-mcp-server, as a discriminated
+ * union so each harness handles all three outcomes explicitly: register the
+ * server (`available`), log the degrade-green note (`docker_missing`), or do
+ * nothing (`disabled`).
+ */
+export declare function resolveTerraformMcp(payload: ToolSelectionFlags): TerraformMcpResolution;

package/dist/utils/time.d.ts

@@ -0,0 +1,15 @@
+/**
+ * time string parsing utilities for timeout configuration.
+ * supports formats like "10m", "1h30m", "10m12s", "30s".
+ */
+export declare const TIMEOUT_DISABLED = "none";
+/**
+ * parse a time string like "10m", "1h30m", "10m12s" into milliseconds.
+ * returns null if the string is not a valid time format.
+ */
+export declare function parseTimeString(input: string): number | null;
+/**
+ * check if a string is a valid time format.
+ */
+export declare function isValidTimeString(input: string): boolean;
+export declare function resolveTimeoutMs(input: string | undefined): number | null;

package/dist/utils/timer.d.ts

@@ -0,0 +1,23 @@
+export declare class Timer {
+    private initialTimestamp;
+    private lastCheckpointTimestamp;
+    constructor();
+    checkpoint(name: string): void;
+}
+/**
+ * Measures wall-clock gap between the last tool_result and the next tool_call,
+ * surfacing it as a "thought for Xs" log when over `THINKING_THRESHOLD`.
+ *
+ * Use one instance per logical session (orchestrator, each subagent) — sharing
+ * a single timer across sessions conflates cross-session interleaving as
+ * thinking time. The optional `formatLine` lets the caller prefix output with
+ * a session label so attribution is visible in the merged log stream.
+ */
+export declare class ThinkingTimer {
+    private readonly durationFormatter;
+    private lastToolResultTimestamp;
+    private readonly formatLine;
+    constructor(formatLine?: (line: string) => string);
+    markToolResult(): void;
+    markToolCall(): void;
+}

package/dist/utils/todoTracking.d.ts

@@ -0,0 +1,16 @@
+export type TodoTracker = {
+    update: (input: unknown) => void;
+    flush: () => Promise<void>;
+    cancel: () => void;
+    /** resolves when any in-flight onUpdate call completes */
+    settled: () => Promise<void>;
+    /** mark in-progress items as completed (for final snapshot before review/progress post) */
+    completeInProgress: () => void;
+    renderCollapsible: (options?: {
+        completeInProgress?: boolean;
+    }) => string;
+    readonly enabled: boolean;
+    /** true after the tracker has successfully called onUpdate at least once */
+    readonly hasPublished: boolean;
+};
+export declare function createTodoTracker(onUpdate: (body: string) => Promise<void>): TodoTracker;

package/dist/utils/token.d.ts

@@ -0,0 +1,52 @@
+import type { PushPermission } from "#app/external";
+import { acquireNewToken } from "#app/utils/github";
+export { acquireNewToken as acquireInstallationToken, revokeGitHubInstallationToken as revokeInstallationToken, };
+/** The live MCP-token refresher (see {@link refreshMcpTokenFn}), or undefined
+ *  when re-minting isn't possible. Passed into `createOctokit` as `refreshAuth`. */
+export declare function getMcpTokenRefresh(): ((stale: string) => Promise<string>) | undefined;
+/**
+ * get the job-scoped token from action input.
+ * this token has permissions defined by the workflow's permissions block.
+ *
+ * fallback order:
+ * 1. INPUT_TOKEN (from workflow `with: token:`)
+ * 2. GH_TOKEN (external token override)
+ * 3. GITHUB_TOKEN (pre-acquired in tests or from GHA env)
+ */
+export declare function getJobToken(): string;
+export type TokenRef = {
+    /** Read live via the getter below: after a mid-run re-mint (`refreshGitToken`
+     *  recovers an auth-class push 401 with a fresh token, revoking the old one),
+     *  this reflects the CURRENT git token. Push-class tools (push_branch,
+     *  push_tags, delete_branch, git_fetch) that read it per call therefore never
+     *  reuse a stale/revoked snapshot. Mirrors the `getMcpTokenRefresh` /
+     *  `githubInstallationToken` live-getter pattern (pullfrog #891/#964). */
+    gitToken: string;
+    mcpToken: string;
+    /** single-flight re-mint of the git token, threaded into pushWithRetry so an
+     *  auth-class push 401 can recover with a fresh token (pullfrog #972). undefined
+     *  when re-minting isn't possible (off-CI or external GH_TOKEN). */
+    refreshGitToken?: (stale: string) => Promise<string>;
+    [Symbol.asyncDispose]: () => Promise<void>;
+};
+type ResolveTokensParams = {
+    push: PushPermission;
+};
+/**
+ * resolve tokens for the action run.
+ *
+ * creates two separate tokens:
+ * - gitToken: contents permission based on `push` setting (assumed exfiltratable)
+ *   - push: enabled → contents:write (can push)
+ *   - push: disabled → contents:read (read-only)
+ * - mcpToken: full installation token - used for GitHub API calls in MCP tools (not exfiltratable)
+ *
+ * security-conscious users can pass their own token via GH_TOKEN env var or inputs.token.
+ */
+export declare function resolveTokens(params: ResolveTokensParams): Promise<TokenRef>;
+/**
+ * get the MCP token from memory.
+ * this is the token used for GitHub API calls in MCP tools.
+ */
+export declare function getGitHubInstallationToken(): string;
+export declare function revokeGitHubInstallationToken(token: string): Promise<void>;

package/dist/utils/toolLicensing.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Tool-licence classification (dependency posture; the "non-permissive-tool
+ * confirmation gate").
+ *
+ * Infraweaver ORCHESTRATES external tools — it never bundles or redistributes
+ * their binaries ("be an orchestrator, not a redistributor"). This module
+ * makes the licence of every selectable tool explicit so the engine can DEFAULT
+ * to the permissively-licensed tools and treat a non-permissive one (tflint's
+ * embedded BUSL Terraform fork, HashiCorp's terraform-mcp-server) as an
+ * *informed, named opt-in* rather than something whose output is consumed
+ * silently. Pure data + pure predicates — the gate that consumes it lives in
+ * [[toolSelection]].
+ */
+/** every external tool the engine can be configured to run. */
+export type ToolId = "terraform" | "tflint" | "trivy" | "checkov" | "infracost" | "gitleaks" | "conftest" | "terratest" | "terraform_mcp" | "opentofu_mcp";
+/**
+ * Coarse licence family the gate reasons about:
+ *   - `permissive`     — MIT / Apache-2.0 / BSD / ISC: default-enabled.
+ *   - `copyleft`       — MPL / (L)GPL / AGPL: gated (explicit opt-in).
+ *   - `source-available` — BUSL / SSPL / Elastic: gated (explicit opt-in).
+ */
+export type LicenseClass = "permissive" | "copyleft" | "source-available";
+export interface ToolLicense {
+    id: ToolId;
+    /** display name for logs / PR notes. */
+    name: string;
+    /** human-facing SPDX-ish identifier (shown, never parsed). */
+    license: string;
+    class: LicenseClass;
+    /**
+     * The core Terraform CLI is the SUBSTRATE the engine cannot run without and
+     * which the operator installs themselves — invoking it is never
+     * redistribution. It is licence-classified for honesty (Terraform moved to
+     * BUSL-1.1 at v1.6) but EXEMPT from the opt-in gate, so a Terraform fixer
+     * always has Terraform.
+     */
+    required?: boolean;
+}
+/**
+ * The single source of truth for what each tool is licensed under. Verified
+ * against the "third-party dependency posture" note (June 2026). Keep in sync
+ * when a tool's licence changes (e.g. a vendor relicensing event).
+ */
+export declare const TOOL_LICENSES: Readonly<Record<ToolId, ToolLicense>>;
+export declare const ALL_TOOL_IDS: ToolId[];
+/** a permissively-licensed tool can be enabled by default; anything else needs
+ * an explicit, licence-named opt-in. */
+export declare function isPermissive(c: LicenseClass): boolean;
+/**
+ * A tool whose output must NOT be consumed without an explicit, licence-named
+ * opt-in: non-permissive AND not the required substrate. This is the predicate
+ * the confirmation gate is built on.
+ */
+export declare function isLicenseGated(id: ToolId): boolean;
+/** every tool currently behind the licence gate (for docs / reporting). */
+export declare const LICENSE_GATED_TOOLS: ToolId[];

package/dist/utils/toolSelection.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Unified tool-selection config + the
+ * non-permissive-tool confirmation gate (built on [[toolLicensing]]).
+ *
+ * One declarative `tools_enabled` list replaces the previous mix of per-flag
+ * inputs and silent presence-detection: an operator names the scanners/engines
+ * they want, prefixing `-` to turn one off. The same list is how a non-permissive
+ * tool (tflint, terraform-mcp-server) is opted into — naming it is the explicit,
+ * licence-aware acknowledgement the gate requires.
+ *
+ * Resolution precedence, per tool (highest first):
+ *   1. the required substrate (`terraform`)  → ON  (exempt; never disablable)
+ *   2. an explicit `-tool` in the list       → OFF (always wins over the rest)
+ *   3. an explicit `tool` / `+tool`          → ON  (this is the licence opt-in)
+ *   4. `all` base                            → ON  (operator accepts every tool)
+ *   5. `none` base                           → only the explicitly/flag-enabled
+ *   6. default base:
+ *        - licence-gated tool  → ON only if its dedicated flag is set, else OFF
+ *        - flag-opt-in tool    → ON only if its dedicated flag is set, else OFF
+ *        - permissive tool     → ON
+ *
+ * The dedicated booleans (`gitleaks`, `terratest`, `terraform_mcp`) still work
+ * and count as an opt-in, so existing workflows keep running unchanged. Pure.
+ */
+import { isPermissive, TOOL_LICENSES, type ToolId } from "#app/utils/toolLicensing";
+/** the parsed `tools_enabled` input: a base posture + per-tool overrides. */
+export interface ToolDirective {
+    /** `all` (enable everything) / `none` (enable nothing) / undefined (defaults). */
+    base?: "all" | "none" | undefined;
+    /** explicit per-tool overrides: true = enable, false = disable. */
+    explicit: Map<ToolId, boolean>;
+    /** tokens that matched no known tool — surfaced as a warning, never fatal. */
+    unknown: string[];
+}
+/** the dedicated booleans that pre-date the unified list. */
+export interface ToolSelectionFlags {
+    toolsEnabled?: ToolDirective | undefined;
+    gitleaks?: boolean;
+    terratest?: boolean;
+    terraformMcp?: boolean;
+    opentofuMcp?: boolean;
+}
+/**
+ * Parse the `tools_enabled` input (comma- or newline-separated). Recognises the
+ * `all` / `none` bases and `tool` / `+tool` / `-tool` (also `!tool`) overrides.
+ * Returns undefined for an empty input so "unset" stays distinguishable from an
+ * explicit list (the consumer then applies the licence-aware defaults).
+ */
+export declare function parseToolSelection(raw: string | undefined): ToolDirective | undefined;
+/** the resolved selection for a run — a deterministic verdict per tool. */
+export interface ResolvedToolSelection {
+    enabled(id: ToolId): boolean;
+    /** the reason a tool is OFF (for the scan report / logs); undefined when ON. */
+    offReason(id: ToolId): string | undefined;
+    /** licence-gated tools that are OFF because they weren't opted into. */
+    gated: ToolId[];
+    /** tools explicitly turned off via `tools_enabled`. */
+    disabled: ToolId[];
+    /** unrecognised `tools_enabled` tokens (warn, never fatal). */
+    unknownTokens: string[];
+}
+/**
+ * Resolve the per-tool selection from the run's payload (the parsed
+ * `tools_enabled` directive + the dedicated booleans). Pure; safe to call from
+ * any consumer (the scan tool, the secret guardrail, the terraform-mcp resolver,
+ * the plan tool) so they all agree on which tools may run this run.
+ */
+export declare function resolveToolSelection(flags: ToolSelectionFlags): ResolvedToolSelection;
+/** map a `terraform_scan` scanner source to the tool id it belongs to (null for
+ * the `reviewer` pseudo-source, which the gate never governs). */
+export declare function scannerToolId(source: string): ToolId | null;
+export type { ToolId };
+export { isPermissive, TOOL_LICENSES };

package/dist/utils/toon.d.ts

@@ -0,0 +1,16 @@
+import { encode } from "@toon-format/toon";
+/**
+ * Recursively replaces lone surrogates in strings and object keys with U+FFFD.
+ * Exported for the tests; prefer {@link toonEncode}.
+ *
+ * Rebuilt with `Object.fromEntries`, which defines own data properties rather
+ * than assigning them — so a `__proto__` key in untrusted input cannot reach
+ * the prototype setter.
+ */
+export declare function toWellFormedDeep<T>(value: T): T;
+/**
+ * `@toon-format/toon`'s `encode`, applied to well-formed input. Use this
+ * everywhere instead of importing `encode` directly — `knip` and the import
+ * guard keep the direct import to this module.
+ */
+export declare function toonEncode(input: unknown, options?: Parameters<typeof encode>[1]): string;

package/dist/utils/version.d.ts

@@ -0,0 +1,2 @@
+import packageJson from "#package.json";
+export declare function getDevDependencyVersion(name: keyof typeof packageJson.devDependencies): string;

package/dist/utils/versioning.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @throws Error if the action can't process payload
+ * The compatibility is determined according to the COMPATIBILITY_POLICY above.
+ * @param payloadVersion the version of the payload
+ * @param actionVersion the version of the action (recipient)
+ */
+export declare function validateCompatibility(payloadVersion: string, actionVersion: string): void;

package/dist/utils/vertex.d.ts

@@ -0,0 +1,16 @@
+export declare const VERTEX_SERVICE_ACCOUNT_JSON_ENV = "VERTEX_SERVICE_ACCOUNT_JSON";
+export declare const GOOGLE_APPLICATION_CREDENTIALS_ENV = "GOOGLE_APPLICATION_CREDENTIALS";
+export declare const GOOGLE_CLOUD_PROJECT_ENV = "GOOGLE_CLOUD_PROJECT";
+export declare const VERTEX_LOCATION_ENV = "VERTEX_LOCATION";
+export type VertexCredentials = {
+    credentialsPath: string;
+    secretDir: string;
+};
+export declare function isVertexRoute(model: string | undefined): boolean;
+export declare function readProjectIdFromVertexServiceAccountJson(): string | undefined;
+export declare function materializeVertexCredentials(params: {
+    model: string | undefined;
+}): VertexCredentials | undefined;
+export declare function cleanupVertexCredentials(credentials: VertexCredentials | undefined): void;
+export declare function applyClaudeVertexEnv(env: Record<string, string | undefined>): void;
+export declare function resolveVertexOpenCodeModel(model: string | undefined): string | undefined;

package/dist/utils/workflow.d.ts

@@ -0,0 +1,13 @@
+import type { OctokitWithPlugins } from "#app/utils/github";
+interface ResolveRunParams {
+    octokit: OctokitWithPlugins;
+}
+export interface ResolveRunResult {
+    runId: number | undefined;
+}
+/**
+ * Resolve GitHub Actions workflow run context.
+ * Uses GITHUB_REPOSITORY and GITHUB_RUN_ID env vars.
+ */
+export declare function resolveRun(_params: ResolveRunParams): Promise<ResolveRunResult>;
+export {};