@kamishibai/sdk 0.1.1

package/src/cli/commands/debug.js

@@ -0,0 +1,34 @@
+import { EXIT } from '../../core/errors.js'
+import { engineVersion } from '../../core/version.js'
+import { resolveHome } from '../../delivery/home.js'
+import { readTemplatePackages } from '../../delivery/templates.js'
+import { readServeRecords } from '../../delivery/run.js'
+import { probeBrowser } from '../../export/browser.js'
+import { registerBuiltinTemplates } from '../registry.js'
+
+/**
+ * `kamishibai debug [--json]` — SPEC §10.1「診斷（環境、依賴、模板解析過程）」.
+ *
+ * One object that answers "what does this installation actually have?". The
+ * browser line is **probed**, never inferred from a package being installed:
+ * the same reasoning that governs `setup` applies here, and a diagnostic that
+ * guesses is worse than none, because it is believed.
+ *
+ * @returns {Promise<{result: object, exitCode: number}>}
+ */
+export async function debugCommand(options = {}, env = process.env) {
+  registerBuiltinTemplates(env)
+  const probe = await probeBrowser()
+
+  return {
+    result: {
+      ok: true,
+      home: resolveHome(env),
+      templates: readTemplatePackages(env).length,
+      browser: probe.available ? 'present' : 'missing',
+      engine: engineVersion(),
+      servers: readServeRecords(env).length,
+    },
+    exitCode: EXIT.OK,
+  }
+}

package/src/cli/commands/example.js

@@ -0,0 +1,22 @@
+import { exampleFor, exampleKinds } from '../../core/example.js'
+import { CODES, EXIT, KsbError } from '../../core/errors.js'
+
+/**
+ * `kamishibai example [doc|<block>]` — the anti-trial-and-error channel.
+ * Human output is the example verbatim, so it can be piped straight into
+ * `render -`.
+ */
+export function exampleCommand(kind = 'doc') {
+  const found = exampleFor(kind)
+  if (found === null) {
+    throw new KsbError({
+      code: CODES.USAGE,
+      message: `unknown example kind "${kind}"; available: ${exampleKinds().join(', ')}`,
+      exitCode: EXIT.USAGE,
+    })
+  }
+  return {
+    result: { ok: true, kind: found.kind, example: found.example },
+    exitCode: EXIT.OK,
+  }
+}

package/src/cli/commands/export.js

@@ -0,0 +1,10 @@
+import { exportArtifact } from '../../export/index.js'
+
+/**
+ * `kamishibai export <artifact> --to pdf|pptx [-o out]`
+ *
+ * @returns {Promise<{result: object, exitCode: number}>}
+ */
+export async function exportCommand(target, options = {}) {
+  return await exportArtifact({ target, format: options.to, out: options.out })
+}

package/src/cli/commands/init.js

@@ -0,0 +1,53 @@
+import { EXIT } from '../../core/errors.js'
+import { engineVersion } from '../../core/version.js'
+import { ensureStoreRoot } from '../../delivery/store.js'
+import {
+  scaffoldTemplatePackage,
+  validateScaffoldRequest,
+} from '../../delivery/template-scaffold.js'
+import { reservedNamespaces } from '../../render/index.js'
+import { registerBuiltinTemplates } from '../registry.js'
+
+/**
+ * `kamishibai init <namespace>/<name> [--layout <文體>]` (CONTRACT D4).
+ *
+ * A template package's entry cost is what decides whether the pure-data path is
+ * the default path or a thing the documentation claims. This writes the whole
+ * format — manifest, stylesheet, 預設 md — into the store and hands back the
+ * exact command that draws it, so the first render is a copy-paste rather than
+ * a guess.
+ *
+ * The reserved namespaces come from the render layer's live registry rather
+ * than a list typed here: a second copy would be free to disagree with the one
+ * `resolveTemplate` actually enforces, and the direction it would fail in is
+ * the bad one — `init` cheerfully creating a package that can never be loaded.
+ *
+ * @returns {{result: object, exitCode: number}}
+ */
+export function initCommand(key, options = {}, env = process.env) {
+  // Everything judgeable without the filesystem is judged **first** (複驗 F-2).
+  // `ensureStoreRoot` creates `~/.kamishibai` and `registerBuiltinTemplates`
+  // writes two manifests into it; running either before the key is validated
+  // means a refused `init ../evil` still built a store on its way to saying no.
+  // A command that rejects your input must leave the disk exactly as it found it.
+  const request = validateScaffoldRequest({
+    key,
+    layout: options.layout,
+    reserved: reservedNamespaces(),
+  })
+
+  ensureStoreRoot(env)
+  // First touch registers the built-ins, so a brand-new store lists the factory
+  // family alongside whatever this command is about to add (E3「首觸」).
+  registerBuiltinTemplates(env)
+
+  const result = scaffoldTemplatePackage({
+    key: request.key,
+    layout: request.layout,
+    engine: engineVersion(),
+    reserved: reservedNamespaces(),
+    env,
+  })
+
+  return { result: { ok: true, ...result }, exitCode: EXIT.OK }
+}

