gg_dna 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): hand-modified instances fail without writing, pending updates are written and reported once, an up-to-date project passes.

DnaManifest

The bookkeeping gg_dna 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.

GgDna

The command line interface for GgDna

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.

Enums

DnaRole

The role a repository plays in the DNA system.

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_.

modifiedInstancesMessage → const String

Headline shown when generated files were edited by hand.

needsCommitMessage → const String

Headline when the generated files could not be committed.

uncommittedTargetsMessage → const String

Headline of the per-file guard failure.

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.

cError(Object message) → String

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

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-.

ggDnaPackageRoot() → Future<String>

Resolves the root folder of the installed gg_dna package (its own dna/ folder is the implicit base layer).

instantiateDna({required DnaHost host, required String targetRoot, String? baseDnaRoot, required String baseVersion}) → 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 gg_dna 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 gg_dna 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

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

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