@kamishibai/sdk 0.1.1

package/src/core/vocabulary.js

@@ -0,0 +1,140 @@
+import { walkBlocks } from './blocks.js'
+import { PLUGIN_TYPE_PREFIX, PLUGIN_TYPE_WILDCARD, pluginBlockTypes } from '../blocks/index.js'
+import { CODES, validationError } from './errors.js'
+
+/**
+ * `manifest.blocks` is a *guard*, not a brochure.
+ *
+ * A template draws the block types it knows and skips the rest. Skipping is the
+ * right behaviour for a renderer — but as the only behaviour it is a silent
+ * data-loss channel: handing a deck tree to `kami/long-form` (via `replay -t`
+ * or a block-tree JSON that names the wrong template) dropped every slide,
+ * produced an empty-bodied artifact, and still reported exit 0, `lint` 0 and a
+ * slide count. Nothing in the pipeline could see it.
+ *
+ * So the vocabulary a template declares is checked against the document before
+ * anything is drawn. A template that cannot express the document must say so
+ * (CONTRACT C4) rather than quietly render less than it was given.
+ *
+ * Two claims are checked, because one cannot stand in for the other:
+ *
+ *  - `manifest.blocks` — which types this template can draw.
+ *  - `manifest.root`   — which *shape* the document must have at its root.
+ *
+ * The mirror case is what forces the second: `kami/slides` must declare the
+ * whole long-form vocabulary (prose, list, table … are all legal inside a
+ * slide), so a flat document tree passes the type check completely — and then
+ * the template draws only `deck.slides`, i.e. nothing, with a progress readout
+ * of `1 / 0` contradicting itself on screen. Type-legal, shape-wrong.
+ */
+
+/** Every block type present in a tree, in document order of first appearance. */
+export function collectBlockTypes(doc) {
+  const seen = new Map()
+  for (const { block, path } of walkBlocks(doc)) {
+    const type = block?.type
+    if (typeof type !== 'string' || seen.has(type)) continue
+    seen.set(type, path)
+  }
+  return seen
+}
+
+/** The block types sitting directly under `doc` — the document's root form. */
+const rootForms = (doc) =>
+  (doc?.children ?? []).map((block) => block?.type).filter((type) => typeof type === 'string')
+
+/**
+ * Throw unless the document's root form matches the one its 文體 requires.
+ *
+ * The requirement is the **layout's**, and only the layout's. 「replay 換皮不換
+ * 文體」 stopped being a rule two templates happened to obey and became a
+ * structure every deck template inherits (wayfinder issue 13 裁決 1) — which is
+ * exactly the claim a `manifest.root ?? layout.rootForm` fallback would give
+ * back: a template declaring `root: 'section'` on the `deck` layout would have
+ * *overwritten* its 文體's requirement, sail past this guard, and then be drawn
+ * by a root form that looks for a deck and finds none. The artifact that comes
+ * out has an empty body and a playback script attached to it — the exact zombie
+ * `src/layouts/deck.js` claims to have abolished.
+ *
+ * A template's own `manifest.root` is therefore a *restatement*, not a source:
+ * `assertLayoutRootForm` refuses any template whose restatement disagrees, so
+ * by the time this runs the two are known to be the same sentence.
+ */
+function assertRootForm({ doc, manifest, layout, key }) {
+  const required = layout === undefined ? manifest.root : layout.rootForm
+  if (typeof required !== 'string' || required.length === 0) return
+  const present = rootForms(doc)
+  if (present.includes(required)) return
+  const got = present.length === 0 ? '空的 doc' : `doc 形（頂層為 ${[...new Set(present)].join(', ')}）`
+  throw validationError(
+    `template "${key}" 需要 \`${required}\` 根形，收到 ${got}。` +
+      `簡報須以 ${required} 語料著作（frontmatter \`template: ${key}\` ＋ \`---\` 切頁符），` +
+      '書轉簡報屬文體轉換而非換皮：replay 只換皮，不重寫文體。' +
+      `否則此模板只會畫出 ${required} 以外一律丟棄的空殼。`,
+    CODES.TEMPLATE_BLOCK_UNSUPPORTED,
+    'doc.children',
+  )
+}
+
+/**
+ * `manifest.blocks` stays the **one** admission rule, for plugin blocks too.
+ *
+ * A manifest is written before any given plugin exists, so it cannot name
+ * `x-gallery` by hand — but it can admit the *class*: listing the `x-*` wildcard
+ * says "this template is willing to draw plugin blocks". Admitting every
+ * registered plugin unconditionally would have been the easy answer and the
+ * wrong one — it hands a template blocks it has no stylesheet for, and the
+ * guard exists precisely because a block nobody painted renders as invisible
+ * data loss with exit 0.
+ *
+ * Registration is checked *before* either form of declaration, and that order
+ * is the point. An `x-…` name nobody registered has no module, so it would sail
+ * through admission and then be dropped by `renderChildren` — exit 0, block
+ * gone, which is the exact data-loss channel this guard exists to make loud.
+ * Requiring it only on the wildcard branch left the hole open on the other one:
+ * a manifest that hand-types `x-galery` for `x-gallery` is a typo, and a typo
+ * must not be the thing that silently deletes content (seal F7).
+ */
+function admits(manifest, type) {
+  const declared = manifest.blocks ?? []
+  const isPlugin = type.startsWith(PLUGIN_TYPE_PREFIX)
+  if (isPlugin && !pluginBlockTypes().includes(type)) return false
+  if (declared.includes(type)) return true
+  // The class wildcard admits plugin blocks only; it is never a way for a
+  // template to acquire core types it never declared.
+  return isPlugin && declared.includes(PLUGIN_TYPE_WILDCARD)
+}
+
+/**
+ * Throw unless every block type in `doc` is admitted by the template.
+ *
+ * Refusal is loud, for core and plugin types alike: this guard's whole reason
+ * for existing is that silently drawing less than you were given is a data-loss
+ * channel nothing downstream can see (CONTRACT C4). A plugin block is not a
+ * softer case — an unadmitted one means the template has no paint for it.
+ */
+function assertDeclaredTypes({ doc, manifest, key }) {
+  for (const [type, path] of collectBlockTypes(doc)) {
+    if (admits(manifest, type)) continue
+    throw validationError(
+      `template "${key}" 的詞彙表不含 block 型別 \`${type}\`；` +
+        `該模板宣告：${[...(manifest.blocks ?? [])].join(', ')}。改用能表達它的模板，` +
+        '或先把文件轉成該模板的詞彙——渲染層不會靜默濾除看不懂的 block。',
+      CODES.TEMPLATE_BLOCK_UNSUPPORTED,
+      path,
+    )
+  }
+}
+
+/**
+ * Assert that a template can express this document, in both type and shape.
+ *
+ * @param {{doc: object, manifest: {namespace: string, name: string,
+ *   blocks: string[], root?: string|null}, layout?: {rootForm?: string|null}}} input
+ * @throws {import('./errors.js').KsbError} exit 1 / KSB_TEMPLATE_BLOCK_UNSUPPORTED
+ */
+export function assertTemplateVocabulary({ doc, manifest, layout }) {
+  const key = `${manifest.namespace}/${manifest.name}`
+  assertDeclaredTypes({ doc, manifest, key })
+  assertRootForm({ doc, manifest, layout, key })
+}

