@kamishibai/sdk 0.1.1

package/src/cli/commands/snapshot.js

@@ -0,0 +1,29 @@
+import { usageError } from '../../core/errors.js'
+import { snapshotArtifact } from '../../export/index.js'
+
+/**
+ * `--slide` arrives as a string from the command line. It is parsed here, at
+ * the boundary, so the export layer only ever sees an integer or nothing —
+ * `--slide abc` must be a usage error, not a `NaN` that quietly snapshots
+ * whatever `handles[NaN - 1]` happens to be.
+ */
+const parseSlide = (value) => {
+  if (value === undefined) return undefined
+  if (!/^[1-9]\d*$/.test(String(value))) {
+    throw usageError(`--slide 必須是正整數，收到 ${JSON.stringify(value)}`)
+  }
+  return Number(value)
+}
+
+/**
+ * `kamishibai snapshot <artifact> [-o out.png] [--slide N]`
+ *
+ * @returns {Promise<{result: object, exitCode: number}>}
+ */
+export async function snapshotCommand(target, options = {}) {
+  return await snapshotArtifact({
+    target,
+    out: options.out,
+    slide: parseSlide(options.slide),
+  })
+}

package/src/cli/commands/templates.js

@@ -0,0 +1,75 @@
+import { EXIT } from '../../core/errors.js'
+import { isDraftKey } from '../../delivery/template-format.js'
+import { readTemplatePackages } from '../../delivery/templates.js'
+import { isReservedKey } from '../../render/index.js'
+import { registerBuiltinTemplates } from '../registry.js'
+
+/**
+ * CONTRACT E3 — the four keys of a template listing entry, in output order,
+ * plus F3's three, appended (additive-only: the four never move or change meaning).
+ *
+ * `layout` because since F2a the 文體 decides the shape of the page, so "which
+ * template shall I use?" is unanswerable without it. `hasCode` because the
+ * trust model is 安裝即信任 with no sandbox (CONTRACT P5): what a listing still
+ * owes a reader is the ability to see which of these packages runs code when it
+ * draws, without opening a single file.
+ *
+ * `reserved` for the same reason one layer further out (封緘 F2). A package
+ * planted at `kami/anything` is refused by the resolver — but the listing is
+ * where a human decides what to draw with, and until this key existed the
+ * squatter appeared there **indistinguishable from the two official packages**:
+ * same namespace, same shape, same everything. Refusing it at render time and
+ * dressing it as official at listing time is the worst of both, so the listing
+ * says what it is. Marked, not filtered: this surface's whole charter is that it
+ * reports the disk (E3), and hiding a package a user really does have installed
+ * would make the one surface that could warn them the one that concealed it.
+ *
+ * `draft` is F7a's, appended by the same rule and for the same shape of reason
+ * (CONTRACT F7a H1). The 臨摹 loop leaves half-cut skins in the store on purpose
+ * — that is what a workspace is — and until this key existed they sat in the
+ * listing wearing exactly the face of a finished package. The marker is the
+ * store's only way to answer 「這張皮是成品還是我昨天畫到一半的」, and it is the
+ * flag `promote` keys on, so listing and command agree by construction.
+ */
+export const TEMPLATE_KEYS = Object.freeze([
+  'namespace',
+  'name',
+  'version',
+  'root',
+  'layout',
+  'hasCode',
+  'reserved',
+  'draft',
+])
+
+/**
+ * `kamishibai templates [--json]` (CONTRACT E3 / VC2).
+ *
+ * Reads the *store*, not the engine's internal registry, after making sure the
+ * built-ins are registered. That order is the point: the listing has to be an
+ * answer about what is installed on this machine — a listing computed from the
+ * bundled modules would happily report templates whose packages were never
+ * written, and the namespace would then be a claim nobody checks.
+ *
+ * `options` carries no flag this command reads — `--json` is the emitter's, not
+ * the command's — but the slot is **not** dead: every command module in this
+ * directory takes `(…args, options, env)`, and `src/cli/index.js` passes them
+ * positionally. Dropping the parameter would silently slide `options` into
+ * `env`, and the listing would then read a store root out of a flags object.
+ *
+ * @returns {{result: Array<object>, exitCode: number}}
+ */
+export function templatesCommand(options = {}, env = process.env) {
+  registerBuiltinTemplates(env)
+  const entries = readTemplatePackages(env).map((pkg) => ({
+    namespace: pkg.namespace,
+    name: pkg.name,
+    version: pkg.version,
+    root: pkg.root,
+    layout: pkg.layout,
+    hasCode: pkg.hasCode,
+    reserved: isReservedKey(`${pkg.namespace}/${pkg.name}`),
+    draft: isDraftKey(`${pkg.namespace}/${pkg.name}`),
+  }))
+  return { result: entries, exitCode: EXIT.OK }
+}

package/src/cli/deliver.js