package/src/cli/commands/lint.js

@@ -0,0 +1,93 @@
+import { readArtifact } from '../../delivery/read.js'
+import { extractIrPayloads } from '../../parser/artifact.js'
+import { lintArtifact, lintRules } from '../../core/lint.js'
+import { templateKeyOf } from '../../core/ir.js'
+import { CODES, EXIT, usageError } from '../../core/errors.js'
+
+/** The single wording for "lint needs something to work on", both paths alike. */
+const NO_TARGET_MESSAGE = 'lint 需要產物路徑；只想看規則請用 `kamishibai lint --rules`'
+
+/**
+ * The single wording for "you asked for both at once".
+ *
+ * Accepting both and quietly listing the rules would hand back exit 0 while the
+ * artifact went unchecked — a gate that reports success without gating is worse
+ * than one that refuses, because CI believes it.
+ */
+const RULES_WITH_TARGET_MESSAGE =
+  '`--rules` 只列規則、不驗證產物；請擇一：去掉產物路徑看規則，或去掉 `--rules` 驗證該產物'
+
+/**
+ * Load the package the artifact says drew it, so the IR is judged against the
+ * vocabulary it was written in (CONTRACT F3 D3).
+ *
+ * The IR schema is generated from the block registry, and a package's `x-*`
+ * plugin blocks only enter that registry when the package is loaded. Without
+ * this, `render` would succeed and `lint` — a *fresh process* that never opened
+ * the package — would then report the plugin block as a schema violation: two
+ * commands disagreeing about what is legal, with the gate on the losing side.
+ *
+ * A key nobody has is passed over rather than raised: the artifact may have been
+ * drawn on another machine, and the schema check will say so in its own words,
+ * naming the block type it does not know. Every *other* failure is re-thrown —
+ * a package that exists and will not load is a real problem, and swallowing it
+ * here would turn "your package is broken" into "your artifact is fine".
+ *
+ * Both modules are imported *here* rather than at the top of the file, for the
+ * reason F4 gave the whole CLI: a static import would drag the render layer and
+ * both factory template packages into every `lint --rules`, which reads no
+ * artifact at all and needs neither.
+ */
+async function loadArtifactVocabulary(html, env) {
+  const payloads = extractIrPayloads(html)
+  if (payloads.length !== 1) return undefined
+  let key
+  try {
+    key = templateKeyOf(JSON.parse(payloads[0]))
+  } catch {
+    // An unparsable payload is `lintArtifact`'s finding to report, not ours.
+    return undefined
+  }
+  if (key === undefined) return undefined
+
+  const { installTemplateStore } = await import('../../delivery/template-package.js')
+  const { resolveTemplate } = await import('../../render/index.js')
+  installTemplateStore(env)
+  try {
+    return await resolveTemplate(key)
+  } catch (error) {
+    if (error?.code !== CODES.TEMPLATE_NOT_FOUND) throw error
+    return undefined
+  }
+}
+
+/**
+ * `kamishibai lint <artifact>` — and `kamishibai lint --rules`, which answers
+ * "what does this gate actually scan, and over which region" without an agent
+ * having to read the linter's source (量測報告 §3 R1).
+ *
+ * @returns {Promise<{result: object|Array, exitCode: number}>}
+ */
+export async function lintCommand(target, options = {}, env = process.env) {
+  const hasTarget = typeof target === 'string' && target.length > 0
+  if (options.rules && hasTarget) throw usageError(RULES_WITH_TARGET_MESSAGE)
+  if (options.rules) return { result: lintRules(), exitCode: EXIT.OK }
+  if (!hasTarget) throw usageError(NO_TARGET_MESSAGE)
+
+  const { html, path } = readArtifact(target)
+  // F7b — the same load answers a second question. A `[gates]` rule is only
+  // meaningful against the package that declared it, and the artifact says which
+  // package drew it; reading the manifest here is what keeps `core/lint.js` fed
+  // by its caller instead of growing an I/O path of its own (AGENTS §3.1).
+  const template = await loadArtifactVocabulary(html, env)
+  const errors = lintArtifact({
+    html,
+    irPayloads: extractIrPayloads(html),
+    gates: template?.manifest?.gates,
+  })
+
+  if (errors.length > 0) {
+    return { result: { ok: false, errors }, exitCode: EXIT.VALIDATION }
+  }
+  return { result: { ok: true, artifact: path, errors: [] }, exitCode: EXIT.OK }
+}

