@kamishibai/sdk 0.1.1

package/src/delivery/store.js

@@ -0,0 +1,219 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { engineVersion } from '../core/version.js'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { writeFileAtomic } from './atomic.js'
+import { MARKER_FILENAME, markerPath, projectDir, resolveHome } from './home.js'
+
+/**
+ * The central artifact store (SPEC §6.1 / §8). `render` and `replay` archive
+ * the canonical copy here; `list`, `open` and future replay/re-skin flows read
+ * from it. Nothing in this module reaches outside `resolveHome()`.
+ */
+
+export const ARTIFACT_EXT = '.html'
+/** Sidecar recording where delivery copies of an artifact were written. */
+export const COPIES_SUFFIX = '.copies.json'
+
+const markerContent = () => `${MARKER_FILENAME}: kamishibai@${engineVersion()}\n`
+
+const writeFailed = (path, cause) =>
+  new KsbError({
+    code: CODES.WRITE_FAILED,
+    message: `could not write to central store at ${path}: ${cause.message}`,
+    exitCode: EXIT.VALIDATION,
+  })
+
+/**
+ * CONTRACT B2 — the first-touch safety gate.
+ *
+ * `~/.kamishibai` is a protected asset: a store that already exists belongs to
+ * the user, so we only ever *add* to it. The marker is written exactly once, at
+ * creation; back-filling it into an existing store would be a mutation of
+ * someone else's directory, and would also lie about who created it.
+ *
+ * @returns {{root: string, created: boolean}}
+ */
+export function ensureStoreRoot(env = process.env) {
+  const root = resolveHome(env)
+  if (existsSync(root)) return { root, created: false }
+  try {
+    mkdirSync(root, { recursive: true })
+    writeFileSync(markerPath(env), markerContent(), 'utf8')
+  } catch (cause) {
+    throw writeFailed(root, cause)
+  }
+  return { root, created: true }
+}
+
+/** Compact UTC stamp, e.g. `20260816T195453123Z`. */
+export const archiveStamp = (now = new Date()) => now.toISOString().replace(/[-:.]/g, '')
+
+/** How many suffixed names to try before admitting defeat. */
+const MAX_NAME_ATTEMPTS = 1000
+
+/** `<slug>`, then `<slug>-<stamp>`, then `<slug>-<stamp>-2`, `-3`, … */
+function* candidateNames(slug, now) {
+  yield slug
+  const stamped = `${slug}-${archiveStamp(now)}`
+  yield stamped
+  for (let n = 2; n < MAX_NAME_ATTEMPTS; n += 1) yield `${stamped}-${n}`
+}
+
+/**
+ * Write the canonical copy under the first name that is free (CONTRACT B2).
+ *
+ * The exclusive `wx` flag *is* the check: an `existsSync` test followed by a
+ * default (truncating) write leaves a window in which two concurrent renders
+ * of the same slug both see "free" and the second silently erases the first.
+ * Artifacts in the central store are permanent records, so the filesystem —
+ * not a prior lookup — has to be the one that says the name was taken.
+ */
+const writeExclusive = (dir, slug, html, now) => {
+  for (const name of candidateNames(slug, now)) {
+    const path = join(dir, `${name}${ARTIFACT_EXT}`)
+    try {
+      writeFileSync(path, html, { encoding: 'utf8', flag: 'wx' })
+      return { name, path }
+    } catch (cause) {
+      if (cause.code !== 'EEXIST') throw writeFailed(path, cause)
+    }
+  }
+  throw writeFailed(
+    join(dir, slug),
+    new Error(`no free artifact name after ${MAX_NAME_ATTEMPTS} attempts`),
+  )
+}
+
+/**
+ * Archive the canonical copy of a rendered artifact.
+ *
+ * @param {{project: string, slug: string, html: string, copies?: string[], env?: object}} input
+ * @returns {{name: string, path: string, dir: string}}
+ */
+export function archiveArtifact({ project, slug, html, copies = [], env = process.env, now }) {
+  ensureStoreRoot(env)
+  const dir = projectDir(project, env)
+  try {
+    mkdirSync(dir, { recursive: true })
+  } catch (cause) {
+    throw writeFailed(dir, cause)
+  }
+
+  const { name, path } = writeExclusive(dir, slug, html, now)
+  mergeCopiesIndex(dir, name, copies, path)
+  return { name, path, dir }
+}
+
+/**
+ * Refresh a canonical copy **that the calling session itself created** with a
+ * newer render of the same source (CONTRACT E1, seal patch F1).
+ *
+ * This is the one sanctioned overwrite of an artifact, and the boundary matters
+ * more than the mechanism. The `wx` law above protects *history*: an artifact
+ * somebody else's run archived is a record, and records are never rewritten. A
+ * live `serve` session's own copy is not history yet — it is the working
+ * document being edited, and freezing it at the first render is what let the
+ * served IR and the canonical IR drift apart. Comments anchored to a block the
+ * canonical did not contain were then unresolvable by the very artifact they
+ * were filed against.
+ *
+ * The caller owns the "did I create this?" judgement; this function only
+ * guarantees the write is all-or-nothing (tmp + rename), so a reader — or a
+ * `comments add` running at that instant — sees one whole render or the other,
+ * never a torn one.
+ *
+ * @param {string} artifactPath the session's own canonical copy
+ * @param {string} html the newer render
+ * @returns {string} the artifact path
+ */
+export function refreshArtifact(artifactPath, html) {
+  try {
+    return writeFileAtomic(artifactPath, html)
+  } catch (cause) {
+    throw writeFailed(artifactPath, cause)
+  }
+}
+
+/**
+ * Record delivery copies against a claimed name, merging with whatever the
+ * index already held (CONTRACT B2 — 已存在→不動既有檔案、僅追加).
+ *
+ * A name freed by a deleted artifact can be re-claimed by `wx`, and its sidecar
+ * may outlive the artifact. Writing the new list flat would silently drop the
+ * earlier delivery history — the index is a cumulative record, not a snapshot
+ * of the last render. Overwriting is only permitted because the content written
+ * is a superset of what was there.
+ *
+ * And because it *is* an overwrite, it goes through the atomic writer (D6): the
+ * one legal truncation in the store must still be all-or-nothing, or a crash
+ * mid-write turns a cumulative record into an empty one.
+ */
+const mergeCopiesIndex = (dir, name, copies, artifactPath) => {
+  const merged = [...new Set([...readCopies(dir, name), ...copies])]
+  try {
+    writeFileAtomic(join(dir, `${name}${COPIES_SUFFIX}`), `${JSON.stringify(merged)}\n`)
+  } catch (cause) {
+    throw writeFailed(artifactPath, cause)
+  }
+}
+
+const readCopies = (dir, name) => {
+  const sidecar = join(dir, `${name}${COPIES_SUFFIX}`)
+  if (!existsSync(sidecar)) return []
+  try {
+    const parsed = JSON.parse(readFileSync(sidecar, 'utf8'))
+    return Array.isArray(parsed) ? parsed.filter((p) => typeof p === 'string') : []
+  } catch {
+    // A corrupt sidecar must not hide the artifact itself: copies are an index,
+    // the artifact is the record.
+    return []
+  }
+}
+
+/**
+ * Raw store entries for a project, newest last. HTML is returned so callers can
+ * read the embedded IR without this layer needing a parser.
+ *
+ * @returns {Array<{name: string, path: string, html: string, copies: string[], mtimeMs: number}>}
+ */
+export function readEntries({ project, env = process.env }) {
+  const dir = projectDir(project, env)
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir)
+    .filter((file) => file.endsWith(ARTIFACT_EXT))
+    .map((file) => {
+      const path = join(dir, file)
+      const name = basename(file, ARTIFACT_EXT)
+      return {
+        name,
+        path,
+        html: readFileSync(path, 'utf8'),
+        copies: readCopies(dir, name),
+        mtimeMs: statSync(path).mtimeMs,
+      }
+    })
+    .sort((a, b) => a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name))
+}
+
+/** Verbatim CONTRACT token — `open latest` resolves to the newest artifact. */
+export const LATEST = 'latest'
+
+/**
+ * Resolve `<name|latest>` against a project's store.
+ * @returns {{name: string, path: string}|null} null when nothing matches
+ */
+export function findArtifact({ project, name, env = process.env }) {
+  const entries = readEntries({ project, env })
+  if (entries.length === 0) return null
+  if (name === LATEST) {
+    const newest = entries[entries.length - 1]
+    return { name: newest.name, path: newest.path }
+  }
+  const wanted = String(name ?? '').endsWith(ARTIFACT_EXT)
+    ? basename(String(name), ARTIFACT_EXT)
+    : String(name ?? '')
+  const hit = entries.find((entry) => entry.name === wanted)
+  return hit ? { name: hit.name, path: hit.path } : null
+}

