@kamishibai/sdk 0.1.1

package/src/delivery/template-package.js

@@ -0,0 +1,376 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { validateGateDeclaration } from '../core/lint-gates.js'
+import { isReservedKey, registerTemplateSource, resetTemplateSources } from '../render/templates.js'
+import {
+  LAYOUT_KNOBS_FIELD,
+  layoutModule,
+  registerTemplateLayoutSource,
+  resetTemplateLayoutSources,
+} from '../layouts/index.js'
+import { templatePackageDir, templatesRoot } from './home.js'
+import { loadPackageExtensions } from './template-extensions.js'
+import {
+  DEFAULT_LANGUAGE,
+  MANIFEST_FILENAME,
+  NO_ROOT,
+  PACKAGE_FILES,
+  splitTemplateKey,
+} from './template-format.js'
+import { parseToml } from './toml.js'
+
+export { MANIFEST_FILENAME, NO_ROOT, PACKAGE_FILES, splitTemplateKey }
+
+/**
+ * A template package on disk, **loaded** rather than merely listed (CONTRACT F3 D1).
+ *
+ * E3 gave the store a template namespace and stopped one step short: a package
+ * could be registered, listed by `templates`, counted by `debug` — and then
+ * `render -t` came back `KSB_TEMPLATE_NOT_FOUND`, because the resolver read a
+ * static registry of the two templates the engine happened to bundle (量測報告
+ * §5.2). The namespace was a ledger of things nobody could use. This module is
+ * the other half: the same directory, read back into the object the render
+ * pipeline already consumes.
+ *
+ * The default path is **pure data** (wayfinder issue 13 裁決 7): a manifest that
+ * declares which 文體 the package rides and how its knobs are turned, a
+ * stylesheet, and a 預設 md that shows what the template looks like when nobody
+ * has written anything yet (issue 14 補充裁定). Nothing here is executable, so
+ * nothing here needs to be trusted. JS is opt-in, and lives next door in
+ * `template-extensions.js`.
+ */
+
+const invalid = (message, path = 'doc.meta.template') =>
+  new KsbError({
+    code: CODES.TEMPLATE_PACKAGE_INVALID,
+    message,
+    path,
+    exitCode: EXIT.VALIDATION,
+  })
+
+const subdirectories = (dir) => {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((entry) => statSync(join(dir, entry)).isDirectory())
+    .sort()
+}
+
+/**
+ * Every package directory in the store, sorted by `<namespace>/<name>`.
+ *
+ * A directory counts as a package when it holds a manifest — the same rule the
+ * listing has always used, kept in one place so `templates` and `render` can
+ * never disagree about what is installed.
+ *
+ * @returns {Array<{namespace: string, name: string, key: string, dir: string, path: string}>}
+ */
+export function packageDirs(env = process.env) {
+  const root = templatesRoot(env)
+  const found = []
+  for (const namespace of subdirectories(root)) {
+    for (const name of subdirectories(join(root, namespace))) {
+      const dir = join(root, namespace, name)
+      const path = join(dir, PACKAGE_FILES.MANIFEST)
+      if (!existsSync(path)) continue
+      found.push({ namespace, name, key: `${namespace}/${name}`, dir, path })
+    }
+  }
+  return found
+}
+
+/** `<namespace>/<name>` of every package installed in the store. */
+export const storeTemplateKeys = (env = process.env) => packageDirs(env).map((pkg) => pkg.key)
+
+const jsFilesUnder = (dir) => {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return []
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) return jsFilesUnder(full)
+    return full.endsWith('.js') ? [full] : []
+  })
+}
+
+/**
+ * Whether a package carries executable code (CONTRACT P5).
+ *
+ * There is no sandbox — 安裝即信任 is the settled trust model (issue 13 裁決 4).
+ * What a trust-on-install model still owes its user is *legibility*: being able
+ * to see, without opening a single file, which of the packages installed here
+ * will run code when they draw. So the listing says so, and this is where it
+ * learns the answer.
+ */
+export const packageHasCode = (dir) =>
+  jsFilesUnder(join(dir, PACKAGE_FILES.ROTORS_DIR)).length > 0 ||
+  jsFilesUnder(join(dir, PACKAGE_FILES.PLUGINS_DIR)).length > 0 ||
+  // F7a's third door counts too. A package whose chrome is JS runs code when it
+  // draws, exactly like a rotor override does, and the whole use of this field
+  // is to let a reader see that without opening a file (CONTRACT P5).
+  existsSync(join(dir, PACKAGE_FILES.CHROME))
+
+const requireString = (table, key, where) => {
+  const value = table[key]
+  if (typeof value !== 'string' || value.length === 0) {
+    throw invalid(
+      `模板包 ${where} 的 ${PACKAGE_FILES.MANIFEST} 缺少字串欄位 \`${key}\`` +
+        `（目前值：${JSON.stringify(value ?? null)}）。`,
+    )
+  }
+  return value
+}
+
+const optionalNumber = (table, key, where) => {
+  const value = table[key]
+  if (value === undefined) return undefined
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw invalid(
+      `模板包 ${where} 的 \`${key}\` 必須是正數的 CSS 像素值，得到 ${JSON.stringify(value)}。`,
+    )
+  }
+  return value
+}
+
+const optionalString = (table, key, where, fallback) => {
+  const value = table[key]
+  if (value === undefined) return fallback
+  if (typeof value !== 'string') {
+    throw invalid(`模板包 ${where} 的 \`${key}\` 必須是字串，得到 ${JSON.stringify(value)}。`)
+  }
+  return value
+}
+
+/**
+ * The 文體's own knobs, as this package turns them (CONTRACT F2b G1/G7).
+ *
+ * A pure-data package must be able to turn every knob its 文體 declares —
+ * `rail = true` in a `manifest.toml` is the whole of 「第三方也能有側欄」, and a
+ * loader that only understood the two canvas dimensions would have made the
+ * knob a privilege of the two templates that ship inside the SDK.
+ *
+ * Which knobs exist is asked of the layout, never listed here: this layer knows
+ * the store, not the 文體 axis. An unregistered layout yields nothing and the
+ * render path refuses the package by name a moment later
+ * (`KSB_LAYOUT_NOT_FOUND`), which is the better error of the two.
+ *
+ * The type is enforced against the knob's own factory value, because TOML will
+ * happily carry `rail = "true"` — a string that is `true` to every branch that
+ * ever tests it.
+ */
+function knobValues(table, layout, where) {
+  const declared = layoutModule(layout)?.[LAYOUT_KNOBS_FIELD]
+  if (declared === undefined) return {}
+  const turned = {}
+  for (const [name, factory] of Object.entries(declared)) {
+    const value = table[name]
+    if (value === undefined) continue
+    if (typeof value !== typeof factory) {
+      throw invalid(
+        `模板包 ${where} 的旋鈕 \`${name}\` 必須是 ${typeof factory}，` +
+          `得到 ${JSON.stringify(value)}。`,
+      )
+    }
+    turned[name] = value
+  }
+  return turned
+}
+
+/**
+ * The manifest as the render layer's data, refused loudly when it is not.
+ *
+ * Every refusal names the field, because the failure this guards against is a
+ * package that half-loads: a missing `layout` defaulted to the article 文體
+ * would draw *some* artifact and call it this template's, which is the same
+ * silent-wrong-output shape `manifest.blocks` and the root-form guard exist to
+ * refuse (CONTRACT D2).
+ */
+export function readPackageManifest({ namespace, name, dir, path }) {
+  const where = `${namespace}/${name}`
+  if (!existsSync(path)) {
+    throw invalid(`模板包 ${where} 缺少 ${PACKAGE_FILES.MANIFEST}（找過：${path}）。`)
+  }
+
+  let table
+  try {
+    table = parseToml(readFileSync(path, 'utf8'))
+  } catch (cause) {
+    throw invalid(`模板包 ${where} 的 ${PACKAGE_FILES.MANIFEST} 讀不出來：${cause.message}`)
+  }
+
+  if (requireString(table, 'namespace', where) !== namespace || requireString(table, 'name', where) !== name) {
+    throw invalid(
+      `模板包 ${where} 的 ${PACKAGE_FILES.MANIFEST} 自稱 ` +
+        `\`${table.namespace}/${table.name}\`，與所在目錄不符。` +
+        '解析鍵取自目錄，宣稱取自檔案——兩者不同就會有一個永遠指不到。',
+    )
+  }
+
+  const blocks = table.blocks
+  if (!Array.isArray(blocks) || blocks.length === 0 || blocks.some((b) => typeof b !== 'string')) {
+    throw invalid(
+      `模板包 ${where} 的 \`blocks\` 必須是非空的 block 型別字串陣列——` +
+        '它是模板的准入表，空表等於一份畫不出任何東西的模板。',
+    )
+  }
+
+  const blockConfig = table.blockConfig
+  if (blockConfig !== undefined && (blockConfig === null || typeof blockConfig !== 'object' || Array.isArray(blockConfig))) {
+    throw invalid(`模板包 ${where} 的 \`blockConfig\` 必須是 \`[blockConfig.<型別>]\` 具名表。`)
+  }
+
+  // F7b — `[gates]`: which of `lint`'s declared-threshold rules this package
+  // opts into, and at what number (SPEC §5.4). The *shape* is judged by the
+  // linter's own spec table rather than restated here, for the reason this file
+  // gives twice already: two spellings of one rule drift, and the direction they
+  // drift in is a manifest that loads with a gate the linter has never heard of.
+  const gates = validateGateDeclaration(table.gates, where)
+
+  const root = optionalString(table, 'root', where, NO_ROOT)
+  const layout = requireString(table, 'layout', where)
+  return Object.freeze({
+    namespace,
+    name,
+    version: requireString(table, 'version', where),
+    description: optionalString(table, 'description', where, ''),
+    language: optionalString(table, 'language', where, DEFAULT_LANGUAGE),
+    layout,
+    root: root === NO_ROOT ? null : root,
+    blocks: Object.freeze([...blocks]),
+    blockConfig: Object.freeze(blockConfig ?? {}),
+    gates,
+    ...(optionalNumber(table, 'maxWidth', where) === undefined ? {} : { maxWidth: table.maxWidth }),
+    ...(optionalNumber(table, 'measure', where) === undefined ? {} : { measure: table.measure }),
+    ...knobValues(table, layout, where),
+  })
+}
+
+const requireFile = (dir, filename, where, why) => {
+  const path = join(dir, filename)
+  if (!existsSync(path)) {
+    throw invalid(`模板包 ${where} 缺少 ${filename}——${why}（找過：${path}）。`)
+  }
+  return path
+}
+
+/** Loaded packages, so one process never imports the same extension twice. */
+const cache = new Map()
+
+/** Test hygiene: forget every loaded package (and let extensions be re-registered). */
+export function resetTemplatePackageCache() {
+  cache.clear()
+}
+
+/**
+ * Load one store package into the object `renderWithTemplatePackage` consumes.
+ *
+ * @returns {Promise<object|undefined>} undefined when no package lives at that key
+ */
+export async function loadStoreTemplate(key, env = process.env) {
+  const split = splitTemplateKey(key)
+  if (split === null) return undefined
+  const { namespace, name } = split
+  const dir = templatePackageDir(namespace, name, env)
+  const path = join(dir, PACKAGE_FILES.MANIFEST)
+  if (!existsSync(path)) return undefined
+  if (cache.has(dir)) return cache.get(dir)
+
+  const where = split.key
+  const manifest = readPackageManifest({ namespace, name, dir, path })
+  const stylesheet = requireFile(
+    dir,
+    PACKAGE_FILES.STYLESHEET,
+    where,
+    '模板包的皮是必需品，沒有它的產物只是一份沒有樣式的骨架',
+  )
+  // The 預設 md is part of the format, not a courtesy (issue 14 補充裁定):
+  // 「預設長怎樣」歸模板, and its carrier is the starter document that renders
+  // into the template's own default appearance. A package without one cannot
+  // answer the question it exists to answer.
+  const source = requireFile(
+    dir,
+    PACKAGE_FILES.DEFAULT_DOC,
+    where,
+    '預設 md 是「這個模板長什麼樣」的唯一載體，缺了它包就沒有開箱樣貌',
+  )
+
+  const { overrides, plugins, chrome } = await loadPackageExtensions({ dir, key: where })
+
+  const template = Object.freeze({
+    manifest,
+    key: where,
+    // F7a: a store package can fill its 文體's chrome slots too (`chrome.js`).
+    // This used to be the literal `{}` — a hard-coded claim that only a bundled
+    // template may have a masthead, which made the first serious 臨摹 come out
+    // headless while the factory skin it replaced kept its header.
+    chrome,
+    language: manifest.language,
+    /** A pure-data package ships no fonts: nothing to subset, nothing to embed. */
+    fonts: Object.freeze([]),
+    styles: () => readFileSync(stylesheet, 'utf8'),
+    overrides,
+    plugins,
+    dir,
+    source,
+  })
+  cache.set(dir, template)
+  return template
+}
+
+/** The store as a template source the render layer can consult (CONTRACT D1). */
+export const storeTemplateSource = (env = process.env) =>
+  Object.freeze({
+    keys: () => storeTemplateKeys(env),
+    load: (key) => loadStoreTemplate(key, env),
+  })
+
+/**
+ * The store as a **layout index** the parser can consult (CONTRACT F2f E4).
+ *
+ * It answers one question and reads one field: which 文體 does each installed
+ * package ride. That is what turns `---` into a page break for a store deck
+ * package — the half F3 deferred (`src/layouts/template-index.js` carries the
+ * reasoning).
+ *
+ * Two packages are deliberately left out of the answer:
+ *
+ *  - one whose manifest will not read. It cannot be drawn with either, and
+ *    `loadStoreTemplate` will say so by name the moment anybody tries; letting
+ *    the exception out here would break the parse of an unrelated document
+ *    because of a broken package the document never mentions.
+ *  - one squatting on a factory namespace (封緘 F2). `resolveTemplate` refuses
+ *    those, so treating one as a deck template would split a document's pages
+ *    for a key that then cannot draw them.
+ */
+export const storeLayoutSource = (env = process.env) =>
+  Object.freeze({
+    entries: () =>
+      packageDirs(env).flatMap((pkg) => {
+        if (isReservedKey(pkg.key)) return []
+        try {
+          return [{ key: pkg.key, layout: readPackageManifest(pkg).layout }]
+        } catch {
+          return []
+        }
+      }),
+  })
+
+/**
+ * Wire the store into the resolution chain.
+ *
+ * The render layer owns the chain and knows nothing about `~/.kamishibai`; this
+ * layer owns the store and knows nothing about how a template is drawn. Calling
+ * this is what joins them, and every command that can resolve a template key
+ * calls it — `test_f3_store_is_wired_into_every_render_path` is the gate that
+ * says so, because a path that forgot would silently answer
+ * `KSB_TEMPLATE_NOT_FOUND` for a package sitting right there on disk, which is
+ * the exact failure this slice exists to remove.
+ */
+export function installTemplateStore(env = process.env) {
+  resetTemplateSources()
+  registerTemplateSource(storeTemplateSource(env))
+  // The same act, for the other consumer: the parser has to know which 文體 an
+  // installed package rides before it decides what `---` means. Wiring the two
+  // together here is what keeps them from disagreeing — a command that had the
+  // loader but not the index would draw a deck package as one long slide.
+  resetTemplateLayoutSources()
+  registerTemplateLayoutSource(storeLayoutSource(env))
+}

