codi-cli

codi-cli / core/config

core/config

Classes

StateManager

Defined in: core/config/state.ts:123

Manages the Codi state file at .codi/state.json.

The state file tracks all generated files and their hashes, enabling:

• Drift detection: identify files modified by the user since last generation
• Incremental generation: skip unchanged files
• Preset cleanup: remove only files installed by a specific preset

Example

const manager = new StateManager('/path/to/.codi', '/path/to/project');
const report = await manager.detectDrift('claude-code');
if (isOk(report)) {
  const drifted = report.data.files.filter(f => f.status === 'drifted');
  console.log(`${drifted.length} files modified since last generation`);
}

Constructors

Constructor

new StateManager(configDir, projectRoot?): StateManager;

Defined in: core/config/state.ts:127

Parameters

Returns

StateManager

Methods

deleteOrphans()

deleteOrphans(orphans): Promise<string[]>;

Defined in: core/config/state.ts:290

Unlinks the given orphaned files from disk. Silently ignores files that were already removed. Returns the paths that were actually deleted so the caller can report them.

Parameters

Returns

Promise<string[]>

detectDrift()

detectDrift(agentId): Promise<Result<DriftReport>>;

Defined in: core/config/state.ts:340

Compares the current on-disk files for an agent against their stored hashes.

Parameters

Returns

Promise<Result<DriftReport>>

A DriftReport listing synced, drifted, and missing files

detectHookDrift()

detectHookDrift(): Promise<Result<DriftFile[]>>;

Defined in: core/config/state.ts:417

Compares the current on-disk hook files against their stored hashes.

Returns

Promise<Result<DriftFile[]>>

detectOrphans()

detectOrphans(nextAgents): Promise<Result<{
  clean: GeneratedFileState[];
  drifted: GeneratedFileState[];
}>>;

Defined in: core/config/state.ts:237

Detects orphaned generated files — files that exist in the previous state but are not present in the next generation run. Called BEFORE updateAgentsBatch so the previous state is still readable.

An orphan is only returned as deletable if its current on-disk hash matches the previously recorded generatedHash (meaning no user edits). Drifted orphans (user-edited after generation) are returned in drifted so the caller can warn or force-delete via force: true.

The method does not touch the filesystem or state — it is a pure diff+inspect. Call deleteOrphans() to actually unlink the files.

Parameters

Returns

Promise<Result<{ clean: GeneratedFileState[]; drifted: GeneratedFileState[]; }>>

detectPresetArtifactDrift()

detectPresetArtifactDrift(): Promise<Result<DriftFile[]>>;

Defined in: core/config/state.ts:386

Compares the current on-disk preset artifact files against their stored hashes.

Returns

Promise<Result<DriftFile[]>>

getAgentFiles()

getAgentFiles(agentId): Promise<Result<GeneratedFileState[]>>;

Defined in: core/config/state.ts:328

Returns the generated file records for a single agent.

Parameters

Returns

Promise<Result<GeneratedFileState[]>>

read()

read(): Promise<Result<StateData>>;

Defined in: core/config/state.ts:133

Reads the state file. Returns an empty state if the file does not exist.

Returns

Promise<Result<StateData>>

removeAgents()

removeAgents(agentIds): Promise<Result<void>>;

Defined in: core/config/state.ts:205

Removes agent entries that no longer appear in the active configuration. Called by apply.ts after a customize that unselects one or more agents, so stale entries do not linger and inflate future orphan counts.

Parameters

Returns

Promise<Result<void>>

updateAgent()

updateAgent(agentId, files): Promise<Result<void>>;

Defined in: core/config/state.ts:177

Updates the generated file records for a single agent.

Parameters

Returns

Promise<Result<void>>

updateAgentsBatch()

updateAgentsBatch(updates): Promise<Result<void>>;

Defined in: core/config/state.ts:188

Updates the generated file records for multiple agents in a single write.

Parameters

Returns

Promise<Result<void>>

updateHooks()

updateHooks(files): Promise<Result<void>>;

Defined in: core/config/state.ts:317

Updates the generated hook file records.

Parameters

Returns

Promise<Result<void>>

updatePresetArtifacts()

updatePresetArtifacts(files): Promise<Result<void>>;

