Technical reference
Install and run
npx deploysutra-ai --version
npx deploysutra-ai analyze --before old.yaml --after new.yaml --profile production --out report
Requires Node.js 20 or newer. Binaries: deploysutra and deploysutra-ai.
Library API (ESM)
import {readManifests, assess, checkPolicies, inspectTofuPlan, verify} from 'deploysutra-ai';
import {renderMarkdown, renderHTML, saveReports} from 'deploysutra-ai/reporting';
const before = readManifests('old.yaml').docs;
const after = readManifests('new.yaml').docs;
const report = assess(before, after, null, {profile: 'production'});
console.log(report.gate, report.gateReasons);
saveReports(report, 'report');
| Function | Returns |
|---|---|
readManifests(file) | {docs, source}; each doc has value, lineMap, source, text |
readManifest(file) | One doc; throws if the file holds several |
docFromObject(obj) | In-memory doc with an exact JSON line map |
checkPolicies(doc) | Sorted findings for one resource |
diffManifests(a, b) | Changes for two docs of the same identity |
assess(before, after, rollback?, {profile?}) | Sealed report; arrays or single docs |
inspectRollback(evidence) | Prerequisite states; ready is always false |
inspectTofuPlan(json) | Sealed action summary |
buildBlastMap(docs) | {nodes, edges} |
explainRule(id), RULES, PROFILES | Registry |
seal, verify, canonical, sha256, safeFile | Evidence primitives |
runAudit({skipTests}) (deploysutra-ai/audit) | Sealed audit report |
Input limits
1 MiB per file, 200 documents, extension .yaml/.yml/.json, regular non-symlink file, no symlinked parent. Plans: first 1000 changes (flagged when truncated).
Supported YAML
Block mappings and sequences; plain, single- and double-quoted scalars (trailing comments allowed); [], {}; one-line scalar flow sequences such as verbs: ["get","list"]; # comments; --- separators; keys made of letters, digits, _ . / -; indentation in multiples of two spaces. Rejected with an error naming the line: tabs, odd indentation, anchors, aliases, tags, merge keys, block scalars (|, >), nested flow collections, flow mappings with content, {{ }} templates, ..., duplicate keys, __proto__/constructor/prototype.
Identity and pairing
Resources are keyed by apiGroup/kind/namespace/name (namespace defaults to default). Two single resources of different identity throw Mismatched. For sets: matching pairs are diffed, extras are resource-added/resource-removed, removal raises DS-K8S-019.
Diff semantics
All fields except status and server-populated metadata are compared. Arrays whose elements all have unique names are matched by name, so reordering is not a change. Redaction: Secret data/stringData/binaryData, keys named like password/token/apiKey/secret/privateKey, and value of env vars whose name looks secret. Strings containing token=, password=, secret= or bearer <x> are masked and clipped to 120 chars.
Line evidence
lineConfidence: exact comes from the parser map; parent marks an absent field attributed to its nearest existing ancestor (for example missing resources); unknown means no line is claimed.
Gate computation
- Findings =
checkPoliciesover AFTER, taggedneworpersistentagainst BEFORE, plus DS-K8S-019 for removed resources. - Reasons = each finding whose severity is in the profile's
blockOn, plus missing rollback prerequisites. - Gate =
BLOCKEDif any reason, otherwiseHUMAN_REVIEW_REQUIRED.
Loopback API
DEPLOYSUTRA_TOKEN (20+ chars) required. Binds 127.0.0.1/::1. GET /health, GET /report; everything else 404/405; every response no-store, nosniff, X-Frame-Options: DENY, CSP default-src 'none'.
MCP server
deploysutra mcp --root <dir>; newline-delimited JSON-RPC 2.0; protocol versions 2025-06-18, 2025-03-26, 2024-11-05; tools listed in the user guide. Paths are relative to the root only.
Performance (recorded)
Median of 5 runs on this machine: assess() over 200 resources 37 ms, parsing 200 documents 12 ms, rules over 200 resources 1 ms.