Files
gcp_solution_architecture_a…/app/tools/local.py
Jonathan Boniface e9246828b3 feat: establish the Target architecture as a graph before code
Design is now approved before any infrastructure code is written (ADR-0005).
A new target-architect Specialist produces one graph of Elements,
Relationships and Checks; the diagram is rendered from it, deployment
guidance must account for every Check, and validation gives a verdict per
Check. Requirements, components, products and recommendations carry ids in
data files, and a submission with a gap in the Requirements chain is refused.

Also in this commit:
- Customer cases group Executions, with an intent history per case
- lesson candidates are captured when an Execution ends
- evaluation gains chain, verdict, judged and interactive checks, and
  per-case thresholds
- Terraform providers are cached between checks
- the requirements analyst proposes defaults instead of asking
- the legacy-baseline case and the checks that only read it are removed
- ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed
- plans for iterations 4 to 7 under .agents/plans/

Unproven with a real model: no evaluation run has completed on this design.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 13:59:09 +01:00

328 lines
12 KiB
Python

"""Local tools: a Mermaid syntax check and Terraform checks in a scratch directory.
Terraform runs only fmt, init -backend=false, validate and plan. No command that
changes cloud resources is ever constructed.
"""
from __future__ import annotations
import asyncio
import os
import re
import tempfile
from collections.abc import Awaitable, Callable, Iterable, Mapping
from dataclasses import dataclass, field
from pathlib import Path, PurePosixPath
from typing import Any
from app.adk.runtime import FILES_SCHEMA, ToolResult, ToolSpec, files_from_argument
_MAX_OUTPUT = 8_000
_TERRAFORM_SUFFIXES = (".tf", ".tfvars", ".tf.json")
_VARIABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$")
_MERMAID_TYPES = (
"flowchart",
"graph",
"sequenceDiagram",
"classDiagram",
"stateDiagram",
"stateDiagram-v2",
"erDiagram",
"C4Context",
"C4Container",
"C4Component",
"C4Deployment",
"architecture-beta",
"block-beta",
)
_BRACKETS = {"]": "[", ")": "(", "}": "{"}
async def mermaid_check(diagram: str) -> ToolResult:
"""A basic structural check; it does not render the diagram."""
problems = []
lines = [
line.strip()
for line in diagram.splitlines()
if line.strip() and not line.strip().startswith("%%")
]
if not diagram.strip():
problems.append("the diagram is empty")
elif not lines or lines[0].split()[0] not in _MERMAID_TYPES:
problems.append(
"the first line must declare a diagram type, such as 'flowchart TD'"
)
for number, line in enumerate(diagram.splitlines(), start=1):
stack: list[str] = []
in_quotes = False
for char in line:
if char == '"':
in_quotes = not in_quotes
elif in_quotes:
continue
elif char in "[({":
stack.append(char)
elif char in _BRACKETS and (not stack or stack.pop() != _BRACKETS[char]):
stack.append("!")
break
if stack:
problems.append(f"Unbalanced brackets on line {number}: {line.strip()}")
if problems:
return ToolResult("Mermaid check failed: " + "; ".join(problems))
return ToolResult("Mermaid check passed (structure only; not rendered).")
@dataclass
class TerraformRunner:
binary: str = "terraform"
timeout_seconds: float = 300
# Providers are downloaded here once and reused by every later check. Without it,
# each validate or plan downloads its providers again into a scratch directory.
plugin_cache_dir: str | None = None
# Terraform's plugin cache is not safe for concurrent installs.
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
refusal = _check_files(files)
if refusal:
return refusal
with tempfile.TemporaryDirectory(prefix="tf-fmt-") as tmp:
root = _write(Path(tmp), files)
code, output = await self._run(
[self.binary, "fmt", "-recursive", "-list=true"], root
)
if code != 0:
return ToolResult(f"terraform fmt failed:\n{output}")
changed = [
name for name in files if (root / name).read_text() != files[name]
]
if not changed:
return ToolResult("terraform fmt: all files are already formatted.")
formatted = "\n\n".join(
f"--- {name}\n{(root / name).read_text()}" for name in changed
)
return ToolResult(
_clip(
f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}"
)
)
async def validate(self, files: Mapping[str, str]) -> ToolResult:
refusal = _check_files(files)
if refusal:
return refusal
with tempfile.TemporaryDirectory(prefix="tf-validate-") as tmp:
root = _write(Path(tmp), files) / _module_dir(files)
failure = await self._init(root)
if failure:
return failure
code, output = await self._run([self.binary, "validate", "-no-color"], root)
verdict = "passed" if code == 0 else "failed"
return ToolResult(_clip(f"terraform validate {verdict}:\n{output}"))
async def plan(
self, files: Mapping[str, str], variables: Mapping[str, str] | None = None
) -> ToolResult:
refusal = _check_files(files)
if refusal:
return refusal
variables = dict(variables or {})
bad = [name for name in variables if not _VARIABLE_NAME.match(name)]
if bad:
return ToolResult(f"Refused: invalid variable names {', '.join(bad)}")
with tempfile.TemporaryDirectory(prefix="tf-plan-") as tmp:
root = _write(Path(tmp), files) / _module_dir(files)
failure = await self._init(root)
if failure:
return failure
args = [
self.binary,
"plan",
"-no-color",
"-input=false",
"-lock=false",
"-refresh=true",
*(f"-var={name}={value}" for name, value in variables.items()),
]
code, output = await self._run(args, root)
verdict = "completed" if code == 0 else "failed"
return ToolResult(
_clip(f"terraform plan {verdict} (nothing was applied):\n{output}")
)
async def _init(self, root: Path) -> ToolResult | None:
command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"]
if self.plugin_cache_dir:
async with self._init_lock:
code, output = await self._run(command, root)
else:
code, output = await self._run(command, root)
if code != 0:
return ToolResult(_clip(f"terraform init failed:\n{output}"))
return None
async def _run(
self, args: list[str], cwd: Path, env: Mapping[str, str] | None = None
) -> tuple[int, str]:
environment = {**os.environ, "TF_IN_AUTOMATION": "1", **(env or {})}
if self.plugin_cache_dir:
cache = Path(self.plugin_cache_dir).expanduser().resolve()
cache.mkdir(parents=True, exist_ok=True)
environment["TF_PLUGIN_CACHE_DIR"] = str(cache)
# Each check runs in a scratch directory with no dependency lock file.
# Without this, Terraform downloads a cached provider again to verify it.
environment["TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE"] = "true"
try:
process = await asyncio.create_subprocess_exec(
*args,
cwd=cwd,
env=environment,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.STDOUT,
)
except FileNotFoundError:
return 127, f"{self.binary} is not installed or not on PATH."
try:
stdout, _ = await asyncio.wait_for(
process.communicate(), timeout=self.timeout_seconds
)
except TimeoutError:
process.kill()
await process.wait()
return 124, f"{' '.join(args[:2])} timed out after {self.timeout_seconds}s."
return process.returncode or 0, stdout.decode(errors="replace")
def _check_files(files: Mapping[str, str]) -> ToolResult | None:
if not files:
return ToolResult("Refused: provide at least one Terraform file.")
bad = []
for name in files:
path = PurePosixPath(name)
if (
path.is_absolute()
or ".." in path.parts
or not name.endswith(_TERRAFORM_SUFFIXES)
):
bad.append(name)
if bad:
return ToolResult(
"Refused: file names must be relative .tf, .tf.json or .tfvars paths "
f"without '..': {', '.join(bad)}"
)
directories = {str(PurePosixPath(name).parent) for name in files}
if len(directories) > 1:
return ToolResult(
"Refused: put all files in one directory (one root module), for example "
f"terraform/main.tf and terraform/variables.tf; got {', '.join(sorted(directories))}"
)
return None
def _module_dir(files: Mapping[str, str]) -> str:
"""The one directory holding the files; Terraform runs there."""
return str(PurePosixPath(next(iter(files))).parent)
def _write(root: Path, files: Mapping[str, str]) -> Path:
for name, content in files.items():
target = root / name
target.parent.mkdir(parents=True, exist_ok=True)
target.write_text(content, encoding="utf-8")
return root
def _clip(text: str) -> str:
return text if len(text) <= _MAX_OUTPUT else text[:_MAX_OUTPUT] + "\n[truncated]"
_FILES_SCHEMA: dict[str, Any] = {
**FILES_SCHEMA,
"description": "Terraform files in one directory, e.g. terraform/main.tf",
}
def _with_files(
method: Callable[..., Awaitable[ToolResult]],
) -> Callable[..., Awaitable[ToolResult]]:
"""Adapt a runner method to take the FILES_SCHEMA argument."""
async def handler(files: Any, **kwargs: Any) -> ToolResult:
try:
converted = files_from_argument(files)
except TypeError as exc:
return ToolResult(f"Refused: files: {exc}")
return await method(converted, **kwargs)
return handler
LOCAL_TOOLS: dict[str, tuple[str, str]] = {
"mermaid_check": ("general", "Check a Mermaid diagram's basic structure."),
"terraform_fmt": ("general", "Format Terraform files and return any that changed."),
"terraform_validate": (
"general",
"Validate Terraform files offline (init -backend=false, validate).",
),
"terraform_plan": (
"cloud_read",
"Preview Terraform against the live cloud environment with a plan. Never applies.",
),
}
def local_tools(names: Iterable[str], runner: TerraformRunner) -> list[ToolSpec]:
builders = {
"mermaid_check": lambda: ToolSpec(
"mermaid_check",
LOCAL_TOOLS["mermaid_check"][1],
{
"type": "object",
"properties": {"diagram": {"type": "string"}},
"required": ["diagram"],
},
mermaid_check,
tier="general",
),
"terraform_fmt": lambda: ToolSpec(
"terraform_fmt",
LOCAL_TOOLS["terraform_fmt"][1],
{
"type": "object",
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
_with_files(runner.fmt),
tier="general",
),
"terraform_validate": lambda: ToolSpec(
"terraform_validate",
LOCAL_TOOLS["terraform_validate"][1],
{
"type": "object",
"properties": {"files": _FILES_SCHEMA},
"required": ["files"],
},
_with_files(runner.validate),
tier="general",
),
"terraform_plan": lambda: ToolSpec(
"terraform_plan",
LOCAL_TOOLS["terraform_plan"][1],
{
"type": "object",
"properties": {
"files": _FILES_SCHEMA,
"variables": {
"type": "object",
"additionalProperties": {"type": "string"},
},
},
"required": ["files"],
},
_with_files(runner.plan),
tier="cloud_read",
),
}
return [builders[name]() for name in names]