io.github.xmpuspus/cloudwright

Analyze blast radius and dependency structure of an architecture. For each component (or just one, if `component_id` is set): returns direct dependents, transitive dependents, blast-radius size, SPOF status, and tier position. Use this to reason about failure modes — 'if component X dies, what else breaks?' When to use: You have a spec and want to understand coupling and failure domains before production. Complementary to `score_architecture` (which gives a summary grade) and `lint_architecture` (which flags specific anti-patterns). Behavior: Pure graph computation — no LLM, no network. Read-only. Does not touch cloud resources.

Score an architecture across reliability, security, cost, compliance, and complexity. Returns the dimension scores, overall weighted score (0-100), letter grade, and per-dimension notes. Weights: Reliability 30% (load balancing, multi-AZ, auto-scaling, CDN, caching), Security 25% (WAF, auth, encryption, HTTPS, DNS), Cost Efficiency 20% (budget compliance, free- tier usage), Compliance 15% (framework validation), Complexity 10% (component count, connection density, tier separation). When to use: You want a quick quality summary before a design review. For specific findings, use `lint_architecture`, `security_scan`, or `validate_compliance`. Behavior: Pure computation — no LLM, no network. Read-only.

Diff two architecture specs and return a structured change report. Returns a structured delta: components added / removed / modified, connections added / removed / modified, cost delta (USD/month), compliance-impact flags (e.g. WAF removal, encryption-at-rest turned off), and a human-readable summary. When to use: You have two versions of a spec (before / after a proposed change) and need a reviewable diff for approval or ADR writing. Behavior: Pure computation — no LLM, no network. Read-only. Does not modify either spec.

Export an architecture spec to Terraform, CloudFormation, Mermaid, D2, or other formats. Returns `{'format': str, 'content': str}` where `content` is the ready-to-write payload. Terraform/CFN outputs use variables for sensitive values (no hardcoded credentials), include provider blocks with region configuration, and generate data sources for VPC/subnet discovery. When to use: You have a finalized ArchSpec and need IaC code, a diagram, or an audit artifact. For multi-format export, call once per `format`. Behavior: Pure computation — no LLM, no network. Does not write files or deploy; the caller is responsible for persisting or applying the returned content.

List all cloud services supported for a given provider. Returns one entry per service with its slug, human-readable name, category (compute / database / storage / networking / etc.), and supported tiers. Use this to discover valid `service:` keys when hand-authoring ArchSpecs or mapping requirements to services. Behavior: Pure lookup from the bundled service registry — no LLM, no network, no cloud access.

Search the cloud instance catalog by provider, specs, or text query. Returns matching instance types with instance family, vCPU / memory / storage, hourly on-demand price, region availability, and architecture (x86 / arm). All filters combine with AND semantics. When to use: Right-sizing workloads, finding the cheapest instance that meets a hardware bar, or discovering equivalents across families. Behavior: Pure lookup from the bundled SQLite catalog — no LLM, no network. Prices reflect catalog snapshot date (see `refresh` CLI command to update).

Scan an architecture and map every finding to compliance framework control IDs. Unlike `validate_compliance` (5-7 static pass/fail checks per framework), this maps EVERY finding, from the built-in scanner, a Terraform HCL scan, and an optional Checkov deep scan, to the specific control IDs it violates (e.g. HIPAA 164.312(a)(2)(iv), SOC2 CC6.1, FedRAMP SC-28), before any infrastructure exists. Returns `{'passed': bool, 'scanner': str, 'checkov_used': bool, 'findings': [...], 'frameworks': [...]}`. Each finding carries `severity`, `rule`, `component_id`, `message`, `remediation`, `source` ('builtin' | 'terraform' | 'checkov'), and `controls` (list of `{framework, control_id, title}`). Each framework summary carries `controls_total`, `controls_violated`, `controls_satisfied`, `findings`, and `status` ('pass' | 'fail'). Set `oscal=True` to instead receive a machine-readable OSCAL 1.1.2 component-definition document mapping every architecture component to its control-implementation status: the interoperability surface for FedRAMP 20x / OSCAL-consuming tooling. Set `traceability=True` (non-OSCAL mode) for the component -> resource -> control chain used in audit reports. When to use: Pre-deployment compliance posture with control-level detail, or generating an OSCAL artifact for a FedRAMP/NIST-800-53 pipeline. For a quick pass/fail per framework without control mapping, use `validate_compliance`. Behavior: Pure computation plus an optional local Checkov subprocess (never a network call; auto-skipped when the checkov binary is absent). Never writes files; the caller persists the returned content if needed. Invalid or empty `spec_json` returns `{'error': str}` instead of raising.

