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');
FunctionReturns
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, PROFILESRegistry
seal, verify, canonical, sha256, safeFileEvidence 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

  1. Findings = checkPolicies over AFTER, tagged new or persistent against BEFORE, plus DS-K8S-019 for removed resources.
  2. Reasons = each finding whose severity is in the profile's blockOn, plus missing rollback prerequisites.
  3. Gate = BLOCKED if any reason, otherwise HUMAN_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.