Architecture

Context

 Developer / CI / AI IDE
          |
          v
   migrasutra CLI  ----->  core (pure functions)  ----->  Reports: JSON, MD, HTML
          |                    |
          |                    +--> reads allow-listed files in the repo (read-only)
          |                    +--> writes only to a temp dir during rehearsal
          +--> skills installer --> .claude/skills, .cursor/skills, .agents/skills ...
          +--> serve (127.0.0.1, bearer token) --> one report, GET only

There is no cloud service, no telemetry and no model call in the product.

Components

ComponentResponsibilityDepends on
CoreScan, plan, rehearse, gate, compare, audit, renderNode standard library only
CLIParse options, write files, install skillsCore, Server
ServerServe a stored report on loopbackNode http
SkillsProcedural instructions for AI hostsNone at runtime
AgentsRole prompts for hosts with subagentsNone at runtime
Schemas, rules, policiesMachine-readable contractsNone

Core never imports the CLI or the server. Dependencies point inward.

Lifecycle

scan --> plan --> rehearse (static) --> gate --> human review
  |                                       ^
  +------------- audit (all in one) ------+

Each hop carries hashes. The plan binds to the scan's package.json hash. The gate binds to the plan ID. A mismatch stops the flow.

Trust boundaries

BoundaryUntrusted inputControl
Repository filesManifests, SQL, Dockerfile textSize cap, symlink refusal, treated as data
Plan file from diskEdited action or targetAction re-validated against target
Imported evidenceClaims that tests passedLabelled UNVERIFIED_EXTERNAL
CLI argumentsInjection stringsStrict validators; no shell is ever spawned
Report viewerStrings that reach HTMLEscaped on output
Server clientsAnyone on the machineLoopback bind, bearer token, GET only

Key decisions

  1. Offline and deterministic. Same input gives the same findings and IDs. This makes audits reproducible.
  2. No execution. Running unknown project code is the largest risk in migration tooling, so v0.2 does not.
  3. Verdict ceiling. The tool cannot know test results, so its best verdict is REVIEW_REQUIRED.
  4. Heuristic SQL checks, stated as such. A false claim of parsing would be worse than a clear limit.
  5. Skills separate from code. Skills guide hosts; the CLI works without any AI.

Roadmap (planned, not shipped)

Runnable sandbox rehearsal, OpenRewrite and jscodeshift adapters, a database restore lab, OpenTofu plan review, and a team server. Each needs a threat model and tests before it is called implemented.