feat: audit command

Cargo.toml

@@ -51,13 +51,15 @@ ed25519-bip32 = "0.4.1"
 bip39 = "2.1.0"
 octocrab = "0.44"
 serde_with = "3.14.0"
+serde_yaml_ng = "0.10"
 askama = "0.14.0"
 prost = "0.13"
 tracing = "0.1"
 tokio-util = "0.7"
 tracing-subscriber = "0.3.22"
 dotenv-parser = "0.1.3"
 termimad = "0.31"
+aiken-lang = "1.1.21"
 
 [dev-dependencies]
 assert_cmd = "2.0"

design/003-ai-aiken-vulnerability-scaffolding.md

@@ -0,0 +1,237 @@
+# AI Vulnerability Scaffolding
+
+## Overview
+
+This document defines the **Milestone 1 scaffolding** for an AI-assisted vulnerability analysis command in Trix, initially focused on Aiken smart contracts.
+
+Scope for this milestone is intentionally limited to:
+- CLI wiring for a new scoped command: `trix audit`
+- Contracts for iterative skill-by-skill analysis state (JSON)
+- Contracts for permission prompt generation and final vulnerability report generation
+- Local-first execution boundaries and security assumptions
+- C4 architecture diagrams in PlantUML
+
+Out of scope for this milestone:
+- Real LLM integration implementation
+- Actual command execution orchestration against an AI provider
+- Deep prompt engineering and remediation automation
+
+## Goals
+
+1. Establish a stable command surface for future implementation.
+2. Define the analysis loop model that processes vulnerability skills one by one.
+3. Persist progress incrementally in JSON after each skill iteration.
+4. Produce a final vulnerability document contract (Markdown output path + structure).
+5. Define a local command permission prompt contract (e.g. `grep`, `cat`) for constrained auto-execution.
+
+## CLI Surface (Scaffolding)
+
+`trix audit` is a **scoped** command and requires a project context (`trix.toml`).
+
+**⚠️  EXPERIMENTAL**: This command requires the `unstable` feature to be enabled. Build with:
+```bash
+cargo build --features unstable
+```
+
+### Command Structure
+
+The command is currently focused on Aiken smart contracts but designed for future extensibility to other languages:
+
+```bash
+trix audit [options]
+```
+
+### Command (Milestone 1)
+
+#### `trix audit`
+
+Audits smart contract code for vulnerabilities using AI-assisted detection. Currently focused on Aiken (`.ak` files).
+
+**Arguments:**
+- `--state-out` (default: `.tx3/audit/state.json`) - Path where the incremental analysis state JSON will be written
+- `--report-out` (default: `.tx3/audit/vulnerabilities.md`) - Path where the final vulnerability report markdown will be written
+- `--skills-dir` (default: `skills/vulnerabilities`) - Path to vulnerability skill definitions
+- `--provider` (default: `scaffold`) - Analysis provider: `scaffold` | `openai` | `anthropic` | `ollama`
+
+**Example:**
+```bash
+trix audit
+trix audit --state-out ./custom/state.json
+trix audit --provider openai
+```
+
+## Skill-by-skill Loop Contract
+
+The analysis process is modeled as an iterative loop:
+
+1. Load one vulnerability skill definition.
+2. Build a focused mini-prompt for that single skill.
+3. Execute analysis (future milestone, provider-backed).
+4. Append iteration result to JSON state.
+5. Continue with next skill until all skills are processed.
+6. Render final vulnerability report document from aggregate findings.
+
+This loop enables narrow prompts per skill, improving precision and traceability.
+
+## State and Output Contracts
+
+### Incremental JSON state
+
+Defined by `AnalysisStateJson` and related structures in:
+- `src/commands/audit/model.rs`
+
+Key sections:
+- Source metadata (multi-file) and provider spec
+- Permission prompt spec (allowed local commands, scope rules)
+- Ordered list of `SkillIterationResult`
+
+Example (simplified):
+```json
+{
+	"version": "1",
+	"source_files": [
+		"onchain/validators/spend.ak",
+		"onchain/validators/mint.ak"
+	],
+	"provider": {
+		"name": "openai-compatible",
+		"model": "gpt-4.1-mini",
+		"notes": "Endpoint: https://api.openai.com/v1/chat/completions"
+	},
+	"permission_prompt": {
+		"shell": "bash",
+		"allowed_commands": ["grep", "cat", "find", "ls"],
+		"scope_rules": [
+			"Only execute commands within the current project root.",
+			"Do not write outside designated output artifacts."
+		],
+		"read_scope": "workspace",
+		"interactive_permissions": false,
+		"allowed_paths": []
+	},
+	"iterations": [
+		{
+			"skill_id": "strict-value-equality-001",
+			"status": "completed",
+			"findings": [
+				{
+					"title": "Strict equality on full value",
+					"severity": "high",
+					"summary": "Strict value equality can reject valid transactions.",
+					"evidence": ["validators/spend.ak:42"],
+					"recommendation": "Compare lovelace and assets separately.",
+					"file": "validators/spend.ak",
+					"line": 42
+				}
+			],
+			"next_prompt": null
+		}
+	]
+}
+```
+
+### Final report
+
+Defined by `VulnerabilityReportSpec` and a Markdown template scaffold:
+- `templates/aiken/report.md`
+
+Note: the report no longer includes a single `target` path because analysis is performed over a set of source files.
+
+### Permission prompt
+
+Template scaffold:
+- `templates/aiken/permission_prompt.md`
+
+This prompt is intended to grant **explicit, bounded, local** command execution rights to the analysis agent.
+
+## External AI Service Note
+
+Future milestones may integrate external AI services (for example, **Anthropic**) behind a provider adapter boundary.
+
+For this milestone, provider integration is represented as a contract only (`ProviderSpec`) and no network behavior is implemented.
+
+## Local Execution and Safety Boundaries
+
+The architecture assumes:
+- Analysis runs locally from the developer machine.
+- Only an allowlist of read-oriented commands is permitted by policy prompt (e.g. `grep`, `cat`, `find`, `ls`).
+- Writes are limited to designated output artifacts (state JSON and report document).
+- Scope rules constrain path access to project roots.
+
+## C4 Architecture Diagrams
+
+C4 diagrams are maintained as separate PlantUML files in [`003-assets/`](003-assets/) for easier image generation and version control.
+
+### Generating Diagrams
+
+To generate PNG/SVG images from PlantUML source:
+
+```bash
+# Using PlantUML CLI
+plantuml design/003-assets/*.puml
+
+# Or using Docker
+docker run --rm -v $(pwd)/design/003-assets:/data plantuml/plantuml:latest *.puml
+```
+
+### C4 - Context Diagram
+
+**Source:** [c4-context.puml](003-assets/c4-context.puml)
+
+![C4 Context Diagram](https://www.plantuml.com/plantuml/svg/LP71SXen343l-nKg9peDxA4vfPSmj9b9XpGCQNibnXP1nMjx97c1lw-zcsc7qrhMqvEblHSrhBdpiBpTBcDGFEjsGKSClxCFpGSArcU7S51DSjUsR4xpDz93tcL1jhKWwDp6hatUX2gQYJfFktPvErlNgrzFgxOpeiZj_nRpLCYcMIDB35E7_GrClcAFFYRaIGasEGZyP3e31J3WepKU4iS_Q7NoiNcv564trG8KUE2MgyT9FPy_GpBsQDuGEXFAX__nsszddHegL3aWXw9SFCAQOqzkRFkSb6AztsVDZ93USo3P7i08B88UE2QorzAzbEBLyCW7yWXZgXhNuvj1OcQBDo17yhxGCMlAAaNJRD2FAnZ76MT_hG6Ox4XV2rIPCJsqsg1n0ZOwX4_GPn-GpOuywUMzmHSuCIaAV7zv_W6YHX5CSF1a-EZYAG1ZYgnNvc4p3yFWTo0Od8oocIIqj2TRrz4bbS74Q95wh87n5w5XbFjILV_iNm00)
+
+*System context showing developer interaction with Trix CLI, local filesystem, and future external AI provider integration.*
+
+### C4 - Container Diagram
+
+**Source:** [c4-container.puml](003-assets/c4-container.puml)
+
+![C4 Container Diagram](https://www.plantuml.com/plantuml/svg/RLHDKnin3Btlhr1p2jD2Bfmu4LAOIIUqJA3jaN5sHT34QxkM7CXq-jyhhzbj4dg9hG-zPqalUybYegJMmkpySUQT678O7wUqGVSZMLTz85VRr20yYmI-c4oYUJbRapodLMACjPQWaxFQjvDWZSjGfooDfTLaTdvwbrtVRnUJrh1WdEoJd0NDhQexZEpTkC7j9nXznYrQ7p2EJghxdPQqZrS-kSR4tLWYlMhAWnumMyn79_2x0XZWnhKb3KzJGwBUjZMk6QbZcLZW8yoi2TdKIgXB5D19t0LFJY2R9gvJYseygsN9hVKH-mJM-w08znko5XPgmBLRQwHdoUTSC1f1XgqEJwyhiYGxu5p37KiAJPV0eiSHGuY-3Q8mTzqbjn4yOzphum7RO3D0zbqbiWr3IuvEIstX21XROYRleBYFU3hkt4e-uMSaEU3uSl_jQpRpQeWLKpKGCO_6MCKtTiVq_mOY1Xyb8tMNzz2t9cuQ_-8E-z1scrGZmnCf-j7i2kRxIMsfmTWLbojC6nD4p_5DaXJnPA2LQ4XWzIQax9wkM9srCE2hbcJIwHmOuvRgtDEVgfVVzQkCdrXB5hxMh1ko22MaQNiv9ellUWziU5R_7CslbcYBqejOvsxhDyWQoO7ErujCJCpBp6f-2vV8894b_ah8maLR1neuAFYtQn-HWJg1PcMebUnHSfdreAooZ_pRa5jp2H-_PrX4wVC236-qqiT1AgMWLrqtpKuORnegUYivXU4mgUqrSq3VzTfdBj4q_IIUo6Bv6qYliQ6aVwkXuRtWK5vyt82kr-RCwX9TapzDVm40)
+
+*Container-level view of Trix CLI internals: command entrypoint, skill loop engine, prompt composer, state/report writers, and provider adapter boundary.*
+
+### C4 - Component Diagram
+
+**Source:** [c4-component.puml](003-assets/c4-component.puml)
+
+![C4 Component Diagram](https://www.plantuml.com/plantuml/svg/TPFFRjim3CRlVWekfnPhuqjFFJNDQKMp1Issgw58J29KVpIAQXeCU_T9jc4dNdeBAVBtCUJdXyY2E5a3oxjcwMtm3Xqt2_s6xbSohlgYdJH98UoPGxolQnA7-KxpFcrIH9BUSMwOIs_hO8GhgDl8okXDlRoxNPVKpzLpRKLafFfKP1voRLKjCq5eXzGy-kIKeEELAEetC5iafHboWnLEmSghP71s3NygW85o9QtAfPJSbQ1Tl07ftLRlRY2Gtsg3rxFyQhsQKoo_NgKFg43sp0oWO_3QyUpwZ1hVj36DyK8XbROImdCR5imsSI84susK4-KfGkw5zsGSajXee_a8BGS4Wm3M5YSgLZlT1CenPyOgHx1k8tXCsdocrRv5s7gP8Yhe-dD881DHvdQg4ws0P7MCshjHSJtaBkWosc048vGRav1yecsy56ROueZkXvakapEciLwXARii4QnArDy6JN-TXHFc67LiIvvYvdq5pKY2CtkO8rx4H_Q40_wrH1Utzu92nVf0cHj1EqbeCqGOU7hzyHrQreHF63nnG-WK4bBBA1buwJEVRgihY1DFM45loX_Sz43attKkRuGIWLkTTP-2HKcTsI5hQEvsndloGSlQynu9UWo1TeoxVdMR_jFAad-hwWLDzzbCN4xuEs7a20u_1XEDrUTktNHE24YtRULm-h5XzCMqhHi85U07obH6lD1-RfiKCOuMcDQDzy-YKPS_WKBkmNWVHWkTTlr_LUgljTLEcFxzj6DweE4Oz_tVG5Xy0ocCAUDL3ncNhAd-0G00)
+
+*Component-level detail of the Aiken command module: skill loader, prompt builders, state model, storage, report renderer, and provider adapter.*
+
+## Skills Source Convention
+
+Vulnerability skills live under:
+- `skills/vulnerabilities/`
+
+One file per skill, designed for 1:1 loop processing.
+
+Each skill file uses YAML frontmatter plus optional markdown guidance body:
+
+Required frontmatter fields:
+- `id`
+- `name`
+- `severity` (`low` | `medium` | `high` | `critical`)
+- `description`
+- `prompt_fragment`
+
+Optional frontmatter fields:
+- `examples` (list)
+- `false_positives` (list)
+- `references` (list)
+- `tags` (list)
+- `confidence_hint`
+
+The markdown body can include richer instructions, rationale, and examples and is passed as guidance context to the prompt builder.
+
+## Milestone 1 Acceptance Criteria
+
+- `trix audit` command exists as a top-level scoped command.
+- Command is gated behind `unstable` feature flag (following `publish` pattern).
+- `trix audit` is implemented as scaffold with Aiken-focused analysis.
+- `src/commands/audit/mod.rs` provides the public command interface.
+- `src/commands/audit/mod.rs` contains the core audit implementation.
+- `src/commands/audit/model.rs` defines scaffolding contracts for state, findings, and prompts.
+- Templates for report and permission prompt exist in `templates/aiken/`.
+- `skills/vulnerabilities/` exists with seed skill files.
+- This design document includes C4 diagrams as separate PlantUML files in `003-assets/`.
+- E2E scaffold tests verify command visibility and baseline behavior for `audit` (tests run with `--features unstable`).

design/003-assets/README.md

@@ -0,0 +1,44 @@
+# Design 003 Assets
+
+This folder contains PlantUML C4 architecture diagrams for the AI Aiken Vulnerability Scaffolding design.
+
+## Files
+
+- `c4-context.puml` - System context diagram
+- `c4-container.puml` - Container-level architecture
+- `c4-component.puml` - Component-level details
+
+## Generating Images
+
+### Using PlantUML CLI
+
+Install PlantUML and run:
+
+```bash
+plantuml c4-*.puml
+```
+
+This will generate PNG files in the same directory.
+
+### Using Docker
+
+```bash
+docker run --rm -v $(pwd):/data plantuml/plantuml:latest c4-*.puml
+```
+
+### Using Online Editor
+
+1. Copy the content of any `.puml` file
+2. Go to https://www.plantuml.com/plantuml/uml/
+3. Paste and generate
+
+### Using VS Code
+
+Install the PlantUML extension:
+- Extension ID: `jebbs.plantuml`
+- Right-click on `.puml` file → "Preview Current Diagram"
+- Export as PNG/SVG
+
+## Output
+
+Generated images (`*.png`, `*.svg`) should be committed to this directory so they render in the markdown document on GitHub and other viewers.

design/003-assets/c4-component.puml

@@ -0,0 +1,23 @@
+@startuml C4_Component_AikenVuln
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+Container_Boundary(aiken, "Audit Command Module") {
+  Component(cmd, "run(args, config, profile)", "mod.rs", "Scoped command entrypoint")
+  Component(skill_loader, "Skill Loader", "future module", "Loads one vulnerability skill at a time")
+  Component(mini_prompt, "Mini Prompt Builder", "future module", "Builds focused prompt for current skill")
+  Component(permission_prompt, "Permission Prompt Builder", "template contract", "Builds local command permission prompt")
+  Component(state_model, "State Model", "model.rs", "AnalysisStateJson + iteration contracts")
+  Component(state_store, "State Store", "future module", "Reads/writes incremental JSON state")
+  Component(report_renderer, "Report Renderer", "template contract", "Renders vulnerability markdown")
+  Component(provider_adapter, "Provider Adapter", "future trait", "Anthropic/other provider integration boundary")
+}
+
+Rel(cmd, skill_loader, "requests next skill")
+Rel(cmd, mini_prompt, "builds per-skill prompt")
+Rel(cmd, permission_prompt, "builds bounded execution prompt")
+Rel(cmd, state_model, "uses contracts")
+Rel(cmd, state_store, "persists each loop iteration")
+Rel(cmd, report_renderer, "renders final report")
+Rel(cmd, provider_adapter, "future: execute AI calls")
+
+@enduml

design/003-assets/c4-container.puml

@@ -0,0 +1,28 @@
+@startuml C4_Container_AikenVuln
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+Person(dev, "Developer")
+System_Boundary(trix, "Trix CLI") {
+  Container(cli, "Audit Command", "Rust + Clap", "CLI command entrypoint and argument handling")
+  Container(loop, "Skill Loop Engine", "Rust", "Iterates vulnerability skills and updates state")
+  Container(prompt, "Prompt Composer", "Rust + Templates", "Builds mini-prompts and permission prompt")
+  Container(state, "State Writer", "Rust + JSON", "Persists incremental analysis state")
+  Container(report, "Report Writer", "Rust + Markdown Templates", "Produces final vulnerability report")
+  Container(provider, "Provider Adapter (Future)", "Rust trait boundary", "Abstracts external AI service")
+}
+
+System_Ext(fs, "Local File System")
+System_Ext(ai, "External AI Provider (Future)")
+
+Rel(dev, cli, "Invokes")
+Rel(cli, loop, "Starts audit")
+Rel(loop, prompt, "Requests skill mini-prompts")
+Rel(loop, state, "Stores iteration results")
+Rel(loop, report, "Builds final findings report")
+Rel(loop, provider, "Future: asks for analysis")
+Rel(state, fs, "Writes state JSON")
+Rel(report, fs, "Writes markdown report")
+Rel(prompt, fs, "Reads skill files and templates")
+Rel(provider, ai, "Future network calls")
+
+@enduml

design/003-assets/c4-context.puml

@@ -0,0 +1,13 @@
+@startuml C4_Context_AikenVuln
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+
+Person(dev, "Developer", "Runs Trix in a local project")
+System(trix, "Trix CLI", "Tx3 package manager")
+System_Ext(ai, "External AI Provider", "Optional future provider such as Anthropic")
+System_Ext(fs, "Local File System", "Project source, skills, outputs")
+
+Rel(dev, trix, "Runs `trix audit`")
+Rel(trix, fs, "Reads code + vulnerability skills; writes JSON state and Markdown report")
+Rel(trix, ai, "Future: sends skill-specific prompts and receives analysis")
+
+@enduml