splicecraft 0.9.5

Terminal-based circular plasmid map viewer, sequence editor, and Primer3/Golden Braid primer design workbench

SpliceCraft

A plasmid workbench you live in. SpliceCraft is a terminal-native viewer, sequence editor, primer + mutagenesis designer, Golden Braid / MoClo cloning workbench, and in-process BLAST / HMMscan engine — all rendered as crisp Unicode braille graphics in any modern terminal.

Built by a practicing bioengineer for daily lab work. Bug reports come from the bench; releases ship from the bench.

Quick start

pipx install splicecraft
splicecraft                      # empty canvas
splicecraft L09137               # fetch pUC19 from NCBI on launch
splicecraft myplasmid.gb         # local GenBank or .dna

Press ? once running for the full keyboard-shortcut reference.

See docs/install.md for pip / uv / conda / source installs and the user-data directory location.

What it does

• View circular and linear braille-dot maps, per-base sequence panel with two-strand display, AA translation, restriction overlays (200+ NEB enzymes incl. Type IIS).
• Edit in-place with deepcopy undo / redo, feature CRUD, 3-second-debounced crash-recovery autosave.
• Clone through a multi-tab Constructor (Traditional / Gibson / Golden Braid / MoClo / custom grammar) with a 4-source part picker.
• Design primers via Primer3 (detection / cloning / GB / generic) with a persistent Designed → Ordered → Validated lifecycle.
• Mutagenize any CDS via SOE-PCR site-directed mutagenesis with edge-case fallback to 2-primer modified-outer PCR.
• Simulate PCR + agarose gels (0.5–4% with the Helling-Goodman- Boyer mobility curve and form corrections).
• Align sequencing runs from the Sequencing toolbar — drop in a Plasmidsaurus .zip, browse a nested 4-tab view of the run (General overview · per-Samples table · Quality metrics including k-mer + contamination + coverage · Align), pick a sample + target plasmid; the pairwise alignment lands as a sequencing-read lane on the linear map right next to the rail, and the target's library entry auto-tags to linear view for future opens.
• Search your library with in-process BLASTN / BLASTP / HMMscan (via pyhmmer — no external blast+ install).
• Drive from outside via a 60+ endpoint localhost JSON API (splicecraft --agent) and a stdlib-only CLI sidecar (splicecraft-cli).

Full feature reference: docs/features.md.

Robustness is a feature

• Four-layer JSON safety net per save: atomic write + .bak + rotating timestamped backups + daily snapshots + suspicious-shrink guard.
• Pre-update snapshots before any pip / pipx / uv subprocess; stored in a sibling directory so a hypothetical recursive-wipe bug in a new version cannot kill recovery.
• 2,600+ tests anchored on 41 sacred invariants (see CLAUDE.md), hypothesis property-based fuzzing on biology primitives.
• Defence-in-depth size caps on every external input (NCBI / PyPI / Kazusa fetch, .dna history packets, JSON saves, agent-API bodies, CLI responses).
• Lock-file PID-fsync + stale-PID detection so a SpliceCraft killed on a shared filesystem releases its lock on next launch.

Full data-safety writeup: docs/data-safety.md. Security policy: SECURITY.md.

Documentation

Topic	Where
Install methods	docs/install.md
First five seconds with pUC19	docs/getting-started.md
Full feature list	docs/features.md
Keybindings + menus	docs/keybindings.md
Data safety + backups	docs/data-safety.md
Agent API (HTTP)	docs/agent-api.md
CLI sidecar	docs/cli.md
Architecture	docs/architecture.md
Sacred invariants	CLAUDE.md
Contributing	CONTRIBUTING.md
Security policy	SECURITY.md
v1.0.0 acceptance gate	V1_GATE.md
Changelog	CHANGELOG.md
Release checklist	RELEASE_CHECKLIST.md

Tests

python3 -m pytest -n auto -q                  # full suite (~5–6 min on 8 cores)
python3 -m pytest tests/test_dna_sanity.py    # biology correctness only (< 2 s)
python3 -m pytest tests/test_perf_regression.py  # perf gates (~3 s)

All tests run offline against synthetic SeqRecords and monkeypatched data paths; the autouse _protect_user_data fixture in tests/conftest.py guarantees no test can write to real user files.

Maintenance

SpliceCraft is actively maintained. The maintainer is a practicing bioengineer running real cloning workflows in it daily; releases typically go out the same week a problem surfaces at the bench. Issues and PRs welcome at github.com/Binomica-Labs/SpliceCraft/issues.

See CONTRIBUTING.md before opening a non-trivial PR — it walks through the sacred invariants, the test cadence, and the security-sensitive code surfaces.

License

MIT