Architecture
Context
Engineers provide local files. DeploySutra reads them, computes evidence, writes reports and stops. A human, using an independent CI/GitOps system, decides and acts.
before.yaml after.yaml plan.json
\ | /
v v v
+------------------------------+
| deploysutra CLI | no apply / deploy / destroy / rollback
+--------------+---------------+
v
+------------------------------+ +---------------------------+
| core: parse -> diff -> rules |----->| reporting: JSON, MD, HTML |
| -> blast map -> gate -> seal| +-------------+-------------+
+------------------------------+ v
^ ^ human reviewer
MCP (stdio) loopback API (decides outside the tool)
Modules
| Module | Responsibility |
|---|---|
util.mjs | SHA-256, canonical JSON, seal/verify, safeFile, text cleaning |
yaml.mjs | Strict YAML subset with exact line maps and multi-document streams |
manifest.mjs | Ingestion, JSON line maps, semantic diff and redaction |
rules.mjs | Rule registry, profiles, per-document checks |
blast.mjs | Dependency edges from supplied manifests |
assess.mjs | Snapshot comparison, gate, rollback model, plan summary |
corpus.mjs | 50 labelled rule cases |
audit.mjs | Independent self-audit |
reporting/index.mjs | Renderers and saveReports |
server/index.mjs, server/mcp.mjs | Loopback API and MCP server |
cli/index.mjs, cli/install.mjs | Command line and skill installer |
Design decisions (short ADRs)
| Decision | Alternatives | Why | Trade-off | Reversibility |
|---|---|---|---|---|
| Zero dependencies, hand-written YAML subset | Add a YAML library | No supply-chain surface; fails loudly on anything unsupported | Not full YAML; Helm output must be rendered first | A parser adapter can replace yaml.mjs behind the same function |
| Gate has two states | Add READY | Static checks can never prove safety | Users may want a green light | Adding a state is a breaking, visible change |
| Block on persistent findings too | Block only new ones | Old HIGH risk is still risk | More noisy for legacy manifests | Use development profile or fix the manifest |
| Desired-state only, no cluster | Live diff | No credentials, reproducible | Cannot see drift | A future adapter would be separately gated |
| Unkeyed SHA-256 seal | Signatures | Works offline with no key management | Not authenticity | Signed provenance planned with an explicit trust root |
| Audit kept out of the core index | Export from core | Core stays free of subprocess APIs | One extra import path | None needed |
Data model (report v2.0)
schemaVersion, productVersion, rulesVersion, scope, profile, source.before/after (path, sha256, bytes), resources, diffs (id, resource, path, change, before, after, redacted, source, line, lineConfidence), policyFindings (id, severity, status new/persistent, resource, field, source, line, requirement), blastMap, impactedByChange, blastRadius, rollback, gate, gateReasons, checks, limitations, integrity.
Deterministic output
The analysis path contains no clocks or randomness. Objects are canonicalised before hashing, so equal inputs give equal digests on every platform.
Extension points
New rules go in the registry with an ID, severity, remediation and a corpus case; skills reference rule IDs and commands and a test fails if either is invented. Future adapters (OPA, Helm, live read-only collectors) must be separate, opt-in and sandboxed.