terramend 0.2.0

package/dist/utils/terraformMcp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * HashiCorp terraform-mcp-server integration (P2.2).
+ *
+ * When the `terraform_mcp` input is on, the agent harness registers a SECOND
+ * MCP server next to terramend'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-PINNED (`TERRAFORM_MCP_IMAGE`); bump deliberately.
+ *     (P4's SHA-pinning sweep will move this to a digest pin.)
+ *   - 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 { ResolvedPayload } from "#app/utils/payload";
+/** pinned release of hashicorp/terraform-mcp-server. Bump deliberately. */
+export declare const TERRAFORM_MCP_IMAGE = "hashicorp/terraform-mcp-server:0.5.2";
+/** 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: Pick<ResolvedPayload, "terraformMcp">): 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,39 @@
+import type { PushPermission } from "#app/external";
+import { acquireNewToken } from "#app/utils/github";
+export { acquireNewToken as acquireInstallationToken, revokeGitHubInstallationToken as revokeInstallationToken, };
+/**
+ * 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 = {
+    gitToken: string;
+    mcpToken: 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/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 {};

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "terramend",
+  "version": "0.2.0",
+  "description": "GitHub Action that remediates Terraform to best practices and opens one scoped pull request per concern.",
+  "keywords": [
+    "github-actions",
+    "terraform",
+    "iac",
+    "remediation",
+    "best-practices",
+    "ai-coding-agent"
+  ],
+  "homepage": "https://github.com/terramend/terramend#readme",
+  "bugs": {
+    "url": "https://github.com/terramend/terramend/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/terramend/terramend.git"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Gabriel Ignat",
+  "type": "module",
+  "imports": {
+    "#app/*": "./src/*.ts",
+    "#package.json": "./package.json"
+  },
+  "exports": {
+    ".": {
+      "@terramend/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./internal": {
+      "@terramend/source": "./src/internal/index.ts",
+      "types": "./dist/internal/index.d.ts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "terramend": "dist/cli.mjs"
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "scripts": {
+    "build": "node esbuild.config.js && tsc -p tsconfig.exports.json",
+    "check:entrypoints": "node scripts/check-entrypoint-imports.ts",
+    "dev:run": "node dev-run.ts",
+    "docker": "node docker.ts",
+    "docs:inputs": "node scripts/generate-input-docs.ts",
+    "docs:models": "node scripts/generate-model-docs.ts",
+    "eval:review": "node test/eval/review.ts",
+    "eval:scan": "node test/eval/run.ts",
+    "format": "biome format --write .",
+    "lint": "biome check .",
+    "lint:ci": "biome ci .",
+    "lint:fix": "biome check --write .",
+    "lock": "pnpm install --no-frozen-lockfile",
+    "runtest": "node test/run.ts",
+    "test": "vitest",
+    "test:catalog": "vitest run --config vitest.main.config.ts",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "upDeps": "pnpm up --latest"
+  },
+  "devDependencies": {
+    "@actions/core": "^3.0.1",
+    "@anthropic-ai/claude-code": "2.1.170",
+    "@ark/fs": "0.56.0",
+    "@ark/util": "0.56.0",
+    "@biomejs/biome": "^2.4.16",
+    "@clack/prompts": "^1.5.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@octokit/plugin-throttling": "^11.0.3",
+    "@octokit/rest": "^22.0.1",
+    "@octokit/webhooks-types": "^7.6.1",
+    "@opencode-ai/sdk": "1.17.3",
+    "@standard-schema/spec": "1.1.0",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@toon-format/toon": "^2.3.0",
+    "@types/node": "^25.9.2",
+    "@types/semver": "^7.7.1",
+    "@types/turndown": "^5.0.6",
+    "@vitest/coverage-v8": "^4.1.8",
+    "ajv": "^8.20.0",
+    "arg": "^5.0.2",
+    "arkregex": "0.0.5",
+    "arktype": "2.2.0",
+    "dotenv": "^17.4.2",
+    "esbuild": "^0.28.0",
+    "execa": "^9.6.1",
+    "fastmcp": "^4.1.0",
+    "file-type": "^22.0.1",
+    "opencode-ai": "1.17.3",
+    "package-manager-detector": "^1.6.0",
+    "picocolors": "^1.1.1",
+    "semver": "7.8.3",
+    "table": "^6.9.0",
+    "turndown": "^7.2.4",
+    "typescript": "6.0.3",
+    "undici": "^8.4.1",
+    "vitest": "^4.1.8",
+    "yaml": "^2.9.0"
+  },
+  "packageManager": "pnpm@11.5.2",
+  "engines": {
+    "node": ">=24",
+    "pnpm": ">=11"
+  }
+}