feat(workflow-util): frontmatter markdown parser — RFC #351 Phase 1 #352

2026-05-19T04:42:13Z

xiaoju commented

2026-05-19 04:42:13 +00:00

What

Add frontmatter markdown parser and validator to workflow-util.

Why

RFC #351 — agent output needs a unified format where frontmatter carries structured meta (for moderator routing) and markdown body carries content (for downstream agents).

Changes

workflow-util/src/frontmatter-markdown/types.ts — AgentFrontmatter, ParsedFrontmatterMarkdown, FrontmatterValidationError types
workflow-util/src/frontmatter-markdown/frontmatter-markdown.ts — parseFrontmatterMarkdown() + validateFrontmatter() with built-in minimal YAML parser
workflow-util/src/frontmatter-markdown/index.ts — module re-exports
workflow-util/__tests__/frontmatter-markdown.test.ts — 45 tests

Design

Zero new dependencies (built-in YAML parser for flat schema)
Never throws — malformed input degrades to no-frontmatter
All fields T | null (no optional properties)

Ref

Refs #351

## What Add frontmatter markdown parser and validator to workflow-util. ## Why RFC #351 — agent output needs a unified format where frontmatter carries structured meta (for moderator routing) and markdown body carries content (for downstream agents). ## Changes - `workflow-util/src/frontmatter-markdown/types.ts` — AgentFrontmatter, ParsedFrontmatterMarkdown, FrontmatterValidationError types - `workflow-util/src/frontmatter-markdown/frontmatter-markdown.ts` — parseFrontmatterMarkdown() + validateFrontmatter() with built-in minimal YAML parser - `workflow-util/src/frontmatter-markdown/index.ts` — module re-exports - `workflow-util/__tests__/frontmatter-markdown.test.ts` — 45 tests ## Design - Zero new dependencies (built-in YAML parser for flat schema) - Never throws — malformed input degrades to no-frontmatter - All fields `T | null` (no optional properties) ## Ref Refs #351

xiaoju added 1 commit 2026-05-19 04:42:13 +00:00

feat(workflow-util): add frontmatter markdown parser and validator 43978360ff

Phase 1 of RFC #351 — define AgentFrontmatter type, parseFrontmatterMarkdown()
and validateFrontmatter() with 45 tests.

- Built-in minimal YAML parser (no new deps)
- Never throws on malformed input — degrades gracefully
- All fields use T | null (no optional properties)

Refs #351

xiaomo approved these changes 2026-05-19 04:56:54 +00:00

xiaomo left a comment

LGTM ✅

整体评价： 干净利落的 Phase 1 实现。

亮点：

完全遵循项目规范 — functional-first, type not interface, T | null not ?:, named exports
零新依赖，内置最小 YAML 解析器恰好覆盖 frontmatter schema 需要的子集
永不抛异常的设计贯彻到位：parser try/catch 兜底，validator 返回违规列表
45 个测试覆盖了各种边界：空输入、无 fence、中间 ---、缺闭合、空 frontmatter、非法值
FrontmatterValidationError 用 discriminated union，类型安全

一个小 nit（不阻塞合并）：

parseMinimalYaml 的 JSDoc 写 "Throws on structural errors"，但实际上它不会抛异常（遇到不可解析的行直接跳过）。建议后续顺手改一下注释。

可以合并，推 Phase 2 🚀

LGTM ✅ **整体评价：** 干净利落的 Phase 1 实现。 **亮点：** - 完全遵循项目规范 — functional-first, `type` not `interface`, `T | null` not `?:`, named exports - 零新依赖，内置最小 YAML 解析器恰好覆盖 frontmatter schema 需要的子集 - 永不抛异常的设计贯彻到位：parser try/catch 兜底，validator 返回违规列表 - 45 个测试覆盖了各种边界：空输入、无 fence、中间 ---、缺闭合、空 frontmatter、非法值 - `FrontmatterValidationError` 用 discriminated union，类型安全 **一个小 nit（不阻塞合并）：** - `parseMinimalYaml` 的 JSDoc 写 "Throws on structural errors"，但实际上它不会抛异常（遇到不可解析的行直接跳过）。建议后续顺手改一下注释。可以合并，推 Phase 2 🚀

xiaomo merged commit f174b96028 into main

2026-05-19 04:56:59 +00:00

xiaomo referenced this issue from a commit

2026-05-19 04:57:00 +00:00

Merge pull request 'feat(workflow-util): frontmatter markdown parser — RFC #351 Phase 1' (#352) from feat/351-frontmatter-markdown-phase1 into main

xiaoju referenced this issue from a commit

2026-05-19 05:46:40 +00:00

docs: fix parseMinimalYaml JSDoc (nit from #352 review)

xiaoju referenced this pull request

2026-05-19 05:46:52 +00:00

feat(workflow-util-agent): two-layer frontmatter safeguard — RFC #351 Phase 2 #353

Sign in to join this conversation.