Technical Specification

Repository layout

PathRole
packages/core/index.mjsPure analysis: scan, plan, rehearse, gate, compare, audit, render
packages/cli/index.mjsArgument parsing, file output, skill installer
packages/server/index.mjsLocalhost bearer-token read-only report API
skills/migrasutra-*/SKILL.md20 portable Agent Skills
agents/Claude-targeted subagent instructions and manifest.json
schemas/JSON Schemas for scan, plan, rehearsal, gate
rules/, policies/, workflows/Rule metadata, default policy, stage definitions
fixtures/clean-app, risky-app, broken-app
tests/node:test suites
scripts/demo, build-docs, test-report, installers

Runtime: Node.js 22 or newer, ES modules, zero runtime dependencies.

Data contracts

Every artifact carries a schema field: migrasutra.scan/v1, plan/v1, rehearsal/v1, gate/v1, compare/v1, audit/v1. Consumers must check it before use.

Evidence ID: MS- plus the first 12 hex characters of SHA-256 over the rule code, file, line and subject. The same input yields the same ID on every machine.

Each finding records sourceHash (SHA-256 of the file), verifiedBy: deterministic-rule and execution: not-run.

Algorithms

Scan. Collect the allowed root files and SQL files (depth at most 5, at most 150 files, symlinks skipped). Read each through safeRead, which resolves the path, checks it stays inside the root, rejects every symlink segment and rejects files over 1 MiB. Hash the content. Apply per-ecosystem rules.

SQL. Blank block comments, line comments and single-quoted strings while keeping newlines, so line numbers stay correct. Run regular expressions over the result. DELETE FROM is checked per ;-separated statement for a WHERE.

Plan. Requires a scan whose package.json hash equals the current file. Finds the dependency section, refuses credential-bearing values, records from and to.

Rehearse. Re-checks the baseline hash, validates the action against the target, applies the edit in memory, writes it to a 0600 temp file, reads it back, deletes the temp directory, and reports both hashes.

Gate. Counts static high findings and rehearsal status. Hard-codes automaticTests: NOT_RUN and rollbackTest: NOT_RUN.

Version compare. compareVersions compares numeric segments, then pre-release tags, and rejects strings that fail validVersion.

Input validation

Local server

Binds 127.0.0.1 only. Needs MIGRASUTRA_SERVER_TOKEN of 16 or more characters, compared with timingSafeEqual. Serves GET /health and GET /report. Every other method returns 405. No file browsing, no shell.

Performance

Reads at most 150 SQL files plus a dozen manifests, each under 1 MiB. Typical audits finish in well under a second on the fixtures. No benchmark on large monorepos has been run; do not assume it scales.

Known limits