Defined in: core/config/state.ts:371

Merges new preset artifact records into the state, updating existing entries by path.

Parameters

Returns

Promise<Result<void>>

write()

write(state): Promise<Result<void>>;

Defined in: core/config/state.ts:155

Writes the state file atomically using a temp file + rename.

Parameters

Returns

Promise<Result<void>>

Interfaces

ArtifactFileState

Defined in: core/config/state.ts:34

State record for a single file installed from a preset.

Tracks which preset each installed file came from, enabling targeted cleanup when a preset is removed.

Properties

hash

hash: string;

Defined in: core/config/state.ts:38

Hash of the file content at installation time.

path

path: string;

Defined in: core/config/state.ts:36

Relative path of the installed artifact file (relative to project root).

preset

preset: string;

Defined in: core/config/state.ts:40

Name of the preset that installed this file.

timestamp

timestamp: string;

Defined in: core/config/state.ts:42

ISO 8601 timestamp of when this file was last installed.

DriftFile

Defined in: core/config/state.ts:70

Drift status for a single generated file.

Produced by StateManager.detectDrift() by comparing the stored hash against the current on-disk file content.

Properties

currentHash?

optional currentHash?: string;

Defined in: core/config/state.ts:83

The hash of the current on-disk content (present when status is “drifted”).

expectedHash?

optional expectedHash?: string;

Defined in: core/config/state.ts:81

The hash stored at generation time (present when status is “drifted”).

path

path: string;

Defined in: core/config/state.ts:72

Relative path of the file being checked.

status

status: "synced" | "drifted" | "missing";

Defined in: core/config/state.ts:79

Result of the hash comparison:

• "synced" - file matches the stored hash (no changes)
• "drifted" - file exists but its hash differs (user-edited)
• "missing" - file does not exist on disk

DriftReport

Defined in: core/config/state.ts:91

Drift report for all files belonging to a single agent.

Returned by StateManager.detectDrift().

Properties

agentId

agentId: string;

Defined in: core/config/state.ts:93

The agent id this report covers (e.g. “claude-code”).

files

files: DriftFile[];

Defined in: core/config/state.ts:95

Per-file drift status entries.

GeneratedFileState

Defined in: core/config/state.ts:15

State record for a single file generated by a Codi adapter.

Stored in state.json and used for drift detection: the generatedHash is compared against the current on-disk hash to detect user edits.

Properties

generatedHash

generatedHash: string;

Defined in: core/config/state.ts:21

Hash of the file content at generation time. Changes indicate user edits (drift).

path

path: string;

Defined in: core/config/state.ts:17

Relative path of the generated file (relative to project root).

sourceHash

sourceHash: string;

Defined in: core/config/state.ts:19

Hash of the source artifacts that produced this file.

sources

sources: string[];

Defined in: core/config/state.ts:23

Names of the source artifacts (rules, skills) that contributed to this file.

timestamp

timestamp: string;

Defined in: core/config/state.ts:25

ISO 8601 timestamp of when this file was last generated.

ParsedProjectDir

Defined in: core/config/parser.ts:33

The raw parsed contents of a .codi/ project directory, before validation.

Produced by scanProjectDir() and consumed by resolveConfig().

Properties

agents

agents: NormalizedAgent[];

Defined in: core/config/parser.ts:43

Normalized agent artifacts scanned from the agents/ subdirectory.

flags

flags: Record<string, FlagDefinition>;

Defined in: core/config/parser.ts:37

Raw flag definitions keyed by flag name, as read from flags.yaml.

manifest

manifest: ProjectManifest;

Defined in: core/config/parser.ts:35

The parsed codi.yaml manifest describing agents, rules, and skills to enable.

mcp

mcp: McpConfig;

Defined in: core/config/parser.ts:45

Merged MCP server configuration from mcp.yaml and mcp-servers/.

rules

rules: NormalizedRule[];

Defined in: core/config/parser.ts:39

Normalized rule artifacts scanned from the rules/ subdirectory.

skills

skills: NormalizedSkill[];

Defined in: core/config/parser.ts:41

Normalized skill artifacts scanned from the skills/ subdirectory.

StateData

Defined in: core/config/state.ts:51

