@formtrieb/cdf-core

Core library for the Component Description Format (CDF) — parsing, validation, profile inference, token-tree, and analysis primitives.

This package is framework-agnostic: pure TypeScript functions that take parsed YAML or JSON input and return typed results. It has no I/O of its own beyond optional file-reading helpers, no MCP layer, no skill-runtime assumptions. It is the substrate that both the @formtrieb/cdf-mcp adapter and the reference Angular generator consume.

Status

v1.0.1 — 2026-04-26. First usable public release (v1.0.0 was a no-op publish, see CHANGELOG.md). CDF spec v1.0.0 is frozen (Component / Profile / Target / Architecture, validated against Radix, shadcn, Primer, Material 3, USWDS). The library has shipped under workspace:* inside the Formtrieb monorepo for ~6 weeks; this version strips the monorepo-internal coupling and re-publishes it as a standalone npm package.

License: Apache-2.0.

Install

npm install @formtrieb/cdf-core
# or pnpm
pnpm add @formtrieb/cdf-core

Requires Node ≥ 20.

What's inside

| Surface | Symbols | Purpose | |---|---|---| | Parsing | parseCDF, parseCDFFile, parseConfig, parseConfigFile, parseProfile, parseProfileFile | Read and type-check CDF Component / Config / Profile YAML files. Returns typed CDFComponent / CDFConfig / CDFProfile. | | Validation | validate, validateFile, validateAll, validateProfile, validateProfileFile | Run the CDF v1.0.0 rule set (≥30 rules across structural, semantic, vocabulary, theming, token-reference). Returns structured Issue[] with severity. | | Resolution | resolveInheritance, resolveExtension, expandTokenPath | Resolve component inheritance (extends:, inherits:), token-path placeholders, profile-extends merge. | | Analysis | analyzeCoverage, analyzeComponentCoverage, suggestImprovements, detectVocabDivergences | Coverage report (which Profile vocabularies / grammars are unused), Component-level coverage delta, suggestion generator, vocab-near-miss detection (Levenshtein ≤2). | | Profile scaffolding | scaffoldProfile, parseScaffoldInput, aggregateRawMaterial, enrichRawMaterial, applyStructuralDeltas | Adapter-friendly scaffolder used by the cdf-profile-scaffold Skill. Emits typed ScaffoldResult with milestones and raw material; consumer (Skill or other adapter) drives the interview loop. | | Token tree | TokenTree, RawToken, TokenExtensions, ColorModifier | Generic DTCG token-tree walker. Inlined from formtrieb-tokens-core in v1.0.0; no MoPla-specific assumptions. | | Vocab divergence apply | applyComponentRename | Rewrite component spec value occurrences after a vocab-divergence resolution. |

See src/index.ts for the full export list.

Minimal example

import { parseCDFFile, validate } from "@formtrieb/cdf-core";

const component = parseCDFFile("./specs/components/Button.spec.yaml");
const issues = validate(component);

for (const issue of issues) {
  console.log(`[${issue.severity}] ${issue.rule}: ${issue.message}`);
}

For Profile-level work:

import { parseProfileFile, validateProfile } from "@formtrieb/cdf-core";

const profile = parseProfileFile("./acme.profile.yaml");
const result = validateProfile(profile, { resolveTokens: true });

console.log(result.summary);

Relationship to other packages

| Package | Role | |---|---| | @formtrieb/cdf-mcp | MCP server exposing this library to LLM clients (Claude Desktop, MCP Inspector). Thin adapter — every business decision lives here. | | formtrieb/cdf repo | Normative specs (CDF-COMPONENT-SPEC, CDF-PROFILE-SPEC, CDF-TARGET-SPEC) + foreign-DS validation ports. |

Development

pnpm install
pnpm --filter @formtrieb/cdf-core build
pnpm --filter @formtrieb/cdf-core test

License

Apache-2.0 — alignment with the CDF spec.