package/src/delivery/template-extensions.js

@@ -0,0 +1,183 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { blockModule, blockTypes, registerBlockModule } from '../blocks/index.js'
+import { PACKAGE_FILES } from './template-format.js'
+
+/**
+ * The opt-in half of a template package: JS 轉子 override and `x-*` plugin
+ * blocks (CONTRACT D3, wayfinder issue 13 裁決 4).
+ *
+ * There is no sandbox, and that is a decision rather than an omission: 安裝即
+ * 信任 is the Obsidian-plugin model the user settled on (issue 13 裁決 4, this
+ * slice's P5). What is *not* optional is that a broken extension fails as an
+ * extension. Letting an `import()` rejection reach the generic handler would
+ * report `KSB_PARSE_FAILED` — telling an agent its document could not be parsed
+ * when the truth is a package on disk, which is the mistake F4 B9 named and
+ * gave `KSB_COMMAND_LOAD_FAILED` its own code to avoid.
+ *
+ * The two halves land in different places, and the difference is not
+ * incidental. A **plugin block** is new vocabulary: it goes into the global
+ * block registry through the same public entry point a third party would use
+ * (CONTRACT A4), and so wears the `x-` prefix and passes the same shape check.
+ * An **override** is *this template's* answer for a type the SDK already has —
+ * `kami/long-form` drawing callouts its own way — so it is template-scoped and
+ * reaches the pipeline through the render context. Registering it globally
+ * would make one installed package silently change how every other template
+ * draws.
+ */
+
+const failed = (message) =>
+  new KsbError({
+    code: CODES.TEMPLATE_EXTENSION_FAILED,
+    message,
+    path: 'doc.meta.template',
+    exitCode: EXIT.VALIDATION,
+  })
+
+/** Plugin types this process already registered, per package — import is once. */
+const registered = new Set()
+
+/** Test hygiene: forget which packages registered which plugin types. */
+export const resetLoadedExtensions = () => registered.clear()
+
+const importDefault = async (file, what) => {
+  let module
+  try {
+    module = await import(pathToFileURL(file).href)
+  } catch (cause) {
+    throw failed(`${what} 載入失敗：${cause?.message ?? String(cause)}（檔案：${file}）`)
+  }
+  const mod = module?.default
+  if (mod === null || typeof mod !== 'object') {
+    throw failed(`${what} 必須 default export 一個模組物件（檔案：${file}）`)
+  }
+  return mod
+}
+
+const subdirectories = (dir) => {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+  return readdirSync(dir).filter((entry) => statSync(join(dir, entry)).isDirectory()).sort()
+}
+
+const jsFiles = (dir) => {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+  return readdirSync(dir).filter((entry) => entry.endsWith('.js')).sort()
+}
+
+/**
+ * Load `rotors/<型別>/override.js` — this template's own conversion for a type.
+ *
+ * An override of a type nobody registered is refused rather than kept: it can
+ * never fire, so keeping it would leave the author believing their callout was
+ * being drawn their way while the factory rotor drew it the other way, with
+ * exit 0 and a clean `lint`. That is the same invisible-divergence failure the
+ * whole guard family in this SDK exists to make loud.
+ */
+async function loadOverrides({ dir, key }) {
+  const root = join(dir, PACKAGE_FILES.ROTORS_DIR)
+  const table = {}
+  for (const type of subdirectories(root)) {
+    const file = join(root, type, PACKAGE_FILES.OVERRIDE)
+    if (!existsSync(file)) continue
+    const what = `模板包 ${key} 的轉子 override \`${type}\``
+    const mod = await importDefault(file, what)
+    if (mod.type !== type) {
+      throw failed(`${what} 自稱 \`${mod.type}\`，與所在目錄不符——一個永遠指不到另一個。`)
+    }
+    if (typeof mod.render !== 'function') {
+      throw failed(`${what} 缺少 \`render\` 函式（轉子的全部工作就是這一個）。`)
+    }
+    if (blockModule(type) === undefined) {
+      throw failed(
+        `${what} 覆寫的型別沒有人註冊；已註冊的型別：${blockTypes().join(', ')}。` +
+          '覆寫一個不存在的型別永遠不會生效，而產物仍舊畫得出來——所以在這裡報。',
+      )
+    }
+    table[type] = mod.render
+  }
+  return Object.freeze(table)
+}
+
+/**
+ * Load `plugins/<型別>.js` — new block vocabulary the package brings with it.
+ *
+ * Registration goes through `registerBlockModule`, the same public entry point
+ * CONTRACT A4 proves a third party can reach without editing a file inside the
+ * SDK. Its `TypeError` becomes a KSB_ finding here rather than a stack trace,
+ * but the *rule set* is not restated: a second copy of the shape check would be
+ * free to disagree with the one the registry actually applies.
+ */
+async function loadPlugins({ dir, key }) {
+  const root = join(dir, PACKAGE_FILES.PLUGINS_DIR)
+  const loaded = []
+  for (const entry of jsFiles(root)) {
+    const type = entry.replace(/\.js$/, '')
+    const file = join(root, entry)
+    const what = `模板包 ${key} 的 plugin block \`${type}\``
+    const mod = await importDefault(file, what)
+    if (mod.type !== type) {
+      throw failed(`${what} 自稱 \`${mod.type}\`，與檔名不符——一個永遠指不到另一個。`)
+    }
+    loaded.push(type)
+
+    const stamp = `${key}:${type}`
+    if (registered.has(stamp)) continue
+    try {
+      registerBlockModule(mod)
+    } catch (cause) {
+      throw failed(`${what} 未通過註冊表形狀校驗：${cause?.message ?? String(cause)}`)
+    }
+    registered.add(stamp)
+  }
+  return Object.freeze(loaded)
+}
+
+/**
+ * Load `chrome.js` — this package's fills for its 文體's chrome slots (F7a).
+ *
+ * Every export must be a function, and nothing here checks the *names*: the
+ * list of slots belongs to the layout, and `assertChromeSlots` already refuses
+ * a fill for a slot the 文體 does not offer, with the message that explains why
+ * a misspelling is silence rather than an error. A second copy of that rule
+ * here would be free to disagree with the one the renderer applies.
+ *
+ * What is checked is the one thing only this layer can see: that a *value* is
+ * callable. `ctx.chrome` skips a non-function silently — correct behaviour for
+ * an unfilled slot, and indistinguishable from a package that exported a
+ * string by mistake and now renders with no masthead and exit 0.
+ */
+async function loadChrome({ dir, key }) {
+  const file = join(dir, PACKAGE_FILES.CHROME)
+  if (!existsSync(file)) return Object.freeze({})
+  const what = `模板包 ${key} 的 ${PACKAGE_FILES.CHROME}`
+  const mod = await importDefault(file, what)
+  const table = {}
+  for (const [slot, fill] of Object.entries(mod)) {
+    if (typeof fill !== 'function') {
+      throw failed(
+        `${what} 的槽位 \`${slot}\` 不是函式（得到 ${typeof fill}）。` +
+          '非函式的填充會被靜靜跳過——產物照畫、exit 0、槽位空白，沒有人會發現。',
+      )
+    }
+    table[slot] = fill
+  }
+  return Object.freeze(table)
+}
+
+/**
+ * Every JS extension a package carries. Pure-data packages take the cheap path:
+ * nothing exists on any of the three paths, so nothing is imported at all.
+ *
+ * @param {{dir: string, key: string}} input
+ * @returns {Promise<{overrides: Record<string, Function>, plugins: readonly string[],
+ *   chrome: Record<string, Function>}>}
+ */
+export async function loadPackageExtensions({ dir, key }) {
+  return {
+    overrides: await loadOverrides({ dir, key }),
+    plugins: await loadPlugins({ dir, key }),
+    chrome: await loadChrome({ dir, key }),
+  }
+}

