terramend 0.2.0

package/dist/mcp/terraform/scanners.d.ts

@@ -0,0 +1,131 @@
+import { type Concern, type ScannerOutcome } from "#app/mcp/terraform/types";
+export declare function scanFmt(cwd: string): ScannerOutcome;
+/** `terraform fmt -check -list=true` prints one unformatted file path per line. */
+export declare function parseFmtOutput(stdout: string, cwd?: string): Concern[];
+/**
+ * Run `terraform validate` across EVERY root and aggregate. `validate` is the
+ * one scanner that's per-root (fmt/tflint/trivy/checkov are recursive over the
+ * whole tree), so a multi-root repo only catches subdir-root validate errors
+ * when we visit each root.
+ */
+export declare function scanValidate(cwd: string): ScannerOutcome;
+/** parse `terraform validate -json`; keeps real errors, drops uninitialized-dir noise. */
+export declare function parseValidateOutput(stdout: string, cwd?: string): Concern[];
+export interface ProviderRequirement {
+    /** local name, e.g. `aws`. */
+    name: string;
+    /** registry source, e.g. `hashicorp/aws`, or null (legacy string form). */
+    source: string | null;
+    /** raw version constraint, e.g. `~> 5.0`, or null when unconstrained. */
+    version: string | null;
+    /** the pinned MAJOR (the lower-bound major of the constraint) — the number a
+     * fix must target, since argument schemas differ across provider majors. */
+    major: number | null;
+}
+/**
+ * Parse every `required_providers { … }` block in some HCL text into the pinned
+ * provider requirements. Handles the modern object form
+ * (`aws = { source = "hashicorp/aws", version = "~> 5.0" }`) and the legacy
+ * string form (`aws = "~> 5.0"`). A repo's "correct" fix depends on the provider
+ * MAJOR — argument names and valid blocks differ across AWS/Azure majors — so
+ * surfacing the pinned major lets a fix target the right schema instead of
+ * breaking `plan`. Brace-matched (not a fragile single regex) so nested objects
+ * don't confuse it. First declaration of a name wins (dedup across files).
+ */
+export declare function parseRequiredProviders(hcl: string): ProviderRequirement[];
+/** read the repo's `*.tf` files (recursively — root + subdir roots + nested
+ * modules) and parse their pinned provider requirements (best-effort; an
+ * unreadable tree yields none). First declaration of a provider wins. */
+export declare function collectProviderRequirements(cwd: string): ProviderRequirement[];
+/** the top-level arguments of a single `resource` block. */
+export interface ResourceArguments {
+    resourceType: string;
+    /** the resource's local name (`resource "aws_s3_bucket" "<name>"`). */
+    name: string;
+    /** top-level attribute + nested-block names (meta-arguments excluded). */
+    args: string[];
+}
+/**
+ * Parse every `resource "<type>" "<name>" { … }` block's TOP-LEVEL argument
+ * names (attributes assigned with `=` and nested block labels) from some HCL.
+ * Conservative by design — it skips `"…"` strings and `#`/`//` line comments so
+ * an interpolation's braces or a commented line can't corrupt the brace depth or
+ * fabricate an argument, and only reports depth-0 names. A `dynamic "x"` block
+ * contributes `x` (the generated block type). Used to cross-check written
+ * arguments against the installed provider schema; pure.
+ */
+export declare function parseResourceArguments(hcl: string): ResourceArguments[];
+export interface UnknownArgument {
+    resource_type: string;
+    /** the resource's local name. */
+    name: string;
+    /** repo-relative file the resource is declared in. */
+    file: string;
+    /** the argument names not present in the installed provider's schema. */
+    unknown: string[];
+}
+/**
+ * §4.15-next — cross-check every resource's written arguments against the
+ * INSTALLED provider's schema, so an argument that's invalid for the pinned
+ * provider major (a "correct" fix for the wrong version) is caught at validate
+ * time, not as a later `plan` failure. Degrades green: returns
+ * `{ checked: false }` when the schema is unavailable (terraform not installed /
+ * dir not init-ed). A resource type absent from the schema is skipped (can't
+ * judge), never flagged.
+ */
+export declare function checkArgumentsAgainstSchema(cwd: string): {
+    checked: boolean;
+    unknown_arguments: UnknownArgument[];
+};
+export declare function scanTflint(cwd: string): ScannerOutcome;
+/** parse `tflint --format json` output into concerns. */
+export declare function parseTflintOutput(stdout: string, cwd?: string): Concern[];
+/**
+ * Parse `trivy config --format json` output into concerns. Trivy nests
+ * misconfigurations under `Results[].Misconfigurations[]`, keyed to the result's
+ * `Target` file. `trivy config` reports only failures by default, but we
+ * defensively drop any `Status: "PASS"` entry so an `--include-non-failures`
+ * run can't leak passing checks into the concern set.
+ */
+export declare function parseTrivyOutput(stdout: string, cwd?: string): Concern[];
+/** parse `checkov -o json` output (object for one framework, array for several). */
+export declare function parseCheckovOutput(stdout: string, cwd?: string): Concern[];
+/**
+ * Terraform files changed on the current branch vs the base. Returns null when
+ * the base can't be determined (caller then falls back to a full scan).
+ */
+export declare function changedTerraformFiles(cwd: string): Set<string> | null;
+/** run every scanner once over `cwd`. shared by `terraform_scan` and the
+ * deterministic remediation verifier so both see the identical toolchain. */
+export declare function runScanners(cwd: string): ScannerOutcome[];
+export interface RemediationVerdict {
+    /** true only when every original concern id is absent from the re-scan. */
+    verified: boolean;
+    /** original ids no longer present (the fix cleared them). */
+    resolved: string[];
+    /** original ids still present (the fix did NOT clear them). */
+    remaining: string[];
+}
+/**
+ * Deterministic ✗→✓ check: partition the group's original `concern_ids` into
+ * those gone from a fresh scan (`resolved`) and those still present
+ * (`remaining`). Concern ids are content hashes (`sha1(source|rule|file|line)`),
+ * so a missing id means that exact concern is gone — the correct primitive for
+ * "did the fix clear it", independent of severity/scope filtering. This is the
+ * code-level replacement for the agent eyeballing a re-scan and self-reporting.
+ */
+export declare function computeRemediationVerdict(originalConcernIds: string[], currentConcernIds: Set<string>): RemediationVerdict;
+/**
+ * §1.4 Regression guard. The full re-scan (`terraform_verify_remediation`)
+ * already sees the whole workspace, so a concern the fix *introduced* shows up
+ * in the current scan. Regressions are exactly the content ids present after the
+ * fix that were not in the pre-fix baseline — `current − baseline`. A non-empty
+ * result means the fix traded one defect for another (e.g. an encryption block
+ * that trips a different tflint rule) and must downgrade the PR to needs-human.
+ *
+ * Both id sets are computed the same way (the deduped union of every scanner's
+ * concern ids, unfiltered by severity) so the diff is apples-to-apples — a
+ * regression at ANY severity is caught, not just ones above the run threshold.
+ * Returns sorted ids for a stable PR body.
+ */
+export declare function computeRegressions(baselineConcernIds: Iterable<string>, currentConcernIds: Iterable<string>): string[];

