@kamishibai/sdk 0.1.1

package/src/core/lint.js

@@ -0,0 +1,281 @@
+import { CODES, ROOT_PATH } from './errors.js'
+import { validateIr } from './validate.js'
+import { cssRuleBlocks, liveMarkup, styleBlocks, styleRegions, svgRegions } from './scan.js'
+import { gateRuleListing, lintGates } from './lint-gates.js'
+
+/**
+ * CONTRACT 外部資源禁形 — every artifact must be able to live offline.
+ * `scope` picks the region each rule is judged against (see ./scan.js).
+ *
+ * Exported as the single source of truth: the A3 test asserts against these
+ * very rules rather than transcribing its own copy, so the禁形 list can never
+ * drift between the linter and the criterion that motivates it.
+ */
+export const EXTERNAL_RULES = Object.freeze([
+  { re: /<link\b[^>]*\bhref\s*=/i, code: CODES.EXTERNAL_STYLESHEET, what: '<link …href=', scope: 'markup' },
+  { re: /<script\b[^>]*\bsrc\s*=/i, code: CODES.EXTERNAL_SCRIPT, what: '<script …src=', scope: 'markup' },
+  { re: /<img\b[^>]*\bsrc\s*=\s*["']?http/i, code: CODES.EXTERNAL_IMAGE, what: '<img …src="http', scope: 'markup' },
+  { re: /@import/i, code: CODES.EXTERNAL_CSS_IMPORT, what: '@import', scope: 'css' },
+  { re: /url\(\s*["']?http/i, code: CODES.EXTERNAL_CSS_URL, what: 'url(http', scope: 'css' },
+])
+
+/**
+ * CONTRACT 禁用字串 — strings whose mere presence means the artifact is
+ * *shipping* something it has no licence to ship.
+ *
+ * `scope` follows the same rule as EXTERNAL_RULES, and for the same reason
+ * (CONTRACT A3「內容文字…不在此限」): a font is redistributed by being
+ * *declared or embedded in CSS*, never by being named in body text. Scanning
+ * the raw document instead would fail any document that writes about the ban —
+ * the project's own SPEC.md, which records the TsangerJinKai02 licence NO-GO,
+ * is exactly such a document.
+ */
+export const BANNED_STRINGS = Object.freeze([
+  { needle: 'TsangerJinKai', code: CODES.BANNED_FONT, why: '未取得再散布授權的字體', scope: 'css' },
+])
+
+/**
+ * What a `scope` *means*, in one clause per region — the single wording behind
+ * both scoped surfaces.
+ *
+ * The benchmark (§3) watched an agent spend a `sed` and a `grep` on
+ * `./scan.js` just to learn whether the banned-font rule reads the whole
+ * document or only its CSS. Guessing wrong costs a rewrite, so verifying was
+ * rational; the fix is to stop making it necessary. These clauses are appended
+ * to every scoped failure message *and* returned by `lint --rules`, so the
+ * answer arrives whether the agent asks up front or only learns on failure.
+ *
+ * Wording derived from ./scan.js: `liveMarkup` keeps everything the browser
+ * will act on and drops the inert IR payload, and rendered content text is
+ * entity-escaped, so it can never match a tag form.
+ */
+export const SCOPE_NOTES = Object.freeze({
+  markup: '；本規則只掃瀏覽器實際生效的 markup，內嵌 IR 與轉義後的正文不受限',
+  css: '；本規則只掃 CSS 區域，正文提及不受限',
+  svg: '；本規則只掃 `<svg>` 子樹，圖外的同形不受限',
+})
+
+/**
+ * CONTRACT F7b — the universal rules collected out of the six retired gates.
+ *
+ * They are a separate table from `EXTERNAL_RULES` for a reason that is pinned
+ * rather than stylistic: A3's five 禁形 are a **verbatim CONTRACT constant**
+ * (`test_a3_forbidden_forms_match_contract_verbatim` compares the `what` column
+ * to the contract line, in order), so that table is a quotation and cannot grow.
+ * These are the rules F7b judged universal — true of *every* artifact the SDK
+ * draws, whatever design language it wears — and each carries its own reason,
+ * because unlike the five they do not share one.
+ *
+ * What is deliberately **not** here is any form of the `rgba()` ban. The
+ * whole-file form (`check.py` inv 8) would have failed `kami/resume` on the day
+ * it landed, and the SVG-scoped form (book #7b) turned out not to be universal
+ * either: its damage model is 「export pdf/pptx 會把 alpha 壓平」, which only
+ * bites a product that is going to be exported. A sand table that lives its
+ * whole life as HTML never meets it, and the first real skinned product did in
+ * fact come back red on an artifact the user had already accepted. Applicability
+ * that varies with what the artifact is *for* is the definition of a gate, so
+ * `rgba()` lives in `[gates] svgRgbaBan`. See `docs/lint-consolidation.md`
+ * 衝突組 3 and CONTRACT R10.
+ *
+ * The four that remain are the ones whose damage model does **not** vary with
+ * use: an executing figure is a security surface and a dangling marker is a
+ * silently missing arrowhead, whoever is looking and wherever it is going.
+ */
+export const SCAN_RULES = Object.freeze([
+  {
+    re: /<[a-zA-Z][\w-]*\b[^>]*\bsrc\s*=\s*["'](?!data:)/i,
+    code: CODES.EXTERNAL_ASSET_SRC,
+    what: 'src="…"（非 data:）',
+    why: '離線單檔沒有「檔案就在旁邊」這回事，相對路徑一離開這台機器就是破圖',
+    scope: 'markup',
+  },
+  {
+    re: /<script\b/i,
+    code: CODES.SVG_SCRIPT,
+    what: '<script',
+    why: '圖是靜態插畫；會執行的圖在匯出與離線檢視兩條路上都不成立',
+    scope: 'svg',
+  },
+  {
+    re: /\son[a-z]+\s*=\s*["']/i,
+    code: CODES.SVG_EVENT_HANDLER,
+    what: 'on…=',
+    why: '同上：互動歸 block 的播放層，不歸圖本身',
+    scope: 'svg',
+  },
+  {
+    re: /\b(?:xlink:)?href\s*=\s*["']?\s*javascript:/i,
+    code: CODES.SVG_JAVASCRIPT_URL,
+    what: 'href="javascript:',
+    why: '圖裡的可執行連結；離線產物會被當成一般網頁開啟，這條就是活的',
+    scope: 'svg',
+  },
+])
+
+/**
+ * CONTRACT F7b — marker bijection, the one collected rule that is not a form.
+ *
+ * `marker-end="url(#arrow)"` pointing at a `<marker>` nobody defined does not
+ * fail, warn, or draw anything: the arrowhead is simply **not there**, and the
+ * diagram still looks like a diagram. That is the same silent-loss shape
+ * `KSB_BOARD_INVALID` (a card on an undeclared lane) and `KSB_GRAPH_INVALID`
+ * (an edge to an undeclared node) already exist to refuse, which is why it is
+ * core rather than a gate: no design language makes a missing arrowhead fine.
+ *
+ * The *other* half of the collected gate — an unused `<marker>` definition — is
+ * not collected. A definition nobody references costs bytes, not meaning, and
+ * a package may legitimately ship one skin's markers for several diagrams.
+ */
+export const MARKER_RULE = Object.freeze({
+  code: CODES.SVG_MARKER_DANGLING,
+  scope: 'svg',
+  pattern: 'marker-(end|start|mid)="url(#id)" ↔ <marker id="id">',
+  why: '指不到的 marker 不會報錯，只會讓箭頭安靜地消失',
+})
+
+const MARKER_DEF_RE = /<marker\b[^>]*\bid\s*=\s*["']([^"']+)["']/gi
+const MARKER_REF_RE = /\bmarker-(?:end|start|mid)\s*=\s*["']\s*url\(\s*#([^)\s"']+)\s*\)\s*["']/gi
+
+/** Why an external-resource form is banned at all — one reason for all five. */
+const EXTERNAL_REASON = '違反零外部請求'
+
+const externalMessage = ({ what, scope }) =>
+  `產物含外部資源引用形 \`${what}\`，${EXTERNAL_REASON}${SCOPE_NOTES[scope]}`
+
+const bannedMessage = ({ needle, why, scope }) =>
+  `產物含禁用字串 \`${needle}\`（${why}）${SCOPE_NOTES[scope]}`
+
+const scanMessage = ({ what, why, scope }) => `產物含 \`${what}\`：${why}${SCOPE_NOTES[scope]}`
+
+/**
+ * The rule set as data, for `kamishibai lint --rules`.
+ *
+ * Derived from the frozen tables above rather than transcribed: a third
+ * copy would be free to drift from the linter, and a listing that disagrees
+ * with the gate is worse than no listing at all — it would be believed.
+ *
+ * F7b adds a fifth field, and only to the rules that need it: a gate rule
+ * carries `gate`, the `manifest.toml` key that turns it on. Without it the
+ * listing would show a rule that never fires on most artifacts and give the
+ * reader no way to learn why — which is the exact question `--rules` exists to
+ * answer without anybody reading `src/core/lint.js` (量測報告 §3 R1).
+ *
+ * @returns {Array<{code: string, scope: string, pattern: string, note: string, gate?: string}>}
+ */
+export function lintRules() {
+  return [
+    ...EXTERNAL_RULES.map(({ code, scope, re }) => ({
+      code,
+      scope,
+      pattern: re.source,
+      note: `${EXTERNAL_REASON}${SCOPE_NOTES[scope]}`,
+    })),
+    ...BANNED_STRINGS.map(({ code, scope, needle, why }) => ({
+      code,
+      scope,
+      pattern: needle,
+      note: `${why}${SCOPE_NOTES[scope]}`,
+    })),
+    ...SCAN_RULES.map(({ code, scope, re, why }) => ({
+      code,
+      scope,
+      pattern: re.source,
+      note: `${why}${SCOPE_NOTES[scope]}`,
+    })),
+    {
+      code: MARKER_RULE.code,
+      scope: MARKER_RULE.scope,
+      pattern: MARKER_RULE.pattern,
+      note: `${MARKER_RULE.why}${SCOPE_NOTES[MARKER_RULE.scope]}`,
+    },
+    ...gateRuleListing().map((rule) => ({
+      ...rule,
+      note: `${rule.note}${SCOPE_NOTES[rule.scope]}`,
+    })),
+  ]
+}
+
+const finding = (code, message, path = ROOT_PATH) => ({ path, code, message })
+
+/** The regions every scoped rule is judged against (see ./scan.js). */
+const scanRegions = (html) => ({
+  markup: liveMarkup(html),
+  css: styleRegions(html),
+  svg: svgRegions(html),
+  // Not a `scope`: the selector-aware view the heading gate needs, computed
+  // once here so a gate never has to re-parse the document it was handed.
+  cssBlocks: cssRuleBlocks(styleBlocks(html)),
+})
+
+const lintExternalResources = (regions) =>
+  EXTERNAL_RULES.filter(({ re, scope }) => re.test(regions[scope])).map((rule) =>
+    finding(rule.code, externalMessage(rule)),
+  )
+
+const lintBannedStrings = (regions) =>
+  BANNED_STRINGS.filter(({ needle, scope }) => regions[scope].includes(needle)).map((rule) =>
+    finding(rule.code, bannedMessage(rule)),
+  )
+
+const lintScanRules = (regions) =>
+  SCAN_RULES.filter(({ re, scope }) => re.test(regions[scope])).map((rule) =>
+    finding(rule.code, scanMessage(rule)),
+  )
+
+const lintMarkerIntegrity = (svg) => {
+  const defined = new Set([...svg.matchAll(MARKER_DEF_RE)].map((m) => m[1]))
+  const dangling = [
+    ...new Set(
+      [...svg.matchAll(MARKER_REF_RE)].map((m) => m[1]).filter((id) => !defined.has(id)),
+    ),
+  ]
+  if (dangling.length === 0) return []
+  return [
+    finding(
+      MARKER_RULE.code,
+      `產物的 SVG 引用了未定義的 marker ${dangling.map((id) => `\`#${id}\``).join('、')}` +
+        `：${MARKER_RULE.why}${SCOPE_NOTES[MARKER_RULE.scope]}`,
+    ),
+  ]
+}
+
+const lintEmbeddedIr = (payloads) => {
+  if (payloads.length === 0) {
+    return [finding(CODES.IR_MISSING, '產物缺少內嵌 IR（<script type="application/kamishibai+json">）')]
+  }
+  if (payloads.length > 1) {
+    return [finding(CODES.IR_DUPLICATE, `產物含 ${payloads.length} 份內嵌 IR，應恰為一份`)]
+  }
+  let ir
+  try {
+    ir = JSON.parse(payloads[0])
+  } catch (cause) {
+    return [finding(CODES.IR_UNPARSABLE, `內嵌 IR 不是合法 JSON：${cause.message}`)]
+  }
+  return validateIr(ir).errors
+}
+
+/**
+ * Lint a rendered artifact: offline rules + embedded-IR schema conformance +
+ * whatever gates the artifact's own template package declared.
+ *
+ * The caller supplies the already-extracted IR payloads **and** the already-read
+ * `[gates]` declaration so that this module stays in the dependency-free core
+ * layer (AGENTS §3.1). `gates` absent means no gate runs, which is also what an
+ * artifact drawn with a factory template gets — the five bundled templates
+ * declare none, and F7b deliberately did not give them defaults.
+ *
+ * @param {{html: string, irPayloads: string[], gates?: Record<string, unknown>}} input
+ * @returns {Array<{path: string, code: string, message: string}>} findings, empty when clean
+ */
+export function lintArtifact({ html, irPayloads, gates }) {
+  const regions = scanRegions(html)
+  return [
+    ...lintExternalResources(regions),
+    ...lintBannedStrings(regions),
+    ...lintScanRules(regions),
+    ...lintMarkerIntegrity(regions.svg),
+    ...lintGates(gates ?? {}, regions),
+    ...lintEmbeddedIr(irPayloads),
+  ]
+}

package/src/core/scan.js

@@ -0,0 +1,84 @@
+import { IR_SCRIPT_TYPE } from './ir.js'
+
+/**
+ * Structural slicing of an artifact, so the offline rules judge *live markup*
+ * rather than content that merely talks about it (CONTRACT A3「內容文字…不在此限」).
+ *
+ * Two observations make this cheap and precise:
+ *
+ * 1. Tag forms (`<link href`, `<script src`, `<img src="http`) need a literal
+ *    `<`. Rendered content text is entity-escaped (`&lt;script`), so it can
+ *    never match — no scrubbing required, and a *raw island*, which is injected
+ *    unescaped and really does fire, still matches exactly as it should.
+ * 2. CSS forms (`@import`, `url(http`) carry no `<`, so escaping does not
+ *    neutralise them. They are only meaningful inside a CSS context, so they
+ *    are scanned only there.
+ *
+ * The embedded IR is inert data, never executed, so it is excluded from both.
+ */
+
+const IR_SCRIPT_RE = new RegExp(
+  `<script[^>]*type\\s*=\\s*["']${IR_SCRIPT_TYPE.replace('+', '\\+')}["'][^>]*>[\\s\\S]*?<\\/script>`,
+  'gi',
+)
+
+const STYLE_BLOCK_RE = /<style\b[^>]*>([\s\S]*?)<\/style>/gi
+const STYLE_ATTR_RE = /\sstyle\s*=\s*"([^"]*)"|\sstyle\s*=\s*'([^']*)'/gi
+
+/** Markup that the browser will actually act on: everything but the IR payload. */
+export function liveMarkup(html) {
+  return String(html ?? '').replace(IR_SCRIPT_RE, '')
+}
+
+/** Every CSS context in the artifact: <style> blocks plus inline style attributes. */
+export function styleRegions(html) {
+  const live = liveMarkup(html)
+  const regions = []
+  for (const m of live.matchAll(STYLE_BLOCK_RE)) regions.push(m[1])
+  for (const m of live.matchAll(STYLE_ATTR_RE)) regions.push(m[1] ?? m[2] ?? '')
+  return regions.join('\n')
+}
+
+/**
+ * Every `<svg>` subtree in the artifact — the third region, added by F7b.
+ *
+ * A figure is judged by different rules than the page around it, and the six
+ * collected gates all say so in their own way: `rgba()` is ordinary CSS in a
+ * stylesheet and a lost alpha channel in an exported PDF; a `<script>` in the
+ * document body is how playback works and has no business inside an
+ * illustration. Scanning the whole document for either form would fail every
+ * artifact the SDK draws (`kami/resume`'s stylesheet really does use `rgba()`),
+ * which is why the collected form is the *scoped* one, never the whole-file one.
+ *
+ * Non-greedy, so a nested `<svg>` closes its parent early. That is the safe
+ * direction: the tail of the outer figure is then scanned as page markup, where
+ * every rule here is a strict subset of what the markup rules already allow.
+ */
+const SVG_BLOCK_RE = /<svg\b[^>]*>[\s\S]*?<\/svg>/gi
+
+export function svgRegions(html) {
+  return [...liveMarkup(html).matchAll(SVG_BLOCK_RE)].map((m) => m[0]).join('\n')
+}
+
+/** Just the `<style>` blocks — the only CSS that carries selectors. */
+export function styleBlocks(html) {
+  return [...liveMarkup(html).matchAll(STYLE_BLOCK_RE)].map((m) => m[1]).join('\n')
+}
+
+/**
+ * `<style>` CSS as `{selector, body}` pairs, for the rules that must know *what
+ * a declaration applies to* (a `font-weight` ceiling means nothing until you
+ * know whether the block is a heading).
+ *
+ * The pattern matches innermost brace pairs, so a rule nested in `@media`
+ * yields the inner selector rather than the at-rule — which is what a reader
+ * expects and what the two collected implementations both failed to do.
+ */
+const CSS_RULE_RE = /([^{}]+)\{([^{}]*)\}/g
+
+export function cssRuleBlocks(css) {
+  return [...String(css ?? '').matchAll(CSS_RULE_RE)].map((m) => ({
+    selector: m[1].trim(),
+    body: m[2],
+  }))
+}

package/src/core/schema.js

@@ -0,0 +1,88 @@
+import { blockModules, blockTypes } from '../blocks/index.js'
+import { children, str } from '../blocks/schema-parts.js'
+import { PLACEMENT_PROPERTIES } from '../blocks/placement.js'
+import { META_KEY_ORDER } from './blocks.js'
+import { IR_VERSION } from './ir.js'
+
+export const SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema'
+export const SCHEMA_ID = 'https://kamishibai.dev/schema/ir-1.json'
+
+/**
+ * One `if type is X then these fields` branch. The branch bodies are not
+ * written here: each block module carries its own, so registering a plugin
+ * block widens the schema without this file knowing the type exists (A4).
+ */
+const whenType = (type, then) => ({
+  if: { required: ['type'], properties: { type: { const: type } } },
+  then,
+})
+
+const metaProperties = () => Object.fromEntries(META_KEY_ORDER.map((key) => [key, str]))
+
+/**
+ * The IR JSON Schema (draft 2020-12). Single source of truth for `lint`,
+ * for the `schema` command, and — by SPEC §15.2 — for generated docs.
+ *
+ * Built fresh on every call rather than frozen at import: the block vocabulary
+ * can grow after load, and a schema cached before a plugin registered would
+ * reject the very block the renderer had just drawn.
+ */
+export function irSchema() {
+  return {
+    $schema: SCHEMA_DIALECT,
+    $id: SCHEMA_ID,
+    title: 'Kamishibai IR',
+    description: '產物內嵌的 kamishibai IR 封包（SPEC §7.3）',
+    type: 'object',
+    required: ['irVersion', 'engine', 'template', 'doc', 'createdAt', 'generator'],
+    properties: {
+      irVersion: { ...str, const: IR_VERSION },
+      engine: str,
+      template: {
+        type: 'object',
+        required: ['namespace', 'name', 'version'],
+        properties: { namespace: str, name: str, version: str },
+        additionalProperties: false,
+      },
+      doc: { $ref: '#/$defs/doc' },
+      createdAt: str,
+      generator: str,
+    },
+    additionalProperties: false,
+    $defs: {
+      meta: {
+        type: 'object',
+        required: ['title'],
+        properties: metaProperties(),
+        additionalProperties: str,
+      },
+      doc: {
+        type: 'object',
+        required: ['id', 'type', 'meta', 'children'],
+        properties: {
+          id: str,
+          type: { const: 'doc' },
+          meta: { $ref: '#/$defs/meta' },
+          children,
+        },
+        unevaluatedProperties: false,
+      },
+      /**
+       * `col`/`row`/`colSpan`/`rowSpan` sit on the *block* rather than inside
+       * the `grid` branch on purpose (issue 14 裁決 1): a bounded 文體's blocks
+       * may carry coordinates without being wrapped in anything, and declaring
+       * them per type would mean editing twelve modules to add one vocabulary.
+       * Because `unevaluatedProperties` (not `additionalProperties`) closes this
+       * object, a property declared here is legal on every branch and nowhere
+       * else — a placement is still refused on a block that is not a block.
+       */
+      block: {
+        type: 'object',
+        required: ['id', 'type'],
+        properties: { id: str, type: { enum: blockTypes() }, ...PLACEMENT_PROPERTIES },
+        allOf: blockModules().map((mod) => whenType(mod.type, mod.schema)),
+        unevaluatedProperties: false,
+      },
+    },
+  }
+}

package/src/core/spec-check.js

@@ -0,0 +1,33 @@
+import { blockModule } from '../blocks/index.js'
+import { validationError } from './errors.js'
+import { walkBlocks } from './blocks.js'
+
+/**
+ * Run every block's own spec check over a document, before a byte is drawn.
+ *
+ * Some blocks carry a claim the JSON Schema cannot express — a `diagram` edge
+ * must point at a node that exists, and no schema keyword says that. Those
+ * checks belong to the block, so a module declares `validate(block) → string[]`
+ * and this gate turns the first non-empty answer into the usual `KSB_` error
+ * with a block path.
+ *
+ * Being generic is the point: it used to be a diagram-shaped call in the render
+ * pipeline, which meant a plugin block had no way to refuse its own broken
+ * spec — it could only draw nonsense. A picture that silently disagrees with
+ * the data it came from is the one failure a reader cannot detect.
+ *
+ * The failure code and wording come from the module as plain data, because the
+ * block layer imports nothing: what it means for a diagram to be undrawable is
+ * the diagram's sentence to write, not this file's.
+ *
+ * @throws {import('./errors.js').KsbError} exit 1, with the module's own code
+ */
+export function assertBlockSpecs(doc) {
+  for (const { block, path } of walkBlocks(doc)) {
+    const mod = blockModule(block?.type)
+    if (typeof mod?.validate !== 'function') continue
+    const problems = mod.validate(block)
+    if (!Array.isArray(problems) || problems.length === 0) continue
+    throw validationError(mod.invalid.message(problems), mod.invalid.code, path)
+  }
+}

package/src/core/validate.js

@@ -0,0 +1,44 @@
+import Ajv2020Module from 'ajv/dist/2020.js'
+import { irSchema } from './schema.js'
+import { CODES } from './errors.js'
+
+const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module
+
+let validator = null
+
+const compile = () => {
+  if (validator === null) {
+    const ajv = new Ajv2020({ allErrors: true, strict: false })
+    validator = ajv.compile(irSchema())
+  }
+  return validator
+}
+
+/** `/doc/children/0/html` → `doc.children[0].html` (SPEC §10.3: 錯誤指到 block path). */
+export function pointerToBlockPath(pointer) {
+  if (typeof pointer !== 'string' || pointer.length === 0) return '$'
+  return pointer
+    .split('/')
+    .filter((part) => part.length > 0)
+    .reduce((acc, part) => {
+      const decoded = part.replace(/~1/g, '/').replace(/~0/g, '~')
+      if (/^\d+$/.test(decoded)) return `${acc}[${decoded}]`
+      return acc.length === 0 ? decoded : `${acc}.${decoded}`
+    }, '')
+}
+
+/**
+ * Validate an IR envelope against the schema.
+ * @returns {{valid: boolean, errors: Array<{path: string, code: string, message: string}>}}
+ */
+export function validateIr(ir) {
+  const validate = compile()
+  const valid = validate(ir)
+  if (valid) return { valid: true, errors: [] }
+  const errors = (validate.errors ?? []).map((e) => ({
+    path: pointerToBlockPath(e.instancePath),
+    code: CODES.IR_SCHEMA,
+    message: `${e.message}${e.params?.allowedValues ? ` (${e.params.allowedValues.join(', ')})` : ''}`,
+  }))
+  return { valid: false, errors }
+}

package/src/core/version.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const PKG_PATH = fileURLToPath(new URL('../../package.json', import.meta.url))
+
+let cached = null
+
+/** Engine (SDK) version, read once from the package manifest. */
+export function engineVersion() {
+  if (cached === null) {
+    const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'))
+    if (typeof pkg.version !== 'string' || pkg.version.length === 0) {
+      throw new Error('package.json is missing a version field')
+    }
+    cached = pkg.version
+  }
+  return cached
+}