@kamishibai/sdk 0.1.1

package/src/delivery/template-scaffold.js

@@ -0,0 +1,181 @@
+import { existsSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { writeFileAtomic } from './atomic.js'
+import { knownLayouts, layoutModule } from '../layouts/index.js'
+import { templatePackageDir } from './home.js'
+import { DEFAULT_LANGUAGE, PACKAGE_FILES, splitTemplateKey } from './template-format.js'
+import { SCAFFOLD_BLUEPRINTS, SCAFFOLD_SUPPORTED_LAYOUTS } from './scaffold-blueprints.js'
+import { stringifyToml } from './toml.js'
+
+export { SCAFFOLD_BLUEPRINTS, SCAFFOLD_SUPPORTED_LAYOUTS }
+
+/**
+ * The scaffold (CONTRACT D4; wayfinder issue 13 裁決 7「必須有模板初始化腳手架」).
+ *
+ * The scaffold exists because the pure-data path is only *real* if someone can
+ * start on it. A format whose entry cost is "hand-write a TOML manifest with
+ * the right key names, guess which 文體 knobs exist, and hope the stylesheet's
+ * geometry markers are spelled the way the injector expects" is a format that
+ * everyone will fork an existing package to avoid — and then the pure-data
+ * default path is a claim rather than a practice.
+ *
+ * So what this writes is not a demo: it is a package that **renders on the way
+ * out**, and the contract pins exactly that (`render <包內預設 md> -t <該包>`
+ * succeeding, `lint` exit 0). The three files are the whole format: the
+ * declaration plus applied state, the skin, and the 預設 md that shows what the
+ * two of them look like when nobody has written any content yet.
+ */
+
+/** The 文體 a scaffolded package rides unless the caller names another. */
+export const SCAFFOLD_LAYOUT = 'article'
+
+/**
+ * `path` follows the code, not the command (CONTRACT Verbatim 四新碼 path).
+ *
+ * A namespace refusal is *about the template key* wherever it is raised, so it
+ * carries `doc.meta.template` here exactly as it does on the render path — an
+ * agent matching on the pair (code, path) must not have to learn that this one
+ * command spells the same refusal differently. `KSB_TEMPLATE_PACKAGE_EXISTS`
+ * keeps the root path because it is about the store, not about a key in a
+ * document that does not exist yet.
+ */
+const refuse = (code, message, path) =>
+  new KsbError({ code, message, ...(path === undefined ? {} : { path }), exitCode: EXIT.VALIDATION })
+
+const scaffoldManifest = ({ namespace, name, layout, engine, blueprint }) =>
+  stringifyToml({
+    name,
+    namespace,
+    version: '0.1.0',
+    engine,
+    root: blueprint.root,
+    blocks: [...blueprint.blocks],
+    layout,
+    language: DEFAULT_LANGUAGE,
+    description: `${namespace}/${name} — kamishibai 模板包骨架`,
+    maxWidth: blueprint.maxWidth,
+    measure: blueprint.measure,
+    // 轉子/<型別>/config: the callout labels are *wording*, and wording is this
+    // template's business rather than the SDK's (CONTRACT A7). A scaffold that
+    // omitted them would render callouts with empty labels and look broken.
+    blockConfig: { callout: { labels: { note: 'NOTE', warn: 'WARNING' } } },
+  })
+
+/**
+ * Everything that can be judged **without touching the filesystem** (複驗 F-2).
+ *
+ * Separated out and called first because ordering is itself a guarantee here.
+ * `initCommand` used to create the store root and register the factory packages
+ * *before* the key was ever looked at, so `init '../evil'` on a fresh machine
+ * left a whole `~/.kamishibai` behind on its way to refusing — a rejected
+ * command that still changed the world. Validation that runs after the side
+ * effects is not validation, it is an epilogue.
+ *
+ * @param {{key: string, layout?: string, reserved?: readonly string[]}} request
+ * @returns {{namespace: string, name: string, key: string, layout: string}}
+ */
+export function validateScaffoldRequest({ key, layout = SCAFFOLD_LAYOUT, reserved = [] }) {
+  const split = splitTemplateKey(key)
+  if (split === null) {
+    throw new KsbError({
+      code: CODES.USAGE,
+      message:
+        `模板鍵 "${key}" 不是 \`<namespace>/<name>\` 形；兩段皆須以英數開頭，` +
+        '其後只准英數、`_` 與 `-`（它們會直接成為庫裡的目錄名）。',
+      exitCode: EXIT.USAGE,
+    })
+  }
+
+  if (reserved.includes(split.namespace)) {
+    throw refuse(
+      CODES.TEMPLATE_NAMESPACE_RESERVED,
+      `\`${split.namespace}\` 是出廠保留的 namespace（保留：${[...reserved].join(', ')}），` +
+        '不得用來建立模板包——冒用出廠名的包在列表上與出廠包無從分辨。',
+      'doc.meta.template',
+    )
+  }
+
+  // 未註冊的文體走既有的碼與既有的 path（F2a Verbatim：KSB_LAYOUT_NOT_FOUND／`doc`）。
+  // 它與「註冊了但腳手架還沒支援」是兩件不同的事，混成同一個碼會讓人分不清
+  // 「我打錯了文體名」與「這個文體還沒輪到」。
+  if (layoutModule(layout) === undefined) {
+    throw refuse(
+      CODES.LAYOUT_NOT_FOUND,
+      `layout \`${layout}\` 沒有人註冊；已註冊的文體：${knownLayouts().join(', ')}。`,
+      'doc',
+    )
+  }
+
+  if (!SCAFFOLD_SUPPORTED_LAYOUTS.includes(layout)) {
+    throw new KsbError({
+      code: CODES.USAGE,
+      message:
+        `腳手架尚未支援文體 \`${layout}\`；目前支援：${SCAFFOLD_SUPPORTED_LAYOUTS.join(', ')}。` +
+        '骨架包附的預設 md 是照文體寫的，硬生出來的包畫不出東西，' +
+        '而它印給你的那句「開箱即用」也會是假的。',
+      exitCode: EXIT.USAGE,
+    })
+  }
+
+  return { ...split, layout }
+}
+
+/**
+ * Write a fresh package into the store.
+ *
+ * Refuses an occupied directory rather than merging into it: a package the user
+ * already has is a protected asset by the same rule the store itself is
+ * (CONTRACT B2「已存在→不動既有檔案」), and a scaffold that half-overwrote one
+ * would destroy the stylesheet somebody had been editing.
+ *
+ * @param {{key: string, layout?: string, engine: string, reserved?: readonly string[],
+ *   env?: object}} input
+ * @returns {{template: string, dir: string, files: string[], source: string}}
+ */
+export function scaffoldTemplatePackage({ key, layout, engine, reserved = [], env = process.env }) {
+  const validated = validateScaffoldRequest({ key, layout, reserved })
+  const { namespace, name } = validated
+  layout = validated.layout
+
+  const dir = templatePackageDir(namespace, name, env)
+  // 三件套**任一**存在即拒（複驗 F-3）。原本只看 manifest.toml，於是一個
+  // 「manifest 被刪掉、stylesheet 與預設 md 還在」的半成品目錄會被當成空地，
+  // 兩個檔案就地被覆寫——而那正是最可能有人正在改的狀態。
+  const occupied = [PACKAGE_FILES.MANIFEST, PACKAGE_FILES.STYLESHEET, PACKAGE_FILES.DEFAULT_DOC]
+    .filter((filename) => existsSync(join(dir, filename)))
+  if (occupied.length > 0) {
+    throw refuse(
+      CODES.TEMPLATE_PACKAGE_EXISTS,
+      `模板包 ${validated.key} 的目錄已經有東西了（${dir}）：${occupied.join('、')}。` +
+        '腳手架不覆寫既有的檔案：裡面的 stylesheet 與預設 md 可能是有人正在改的東西。',
+    )
+  }
+
+  // Guaranteed present: `validateScaffoldRequest` refuses any 文體 this table
+  // has no blueprint for, which is the same list `-l` is narrowed to.
+  const blueprint = SCAFFOLD_BLUEPRINTS[layout]
+  const files = [
+    [PACKAGE_FILES.MANIFEST, scaffoldManifest({ namespace, name, layout, engine, blueprint })],
+    [PACKAGE_FILES.STYLESHEET, blueprint.stylesheet()],
+    [PACKAGE_FILES.DEFAULT_DOC, blueprint.document({ namespace, name })],
+  ]
+
+  try {
+    mkdirSync(dir, { recursive: true })
+    for (const [filename, text] of files) writeFileAtomic(join(dir, filename), text)
+  } catch (cause) {
+    throw new KsbError({
+      code: CODES.WRITE_FAILED,
+      message: `could not write template package at ${dir}: ${cause.message}`,
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+
+  return {
+    template: validated.key,
+    dir,
+    files: files.map(([filename]) => filename),
+    source: join(dir, PACKAGE_FILES.DEFAULT_DOC),
+  }
+}

package/src/delivery/templates.js

@@ -0,0 +1,192 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { writeFileAtomic } from './atomic.js'
+import { templatePackageDir } from './home.js'
+import { MANIFEST_FILENAME, NO_ROOT } from './template-format.js'
+import { packageDirs, packageHasCode } from './template-package.js'
+import { parseToml, stringifyToml } from './toml.js'
+
+export { MANIFEST_FILENAME, NO_ROOT }
+
+/**
+ * The template namespace inside the central store (CONTRACT E3, VC2).
+ *
+ * Until now a template was a JS module the engine happened to bundle. That is
+ * enough to *render* with, and not enough to be a **package**: nothing on disk
+ * said which templates this installation has, what versions they are, or what
+ * they can draw. `templates/<namespace>/<name>/manifest.toml` is that record —
+ * the probe surface an Agent (or a human, or the next slice's `init`/`import`)
+ * can read without importing the engine.
+ *
+ * The manifest mirrors the JS manifest rather than replacing it: the module is
+ * still the single source, and the TOML is a faithful projection of it, so the
+ * two can be diffed field by field instead of drifting.
+ */
+
+/**
+ * Verbatim CONTRACT constant — manifest.toml keys, in output order.
+ * Order is part of the byte-consistency claim, so it lives here, once.
+ *
+ * The first six are E3's and may never move: they are the pinned projection.
+ * The rest are F3's, appended — and appended because the manifest stopped being
+ * a *description* of a template and became the instruction that loads one. A
+ * package whose descriptor omits its 文體 and its applied state is a package
+ * only the engine that bundled it can draw with, which is the ledger/loading
+ * point split this slice closes. Optional keys are written only when the
+ * manifest carries them, so the emitted key list is always a subsequence of
+ * this one.
+ */
+export const MANIFEST_KEYS = Object.freeze([
+  'name',
+  'namespace',
+  'version',
+  'engine',
+  'root',
+  'blocks',
+  'layout',
+  'language',
+  'description',
+  'maxWidth',
+  'measure',
+  'blockConfig',
+])
+
+/** The six E3 pinned as the projection, before F3 appended to it. */
+export const MANIFEST_KEYS_E3 = Object.freeze(MANIFEST_KEYS.slice(0, 6))
+
+const writeFailed = (path, cause) =>
+  new KsbError({
+    code: CODES.WRITE_FAILED,
+    message: `could not write template package at ${path}: ${cause.message}`,
+    exitCode: EXIT.VALIDATION,
+  })
+
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value)
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0
+const isTable = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+/** Keys carried only when the manifest actually has them, in MANIFEST_KEYS order. */
+const OPTIONAL_PROJECTION = Object.freeze([
+  ['language', isNonEmptyString],
+  ['description', isNonEmptyString],
+  ['maxWidth', isFiniteNumber],
+  ['measure', isFiniteNumber],
+  ['blockConfig', (value) => isTable(value) && Object.keys(value).length > 0],
+])
+
+/**
+ * Project a JS template manifest onto the TOML table (CONTRACT E3, widened by F3).
+ *
+ * Still a *projection*, not a second source: the module remains the truth and
+ * the TOML mirrors it field by field so the two can be diffed rather than
+ * drift. F3 only widens what gets mirrored — the 文體 the template rides and
+ * the applied state it turns that 文體's knobs to — because those are the
+ * fields a *loader* needs and a *listing* did not.
+ *
+ * An absent optional field is omitted rather than written as an empty value:
+ * `maxWidth = 0` would be a legible number that happens to be a lie, and a
+ * reader has no way to tell it apart from a template that meant it.
+ *
+ * @param {object} manifest
+ * @param {string} engine engine version this package was registered by
+ */
+export function manifestTable(manifest, engine) {
+  if (!isNonEmptyString(manifest.layout)) {
+    throw new KsbError({
+      code: CODES.TEMPLATE_PACKAGE_INVALID,
+      message:
+        `模板 ${manifest.namespace}/${manifest.name} 沒有宣告所屬 layout，無法投影成可載入的包。`,
+      // Same code, same path, wherever it is raised (CONTRACT Verbatim 四新碼 path):
+      // an agent keying on (code, path) must not meet two spellings of one refusal.
+      path: 'doc.meta.template',
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+  const table = {
+    name: manifest.name,
+    namespace: manifest.namespace,
+    version: manifest.version,
+    engine,
+    root: manifest.root ?? NO_ROOT,
+    blocks: [...manifest.blocks],
+    layout: manifest.layout,
+  }
+  for (const [key, ok] of OPTIONAL_PROJECTION) {
+    if (ok(manifest[key])) table[key] = manifest[key]
+  }
+  return table
+}
+
+/**
+ * Register (or refresh) one built-in template package.
+ *
+ * The write is skipped when the bytes already match: registration runs on every
+ * render, and rewriting an identical file would churn mtimes inside a store
+ * whose whole purpose is to be a stable record.
+ *
+ * @returns {{namespace: string, name: string, version: string, root: string,
+ *   path: string, written: boolean}}
+ */
+export function registerTemplatePackage({ manifest, engine, env = process.env }) {
+  const table = manifestTable(manifest, engine)
+  const dir = templatePackageDir(manifest.namespace, manifest.name, env)
+  const path = join(dir, MANIFEST_FILENAME)
+  const text = stringifyToml(table)
+
+  let written = false
+  try {
+    if (!existsSync(path) || readFileSync(path, 'utf8') !== text) {
+      mkdirSync(dir, { recursive: true })
+      writeFileAtomic(path, text)
+      written = true
+    }
+  } catch (cause) {
+    throw writeFailed(path, cause)
+  }
+
+  return {
+    namespace: table.namespace,
+    name: table.name,
+    version: table.version,
+    root: table.root,
+    path,
+    written,
+  }
+}
+
+const readPackage = ({ namespace, name, dir, path }) => {
+  const hasCode = packageHasCode(dir)
+  let table
+  try {
+    table = parseToml(readFileSync(path, 'utf8'))
+  } catch {
+    // An unreadable manifest is still a package on disk: dropping it silently
+    // would make `templates` disagree with the filesystem, which is the one
+    // thing this listing exists to prevent.
+    return { namespace, name, version: '', root: NO_ROOT, layout: '', hasCode, path }
+  }
+  return {
+    namespace: typeof table.namespace === 'string' ? table.namespace : namespace,
+    name: typeof table.name === 'string' ? table.name : name,
+    version: typeof table.version === 'string' ? table.version : '',
+    root: typeof table.root === 'string' ? table.root : NO_ROOT,
+    // The 文體 a package rides is now the first thing a reader needs from a
+    // listing: since F2a it decides the shape of the page, and since F3 a
+    // package that names one nobody registered is a package that will not draw.
+    layout: typeof table.layout === 'string' ? table.layout : '',
+    hasCode,
+    path,
+  }
+}
+
+/**
+ * Every registered package, sorted by `<namespace>/<name>` so the listing is
+ * deterministic regardless of directory-read order.
+ *
+ * @returns {Array<{namespace: string, name: string, version: string, root: string,
+ *   layout: string, hasCode: boolean, path: string}>}
+ */
+export function readTemplatePackages(env = process.env) {
+  return packageDirs(env).map(readPackage)
+}

package/src/delivery/toml.js

@@ -0,0 +1,195 @@
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+/**
+ * A deliberately tiny TOML writer/reader for template package manifests
+ * (CONTRACT E3, SPEC §5.2「描述檔格式定為 TOML」).
+ *
+ * Scope is the whole point: a full TOML implementation would be several hundred
+ * lines of surface that nothing in this SDK exercises — and a dependency whose
+ * formatting choices we do not control would break the byte-consistency claim
+ * the manifest is pinned on. What is written here is read back here, and both
+ * halves are asserted against the JS manifest they mirror.
+ *
+ * F3 widens the alphabet exactly as far as a *loadable* package needs and no
+ * further (CONTRACT P2): numbers, because the applied state a template turns its
+ * layout's knobs to (`measure`, `maxWidth`) is arithmetic and storing it as a
+ * string would push the parsing into every reader; and one level of named
+ * tables (`[blockConfig.callout.labels]`), because 轉子/<型別>/config is nested
+ * by nature and flattening it would invent a key-mangling convention that only
+ * this file understands.
+ *
+ * Determinism survives the widening, and that is the part with a load-bearing
+ * consequence: scalar keys are written in the caller's insertion order, then
+ * table sections in theirs, depth first. Arrays keep their element order, and no
+ * value is ever re-wrapped or re-flowed. The same manifest therefore serialises
+ * to the same bytes on every machine, which is what lets
+ * `registerTemplatePackage` skip an identical rewrite.
+ */
+
+/** The scalar value shapes a manifest may carry. */
+const isStringArray = (value) => Array.isArray(value) && value.every((v) => typeof v === 'string')
+
+/**
+ * A finite number. `NaN`/`Infinity` have no TOML spelling, and writing one would
+ * produce a manifest this parser could not read back — a package that is broken
+ * only on the reading side is the drift this module exists to refuse.
+ */
+const isNumber = (value) => typeof value === 'number' && Number.isFinite(value)
+
+/** A nested table: a plain object, never an array and never null. */
+const isTable = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+
+const manifestError = (message) =>
+  new KsbError({
+    code: CODES.PARSE_FAILED,
+    message,
+    exitCode: EXIT.VALIDATION,
+  })
+
+/** TOML basic string: only the escapes the manifest alphabet can actually need. */
+const quote = (value) =>
+  `"${String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t')}"`
+
+const unquote = (raw) => {
+  const body = raw.slice(1, -1)
+  return body.replace(/\\(.)/g, (_, c) => {
+    if (c === 'n') return '\n'
+    if (c === 'r') return '\r'
+    if (c === 't') return '\t'
+    return c
+  })
+}
+
+const formatValue = (value) => {
+  if (typeof value === 'string') return quote(value)
+  if (isNumber(value)) return String(value)
+  if (typeof value === 'boolean') return String(value)
+  if (isStringArray(value)) return `[${value.map(quote).join(', ')}]`
+  throw manifestError(
+    `manifest value must be a string, number, boolean, string array or table, got ${typeof value}`,
+  )
+}
+
+/**
+ * Emit one table: its scalars, then its sub-tables, each under its own header.
+ *
+ * Two rules, both load-bearing:
+ *
+ *  - Scalars come first. A key written after a `[section]` header reads back as
+ *    belonging to that section — TOML's one genuinely surprising rule, and the
+ *    one way this writer could produce a file it cannot itself parse back into
+ *    the table it was given.
+ *  - A header is written only for a table that carries values of its own, or
+ *    for an empty leaf. `[blockConfig.callout.labels]` already declares every
+ *    ancestor on the way down, so emitting `[blockConfig]` and
+ *    `[blockConfig.callout]` above it adds two empty stanzas that say nothing
+ *    and read as though something is missing from them. The empty *leaf* is the
+ *    exception: it is the only place a header carries the whole fact.
+ */
+const emitTable = (table, path, lines) => {
+  const nested = []
+  for (const [key, value] of Object.entries(table)) {
+    if (isTable(value)) {
+      nested.push([key, value])
+      continue
+    }
+    lines.push(`${key} = ${formatValue(value)}`)
+  }
+  for (const [key, value] of nested) {
+    const child = [...path, key]
+    const entries = Object.values(value)
+    if (entries.length === 0 || entries.some((v) => !isTable(v))) {
+      lines.push('')
+      lines.push(`[${child.join('.')}]`)
+    }
+    emitTable(value, child, lines)
+  }
+  return lines
+}
+
+/**
+ * Serialise a table to TOML.
+ * @param {Record<string, string|number|boolean|string[]|object>} table
+ * @returns {string} newline-terminated TOML text
+ */
+export function stringifyToml(table) {
+  return `${emitTable(table, [], []).join('\n')}\n`
+}
+
+const KEY_LINE = /^([A-Za-z0-9_-]+)\s*=\s*(.+)$/
+const TABLE_HEADER = /^\[([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)\]$/
+const STRING_VALUE = /^"(?:[^"\\]|\\.)*"$/
+const NUMBER_VALUE = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/
+
+const parseValue = (raw, key) => {
+  const text = raw.trim()
+  if (STRING_VALUE.test(text)) return unquote(text)
+  if (NUMBER_VALUE.test(text)) return Number(text)
+  if (text === 'true') return true
+  if (text === 'false') return false
+  if (text.startsWith('[') && text.endsWith(']')) {
+    const inner = text.slice(1, -1).trim()
+    if (inner.length === 0) return []
+    const parts = inner.split(',').map((p) => p.trim()).filter((p) => p.length > 0)
+    for (const part of parts) {
+      if (!STRING_VALUE.test(part)) throw manifestError(`array entry of "${key}" is not a string: ${part}`)
+    }
+    return parts.map(unquote)
+  }
+  throw manifestError(`value of "${key}" is not a manifest value: ${text}`)
+}
+
+/**
+ * Walk (creating as needed) to the table a `[a.b.c]` header names.
+ *
+ * A segment that already holds a scalar is refused rather than overwritten: the
+ * file would then say two contradictory things about one key, and whichever the
+ * reader happened to keep would be arbitrary.
+ */
+const descend = (root, segments, line) => {
+  let cursor = root
+  for (const segment of segments) {
+    const next = cursor[segment]
+    if (next === undefined) cursor[segment] = {}
+    else if (!isTable(next)) {
+      throw manifestError(`line ${line}: \`${segments.join('.')}\` is already a value, not a table`)
+    }
+    cursor = cursor[segment]
+  }
+  return cursor
+}
+
+/**
+ * Parse a TOML table. Anything this writer cannot have produced is a hard error
+ * rather than a silently dropped key — a manifest that half-parses is exactly
+ * the "template resolves to something unexpected" failure E3 exists to make
+ * impossible, and F3 turns that manifest into a *loading* instruction, so a
+ * dropped key would now change what gets drawn rather than only what gets
+ * listed.
+ *
+ * @param {string} text
+ * @returns {Record<string, string|number|boolean|string[]|object>}
+ */
+export function parseToml(text) {
+  const table = {}
+  let cursor = table
+  for (const [index, line] of String(text ?? '').split('\n').entries()) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0 || trimmed.startsWith('#')) continue
+    const header = TABLE_HEADER.exec(trimmed)
+    if (header !== null) {
+      cursor = descend(table, header[1].split('.'), index + 1)
+      continue
+    }
+    const match = KEY_LINE.exec(trimmed)
+    if (match === null) throw manifestError(`line ${index + 1} is not a key/value pair: ${trimmed}`)
+    cursor[match[1]] = parseValue(match[2], match[1])
+  }
+  return table
+}

package/src/delivery/write.js

@@ -0,0 +1,35 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+const write = (outPath, data, encoding) => {
+  const absolute = resolve(outPath)
+  try {
+    mkdirSync(dirname(absolute), { recursive: true })
+    writeFileSync(absolute, data, encoding === undefined ? undefined : encoding)
+  } catch (cause) {
+    throw new KsbError({
+      code: CODES.WRITE_FAILED,
+      message: `could not write artifact to ${absolute}: ${cause.message}`,
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+  return absolute
+}
+
+/**
+ * Write an artifact to disk, creating parent directories as needed.
+ * @returns {{path: string, bytes: number}} absolute path and byte length
+ */
+export function writeArtifact(outPath, html) {
+  return { path: write(outPath, html, 'utf8'), bytes: Buffer.byteLength(html, 'utf8') }
+}
+
+/**
+ * Write a binary deliverable (PDF / PPTX / PNG) through the same single writer,
+ * so the export chain cannot invent its own error code for a failed write.
+ * @returns {{path: string, bytes: number}}
+ */
+export function writeBytes(outPath, buffer) {
+  return { path: write(outPath, buffer), bytes: buffer.length }
+}