@brandon_m_behring/book-scaffold-astro 4.26.2 → 4.27.0

package/recipes/19-prevalidate-hook.md

@@ -1,113 +1,59 @@
-# Recipe 19 — `prevalidate` npm hook (v4.6.0+)
+# Recipe 19 — generated data before validation (v4.27+)
 
-`book-scaffold validate` checks `<Cite key="...">` against `src/data/references.json` (academic profile) and `<XRef id="...">` against `src/data/labels.json`. Both JSON files are **derived artifacts** regenerated from `bibliography.bib` + chapter MDX by `book-scaffold build-bib` + `book-scaffold build-labels`. Both are gitignored.
+`book-scaffold validate` checks citations and cross-references against two derived, normally gitignored files:
 
-When `npm run validate` runs **standalone** (e.g., a reusable deploy workflow runs only the validate command, without the full `npm run build` chain), the prereq scripts don't fire and the validator chokes on apparently-missing keys.
+- `src/data/references.json`, emitted by `book-scaffold build-bib`
+- `src/data/labels.json`, emitted by `book-scaffold build-labels`
 
-The `prevalidate` npm lifecycle hook is the canonical fix: it auto-runs the prereqs whenever `npm run validate` is invoked, regardless of how validate is called.
-
----
-
-## TL;DR
-
-```json
-{
-  "scripts": {
-    "prevalidate": "npm run build:bib && npm run build:labels --if-present",
-    "validate": "book-scaffold validate"
-  }
-}
-```
-
-`npm run validate` → automatically runs `prevalidate` first (build:bib + build:labels) → then runs `validate`. CI and local behave identically; no separate `ci:validate` wrapper script needed.
-
----
-
-## Why the workaround was needed
-
-`brandon-behring/deploy-workflows@v1` (the reusable Cloudflare Workers deploy) runs `npm run <validate-command>` between `npm ci` and `npm run build`. Without the `prevalidate` hook OR an explicit wrapper script, the validate step ran against missing artifacts.
-
-The Phase 1c first-deploy of `ssm-foundations` (2026-05-26) hit this — validate emitted 25+ "Unknown bibkey" errors that pointed at chapter content instead of the missing `references.json` artifact. The deploy-time fix shipped as a `ci:validate` wrapper:
+Every profile can use theorem/Figure IDs and XRefs, so every generated book now carries the same npm lifecycle:
 
 ```json
 {
   "scripts": {
-    "ci:validate": "npm run build:bib && npm run build:labels --if-present && npm run validate"
+    "prevalidate": "npm run build:bib --if-present && npm run build:labels --if-present",
+    "validate": "book-scaffold validate",
+    "prebuild": "npm run validate --if-present"
   }
 }
 ```
 
-…with `validate-command: ci:validate` in `.github/workflows/deploy.yml`. This worked but introduced consumer-side ceremony for what is structurally a scaffold-level convention.
-
-The cleaner long-term fix is the `prevalidate` npm-lifecycle hook (this recipe). v4.6.0's `create-book` automatically scaffolds it for academic + research-portfolio profiles.
-
----
+`npm run validate` runs `prevalidate` automatically. `npm run build` runs `prebuild`, which delegates to that same path. Academic, tools, minimal, course-notes, and research-portfolio scaffolds use this identical contract.
 
-## Migration: from `ci:validate` to `prevalidate`
+## Direct CLI calls self-heal too
 
-Existing consumers (DML, ssm, dlai when it ships) that adopted the `ci:validate` wrapper during 2026-05-26 deploys can migrate when they bump to scaffold `^4.6.0`. Three-file mechanical change per consumer:
+An npm hook cannot protect `npx book-scaffold validate` or a direct bin invocation. Starting in v4.27, the validator itself regenerates each missing artifact before loading it:
 
-### 1. `package.json` — rename `ci:validate` → `prevalidate`
+1. Missing `labels.json` invokes `build-labels`.
+2. Missing `references.json` invokes `build-bib`, even when no default `bibliography.bib` exists; that valid no-bibliography case emits `{}`.
+3. Existing files are not rewritten.
+4. A child failure stops validation and preserves the original child diagnostic and non-zero status.
 
-```diff
- {
-   "scripts": {
--    "ci:validate": "npm run build:bib && npm run build:labels --if-present && npm run validate",
-+    "prevalidate": "npm run build:bib && npm run build:labels --if-present",
-     "validate": "book-scaffold validate"
-   }
- }
-```
+This makes fresh checkouts deterministic without hiding stale existing data. After changing theorem IDs, kinds, slugs, bibliography entries, or `numberStyle`, explicitly rerun the corresponding build command.
 