package/src/delivery/atomic.js

@@ -0,0 +1,71 @@
+import { appendFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+/**
+ * Crash-safe file replacement: write a sibling temp file, then `rename` it over
+ * the target (CONTRACT D6, the S2 ride-along).
+ *
+ * The sidecar index is the case that forced this. `writeFileSync` truncates
+ * first and writes after, so a process killed in between leaves a **zero-byte
+ * or half-written** index — and the reader treats a corrupt sidecar as "no
+ * delivery copies", i.e. the record is silently gone rather than visibly broken.
+ * `rename` within one directory is atomic: a reader sees either the whole old
+ * file or the whole new one, never a torn one.
+ *
+ * The temp name carries the pid and a per-process counter, so two concurrent
+ * writers cannot land on the same scratch file and corrupt each other — which
+ * is the same reasoning that makes the artifact write exclusive (`wx`).
+ */
+
+let sequence = 0
+
+const tempPathFor = (targetPath) => {
+  sequence += 1
+  return join(dirname(targetPath), `.${basename(targetPath)}.${process.pid}.${sequence}.tmp`)
+}
+
+/**
+ * Append one record line to an append-only log (CONTRACT E2 的留言 sidecar).
+ *
+ * The rename dance above is the wrong tool here and would be actively worse: a
+ * read-all/rewrite-all cycle turns an append-only history into a full-file
+ * replacement, so a crash — or a second writer — can lose records that were
+ * already durable. A single `O_APPEND` write of one line is what an append log
+ * actually needs: the kernel places every writer at the current end of file, so
+ * concurrent appends interleave by record instead of overwriting each other.
+ *
+ * The line is written in one call for that reason; callers must therefore pass
+ * one complete record **without** its trailing newline — this function adds the
+ * terminator, so that the record and its delimiter cannot be split across two
+ * writes and interleaved with somebody else's.
+ *
+ * @param {string} targetPath absolute path of the log
+ * @param {string} line one record, without its trailing newline
+ * @returns {string} the target path
+ */
+export function appendLineAtomic(targetPath, line) {
+  if (line.includes('\n')) {
+    throw new Error('append record must be a single line; embedded newline would split the record')
+  }
+  appendFileSync(targetPath, `${line}\n`, { encoding: 'utf8', flag: 'a' })
+  return targetPath
+}
+
+/**
+ * @param {string} targetPath absolute path to replace
+ * @param {string} data file contents
+ * @returns {string} the target path
+ */
+export function writeFileAtomic(targetPath, data) {
+  const tmp = tempPathFor(targetPath)
+  try {
+    writeFileSync(tmp, data, { encoding: 'utf8', flag: 'wx' })
+    renameSync(tmp, targetPath)
+  } catch (cause) {
+    // A failed write must not leave scratch files behind: the store is a
+    // permanent record, and residue there is indistinguishable from content.
+    rmSync(tmp, { force: true })
+    throw cause
+  }
+  return targetPath
+}

package/src/delivery/comments.js

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { appendLineAtomic } from './atomic.js'
+
+/**
+ * The block-anchored comment loop (CONTRACT E2, SPEC §13.1).
+ *
+ * Two properties carry the whole design:
+ *
+ * 1. **Comments are data, never edits.** Nothing here touches the artifact. A
+ *    comment is a row in a log beside it, so the artifact stays exactly what
+ *    the renderer produced and the file remains the single source of truth.
+ * 2. **The log is append-only.** Resolving a comment appends a *new* record
+ *    with the same id and `status: "resolved"`; it never rewrites the line that
+ *    recorded the original opinion. A human's comment is testimony — the
+ *    record of what was said must survive the decision to act on it, which is
+ *    also what lets an Agent see that a comment was raised at all after it has
+ *    been dealt with.
+ *
+ * Reading folds the log by id, last record wins. Every record therefore has
+ * the same five keys, which is what keeps `comments --json` a homogeneous array
+ * rather than a union of two shapes.
+ */
+
+/** Verbatim CONTRACT constant — the sidecar suffix, appended to the artifact path. */
+export const COMMENTS_SUFFIX = '.comments.jsonl'
+/** Verbatim CONTRACT constant — comment fields, in output order. */
+export const COMMENT_KEYS = Object.freeze(['id', 'blockId', 'text', 'ts', 'status'])
+/** Verbatim CONTRACT constant — the two legal statuses. */
+export const STATUS_OPEN = 'open'
+export const STATUS_RESOLVED = 'resolved'
+
+/** `<canonical>.comments.jsonl` — beside the artifact it belongs to. */
+export function commentsPath(artifactPath) {
+  return `${resolve(artifactPath)}${COMMENTS_SUFFIX}`
+}
+
+const validationError = (code, message) =>
+  new KsbError({ code, message, exitCode: EXIT.VALIDATION })
+
+/**
+ * Raw records in write order. A malformed line is skipped rather than fatal:
+ * the log may be appended to by a server that died mid-line, and one torn
+ * record must not make every earlier comment unreadable.
+ */
+export function readCommentRecords(artifactPath) {
+  const path = commentsPath(artifactPath)
+  if (!existsSync(path)) return []
+  let text
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (cause) {
+    throw validationError(
+      CODES.ARTIFACT_UNREADABLE,
+      `could not read comments sidecar ${path}: ${cause.message}`,
+    )
+  }
+  const records = []
+  for (const line of text.split('\n')) {
+    if (line.trim().length === 0) continue
+    try {
+      const parsed = JSON.parse(line)
+      if (parsed && typeof parsed.id === 'string') records.push(parsed)
+    } catch {
+      continue
+    }
+  }
+  return records
+}
+
+/** Exactly the five pinned keys, in the pinned order. */
+const toEntry = (record) => ({
+  id: String(record.id),
+  blockId: String(record.blockId ?? ''),
+  text: String(record.text ?? ''),
+  ts: String(record.ts ?? ''),
+  status: record.status === STATUS_RESOLVED ? STATUS_RESOLVED : STATUS_OPEN,
+})
+
+/**
+ * Effective comments: folded by id (last record wins), ordered by the first
+ * time each id appeared, so resolving a comment never reorders the list.
+ *
+ * @returns {Array<{id: string, blockId: string, text: string, ts: string, status: string}>}
+ */
+export function listComments(artifactPath) {
+  const order = []
+  const byId = new Map()
+  for (const record of readCommentRecords(artifactPath)) {
+    if (!byId.has(record.id)) order.push(record.id)
+    byId.set(record.id, record)
+  }
+  return order.map((id) => toEntry(byId.get(id)))
+}
+
+/** `c1`, `c2`, … — one past the highest id already in the log. */
+const nextCommentId = (records) => {
+  let highest = 0
+  for (const record of records) {
+    const match = /^c(\d+)$/.exec(String(record.id))
+    if (match !== null) highest = Math.max(highest, Number(match[1]))
+  }
+  return `c${highest + 1}`
+}
+
+const appendRecord = (artifactPath, entry) => {
+  const path = commentsPath(artifactPath)
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    appendLineAtomic(path, JSON.stringify(entry))
+  } catch (cause) {
+    throw validationError(
+      CODES.WRITE_FAILED,
+      `could not append to comments sidecar ${path}: ${cause.message}`,
+    )
+  }
+  return entry
+}
+
+/**
+ * Append one comment, anchored to a block that must exist.
+ *
+ * `blockIds` is supplied by the caller (read off the artifact's IR) rather than
+ * parsed here: this layer never learns what an artifact looks like inside, and
+ * the server and the CLI must validate against the *same* set or the two write
+ * paths would disagree about which anchors are legal.
+ *
+ * @param {{artifactPath: string, blockId: string, text: string,
+ *   blockIds: Set<string>|string[], now?: Date}} input
+ */
+export function appendComment({ artifactPath, blockId, text, blockIds, now = new Date() }) {
+  const legal = blockIds instanceof Set ? blockIds : new Set(blockIds ?? [])
+  const anchor = String(blockId ?? '').trim()
+  const body = String(text ?? '').trim()
+
+  if (anchor.length === 0) {
+    throw validationError(CODES.BLOCK_NOT_FOUND, 'comment must name a blockId')
+  }
+  if (!legal.has(anchor)) {
+    throw validationError(
+      CODES.BLOCK_NOT_FOUND,
+      `block "${anchor}" is not in this artifact's IR; known ids: ${[...legal].join(', ')}`,
+    )
+  }
+  if (body.length === 0) {
+    throw validationError(CODES.INPUT_EMPTY, 'comment text must not be empty')
+  }
+
+  const id = nextCommentId(readCommentRecords(artifactPath))
+  return appendRecord(artifactPath, {
+    id,
+    blockId: anchor,
+    text: body,
+    ts: now.toISOString(),
+    status: STATUS_OPEN,
+  })
+}
+
+/**
+ * Mark a comment resolved by appending a resolution record. The original line
+ * stays exactly where it was.
+ *
+ * @param {{artifactPath: string, id: string, now?: Date}} input
+ */
+export function resolveComment({ artifactPath, id, now = new Date() }) {
+  const wanted = String(id ?? '').trim()
+  const current = listComments(artifactPath).find((entry) => entry.id === wanted)
+  if (current === undefined) {
+    throw validationError(
+      CODES.COMMENT_NOT_FOUND,
+      `no comment "${wanted}" on ${resolve(artifactPath)}`,
+    )
+  }
+  return appendRecord(artifactPath, {
+    ...current,
+    ts: now.toISOString(),
+    status: STATUS_RESOLVED,
+  })
+}

