dexin-content 0.1.1 → 0.2.0

package/cli/main.ts

@@ -0,0 +1,207 @@
+#!/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)
+}

package/cli/package.ts

@@ -0,0 +1,137 @@
+// flow/cli/package.ts
+//极薄：flowPackage — 从已编译 Artifact Store 读 → 按 manifest skeleton 组装 ContentPackage JSON
+//
+// 逻辑来源：dexinlabs-content/dexin-content/build-content-package.ts
+// （读 store、过滤 lesson domain、按 manifest 组装 lessons[] + pages[]）
+
+import { mkdir, writeFile, readFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { createFsArtifactStore } from '../core/artifact/store.js'
+import { ContentQuery } from '../core/artifact/query.js'
+import type { PositiveArtifact } from '../core/types/index.js'
+
+export interface FlowManifest {
+  courses: { slug: string; title: string; order: number }[]
+  topics: { slug: string; title: string; order: number }[]
+  chapters: { slug: string; title: string; order: number; topic_slug: string }[]
+}
+
+export interface OutLesson {
+  topic_slug: string
+  chapter_slug: string
+  slug: string
+  title: string
+  order: number
+  content: { version: number; blocks: unknown[] }
+}
+
+export interface OutPage {
+  slug: string
+  title: string
+  content: { version: number; blocks: unknown[] }
+}
+
+export interface OutPackage {
+  protocol_version: 1
+  ast_version: 1
+  manifest: FlowManifest
+  lessons: OutLesson[]
+  pages: OutPage[]
+  exercises: unknown[]
+}
+
+export interface FlowPackageInput {
+  /** Artifact Store 目录（flowBuild 的 outDir） */
+  storeDir: string
+  /** content-manifest.json 路径 */
+  manifestPath: string
+  /** ContentPackage JSON 输出路径 */
+  outFile: string
+}
+
+export async function flowPackage(input: FlowPackageInput): Promise<OutPackage> {
+  const store = createFsArtifactStore(input.storeDir)
+  const query = new ContentQuery(store)
+
+  // 1. 读 manifest skeleton
+  let manifest: FlowManifest
+  try {
+    manifest = JSON.parse(await readFile(input.manifestPath, 'utf-8'))
+  } catch (e) {
+    throw new Error(`[flowPackage] manifest 读取失败: ${(e as Error).message}`)
+  }
+
+  // 2. 读 artifact index
+  let entries
+  try {
+    entries = await query.list()
+  } catch (e) {
+    throw new Error(
+      `[flowPackage] artifact store 读取失败（是否先跑 flowBuild？）: ${(e as Error).message}`
+    )
+  }
+
+  // 3. 按 domain 分类
+  const lessonEntries = entries.filter(e => e.domain === 'lesson')
+  const docEntries = entries.filter(e => e.domain === 'document')
+
+  // 4. 组装 lessons[]
+  const manifestTopicSlugs = new Set(manifest.topics.map(t => t.slug))
+  const manifestChapterKeys = new Set(manifest.chapters.map(c => `${c.topic_slug}/${c.slug}`))
+  const lessons: OutLesson[] = []
+  const lessonsByOrder: OutLesson[] = []
+  let errors = 0
+
+  for (const entry of lessonEntries) {
+    const doc: PositiveArtifact | null = await query.byId(entry.id)
+    if (!doc) { errors++; continue }
+    if (!doc.content || doc.content.version !== 1 || !Array.isArray(doc.content.blocks)) { errors++; continue }
+
+    const { topic_slug, chapter_slug, slug } = doc.identity as {
+      topic_slug: string; chapter_slug: string; slug: string
+    }
+
+    if (!manifestTopicSlugs.has(topic_slug)) { errors++; continue }
+    if (!manifestChapterKeys.has(`${topic_slug}/${chapter_slug}`)) { errors++; continue }
+
+    const title = String((doc.meta as { title?: unknown })?.title ?? slug)
+    const order = Number((doc.meta as { order?: unknown })?.order ?? 0)
+
+    const pkgLesson: OutLesson = {
+      slug, title, topic_slug, chapter_slug, order,
+      content: { version: doc.content.version, blocks: doc.content.blocks },
+    }
+    lessons.push(pkgLesson)
+  }
+
+  // 5. 组装 pages[]
+  const pages: OutPage[] = []
+  for (const entry of docEntries) {
+    const doc = await query.byId(entry.id)
+    if (!doc) continue
+    if (!doc.content || doc.content.version !== 1 || !Array.isArray(doc.content.blocks)) continue
+    const ident = doc.identity as { slug?: string; id?: string } | undefined
+    const slug = ident?.slug ?? (ident?.id ?? entry.id).split('/').pop()!
+    const title = String((doc.meta as { title?: unknown })?.title ?? slug)
+    pages.push({ slug, title, content: { version: doc.content.version, blocks: doc.content.blocks } })
+  }
+
+  if (errors > 0) {
+    throw new Error(`[flowPackage] FAIL — ${errors} 个错误`)
+  }
+
+  // 6. 组装 + 写文件
+  const pkg: OutPackage = {
+    protocol_version: 1,
+    ast_version: 1,
+    manifest,
+    lessons,
+    pages,
+    exercises: [],
+  }
+
+  await mkdir(dirname(resolve(input.outFile)), { recursive: true })
+  await writeFile(input.outFile, JSON.stringify(pkg, null, 2) + '\n', 'utf-8')
+
+  return pkg
+}

package/cli/serve.ts

@@ -0,0 +1,135 @@
+// flow/cli/serve.ts
+//极薄：flowServe — Artifact Store 只读 dev preview server
+//
+// 设计取舍：
+//   Phase 2 第一版只做"读已编译 store → HTTP 预览"。不 watch、不 SSE。
+//   用户编辑 md → 手动跑 flow build → browser refresh。
+//   watch/SSE 在后续迭代加（需要 chokidar 依赖，极简原则）。
+//
+// 路由：
+//   GET /              — 索引页（所有已编译文档列表）
+//   GET /view/<path>   — 渲染后的 HTML
+//   GET /api/index     — JSON 索引
+//   GET /api/doc/:id   — JSON artifact
+
+import http from 'node:http'
+import { isAbsolute, resolve } from 'node:path'
+import { createFsArtifactStore } from '../core/artifact/store.js'
+import { ContentQuery } from '../core/artifact/query.js'
+import type { PositiveArtifact } from '../core/types/index.js'
+
+export interface FlowServeInput {
+  /** Artifact Store 目录 */
+  storeDir: string
+  /** HTTP 端口（默认 3714） */
+  port?: number
+}
+
+export interface FlowServeResult {
+  port: number
+  server: http.Server
+}
+
+const DESIGN_TOKENS = `
+:root {
+  --color-primary: #3b6fe0;
+  --color-text-primary: #18181b;
+  --color-text-secondary: #52525b;
+  --color-bg-primary: #fbfbfa;
+  --color-border: #e4e4e7;
+  --color-code-bg: #1c1c1f;
+  --color-code-text: #e4e4e7;
+  --font-content: "Inter", "Noto Sans SC", -apple-system, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, monospace;
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: var(--font-content); color: var(--color-text-primary); background: var(--color-bg-primary); line-height: 1.7; max-width: 800px; margin: 0 auto; padding: 2rem 1.5rem; }
+h1 { font-size: 1.875rem; font-weight: 700; margin: 1rem 0 0.5rem; }
+h2 { font-size: 1.5rem; font-weight: 700; margin: 1.5rem 0 0.5rem; }
+h3 { font-size: 1.25rem; font-weight: 600; margin: 1.25rem 0 0.5rem; }
+p { margin: 0.5rem 0; }
+blockquote { border-left: 4px solid var(--color-border); padding: 0.5rem 1rem; margin: 1rem 0; color: var(--color-text-secondary); background: #f4f4f5; border-radius: 0 0.5rem 0.5rem 0; }
+ul, ol { padding-left: 1.5rem; margin: 0.5rem 0; }
+code { font-family: var(--font-mono); font-size: 0.875em; }
+p code, li code { background: #f4f4f5; padding: 0.125rem 0.375rem; border-radius: 0.25rem; }
+pre { background: var(--color-code-bg); color: var(--color-code-text); padding: 1rem; border-radius: 0.5rem; overflow-x: auto; margin: 1rem 0; font-family: var(--font-mono); font-size: 0.875rem; }
+table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
+th, td { border: 1px solid var(--color-border); padding: 0.5rem 0.75rem; text-align: left; }
+th { background: #f4f4f5; font-weight: 600; }
+.badge { display: inline-block; font-size: 0.75rem; padding: 0.125rem 0.5rem; border-radius: 1rem; background: #f4f4f5; color: var(--color-text-secondary); margin-left: 0.5rem; }
+.nav-list { list-style: none; padding: 0; }
+.nav-list li { padding: 0.25rem 0; }
+.nav-list a { color: var(--color-primary); }
+`
+
+export async function flowServe(input: FlowServeInput): Promise<FlowServeResult> {
+  const storeDir = isAbsolute(input.storeDir) ? input.storeDir : resolve(input.storeDir)
+  const port = input.port ?? 3714
+  const store = createFsArtifactStore(storeDir)
+  const query = new ContentQuery(store)
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url ?? '/', `http://localhost:${port}`)
+    const pathname = url.pathname
+
+    try {
+      if (pathname === '/api/index') {
+        const entries = await query.list()
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ entries }, null, 2))
+        return
+      }
+
+      if (pathname.startsWith('/api/doc/')) {
+        const id = decodeURIComponent(pathname.slice('/api/doc/'.length))
+        const doc = await query.byId(id)
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify(doc, null, 2))
+        return
+      }
+
+      if (pathname === '/' || pathname === '') {
+        const entries = await query.list()
+        const items = entries
+          .map(e => `<li><a href="/view${e.path}">${escMeta(e.meta.title)}</a> <span class="badge">${e.domain}</span></li>`)
+          .join('')
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(htmlShell('Flow Dev Preview', `<h1>Dev Preview</h1><p>${entries.length} document(s)</p><ul class="nav-list">${items}</ul>`))
+        return
+      }
+
+      if (pathname.startsWith('/view/')) {
+        const docPath = decodeURIComponent(pathname.slice('/view'.length))
+        const doc = await query.byPath(docPath)
+        if (!doc) {
+          res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' })
+          res.end(htmlShell('Not Found', `<h1>404</h1><p>Document not found: ${docPath}</p>`))
+          return
+        }
+        const title = String((doc.meta as { title?: unknown })?.title ?? doc.fixture)
+        const blockCount = (doc.content as { blocks?: unknown[] } | undefined)?.blocks?.length ?? 0
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(htmlShell(title, `<h1>${title}</h1><p><span class="badge">${doc.domain}</span> ${blockCount} blocks</p><pre style="white-space:pre-wrap;">${JSON.stringify(doc.content, null, 2)}</pre>`))
+        return
+      }
+
+      res.writeHead(404, { 'Content-Type': 'text/plain' })
+      res.end('Not Found')
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' })
+      res.end(String((e as Error).message))
+    }
+  })
+
+  await new Promise<void>((resolveFn) => server.listen(port, () => resolveFn()))
+
+  return { port, server }
+}
+
+function escMeta(s: unknown): string {
+  return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function htmlShell(title: string, body: string): string {
+  return `<!DOCTYPE html><html><head><meta charset="UTF-8"><title>${title}</title><style>${DESIGN_TOKENS}</style></head><body>${body}</body></html>`
+}

package/cli/validate.ts

@@ -0,0 +1,136 @@
+// flow/cli/validate.ts
+//极薄：flowValidate — ContentPackage JSON 结构校验
+//
+// 只做 protocol_version / ast_version / manifest shape / lessons shape 检查。
+// 不做 dexinlabs Gate3 V1_EXPECTED_TOPIC_ORDER（宿主业务 gate，Flow 不管）。
+
+import { readFile } from 'node:fs/promises'
+
+export interface FlowValidateResult {
+  pass: boolean
+  errors: string[]
+  warnings: string[]
+  summary: {
+    protocol_version: number
+    ast_version: number
+    lessons: number
+    pages: number
+    topics: number
+    chapters: number
+    totalBlocks: number
+  }
+}
+
+export async function flowValidate(input: string | Buffer | object): Promise<FlowValidateResult> {
+  let pkg: any
+  let sourceLabel: string
+
+  if (typeof input === 'string') {
+    // 文件路径
+    try {
+      const text = await readFile(input, 'utf-8')
+      pkg = JSON.parse(text)
+      sourceLabel = input
+    } catch (e) {
+      return {
+        pass: false,
+        errors: [`无法读取/解析 JSON: ${(e as Error).message}`],
+        warnings: [],
+        summary: { protocol_version: 0, ast_version: 0, lessons: 0, pages: 0, topics: 0, chapters: 0, totalBlocks: 0 }
+      }
+    }
+  } else if (input && typeof input === 'object') {
+    pkg = input
+    sourceLabel = '(passed object)'
+  } else {
+    return {
+      pass: false,
+      errors: [`无效输入: 需要 JSON 文件路径或已解析对象`],
+      warnings: [],
+      summary: { protocol_version: 0, ast_version: 0, lessons: 0, pages: 0, topics: 0, chapters: 0, totalBlocks: 0 }
+    }
+  }
+
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  // 1. protocol_version
+  if (pkg.protocol_version !== 1) {
+    errors.push(`protocol_version 应为 1, 实际: ${pkg.protocol_version}`)
+  }
+
+  // 2. ast_version
+  if (pkg.ast_version !== 1) {
+    errors.push(`ast_version 应为 1, 实际: ${pkg.ast_version}`)
+  }
+
+  // 3. manifest shape
+  if (!pkg.manifest || typeof pkg.manifest !== 'object') {
+    errors.push('manifest 缺失或不是对象')
+  } else {
+    if (!Array.isArray(pkg.manifest.topics)) errors.push('manifest.topics 缺失或不是数组')
+    if (!Array.isArray(pkg.manifest.chapters)) errors.push('manifest.chapters 缺失或不是数组')
+    if (!Array.isArray(pkg.manifest.courses)) warnings.push('manifest.courses 缺失（可选）')
+  }
+
+  // 4. lessons shape
+  if (!Array.isArray(pkg.lessons)) {
+    errors.push('lessons 缺失或不是数组')
+  } else {
+    const lessons = pkg.lessons as any[]
+    for (let i = 0; i < lessons.length; i++) {
+      const l = lessons[i]
+      if (!l.slug) errors.push(`lessons[${i}].slug 缺失`)
+      if (!l.title) errors.push(`lessons[${i}].title 缺失`)
+      if (!l.topic_slug) errors.push(`lessons[${i}].topic_slug 缺失`)
+      if (!l.chapter_slug) errors.push(`lessons[${i}].chapter_slug 缺失`)
+      if (typeof l.order !== 'number') errors.push(`lessons[${i}].order 缺失或非数字`)
+      if (!l.content || l.content.version !== 1 || !Array.isArray(l.content.blocks)) {
+        errors.push(`lessons[${i}].content shape 无效`)
+      }
+    }
+  }
+
+  // 5. pages shape (optional)
+  if (pkg.pages && !Array.isArray(pkg.pages)) {
+    errors.push('pages 不是数组（应为数组或缺失）')
+  } else if (pkg.pages) {
+    for (let i = 0; i < pkg.pages.length; i++) {
+      const p = pkg.pages[i]
+      if (!p.slug) errors.push(`pages[${i}].slug 缺失`)
+      if (!p.title) errors.push(`pages[${i}].title 缺失`)
+      if (!p.content || p.content.version !== 1 || !Array.isArray(p.content.blocks)) {
+        errors.push(`pages[${i}].content shape 无效`)
+      }
+    }
+  }
+
+  // 6. exercises
+  if (!pkg.exercises) {
+    warnings.push('exercises 缺失（MVP 预期为 []）')
+  }
+
+  // Summary
+  const lessons = Array.isArray(pkg.lessons) ? pkg.lessons : []
+  const pages = Array.isArray(pkg.pages) ? pkg.pages : []
+  const manifest = pkg.manifest ?? {}
+  const topics = Array.isArray(manifest.topics) ? manifest.topics : []
+  const chapters = Array.isArray(manifest.chapters) ? manifest.chapters : []
+  const totalBlocks = lessons.reduce((n: number, l: any) => n + (l.content?.blocks?.length ?? 0), 0)
+                    + pages.reduce((n: number, p: any) => n + (p.content?.blocks?.length ?? 0), 0)
+
+  return {
+    pass: errors.length === 0,
+    errors,
+    warnings,
+    summary: {
+      protocol_version: pkg.protocol_version ?? 0,
+      ast_version: pkg.ast_version ?? 0,
+      lessons: lessons.length,
+      pages: pages.length,
+      topics: topics.length,
+      chapters: chapters.length,
+      totalBlocks,
+    }
+  }
+}