Delete a conversation session. Returns `{'deleted': True}` on success or `{'error': ...}` if the session did not exist. Destructive: the session's conversation history and any uncommitted spec are lost. There is no undo. When to use: Clean-up after a completed design, or abandoning a dead-end conversation. Does not affect any deployed infrastructure — cloudwright never deploys anything. Behavior: Removes the session file from the session store. No LLM, no network.

Validate an architecture against compliance frameworks. Returns one result object per framework with pass/fail status per check, evidence (which components triggered the rule), and remediation hints. When to use: You have a proposed architecture and need to know whether it satisfies HIPAA / PCI-DSS / SOC 2 / FedRAMP / GDPR before proceeding. Use `security_scan` for anti-pattern detection (weak auth, public buckets, etc.) which is framework-agnostic. Behavior: Pure computation — no LLM, no network. Evaluates the spec statically against 30+ rules. Does not access or modify any cloud resources.

Scan an architecture for security anti-patterns and misconfigurations. Returns a structured report with severity-graded findings (critical / high / medium / low / info), each tied to specific component IDs. Framework- agnostic — use `validate_compliance` for specific regulatory frameworks. Checks include: unencrypted data stores, public-facing databases, missing WAF on public HTTP endpoints, weak auth on APIs, SPOFs, overly permissive connection protocols. Behavior: Pure computation — no LLM, no network. Does not touch cloud.

Scan Terraform HCL source for security misconfigurations. Returns findings (severity-graded) tied to specific resource blocks — e.g. aws_s3_bucket with `acl = public-read`, aws_security_group with `cidr_blocks = 0.0.0.0/0` on sensitive ports, aws_rds_instance with `storage_encrypted = false`. When to use: You have existing Terraform code (not an ArchSpec) and want an immediate security audit. For ArchSpec-level audit, use `security_scan`. Behavior: Pure computation — no LLM, no network. Does not run Terraform or touch cloud. Safe for scanning untrusted HCL.

Lint an architecture for anti-patterns and best-practice violations. Returns a list of warnings with rule name, severity (error / warning), component IDs involved, and a human-readable message. Errors (production-blocking): unencrypted data stores, single-AZ databases, missing load balancer on public compute, public databases, single point of failure. Warnings (review-worthy): oversized instances (16xlarge+), missing WAF, missing monitoring, missing backups, missing auth. When to use vs `security_scan`: lint is about **architectural hygiene** (is this a sane shape?). security_scan is about **threat exposure** (can an attacker reach X?). Use both for comprehensive review. Behavior: Pure computation — no LLM, no network. Does not touch cloud.

Estimate the monthly cloud bill for an architecture spec. Returns a structured estimate with per-component breakdown, total monthly cost, data-transfer costs, and currency. Deterministic: same spec + tier yields same result. When to use: You need the numeric bill for one architecture on one provider+tier combination. For multi-provider comparison of just the costs, use `compare_provider_costs`. For side-by-side architecture + cost comparison across providers, use `compare_providers` + this tool. Behavior: Pure computation — no LLM, no network, no API costs. Works offline. Does not deploy or touch cloud resources.

Compare the monthly **cost totals** of an architecture across cloud providers. Returns one numeric cost summary per provider (monthly total, per-component breakdown, currency). Use this for cost-focused provider selection. When to use vs `compare_providers`: This tool returns only **cost numbers**. `compare_providers` returns full alternative **architectures** (components, connections, tiers). If you want both the re-drawn architecture and its bill, call `compare_providers` first, then `estimate_cost` on each returned spec — or call both in parallel. Behavior: Pure computation — no LLM, no network, no API costs. Uses the same offline catalog as `estimate_cost`. Does not deploy.

Create a new stateful architecture-design conversation session. Returns `{'session_id': <12-char hex>}`. The session_id is the handle for subsequent `chat_send` / `chat_delete_session` calls. When to use: Multi-turn architecture design where each turn depends on the prior one (e.g. 'design it', 'now add a cache', 'now move to GCP'). For single-shot design use `design_architecture`; for one-shot edits of an existing spec use `modify_architecture`. Behavior: Writes a new session file to the session store (persisted on disk). Does not call the LLM — the first LLM call happens on the first `chat_send`. Constraints are frozen at session creation and apply to every turn.

Send a message to an existing conversation session and get a response. Returns `{'response': str, 'spec': dict|None, 'usage': dict, 'cumulative_usage': dict}`. `spec` is populated when the turn produced or modified an ArchSpec. `usage` reports LLM token counts for this turn; `cumulative_usage` totals across the whole session. When to use: Every turn after `chat_create_session`. For zero-state single-shot calls use `design_architecture` / `modify_architecture` instead. Behavior: Calls an LLM — incurs API costs proportional to the conversation history length (history grows each turn). Persists updated session state back to the session store.