package/dist/mcp/terraform/tools.d.ts

@@ -0,0 +1,63 @@
+import type { LocalToolContext } from "#app/mcp/localContext";
+export declare const TerraformScanParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    scan_scope?: "diff" | "full";
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+    group_by?: "file" | "rule";
+}, {}>;
+export declare function TerraformScanTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    scan_scope?: "diff" | "full";
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+    group_by?: "file" | "rule";
+}, {
+    scan_scope?: "diff" | "full";
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+    group_by?: "file" | "rule";
+}>>;
+export declare const TerraformValidateParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    paths?: string[];
+}, {}>;
+export declare function TerraformValidateTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    paths?: string[];
+}, {
+    paths?: string[];
+}>>;
+export declare const TerraformVerifyRemediationParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    concern_ids: string[];
+}, {}>;
+export declare function TerraformVerifyRemediationTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    concern_ids: string[];
+}, {
+    concern_ids: string[];
+}>>;
+export declare const InfracostDiffParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function InfracostDiffTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>>;
+export declare const TerraformEmitSarifParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    output_path?: string;
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+}, {}>;
+export declare function TerraformEmitSarifTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    output_path?: string;
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+}, {
+    output_path?: string;
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+}>>;
+export declare function collectCloudCredentials(): Record<string, string>;
+export declare const TerraformPlanParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function TerraformPlanTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>>;
+export declare const ReadFindingsParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    path?: string;
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+    group_by?: "file" | "rule";
+}, {}>;
+export declare function ReadFindingsTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    path?: string;
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+    group_by?: "file" | "rule";
+}, {
+    path?: string;
+    severity_threshold?: "critical" | "high" | "medium" | "low" | "info";
+    group_by?: "file" | "rule";
+}>>;
+export declare const TerraformVersionCurrencyParams: import("arktype/internal/variants/object.ts").ObjectType<object, {}>;
+export declare function TerraformVersionCurrencyTool(ctx: LocalToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<object, object>>;

package/dist/mcp/terraform/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * A degrade-green skip result carrying the structured §3.5 envelope
+ * (`ok: false` + machine `code` + human `detail`) PLUS the legacy alias the tool
+ * returned before it converged on the envelope — `ran`/`found` and
+ * `skipped_reason`/`reason` — so existing prompt + test contracts keep working.
+ * Additive, never breaking. `extra` folds in any tool-specific fields (e.g.
+ * read_findings' empty `concerns`/`groups`).
+ */
+export declare function skipResult(code: string, detail: string, opts?: {
+    key?: "ran" | "found";
+    reasonKey?: "skipped_reason" | "reason";
+    extra?: Record<string, any>;
+}): Record<string, any>;
+/**
+ * Internal "concern" model — the Remediator's ground truth for "what is not
+ * best practice". Produced by `terraform_scan` from the fork's own deterministic
+ * Terraform check tools (fmt / validate / tflint / trivy / checkov).
+ *
+ * This is a deliberate SUBSET of the reviewer's `findings.schema.json` v1.0
+ * (../terraform-reviewer/schemas/findings.schema.json). The reviewer's findings
+ * add `lens` / `standard` / `control_id` / `state` on top. Keeping the shape a
+ * subset means a future reviewer integration (read_findings) can emit the same
+ * Concern[] with no change to the modes or the rest of the tools — only the
+ * SOURCE of concerns swaps.
+ */
+export interface Concern {
+    /** stable content id: sha1(source|rule_id|file|line). idempotency key for branch/PR naming. */
+    id: string;
+    /** producing tool. `reviewer` marks a concern loaded from a terraform-reviewer
+     * findings.json whose original tool isn't one Terramend re-runs (tfsec / infracost
+     * / llm) — its provenance lives in `rule_id`. */
+    source: "terraform-fmt" | "terraform-validate" | "tflint" | "trivy" | "checkov" | "reviewer";
+    /** original namespaced rule, e.g. "trivy:AVD-AWS-0088" */
+    rule_id: string;
+    severity: Severity;
+    category: "security" | "style" | "correctness" | "cost";
+    /** the scanner message — what is wrong */
+    evidence: string;
+    location: {
+        file: string;
+        line: number | null;
+    };
+    remediation_hint: string | null;
+}
+export declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+export type Severity = (typeof SEVERITIES)[number];
+export declare const SEVERITY_RANK: Record<Severity, number>;
+export declare function concernId(source: string, ruleId: string, file: string, line: number | null): string;
+/**
+ * Normalize a scanner-reported path to a repo-relative POSIX path. Each scanner
+ * reports the file differently — tflint gives `main.tf` (relative), trivy a
+ * scan-dir-relative `Target`, terraform an absolute path (`/repo/main.tf` or
+ * `D:\repo\main.tf`), checkov a leading-slash path (`/main.tf`). Left
+ * unnormalized, these leak into `location.file` AND the
+ * content-derived `concernId`, making the id (and the `remediate/<id>` branch)
+ * machine-dependent and breaking the ✗→✓ re-scan id match across environments.
+ * So normalize BEFORE building any Concern.
+ */
+export declare function toRepoRelative(raw: string | undefined, cwd: string): string;
+export type RunResult = {
+    status: number;
+    stdout: string;
+    stderr: string;
+    missing: boolean;
+};
+/**
+ * Hard wall-clock cap on any single scanner/terraform invocation. Bounds a hung
+ * subprocess (e.g. `terraform init`/`plan` stalling on a private registry, a
+ * tflint plugin fetch that never returns) so it can't block the run forever.
+ * Generous (5 min) so it only ever fires on a genuine hang, never a slow-but-
+ * progressing plan. A timeout surfaces as a non-zero/`-1` status the caller
+ * already treats as "this scanner did not produce results".
+ */
+export declare const SUBPROCESS_TIMEOUT_MS = 300000;
+/**
+ * Run a scanner without throwing. Terraform tools exit non-zero when they FIND
+ * issues, so a non-zero status is normal, not an error. `missing` is set when
+ * the binary isn't on PATH (ENOENT) — the scanner then degrades to "skipped"
+ * rather than failing the run (plan §9.2: a tool being absent must not block).
+ *
+ * `extraEnv` opts a specific command back into a needed credential: the scanners
+ * run with a restricted env that strips every `*_KEY`/secret, but infracost
+ * legitimately needs its `INFRACOST_API_KEY`. resolveEnv(object) merges the
+ * restricted base with the explicit vars, so only the named keys get through.
+ */
+export declare function run(cmd: string, args: string[], cwd: string, extraEnv?: Record<string, string>): RunResult;
+export type ScannerOutcome = {
+    source: Concern["source"];
+    ran: boolean;
+    skipped_reason?: string;
+    concerns: Concern[];
+    /**
+     * For `terraform validate` only: count of roots where terraform RAN but its
+     * `-json` output could not be parsed (a real CLI-level failure, not a missing
+     * binary). Lets the validate tool report `passed` as fail-closed instead of
+     * silently treating an un-validated root as clean. Undefined/0 elsewhere.
+     */
+    unvalidated?: number;
+};
+export declare function skipped(source: Concern["source"], reason: string): ScannerOutcome;
+export interface ResolvedRoot {
+    /** absolute dir the per-root command (init/plan/validate) runs in. */
+    absDir: string;
+    /** that root's path relative to the scan `cwd` ("" when the root IS cwd) —
+     * prepended to per-root concern files so they stay cwd-relative. */
+    relDir: string;
+}
+/**
+ * The Terraform root modules to operate on under `cwd`. A repo can hold several
+ * roots (hepcare: `terraform/` + `terraform/core/`); `terraform validate` /
+ * `plan` are per-root, so they must run in EACH. Falls back to `cwd` itself as a
+ * single root when none is detected — so a normal single-root repo behaves
+ * exactly as before (no rebasing, one iteration).
+ */
+export declare function resolveRoots(cwd: string): ResolvedRoot[];
+/**
+ * Re-base a concern produced by a per-root command (its file is relative to the
+ * root dir) onto the scan `cwd` by prefixing the root's `relDir`, and recompute
+ * the content id so it stays consistent with the cwd-relative scanners (✗→✓).
+ * A no-op when `relDir` is "" (the root IS cwd).
+ */
+export declare function rebaseConcern(c: Concern, relDir: string): Concern;
+/** true when a path is a Terraform source file Terramend may remediate. */
+export declare function isTerraformFile(file: string): boolean;
+/**
+ * Terramend is Terraform-only. A concern in a non-`.tf`/`.tfvars` file can never
+ * be remediated (the `allowed_paths` push guardrail blocks it) and is pure noise,
+ * so any scanner that also inspects other IaC — checkov's github_actions, trivy's
+ * dockerfile/kubernetes — gets filtered down to Terraform here. This is the
+ * catch-all backstop; `scanCheckov` also scopes itself with `--framework terraform`.
+ */
+export declare function isTerraformConcern(c: Concern): boolean;
+export declare function dedupe(concerns: Concern[]): Concern[];
+export declare function sortConcerns(concerns: Concern[]): Concern[];
+export declare function lowerSeverity(s: string | undefined): Severity;
+/** the repo's base ref for diff-scope, or null when one can't be determined. */
+export declare function resolveBaseRef(cwd: string): string | null;
+/**
+ * A scoped unit of work = all concerns in one file. Different scanners flag the
+ * same underlying defect under different rule ids (trivy ∩ checkov overlap
+ * heavily on e.g. S3 buckets), so per-concern PRs would spam many PRs for one
+ * bad file. Remediate acts on ONE group per PR (branch `remediate/<group.id>`),
+ * fixing every concern in the file together and proving them all cleared (✗→✓).
+ */
+export interface ConcernGroup {
+    /** stable id — the remediation branch/PR key (`remediate/<id>`). Derived from
+     * the file (by-file grouping) or the rule (by-rule grouping). */
+    id: string;
+    /** the group's primary file (by-file) or a human label like "3 files"
+     * (by-rule); `files` carries the full list for by-rule groups. */
+    file: string;
+    /** §3.11 — every file the group spans. one entry for a by-file group; the
+     * full set for a by-rule group (the agent must fix the rule in all of them). */
+    files?: string[];
+    /** how the group was formed — `file` (default) or `rule` (§3.11). */
+    grouping?: "file" | "rule";
+    /** highest severity among the group's concerns. */
+    severity: Severity;
+    concern_count: number;
+    /** distinct rule ids in the group, for the PR body. */
+    rule_ids: string[];
+    /** the concern ids the re-scan must confirm are gone to call this ✓. */
+    concern_ids: string[];
+    /** §3.9 — `auto` (open a normal PR) or `needs-human` (escalate). attached by
+     * the scan tool from the group's concerns, not by `groupConcerns` (which has
+     * no autonomy threshold). undefined until the scan tool annotates it. */
+    autonomy?: Autonomy;
+    /** §3.9 — why the group was escalated (empty/absent for `auto`). */
+    autonomy_reasons?: string[];
+}
+export type Autonomy = "auto" | "needs-human";
+export type BlastTier = "low" | "medium" | "high";

package/dist/mcp/terraform.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Facade for the Terraform MCP toolchain. The implementation lives in the
+ * per-concern modules under `./terraform/`; this file re-exports every symbol so
+ * existing importers (`#app/mcp/terraform`) keep resolving unchanged.
+ *
+ *   types     — Concern + shared types/helpers (ids, paths, roots, severity)
+ *   scanners  — fmt / validate / tflint / trivy / checkov + provider/arg schema
+ *   decisions — grouping, autonomy, confidence, refusal, prevention, co-location
+ *   cost      — infracost breakdown / delta / escalation
+ *   currency  — registry version currency (provider + module upgrade intel)
+ *   findings  — reviewer findings + SARIF ingest/emit
+ *   plan      — plan parsing + destroy/blast/stability/aggregation
+ *   tools     — the MCP Tool factories + their *Params schemas
+ */
+export * from "#app/mcp/terraform/cost";
+export * from "#app/mcp/terraform/currency";
+export * from "#app/mcp/terraform/decisions";
+export * from "#app/mcp/terraform/findings";
+export * from "#app/mcp/terraform/plan";
+export * from "#app/mcp/terraform/scanners";
+export * from "#app/mcp/terraform/tools";
+export * from "#app/mcp/terraform/types";

package/dist/mcp/terratest.d.ts

@@ -0,0 +1,83 @@
+import type { ToolContext } from "#app/mcp/server";
+/**
+ * §28 Terratest scaffolding (opt-in via the `terratest` input). When Terramend
+ * GENERATES a reusable module, it can also scaffold a minimal Go
+ * [Terratest](https://terratest.gruntwork.io/) smoke test + a Terraform-native
+ * `*.tftest.hcl` so the generated infrastructure is testable from the first
+ * commit. Both tests plan the module **directly** — Terramend does not generate
+ * `examples/` fixtures.
+ *
+ * Design choices:
+ *  - **Plan-only, never apply.** The scaffolded tests run `terraform init` +
+ *    `plan` against the module and assert it plans cleanly. Terramend never
+ *    applies (no cloud credentials — the sovereignty stance), so the generated
+ *    tests mirror that: they're a deployability smoke test the USER runs in their
+ *    own pipeline (with creds) for real apply/assert coverage.
+ *  - **Pure generation.** The file contents are computed deterministically here
+ *    and unit-tested; the agent writes the returned files with its own tools.
+ *  - The Go test + native test files fall outside the Terraform-only default
+ *    allow-list, so the `terratest` input also widens the push guardrail (see
+ *    guardrails.ts).
+ */
+export interface ScaffoldFile {
+    /** repo-relative path to write. */
+    path: string;
+    content: string;
+}
+export interface TerratestScaffold {
+    files: ScaffoldFile[];
+    notes: string[];
+}
+/**
+ * Build a Terratest smoke-test + native test for a generated module. Pure:
+ * `moduleName` names the module, `modulePath` is its repo-relative dir, and
+ * `variables` (optional) are surfaced as TODO placeholders so the test author
+ * fills in real values. Both tests plan the module directly (no `examples/`
+ * fixture). Returns the files to write + operator notes.
+ */
+export declare function scaffoldTerratest(opts: {
+    moduleName: string;
+    modulePath: string;
+    variables?: {
+        name: string;
+        required?: boolean;
+    }[];
+}): TerratestScaffold;
+/**
+ * §28 (native variant) — scaffold a Terraform-native test (Terraform 1.6+) that
+ * lives in the module's own `tests/` dir and plans the module in place. Lighter
+ * than Terratest: no Go toolchain, just HCL that Terraform runs with
+ * `terraform test`. Plan-only `run` block (no apply, so no cloud needed to
+ * construct the test). Pure.
+ */
+export declare function scaffoldTerraformTest(opts: {
+    moduleName: string;
+    modulePath: string;
+    variables?: {
+        name: string;
+        required?: boolean;
+    }[];
+}): ScaffoldFile;
+export declare const ScaffoldTerratestParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    module_name: string;
+    module_path: string;
+    variables?: {
+        name: string;
+        required?: boolean;
+    }[];
+}, {}>;
+export declare function ScaffoldTerratestTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    module_name: string;
+    module_path: string;
+    variables?: {
+        name: string;
+        required?: boolean;
+    }[];
+}, {
+    module_name: string;
+    module_path: string;
+    variables?: {
+        name: string;
+        required?: boolean;
+    }[];
+}>>;

