dexin-content 0.2.1 → 0.3.0

package/README.md

@@ -1,112 +1,121 @@
-# dexin-content
-
-得心实验室的**结构化内容编译与运行时 package**。
-
-负责与具体业务领域无关的通用内容管线：
-
-- **Compile**：将带 frontmatter 的 Markdown 编译成中性 Content AST，再经宿主注入的 `DomainParser` 产出稳定的 PositiveArtifact
-- **Store**：Artifact 与索引（ContentIndex）的 FS/Memory 抽象
-- **Query**：按 id / URL path / collection / 条件过滤对 Artifact 做只读查询
-- **Collection**：集合声明、发现、批量编译与增量变化检测
-- **Diff**：Canonical JSON 序列化与对象级差异原语（Golden/Regress 管线使用）
-
-## 目录范围
-
-dexin-content 是**通用层**：
-- `core/` 编译核心（types / compiler / markdown / frontmatter / discovery）
-- 根层 `collection.ts`、`store.ts`、`query.ts`、`diff.ts` 是稳定能力
-- `scripts/` 仓内脚本（不在发布包 files 内，仅供本地开发/测试；也不作为公开 API）
-
-宿主应用负责域扩展（DomainParser）、编排脚本与内容文件所有权，通过 `exports` 里的子路径消费本 package。
-
-## 安装
-
-> 需要 Node.js ≥ 20。Package 以 TypeScript 源码形式分发（`*.ts`），宿主应通过 `tsx`、Nuxt/Vite 等支持 TS 解析的工具链使用。
-
-```bash
-# Gitee 源（当前发布前）
-npm install git+https://gitee.com/cuizhn/dexin-content.git
-
-# 发布到 npm 后
-npm install dexin-content
-```
-
-## 公开 API 边界
-
-唯一公共 API 边界是 `package.json` 中 `exports` 字段。**只使用下列路径**：
-
-| 子路径 | 暴露内容 |
-|---|---|
-| `.` | 门面：核心类型 + `DomainParserRegistry` / `compile` + `ArtifactStore` / `ContentQuery` + `defineCollection / resolveCollections / discover / compileCollections` |
-| `./core/types` | 类型：`Inline` / `DocumentBlock` / `DocumentContent` / `DocumentIdentity` / `PositiveArtifact` / `Artifact` / `Meta` / `ParseError` / `DomainParser` / `Schema` / `ParseContext` |
-| `./core/compiler` | `compile`、`CompileInput`、`CompileResult`、`DomainParserRegistry` |
-| `./core/discovery` | `buildDocumentIdentity` / `normaliseRel` / `readSourceFile` / `sanitizeSourceText` / `mkLineEndingError` |
-| `./core/frontmatter` | `splitFrontmatter` / `parseFrontmatter` / `validateSchema` / `projectMeta` |
-| `./store` | `ArtifactStore` 接口 + `createFsArtifactStore` / `createMemoryArtifactStore` + `ContentIndex` / `IndexEntry` |
-| `./collection` | `defineCollection` / `resolveCollections` / `compileCollections` / `recompileChanged` / `createLocalSource` / `createMemorySource` / `SourceAdapter` / `ResolvedCollection` / `CollectionDefinition` |
-| `./query` | `ContentQuery` (byId / byPath / list / collection) + `QueryOptions` |
-| `./diff` | `toCanonicalJSON` / `sortKeysDeep` / `stripUnderscoreKeysGolden` / `underscorePrefixedPaths` / `firstDiff` / `shortStr` |
-
-任何未列入上表的内部路径均不保证稳定。
-
-## 快速示例
-
-```ts
-import {
-  defineCollection,
-  resolveCollections,
-  createLocalSource,
-  compileCollections,
-} from 'dexin-content/collection'
-import { createFsArtifactStore } from 'dexin-content/store'
-import { ContentQuery } from 'dexin-content/query'
-import { DomainParserRegistry } from 'dexin-content/core/compiler'
-import type {
-  DomainParser,
-  DocumentContent,
-  ParseContext,
-} from 'dexin-content/core/types'
-
-// 1) 注入你的域 parser；parser 决定中性 AST 如何映射到目标 Artifact 内容结构
-const documentParser: DomainParser = {
-  domain: 'document',
-  parse(content: DocumentContent, _ctx: ParseContext) {
-    return { version: 1, blocks: content.blocks as unknown[] }
-  },
-}
-const registry = new DomainParserRegistry()
-registry.register(documentParser)
-
-// 2) 声明集合 + 编译
-const collections = resolveCollections(
-  [defineCollection({ name: 'legal', source: 'legal', domain: 'document' })],
-  '/path/to/content/root',
-)
-const source = createLocalSource('/path/to/content/root')
-const store = createFsArtifactStore('/path/to/output/dexin-content')
-await compileCollections(source, collections, registry, store)
-
-// 3) 运行时只读查询（不解析任何 Markdown）
-const query = new ContentQuery(store)
-const entry = await query.byPath('/legal/privacy')
-```
-
-## 开发
-
-```bash
-# 依赖
-npm install
-
-# 类型检查（唯一静态门禁）
-npm run typecheck
-
-# 仓内自检测（需先 build 输出 output/dexin-content/）
-npm run runtime:check
-
-# 预发布 tarball 内容检查
-npm run pack
-```
-
-## License
-
-MIT © 得心实验室。详见 [LICENSE](./LICENSE)。
+# dexin-content
+
+得心实验室的**结构化内容编译与运行时 package**。
+
+负责与具体业务领域无关的通用内容管线：
+
+- **Compile**：将带 frontmatter 的 Markdown 编译成中性 Content AST，再经宿主注入的 `DomainParser` 产出稳定的 PositiveArtifact
+- **Store**：Artifact 与索引（ContentIndex）的 FS/Memory 抽象
+- **Query**：按 id / URL path / collection / 条件过滤对 Artifact 做只读查询
+- **Collection**：集合声明、发现、批量编译与增量变化检测
+- **Diff**：Canonical JSON 序列化与对象级差异原语（Golden/Regress 管线使用）
+
+## 目录范围
+
+dexin-content 是**通用层**：
+- `core/` 编译核心（types / compiler / parser / artifact）
+- `domains/lesson/` 内置 lesson 域 parser（其余域由宿主自行注入）
+- `cli/` flow 编排（build / package / validate / check / serve）
+- `scripts/` 仓内脚本（不在发布包 files 内，仅供本地开发/测试；也不作为公开 API）
+
+宿主应用负责域扩展（DomainParser）、编排脚本与内容文件所有权，通过 `exports` 里的子路径消费本 package。
+
+## 安装
+
+> 需要 Node.js ≥ 20。Package 以 TypeScript 源码形式分发（`*.ts`），宿主应通过 `tsx`、Nuxt/Vite 等支持 TS 解析的工具链使用。
+
+```bash
+# Gitee 源（当前发布前）
+npm install git+https://gitee.com/cuizhn/dexin-content.git
+
+# 发布到 npm 后
+npm install dexin-content
+```
+
+## 公开 API 边界
+
+唯一公共 API 边界是 `package.json` 中 `exports` 字段。**只使用下列路径**：
+
+| 子路径 | 暴露内容 |
+|---|---|
+| `.` | 门面：核心类型 + `DomainParserRegistry` / `compile` + `ArtifactStore` / `ContentQuery` + `defineCollection / resolveCollections / discover / compileCollections` |
+| `./core/types` | 类型：`Inline` / `DocumentBlock` / `DocumentContent` / `DocumentIdentity` / `PositiveArtifact` / `Artifact` / `Meta` / `ParseError` / `DomainParser` / `Schema` / `ParseContext` |
+| `./core/compiler` | `compile`、`CompileInput`、`CompileResult`、`DomainParserRegistry` |
+| `./core/discovery` | `buildDocumentIdentity` / `normaliseRel` / `readSourceFile` / `sanitizeSourceText` / `mkLineEndingError` |
+| `./core/frontmatter` | `splitFrontmatter` / `parseFrontmatter` / `validateSchema` / `projectMeta` |
+| `./store` | `ArtifactStore` 接口 + `createFsArtifactStore` / `createMemoryArtifactStore` + `ContentIndex` / `IndexEntry` |
+| `./collection` | `defineCollection` / `resolveCollections` / `compileCollections` / `recompileChanged` / `createLocalSource` / `createMemorySource` / `SourceAdapter` / `ResolvedCollection` / `CollectionDefinition` |
+| `./query` | `ContentQuery` (byId / byPath / list / collection) + `QueryOptions` |
+| `./diff` | `toCanonicalJSON` / `sortKeysDeep` / `stripUnderscoreKeysGolden` / `underscorePrefixedPaths` / `firstDiff` / `shortStr` |
+| `./core/markdown` | Markdown → 中性 AST 解析（`parseDocument` 等） |
+| `./core/types/lessonAST` | LessonAST 类型与常量 |
+| `./domains/lesson` | 内置 lesson 域：`lessonParser` / `buildLessonIdentity` / `mapBlocks` |
+| `./cli/build` | `flowBuild`（目录发现 → compile → Artifact Store + index.json） |
+| `./cli/package` | `flowPackage`（按 manifest 打包 ContentPackage） |
+| `./cli/validate` | `flowValidate` |
+| `./cli/check` | `flowCheck` |
+| `./cli/serve` | `flowServe`（dev preview HTTP 服务） |
+
+任何未列入上表的内部路径均不保证稳定。
+
+## 快速示例
+
+```ts
+import {
+  defineCollection,
+  resolveCollections,
+  createLocalSource,
+  compileCollections,
+} from 'dexin-content/collection'
+import { createFsArtifactStore } from 'dexin-content/store'
+import { ContentQuery } from 'dexin-content/query'
+import { DomainParserRegistry } from 'dexin-content/core/compiler'
+import type {
+  DomainParser,
+  DocumentContent,
+  ParseContext,
+} from 'dexin-content/core/types'
+
+// 1) 注入你的域 parser；parser 决定中性 AST 如何映射到目标 Artifact 内容结构
+const documentParser: DomainParser = {
+  domain: 'document',
+  parse(content: DocumentContent, _ctx: ParseContext) {
+    return { version: 1, blocks: content.blocks as unknown[] }
+  },
+}
+const registry = new DomainParserRegistry()
+registry.register(documentParser)
+
+// 2) 声明集合 + 编译
+const collections = resolveCollections(
+  [defineCollection({ name: 'legal', source: 'legal', domain: 'document' })],
+  '/path/to/content/root',
+)
+const source = createLocalSource('/path/to/content/root')
+const store = createFsArtifactStore('/path/to/artifact-store')
+await compileCollections(source, collections, registry, store)
+
+// 3) 运行时只读查询（不解析任何 Markdown）
+const query = new ContentQuery(store)
+const entry = await query.byPath('/legal/privacy')
+```
+
+## 开发
+
+```bash
+# 依赖
+npm install
+
+# 类型检查（唯一静态门禁）
+npm run typecheck
+
+# 仓内自检测（脚本自建临时 fixture，无需任何本地产物）
+npm run runtime:check
+
+# 预发布 tarball 内容检查
+npm run pack
+```
+
+## License
+
+Apache-2.0 © 得心实验室。详见 [LICENSE](./LICENSE)。