package/src/cli/commands/list.js

@@ -0,0 +1,54 @@
+import { extractIrPayloads } from '../../parser/artifact.js'
+import { templateLabelOf } from '../../core/ir.js'
+import { EXIT } from '../../core/errors.js'
+import { resolveProject } from '../../delivery/project.js'
+import { readEntries } from '../../delivery/store.js'
+
+/** CONTRACT B4 — the six keys of a list entry, in output order. */
+export const LIST_KEYS = Object.freeze([
+  'name',
+  'template',
+  'createdAt',
+  'generator',
+  'artifact',
+  'copies',
+])
+
+/**
+ * An artifact whose IR cannot be read is still a record in the store: it is
+ * listed with empty descriptive fields rather than dropped, because a silently
+ * shorter list is indistinguishable from "no such artifact".
+ */
+const irOf = (html) => {
+  const payloads = extractIrPayloads(html)
+  if (payloads.length !== 1) return null
+  try {
+    return JSON.parse(payloads[0])
+  } catch {
+    return null
+  }
+}
+
+const toEntry = (record) => {
+  const ir = irOf(record.html)
+  return {
+    name: record.name,
+    template: ir === null ? '' : templateLabelOf(ir),
+    createdAt: ir?.createdAt ?? '',
+    generator: ir?.generator ?? '',
+    artifact: record.path,
+    copies: record.copies,
+  }
+}
+
+/**
+ * `kamishibai list [--project name]` — the project's presentation history
+ * (SPEC §9.2). An empty project is an empty array with exit 0, not an error.
+ *
+ * @returns {{result: Array<object>, exitCode: number}}
+ */
+export function listCommand(options = {}, env = process.env, cwd = process.cwd()) {
+  const project = resolveProject({ project: options.project, cwd })
+  const entries = readEntries({ project: project.name, env }).map(toEntry)
+  return { result: entries, exitCode: EXIT.OK }
+}

package/src/cli/commands/open.js