package/dist/mcp/upload.d.ts

@@ -0,0 +1,6 @@
+import type { ToolContext } from "#app/mcp/server";
+export declare function UploadFileTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    path: string;
+}, {
+    path: string;
+}>>;

package/dist/models.d.ts

@@ -0,0 +1,171 @@
+/**
+ * model alias registry.
+ *
+ * slugs use the format `provider/model-id` (e.g. "anthropic/claude-opus").
+ * bump `resolve` when a new model generation ships — the alias (slug) stays stable.
+ */
+/**
+ * routing discriminant for entries whose `resolve` is dynamic — looked up
+ * from a separate env var at run time rather than fixed in the catalog.
+ *
+ * `"bedrock"` means the actual model ID comes from `BEDROCK_MODEL_ID`
+ * (an AWS-canonical Bedrock model ID like `eu.anthropic.claude-opus-4-7`
+ * or `amazon.nova-pro-v1:0`). `"vertex"` means the actual model ID comes
+ * from `VERTEX_MODEL_ID` (a Vertex AI model ID like
+ * `claude-opus-4-1@20250805` or `gemini-2.5-pro`). enterprise hosted-model
+ * customers self-select for version control — silent alias bumps would break
+ * compliance review, model-access enrollment, and provisioned-throughput
+ * contracts. so the single `bedrock/byok` and `vertex/byok` entries are
+ * routing slugs, not model aliases: the harness reads the backend-specific
+ * env var and routes to claude-code for Anthropic IDs or opencode for
+ * everything else.
+ */
+export type ModelRouting = "bedrock" | "vertex";
+export interface ModelAlias {
+    /** stable alias stored in DB, e.g. "anthropic/claude-opus" */
+    slug: string;
+    /** provider key (matches providers keys) */
+    provider: string;
+    /** human-readable name shown in dropdowns */
+    displayName: string;
+    /** concrete models.dev specifier, e.g. "anthropic/claude-opus-4-6". sentinel for routing entries — never passed to a CLI directly. */
+    resolve: string;
+    /** full models.dev specifier for the OpenRouter equivalent (undefined for free models and routing entries) */
+    openRouterResolve: string | undefined;
+    /** top-tier pick for this provider — preferred during auto-select */
+    preferred: boolean;
+    /** whether this alias is free and requires no API key */
+    isFree: boolean;
+    /** slug of a replacement model — presence implies this model is deprecated */
+    fallback: string | undefined;
+    /** dynamic-resolution discriminant — see ModelRouting docs */
+    routing: ModelRouting | undefined;
+    /** alias key (within same provider) of the cheaper sibling reviewfrog should
+     * use as its lens-fanout subagent. e.g. claude-opus → "claude-sonnet". */
+    subagentModel: string | undefined;
+    /** hide from selectable lists (UI dropdowns, CLI pickers). does NOT affect
+     * resolution — for that use `fallback`. used for internal-only tier targets
+     * (e.g. gpt-5.4 as a subagent target without exposing it to users). */
+    hidden: boolean;
+}
+interface ModelDef {
+    displayName: string;
+    /** concrete models.dev specifier, e.g. "anthropic/claude-opus-4-6" */
+    resolve: string;
+    /** full models.dev specifier for the OpenRouter equivalent, e.g. "openrouter/anthropic/claude-opus-4.6" */
+    openRouterResolve?: string;
+    preferred?: boolean;
+    envVars?: readonly string[];
+    isFree?: boolean;
+    /** slug of a replacement model — presence implies this model is deprecated */
+    fallback?: string;
+    /** dynamic-resolution discriminant — see ModelRouting docs */
+    routing?: ModelRouting;
+    /** alias key (within same provider) of the cheaper sibling reviewfrog should
+     * use as its lens-fanout subagent (e.g. claude-opus → "claude-sonnet"). */
+    subagentModel?: string;
+    /** hide from selectable lists. does NOT affect resolution; for that use `fallback`. */
+    hidden?: boolean;
+}
+export interface ProviderConfig {
+    displayName: string;
+    envVars: readonly string[];
+    /** credentials authored only via `terramend auth <provider>` — never
+     * user-facing in `init`, never documented as a manual GHA secret. counted
+     * for hasAnyKey / log-redaction purposes but excluded from any prompt /
+     * paste flow. CLI-managed magic. see wiki/codex-auth.md. */
+    managedCredentials?: readonly string[];
+    models: Record<string, ModelDef>;
+}
+export declare const providers: {
+    anthropic: ProviderConfig;
+    openai: ProviderConfig;
+    google: ProviderConfig;
+    xai: ProviderConfig;
+    deepseek: ProviderConfig;
+    moonshotai: ProviderConfig;
+    opencode: ProviderConfig;
+    bedrock: ProviderConfig;
+    vertex: ProviderConfig;
+    openrouter: ProviderConfig;
+};
+export type ModelProvider = keyof typeof providers;
+export declare function parseModel(slug: string): {
+    provider: string;
+    model: string;
+};
+export declare function getModelProvider(slug: string): string;
+export declare function getProviderDisplayName(slug: string): string | undefined;
+export declare function getModelEnvVars(slug: string): string[];
+/** managed credentials are authored only via `terramend auth <provider>` — they
+ * count as "configured" for hasAnyKey-style UI checks but are never offered as
+ * a manual-paste option in `init` or the AgentSettings env-var button row.
+ * see `provider.managedCredentials` and wiki/codex-auth.md. */
+export declare function getModelManagedCredentials(slug: string): string[];
+export declare const modelAliases: ModelAlias[];
+export declare const DEFAULT_PROXY_MODEL: string;
+/** short label for the model auto-select picks today (console hint copy). */
+export declare function getAutoSelectHintModel(): string;
+/** resolve a model slug to its concrete models.dev specifier (e.g. "anthropic/claude-opus-4-6") */
+export declare function resolveModelSlug(slug: string): string | undefined;
+/**
+ * walk the fallback chain to the terminal (non-deprecated) alias.
+ * returns undefined if the chain is broken, exhausted, or cyclic.
+ *
+ * use this in UI display sites (dropdown trigger labels, PR-comment footers,
+ * etc.) so a deprecated stored slug renders as the model the user actually
+ * runs against — not the historical name. selectable lists should still hide
+ * deprecated and internal-only aliases by filtering on `!a.fallback && !a.hidden`.
+ */
+export declare function resolveDisplayAlias(slug: string): ModelAlias | undefined;
+/**
+ * resolve a model slug to the CLI-ready model string, following the fallback
+ * chain when a model is deprecated. returns the first non-deprecated resolve
+ * target, or undefined if the chain is exhausted or broken.
+ */
+export declare function resolveCliModel(slug: string): string | undefined;
+/**
+ * resolve a model slug to the OpenRouter-ready model string, following the
+ * fallback chain when a model is deprecated. returns undefined if the chain
+ * is exhausted/broken or the terminal alias has no openrouter equivalent
+ * (e.g. free opencode models).
+ */
+export declare function resolveOpenRouterModel(slug: string): string | undefined;
+/** env var that supplies the Bedrock model ID for the `bedrock/byok` slug. */
+export declare const BEDROCK_MODEL_ID_ENV = "BEDROCK_MODEL_ID";
+/** env var that supplies the Vertex AI model ID for the `vertex/byok` slug. */
+export declare const VERTEX_MODEL_ID_ENV = "VERTEX_MODEL_ID";
+/**
+ * the Bedrock model ID passed to claude-code or opencode is whatever the
+ * user set in `BEDROCK_MODEL_ID` — Terramend never resolves or upgrades it.
+ * we route by checking whether the ID names an Anthropic model: claude-code
+ * handles Anthropic-on-Bedrock natively (with `CLAUDE_CODE_USE_BEDROCK=1`),
+ * everything else goes through opencode's `amazon-bedrock` provider.
+ *
+ * AWS Bedrock IDs come in two shapes:
+ *   - dotted foundation IDs: `eu.anthropic.claude-opus-4-7`,
+ *     `anthropic.claude-haiku-4-5-20251001-v1:0`, `amazon.nova-pro-v1:0`,
+ *     `meta.llama4-scout-17b-instruct-v1:0`. AWS-published, lowercase, the
+ *     foundation provider always appears as a discrete dot-segment.
+ *   - inference-profile ARNs: `arn:aws:bedrock:eu-west-2:<acct>:application-inference-profile/<user-name>`.
+ *     `<user-name>` is operator-chosen, so a naive substring check is fragile
+ *     in both directions (Anthropic profile named without "anthropic" → routes
+ *     to opencode and misses CLAUDE_CODE_USE_BEDROCK; non-Anthropic profile
+ *     whose name happens to contain "anthropic" → routes to claude-code).
+ *
+ * we anchor on a discrete dot-segment match (case-insensitive). this catches
+ * every published foundation ID and is conservative for ARN-form IDs: ARN
+ * names that don't include "anthropic" as their own dot-segment route to
+ * opencode by default. operators using ARN-form IDs whose backing model is
+ * Anthropic should set `TERRAMEND_AGENT=claude` to force the right route, or
+ * include the foundation segment in the profile name.
+ */
+export declare function isBedrockAnthropicId(bedrockModelId: string): boolean;
+/**
+ * Vertex Anthropic model IDs start with the Claude family name, e.g.
+ * `claude-opus-4-1@20250805`. partner-model resource paths can contain the
+ * substring "anthropic" elsewhere, so the Bedrock segment check does not
+ * transfer — anchor on the model ID prefix instead.
+ */
+export declare function isVertexAnthropicId(vertexModelId: string): boolean;
+export {};