@brandon_m_behring/book-scaffold-astro 4.9.0 → 4.10.0

package/bin/book-scaffold.mjs

@@ -27,7 +27,7 @@ const HELP = `Usage: book-scaffold <sub-command> [args...]
 Sub-commands:
   validate           Pre-flight content validator (XRef ids, Cite keys, Figure srcs).
   build-labels       Emit src/data/labels.json for cross-references (Phase C).
-  build-bib          BibTeX -> CSL JSON for the <Cite> component.
+  build-bib          BibTeX -> references.json (+ sources/manifest.yaml -> sources.json).
   build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback (+ TikZ in v4.2.0).
   build-tips         Scan chapters for <Tip> instances; emit src/data/tips.json (v4.3.0).
   build-exercises    Scan chapters for <Exercise> instances; emit src/data/exercises.json (v4.4.0).

package/components/SourceArchive.astro

@@ -3,14 +3,14 @@
  * SourceArchive — renders every entry in sources/manifest.yaml grouped
  * by tier in descending authority (T1 → T4).
  *
- * Used from Appendix D (`d-source-archive-index.mdx`) to replace the
- * static hand-maintained listing with an auto-generated view that
- * always reflects the manifest.
+ * Used by the auto-injected /references page (v4.10.0, #85) and by
+ * author-placed source-archive appendices, replacing a static hand-
+ * maintained listing with an auto-generated view that always reflects
+ * the manifest.
  *
  * Empty-tier behavior: renders an honest placeholder ("No sources at
- * this tier yet.") rather than hiding the section. This matches the
- * pedagogy of Appendix D — the archive is intentionally sparse in the
- * early book, and the gap is visible by design.
+ * this tier yet.") rather than hiding the section, so the tier taxonomy
+ * stays visible even before a tier has entries.
  */
 import { sourceTiers } from '@brandon_m_behring/book-scaffold-astro';
 import {
@@ -53,7 +53,7 @@ function year(d: Date | undefined): string | null {
 
         {empty ? (
           <p class="source-archive-empty">
-            No sources at this tier yet. Appendix D is intentionally sparse in the early book; this slot fills as chapters leave draft.
+            No sources at this tier yet.
           </p>
         ) : (
           <ol

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -142,15 +142,21 @@
     "test": "node --test tests/*.test.mjs"
   },
   "peerDependencies": {
-    "astro": "^6.1.7",
     "@astrojs/mdx": "^5.0.3",
     "@astrojs/preact": "^5.1.1",
+    "astro": "^6.1.7",
     "preact": "^10.29.1"
   },
   "peerDependenciesMeta": {
-    "katex": { "optional": true },
-    "rehype-katex": { "optional": true },
-    "remark-math": { "optional": true }
+    "katex": {
+      "optional": true
+    },
+    "rehype-katex": {
+      "optional": true
+    },
+    "remark-math": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.6.1",
@@ -158,7 +164,8 @@
     "@citation-js/plugin-bibtex": "^0.7.21",
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
-    "pagefind": "^1.5.2"
+    "pagefind": "^1.5.2",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/pages/references.astro

@@ -1,16 +1,22 @@
 ---
 /**
- * /references — the book's bibliography page.
+ * /references — the book's bibliography + cited-sources page.
  *
- * Renders every entry in src/data/references.json (produced by
- * scripts/build-bib.mjs from guides/shared/references.bib). Each
- * entry gets an anchor ID matching its bibkey, so `<Cite key="gu2024mamba" />`
- * elsewhere on the site links to /references#gu2024mamba.
+ * Auto-injected on every profile (integration route table). Reads two
+ * independent inputs, each via a defensive `import.meta.glob` (missing file →
+ * empty, never a crash — same pattern <XRef> uses for labels.json):
  *
- * Sorted alphabetically by first-author surname, then by year.
- * arXiv-style notes are surfaced as direct links when present.
+ *   - src/data/references.json — BibTeX entries (academic), from build-bib.
+ *     Each entry's anchor matches its bibkey, so `<Cite key="…" />` links to
+ *     /references#<bibkey>.
+ *   - src/data/sources.json — sources/manifest.yaml entries (tools profile),
+ *     also from build-bib (v4.10.0, #85). Its presence is a profile-safe GATE
+ *     for the <SourceArchive> render: a falsy `&&` never instantiates the
+ *     component, so academic/minimal books (which have no `sources` content
+ *     collection) never call getCollection('sources').
  */
 import Base from '../layouts/Base.astro';
+import SourceArchive from '../components/SourceArchive.astro';
 
 type CslAuthor = { family?: string; given?: string; literal?: string };
 type CslEntry = {
@@ -29,8 +35,7 @@ type CslEntry = {
   note?: string;
 };
 
-// Resolve references.json from consumer's project root. Missing file -> empty
-// list (page renders an "empty bibliography" notice rather than crashing).
+// --- Bibliography: BibTeX → references.json (academic profile). ---
 const refsModules = import.meta.glob<{ default: Record<string, CslEntry> }>(
   '/src/data/references.json',
   { eager: true },
@@ -39,6 +44,18 @@ const refsModule = refsModules['/src/data/references.json'];
 const map = (refsModule?.default ?? {}) as Record<string, CslEntry>;
 const entries = Object.values(map);
 
+// --- Cited sources: sources/manifest.yaml → sources.json (tools profile).
+// Presence-only gate; the actual render reads the live `sources` collection
+// via <SourceArchive>, which only runs when this gate is true (so it is never
+// reached on profiles without a `sources` collection). ---
+const srcModules = import.meta.glob<{ default: unknown[] }>(
+  '/src/data/sources.json',
+  { eager: true },
+);
+const sourcesData = (srcModules['/src/data/sources.json']?.default ?? []) as unknown[];
+const hasSources = Array.isArray(sourcesData) && sourcesData.length > 0;
+const hasBib = entries.length > 0;
+
 const surname = (a: CslAuthor): string =>
   (a.family ?? a.literal ?? '').toLowerCase();
 
@@ -73,61 +90,95 @@ function arxivUrl(note?: string): string | null {
   const m = note.match(/arXiv:\s*(\S+)/i);
   return m ? `https://arxiv.org/abs/${m[1]}` : null;
 }