@@ -0,0 +1,31 @@
+import { CODES, EXIT, KsbError } from '../../core/errors.js'
+import { resolveProject } from '../../delivery/project.js'
+import { findArtifact, LATEST } from '../../delivery/store.js'
+import { openPath } from '../../delivery/open.js'
+
+/**
+ * `kamishibai open <name|latest> [--dry-run]`
+ *
+ * Resolves a name against the current project's central store and hands it to
+ * the single cross-platform opener (SPEC §8). `--dry-run` resolves only —
+ * the pinned surface is the absolute path, so an Agent can use `open` as a
+ * lookup without ever spawning a browser.
+ *
+ * @returns {{result: {ok: true, path: string}, exitCode: number}}
+ */
+export function openCommand(nameSpec = LATEST, options = {}, env = process.env, cwd = process.cwd()) {
+  const project = resolveProject({ project: options.project, cwd })
+  const found = findArtifact({ project: project.name, name: nameSpec, env })
+
+  if (found === null) {
+    throw new KsbError({
+      code: CODES.ARTIFACT_NOT_FOUND,
+      message: `no artifact "${nameSpec}" in project "${project.name}"`,
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+
+  if (options.dryRun !== true) openPath(found.path)
+
+  return { result: { ok: true, path: found.path }, exitCode: EXIT.OK }
+}

package/src/cli/commands/promote.js

@@ -0,0 +1,38 @@
+import { EXIT } from '../../core/errors.js'
+import { ensureStoreRoot } from '../../delivery/store.js'
+import {
+  promoteTemplatePackage,
+  validatePromoteRequest,
+} from '../../delivery/template-promote.js'
+import { reservedNamespaces } from '../../render/index.js'
+import { registerBuiltinTemplates } from '../registry.js'
+
+/**
+ * `kamishibai promote <draft/名> <namespace/名>` (CONTRACT F7a H1).
+ *
+ * The exit of the 臨摹 workspace. `init draft/<名>` opens one, the Agent reads
+ * the original and writes the skin, `render` + `snapshot` close the loop by eye,
+ * `lint` closes it mechanically — and this is what turns the result into a
+ * package other things may depend on.
+ *
+ * The reserved namespaces come from the render layer's live registry rather
+ * than a list typed here, for the reason `init` records next door: a second copy
+ * would be free to disagree with the one `resolveTemplate` enforces, and it
+ * would fail in the bad direction — a `promote` that cheerfully lands a package
+ * at a key that can never be loaded.
+ *
+ * @returns {{result: object, exitCode: number}}
+ */
+export function promoteCommand(from, to, options = {}, env = process.env) {
+  // Everything judgeable without the filesystem is judged **first** (複驗 F-2),
+  // and `validatePromoteRequest` is called ahead of `ensureStoreRoot` for the
+  // same reason `init` does it: a refused `promote ../evil x/y` that still built
+  // a store on its way to saying no is a rejected command that changed the world.
+  validatePromoteRequest({ from, to, reserved: reservedNamespaces(), env })
+
+  ensureStoreRoot(env)
+  registerBuiltinTemplates(env)
+
+  const result = promoteTemplatePackage({ from, to, reserved: reservedNamespaces(), env })
+  return { result: { ok: true, ...result }, exitCode: EXIT.OK }
+}

package/src/cli/commands/render.js

@@ -0,0 +1,31 @@
+import { readSource } from '../../delivery/read.js'
+import { resolveCreatedAt } from '../../core/ir.js'
+import { compileDocument } from '../../render/compile.js'
+import { installTemplateStore } from '../../delivery/template-package.js'
+import { deliver } from '../deliver.js'
+
+/**
+ * `kamishibai render <input> [-o out.html] [--project name]`
+ *
+ * Renders, archives the canonical copy into the central store, and writes the
+ * delivery copy — the two are byte-identical by construction (CONTRACT B3).
+ *
+ * @returns {Promise<{result: object, exitCode: number}>}
+ */
+export async function renderCommand(inputSpec, options = {}, env = process.env) {
+  // The store joins the resolution chain before anything is resolved (F3 D1):
+  // without this, a package sitting in the namespace answers
+  // `KSB_TEMPLATE_NOT_FOUND` — the exact failure 量測報告 §5.2 measured.
+  installTemplateStore(env)
+  const { source, format, slug } = readSource(inputSpec)
+
+  const { html, slides } = await compileDocument({
+    source,
+    format,
+    template: options.template,
+    generator: options.generator,
+    createdAt: resolveCreatedAt(env),
+  })
+
+  return deliver({ html, slides, slug, options, env })
+}

package/src/cli/commands/replay.js

@@ -0,0 +1,49 @@
+import { basename, extname } from 'node:path'
+import { readArtifact } from '../../delivery/read.js'
+import { readEmbeddedIr } from '../../parser/artifact.js'
+import { validateIr } from '../../core/validate.js'
+import { replayCreatedAt, templateKeyOf } from '../../core/ir.js'
+import { renderWithTemplatePackage, resolveTemplate } from '../../render/index.js'
+import { installTemplateStore } from '../../delivery/template-package.js'
+import { EXIT } from '../../core/errors.js'
+import { deliver } from '../deliver.js'
+
+/**
+ * `kamishibai replay <artifact> [-o out.html]`
+ *
+ * Re-renders an artifact from its own embedded IR (SPEC §7.3). With
+ * `KAMISHIBAI_BUILD_TIME` pinned the result is byte-identical to the original
+ * render (CONTRACT B6) — which is what makes re-skinning and engine upgrades
+ * verifiable rather than hopeful.
+ *
+ * @returns {Promise<{result: object, exitCode: number}>}
+ */
+export async function replayCommand(target, options = {}, env = process.env) {
+  // 換皮 is the whole point of `replay`, so the skins the store holds have to be
+  // reachable from here too (F3 D1) — a chain wired only into `render` would
+  // make store packages re-renderable exactly never.
+  installTemplateStore(env)
+  const { html: source, path } = readArtifact(target)
+  const ir = readEmbeddedIr(source, path)
+
+  // The template is resolved **before** the IR is validated, because resolving
+  // it is what loads the package's `x-*` plugin blocks into the registry the IR
+  // schema is generated from (F3 D3). Validating first would judge an artifact
+  // against a vocabulary smaller than the one it was drawn in, and reject its
+  // own plugin blocks as unknown types — 換皮 failing on exactly the artifacts
+  // the extension mechanism exists to produce.
+  const template = await resolveTemplate(options.template ?? templateKeyOf(ir))
+
+  const { errors } = validateIr(ir)
+  if (errors.length > 0) return { result: { ok: false, errors }, exitCode: EXIT.VALIDATION }
+
+  const { html, slides } = await renderWithTemplatePackage({
+    template,
+    doc: ir.doc,
+    createdAt: replayCreatedAt(env, ir),
+    generator: options.generator ?? ir.generator,
+  })
+
+  const slug = basename(path, extname(path)) || 'document'
+  return deliver({ html, slides, slug, options, env })
+}

package/src/cli/commands/schema.js

@@ -0,0 +1,10 @@
+import { irSchema } from '../../core/schema.js'
+import { EXIT } from '../../core/errors.js'
+
+/**
+ * `kamishibai schema` — emits the IR JSON Schema itself, so both the human and
+ * the `--json` path show the same object.
+ */
+export function schemaCommand() {
+  return { result: irSchema(), exitCode: EXIT.OK }
+}

package/src/cli/commands/serve.js

@@ -0,0 +1,178 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { CODES, EXIT, KsbError, usageError } from '../../core/errors.js'
+import { STDIN_SPEC } from '../../delivery/read.js'
+import { resolveProject } from '../../delivery/project.js'
+import { registerServe } from '../../delivery/run.js'
+import { registerBuiltinTemplates } from '../registry.js'
+
+/**
+ * `kamishibai serve <input> [--port N]` (CONTRACT E1).
+ *
+ * The command starts a **detached** preview server and returns: the shell (and
+ * the Agent driving it) gets its prompt back, and the server's existence is
+ * recorded in the pidfile so `close` can end it later. The alternative — a
+ * foreground process — makes `serve` unusable from an Agent loop and makes
+ * "stop it" mean "find the terminal you started it in".
+ *
+ * Failure to *start* is reported synchronously, with the daemon's own KSB_
+ * finding: printing a URL that nothing answers on would be the reassuring lie
+ * this SDK keeps refusing to tell.
+ */
+
+const DAEMON = fileURLToPath(new URL('../../serve/daemon.js', import.meta.url))
+
+/** How long to wait for the daemon to report a listening port. */
+export const HANDSHAKE_TIMEOUT_MS = 20_000
+
+/** `--port` arrives as a string; the boundary is where it stops being one. */
+const parsePort = (value) => {
+  if (value === undefined) return 0
+  const text = String(value)
+  if (!/^\d+$/.test(text) || Number(text) < 1 || Number(text) > 65535) {
+    throw new KsbError({
+      code: CODES.SERVE_PORT_INVALID,
+      message: `--port 必須是 1–65535 的整數，收到 ${JSON.stringify(value)}`,
+      exitCode: EXIT.USAGE,
+    })
+  }
+  return Number(text)
+}
+
+const startFailed = (message) =>
+  new KsbError({ code: CODES.SERVE_START_FAILED, message, exitCode: EXIT.VALIDATION })
+
+/**
+ * Spawn the daemon and wait for its one handshake line.
+ *
+ * stdout is a pipe only until the handshake lands; it is then destroyed and the
+ * child unref'd, so the parent's event loop is free to exit while the server
+ * keeps running. stderr is discarded for the same reason a detached process
+ * must never hold a pipe nobody drains: it would eventually block on a full
+ * buffer and the preview would freeze for no visible reason.
+ */
+const spawnDaemon = (args, env) =>
+  new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, [DAEMON, ...args], {
+      detached: true,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env,
+    })
+
+    let buffer = ''
+    let settled = false
+
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      child.stdout.removeAllListeners()
+      child.removeAllListeners('error')
+      child.removeAllListeners('exit')
+      fn(value)
+    }
+
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGTERM')
+      } catch {
+        // Already gone; nothing to stop.
+      }
+      finish(rejectPromise, startFailed(`daemon 在 ${HANDSHAKE_TIMEOUT_MS}ms 內沒有回報監聽位址`))
+    }, HANDSHAKE_TIMEOUT_MS)
+
+    child.on('error', (cause) => finish(rejectPromise, startFailed(`無法啟動 daemon：${cause.message}`)))
+
+    // The give-up signal is the *stream* ending, not the process exiting. A
+    // daemon that reports a failed start writes its finding and then exits, and
+    // those two events race: keying off `exit` would sometimes discard the real
+    // KSB_ diagnosis and report a generic "it died" instead. Stream order does
+    // guarantee that every buffered byte is emitted before `close`.
+    let exitCode = null
+    child.on('exit', (code) => {
+      exitCode = code
+    })
+    child.stdout.on('close', () =>
+      finish(rejectPromise, startFailed(`daemon 在回報監聽位址前就結束了（exit ${exitCode}）`)),
+    )
+
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk
+      const newline = buffer.indexOf('\n')
+      if (newline === -1) return
+      const line = buffer.slice(0, newline)
+      let payload
+      try {
+        payload = JSON.parse(line)
+      } catch (cause) {
+        finish(rejectPromise, startFailed(`daemon 回報了無法解析的訊息：${cause.message}`))
+        return
+      }
+      finish(resolvePromise, { child, payload })
+    })
+  })
+
+/**
+ * @returns {Promise<{result: object, exitCode: number}>}
+ */
+export async function serveCommand(inputSpec, options = {}, env = process.env, cwd = process.cwd()) {
+  if (inputSpec === STDIN_SPEC) {
+    throw usageError('serve 需要一個可監看的來源檔，stdin（`-`）無法監看')
+  }
+  const input = resolve(String(inputSpec))
+  if (!existsSync(input)) {
+    throw new KsbError({
+      code: CODES.INPUT_NOT_FOUND,
+      message: `input not found: ${inputSpec}`,
+      exitCode: EXIT.USAGE,
+    })
+  }
+
+  const port = parsePort(options.port)
+  const project = resolveProject({ project: options.project, cwd })
+  registerBuiltinTemplates(env)
+
+  const args = ['--input', input, '--project', project.name, '--port', String(port)]
+  if (options.template !== undefined) args.push('--template', options.template)
+  if (options.generator !== undefined) args.push('--generator', options.generator)
+
+  const { child, payload } = await spawnDaemon(args, env)
+
+  if (payload?.ok !== true) {
+    child.stdout.destroy()
+    child.unref()
+    return {
+      result: { ok: false, errors: payload?.errors ?? [] },
+      exitCode: payload?.exitCode ?? EXIT.VALIDATION,
+    }
+  }
+
+  registerServe(
+    {
+      pid: payload.pid,
+      port: payload.port,
+      url: payload.url,
+      input,
+      artifact: payload.artifact,
+      startedAt: new Date().toISOString(),
+    },
+    env,
+  )
+
+  child.stdout.destroy()
+  child.unref()
+
+  return {
+    result: {
+      ok: true,
+      url: payload.url,
+      pid: payload.pid,
+      port: payload.port,
+      artifact: payload.artifact,
+    },
+    exitCode: EXIT.OK,
+  }
+}