List all saved conversation sessions. Returns a list of session metadata: session_id, creation timestamp, last-activity timestamp, cumulative token usage, and whether the session currently owns a spec. When to use: Resuming prior work, cleaning up abandoned sessions, or auditing session token spend. Behavior: Pure disk read, no LLM, no network. Read-only, except for an age-based expiry sweep run first: sessions whose last save is older than `CLOUDWRIGHT_MCP_SESSION_TTL_DAYS` (default 7 days) are deleted before the remaining sessions are listed. Set the TTL to 0 or below to disable the sweep.

Run the deterministic offline critic (scorer + linter + validator) on an architecture. This is the same generate -> critique -> repair engine `Architect.design()` uses internally to self-correct a spec before returning it, exposed standalone so an agent can review any spec (hand-authored, imported, or previously designed) for free, with no LLM call. Returns `{'score': float, 'grade': str, 'findings': [...], 'blocking_count': int, 'summary': str}`. Findings are severity-ranked (critical/high first) and each carries `source` ('scorer' | 'linter' | 'validator'), `code`, `message`, `recommendation`, and an optional `component` id. `blocking_count` counts critical + high findings; a non-zero count means the architecture should not ship as-is. When to use: A quick, free, structured review of any spec, before deploying, after a `modify_architecture` edit, or auditing an imported/hand-written spec. For a numeric-only quality score use `score_architecture`; for anti-pattern detail alone use `lint_architecture` or `security_scan`. This tool merges all three plus compliance checks into one severity-ranked report. Behavior: Pure computation, no LLM, no network, no API key required. Read-only. Invalid or empty `spec_json` returns `{'error': str}` instead of raising.

Prove an architecture's exported infrastructure is deployable. Read-only. Exports the spec to a throwaway temp directory and runs `terraform init -backend=false` + `validate` (no cloud credentials required) as the offline proof of deployability, or the Pulumi equivalent. This is the same read-only planner behind `cloudwright plan`. Returns `{'tool': str, 'available': bool, 'validated': bool, 'plan_ran': bool, 'ok': bool, 'summary': {'add','change','destroy'}|None, 'messages': [str], 'output_tail': str}`. `available=False` means the terraform/tofu/pulumi binary isn't installed: a structured skip, not an error. `ok` is the overall deployability verdict; `plan_ran` is True only when a full plan/preview executed (needs credentials). MCP-context boundary: the default here is validate-only (`run_plan=False`) to keep the call fast and credential-free, unlike the CLI which defaults to attempting a full plan. Pass `run_plan=True` for a real resource diff when credentials are available in the server's environment. Under no argument combination does this tool run `terraform apply` / `pulumi up`; the underlying planner has no apply code path at all. When to use: After `export_architecture` (format='terraform'), to confirm the generated IaC is syntactically and semantically valid before handing it to a deploy pipeline. Complementary to `security_scan` / `scan_compliance_controls`, which check the *design*, not whether the emitted HCL/Pulumi program compiles. Behavior: Runs a local subprocess (terraform/tofu/pulumi) against a temp directory deleted when the call returns. No cloud resources are read, created, or modified. Degrades to a structured `{'available': False, ...}` result when the binary is missing, and to `{'error': str}` for an invalid spec or unknown `target`. Neither case raises.

Design a cloud architecture from a natural-language description. Primary entry point for greenfield architecture design. Returns a complete ArchSpec (YAML-serializable dict) with components, connections, tier assignments, and a cost estimate. When to use: You have a requirement (prose) and need a concrete architecture with services, wiring, and cost. Use `modify_architecture` to iterate on an existing spec, or `chat_create_session` + `chat_send` for multi-turn refinement. Behavior: Calls an LLM provider (Anthropic or OpenAI depending on configured keys) — incurs API costs per invocation. Deterministic post-processing layers (cost engine, catalog lookup) apply safe defaults like encryption-at-rest, multi-AZ on databases, and auto-scaling. Does not deploy or modify any cloud resources.

Modify an existing architecture with a natural-language instruction. When to use: You already have an ArchSpec and want to evolve it (add a cache, swap a service, change a region). Returns the updated ArchSpec. For from-scratch design, use `design_architecture`. For iterative multi-turn editing with conversation memory, use `chat_create_session`. Behavior: Calls an LLM provider — incurs API costs. Pure function: returns a new spec without mutating the input. Does not deploy.

Compare an architecture's **service mapping** across cloud providers. Returns one translated ArchSpec per target provider, showing which services the original would become on each. Use this to understand architectural portability and equivalent services. When to use vs `compare_provider_costs`: This tool returns full alternative **architectures** (with components, connections, tiers). `compare_provider_costs` returns only numeric **cost totals** per provider — use that when you only care about the bill, not the shape. Behavior: Calls an LLM to resolve ambiguous service mappings where the static equivalence table is insufficient. Does not deploy.