@@ -0,0 +1,54 @@
+import { join } from 'node:path'
+import { EXIT } from '../core/errors.js'
+import { resolveProject } from '../delivery/project.js'
+import { archiveArtifact } from '../delivery/store.js'
+import { writeArtifact } from '../delivery/write.js'
+import { registerBuiltinTemplates } from './registry.js'
+
+/**
+ * The delivery chain shared by `render` and `replay` (SPEC §8): one canonical
+ * copy into the central store, one delivery copy at the caller's path, and the
+ * copy's location recorded in the store index.
+ *
+ * The project is resolved *before* anything is written: a rejected `--project`
+ * must not leave a half-delivered artifact behind.
+ *
+ * `slides` joins the result only for deck artifacts (CONTRACT C4): a document
+ * artifact must keep the pinned four-key shape exactly, so an always-present
+ * key set to 0 or null is not an option.
+ *
+ * @returns {{result: {ok: true, artifact: string, bytes: number, archived: string,
+ *   slides?: number}, exitCode: number}}
+ */
+export function deliver({
+  html,
+  slides,
+  slug,
+  options = {},
+  env = process.env,
+  cwd = process.cwd(),
+}) {
+  const project = resolveProject({ project: options.project, cwd })
+
+  const outPath = options.out ?? join('out', `${slug}.html`)
+  const { path, bytes } = writeArtifact(outPath, html)
+
+  const { path: archived } = archiveArtifact({
+    project: project.name,
+    slug,
+    html,
+    copies: [path],
+    env,
+  })
+
+  // First touch of the store registers the built-in template packages (E3), so
+  // an Agent that never ran `setup` still finds a populated namespace. It is a
+  // no-op once the manifests match, which is the normal case.
+  registerBuiltinTemplates(env)
+
+  const result = { ok: true, artifact: path, bytes, archived }
+  return {
+    result: Number.isInteger(slides) ? { ...result, slides } : result,
+    exitCode: EXIT.OK,
+  }
+}

package/src/cli/emit.js

@@ -0,0 +1,29 @@
+import { EXIT, KsbError, ROOT_PATH, CODES } from '../core/errors.js'
+import { formatResult } from './format.js'
+
+/** Write a command result to stdout in the requested shape and set the exit code. */
+export function emit({ command, result, json, exitCode = EXIT.OK }) {
+  const text = json ? JSON.stringify(result) : formatResult(command, result)
+  process.stdout.write(text.endsWith('\n') ? text : `${text}\n`)
+  process.exitCode = exitCode
+}
+
+/** Normalise any thrown value into the pinned failure result object. */
+export function toFailure(error) {
+  if (error instanceof KsbError) {
+    return { result: { ok: false, errors: [error.toFinding()] }, exitCode: error.exitCode }
+  }
+  return {
+    result: {
+      ok: false,
+      errors: [
+        {
+          path: ROOT_PATH,
+          code: CODES.PARSE_FAILED,
+          message: error?.message ?? String(error),
+        },
+      ],
+    },
+    exitCode: EXIT.VALIDATION,
+  }
+}

package/src/cli/format.js