package/cli/build.ts

@@ -157,7 +157,7 @@ async function discoverAndCompileDocuments(
 }
 
 async function writeArtifact(outDir: string, artifact: PositiveArtifact): Promise<void> {
-  const outFile = path.join(outDir, 'lessons', artifact.fixture + '.json')
+  const outFile = path.join(outDir, 'content', artifact.fixture + '.json')
   await mkdir(path.dirname(outFile), { recursive: true })
   await writeFile(outFile, JSON.stringify(artifact, null, 2) + '\n', 'utf-8')
 }
@@ -183,6 +183,6 @@ async function walkMdFiles(dir: string): Promise<string[]> {
   }
   return out.sort()
 }
-
-
-
+
+
+

package/cli/main.ts

@@ -1,207 +1,197 @@
-#!/usr/bin/env tsx
-// ─────────────────────────────────────────────────────────────
-// dexin-content CLI main entry
-//
-// Modes:
-//   Single-file:  tsx cli/main.ts build <file.md> --domain lesson --out <path>
-//   Directory:    tsx cli/main.ts build <dir> --out <dir> [--manifest <path>]
-// ─────────────────────────────────────────────────────────────
-
-import { readFile, writeFile, mkdir } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { resolve, isAbsolute, dirname, basename } from 'node:path'
-
-import { DomainParserRegistry, compile } from '../core/compiler/compiler'
-import type { CompileInput } from '../core/compiler/compiler'
-import { lessonParser, buildLessonIdentity } from '../domains/lesson/index'
-import { documentParser, buildDocumentIdentity } from '../domains/document/index'
-import { flowBuild } from './build'
-import { flowPackage } from './package'
-
-type CmdArgs = Record<string, string | boolean>
-
-function parseArgs(argv: string[]): { command: string; args: CmdArgs; positionals: string[] } {
-  const command = argv[0] ?? ''
-  const positionals: string[] = []
-  const args: CmdArgs = {}
-  for (let i = 1; i < argv.length; i++) {
-    const a = argv[i]
-    if (a.startsWith('--')) {
-      const key = a.slice(2)
-      const next = argv[i + 1]
-      if (next && !next.startsWith('--')) {
-        args[key] = next; i++
-      } else {
-        args[key] = true
-      }
-    } else {
-      positionals.push(a)
-    }
-  }
-  return { command, args, positionals }
-}
-
-function printHelp() {
-  console.log(`dexin-content CLI — Independent content compilation tool
-
-Usage:
-  dexin-content <command> [options]   (npm bin; or locally: npx tsx cli/main.ts)
-
-Commands:
-  build    Compile markdown to artifacts
-  help     Show this help
-
-Build modes:
-  Single-file:
-    dexin-content build <file.md> --domain <lesson|document> --out <path>
-
-  Directory tree:
-    dexin-content build <dir> --out <dir> [--manifest <path>] [--lessons <dir>] [--documents <dir>]
-
-Options:
-  --domain <name>      Domain parser (lesson | document). Required for single-file mode.
-  --out <path>         Output path (file for single, directory for batch).
-  --manifest <path>    Content manifest JSON for packaging.
-  --lessons <dir>      Relative path to lessons directory (default: lessons).
-  --documents <dir>   Relative path to documents directory.
-`)
-}
-
-async function runSingleFile(filePath: string, domain: string, outPath?: string) {
-  const absPath = isAbsolute(filePath) ? filePath : resolve(filePath)
-  if (!existsSync(absPath)) {
-    console.error(`Error: file not found: ${absPath}`)
-    process.exit(1)
-  }
-
-  const source = await readFile(absPath, 'utf-8')
-  const relPath = basename(absPath)
-
-  const registry = new DomainParserRegistry()
-  registry.register(lessonParser)
-  registry.register(documentParser)
-
-  let identity: any
-  let fixture: string
-
-  if (domain === 'lesson') {
-    // Try to parse lesson identity from parent directories
-    const parent = dirname(absPath)
-    const grandParent = dirname(parent)
-    const topicSlug = basename(grandParent)
-    const chapterSlug = basename(parent)
-    const lessonSlug = basename(absPath).replace(/\.md$/, '')
-    fixture = `${topicSlug}/${chapterSlug}/${lessonSlug}`
-    identity = buildLessonIdentity(lessonSlug, topicSlug, chapterSlug, relPath)
-  } else if (domain === 'document') {
-    const slug = basename(absPath).replace(/\.md$/, '')
-    fixture = slug
-    identity = buildDocumentIdentity(slug, relPath)
-  } else {
-    console.error(`Error: unknown domain '${domain}'`)
-    process.exit(1)
-  }
-
-  const input: CompileInput = {
-    fixture,
-    domain,
-    identity,
-    source,
-    file: relPath
-  }
-
-  const result = compile(input, registry)
-
-  if (result.kind === 'error') {
-    const err = result.error
-    console.error(`Compile error: ${err?.code ?? 'UNKNOWN'} — ${err?.message ?? err}`)
-    process.exit(1)
-  }
-
-  const output = JSON.stringify(result.artifact, null, 2) + '\n'
-
-  if (outPath) {
-    const absOut = isAbsolute(outPath) ? outPath : resolve(outPath)
-    await mkdir(dirname(absOut), { recursive: true })
-    await writeFile(absOut, output, 'utf-8')
-    console.log(`Compiled ${fixture} → ${absOut}`)
-  } else {
-    process.stdout.write(output)
-  }
-}
-
-async function runDirectory(rootDir: string, args: CmdArgs) {
-  const root = isAbsolute(rootDir) ? rootDir : resolve(rootDir)
-  if (!existsSync(root)) {
-    console.error(`Error: directory not found: ${root}`)
-    process.exit(1)
-  }
-
-  const outDirRaw = args.out as string | undefined
-  const outDir = outDirRaw
-    ? (isAbsolute(outDirRaw) ? outDirRaw : resolve(outDirRaw))
-    : resolve(root, 'output', 'flow')
-
-  const registry = new DomainParserRegistry()
-  registry.register(lessonParser)
-  registry.register(documentParser)
-
-  const lessonResult = await flowBuild({
-    root,
-    lessonsDir: args.lessons as string | undefined,
-    documentDir: args.documents as string | undefined,
-    outDir,
-    domain: {
-      lesson: lessonParser,
-      document: documentParser,
-      buildLessonIdentity
-    }
-  })
-
-  console.log(`Build complete: ${lessonResult.compiled} artifacts in ${lessonResult.durationMs}ms`)
-
-  if (args.manifest) {
-    const manifestPath = isAbsolute(args.manifest as string)
-      ? args.manifest as string
-      : resolve(args.manifest as string)
-    const pkg = await flowPackage({
-      storeDir: outDir,
-      manifestPath,
-      outFile: resolve(outDir, 'manifest.json')
-    })
-    console.log(`Packaged manifest.json: ${pkg.lessons.length} lessons, ${pkg.pages.length} pages`)
-  }
-}
-
-// ── Main ──────────────────────────────────────────────────
-
-const { command, args, positionals } = parseArgs(process.argv.slice(2))
-
-if (command === 'help' || !command) {
-  printHelp()
-  process.exit(0)
-}
-
-if (command === 'build') {
-  const target = positionals[0]
-  if (!target) {
-    console.error('Error: missing target. Usage: build <file.md | directory>')
-    process.exit(1)
-  }
-
-  const isFile = target.endsWith('.md')
-  if (isFile) {
-    const domain = args.domain as string | undefined
-    if (!domain) {
-      console.error('Error: --domain required for single-file mode')
-      process.exit(1)
-    }
-    await runSingleFile(target, domain, args.out as string | undefined)
-  } else {
-    await runDirectory(target, args)
-  }
-} else {
-  console.error(`Unknown command: ${command}`)
-  printHelp()
-  process.exit(1)
-}
+#!/usr/bin/env tsx
+// ─────────────────────────────────────────────────────────────
+// dexin-content CLI main entry
+//
+// Modes:
+//   Single-file:  tsx cli/main.ts build <file.md> --domain lesson --out <path>
+//   Directory:    tsx cli/main.ts build <dir> --out <dir> [--manifest <path>]
+// ─────────────────────────────────────────────────────────────
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve, isAbsolute, dirname, basename } from 'node:path'
+
+import { DomainParserRegistry, compile } from '../core/compiler/compiler'
+import type { CompileInput } from '../core/compiler/compiler'
+import { lessonParser, buildLessonIdentity } from '../domains/lesson/index'
+import { flowBuild } from './build'
+import { flowPackage } from './package'
+
+type CmdArgs = Record<string, string | boolean>
+
+function parseArgs(argv: string[]): { command: string; args: CmdArgs; positionals: string[] } {
+  const command = argv[0] ?? ''
+  const positionals: string[] = []
+  const args: CmdArgs = {}
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next && !next.startsWith('--')) {
+        args[key] = next; i++
+      } else {
+        args[key] = true
+      }
+    } else {
+      positionals.push(a)
+    }
+  }
+  return { command, args, positionals }
+}
+
+function printHelp() {
+  console.log(`dexin-content CLI — Independent content compilation tool
+
+Usage:
+  dexin-content <command> [options]   (npm bin; or locally: npx tsx cli/main.ts)
+
+Commands:
+  build    Compile markdown to artifacts
+  help     Show this help
+
+Build modes:
+  Single-file:
+    dexin-content build <file.md> --domain lesson --out <path>
+
+  Directory tree:
+    dexin-content build <dir> --out <dir> [--manifest <path>] [--lessons <dir>]
+
+Options:
+  --domain <name>      Domain parser (lesson). Required for single-file mode.
+  --out <path>         Output path (file for single, directory for batch).
+  --manifest <path>    Content manifest JSON for packaging.
+  --lessons <dir>      Relative path to lessons directory (default: lessons).
+`)
+}
+
+async function runSingleFile(filePath: string, domain: string, outPath?: string) {
+  const absPath = isAbsolute(filePath) ? filePath : resolve(filePath)
+  if (!existsSync(absPath)) {
+    console.error(`Error: file not found: ${absPath}`)
+    process.exit(1)
+  }
+
+  const source = await readFile(absPath, 'utf-8')
+  const relPath = basename(absPath)
+
+  const registry = new DomainParserRegistry()
+  registry.register(lessonParser)
+
+  let identity: any
+  let fixture: string
+
+  if (domain === 'lesson') {
+    // Try to parse lesson identity from parent directories
+    const parent = dirname(absPath)
+    const grandParent = dirname(parent)
+    const topicSlug = basename(grandParent)
+    const chapterSlug = basename(parent)
+    const lessonSlug = basename(absPath).replace(/\.md$/, '')
+    fixture = `${topicSlug}/${chapterSlug}/${lessonSlug}`
+    identity = buildLessonIdentity(lessonSlug, topicSlug, chapterSlug, relPath)
+  } else {
+    console.error(`Error: unknown domain '${domain}'`)
+    process.exit(1)
+  }
+
+  const input: CompileInput = {
+    fixture,
+    domain,
+    identity,
+    source,
+    file: relPath
+  }
+
+  const result = compile(input, registry)
+
+  if (result.kind === 'error') {
+    const err = result.error
+    console.error(`Compile error: ${err?.code ?? 'UNKNOWN'} — ${err?.message ?? err}`)
+    process.exit(1)
+  }
+
+  const output = JSON.stringify(result.artifact, null, 2) + '\n'
+
+  if (outPath) {
+    const absOut = isAbsolute(outPath) ? outPath : resolve(outPath)
+    await mkdir(dirname(absOut), { recursive: true })
+    await writeFile(absOut, output, 'utf-8')
+    console.log(`Compiled ${fixture} → ${absOut}`)
+  } else {
+    process.stdout.write(output)
+  }
+}
+
+async function runDirectory(rootDir: string, args: CmdArgs) {
+  const root = isAbsolute(rootDir) ? rootDir : resolve(rootDir)
+  if (!existsSync(root)) {
+    console.error(`Error: directory not found: ${root}`)
+    process.exit(1)
+  }
+
+  const outDirRaw = args.out as string | undefined
+  const outDir = outDirRaw
+    ? (isAbsolute(outDirRaw) ? outDirRaw : resolve(outDirRaw))
+    : resolve(root, 'output', 'flow')
+
+  const registry = new DomainParserRegistry()
+  registry.register(lessonParser)
+
+  const lessonResult = await flowBuild({
+    root,
+    lessonsDir: args.lessons as string | undefined,
+    outDir,
+    domain: {
+      lesson: lessonParser,
+      buildLessonIdentity
+    }
+  })
+
+  console.log(`Build complete: ${lessonResult.compiled} artifacts in ${lessonResult.durationMs}ms`)
+
+  if (args.manifest) {
+    const manifestPath = isAbsolute(args.manifest as string)
+      ? args.manifest as string
+      : resolve(args.manifest as string)
+    const pkg = await flowPackage({
+      storeDir: outDir,
+      manifestPath,
+      outFile: resolve(outDir, 'manifest.json')
+    })
+    console.log(`Packaged manifest.json: ${pkg.lessons.length} lessons, ${pkg.pages.length} pages`)
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────
+
+const { command, args, positionals } = parseArgs(process.argv.slice(2))
+
+if (command === 'help' || !command) {
+  printHelp()
+  process.exit(0)
+}
+
+if (command === 'build') {
+  const target = positionals[0]
+  if (!target) {
+    console.error('Error: missing target. Usage: build <file.md | directory>')
+    process.exit(1)
+  }
+
+  const isFile = target.endsWith('.md')
+  if (isFile) {
+    const domain = args.domain as string | undefined
+    if (!domain) {
+      console.error('Error: --domain required for single-file mode')
+      process.exit(1)
+    }
+    await runSingleFile(target, domain, args.out as string | undefined)
+  } else {
+    await runDirectory(target, args)
+  }
+} else {
+  console.error(`Unknown command: ${command}`)
+  printHelp()
+  process.exit(1)
+}

package/core/artifact/store.ts

@@ -73,7 +73,7 @@ const defaultFsOps: FsOps = {
 
 /**
  * File-system Artifact Store.
- * Layout: <baseDir>/index.json + <baseDir>/lessons/<id>.json
+ * Layout: <baseDir>/index.json + <baseDir>/content/<id>.json
  * Docs are serialised via toCanonicalJSON (2-space, key-lexicographic,
  * LF, trailing newline) to match golden candidate form.
  */
@@ -82,7 +82,7 @@ export function createFsArtifactStore (
   fsOps: FsOps = defaultFsOps
 ): ArtifactStore {
   const idxPath = () => `${baseDir}/index.json`
-  const docPath = (id: string) => `${baseDir}/lessons/${id}.json`
+  const docPath = (id: string) => `${baseDir}/content/${id}.json`
 
   return {
     async writeIndex (index) {

package/index.ts

@@ -1,61 +1,57 @@
-// dexin-content — Universal content compilation layer
-// Re-exports core types and interfaces for host consumption.
-// Domain parsers are injected by the host via DomainParserRegistry.
-
-export type {
-  DomainName, DocumentIdentity, Schema, Artifact, ParseError,
-  DomainParser, ParseContext,
-  Meta, Identity, StructuredIdentity, TEX_INLINE_TYPE
-} from './core/types/index'
-
-// LessonAST 类型
-export type {
-  LessonContent, Block, BlockType,
-  ParagraphBlock, HeadingBlock, QuoteBlock, HintBlock,
-  DefinitionBlock, ExampleBlock, QuestionBlock,
-  ImageBlock, CodeBlock, FormulaBlock, ListBlock,
-  TableBlock, TableCell, SectionBlock, DividerBlock,
-  ContainerBlock, ExerciseContent,
-  Inline, TextInline, BoldInline, ItalicInline,
-  CodeInline, LinkInline, FormulaInline, MathInline,
-  BaseBlock
-} from './core/types/lessonAST'
-
-export {
-  BLOCK_TYPES, HINT_LEVELS, HEADING_LEVELS
-} from './core/types/lessonAST'
-
-export { DomainParserRegistry, compile } from './core/compiler/compiler'
-export type { CompileInput, CompileResult } from './core/compiler/compiler'
-export { normaliseRel, buildDocumentIdentity as buildDocPageIdentity, readSourceFile } from './core/compiler/discovery'
-export { splitFrontmatter, parseFrontmatter, validateSchema } from './core/parser/frontmatter'
-export { parseDocument } from './core/parser/markdown'
-
-export type { ArtifactStore, ContentIndex, IndexEntry } from './core/artifact/store'
-export { createFsArtifactStore, createMemoryArtifactStore } from './core/artifact/store'
-
-export type { CollectionDefinition, SourceAdapter, ResolvedCollection } from './core/artifact/collection'
-export { defineCollection, resolveCollections, discover, compileCollections } from './core/artifact/collection'
-
-export type { ContentQuery as ContentQueryType } from './core/artifact/query'
-export { ContentQuery } from './core/artifact/query'
-
-export { toCanonicalJSON, firstDiff, sortKeysDeep, stripUnderscoreKeysGolden } from './core/artifact/diff'
-
-// Lesson domain
-export { lessonParser } from './domains/lesson/parser'
-export { buildLessonIdentity } from './domains/lesson/identity'
-export { mapBlocks, lessonError, KNOWN_CONTAINERS } from './domains/lesson/blocks'
-
-// Document domain
-export { documentParser } from './domains/document/parser'
-export { buildDocumentIdentity as buildDocumentPageIdentity } from './domains/document/identity'
-
-// CLI
-export type { FlowBuildInput, FlowBuildResult } from './cli/build'
-export { flowBuild } from './cli/build'
-export type { FlowManifest, OutLesson, OutPage, OutPackage } from './cli/package'
-export { flowPackage } from './cli/package'
-export { flowValidate } from './cli/validate'
-export { flowCheck } from './cli/check'
-export { flowServe } from './cli/serve'
+// dexin-content — Universal content compilation layer
+// Re-exports core types and interfaces for host consumption.
+// Domain parsers are injected by the host via DomainParserRegistry.
+
+export type {
+  DomainName, DocumentIdentity, Schema, Artifact, ParseError,
+  DomainParser, ParseContext,
+  Meta, Identity, StructuredIdentity, TEX_INLINE_TYPE
+} from './core/types/index'
+
+// LessonAST 类型
+export type {
+  LessonContent, Block, BlockType,
+  ParagraphBlock, HeadingBlock, QuoteBlock, HintBlock,
+  DefinitionBlock, ExampleBlock, QuestionBlock,
+  ImageBlock, CodeBlock, FormulaBlock, ListBlock,
+  TableBlock, TableCell, SectionBlock, DividerBlock,
+  ContainerBlock, ExerciseContent,
+  Inline, TextInline, BoldInline, ItalicInline,
+  CodeInline, LinkInline, FormulaInline, MathInline,
+  BaseBlock
+} from './core/types/lessonAST'
+
+export {
+  BLOCK_TYPES, HINT_LEVELS, HEADING_LEVELS
+} from './core/types/lessonAST'
+
+export { DomainParserRegistry, compile } from './core/compiler/compiler'
+export type { CompileInput, CompileResult } from './core/compiler/compiler'
+export { normaliseRel, buildDocumentIdentity as buildDocPageIdentity, readSourceFile } from './core/compiler/discovery'
+export { splitFrontmatter, parseFrontmatter, validateSchema } from './core/parser/frontmatter'
+export { parseDocument } from './core/parser/markdown'
+
+export type { ArtifactStore, ContentIndex, IndexEntry } from './core/artifact/store'
+export { createFsArtifactStore, createMemoryArtifactStore } from './core/artifact/store'
+
+export type { CollectionDefinition, SourceAdapter, ResolvedCollection } from './core/artifact/collection'
+export { defineCollection, resolveCollections, discover, compileCollections } from './core/artifact/collection'
+
+export type { ContentQuery as ContentQueryType } from './core/artifact/query'
+export { ContentQuery } from './core/artifact/query'
+
+export { toCanonicalJSON, firstDiff, sortKeysDeep, stripUnderscoreKeysGolden } from './core/artifact/diff'
+
+// Lesson domain
+export { lessonParser } from './domains/lesson/parser'
+export { buildLessonIdentity } from './domains/lesson/identity'
+export { mapBlocks, lessonError, KNOWN_CONTAINERS } from './domains/lesson/blocks'
+
+// CLI
+export type { FlowBuildInput, FlowBuildResult } from './cli/build'
+export { flowBuild } from './cli/build'
+export type { FlowManifest, OutLesson, OutPage, OutPackage } from './cli/package'
+export { flowPackage } from './cli/package'
+export { flowValidate } from './cli/validate'
+export { flowCheck } from './cli/check'
+export { flowServe } from './cli/serve'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexin-content",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Open content toolchain — Markdown → LessonAST/ContentPackage compiler, CLI and validator (dexinlabs ecosystem).",
   "keywords": [
     "markdown",
@@ -53,8 +53,7 @@
     "./cli/check": "./cli/check.ts",
     "./core/discovery": "./core/compiler/discovery.ts",
     "./core/types/lessonAST": "./core/types/lessonAST.ts",
-    "./domains/lesson": "./domains/lesson/index.ts",
-    "./domains/document": "./domains/document/index.ts"
+    "./domains/lesson": "./domains/lesson/index.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/core/validator/integrity.ts

@@ -1,199 +0,0 @@
-// ─────────────────────────────────────────────────────────────
-// dexin-content/runtime-check.ts — Runtime flow (B1-SPEC T5.3 / ARCH-REPORT §8)
-//
-// Reads pre-compiled artifacts from output/dexin-content/ via ContentQuery.
-// Asserts structural correctness of the read-back artifacts.
-//
-// ZERO MARKDOWN PARSING PROOF (B1-SPEC T5.3):
-//   This module imports ONLY from:
-//     - ./store        (fs/memory store + ContentIndex types; markdown-free)
-//     - ./query        (ContentQuery; markdown-free)
-//     - ./core/types   (type-only imports, erased at compile time)
-//     - node:*         (built-in modules)
-//   It does NOT import: markdown, remark, unified, core/compiler,
-//   core/frontmatter, core/markdown, domain/*, collection (which
-//   transitively imports the compiler). The runtime path reads
-//   pre-compiled artifacts from output/ and never reparses source.
-//
-//   Transitive dependency audit:
-//     store.ts  → node:fs/promises, node:path, ./core/types (types), ./diff
-//     query.ts  → ./core/types (types), ./store
-//     diff.ts   → (zero imports — pure JSON/Object operations)
-//   No markdown/remark/unified anywhere in the runtime import graph.
-//
-// grep-zero: no business vocabulary appears anywhere in this
-// module — including error messages.
-// ─────────────────────────────────────────────────────────────
-
-import { fileURLToPath } from 'node:url'
-import { join } from 'node:path'
-
-import type { PositiveArtifact } from '../types'
-import { createFsArtifactStore, createMemoryArtifactStore, type ArtifactStore } from '../artifact/store'
-import { ContentQuery } from '../artifact/query'
-
-const __filename = fileURLToPath(import.meta.url)
-const ROOT = join(__filename, '..', '..')
-const OUTPUT_DIR = join(ROOT, 'output', 'dexin-content')
-
-// ── Helpers ──────────────────────────────────────────────
-
-let pass = 0
-let fail = 0
-const errors: string[] = []
-
-function ok (label: string): void {
-  pass++
-  console.log(`  ✅ ${label}`)
-}
-
-function ko (label: string, detail: string): void {
-  fail++
-  errors.push(`${label}: ${detail}`)
-  console.log(`  ❌ ${label}: ${detail}`)
-}
-
-function assertArtifact (label: string, doc: PositiveArtifact | null, expectDomain: string, expectId: string): void {
-  if (doc === null) { ko(label, 'returned null'); return }
-  if (doc.domain !== expectDomain) { ko(label, `domain=${doc.domain} (expected ${expectDomain})`); return }
-  if (doc.fixture !== expectId) { ko(label, `fixture=${doc.fixture} (expected ${expectId})`); return }
-  if (!doc.content?.blocks?.length) { ko(label, 'content.blocks empty or missing'); return }
-  if (!doc.identity) { ko(label, 'identity missing'); return }
-  if (!doc.meta) { ko(label, 'meta missing'); return }
-  ok(label)
-}
-
-// ── R1: byPath on legal/privacy + about ───────────────────
-
-async function checkR1 (query: ContentQuery): Promise<void> {
-  console.log('── R1: query.byPath ──')
-  const privacy = await query.byPath('/legal/privacy')
-  assertArtifact('R1 byPath(/legal/privacy)', privacy, 'document', 'legal/privacy')
-
-  const about = await query.byPath('/about')
-  assertArtifact('R1 byPath(/about)', about, 'document', 'about')
-
-  const notFound = await query.byPath('/nonexistent')
-  if (notFound !== null) ko('R1 byPath(/nonexistent)', 'should be null')
-  else ok('R1 byPath(/nonexistent) → null')
-}
-
-// ── R2: byId ─────────────────────────────────────────────
-
-async function checkR2 (query: ContentQuery): Promise<void> {
-  console.log('── R2: query.byId ──')
-  const byIdPrivacy = await query.byId('legal/privacy')
-  assertArtifact('R2 byId(legal/privacy)', byIdPrivacy, 'document', 'legal/privacy')
-
-  const byIdAbout = await query.byId('about')
-  assertArtifact('R2 byId(about)', byIdAbout, 'document', 'about')
-
-  const byIdMissing = await query.byId('does/not/exist')
-  if (byIdMissing !== null) ko('R2 byId(missing)', 'should be null')
-  else ok('R2 byId(missing) → null')
-}
-
-// ── R3: collection ───────────────────────────────────────
-
-async function checkR3 (query: ContentQuery): Promise<void> {
-  console.log('── R3: query.collection ──')
-  const legal = await query.collection('legal')
-  if (legal.length !== 1) ko('R3 collection(legal)', `len=${legal.length}`)
-  else if (legal[0].id !== 'legal/privacy') ko('R3 collection(legal)', `id=${legal[0].id}`)
-  else ok('R3 collection(legal) → 1 entry (legal/privacy)')
-
-  const about = await query.collection('about')
-  if (about.length !== 1) ko('R3 collection(about)', `len=${about.length}`)
-  else if (about[0].id !== 'about') ko('R3 collection(about)', `id=${about[0].id}`)
-  else ok('R3 collection(about) → 1 entry (about)')
-}
-
-// ── R4: list with where/sort/limit ───────────────────────
-
-async function checkR4 (query: ContentQuery): Promise<void> {
-  console.log('── R4: query.list ──')
-  const all = await query.list()
-  if (all.length !== 2) ko('R4 list()', `len=${all.length}`)
-  else ok('R4 list() → 2 entries')
-
-  const legalOnly = await query.list('legal')
-  if (legalOnly.length !== 1) ko('R4 list(legal)', `len=${legalOnly.length}`)
-  else ok('R4 list(legal) → 1 entry')
-
-  const sorted = await query.list(undefined, { sort: (a, b) => a.id.localeCompare(b.id) })
-  if (sorted.length !== 2) ko('R4 list(sort)', `len=${sorted.length}`)
-  else ok('R4 list(sort) → 2 sorted')
-
-  const limited = await query.list(undefined, { limit: 1 })
-  if (limited.length !== 1) ko('R4 list(limit=1)', `len=${limited.length}`)
-  else ok('R4 list(limit=1) → 1 entry')
-
-  const filtered = await query.list(undefined, { where: e => e.collection === 'legal' })
-  if (filtered.length !== 1) ko('R4 list(where=legal)', `len=${filtered.length}`)
-  else ok('R4 list(where=legal) → 1 entry')
-}
-
-// ── R5: no-index → throw (zero-parse invariant) ─────────
-
-async function checkR5 (): Promise<void> {
-  console.log('── R5: no-index → throw (zero-parse invariant) ──')
-  const emptyStore = createMemoryArtifactStore()
-  const query = new ContentQuery(emptyStore)
-  try {
-    await query.byPath('/legal/privacy')
-    ko('R5 byPath no-index', 'should have thrown')
-  } catch (e) {
-    const msg = (e as Error).message
-    if (msg.includes('No index')) ok('R5 byPath no-index → throws')
-    else ko('R5 byPath no-index', `wrong message: ${msg}`)
-  }
-  try {
-    await query.list()
-    ko('R5 list no-index', 'should have thrown')
-  } catch (e) {
-    const msg = (e as Error).message
-    if (msg.includes('No index')) ok('R5 list no-index → throws')
-    else ko('R5 list no-index', `wrong message: ${msg}`)
-  }
-}
-
-// ── R6: deep-equal byPath vs byId (store round-trip) ────
-
-async function checkR6 (query: ContentQuery): Promise<void> {
-  console.log('── R6: byPath vs byId deep-equal (round-trip) ──')
-  const byPath = await query.byPath('/legal/privacy')
-  const byId = await query.byId('legal/privacy')
-  if (byPath === null || byId === null) { ko('R6 deep-equal', 'one or both null'); return }
-  if (byPath.fixture !== byId.fixture) { ko('R6 deep-equal', 'fixture mismatch'); return }
-  if (byPath.domain !== byId.domain) { ko('R6 deep-equal', 'domain mismatch'); return }
-  if (byPath.content.blocks.length !== byId.content.blocks.length) { ko('R6 deep-equal', 'blocks length mismatch'); return }
-  ok('R6 byPath(/legal/privacy) deep-equal byId(legal/privacy)')
-}
-
-// ── Main ─────────────────────────────────────────────────
-
-async function main (): Promise<void> {
-  console.log('── runtime:check ──')
-  console.log(`  output dir: ${OUTPUT_DIR}`)
-
-  const store: ArtifactStore = createFsArtifactStore(OUTPUT_DIR)
-  const query = new ContentQuery(store)
-
-  await checkR1(query)
-  await checkR2(query)
-  await checkR3(query)
-  await checkR4(query)
-  await checkR5()
-  await checkR6(query)
-
-  console.log(`\n──────── runtime:check summary ────────`)
-  console.log(`${pass} pass, ${fail} fail`)
-  if (fail > 0) {
-    console.log('\nFailures:')
-    for (const e of errors) console.log(`  - ${e}`)
-    process.exit(1)
-  }
-  process.exit(0)
-}
-
-void main()

package/domains/document/identity.ts

@@ -1,27 +0,0 @@
-/**
- * DocumentIdentity — dexinlabs-specific identity builder for document content.
- *
- * Maps page slugs to DocumentIdentity shape with collection='pages'.
- *
- * This keeps dexin-content generic while allowing dexinlabs to maintain
- * its document/page organization.
- */
-import type { DocumentIdentity } from '../../core/types/index'
-
-/**
- * Build a DocumentIdentity for a page file.
- *
- * @param slug - Page identifier (e.g., 'about', 'privacy')
- * @param relPath - Relative path from content root (e.g., 'pages/about.md')
- */
-export function buildDocumentIdentity(
-  slug: string,
-  relPath: string
-): DocumentIdentity {
-  return {
-    id: slug,
-    path: `/${slug}`,
-    file: relPath,
-    collection: 'pages'
-  }
-}

package/domains/document/index.ts

@@ -1,5 +0,0 @@
-/**
- * document-domain barrel
- */
-export { documentParser } from './parser'
-export { buildDocumentIdentity } from './identity'

package/domains/document/parser.ts

@@ -1,105 +0,0 @@
-// ─────────────────────────────────────────────────────────────
-// domains/document/parser.ts
-//
-// Document domain parser. Identity behaviour defined in §6.3.15 frozen.
-//
-// Content behaviour:
-//   * Heading = straight docAST heading (h1→1, h2→2, h3→3, h4→4; no
-//     absorption, no downgrade).
-//   * md h5/h6 → DOC_HEADING_DEPTH_UNDEFINED (6.3.10 frozen: ERROR)。
-//   * No section grouping (6.3.11 frozen).
-//   * ContainerBlock (6.3.12) stays neutral (never re-mapped to domain blocks).
-//   * Plain blocks pass through unchanged from DocumentAST.
-//   * `mdDepth` 属 transient 辅助注解：clone/render 路径显式剔除。
-// ─────────────────────────────────────────────────────────────
-
-import type {
-  DomainParser,
-  ParseContext,
-  ParseError
-} from '../../core/types/index'
-import type { LessonContent, Block, HeadingBlock } from '../../core/types/lessonAST'
-
-export const documentParser: DomainParser = {
-  domain: 'document',
-  parse (content: LessonContent, ctx: ParseContext): LessonContent {
-    // Pre-pass: document-domain heading depth fail-fast (6.3.10).
-    walkAndEnforceHeadingDepth(content.blocks, ctx)
-
-    // Deep-copy structural nodes so future mutations to docAST do not leak.
-    return { version: 1, blocks: cloneBlocks(content.blocks) }
-  }
-}
-
-function walkAndEnforceHeadingDepth (blocks: Block[], ctx: ParseContext): void {
-  for (const b of blocks) {
-    if (b.type === 'heading') {
-      const mdDepth = (b as HeadingBlock).mdDepth ?? b.level
-      if (mdDepth > 4) {
-        const err = new Error(
-          `[DOC_HEADING_DEPTH_UNDEFINED] Document domain only supports h1–h4. ` +
-          `Encountered h${mdDepth} (heading level ${mdDepth}): no mapping defined per 6.3.10 frozen table. ` +
-          `Allowed heading markdown depths: 1–4. Silently capping to level 4 is forbidden (information loss). ` +
-          `file: ${ctx.file}`
-        ) as ParseError & Error
-        err.code = 'DOC_HEADING_DEPTH_UNDEFINED'
-        err.file = ctx.file
-        err.loc = { headingDepth: mdDepth, allowed: 'h1-h4' }
-        throw err
-      }
-    }
-    if (b.type === 'quote') walkAndEnforceHeadingDepth(b.children, ctx)
-    if (b.type === 'container') walkAndEnforceHeadingDepth(b.children, ctx)
-  }
-}
-
-function cloneBlocks (xs: Block[]): Block[] {
-  return xs.map(b => {
-    switch (b.type) {
-      case 'paragraph': return { type:'paragraph', children: cloneInlineArr(b.children) }
-      case 'heading': {
-        // Drop transient mdDepth — canonical output never contains it.
-        return { type:'heading', level: b.level, children: cloneInlineArr(b.children) }
-      }
-      case 'quote':     return { type:'quote',     children: cloneBlocks(b.children) }
-      case 'divider':   return { type:'divider' }
-      case 'list':      return {
-        type:'list', ordered: b.ordered,
-        items: b.items.map(row => row.map(cloneInline))
-      }
-      case 'table':     return {
-        type:'table',
-        headers: b.headers.map(c => c.map(cloneInline)),
-        rows:    b.rows.map(r => r.map(c => c.map(cloneInline)))
-      }
-      case 'image':     return { type:'image', src:b.src, alt:b.alt, caption:b.caption }
-      case 'code':      return { type:'code',  language: b.language, code: b.code }
-      case 'formula':   return { type:'formula', latex: b.latex, display: b.display }
-      case 'container': return {
-        type:'container',
-        name: b.name,
-        attrs: { ...b.attrs },
-        children: cloneBlocks(b.children)
-      }
-      default:
-        // hint/definition/example/question/section — domain-specific, not expected here
-        return b
-    }
-  })
-}
-
-function cloneInlineArr (xs: any[]): any[] {
-  return xs.map(cloneInline)
-}
-
-function cloneInline (i: any): any {
-  switch (i.type) {
-    case 'text':   return { type:'text', value: i.value }
-    case 'code':   return { type:'code', value: i.value }
-    case 'math':   return { type:'math', latex: i.latex }
-    case 'bold':   return { type:'bold', children: cloneInlineArr(i.children) }
-    case 'italic': return { type:'italic', children: cloneInlineArr(i.children) }
-    case 'link':   return { type:'link', url: i.url, children: cloneInlineArr(i.children) }
-    default:        return { ...i }
-  }
-}