package/src/cli/commands/setup.js

@@ -0,0 +1,64 @@
+import { execFileSync } from 'node:child_process'
+import { EXIT } from '../../core/errors.js'
+import { resolveHome } from '../../delivery/home.js'
+import { ensureStoreRoot } from '../../delivery/store.js'
+import { BROWSER_SETUP_COMMAND, browserMissingError, probeBrowser } from '../../export/browser.js'
+import { registerBuiltinTemplates } from '../registry.js'
+
+/**
+ * `kamishibai setup [--dry-run]` — SPEC §10.1「初始化環境（建中央儲存庫、裝渲染依賴）」.
+ *
+ * The browser state is *probed*, never assumed: this command exists so that the
+ * answer to "can this machine export?" is one command away, and a `setup` that
+ * reported success without launching a browser would be exactly the reassuring
+ * lie that D4 forbids.
+ */
+
+/** The three states this command can honestly report. */
+export const BROWSER_STATES = Object.freeze(['present', 'installed', 'missing'])
+
+const runInstall = () => {
+  const [command, ...args] = BROWSER_SETUP_COMMAND.split(' ')
+  execFileSync(command, args, { stdio: 'ignore' })
+}
+
+/**
+ * @returns {Promise<{result: {ok: true, home: string, browser: string, command: string},
+ *   exitCode: number}>}
+ */
+export async function setupCommand(options = {}, env = process.env) {
+  const dryRun = options.dryRun === true
+  const home = dryRun ? resolveHome(env) : ensureStoreRoot(env).root
+
+  // Initialising the environment includes populating the template namespace
+  // (CONTRACT E3): a store without `templates/` is only half a store. Skipped
+  // under `--dry-run`, which must not create so much as a directory.
+  if (!dryRun) registerBuiltinTemplates(env)
+
+  const probe = await probeBrowser()
+  if (probe.available) {
+    return {
+      result: { ok: true, home, browser: 'present', command: BROWSER_SETUP_COMMAND },
+      exitCode: EXIT.OK,
+    }
+  }
+  if (dryRun) {
+    return {
+      result: { ok: true, home, browser: 'missing', command: BROWSER_SETUP_COMMAND },
+      exitCode: EXIT.OK,
+    }
+  }
+
+  try {
+    runInstall()
+  } catch (cause) {
+    throw browserMissingError(`\`${BROWSER_SETUP_COMMAND}\` 執行失敗（${cause.message}）`)
+  }
+  const after = await probeBrowser()
+  if (!after.available) throw browserMissingError('安裝指令跑完了，瀏覽器仍然啟動不起來')
+
+  return {
+    result: { ok: true, home, browser: 'installed', command: BROWSER_SETUP_COMMAND },
+    exitCode: EXIT.OK,
+  }
+}