The complete state stored in .codi/state.json.

Tracks all generated files and their hashes to enable drift detection, incremental generation, and preset artifact cleanup.

Properties

agents

agents: Record<string, GeneratedFileState[]>;

Defined in: core/config/state.ts:57

Generated file records keyed by agent id (e.g. “claude-code”).

hooks

hooks: GeneratedFileState[];

Defined in: core/config/state.ts:59

Generated file records for hook scripts.

lastGenerated

lastGenerated: string;

Defined in: core/config/state.ts:55

ISO 8601 timestamp of the most recent generation run.

presetArtifacts?

optional presetArtifacts?: ArtifactFileState[];

Defined in: core/config/state.ts:61

File records for artifacts installed from presets.

version

version: "1";

Defined in: core/config/state.ts:53

Schema version for forward-compatibility checks.

Functions

flagsFromDefinitions()

function flagsFromDefinitions(defs, source): ResolvedFlags;

Defined in: core/config/composer.ts:22

Converts raw flag definitions (as stored in flags.yaml) into resolved flags with source tracking.

Each resolved flag records the path of the flags.yaml file it came from, enabling drift detection and audit logging.

Parameters

Returns

ResolvedFlags

A ResolvedFlags map ready for use in NormalizedConfig

Example

const resolved = flagsFromDefinitions(
  { 'max-file-lines': { mode: 'enforced', value: 700, locked: false } },
  '/path/to/.codi/flags.yaml'
);

parseFlags()

function parseFlags(configDir): Promise<Result<Record<string, FlagDefinition>>>;

Defined in: core/config/parser.ts:79

Parameters

Returns

Promise<Result<Record<string, FlagDefinition>>>

parseManifest()

function parseManifest(configDir): Promise<Result<ProjectManifest>>;

Defined in: core/config/parser.ts:64

Reads and validates the codi.yaml manifest file from a config directory.

Parameters

Returns

Promise<Result<ProjectManifest>>

A Result wrapping the parsed manifest, or errors if the file is missing or invalid

resolveConfig()

function resolveConfig(projectRoot): Promise<Result<NormalizedConfig>>;

Defined in: core/config/resolver.ts:33

Resolves the full project configuration by reading .codi/ as the single source of truth.

Reads the manifest, flags, rules, skills, agents, and MCP config from the .codi/ directory, validates them, and returns a NormalizedConfig ready for generation. Presets are consumed at install time and are not re-read during resolution.

Parameters

Returns

Promise<Result<NormalizedConfig>>

A Result wrapping the resolved config on success, or validation errors on failure

Example

import { resolveConfig, isOk } from 'codi-cli';

const result = await resolveConfig(process.cwd());
if (isOk(result)) {
  console.log(`${result.data.rules.length} rules loaded`);
} else {
  result.errors.forEach(e => console.error(e.message));
}

scanProjectDir()

function scanProjectDir(projectRoot): Promise<Result<ParsedProjectDir>>;

Defined in: core/config/parser.ts:412

Reads and parses all artifacts from a .codi/ project directory.

Reads the manifest, flags, rules, skills, agents, and MCP config in parallel. Returns a ParsedProjectDir containing normalized but unvalidated data.

Parameters

Returns

Promise<Result<ParsedProjectDir>>

A Result wrapping the parsed directory contents, or errors if any file is invalid

scanRules()

function scanRules(rulesDir): Promise<Result<NormalizedRule[]>>;

Defined in: core/config/parser.ts:110

Parameters

Returns

Promise<Result<NormalizedRule[]>>

validateConfig()

function validateConfig(config): ProjectError[];

Defined in: core/config/validator.ts:44

Validates a NormalizedConfig and returns a list of errors.

Checks agent ids against the registered adapter list, validates rule and skill names and sizes, enforces flag references, checks platform compatibility for skills, and rejects rule/skill/agent content containing unresolved git merge-conflict markers (E_CONFLICT_MARKERS). Returns an empty array if the config is valid.

Parameters

Returns

ProjectError[]

An array of ProjectError objects. Empty array means valid.

Example

const errors = validateConfig(config);
if (errors.length > 0) {
  errors.forEach(e => console.error(e.message));
}