+
+const lede =
+  hasBib && hasSources
+    ? 'Every work cited in this book — the bibliography below, then the external sources grouped by tier.'
+    : hasBib
+      ? 'Every paper, book, and software citation in this book, sorted alphabetically by first-author surname. Click an entry’s anchor to share a deep link, or follow the arXiv / DOI / URL for the source.'
+      : hasSources
+        ? 'Every external source cited in this book, grouped by tier in descending authority.'
+        : 'This book has no references yet.';
 ---
-<Base
-  title="References — Post-Transformers"
-  description="Bibliography for the post_transformers guide, generated from guides/shared/references.bib."
->
+<Base title="References" description="Bibliography and cited sources for this book.">
   <article class="prose">
     <header>
       <h1>References</h1>
-      <p class="lede">
-        Every paper, book, and software citation in this guide, sorted
-        alphabetically by first-author surname. Click an entry's
-        anchor to share a deep link, or follow the arXiv / DOI / URL
-        for the source.
-      </p>
-      <p>
-        <small>
-          {entries.length} entries. Generated from
-          <code>guides/shared/references.bib</code> at build time via
-          <code>scripts/build-bib.mjs</code>.
-        </small>
-      </p>
+      <p class="lede">{lede}</p>
     </header>
 
-    <ol class="references-list">
-      {entries.map((e) => {
-        const y = year(e);
-        const arxiv = arxivUrl(e.note);
-        const primaryUrl = arxiv ?? e.URL ?? (e.DOI ? `https://doi.org/${e.DOI}` : null);
-        return (
-          <li id={e.id} class="reference-entry">
-            <span class="reference-key" aria-label="bibkey">[{e.id}]</span>
-            <span class="reference-text">
-              {formatAuthors(e.author)}
-              {y > 0 && <> ({y})</>}.
-              {' '}
-              <em>{e.title}</em>.
-              {e['container-title'] && <> {e['container-title']}.</>}
-              {e.publisher && !e['container-title'] && <> {e.publisher}.</>}
-              {e.volume && <> Vol. {e.volume}{e.issue && <>, no. {e.issue}</>}.</>}
-              {e.page && <> pp. {e.page}.</>}
-              {primaryUrl && (
-                <>
+    {!hasBib && !hasSources && (
+      <p class="references-empty">
+        No references yet. Add a <code>bibliography.bib</code> (academic) or
+        populate <code>sources/manifest.yaml</code> (tools), then run
+        <code>npm run build:bib</code>.
+      </p>
+    )}
+
+    {hasBib && (
+      <section class="references-bibliography">
+        {hasSources && <h2>Bibliography</h2>}
+        <ol class="references-list">
+          {entries.map((e) => {
+            const y = year(e);
+            const arxiv = arxivUrl(e.note);
+            const primaryUrl = arxiv ?? e.URL ?? (e.DOI ? `https://doi.org/${e.DOI}` : null);
+            return (
+              <li id={e.id} class="reference-entry">
+                <span class="reference-key" aria-label="bibkey">[{e.id}]</span>
+                <span class="reference-text">
+                  {formatAuthors(e.author)}
+                  {y > 0 && <> ({y})</>}.
                   {' '}
-                  <a href={primaryUrl} rel="external noopener">link</a>.
-                </>
-              )}
-            </span>
-          </li>
-        );
-      })}
-    </ol>
+                  <em>{e.title}</em>.
+                  {e['container-title'] && <> {e['container-title']}.</>}
+                  {e.publisher && !e['container-title'] && <> {e.publisher}.</>}
+                  {e.volume && <> Vol. {e.volume}{e.issue && <>, no. {e.issue}</>}.</>}
+                  {e.page && <> pp. {e.page}.</>}
+                  {primaryUrl && (
+                    <>
+                      {' '}
+                      <a href={primaryUrl} rel="external noopener">link</a>.
+                    </>
+                  )}
+                </span>
+              </li>
+            );
+          })}
+        </ol>
+      </section>
+    )}
+
+    {hasSources && (
+      <section class="references-sources">
+        <h2>Cited sources</h2>
+        <p class="references-sources-lede">
+          External sources cited inline via <code>&lt;Citation&gt;</code>, grouped
+          by tier in descending authority.
+        </p>
+        <SourceArchive />
+      </section>
+    )}
   </article>
 </Base>
 
 <style>
