helix library

Classes

DnaClaudeConfig

The Claude tool configuration (claude:).

DnaConfig

The parsed dna/_dna.json of a repository.

DnaHost

Injectable host interface: every file-system and git access of the DNA engine goes through this seam, so the engine core stays free of dart:io/Process and can be compiled to WebAssembly (the JS bridge injects node callbacks instead).

DnaInstantiationResult

Outcome of one instantiation run (see the golden-update semantics in the README): locally changed instances are backed up and overwritten, pending updates are written and reported once, an up-to-date project passes.

DnaManifest

The bookkeeping helix writes to <target>/dna/_generated.json.

DnaManifestClaude

The Claude section of the manifest.

DnaManifestInstance

One instantiated (public) file owned by the DNA.

DnaManifestLayer

One resolved layer of the inheritance tree.

Helix

The command line interface for Helix

IoDnaHost

DnaHost backed by dart:io and the local git binary. This file is the only place binding the engine to the real platform — the engine core itself must not import dart:io.

MemoryDnaHost

In-memory DnaHost for tests and as the reference for callback-based hosts (WASM bridge). Stores files in a flat map keyed by normalized posix path.

Constants

dnaConfigPath → const String

Path of the DNA config file relative to the project root — the only place DNA configuration lives.

dnaGeneratedPath → const String

Path of the engine-owned bookkeeping relative to the project root.

generatedDnaCommitMessage → const String

Commit message of the automatic commit that carries everything the DNA generated.

invalidDotEscapesMessage → const String

Headline when DNA files escape a leading dot with dot_.

jsonOverridesSuffix → const String

Sidecar suffix that merges into the same-named .json file.

uncommittedTargetsMessage → const String

Headline of the per-file guard failure.

yamlOverridesSuffixes → const List<String>

Structural YAML overrides are not supported yet — hard error.

Functions

cAction(Object message) → String

Color of an instruction in the DNA report.

cCmd(Object message) → String

Color of a file path or command in the DNA report.

cDetail(Object message) → String

Color of a step that was carried out — the details a reader skims past on the way to the instruction.

cError(Object message) → String

Colors of the DNA report — the problem in cError, files in cCmd, what to do in cAction, what happened in cDetail.

describeDnaSources(List<String> paths, Map<String, String> sources) → String

Renders one instruction per reported path: move the edits from the generated file to the DNA file it is produced from.

describeInvalidDotEscapes(List<String> segments) → String

Renders one instruction per invalid dot escape: rename it to dot-.

instantiateDna({required DnaHost host, required String targetRoot, String? baseDnaRoot, required String baseVersion}) → Future<DnaInstantiationResult>

Runs one instantiation over targetRoot: expands the inheritance tree, merges all dna/ replicas (last override wins), renders markdown markers, substitutes variables, converts file naming and reconciles the generated state with the project — honoring instance ownership from the manifest and the per-file guard (no existing file with uncommitted work is ever overwritten).

invalidDotEscapes(DnaHost host, String root) → List<String>

The paths below <root>/dna/ that escape a leading dot with dot_ instead of dot-, project-relative. Only dot- is decoded, so these would instantiate as literal dot_… folders.

parseGitStatusPaths(String output, {String prefix = ''}) → Set<String>

Parses git status --porcelain output into paths relative to the folder identified by prefix (the repo-root-relative path of that folder, as printed by git rev-parse --show-prefix). Rename entries contribute both their old and their new path.

readDnaConfig(DnaHost host, String targetRoot, {String? packageLabel}) → ({DnaConfig config, List<String> warnings})

Reads the DNA config of targetRoot from dna/_dna.json. A missing file yields the default config — but only when there is no dna/ folder at all. A dna/ folder without _dna.json is an error: the config is the only thing that says whether that folder is hand-authored (role: dna) or engine-generated, and defaulting to project would let the engine wipe a hand-written DNA. Run helix init to place the config.

runDnaTest({String? targetRoot, DnaHost? host, String? baseDnaRoot, void log(String message)?}) → Future<void>

Entry point for the placed DNA test (test/dna/dna_test.dart imports helix as dev-dependency and calls this). Runs one instantiation over the current project and throws when the project is not in a clean, up-to-date DNA state:

Typedefs

DnaTestRunner = Future<void> Function({String? baseDnaRoot, DnaHost? host, void log(String message)?, String? targetRoot})

Signature of runDnaTest — the seam that lets the commands calling it be tested without a project on disk.

GitRunner = Future<String> Function(String workingDirectory, List<String> args)

Runs a git command in workingDirectory and returns its stdout — injectable for tests.