@@ -0,0 +1,153 @@
+/**
+ * The single formatter. Both output paths (`--json` and human-readable) consume
+ * the *same* result object: `--json` serialises it, humans get this rendering.
+ * Nothing may be computed here that the JSON path cannot show.
+ */
+
+const formatErrors = (errors) =>
+  [
+    `✖ ${errors.length} 個問題：`,
+    ...errors.map((e) => `  - [${e.code}] ${e.path}: ${e.message}`),
+  ].join('\n')
+
+/**
+ * `render` / `replay` share one result shape, so they share one rendering.
+ * Every extension key has to surface here too — a key that lives only in
+ * `--json` is exactly the two-path drift this formatter exists to prevent.
+ */
+const formatDelivery = (verb) => (r) =>
+  [
+    `✔ 已${verb} → ${r.artifact}（${r.bytes} bytes${
+      Number.isInteger(r.slides) ? `，${r.slides} 張` : ''
+    }）`,
+    `  正本 → ${r.archived}`,
+  ].join('\n')
+
+const formatListEntry = (e) =>
+  [
+    `• ${e.name}　${e.template}　${e.createdAt}　${e.generator}`,
+    `  正本 → ${e.artifact}`,
+    ...e.copies.map((copy) => `  副本 → ${copy}`),
+  ].join('\n')
+
+const formatList = (entries) =>
+  entries.length === 0 ? '（此專案尚無產物）' : entries.map(formatListEntry).join('\n')
+
+/** Every key of the pinned export/snapshot shapes has to reach human output too. */
+const formatExport = (r) => `✔ 已匯出 ${r.format} → ${r.artifact}`
+const formatSnapshot = (r) => `✔ 已截圖 → ${r.artifact}（${r.width}×${r.height}）`
+const formatSetup = (r) =>
+  [
+    `✔ 中央儲存庫 → ${r.home}`,
+    `  瀏覽器：${r.browser}（安裝指令：${r.command}）`,
+  ].join('\n')
+
+/**
+ * S5 surfaces. Every key of each pinned JSON shape has to appear here too —
+ * the `--json` path and the human path are the same result object rendered
+ * twice, and a key that only one of them shows is the drift this file exists
+ * to prevent.
+ */
+const formatServe = (r) =>
+  [
+    `✔ 預覽伺服器 → ${r.url}`,
+    `  pid ${r.pid}　port ${r.port}`,
+    `  正本 → ${r.artifact}`,
+  ].join('\n')
+
+const formatClose = (r) =>
+  [
+    r.closed.length === 0 ? '✔ 沒有執行中的預覽伺服器' : `✔ 已終止 ${r.closed.join('、')}`,
+    ...(r.stale.length === 0 ? [] : [`  已清掉的殘留紀錄：${r.stale.join('、')}`]),
+  ].join('\n')
+
+const formatCommentEntry = (e) => `• [${e.status}] ${e.id}　${e.blockId}　${e.ts}\n  ${e.text}`
+
+/** `comments` lists an array; `comments add|resolve` answer with one entry. */
+const formatComments = (result) => {
+  if (!Array.isArray(result)) return formatCommentEntry(result)
+  return result.length === 0 ? '（此產物尚無留言）' : result.map(formatCommentEntry).join('\n')
+}
+
+/**
+ * Every key of the pinned template-listing shape reaches human output too —
+ * including F3's two. `hasCode` in particular: it is the one field whose whole
+ * purpose is to be *seen* (CONTRACT P5), so letting it live only in `--json`
+ * would defeat the field rather than merely drift from it.
+ */
+const formatTemplateEntry = (t) =>
+  `• ${t.namespace}/${t.name}@${t.version}　root=${t.root === '' ? '（不限）' : t.root}` +
+  `　layout=${t.layout === '' ? '（未宣告）' : t.layout}　${t.hasCode ? 'hasCode=帶碼' : 'hasCode=純資料'}` +
+  (t.reserved ? '　（冒用出廠名，無法載入）' : '') +
+  (t.draft ? '　（臨摹工作區草稿，promote 後轉正）' : '')
+
+const formatTemplates = (entries) =>
+  entries.length === 0 ? '（尚未註冊任何模板包）' : entries.map(formatTemplateEntry).join('\n')
+
+/** `init` answers with the package it just wrote and the file to render first. */
+const formatInit = (r) =>
+  [
+    `✔ 已建立模板包 ${r.template} → ${r.dir}`,
+    `  檔案：${r.files.join('、')}`,
+    `  開箱即用：kamishibai render ${r.source} -t ${r.template}`,
+  ].join('\n')
+
+/** `promote` answers with where the draft went, and what to draw with now. */
+const formatPromote = (r) =>
+  [
+    `✔ 已轉正 ${r.from} → ${r.to}（${r.dir}）`,
+    `  manifest 已改寫：${r.manifest}`,
+    `  ${r.from} 原位已不存在；改用：kamishibai render <來源> -t ${r.to}`,
+  ].join('\n')
+
+const formatDebug = (r) =>
+  [
+    `✔ 中央儲存庫 → ${r.home}`,
+    `  模板包：${r.templates}`,
+    `  瀏覽器：${r.browser}`,
+    `  引擎：${r.engine}`,
+    `  執行中的預覽伺服器：${r.servers}`,
+  ].join('\n')
+
+/**
+ * `lint --rules` lists the gate itself. Same array the `--json` path serialises:
+ * a rule that only one of the two paths shows is the drift this file prevents.
+ */
+const formatRuleEntry = (rule) =>
+  [
+    `• [${rule.code}]　scope=${rule.scope}　pattern=${rule.pattern}` +
+      // F7b: only a gate rule carries a declaration site, and only a gate rule
+      // grows the line. The ten rules that were here before F7b render byte for
+      // byte as they did, which is what「既有輸出格式不破」means.
+      (rule.gate === undefined ? '' : `　gate=${rule.gate}`),
+    `  ${rule.note}`,
+  ].join('\n')
+
+const formatLint = (r) =>
+  Array.isArray(r) ? r.map(formatRuleEntry).join('\n') : `✔ lint 通過：${r.artifact}`
+
+const RENDERERS = Object.freeze({
+  render: formatDelivery('渲染'),
+  replay: formatDelivery('重繪'),
+  export: formatExport,
+  snapshot: formatSnapshot,
+  setup: formatSetup,
+  lint: formatLint,
+  example: (r) => r.example,
+  schema: (r) => JSON.stringify(r, null, 2),
+  list: formatList,
+  open: (r) => r.path,
+  serve: formatServe,
+  close: formatClose,
+  comments: formatComments,
+  templates: formatTemplates,
+  init: formatInit,
+  promote: formatPromote,
+  debug: formatDebug,
+})
+
+export function formatResult(command, result) {
+  if (result && result.ok === false) return formatErrors(result.errors ?? [])
+  const renderer = RENDERERS[command]
+  return renderer ? renderer(result) : JSON.stringify(result, null, 2)
+}