package/src/delivery/template-format.js

@@ -0,0 +1,112 @@
+/**
+ * The template package format, as constants — the one place its filenames live.
+ *
+ * It is its own module so that the reader of a package (`template-package.js`)
+ * and the loader of its JS (`template-extensions.js`) can both name the layout
+ * without importing each other. Two copies of `'manifest.toml'` is precisely
+ * how a format grows a second, slightly different spelling.
+ *
+ * The shape is wayfinder issue 13 裁決 7's 目錄形 with two engineering
+ * simplifications, recorded here because a reader comparing the two will
+ * otherwise think one of them drifted:
+ *
+ *  - `core-config.toml` and 轉子/<型別>/config are **one** file: `manifest.toml`,
+ *    the latter as its `[blockConfig.<型別>]` tables. Both are pure data, and a
+ *    single descriptor is what keeps the byte-determinism claim checkable.
+ *  - `core-style` and `stylesheet/` are **one** `stylesheet.css`: the SDK ships
+ *    no sass pipeline, and issue 13 裁決 6 leaves sass an internal-organisation
+ *    freedom rather than a public contract.
+ *
+ * Everything else is issue 13's tree with ASCII directory names: `plugins/`
+ * unchanged, 轉子/<型別>/{override} as `rotors/<型別>/override.js`, plus the
+ * 預設 md that issue 14's 補充裁定 added to the format.
+ */
+
+/** Verbatim CONTRACT constants — the package directory layout. */
+export const PACKAGE_FILES = Object.freeze({
+  MANIFEST: 'manifest.toml',
+  STYLESHEET: 'stylesheet.css',
+  DEFAULT_DOC: 'default.md',
+  ROTORS_DIR: 'rotors',
+  OVERRIDE: 'override.js',
+  PLUGINS_DIR: 'plugins',
+  /**
+   * F7a — the package's fills for its 文體's chrome slots.
+   *
+   * The third JS door, opened for the reason 臨摹 exists to find (AGENTS §3.5
+   * 「凡臨摹不出來的，就是模板語言漏考量的東西」). Until this file existed a
+   * store package's `chrome` was the literal `{}`: the masthead, the colophon
+   * and the rail were things **only a bundled template could have**, so the
+   * first real skin anyone tried to 臨摹 came out headless while the factory
+   * template it was replacing kept its header. A package format that cannot
+   * express the one region every page starts with is not a package format.
+   *
+   * A flat file rather than a directory, because a slot fill is one function
+   * and the layout — not the package — owns the list of slot names
+   * (`assertChromeSlots` refuses a name the 文體 does not offer).
+   */
+  CHROME: 'chrome.js',
+})
+
+/** Verbatim CONTRACT constant — the package descriptor's filename. */
+export const MANIFEST_FILENAME = PACKAGE_FILES.MANIFEST
+
+/**
+ * A template with no required root form carries the empty string, not a missing
+ * key. TOML has no null, and an *absent* key would be indistinguishable from a
+ * manifest written by an older engine that did not know about roots — so the
+ * "no constraint" case is stated explicitly.
+ */
+export const NO_ROOT = ''
+
+/** Default `language` when a package does not state one. */
+export const DEFAULT_LANGUAGE = 'zh-TW'
+
+/**
+ * Verbatim CONTRACT F7a constant — the 臨摹 workspace namespace.
+ *
+ * A package under `draft/` is a *work in progress*: it renders, it lints, it can
+ * be pointed at with `-t` exactly like any other package, and that is the whole
+ * point — the 臨摹 loop is `init draft/<名> → 編輯 → render + snapshot 對照 →
+ * lint 綠 → 人驗 → promote`, and every step of it needs a package that really
+ * draws. What `draft/` buys is the one thing the store had no way to say: which
+ * of the packages on this machine is a finished skin and which is a sketch
+ * somebody is still cutting.
+ *
+ * It is a *marker*, not a fence, for the same reason `reserved` is one
+ * (`cli/commands/templates.js`): this surface reports the disk. Hiding a draft
+ * would make the listing disagree with the filesystem, and refusing to render
+ * one would make the workflow impossible to walk.
+ */
+export const DRAFT_NAMESPACE = 'draft'
+
+/**
+ * Whether a key names a package in the 臨摹 workspace (CONTRACT F7a H1).
+ *
+ * One definition, called by both the listing and `promote`, for the reason
+ * `isReservedKey` states next door: two spellings of one predicate are free to
+ * drift, and the direction they drift in is the bad one — a listing that marks a
+ * package `promote` refuses to move, or a `promote` that moves one the listing
+ * never called a draft.
+ */
+export function isDraftKey(key) {
+  const split = splitTemplateKey(key)
+  return split !== null && split.namespace === DRAFT_NAMESPACE
+}
+
+/**
+ * A namespace or name segment. Anchored and free of dots on purpose: the
+ * segments are joined onto the store root, so `..` would let `-t` address any
+ * directory on the machine and read a "stylesheet" out of it.
+ */
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/
+
+/** Split `<namespace>/<name>[@version]`; null when the key is not that shape. */
+export function splitTemplateKey(key) {
+  const bare = String(key ?? '').split('@')[0]
+  const parts = bare.split('/')
+  if (parts.length !== 2) return null
+  const [namespace, name] = parts
+  if (!SEGMENT.test(namespace) || !SEGMENT.test(name)) return null
+  return { namespace, name, key: `${namespace}/${name}` }
+}