package/src/delivery/template-promote.js

@@ -0,0 +1,240 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { writeFileAtomic } from './atomic.js'
+import { templatePackageDir, templatesRoot } from './home.js'
+import {
+  DRAFT_NAMESPACE,
+  MANIFEST_FILENAME,
+  PACKAGE_FILES,
+  isDraftKey,
+  splitTemplateKey,
+} from './template-format.js'
+import { parseToml, stringifyToml } from './toml.js'
+
+/**
+ * `promote` — the last step of the 臨摹 loop (CONTRACT F7a H1).
+ *
+ * `init draft/<名>` opens a workspace; everything between it and here is the
+ * Agent's own reading-and-writing (H2's Not-building: the SDK grows no
+ * image-parsing hand). What the SDK owes the workflow is its *end*: the moment
+ * a sketch stops being a sketch has to be a mechanical move with a receipt, not
+ * a `mv` somebody types and a manifest they remember to edit.
+ *
+ * Remembering is exactly what fails. The package directory and the manifest's
+ * own `namespace`/`name` are two statements of one fact, and a hand-moved
+ * package leaves them disagreeing: the store lists it at its new key (that is
+ * read off the path) while the manifest — the thing `readPackage` prefers, and
+ * the thing a human opens — still names `draft/`. So the rewrite travels with
+ * the move, in one function, and neither can happen without the other.
+ */
+
+const refuse = (code, message, exitCode, path) =>
+  new KsbError({ code, message, exitCode, ...(path === undefined ? {} : { path }) })
+
+/**
+ * The key a caller wrote, split — or a usage refusal naming which of the two
+ * arguments was malformed.
+ *
+ * Shape is judged before anything touches the disk, per the same 複驗 F-2 rule
+ * `validateScaffoldRequest` records: a command that rejects your input must
+ * leave the store exactly as it found it, and a validation that runs after the
+ * side effects is an epilogue rather than a gate.
+ */
+const requireKey = (key, role) => {
+  const split = splitTemplateKey(key)
+  if (split === null) {
+    throw refuse(
+      CODES.USAGE,
+      `${role} "${key}" 不是 \`<namespace>/<name>\` 形；兩段皆須以英數開頭，` +
+        '其後只准英數、`_` 與 `-`（它們會直接成為庫裡的目錄名）。',
+      EXIT.USAGE,
+    )
+  }
+  return split
+}
+
+/** Every file and directory sitting under a package directory, recursively empty-safe. */
+const isEmptyDir = (dir) => existsSync(dir) && readdirSync(dir).length === 0
+
+/**
+ * Everything judgeable without writing (CONTRACT F7a H1 三拒絕面).
+ *
+ * The three refusals are three *different* mistakes and carry three different
+ * codes, because an agent keying on the code has to be able to tell "I named a
+ * package that is not there" from "I aimed at a name somebody already owns":
+ *
+ *  - 來源非 `draft/` → `KSB_USAGE`. Not a missing thing, a wrong kind of thing.
+ *    `promote` is the workspace's exit; asked to move a package that was never
+ *    in the workspace it has no meaning to execute, and silently doing a rename
+ *    would make the command's name a lie.
+ *  - 來源不存在 → `KSB_TEMPLATE_NOT_FOUND`, the code the render path already
+ *    raises for a key with nothing behind it. One spelling of one refusal.
+ *  - 目標撞名 → `KSB_TEMPLATE_PACKAGE_EXISTS`, the same code `init` raises for
+ *    the same fact, and refused for the same reason it is there: the occupied
+ *    directory may hold a stylesheet somebody is editing, and a `promote` that
+ *    merged into it would destroy work while reporting success.
+ *
+ * A reserved target is refused on top of the three, because the alternative is
+ * `promote` cheerfully manufacturing the one thing `init` and `resolveTemplate`
+ * both exist to prevent — a package at `kami/<名>` that lists as official and
+ * can never be loaded. A `draft/` target is refused too: that is a rename, and
+ * a command called `promote` that quietly performs one is worse than one that
+ * says it does not do that.
+ *
+ * @param {{from: string, to: string, reserved?: readonly string[], env?: object}} request
+ * @returns {{source: object, target: object, sourceDir: string, targetDir: string}}
+ */
+export function validatePromoteRequest({ from, to, reserved = [], env = process.env }) {
+  const source = requireKey(from, '來源模板鍵')
+  const target = requireKey(to, '目標模板鍵')
+
+  if (!isDraftKey(source.key)) {
+    throw refuse(
+      CODES.USAGE,
+      `promote 只搬 \`${DRAFT_NAMESPACE}/\` 底下的臨摹草稿，而來源是 ${source.key}。` +
+        '轉正是工作區的出口，不是通用的改名指令——' +
+        '對一個本來就不在工作區裡的包執行它，沒有任何一件事會被「轉正」。',
+      EXIT.USAGE,
+      'doc.meta.template',
+    )
+  }
+
+  if (target.namespace === DRAFT_NAMESPACE) {
+    throw refuse(
+      CODES.USAGE,
+      `promote 的目標不得留在 \`${DRAFT_NAMESPACE}/\`（收到 ${target.key}）：` +
+        '那是改名，不是轉正。要換草稿名字請自己搬目錄。',
+      EXIT.USAGE,
+      'doc.meta.template',
+    )
+  }
+
+  if (reserved.includes(target.namespace)) {
+    throw refuse(
+      CODES.TEMPLATE_NAMESPACE_RESERVED,
+      `\`${target.namespace}\` 是出廠保留的 namespace（保留：${[...reserved].join(', ')}），` +
+        '不得作為轉正目標——冒用出廠名的包在列表上與出廠包無從分辨，而且永遠載不起來。',
+      EXIT.VALIDATION,
+      'doc.meta.template',
+    )
+  }
+
+  const sourceDir = templatePackageDir(source.namespace, source.name, env)
+  const targetDir = templatePackageDir(target.namespace, target.name, env)
+
+  if (!existsSync(join(sourceDir, MANIFEST_FILENAME))) {
+    throw refuse(
+      CODES.TEMPLATE_NOT_FOUND,
+      `找不到臨摹草稿 ${source.key}（${sourceDir} 沒有 ${MANIFEST_FILENAME}）。` +
+        `草稿由 \`kamishibai init ${source.key}\` 開出來，用 \`kamishibai templates\` 看現有的有哪些。`,
+      EXIT.VALIDATION,
+      'doc.meta.template',
+    )
+  }
+
+  // 三件套**任一**存在即拒，與 `scaffoldTemplatePackage` 同一條（複驗 F-3）：
+  // 只看 manifest.toml 的話，一個「manifest 被刪、stylesheet 還在」的半成品
+  // 目錄會被當成空地，而那正是最可能有人正在改的狀態。
+  const occupied = [PACKAGE_FILES.MANIFEST, PACKAGE_FILES.STYLESHEET, PACKAGE_FILES.DEFAULT_DOC]
+    .filter((filename) => existsSync(join(targetDir, filename)))
+  if (occupied.length > 0) {
+    throw refuse(
+      CODES.TEMPLATE_PACKAGE_EXISTS,
+      `模板包 ${target.key} 的目錄已經有東西了（${targetDir}）：${occupied.join('、')}。` +
+        'promote 不覆寫既有的檔案：裡面的 stylesheet 與預設 md 可能是有人正在改的東西。',
+      EXIT.VALIDATION,
+    )
+  }
+
+  return { source, target, sourceDir, targetDir }
+}
+
+/**
+ * Rewrite the moved package's own account of its identity.
+ *
+ * Parsed and re-emitted rather than string-replaced: `draft` is a plausible
+ * substring of a description, a block name or a stylesheet path, and a textual
+ * swap would rewrite whichever of them happened to match. The writer preserves
+ * insertion order, so every other key comes back byte-for-byte where it was.
+ *
+ * `name` travels with `namespace` because the two are one fact with the
+ * directory: `promote draft/x acme/y` that rewrote only the namespace would
+ * leave a manifest calling itself `acme/x` inside a directory called `acme/y`,
+ * and the listing (which reads the manifest) and the resolver (which reads the
+ * path) would then disagree about what is installed.
+ */
+const rewriteIdentity = (dir, target) => {
+  const path = join(dir, MANIFEST_FILENAME)
+  let table
+  try {
+    table = parseToml(readFileSync(path, 'utf8'))
+  } catch (cause) {
+    throw refuse(
+      CODES.TEMPLATE_PACKAGE_INVALID,
+      `轉正後無法解析 ${path}：${cause.message}。` +
+        '包已經搬到新位置，但 manifest 讀不動——請手動修好 manifest 再列一次 templates。',
+      EXIT.VALIDATION,
+      'doc.meta.template',
+    )
+  }
+  writeFileAtomic(path, stringifyToml({ ...table, namespace: target.namespace, name: target.name }))
+  return path
+}
+
+/**
+ * Move one 臨摹 draft out of the workspace and into a real namespace.
+ *
+ * Zero residue is a named acceptance face rather than a side effect: a
+ * `promote` that left the draft in place would leave two packages claiming to
+ * be the same skin, and the next `render -t draft/<名>` would keep drawing the
+ * stale one — which looks exactly like the promotion never happening, except
+ * that it did. So the source directory is gone when this returns, and the
+ * emptied `draft/` namespace directory goes with it.
+ *
+ * @param {{from: string, to: string, reserved?: readonly string[], env?: object}} input
+ * @returns {{from: string, to: string, dir: string, manifest: string, source: string}}
+ */
+export function promoteTemplatePackage({ from, to, reserved = [], env = process.env }) {
+  const { source, target, sourceDir, targetDir } = validatePromoteRequest({
+    from,
+    to,
+    reserved,
+    env,
+  })
+
+  try {
+    // The target namespace directory need not exist yet — `common-dev/` is
+    // brand new the first time anything is promoted into it, and `rename` will
+    // not create a parent for you.
+    mkdirSync(dirname(targetDir), { recursive: true })
+    renameSync(sourceDir, targetDir)
+  } catch (cause) {
+    throw refuse(
+      CODES.WRITE_FAILED,
+      `無法把 ${source.key} 搬到 ${target.key}（${sourceDir} → ${targetDir}）：${cause.message}。`,
+      EXIT.VALIDATION,
+    )
+  }
+
+  const manifest = rewriteIdentity(targetDir, target)
+
+  // 零殘留：草稿的 namespace 目錄空了就一併收掉。`packageDirs` 不看沒有 manifest
+  // 的目錄，所以留著不會出現在列表上——但它會出現在 `ls`，而一個空的 `draft/`
+  // 讀起來像「還有草稿沒清」。失敗不致命（別人可能正好在裡面開新草稿），所以
+  // 這一步不擋成功的搬移。
+  try {
+    const draftRoot = join(templatesRoot(env), source.namespace)
+    if (isEmptyDir(draftRoot)) rmdirSync(draftRoot)
+  } catch {
+    // 目錄非空或被別人握著：轉正本身已經完成，這只是清掃。
+  }
+
+  return {
+    from: source.key,
+    to: target.key,
+    dir: targetDir,
+    manifest,
+    source: join(targetDir, PACKAGE_FILES.DEFAULT_DOC),
+  }
+}