package/src/delivery/home.js

@@ -0,0 +1,70 @@
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/**
+ * The single resolver for the central store root (CONTRACT B1).
+ *
+ * Every path that touches `~/.kamishibai` must come through here. Two callers
+ * each doing their own `join(homedir(), …)` is how a test suite ends up writing
+ * into the developer's real store: one of them will miss the override, and
+ * nothing downstream can tell that it did.
+ */
+
+/** Verbatim CONTRACT constant. */
+export const HOME_ENV = 'KAMISHIBAI_HOME'
+/** Verbatim CONTRACT constant — default store root is `~/.kamishibai`. */
+export const DEFAULT_HOME_DIRNAME = '.kamishibai'
+/** Verbatim CONTRACT constant — 庫佈局 `artifacts/<專案名>/<slug>.html`. */
+export const ARTIFACTS_DIRNAME = 'artifacts'
+/** Verbatim CONTRACT constant — 標記檔名. */
+export const MARKER_FILENAME = 'created-by'
+/** Verbatim CONTRACT constant — `templates/<namespace>/<name>/manifest.toml`. */
+export const TEMPLATES_DIRNAME = 'templates'
+/** Verbatim CONTRACT constant — `<KAMISHIBAI_HOME>/run/serve.pid`. */
+export const RUN_DIRNAME = 'run'
+/** Verbatim CONTRACT constant — the serve pidfile's basename. */
+export const SERVE_PIDFILE = 'serve.pid'
+
+/** Absolute store root: `KAMISHIBAI_HOME` wins, else `~/.kamishibai`. */
+export function resolveHome(env = process.env) {
+  const override = env?.[HOME_ENV]
+  if (typeof override === 'string' && override.trim().length > 0) {
+    return resolve(override.trim())
+  }
+  return join(homedir(), DEFAULT_HOME_DIRNAME)
+}
+
+/** `<HOME>/artifacts` */
+export function artifactsRoot(env = process.env) {
+  return join(resolveHome(env), ARTIFACTS_DIRNAME)
+}
+
+/** `<HOME>/artifacts/<project>` */
+export function projectDir(project, env = process.env) {
+  return join(artifactsRoot(env), project)
+}
+
+/** `<HOME>/created-by` */
+export function markerPath(env = process.env) {
+  return join(resolveHome(env), MARKER_FILENAME)
+}
+
+/** `<HOME>/templates` — the template namespace root (CONTRACT E3). */
+export function templatesRoot(env = process.env) {
+  return join(resolveHome(env), TEMPLATES_DIRNAME)
+}
+
+/** `<HOME>/templates/<namespace>/<name>` */
+export function templatePackageDir(namespace, name, env = process.env) {
+  return join(templatesRoot(env), namespace, name)
+}
+
+/** `<HOME>/run` — ephemeral process state, never a record. */
+export function runDir(env = process.env) {
+  return join(resolveHome(env), RUN_DIRNAME)
+}
+
+/** `<HOME>/run/serve.pid` */
+export function servePidfile(env = process.env) {
+  return join(runDir(env), SERVE_PIDFILE)
+}

