A Rails-specific coding harness being rewritten in TypeScript 7, Bun and OpenTUI/Solid.
Development status: v0.1 is incomplete and has no supported release yet. The replacement now runs configured coding tasks through native/compatible providers, explicit execution approvals and independent checks. It includes persistent sessions, a streaming terminal, local source navigation and scoped Playwright flows. The native source viewer includes Ruby highlighting, fuzzy navigation, pins, diffs, committed source and editor handoff. /revision HEAD or /revision FULL_COMMIT_ID [path] opens immutable Git source; /worktree returns to current files. Historical selections keep their commit when attached, and missing remote objects are not fetched. Headless source --root PATH --path FILE --revision HEAD [--start N --end N] reads the same evidence. Full parity, recovery, interaction and App Inspection recording acceptance remain in progress. See the acceptance ledger for observed evidence and outstanding requirements. The former Ruby implementation remains in Git history at fdee113.
Use Bun 1.4.2 and the exact lockfile. TypeScript 7 strict mode checks application code. Structural parsing uses Ruby 4.0.6 with built-in Prism 1.8.1; unavailable parsing remains unknown and never boots the target application.
bun install --frozen-lockfile
bun run typecheck
bun run build
./dist/mavona # terminal
./dist/mavona inspect /path/to/app --format json
./dist/mavona inspect /path/to/app --task "Change order validation"Ctrl+P opens the command palette; Ctrl+O opens saved sessions; both preserve the composer draft. Ctrl+D opens the revision-labelled diff and Ctrl+R shows declared Rails evidence.
The terminal supports /providers, /connect for guided connection choices, /connect provider model [URL local|remote], /models, /files [query], /open path[:line], /find text, /goto line, /select start:end, /attach, /references, /detach ID, /refresh, /back, /diff, /source and /help.
Connection/model selection makes no inference call; model discovery requests metadata only, and task submission performs a bounded capability preflight. Explicit endpoint/locality/model choices survive session reopening; /disconnect clears the saved selection. Unsupported subscription routes remain visibly unavailable. Credentials come from the provider's environment variable or OS secure store. Never enter credentials into the composer.
Source reading supports /files or Ctrl+P for fuzzy navigation, /open path:line, /select start:end, explicit /copy, /pin and /pins. Wide terminals show a source pane adjustable with /pane 20–40; narrow overlays retain the conversation scroll position. Ctrl+End returns the transcript to its latest output.
Configure an external editor with /editor terminal ["/usr/bin/vi","{path}"] or /editor gui ["code","--wait","{path}"], then /edit from an open source snapshot. {line} is also supported in argument templates. Each launch is reviewed; no shell interpolation occurs. Use the editor's save/quit controls during handoff. GUI ownership persists until explicit return confirmation. Terminal handoff uses /bin/stty to restore pre-editor modes even after termination. Saved changes invalidate prior verification and grants; use /refresh to update the displayed snapshot. /reconcile explicitly records changed repository state before another task; it does not mark pending effects or old checks passed.
/new creates a fresh session in the current checkout with the same explicit model connection; /fork copies history and draft into a new session in that checkout. These actions preserve the original session and never replay effects. Headless sessions new --root PATH returns a new stable ID.
/session shows current metadata and pending effects; /rename TITLE, /pin-session, /unpin-session, /archive and /unarchive manage the session without deleting source or evidence. Archival asks for exact confirmation. Session search includes names and recorded task text. Headless sessions rename ID --title TITLE, sessions pin ID and sessions unpin ID use stable IDs.
/export /new/path.json reviews an exact canonical session snapshot before file creation. Headless sessions export ID --destination /new/path.json previews it; repeat with --approve-export REVIEW_ID. Export files exclude artifact/authentication files, preserve pending effects, and never replace existing destinations. Destinations must be outside session storage and Git worktrees. Plain sessions export ID still writes JSON to stdout.
/storage or sessions storage ID --data-dir PATH reports sampled apparent-byte totals by metadata, screenshot, video, ZIP trace and other files. Global thresholds are currently advisory; per-run capture limits remain enforced. Retained checkout source is excluded from disposable session storage.
/recover selects retained deleted source; /restore RECOVERY_EVENT_ID reviews restoration and refuses to replace a current file. Headless sessions recovery SESSION_ID lists stable IDs; sessions restore SESSION_ID --recovery EVENT_ID prints a read-only preview, then --approve-restore REVIEW_ID authorizes that exact restoration. Prior verification becomes stale.
/dispose RECOVERY_EVENT_ID separately reviews permanent removal of a retained copy. Headless sessions dispose SESSION_ID --recovery EVENT_ID previews it; --approve-dispose REVIEW_ID approves the exact irreversible removal. Recreated current source remains untouched. Interrupted operations require inspection and reconciliation before a new review.
A required fresh verifier with a nonzero exit may trigger one repair attempt within the same turn/tool/time budget. Use --repair-attempts 0 or /repair 0 to disable it; unknown or stale outcomes never trigger repair. Each effect requests exact-action approval; /revoke clears execution grants. /verify ["ruby","bin/rails","test"] configures a required check whose execution also requires approval.
Interrupted effects can be inspected with terminal /effects or mavona sessions show ID. After inspecting the worktree and any affected application state, explicitly acknowledge it with /reconcile EFFECT_ID explanation in the owning session, or mavona sessions reconcile ID --effect EFFECT_ID --reason "Inspected current state". This preserves an unknown outcome and makes prior verification stale; it does not retry the effect. A pending worktree effect blocks new sessions before model preflight.
Acceptance criteria are captured before inference and retained across retries. Changed test/spec files or selected criterion files require explicit adoption of their recorded before/after review. In the terminal, inspect /acceptance, then use /adopt REVIEW_ID explanation; an active task can also present the exact review for approval. Headless users inspect sessions show ID and run sessions adopt ID --review REVIEW_SHA256 --reason "Reviewed the changed criteria". A changed worktree invalidates the review. Adoption neither executes commands nor marks correctness passed; execution approval and fresh independent checks remain required.
Use /vision on to explicitly override image capability for the current model; the model can propose up to four current-task masked captures, and every selection separately reviews IDs, digests, dimensions and the exact destination before submission. Switching/reopening clears the override. Without vision, DOM/text evidence remains available and visual judgement stays unknown.
/app opens recorded inspection evidence; /app history selects a prior run. The text drawer supports arrows, PageUp/PageDown, Home/End and Escape while retaining the composer and source view. Viewing evidence never resumes browser activity or refreshes verification.
/app rerun reviews the selected saved repository flow before fresh execution. Headless app rerun --session ID --inspection ID previews scope; repeat with --approve-rerun REVIEW_ID. Changed saved files require a new app run review. Inline/external flows and unsaved overrides cannot be rerun from history, and rerun implies no fixture reset.
/app compare chooses two recorded capture IDs for a local before/after, overlay and raw difference viewer. Headless app compare --session ID --before CAPTURE_ID --after CAPTURE_ID starts the viewer; --summary returns diagnostic JSON with exit 4 for unknown comparison truth. Each capture is limited to 8 million pixels for this viewer. Changed, expired or unreviewed images are refused; raw pixel differences never adopt a baseline or establish correctness.
/app report starts a full-resolution local viewer for the selected run; /app stop closes it. Headless use: mavona app report --session SESSION_ID --inspection INSPECTION_ID [--data-dir PATH]; Ctrl+C stops its loopback server. Changed, expired or unrecorded report files are refused.
/app export /new/path.tar.gz previews a portable archive before approval; destinations must be outside Git worktrees and session storage. Headless app export --session ID --inspection ID --destination /new/path.tar.gz prints the exact preview; repeat with --approve-export REVIEW_ID to write it. Existing files are never replaced, and nothing is uploaded.
Headless tasks require explicit provider/model selection and execution scope:
./dist/mavona run "Change order validation" --provider ollama --model YOUR_MODEL \
--allow-write app/models/order.rb \
--allow-command '["ruby","bin/rails","test","test/models/order_test.rb"]' \
--verify '["ruby","bin/rails","test","test/models/order_test.rb"]' --format jsonl
./dist/mavona sessions list
./dist/mavona sessions show SESSION_ID
./dist/mavona sessions export SESSION_ID
./dist/mavona resume SESSION_IDA configured remote provider receives repository context when a task is submitted and can incur charges. Locality never changes automatically. Required checks report passed, failed or unknown independently of assistant prose. Task exit codes are 0 verified, 2 decision/approval required, 3 verification failed, 4 unknown/budget exhausted, 5 execution error, and 130 cancelled. Read-only inspect returns 0 for a selected Rails root or 2 for unsupported/ambiguous scope.
Browser engines are separate from the executable. Provision explicitly; startup never downloads them. Installation prints target/cache/download information and does not install privileged OS packages. Set PLAYWRIGHT_BROWSERS_PATH for a pre-provisioned offline cache.
./dist/mavona app doctor
./dist/mavona app install --browser chromium --dry-run
./dist/mavona app install --browser chromium
./dist/mavona app run --flow path/to/flow.json
# Review the returned complete flow and digest, then approve that exact digest:
./dist/mavona app run --flow path/to/flow.json --approve-flow DIGEST --format jsonlThe coding loop can request no-boot parse_ruby facts or propose probe_runtime. Runtime probing boots the selected app through Rails runner in the test environment and requires exact command approval; initializers can still have filesystem or network effects. Headless --allow-runtime-probe '["Order"]' authorizes that exact model list once. Runtime facts never verify task correctness. Large source reads and tool results are retrievable in bounded ranges; local compaction preserves pinned constraints and canonical evidence.
The coding loop exposes inspect_app through the same service. The TUI reviews the concrete proposed flow; headless runs can pass --allow-inspection-flow PATH to authorize that saved flow once. Changed files/settings or a changed review refuse execution. Model-proposed assertions remain diagnostic, and independent repository checks still determine task correctness. For exact headless image submission, --allow-image-sha256 '["SHA256_FROM_REVIEWED_CAPTURE"]' explicitly overrides vision capability on the selected route and grants each listed digest once. Only a newly captured masked image with matching bytes can be selected; this flag does not authorize browser access. Browser observations/assertions are recorded as canonical events; the full report remains local.
Named --profile desktop|tablet|mobile settings include viewport, pixel ratio, touch and mobile layout emulation; --color-scheme light|dark and --reduced-motion reduce|no-preference are included in the flow approval. Each run lists its selected profile and other unchecked profiles. Emulation is not real-device testing. Saved flows support tap for touch interactions. Only explicit loopback development origins are supported. /app doctor and /app run path/to/flow.json expose the same service in the terminal. Reports and masked captures live under the host-managed session artifact directory. Screenshots do not establish correctness. Use --trace and --video (or flow evidence flags) before reviewing the approval digest to record constrained Playwright traces and masked checkpoint video. Traces omit DOM, source, arguments and network payloads; the pinned upstream offline loader validates each archive. Videos play masked checkpoint frames at 2 fps and do not preserve pauses. Artifact success does not verify application behavior. Open an archive offline with mavona app replay --trace-file PATH or /app replay PATH; open the printed loopback URL in a browser. The foreground CLI stops on Ctrl+C; the TUI owns one viewer until /app stop, Ctrl+C or exit. Replay serves only embedded upstream assets and the selected immutable archive.
Default Bun tests use local fixtures, fake providers and local HTTP servers; no paid models or external Rails repository. Provision browsers first for actual engine tests. The real Rails/Turbo/Stimulus acceptance fixture has its own isolated SQLite test databases:
bun node_modules/playwright/cli.js install chromium firefox webkit
bundle install --gemfile fixtures/rails-dogfood/Gemfile
ruby fixtures/rails-dogfood/bin/check
bun test
bun scripts/rails-browser-acceptance.ts
MAVONA_TEST_BINARY="$PWD/dist/mavona" bun test tests/cli.test.ts tests/session-cli.test.ts tests/inspection-cli.test.ts
python3 scripts/pty-smoke.py dist/mavonaOnly Darwin arm64 has observed native packaging evidence so far. Clean isolated browser installation and execution were tested there without Node/Bun on PATH. CI is prepared for Linux and macOS but has not run remotely. Cross-platform support, signing and publication are not claimed.
Local unsigned artifact preparation, checksum verification and install/remove instructions are in distribution/README.md. Packaging does not authorize publication or establish full release acceptance.
- Implementation plan and release acceptance
- Product requirements and architecture
- Terminal/source UX and App Inspection
- Providers and locality, trust boundaries and retention
- Rewrite parity, evaluation, preview policy and glossary
Input mockups and historical review material are design inputs outside tracked source. The maintained UX contracts capture the required conversation, code review and App Inspection workflows.
MIT — Copyright (c) 2026 Daryl Yeo.