-Note the renamed script no longer needs to call `validate` itself — npm's lifecycle invokes it automatically after `prevalidate` completes.
+## Bibliography path precedence
 
-### 2. `.github/workflows/deploy.yml` — revert `validate-command`
+Books with a shared or non-root bibliography can set:
 
-```diff
- jobs:
-   deploy:
-     uses: brandon-behring/deploy-workflows/.github/workflows/deploy-astro-worker.yml@v2
-     secrets: inherit
-     with:
-       working-directory: web
--      validate-command: ci:validate
-+      validate-command: validate
-       enable-pr-previews: true
+```dotenv
+BOOK_BIB_PATH=../shared/references.bib
 ```
 
-The reusable workflow's `validate-command` now points at the native `validate` script; the `prevalidate` hook handles its own prereqs transparently.
+`build-bib` resolves the process environment first, then the project-root `.env`, then `./bibliography.bib`. Relative paths are resolved from the book root. This same precedence applies when validation invokes `build-bib` during self-healing.
 
-### 3. Simplify `prebuild` (optional)
+## Migrating older consumers
 
-If the consumer's `prebuild` still has the long chain:
+Replace custom `ci:validate` wrappers and profile-conditional hooks with the uniform scripts above. A reusable deploy workflow can call the normal `validate` script; no wrapper needs to repeat the artifact chain.
 
 ```diff
  {
    "scripts": {
--    "prebuild": "npm run build:bib --if-present && npm run build:labels --if-present && npm run validate --if-present",
-+    "prebuild": "npm run validate --if-present",
-     "build": "astro build && pagefind --site dist"
+-    "ci:validate": "npm run build:bib && npm run build:labels && npm run validate",
++    "prevalidate": "npm run build:bib --if-present && npm run build:labels --if-present",
+     "validate": "book-scaffold validate",
+-    "prebuild": "npm run build:bib && npm run build:labels && npm run validate"
++    "prebuild": "npm run validate --if-present"
    }
  }
 ```
 
-Now `npm run build` → triggers `prebuild` (which runs `validate`) → triggers `prevalidate` (which runs the prereqs) → validate runs cleanly. Single source of truth for the prereq chain.
-
----
-
-## When `prevalidate` is NOT needed
-
-Profiles that don't run cite-key or XRef validation don't need `prevalidate`. Specifically:
-
-- `tools`, `minimal`: no `<Cite>` resolution against `references.json`.
-- `course-notes`: depends on whether the consumer uses `<Cite>` (some do for source-tier attribution).
-
-For these profiles, `book-scaffold validate` operates on chapter structure + XRef IDs only; `prevalidate` would be a no-op. The v4.6.0 create-book template adds `prevalidate` ONLY for academic + research-portfolio.
-
----
-
-## Why this matters
-
-Recipe 19 is part of [issue #76](https://github.com/brandon-behring/book-scaffold-astro/issues/76)'s v4.6 bundle. Companion: [recipe 18 — chapter-route ownership](./18-chapter-route-ownership.md), which fixes another silent-CI surface from the same Phase 1c first-deploys.
-
-The `prevalidate` convention also closes [issue #77](https://github.com/brandon-behring/book-scaffold-astro/issues/77) — the v4.6 validator now emits a single re-framed error pointing at this recipe when `references.json` is missing, replacing the noisy 25-symptom output.
+The historical profile split is intentionally gone: non-academic profiles still need labels, and an empty bibliography build is a supported no-op that creates the importable empty artifact.

package/scripts/build-bib.mjs

@@ -39,6 +39,7 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readEnvFile } from './read-env.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-bib
@@ -49,7 +50,8 @@ AND sources/manifest.yaml -> src/data/sources.json (tools-profile sources for
 the /references page). Either input may be absent.
 
 Env:
-  BOOK_BIB_PATH      Override path to .bib file (default: ./bibliography.bib).
+  BOOK_BIB_PATH      Override path to .bib file (process env wins, then root
+                     .env; default: ./bibliography.bib).
 
 Options:
   --help, -h         Print this message and exit (non-mutating).
@@ -64,11 +66,13 @@ import '@citation-js/plugin-bibtex';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = process.cwd();
+const dotenv = readEnvFile(PROJECT_ROOT);
 
 // Default: bibliography.bib at scaffold root.
 // Override via BOOK_BIB_PATH=path/to/your.bib (absolute or relative to cwd).
-const BIB_PATH = process.env.BOOK_BIB_PATH
-  ? resolve(process.cwd(), process.env.BOOK_BIB_PATH)
+const configuredBibPath = process.env.BOOK_BIB_PATH ?? dotenv.BOOK_BIB_PATH;
+const BIB_PATH = configuredBibPath
+  ? resolve(PROJECT_ROOT, configuredBibPath)
   : resolve(PROJECT_ROOT, 'bibliography.bib');
 const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
 const SOURCES_PATH = resolve(PROJECT_ROOT, 'sources/manifest.yaml');

package/scripts/build-labels.mjs

@@ -12,14 +12,15 @@
  *
  * Kind-aware (#126): a `<Theorem kind="proposition">` resolves its display
  * WORD through the shared theorem-label vocabulary (`Proposition 8.1`), not a
- * kind-blind `Theorem 8.1`. The theorem family shares one counter (keyed by
- * the JSX component, as amsthm shares its counter), so numbers are unchanged.
+ * kind-blind `Theorem 8.1`. v4.27.0 (#175) lets defineBookConfig / defineStyle
+ * select shared (the historical default) or independent per-kind counters.
  *
  * The resulting map is consumed by XRef.astro via
  * `import.meta.glob('/src/data/labels.json', { eager: true })`.
  *
- * Per-chapter, per-type counter: each chapter resets the counter, so two
- * chapters can both have `Theorem 1` without colliding. The chapter
+ * Per-chapter counters: each chapter resets the sequence, so two chapters can
+ * both have `Theorem 1` without colliding. Labelable component families always
+ * have independent counters; theorem kinds share or split per numberStyle. The chapter
  * number comes from frontmatter:
  *   - tools profile: `chapter` field (number).
  *   - academic profile: `week` field (number).
@@ -46,6 +47,7 @@
 import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
 import { resolve, relative, join, basename, dirname } from 'node:path';
 import { readChaptersBase } from './walk-mdx.mjs';
+import { loadResolvedBookConfig } from './resolve-book-config.mjs';
 // #126: reuse the ONE kind vocabulary (theorem-label.ts → its own lean tsup
 // entry) so a <Theorem kind="proposition"> xref reads "Proposition N.M", not a
 // kind-blind "Theorem N.M" — and so an unknown/absent kind FAILS HERE (same
@@ -66,6 +68,9 @@ Env:
 
 Options:
   --help, -h          Print this message and exit (non-mutating).
+
+Numbering is read from defineBookConfig / defineStyle numberStyle. It defaults
+to shared when no scaffold integration can be resolved.
 `;
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
@@ -182,6 +187,7 @@ async function walkChapters(dir) {
 
 async function main() {
   const cwd = process.cwd();
+  const { numberStyle } = await loadResolvedBookConfig(cwd);
   const chaptersDir = resolve(cwd, CHAPTERS_DIR);
   const files = await walkChapters(chaptersDir);
 
@@ -207,10 +213,6 @@ async function main() {
       const id = extractAttr(attrs, 'id');
       if (!id) continue;
 
-      // One shared counter per component (keyed by the JSX name, NOT the
-      // amsthm kind) — so theorem/proposition/lemma share a sequence exactly
-      // as they do under amsthm, and existing numbers never shift (#126).
-      counters[componentName] = (counters[componentName] ?? 0) + 1;
       foundInChapter += 1;
       totalIds += 1;
 
@@ -224,13 +226,16 @@ async function main() {
       // "no kind=" rather than the misleading kind="null".
       const labelOverride = extractAttr(attrs, 'label');
       let word;
+      let theoremKind;
       if (labelOverride == null) {
         if (componentName === 'Theorem') {
           try {
-            word = theoremLabel({
+            const resolvedLabel = theoremLabel({
               kind: extractAttr(attrs, 'kind') ?? undefined,
               type: extractAttr(attrs, 'type') ?? undefined,
-            }).fullLabel;
+            });
+            word = resolvedLabel.fullLabel;
+            theoremKind = resolvedLabel.kind;
           } catch (err) {
             throw new Error(
               `<Theorem id="${id}"> in ${relative(cwd, file)}: ${err.message}`,
@@ -241,13 +246,25 @@ async function main() {
         }
       }
 
+      // label= is a custom, unnumbered display and therefore does not consume
+      // either the historical shared sequence or a per-kind sequence. This
+      // keeps later auto-numbered entries stable when prose-only labels move.
+      const counterKey =
+        numberStyle === 'per-kind' && componentName === 'Theorem'
+          ? `Theorem/${theoremKind}`
+          : componentName;
+      if (labelOverride == null) {
+        counters[counterKey] = (counters[counterKey] ?? 0) + 1;
+      }
+
       // The bare counter string the heading reuses: Theorem.astro reads
       // `number` by id and renders it, so heading == xref by construction.
       // A `label=` override opts out of auto-numbering → number is null.
-      const number =
-        chapterNum != null
-          ? `${chapterNum}.${counters[componentName]}`
-          : String(counters[componentName]);
+      const number = labelOverride != null
+        ? null
+        : chapterNum != null
+          ? `${chapterNum}.${counters[counterKey]}`
+          : String(counters[counterKey]);
       const display = labelOverride ?? `${word} ${number}`;
 
       if (labels[id]) {
@@ -263,7 +280,7 @@ async function main() {
         // labels.json serves any deploy base (root or path-proxied series).
         href: `chapters/${slug}#${id}`,
         display,
-        number: labelOverride ? null : number,
+        number,
       };
     }
 
@@ -281,7 +298,7 @@ async function main() {
   process.stdout.write(
     `build-labels: ${totalIds} id${totalIds === 1 ? '' : 's'} across ` +
       `${chaptersWithIds} chapter${chaptersWithIds === 1 ? '' : 's'} → ` +
-      `${OUTPUT_PATH}\n`,
+      `${OUTPUT_PATH} (number-style=${numberStyle})\n`,
   );
 }
 

package/scripts/read-env.mjs

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/** Read a small dotenv-style file without mutating process.env. */
+export function readEnvFile(projectRoot = process.cwd()) {
+  try {
+    const out = {};
+    const source = readFileSync(resolve(projectRoot, '.env'), 'utf8');
+    for (const line of source.split(/\r?\n/)) {
+      const match = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (!match) continue;
+      let value = match[2] ?? '';
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      out[match[1]] = value;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}

package/scripts/resolve-book-config.mjs

@@ -0,0 +1,96 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfigFromFile } from 'vite';
+
+export const DEFAULT_TOOLING_CONFIG = Object.freeze({
+  preset: null,
+  numberStyle: 'shared',
+  integrationFound: false,
+});
+
+const ASTRO_CONFIG_NAMES = [
+  'astro.config.mjs',
+  'astro.config.ts',
+  'astro.config.js',
+  'astro.config.cjs',
+];
+const PRESETS = ['academic', 'tools', 'minimal', 'course-notes', 'research-portfolio'];
+
+function findAstroConfig(projectRoot) {
+  for (const name of ASTRO_CONFIG_NAMES) {
+    const path = resolve(projectRoot, name);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+function assertNumberStyle(value, configPath) {
+  if (value !== 'shared' && value !== 'per-kind') {
+    throw new Error(
+      `book-scaffold tooling: ${configPath} resolved invalid numberStyle ` +
+        `${JSON.stringify(value)}; expected shared | per-kind.`,
+    );
+  }
+}
+
+function assertPreset(value, configPath) {
+  if (value != null && !PRESETS.includes(value)) {
+    throw new Error(
+      `book-scaffold tooling: ${configPath} resolved invalid preset ` +
+        `${JSON.stringify(value)}; expected ${PRESETS.join(' | ')}.`,
+    );
+  }
+}
+
+/**
+ * Evaluate the consumer's actual Astro config and read the scaffold
+ * integration's internal resolved metadata. Absence of a config/integration is
+ * a supported legacy shape and preserves shared numbering. Evaluation errors
+ * are deliberately not swallowed: tooling must not silently use wrong config.
+ */
+export async function loadResolvedBookConfig(projectRoot = process.cwd()) {
+  const configPath = findAstroConfig(projectRoot);
+  if (!configPath) return { ...DEFAULT_TOOLING_CONFIG };
+
+  let loaded;
+  try {
+    loaded = await loadConfigFromFile(
+      { command: 'build', mode: 'production', isSsrBuild: true, isPreview: false },
+      configPath,
+      projectRoot,
+      'silent',
+    );
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`book-scaffold tooling: failed to evaluate ${configPath}: ${detail}`, {
+      cause: error,
+    });
+  }
+
+  if (!loaded) {
+    throw new Error(`book-scaffold tooling: Vite did not return config for ${configPath}.`);
+  }
+
+  const integrations = Array.isArray(loaded.config?.integrations)
+    ? loaded.config.integrations.flat(Infinity)
+    : [];
+  const integration = integrations.find((candidate) => candidate?.name === 'book-scaffold-astro');
+  if (!integration) return { ...DEFAULT_TOOLING_CONFIG };
+
+  const metadata = integration.__bookScaffoldResolvedConfig;
+  if (!metadata) {
+    // A config can contain an older scaffold integration with no metadata.
+    // Preserve the historical numbering default rather than treating upgrade
+    // sequencing as a config error.
+    return { ...DEFAULT_TOOLING_CONFIG, integrationFound: true };
+  }
+
+  const numberStyle = metadata.numberStyle ?? 'shared';
+  assertNumberStyle(numberStyle, configPath);
+  assertPreset(metadata.preset, configPath);
+  return {
+    preset: metadata.preset ?? null,
+    numberStyle,
+    integrationFound: true,
+  };
+}