package/src/delivery/open.js

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+/**
+ * The single cross-platform opener (SPEC §8 開啟三通道 ①). One chain, tried in
+ * order — WSL first because that is where this SDK is developed and `xdg-open`
+ * there resolves to a Linux browser that cannot show the file to the user.
+ */
+export const OPEN_CHAIN = Object.freeze(['wslview', 'xdg-open', 'explorer.exe', 'open'])
+
+/**
+ * @param {string} target absolute path of the artifact to open
+ * @param {(cmd: string, args: string[]) => void} [run] injected for tests
+ * @returns {string} the launcher that succeeded
+ */
+export function openPath(target, run = (cmd, args) => execFileSync(cmd, args, { stdio: 'ignore' })) {
+  const tried = []
+  for (const cmd of OPEN_CHAIN) {
+    try {
+      run(cmd, [target])
+      return cmd
+    } catch {
+      tried.push(cmd)
+    }
+  }
+  throw new KsbError({
+    code: CODES.OPEN_FAILED,
+    message: `could not open ${target}; tried: ${tried.join(', ')}`,
+    exitCode: EXIT.VALIDATION,
+  })
+}

package/src/delivery/project.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+/**
+ * Project resolution (SPEC §9.1). The order is contractual:
+ *
+ *   `--project` → `.kamishibai.toml` → git root → cwd
+ *
+ * The anchor file sits above git root in the order on purpose: a non-git
+ * directory (or a sub-repo checked out inside another repo) still needs a
+ * stable project identity, and running from a nested subdirectory must resolve
+ * to the same project as running from its root.
+ */
+
+/** Verbatim CONTRACT constant — the project anchor file. */
+export const ANCHOR_FILENAME = '.kamishibai.toml'
+const GIT_MARKER = '.git'
+
+/** Resolution layers, in contract order — exported so tests read the真源. */
+export const RESOLUTION_ORDER = Object.freeze(['--project', ANCHOR_FILENAME, 'git-root', 'cwd'])
+
+/**
+ * Project names are validated in two tiers, because the two sources are not
+ * the same kind of input (seal 補釘 F1):
+ *
+ * - What the user *typed* (`--project`) is rejected when illegal. Silently
+ *   rewriting it would archive into a directory they never asked for.
+ * - What we *derived* (anchor file / git root / cwd) is normalised. Nobody
+ *   chooses to work in `~/Google Drive/My Project`, and S1 ran there fine —
+ *   refusing to render because a parent folder has a space is our bug, not
+ *   the user's.
+ */
+const INVALID_NAME = /[/\\\s]/
+
+/** Substituted for any character that may not appear in a directory name. */
+export const NAME_SEPARATOR = '-'
+/** Last resort when normalisation leaves nothing usable. */
+export const FALLBACK_PROJECT = 'unnamed-project'
+
+const rejectName = (name, why) =>
+  new KsbError({
+    code: CODES.USAGE,
+    message: `invalid project name "${name}": ${why}`,
+    exitCode: EXIT.USAGE,
+  })
+
+/** Strict tier — for names the user supplied verbatim. */
+export function assertProjectName(name) {
+  const trimmed = String(name ?? '').trim()
+  if (trimmed.length === 0) throw rejectName(name, 'must not be empty')
+  if (trimmed === '.' || trimmed === '..' || trimmed.includes('..')) {
+    throw rejectName(trimmed, 'must not contain path traversal')
+  }
+  if (INVALID_NAME.test(trimmed)) {
+    throw rejectName(trimmed, 'must not contain path separators or whitespace')
+  }
+  return trimmed
+}
+
+/**
+ * Lenient tier — deterministic normalisation for derived names.
+ *
+ * Deterministic is the whole point: the same directory must resolve to the
+ * same project on every run, or a project's history silently splits in two.
+ * The result is then put through the strict check, so normalisation can never
+ * emit something the strict tier would have rejected.
+ */
+export function normaliseProjectName(name) {
+  const normalised = String(name ?? '')
+    .trim()
+    // eslint-disable-next-line no-control-regex
+    .replace(/[/\\\s\u0000-\u001f]+/g, NAME_SEPARATOR)
+    .replace(/\.{2,}/g, NAME_SEPARATOR)
+    .replace(new RegExp(`\\${NAME_SEPARATOR}{2,}`, 'g'), NAME_SEPARATOR)
+    .replace(new RegExp(`^\\${NAME_SEPARATOR}+|\\${NAME_SEPARATOR}+$`, 'g'), '')
+
+  if (normalised.length === 0 || normalised === '.') return FALLBACK_PROJECT
+  return assertProjectName(normalised)
+}
+
+/** Walk from `start` up to the filesystem root, returning the first hit. */
+const walkUp = (start, probe) => {
+  let dir = resolve(start)
+  for (;;) {
+    const hit = probe(dir)
+    if (hit !== null) return hit
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * Read the project name out of an anchor file. Only the `name = "…"` key is
+ * consulted — S2 needs the anchor *read*, not a general TOML implementation
+ * (the manifest parser lands with the template-authoring slice). An anchor
+ * without a usable name still anchors: the directory holding it wins.
+ */
+const anchorName = (file) => {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (cause) {
+    throw new KsbError({
+      code: CODES.ARTIFACT_UNREADABLE,
+      message: `could not read project anchor ${file}: ${cause.message}`,
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+  const match = /^\s*name\s*=\s*["']([^"'\n]+)["']/m.exec(text)
+  return match ? match[1].trim() : basename(dirname(file))
+}
+
+const fromAnchor = (cwd) =>
+  walkUp(cwd, (dir) => {
+    const candidate = join(dir, ANCHOR_FILENAME)
+    return existsSync(candidate) ? candidate : null
+  })
+
+const fromGitRoot = (cwd) => walkUp(cwd, (dir) => (existsSync(join(dir, GIT_MARKER)) ? dir : null))
+
+/**
+ * @param {{project?: string, cwd?: string}} input
+ * @returns {{name: string, source: string}} resolved project and which layer won
+ */
+export function resolveProject({ project, cwd = process.cwd() } = {}) {
+  if (project !== undefined && project !== null && String(project).length > 0) {
+    return { name: assertProjectName(project), source: '--project' }
+  }
+
+  const anchor = fromAnchor(cwd)
+  if (anchor !== null) {
+    return { name: normaliseProjectName(anchorName(anchor)), source: ANCHOR_FILENAME }
+  }
+
+  const gitRoot = fromGitRoot(cwd)
+  if (gitRoot !== null) return { name: normaliseProjectName(basename(gitRoot)), source: 'git-root' }
+
+  return { name: normaliseProjectName(basename(resolve(cwd))), source: 'cwd' }
+}