just-dna-compiler

Validate, compile, and reverse just-dna annotation modules.

Generated from the command tree itself at build time, so a flag added or renamed in the code appears here without anyone editing a table.

just-dna-compiler close

Declare this module's authoring phase finished, bound to its authored bytes (RM73).

Authoring is a process and it had no end, so every check that needed to know whether a value was still a copy of its source, or whether a stub had been filled, was guessing. Closing writes a closure block into the module's verification.json naming the hash of module_spec.yaml and the authored CSVs as they stand right now. Edit any of them afterwards and the hash moves, the compiler drops the closure, and the module is open again — which is the point.

It is deliberate on purpose. validate will not do this for you however cleanly it passes: a record stamped by whatever happened to run says only that something ran. --private-key signs the act with the same key sign uses on a compiled artifact, which is what turns someone closed this into this party closed this.

Refuses on a spec that does not validate, and does not refuse on warnings — an unresolved rsID or an ungrounded threshold is a legitimate state to call finished.

Argument	Type	Default	Says
spec_dir	directory	required	Module spec directory to declare finished

Option	Type	Default	Says
--by	str		Who is closing authoring. Legibility only — sign it to make it provable.
--private-key	file		Ed25519 private key PEM (from keygen). Signs the closure over the authored bytes.

just-dna-compiler compile

Compile a spec directory into a parquet artifact + manifest.json. Exit 1 on failure.

Argument	Type	Default	Says
spec_dir	directory	required	Module spec directory
output_dir	directory	required	Output dir for parquet + manifest.json

Option	Type	Default	Says
--strict / --no-strict	flag		All-or-nothing: fail rather than emit a partial artifact with unresolved positions.
--ensembl-cache	path		DEPRECATED (removed at 1.0): Ensembl reference (.duckdb/parquet dir); routes to just-dna-enricher. Prefer producing resolution.csv with just-dna-enricher enrich.
--resolve / --no-resolve	flag	on	Resolve missing rsid/position via the injected Ensembl reference.
--compression	str	zstd	Parquet compression codec.
--compiled-by	str		Provenance tag for the manifest (e.g. marketplace-server).
--strip-identity	flag		Inject the identity authority keys (namespace/owner/canonical_id) to strip.
--authority-key	str	[]	Extra authority-owned module key to strip (repeatable).

just-dna-compiler describe

Emit the full machine description of one table kind: columns, options, requirements.

Always JSON — this is the form an authoring tool or MCP surface consumes, beside just_dna_format.reference.authoring_reference().

Argument	Type	Default	Says
kind	str	required	Authored CSV to describe, e.g. variants.csv

just-dna-compiler hint

Inspect authored CSV rows and report what is wrong, what the model rewrites, and what is left to you on purpose. Writes nothing — the corrected text goes to stdout for you to use or not.

Offline: this is the pure half. The enricher adds the lookups that need a reference.

Argument	Type	Default	Says
kind	str	required	Authored CSV the rows belong to

Option	Type	Default	Says
--file	file		Read the CSV text from a file.
--row	str		A single CSV row (or header+rows) inline.
--json	flag		Emit the full machine report.

just-dna-compiler keygen

Generate an Ed25519 signing key: the private PEM sign needs, and the public key verify pins.

Closes the same gap verify was built to close, one step upstream. verify_manifest and the signing helpers live in just-dna-format, which ships no CLI of its own (Typer would breach its pydantic-plus-cryptography dependency floor) — so sign --private-key demanded a file the toolchain had no way to produce, and verify --public-key demanded a string derivable only by calling public_key_b64_from_pem from Python. Both halves now have a route.

The key is unencrypted PKCS#8, which is what sign_digest reads. That is a deliberate limit rather than an oversight: this command bootstraps a key, it is not a key-management system, and pretending otherwise by adding a passphrase prompt would imply custody guarantees nothing here provides. A publishing key belongs in whatever secret store the publisher already runs.

Option	Type	Default	Says
--out	file		Write the private key PEM here (refuses to overwrite). Omit to print it to stdout.

just-dna-compiler reference

Print the authoring reference — every model's columns, vocabularies and requirements.

Generated from the live pydantic models, so it cannot drift from what the compiler accepts. That is the point: it is the drift-proof replacement for a hand-kept spec dump, and the consumer that most needs it (an MCP surface offering an author the valid values) had to import just_dna_format.reference and write Python, because the schema tier ships no CLI. describe answers the same question for one table; this answers it for all of them at once, plus the vocabularies, the open-vs-closed flag, the REQUIRED_ANY_OF rules and the recommended palette.

Option	Type	Default	Says
--json / --summary	flag	on	Full JSON (default), or a one-line-per-table summary.
--schemas	flag		Emit the per-model JSON Schemas instead of the authoring reference.

just-dna-compiler requirements

What an author must supply for one table kind: always, one-of, and never-empty defaults.

Argument	Type	Default	Says
kind	str	required	Authored CSV to describe

Option	Type	Default	Says
--json	flag		Emit the machine-readable form.

just-dna-compiler reverse

Reverse a compiled parquet artifact back into the authored spec DSL (yaml + csv).

Argument	Type	Default	Says
parquet_dir	directory	required	Compiled parquet directory
output_dir	directory	required	Output dir for the reconstructed spec

