splicecraft 0.9.13

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. Every save path — L0 Domesticator, Constructor TU / MOD / L3+, Traditional cloning, Gibson, MoClo — lands as a single complete library entry (payload + overhangs + backbone) carrying every parent L0 / TU feature as its own annotation, so the L0 → TU → MOD provenance chain is browsable from the Library panel.
• 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.
• Log experiments from the Experiments toolbar — full-screen lab-notebook workbench with a split-pane layout: entries list on the left (Updated · Title with horizontal scroll for long titles)
  • full-width markdown TextArea editor on the right. Group entries into named projects (Ctrl+P → Projects… picker: Open / New / Rename / Duplicate / Delete) — projects are to experiments what plasmid collections are to plasmids. In-editor colored cross-references — @<plasmid> (lime), !<action> (purple), &<gel> (orange) — backspace deletes the whole tag, and Ctrl+G or double-click on a tag opens its source modal focused on that entry. Persistent experiments.json + experiment_projects.json + gels.json, per-entry image attachments (file picker on Linux/WSL · Pillow clipboard grab on Win/Mac), and F7 spellcheck via pyspellchecker with a user-maintained custom dictionary.
• Save Simulator gels from the Simulator → Gel → Library button — name + save the current lane layout + agarose %, load it back later, or reference it as &<id> in an Experiments entry.
• 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

• Load-time collision detection across parts bin, plasmid library, and primer library. An exact duplicate (same name + same content) prompts skip (default) or keep as " COPY" so duplicates can coexist with their twin. A name-match with different content prompts three-way keep original (default) / overwrite / cancel the load — never silently clobbers existing data.
• 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.
• Master Delete under File → "⚠ Master Delete (wipe all user data)…" lets you wipe every plasmid, collection, experiment, gel, primer, part, grammar, codon table, feature, setting, backup, snapshot, and pre-update recovery copy in one go — true clean slate. Triple-gated: typed YES (case-sensitive) to enable the Delete button, then a default-No confirm with a 3-second cool-down on the destructive button. No keyboard shortcut. No agent endpoint.
• Entry-vector auto-detection. When you import a folder via Collections → New Collection, SpliceCraft scans every plasmid, identifies acceptors (UPD / α1 / α2 / Ω1 / Ω2 for Golden Braid), and auto-binds them to their roles. Manual review + override via Settings → Entry Vectors…. Configured acceptors flip TU classification from the lenient fallback to strict per-acceptor matching with explicit role labels.

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