@kamishibai/sdk 0.1.1

package/src/cli/index.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from 'commander'
+import { engineVersion } from '../core/version.js'
+import { EXIT, usageError, commandLoadError } from '../core/errors.js'
+import { emit, toFailure } from './emit.js'
+
+/**
+ * Command modules are loaded *inside* their action, never at the top level.
+ *
+ * Eagerly importing all fifteen dragged every command's dependency tree into
+ * every invocation: `--version` paid ~208 ms to answer from a string it already
+ * had (量測報告 §1.2), and CLI-spawning tests paid it once per spawn until they
+ * blew the 5 s default budget (§1.5). An `import()` inside the action loads
+ * exactly the one module the invocation actually runs.
+ *
+ * Every one of those loads goes through `load`, because a rejected `import()`
+ * would otherwise reach the generic handler and be reported as
+ * `KSB_PARSE_FAILED` — telling an agent its *document* failed to parse when the
+ * truth is a broken install.
+ */
+const load = async (command, importer) => {
+  try {
+    return await importer()
+  } catch (cause) {
+    throw commandLoadError(command, cause)
+  }
+}
+
+const argv = process.argv
+const wantsJson = argv.includes('--json')
+
+const HELP_CODES = new Set(['commander.helpDisplayed', 'commander.help'])
+const VERSION_CODE = 'commander.version'
+
+const HELP_FLAGS = new Set(['-h', '--help', 'help'])
+const VERSION_FLAGS = new Set(['-v', '--version'])
+
+/** The subcommands. Presence of one is what makes an invocation a command. */
+const COMMANDS = Object.freeze([
+  'render',
+  'lint',
+  'example',
+  'schema',
+  'list',
+  'open',
+  'replay',
+  'export',
+  'snapshot',
+  'setup',
+  'serve',
+  'close',
+  'comments',
+  'templates',
+  'init',
+  'promote',
+  'debug',
+])
+
+/** The single wording for "you gave no command", shared by both output paths. */
+const NO_COMMAND_MESSAGE = 'no command given; try `kamishibai --help`'
+
+/**
+ * Commander raises the same help error whether the user *asked* for help or
+ * merely gave no command. Only the former is a success: treating both as
+ * exit 0 turned `kamishibai --json` into exit 0 with empty stdout, which any
+ * downstream `JSON.parse` would crash on while looking like success (A7).
+ */
+const askedForHelp = argv.slice(2).some((a) => HELP_FLAGS.has(a))
+const askedForVersion = argv.slice(2).some((a) => VERSION_FLAGS.has(a))
+
+/**
+ * Detect "no command" by looking for a subcommand token, not by counting argv:
+ * a bare `--json` makes argv長 enough to slip past a length check and then falls
+ * through to commander, whose help error message is the internal token
+ * `(outputHelp)` — leaking implementation detail and making the two output
+ * paths disagree on the wording (A7).
+ */
+const hasCommand = argv.slice(2).some((a) => COMMANDS.includes(a))
+
+/** Commander's own output, captured so `--json` can return it as a JSON field. */
+const captured = []
+
+const buildProgram = () => {
+  const program = new Command()
+  program
+    .name('kamishibai')
+    .description('Agent Presentation SDK — 結構化內容渲染為離線單檔產物')
+    .version(engineVersion(), '-v, --version')
+    .option('--json', '以 JSON 輸出結果（可置於指令前或後）')
+    .exitOverride()
+
+  // With --json, stdout must stay a single JSON object, so commander's own
+  // help/usage text is captured instead of printed — help then comes back as
+  // a JSON field, and usage errors as a KSB_ error object.
+  if (wantsJson) {
+    program.configureOutput({
+      writeOut: (str) => captured.push(str),
+      writeErr: (str) => captured.push(str),
+    })
+  }
+
+  program
+    .command('render')
+    .description('把 Markdown 超集或 block tree JSON 渲染成離線單檔 HTML（`-` 讀 stdin）')
+    .argument('<input>', 'Markdown 超集／block tree JSON 檔路徑，或 `-` 表示 stdin')
+    .option('-o, --out <path>', '產物輸出路徑')
+    .option('-t, --template <key>', '覆寫模板 <namespace>/<name>')
+    .option('-g, --generator <name>', 'IR generator 欄位值')
+    .option('-p, --project <name>', '覆寫中央產物庫的專案名（預設依四層解析）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (input, options) => {
+      const { renderCommand } = await load('render', () => import('./commands/render.js'))
+      const { result, exitCode } = await renderCommand(input, options)
+      emit({ command: 'render', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('replay')
+    .description('由產物內嵌 IR 重繪（換模板／升版／換皮）')
+    .argument('<artifact>', '既有產物 HTML 路徑')
+    .option('-o, --out <path>', '產物輸出路徑')
+    .option('-t, --template <key>', '覆寫模板 <namespace>/<name>')
+    .option('-g, --generator <name>', 'IR generator 欄位值')
+    .option('-p, --project <name>', '覆寫中央產物庫的專案名（預設依四層解析）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (artifact, options) => {
+      const { replayCommand } = await load('replay', () => import('./commands/replay.js'))
+      const { result, exitCode } = await replayCommand(artifact, options)
+      emit({ command: 'replay', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('list')
+    .description('列出當前專案的中央產物庫呈現史')
+    .option('-p, --project <name>', '覆寫專案名（預設 .kamishibai.toml → git root → cwd）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (options) => {
+      const { listCommand } = await load('list', () => import('./commands/list.js'))
+      const { result, exitCode } = listCommand(options)
+      emit({ command: 'list', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('open')
+    .description('由中央產物庫解析並開啟產物（跨平台開啟鏈）')
+    .argument('<name>', '產物名稱，或 `latest` 表示最新一份')
+    .option('-p, --project <name>', '覆寫專案名（預設 .kamishibai.toml → git root → cwd）')
+    .option('--dry-run', '只解析路徑、不開啟瀏覽器')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (name, options) => {
+      const { openCommand } = await load('open', () => import('./commands/open.js'))
+      const { result, exitCode } = openCommand(name, options)
+      emit({ command: 'open', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('export')
+    .description('把產物匯出成附屬格式（document → pdf、deck → pptx）')
+    .argument('<artifact>', '既有產物 HTML 路徑')
+    .requiredOption('--to <format>', '匯出格式：pdf 或 pptx')
+    .option('-o, --out <path>', '匯出檔輸出路徑（預設 out/<產物名>.<格式>）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (artifact, options) => {
+      const { exportCommand } = await load('export', () => import('./commands/export.js'))
+      const { result, exitCode } = await exportCommand(artifact, options)
+      emit({ command: 'export', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('snapshot')
+    .description('把產物截成 PNG，讓 Agent（與人）看得到視覺效果')
+    .argument('<artifact>', '既有產物 HTML 路徑')
+    .option('-o, --out <path>', 'PNG 輸出路徑（預設 out/<產物名>.png）')
+    .option('--slide <n>', 'deck 產物要截第幾張（預設第 1 張）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (artifact, options) => {
+      const { snapshotCommand } = await load('snapshot', () => import('./commands/snapshot.js'))
+      const { result, exitCode } = await snapshotCommand(artifact, options)
+      emit({ command: 'snapshot', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('setup')
+    .description('初始化環境：建中央儲存庫、確認（必要時安裝）渲染用瀏覽器')
+    .option('--dry-run', '只回報狀態、不建目錄也不安裝')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (options) => {
+      const { setupCommand } = await load('setup', () => import('./commands/setup.js'))
+      const { result, exitCode } = await setupCommand(options)
+      emit({ command: 'setup', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('serve')
+    .description('起本地預覽伺服器：來源檔一變就重繪並推播 reload（SPEC §10.2 watch 模式）')
+    .argument('<input>', 'Markdown 超集／block tree JSON 檔路徑')
+    .option('--port <n>', '指定連接埠（預設由系統挑一個空的）')
+    .option('-t, --template <key>', '覆寫模板 <namespace>/<name>')
+    .option('-g, --generator <name>', 'IR generator 欄位值')
+    .option('-p, --project <name>', '覆寫中央產物庫的專案名（預設依四層解析）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (input, options) => {
+      const { serveCommand } = await load('serve', () => import('./commands/serve.js'))
+      const { result, exitCode } = await serveCommand(input, options)
+      emit({ command: 'serve', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('close')
+    .description('終止本 SDK 起的預覽伺服器（沒有在跑也算成功）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (options) => {
+      const { closeCommand } = await load('close', () => import('./commands/close.js'))
+      const { result, exitCode } = closeCommand(options)
+      emit({ command: 'close', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('comments')
+    .description('讀寫產物留言（block id 錨定）：列出／`resolve <產物> <id>`／`add <產物> <blockId> <文字>`')
+    .argument('<args...>', '`<產物>`、`resolve <產物> <id>` 或 `add <產物> <blockId> <文字>`')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (args) => {
+      const { commentsCommand } = await load('comments', () => import('./commands/comments.js'))
+      const { result, exitCode } = commentsCommand(args)
+      emit({ command: 'comments', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('templates')
+    .description('列出中央儲存庫已註冊的模板包')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (options) => {
+      const { templatesCommand } = await load('templates', () => import('./commands/templates.js'))
+      const { result, exitCode } = templatesCommand(options)
+      emit({ command: 'templates', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('init')
+    .description('產生模板包骨架（manifest＋stylesheet＋預設 md），開箱即可 render')
+    .argument('<key>', '模板鍵 <namespace>/<name>（出廠 namespace 保留）')
+    // 這一句必須列出腳手架**真的**做得出來的每一個文體（封緘 F2）：help 是
+    // 使用者唯一的能力面目錄，而它原本只說「預設 article」——於是 F2f 讓腳手架
+    // 學會 deck 的那天，能力長了、目錄沒長，讀 help 的人除了猜沒有別的辦法。
+    // 這裡不 import 那份清單：F4 已把序幕的 static import 釘成白名單，為了一句
+    // 說明拉一個模組進每一次 `--version` 是划不來的交易。改由
+    // `test_f3_init_is_in_help` 拿 SCAFFOLD_SUPPORTED_LAYOUTS 組出這一整行來對，
+    // 清單長大而這裡沒跟上就會紅。
+    .option(
+      '-l, --layout <name>',
+      '所騎的文體（article／card／deck／one-page／resume；預設 article）',
+    )
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (key, options) => {
+      const { initCommand } = await load('init', () => import('./commands/init.js'))
+      const { result, exitCode } = initCommand(key, options)
+      emit({ command: 'init', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('promote')
+    .description('把臨摹草稿 `draft/<名>` 轉正成正式模板包（目錄搬移＋manifest 改寫）')
+    .argument('<from>', '來源模板鍵，必須是 `draft/<名>`')
+    .argument('<to>', '目標模板鍵 <namespace>/<name>（出廠 namespace 保留）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (from, to, options) => {
+      const { promoteCommand } = await load('promote', () => import('./commands/promote.js'))
+      const { result, exitCode } = promoteCommand(from, to, options)
+      emit({ command: 'promote', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('debug')
+    .description('診斷：儲存庫位置、模板包數、瀏覽器狀態、引擎版本')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (options) => {
+      const { debugCommand } = await load('debug', () => import('./commands/debug.js'))
+      const { result, exitCode } = await debugCommand(options)
+      emit({ command: 'debug', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('lint')
+    .description('驗證產物：零外部請求、內嵌 IR 齊備且通過 schema')
+    .argument('[artifact]', '產物 HTML 路徑（`--rules` 時可省略）')
+    .option('--rules', '列出 lint 規則（code／掃描範圍／pattern／說明），不驗證產物')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (artifact, options) => {
+      const { lintCommand } = await load('lint', () => import('./commands/lint.js'))
+      const { result, exitCode } = await lintCommand(artifact, options)
+      emit({ command: 'lint', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('example')
+    .description('輸出合法範例（`doc`／`deck` 為 Markdown 超集，其餘為 block JSON）')
+    .argument('[kind]', '範例類型：doc、deck 或 block 名稱', 'doc')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async (kind) => {
+      const { exampleCommand } = await load('example', () => import('./commands/example.js'))
+      const { result, exitCode } = exampleCommand(kind)
+      emit({ command: 'example', result, json: wantsJson, exitCode })
+    })
+
+  program
+    .command('schema')
+    .description('輸出 IR 的 JSON Schema（draft 2020-12）')
+    .option('--json', '以 JSON 輸出結果')
+    .action(async () => {
+      const { schemaCommand } = await load('schema', () => import('./commands/schema.js'))
+      const { result, exitCode } = schemaCommand()
+      emit({ command: 'schema', result, json: wantsJson, exitCode })
+    })
+
+  return program
+}
+
+async function main() {
+  if (!hasCommand && !askedForHelp && !askedForVersion) throw usageError(NO_COMMAND_MESSAGE)
+  await buildProgram().parseAsync(argv)
+}
+
+/**
+ * `--help` / `--version` succeed only when the user actually asked for them.
+ * Without `--json` commander has already written the text to stdout itself;
+ * with `--json` that text was captured instead, and comes back as a field so
+ * stdout stays a single JSON object.
+ */
+const emitHelp = (field, value) => {
+  if (wantsJson) {
+    emit({ command: 'cli', result: { ok: true, [field]: value }, json: true, exitCode: EXIT.OK })
+    return
+  }
+  process.exitCode = EXIT.OK
+}
+
+/**
+ * Commander sets some error messages to bare internal tokens such as
+ * `(outputHelp)`. Those are event names, not diagnostics — never show them.
+ */
+const INTERNAL_TOKEN = /^\(\w+\)$/
+
+const userFacingMessage = (raw) => {
+  const message = String(raw ?? '').replace(/^error:\s*/, '').trim()
+  return message.length === 0 || INTERNAL_TOKEN.test(message) ? NO_COMMAND_MESSAGE : message
+}
+
+main().catch((error) => {
+  if (error instanceof CommanderError) {
+    if (error.code === VERSION_CODE && askedForVersion) {
+      emitHelp('version', engineVersion())
+      return
+    }
+    if (HELP_CODES.has(error.code) && askedForHelp) {
+      emitHelp('help', captured.join('').trimEnd())
+      return
+    }
+    const { result } = toFailure(usageError(userFacingMessage(error.message)))
+    emit({ command: 'cli', result, json: wantsJson, exitCode: EXIT.USAGE })
+    return
+  }
+  const { result, exitCode } = toFailure(error)
+  emit({ command: 'cli', result, json: wantsJson, exitCode })
+})

package/src/cli/registry.js

@@ -0,0 +1,18 @@
+import { engineVersion } from '../core/version.js'
+import { builtinManifests } from '../render/index.js'
+import { registerTemplatePackage } from '../delivery/templates.js'
+
+/**
+ * The one place where "what the engine can draw" (render layer) meets "what the
+ * store records" (delivery layer). Wiring them here, at the CLI boundary, is
+ * what keeps the store from importing templates and the renderer from knowing
+ * where `~/.kamishibai` is.
+ *
+ * It runs on `setup`, on every delivery, and on `templates`/`debug` — a first
+ * touch of any kind registers the built-ins, so an Agent that never ran `setup`
+ * still finds the namespace populated (CONTRACT E3「`setup`（或首觸）」).
+ */
+export function registerBuiltinTemplates(env = process.env) {
+  const engine = engineVersion()
+  return builtinManifests().map((manifest) => registerTemplatePackage({ manifest, engine, env }))
+}

package/src/core/blocks.js

@@ -0,0 +1,147 @@
+import { blockModule, blockModules, blockTypes, registryVersion } from '../blocks/index.js'
+import { CALLOUT_VARIANTS } from '../blocks/callout.js'
+import { RAW_SUBTYPES } from '../blocks/raw.js'
+import { diagramParseError } from '../blocks/diagram.js'
+
+/**
+ * Tree-shaped operations over the canonical block vocabulary.
+ *
+ * What a block *is* no longer lives here: each type owns one module under
+ * `src/blocks/`, and this file derives everything type-specific from the
+ * registry. Only genuinely cross-type work stays — id assignment, the document
+ * walk, and the `doc` envelope, none of which any single block can own.
+ */
+
+/** The canonical block vocabulary, in registration order (SPEC §3). */
+export const BLOCK_TYPES = Object.freeze(blockTypes())
+
+export { CALLOUT_VARIANTS, RAW_SUBTYPES, diagramParseError }
+
+export const META_KEY_ORDER = Object.freeze(['title', 'kicker', 'subtitle', 'author', 'date'])
+
+/** The `doc` envelope — the one node that is not a block and has no module. */
+export const doc = ({ meta, children }) => Object.freeze({ type: 'doc', meta, children })
+
+/**
+ * Block factories, resolved through the registry on every access.
+ *
+ * `create.section({…})` reads like the plain factory it replaced, but the
+ * function comes from the section module rather than from a list maintained
+ * here — the list is exactly what CONTRACT A3 forbids the core to keep. Live
+ * lookup rather than a snapshot, so a block registered after this module loaded
+ * is still constructible.
+ */
+export const create = new Proxy(
+  // Extensible on purpose: a Proxy over a frozen target may not report a
+  // property the target lacks, which would make every lookup return undefined.
+  {},
+  {
+    get: (_target, type) => (typeof type === 'string' ? blockModule(type)?.create : undefined),
+    has: (_target, type) => blockModule(String(type)) !== undefined,
+  },
+)
+
+/**
+ * A block nests its sub-blocks under one of two field shapes, and which key a
+ * type uses is the type's own knowledge — declared by its module's `nesting`,
+ * never listed again here. Every generic walk (id assignment, traversal) is
+ * written against these derived sets rather than against `children` alone: a
+ * new container type that forgot to declare its nesting would otherwise
+ * silently lose ids for everything inside it.
+ *
+ *  - arrays   (`children` / `slides`) — a flat array of blocks
+ *  - matrices (`items`)               — an array *of arrays* of blocks
+ */
+let nestingCache = { version: -1, arrays: [], matrices: [] }
+
+function nestingKeys() {
+  const version = registryVersion()
+  if (nestingCache.version === version) return nestingCache
+  const arrays = new Set(['children']) // the `doc` envelope's own shape
+  const matrices = new Set()
+  for (const mod of blockModules()) {
+    for (const key of mod.nesting?.arrays ?? []) arrays.add(key)
+    for (const key of mod.nesting?.matrices ?? []) matrices.add(key)
+  }
+  nestingCache = { version, arrays: [...arrays], matrices: [...matrices] }
+  return nestingCache
+}
+
+/** The nesting field names currently in the vocabulary — exported for inspection. */
+export const blockArrayKeys = () => Object.freeze([...nestingKeys().arrays])
+export const blockMatrixKeys = () => Object.freeze([...nestingKeys().matrices])
+
+/**
+ * Assign deterministic document-order ids (b1, b2, …) to a block tree.
+ * Returns a new tree; the input is untouched.
+ */
+export function withIds(node, counter = { n: 0 }, keys = nestingKeys()) {
+  counter.n += 1
+  const id = `b${counter.n}`
+  const { id: _previousId, ...rest } = node
+  // Own fields first, nested ones after — key order here is the key order of
+  // the embedded IR JSON, and therefore of the artifact's bytes.
+  const isNested = (key, value) =>
+    Array.isArray(value) && (keys.matrices.includes(key) || keys.arrays.includes(key))
+  const out = { id }
+  for (const [key, value] of Object.entries(rest)) {
+    if (!isNested(key, value)) out[key] = value
+  }
+  for (const key of keys.matrices) {
+    const value = rest[key]
+    if (!Array.isArray(value)) continue
+    out[key] = value.map((group) =>
+      Array.isArray(group) ? group.map((block) => withIds(block, counter, keys)) : group,
+    )
+  }
+  for (const key of keys.arrays) {
+    const value = rest[key]
+    if (!Array.isArray(value)) continue
+    out[key] = value.map((block) => withIds(block, counter, keys))
+  }
+  return out
+}
+
+/** Depth-first walk in document order, across every nesting shape. */
+export function* walkBlocks(node, path = 'doc', keys = nestingKeys()) {
+  yield { block: node, path }
+  for (const key of keys.matrices) {
+    if (!Array.isArray(node[key])) continue
+    for (const [group, blocks] of node[key].entries()) {
+      if (!Array.isArray(blocks)) continue
+      for (const [index, child] of blocks.entries()) {
+        yield* walkBlocks(child, `${path}.${key}[${group}][${index}]`, keys)
+      }
+    }
+  }
+  for (const key of keys.arrays) {
+    if (!Array.isArray(node[key])) continue
+    for (const [index, child] of node[key].entries()) {
+      yield* walkBlocks(child, `${path}.${key}[${index}]`, keys)
+    }
+  }
+}
+
+/**
+ * Every block id a tree carries — the set of anchors a comment may name
+ * (CONTRACT E2). Derived from the same walk that assigns the ids, so an anchor
+ * can never be legal in one place and unknown in the other.
+ *
+ * @returns {Set<string>}
+ */
+export function collectBlockIds(node) {
+  const ids = new Set()
+  if (node === undefined || node === null) return ids
+  for (const { block } of walkBlocks(node)) {
+    if (typeof block?.id === 'string') ids.add(block.id)
+  }
+  return ids
+}
+
+/** The first `deck` block in a tree, or undefined for a document artifact. */
+export function findDeck(node) {
+  for (const { block } of walkBlocks(node)) {
+    if (block?.type === 'deck') return block
+  }
+  return undefined
+}