Merge remote-tracking branch 'origin/master' into worktree/provider-routed-llm-adapters

# Conflicts: # docs/config-catalog.md # packages/examples/acp-demo/tests/acp-agent.spec.ts # packages/examples/stdio-demo/README.md # packages/examples/stdio-demo/src/index.ts # packages/examples/stdio-demo/tests/stdio-agent.spec.ts
2026-07-15 20:14:09 +08:00
parent d24e212f96 5ee9217146
commit f47a87fcf5
138 changed files with 613 additions and 530 deletions
@@ -0,0 +1,202 @@
+import { describe, expect, it } from 'vitest'
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
+import * as agentCore from '../src/index.ts'
+import { AgentId, agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import type { Message } from '@deepseek-ai/dsh-llm'
+
+async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
+  const agent = { session: { header: { cwd } } } as unknown as Agent
+  const empty: Message[] = []
+  return await agentEvents(ctx, agent).waterfall(
+    'agent/session-prefix', empty, new AbortController().signal,
+    () => Promise.resolve(empty),
+  )
+}
+
+/**
+ * Unit coverage for the @deepseek-ai/dsh-agent-spine-demo bundle: mounting it brings
+ * up the whole default spine in one `ctx.plugin`, and the forwarded
+ * `agents` config reaches the loop (default `[]`, or a pre-created agent).
+ *
+ * The bundle is exercised through `ctx.plugin(agentCore, …)` — the NAMESPACE
+ * import, the same shape the Loader builds from `unwrapExports`. The real
+ * Loader-path guard (export shape, `unwrapExports`) is the app packages' keyless
+ * bin smokes; here we assert the composition + config forwarding.
+ */
+async function mount(config?: agentCore.Config): Promise<Context> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-agents-'))
+  const ctx = new Context()
+  try {
+    await ctx.plugin(agentCore, config)
+    // The bundle mounts its children inside apply() (not awaited there); let their
+    // fibers settle so the spine services and any pre-created agent are ready.
+    await new Promise(resolve => setTimeout(resolve, 50))
+    return ctx
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
+async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-agents-'))
+  try {
+    return await run()
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
+describe('dsh-agent-spine-demo bundle', () => {
+  it('brings up the full default spine', async () => {
+    const ctx = await mount()
+    // One service from each layer of the spine proves the children loaded.
+    expect(ctx.get('timer')).toBeDefined()
+    expect(ctx.get('llm')).toBeDefined()
+    expect(ctx.get('sessions')).toBeDefined()
+    expect(ctx.get('systemPrompt')).toBeDefined()
+    expect(ctx.get('tools')).toBeDefined()
+    expect(ctx.get('skills')).toBeDefined()
+    expect(ctx.get('agents')).toBeDefined()
+    expect(ctx.get('agentLoop')).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('includes the skill registry, local provider, and skill tool without builtin skills', async () => {
+    const ctx = await mount()
+
+    expect(ctx.skills).toBeDefined()
+    expect(ctx.tools.schemas().map(tool => tool.name)).toContain('skill')
+    expect(await ctx.skills.list()).toEqual([])
+
+    await ctx.fiber.dispose()
+  })
+
+  it('defaults the agents list to empty (no pre-created agents)', async () => {
+    const ctx = await mount()
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('forwards a pre-created agent to the loop and the persona to system-prompt', async () => {
+    const ctx = await mount({
+      agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock' }],
+      persona: 'You are main.',
+    })
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    const assembly = await ctx.get('systemPrompt')!.assemble()
+    expect(assembly.sections.find(s => s.name === 'deployment:persona')?.text).toBe('You are main.')
+    await ctx.fiber.dispose()
+  })
+
+  it('tolerates a schema-bypassing direct apply (the ?? fallbacks fire)', async () => {
+    // ctx.plugin validates + defaults the bundle config first; a direct apply
+    // skips the schema, so the forwarding `?? []` / `?? ''` are what fire.
+    const ctx = new Context()
+    agentCore.apply(ctx, {})
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(ctx.get('agentLoop')).toBeDefined()
+    expect(ctx.get('agents')?.list()).toHaveLength(0)
+    const assembly = await ctx.get('systemPrompt')!.assemble()
+    expect(assembly.sections.find(s => s.name === 'deployment:persona')?.text).toBe('')
+    await ctx.fiber.dispose()
+  })
+
+  it('forwards skill config to the registry, local provider, and model-facing consumer', async () => {
+    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-home-'))
+    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-agents-'))
+    const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-custom-'))
+    await mkdir(custom, { recursive: true })
+    await writeFile(join(custom, 'custom-skill.md'), '---\nname: custom-skill\ndescription: Custom skill\n---\n\nCustom body.\n')
+    const ctx = await mount({
+      agents: [],
+      skills: {
+        registry: { collectCacheMaxEntries: 4 },
+        local: {
+          dshHome: join(home, '.dsh'),
+          agentsHome: join(agentsHome, '.agents'),
+          customSkillDirs: [custom],
+        },
+        tool: { catalogDescriptionMaxLength: 6 },
+      },
+    })
+    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['custom-skill'])
+    expect(JSON.stringify(await composePrefix(ctx, '/tmp'))).toContain('- `custom-skill`: Cus...')
+    await ctx.fiber.dispose()
+  })
+
+  it('uses the default skill config when apply is called directly without skills', async () => {
+    await withIsolatedSkillHomes(async () => {
+      const ctx = new Context()
+      agentCore.apply(ctx, { agents: [] })
+      await new Promise(resolve => setTimeout(resolve, 50))
+      expect(ctx.skills).toBeDefined()
+      expect(await ctx.skills.list()).toEqual([])
+      await ctx.fiber.dispose()
+    })
+  })
+
+  it('forwards toolOrder to the system-prompt assembly', async () => {
+    const ctx = await mount({ toolOrder: ['zulu', TOOL_ORDER_REST] })
+    // The bundle's own bash tools pend on the absent `ctx.bash` executor in
+    // this providerless mount, so register two plain tools to order.
+    for (const name of ['alpha', 'zulu']) {
+      ctx.get('tools')!.register({
+        name,
+        description: name,
+        parameters: {},
+        execute: async () => [],
+      })
+    }
+    const assembly = await ctx.get('systemPrompt')!.assemble()
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill'])
+    await ctx.fiber.dispose()
+  })
+
+  it('re-exports the loop config schema as its own', () => {
+    expect(agentCore.Config).toBeDefined()
+    expect(agentCore.name).toBe('agent-spine-demo')
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
+    // A default export would make `unwrapExports` collapse this inject-less namespace and silently
+    // drop `name`/`Config`. Apps import the bundle directly, so this is its Loader-shape guard.
+    expect('default' in agentCore).toBe(false)
+    expect(typeof agentCore.apply).toBe('function')
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(agentCore) as Record<string, unknown>
+    expect(unwrapped).toBe(agentCore)
+    expect(unwrapped.name).toBe('agent-spine-demo')
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})
@@ -0,0 +1,445 @@
+/**
+ * Negative-path tests for the config catalog generator (`scripts/gen-config-catalog.ts`).
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectConfigCatalog, render } from '../../../../scripts/gen-config-catalog.ts'
+
+/** Write one fixture package (package.json + src files) under a scan root. */
+function writePkg(root: string, dir: string, name: string, files: Record<string, string>): void {
+  const pkgDir = join(root, 'packages', dir)
+  mkdirSync(join(pkgDir, 'src'), { recursive: true })
+  writeFileSync(join(pkgDir, 'package.json'), JSON.stringify({ name }))
+  for (const [rel, text] of Object.entries(files)) writeFileSync(join(pkgDir, rel), text)
+}
+
+const roots: string[] = []
+const makeRoot = (): string => {
+  const root = mkdtempSync(join(tmpdir(), 'config-catalog-'))
+  roots.push(root)
+  return root
+}
+/** One-package fixture: the common case. */
+const make = (files: Record<string, string>, name = '@fix/one'): string => {
+  const root = makeRoot()
+  writePkg(root, 'group/one', name, files)
+  return root
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+const DOCUMENTED_CONFIG = `/** Fixture config. */
+export interface Config {
+  /** A knob. */
+  knob?: string
+}
+`
+
+describe('gen-config-catalog classification', () => {
+  it('classifies an apply plugin with a config parameter and extracts the paste', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+export const inject = ['tools']
+${DOCUMENTED_CONFIG}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]).toMatchObject({ pkg: '@fix/one', kind: 'config', configTypeName: 'Config', inject: ['tools'] })
+    expect(entries[0]?.pastes?.[0]?.text).toContain('/** A knob. */')
+  })
+
+  it('classifies a default service class, reading its constructor and static inject', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+${DOCUMENTED_CONFIG}
+/** Fixture service. */
+export default class Fix {
+  static inject = ['llm']
+  static Config = z.object({ knob: z.string() }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    }))
+    expect(entries[0]).toMatchObject({ kind: 'config', className: 'Fix', inject: ['llm'], schemaKeys: ['knob'] })
+  })
+
+  it('classifies an abstract default class as a seam', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': 'export default abstract class FixSeam { abstract run(): void }\n',
+    }))
+    expect(entries[0]).toMatchObject({ kind: 'seam', className: 'FixSeam' })
+  })
+
+  it('classifies a plugin whose apply takes no config as no-config', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': 'import type { Context } from \'cordis\'\n/** Load. */\nexport function apply(ctx: Context): void {}\n',
+    }))
+    expect(entries[0]?.kind).toBe('no-config')
+  })
+
+  it('classifies a module with neither default export nor apply as a library', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': 'export const helper = 1\n',
+    }))
+    expect(entries[0]?.kind).toBe('library')
+  })
+
+  it('hard-errors on a package with no entry file', () => {
+    const root = makeRoot()
+    mkdirSync(join(root, 'packages', 'group', 'one'), { recursive: true })
+    writeFileSync(join(root, 'packages', 'group', 'one', 'package.json'), JSON.stringify({ name: '@fix/one' }))
+    expect(() => collectConfigCatalog(root)).toThrow(/entry .* is missing or unreadable/)
+  })
+
+  it('hard-errors on a package.json without a name', () => {
+    const root = makeRoot()
+    mkdirSync(join(root, 'packages', 'group', 'one', 'src'), { recursive: true })
+    writeFileSync(join(root, 'packages', 'group', 'one', 'package.json'), '{}')
+    expect(() => collectConfigCatalog(root)).toThrow(/has no "name"/)
+  })
+})
+
+describe('gen-config-catalog config extraction guards', () => {
+  it('hard-errors on a config field with no JSDoc prose', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+export interface Config {
+  knob?: string
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/config field 'Config\.knob' .* has no JSDoc prose/)
+  })
+
+  it('hard-errors on an undocumented field nested in a type literal', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+/** Fixture config. */
+export interface Config {
+  /** Entries. */
+  entries: {
+    id: string
+  }[]
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/config field 'Config\.entries\.id' .* has no JSDoc prose/)
+  })
+
+  it('pastes a package-local type transitively and records external refs', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import type { Mode } from './types.ts'
+import type { Remote } from '@fix/dep'
+/** Fixture config. */
+export interface Config {
+  /** The mode. */
+  mode?: Mode
+  /** The remote. */
+  remote?: Remote
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+      'src/types.ts': '/** Fixture mode. */\nexport type Mode = \'a\' | \'b\'\n',
+    }))
+    expect(entries[0]?.pastes?.map(p => p.source)).toEqual([
+      'packages/group/one/src/index.ts:5',
+      'packages/group/one/src/types.ts:2',
+    ])
+    expect(entries[0]?.refs).toEqual([{ alias: 'Remote', imported: 'Remote', specifier: '@fix/dep' }])
+  })
+
+  it('hard-errors on a referenced type name that resolves nowhere', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+/** Fixture config. */
+export interface Config {
+  /** The ghost. */
+  ghost?: Ghost
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/references 'Ghost' .* neither declared in the package, imported, nor a known global/)
+  })
+
+  it('hard-errors on a config type imported from another package', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import type { Config } from '@fix/dep'
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/config type 'Config' is imported from '@fix\/dep'/)
+  })
+
+  it('hard-errors when one name resolves to two different declarations across the closure', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import type { A } from './a.ts'
+import type { B } from './b.ts'
+/** Fixture config. */
+export interface Config {
+  /** A. */
+  a?: A
+  /** B. */
+  b?: B
+}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+      'src/a.ts': '/** First Option. */\nexport interface Option {\n  /** X. */\n  x?: string\n}\n/** A. */\nexport interface A {\n  /** O. */\n  o?: Option\n}\n',
+      'src/b.ts': '/** Second Option. */\nexport interface Option {\n  /** Y. */\n  y?: string\n}\n/** B. */\nexport interface B {\n  /** O. */\n  o?: Option\n}\n',
+    }))).toThrow(/type name 'Option' resolves to two different declarations/)
+  })
+})
+
+describe('gen-config-catalog schema cross-check', () => {
+  it('accepts a chained schema whose keys all appear on the config type', () => {
+    const entries = collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+${DOCUMENTED_CONFIG}
+export const Config: z<Config> = z.object({ knob: z.string() }).default({})
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))
+    expect(entries[0]?.schemaKeys).toEqual(['knob'])
+  })
+
+  it('hard-errors on a schema key the config type does not declare', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+${DOCUMENTED_CONFIG}
+export const Config: z<Config> = z.object({ knob: z.string(), hidden: z.number() })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/schema validates key 'hidden' but config type 'Config' declares no such member/)
+  })
+
+  it('hard-errors on a NESTED schema key the config type does not declare', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Fixture config. */
+export interface Config {
+  /** Entries. */
+  entries: {
+    /** Id. */
+    id: string
+  }[]
+}
+export const Config: z<Config> = z.object({ entries: z.array(z.object({ id: z.string(), ghost: z.string() })) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).toThrow(/schema validates key 'entries\[\]\.ghost'/)
+  })
+
+  it('resolves nested keys through a workspace-imported intersection part (re-export chains included)', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/dep', '@fix/dep', {
+      'src/index.ts': 'export * from \'./types.ts\'\n',
+      'src/types.ts': '/** Shared options. */\nexport interface Opts {\n  /** Model. */\n  model?: string\n}\n',
+    })
+    writePkg(root, 'group/one', '@fix/one', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { Opts } from '@fix/dep'
+/** Fixture config. */
+export interface Config {
+  /** Entries. */
+  entries: (Opts & {
+    /** Id. */
+    id: string
+  })[]
+}
+export const Config: z<Config> = z.object({ entries: z.array(z.object({ id: z.string(), model: z.string() })) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    expect(() => collectConfigCatalog(root)).not.toThrow()
+  })
+
+  it('resolves nested keys through a Partial<> wrapper', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Caps. */
+export interface Caps {
+  /** X. */
+  x?: boolean
+}
+/** Fixture config. */
+export interface Config {
+  /** Capabilities. */
+  capabilities?: Partial<Caps>
+}
+export const Config: z<Config> = z.object({ capabilities: z.object({ x: z.boolean() }) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).not.toThrow()
+  })
+
+  it('leaves a nested key under an external (unresolvable) type unreported', () => {
+    expect(() => collectConfigCatalog(make({
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { External } from 'some-external-pkg'
+/** Fixture config. */
+export interface Config {
+  /** Options. */
+  options?: External
+}
+export const Config: z<Config> = z.object({ options: z.object({ whatever: z.string() }) })
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    }))).not.toThrow()
+  })
+
+  it('folds an intersected workspace schema into the subset check', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/leaf', '@fix/leaf', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Leaf config. */
+export interface Config {
+  /** Leaf knob. */
+  leaf?: string
+}
+/** Leaf service. */
+export default class Leaf {
+  static Config = z.object({ leaf: z.string() }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    })
+    writePkg(root, 'group/bundle', '@fix/bundle', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import Leaf from '@fix/leaf'
+/** Bundle config. */
+export interface Config {
+  /** Forwarded leaf knob. */
+  leaf?: string
+}
+export const Config = z.intersect([Leaf.Config]) as unknown as z<Config>
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    const entries = collectConfigCatalog(root)
+    expect(entries.find(e => e.pkg === '@fix/bundle')?.schemaComposes).toEqual(['@fix/leaf'])
+  })
+
+  it('resolves composed nested keys through an indexed-access forwarder', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/leaf', '@fix/leaf', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Leaf config. */
+export interface Config {
+  /** Agents. */
+  agents: {
+    /** Id. */
+    id: string
+  }[]
+}
+/** Leaf service. */
+export default class Leaf {
+  static Config = z.object({ agents: z.array(z.object({ id: z.string() })) }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    })
+    writePkg(root, 'group/bundle', '@fix/bundle', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import Leaf, { type Config as LeafConfig } from '@fix/leaf'
+/** Bundle config forwarding the leaf's agents list. */
+export interface Config {
+  /** Forwarded agents list. */
+  agents?: LeafConfig['agents']
+}
+export const Config = z.intersect([Leaf.Config]) as unknown as z<Config>
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    expect(() => collectConfigCatalog(root)).not.toThrow()
+  })
+
+  it('hard-errors when an intersected schema key is missing from the bundle config type', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/leaf', '@fix/leaf', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+/** Leaf config. */
+export interface Config {
+  /** Leaf knob. */
+  leaf?: string
+}
+/** Leaf service. */
+export default class Leaf {
+  static Config = z.object({ leaf: z.string() }) as unknown as z<Config>
+  constructor(ctx: Context, config: Config) {}
+}
+`,
+    })
+    writePkg(root, 'group/bundle', '@fix/bundle', {
+      'src/index.ts': `import type { Context } from 'cordis'
+import z from 'schemastery'
+import Leaf from '@fix/leaf'
+/** Bundle config that forgot to declare the forwarded field. */
+export interface Config {
+  /** Unrelated. */
+  other?: string
+}
+export const Config = z.intersect([Leaf.Config]) as unknown as z<Config>
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    expect(() => collectConfigCatalog(root)).toThrow(/schema validates key 'leaf' but config type 'Config' declares no such member/)
+  })
+})
+
+describe('gen-config-catalog render', () => {
+  it('renders sections, fences, and the terse classification lists', () => {
+    const root = makeRoot()
+    writePkg(root, 'group/one', '@fix/one', {
+      'src/index.ts': `import type { Context } from 'cordis'
+${DOCUMENTED_CONFIG}
+/** Load. */
+export function apply(ctx: Context, config: Config): void {}
+`,
+    })
+    writePkg(root, 'group/lib', '@fix/lib', { 'src/index.ts': 'export const helper = 1\n' })
+    writePkg(root, 'group/seam', '@fix/seam', {
+      'src/index.ts': 'export default abstract class Seam { abstract run(): void }\n',
+    })
+    const page = render(collectConfigCatalog(root))
+    expect(page).toContain('## `@fix/one`')
+    expect(page).toContain('```ts config-catalog')
+    expect(page).toContain('/** A knob. */')
+    expect(page).toContain('- `@fix/lib` ([`packages/group/lib/src/index.ts`](../packages/group/lib/src/index.ts))')
+    expect(page).toContain('- `@fix/seam` — abstract `Seam`')
+  })
+})