Option	Type	Default	Says
--module-name	str		Override the recovered module name.
--title	str
--description	str
--report-title	str
--icon	str	database
--color	str	#6435c9
--version	str		Advisory module.version to re-emit into the spec.
--resolution / --no-resolution	flag	on	Also emit resolution.csv (the resolved facts), so reverse→compile is fully offline.
--genome-build	str		Override the build. Read from the artifact's manifest.json by default; only needed for a bare parquet directory that carries no manifest.

just-dna-compiler scaffold

Create module_spec.yaml plus a stub CSV per kind. Never overwrites; existing files are kept.

Re-runnable: run it again with a different --kind to add a table to a module that already exists.

Argument	Type	Default	Says
spec_dir	directory	required	Module spec directory to create

Option	Type	Default	Says
--kind	str	[]	Authored table kind to stub (repeatable).
--name	str		Machine name for the module block.
--rows	int range	1	Stub rows per table.
--dry-run	flag		Report the plan; write nothing.

just-dna-compiler sign

Sign a compiled module's artifact.digest and write the signature into its manifest.json.

Signs the digest, never the files directly: the digest is already a Merkle root over the whole file set, so one signature covers every artifact byte, and re-signing after any edit is impossible to forget — the digest moves and the old signature stops verifying.

Argument	Type	Default	Says
module_dir	directory	required	Compiled module directory (holding manifest.json)

Option	Type	Default	Says
--private-key	file	required	Ed25519 private key PEM.

just-dna-compiler signature

Print the content signature of a spec's raw authored data — no compile, no Ensembl.

Name- and reference-independent, so a client can compute it and dedup against a registry without recompiling (surviving metadata-strip and a recompile against a different reference).

Argument	Type	Default	Says
spec_dir	directory	required	Module spec directory

just-dna-compiler stub

Print a header plus stub rows, with a placeholder wherever a human must decide.

An unreplaced stub cannot compile — it is refused by name and row — so a half-filled table fails loudly on exactly the rows still to do rather than compiling into a module that asserts nothing.

Argument	Type	Default	Says
kind	str	required	Authored CSV to emit stub rows for

Option	Type	Default	Says
--rows	int range	1	How many stub rows to emit.

just-dna-compiler sweep

Measure what this release changed about compiled output, against a previous release's (RM126).

BEFORE must have been produced by the previous release — one compile per module spec, from the SAME spec root this run uses, so the compiler is the only variable. With --release the release gate runs and a measured movement that no ReleaseRecord declares exits 1.

This is a release-sequence command, not an ordinary test: it needs the previous release actually installed. COMPILER.md carries the full sequence.

Argument	Type	Default	Says
before	directory	required	Compiled output tree from the PREVIOUS release
after	directory	required	Compiled output tree for THIS release (built when --spec-root)

Option	Type	Default	Says
--spec-root	directory		Compile every module spec under this directory into AFTER with the installed compiler.
--release	str		Run the release gate against the ReleaseRecord for this version (0.7.0, or the stamped just-dna-compiler 0.7.0). Exit 1 on a finding.
--json	flag		Emit the measurement as JSON.

just-dna-compiler template

Print a header-only CSV for one authored table kind, generated from the live models.

The requirements go to stderr, so just-dna-compiler template x.csv > x.csv stays clean.

Argument	Type	Default	Says
kind	str	required	Authored CSV to emit a header for, e.g. repeat_alleles.csv

just-dna-compiler validate

Validate a spec directory without producing output. Exit 1 if invalid.

Argument	Type	Default	Says
spec_dir	directory	required	Module spec directory

Option	Type	Default	Says
--strip-identity	flag		Inject the identity authority keys (namespace/owner/canonical_id) to strip.
--authority-key	str	[]	Extra authority-owned module key to strip (repeatable).
--strict / --best-effort	flag		Pre-flight for a strict compile: escalate the mode-laddered findings to errors, as compile --strict does. Use it whenever the compile you intend to run is strict.

just-dna-compiler verify

Verify a compiled module against its manifest (SPEC §5 verify-then-install). Exit 1 on failure.

The verify-only path the format has always specified and never exposed: verify_manifest and the signature check live in just-dna-format, which ships no CLI of its own (Typer would breach its pydantic-plus-cryptography dependency floor), so until now a consumer had to write Python to check a download. It re-hashes every artifact file, recomputes artifact.digest over the set, and — when a key is pinned — verifies the Ed25519 signature over that digest.

Argument	Type	Default	Says
module_dir	directory	required	Compiled module directory (holding manifest.json)

Option	Type	Default	Says
--require-marketplace / --no-require-marketplace	flag	on	Demand compile_success and compiled_by=marketplace-server. Off for a local artifact.
--public-key	str		Base64 raw Ed25519 key the manifest signature MUST verify against.
--check-inputs	flag		Also hash the declared inputs[].
--check-logs	flag		Also hash any logs[] present on disk.
--check-provenance	flag		Also hash the provenance document, if declared and present.
--check-logo	flag		Also hash the logo, if declared.
--check-readme	flag		Also hash the readme, if declared.
--check-derived	flag		Also hash any declared derived-fact sidecar CSVs present on disk.