+  .references-empty {
+    color: var(--color-text-muted);
+    font-style: italic;
+    padding: var(--space-3);
+    background: var(--color-bg-subtle);
+    border-radius: var(--radius-sm);
+    text-indent: 0;
+  }
+  .references-sources {
+    margin-top: var(--space-6);
+  }
+  .references-sources-lede {
+    color: var(--color-text-muted);
+    font-size: var(--text-sm);
+    text-indent: 0;
+  }
   .references-list {
     list-style: none;
     padding: 0;

package/scripts/build-bib.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/build-bib.mjs — Bibliography pipeline (academic profile).
+ * scripts/build-bib.mjs — Bibliography + source-manifest pipeline.
  *
  * Reads bibliography.bib at scaffold root (BibTeX), parses via @citation-js,
  * emits src/data/references.json keyed by bibkey. The .bib path is
@@ -8,6 +8,12 @@
  * elsewhere (e.g. a shared `guides/shared/references.bib` outside the
  * Astro project — the post_transformers pattern).
  *
+ * v4.10.0 (#85): ALSO reads sources/manifest.yaml (tools-profile sources,
+ * cited inline via <Citation src>) and emits src/data/sources.json so the
+ * auto-injected /references page can surface them. The two steps are
+ * independent — a tools book with a manifest and no .bib still gets a
+ * populated /references.
+ *
  * Run on `prebuild` so every Astro build sees fresh bibliography data.
  * Idempotent: re-running with no .bib change produces a byte-identical
  * output (modulo timestamp, which we omit).
@@ -37,8 +43,10 @@ import { fileURLToPath } from 'node:url';
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-bib
 
-Bibliography pipeline (academic profile). Reads bibliography.bib (or
-BOOK_BIB_PATH if set), parses via @citation-js, emits src/data/references.json.
+Bibliography + source-manifest pipeline. Reads bibliography.bib (or
+BOOK_BIB_PATH if set) -> src/data/references.json (BibTeX via @citation-js),
+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).
@@ -63,8 +71,10 @@ const BIB_PATH = process.env.BOOK_BIB_PATH
   ? resolve(process.cwd(), process.env.BOOK_BIB_PATH)
   : resolve(PROJECT_ROOT, 'bibliography.bib');
 const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
+const SOURCES_PATH = resolve(PROJECT_ROOT, 'sources/manifest.yaml');
+const SOURCES_OUT = resolve(PROJECT_ROOT, 'src/data/sources.json');
 
-async function main() {
+async function buildReferences() {
   // Graceful skip when the .bib file is absent (minimal/tools profile, or
   // an academic book that hasn't authored citations yet). Emits an empty
   // references.json so consumers can still `import refs from '...'`.
@@ -125,6 +135,45 @@ async function main() {
   );
 }
 
+// v4.10.0 (closes #85): tools-profile books keep their sources in
+// sources/manifest.yaml (cited inline via <Citation src="id" />); the BibTeX
+// path above never sees them, so the auto-injected /references page rendered
+// blank. Emit those sources to src/data/sources.json so references.astro can
+// surface them via the same defensive import.meta.glob it uses for
+// references.json. Absent manifest -> no file written (academic/minimal books
+// degrade to empty, exactly like a missing .bib). YAML is lazy-imported so the
+// --help / no-manifest paths stay dependency-free.
+async function buildSources() {
+  let yamlText;
+  try {
+    yamlText = await readFile(SOURCES_PATH, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return; // no manifest — nothing to emit
+    throw err;
+  }
+
+  const { parse } = await import('yaml');
+  const parsed = parse(yamlText);
+  // The manifest is a YAML array of source objects. Keep only well-formed
+  // entries (a string `id` is the citation key + the /references anchor target).
+  // A blank or comments-only manifest parses to null/undefined/[].
+  const sources = Array.isArray(parsed)
+    ? parsed.filter((s) => s && typeof s.id === 'string')
+    : [];
+
+  await mkdir(dirname(SOURCES_OUT), { recursive: true });
+  await writeFile(SOURCES_OUT, JSON.stringify(sources, null, 2) + '\n', 'utf8');
+  console.log(
+    `build-bib: ${sources.length} source${sources.length === 1 ? '' : 's'} -> ` +
+      `${SOURCES_OUT.replace(PROJECT_ROOT + '/', '')}`,
+  );
+}
+
+async function main() {
+  await buildReferences();
+  await buildSources();
+}
+
 main().catch((err) => {
   console.error(`build-bib: failed`);
   console.error(err);