@brandon_m_behring/book-scaffold-astro 3.5.1 → 3.5.3

package/dist/index.d.ts

@@ -79,4 +79,28 @@ declare function getFreshness(lastVerified: Date | undefined, volatility: Volati
  * affordance without a separate branch. */
 declare function freshnessLabel(f: Freshness | null): string;
 
-export { BookConfigOptions, BookScaffoldIntegrationOptions, type Freshness, type FreshnessStatus, type VolatilityLevel, bookScaffoldIntegration, defineBookConfig, defineMdxComponents, freshnessLabel, getFreshness, volatilityLevels };
+/**
+ * src/lib/chapter-sort.ts — pure sort-key helper for chapter frontmatter.
+ *
+ * Lives in its own file (no `astro:content` imports) so tsup can include it
+ * in the toolkit's DTS bundle without trying to resolve Astro's virtual
+ * modules at build time. The Astro-context wrappers (sortKey, getAllChapters,
+ * getNeighbors) live in src/lib/chapters.ts and import from here.
+ */
+/**
+ * Pure-function sort key from a chapter frontmatter object. Spans both
+ * tools and academic schemas:
+ *
+ *  - Tools: numeric `part` (0-10), numeric `chapter` (0-99). Encodes as
+ *    `part * 1000 + chapter` so chapters within a part stay grouped.
+ *  - Academic: string-enum `part` (foundations|ssm-core|...), numeric `week`
+ *    (1-99), no `chapter`. Maps `part` to a fixed ordinal then encodes as
+ *    `partOrdinal * 1000 + week`.
+ *
+ * v3.5.2 (closes #24): previously the tools-only formula crashed on
+ * academic chapters (string `part`, no `chapter`) by producing NaN sort
+ * keys.
+ */
+declare function chapterSortKey(data: Record<string, unknown>): number;
+
+export { BookConfigOptions, BookScaffoldIntegrationOptions, type Freshness, type FreshnessStatus, type VolatilityLevel, bookScaffoldIntegration, chapterSortKey, defineBookConfig, defineMdxComponents, freshnessLabel, getFreshness, volatilityLevels };

package/dist/index.mjs

@@ -697,6 +697,22 @@ function freshnessLabel(f) {
       return `Stale (${f.daysOld}d old; ${Math.abs(f.daysUntil)}d past threshold)`;
   }
 }
+
+// src/lib/chapter-sort.ts
+var ACADEMIC_PART_ORDINAL = {
+  foundations: 1,
+  "ssm-core": 2,
+  "beyond-ssm": 3,
+  integration: 4,
+  synthesis: 5
+};
+var UNKNOWN_PART_ORDINAL = 99;
+function chapterSortKey(data) {
+  const partRaw = data.part;
+  const partOrdinal = typeof partRaw === "number" ? partRaw : typeof partRaw === "string" ? ACADEMIC_PART_ORDINAL[partRaw] ?? UNKNOWN_PART_ORDINAL : UNKNOWN_PART_ORDINAL;
+  const within = typeof data.chapter === "number" ? data.chapter : typeof data.week === "number" ? data.week : 0;
+  return partOrdinal * 1e3 + within;
+}
 export {
   BOOK_PRESETS,
   BOOK_PROFILES,
@@ -706,6 +722,7 @@ export {
   bookScaffoldIntegration,
   changeKinds,
   changelogSchema,
+  chapterSortKey,
   chapterStatus,
   courseNotesChapterSchema,
   defineBookConfig,

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": "3.5.1",
+  "version": "3.5.3",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/pages/chapters.astro

@@ -2,10 +2,17 @@
 /**
  * /chapters — book index page.
  *
- * Groups non-draft chapters by Part in ascending part+chapter order.
- * Each card exposes `data-tools="<slug> <slug>..."` so future tool-filter
- * plumbing (Stage 3.2 commit 3) can hide cards via a single attribute
- * selector without touching the card rendering.
+ * Groups non-draft chapters by Part in ascending order. Each card exposes
+ * `data-tools="<slug> <slug>..."` so the ToolFilter island can hide cards via
+ * a single attribute selector without touching card rendering.
+ *
+ * v3.5.2 (closes #24): schema-aware. Previously hardcoded the tools-profile
+ * shape and crashed on academic profile (no `chapter` / `volatility` /
+ * `tools_compared` / `last_verified`). Now renders either shape:
+ *   - tools: `Chapter N` + volatility badge + freshness + tools-compared tags
+ *   - academic: `Week N` + status badge (no freshness or tools-compared)
+ * Field presence is the schema discriminator (cheaper than reading
+ * BOOK_PROFILE at the route layer).
  */
 import Base from '../layouts/Base.astro';
 import { getAllChapters, type Chapter } from '../src/lib/chapters';
@@ -13,94 +20,133 @@ import { getFreshness, freshnessLabel } from '../src/lib/freshness';
 
 const chapters = await getAllChapters();
 
-// Stable insertion-order grouping: iterate sorted chapters once.
-const byPart = new Map<number, Chapter[]>();
+// Stable insertion-order grouping by `part`. Map key may be number (tools) or
+// string (academic enum); Map preserves insertion order for both.
+type PartKey = string | number;
+const byPart = new Map<PartKey, Chapter[]>();
 for (const c of chapters) {
-  const list = byPart.get(c.data.part);
+  const key = (c.data as { part: PartKey }).part;
+  const list = byPart.get(key);
   if (list) list.push(c);
-  else byPart.set(c.data.part, [c]);
+  else byPart.set(key, [c]);
 }
 
 function formatDate(d: Date): string {
   return d.toISOString().slice(0, 10);
 }
 
-function partLabel(part: number, appendix: boolean): string {
-  return appendix ? 'Appendices' : `Part ${part}`;
+/** Render-ready label for a Part heading. Tools: "Part N" or "Appendices"
+ *  (parts >= 6 are appendices). Academic: titlecase the enum string. */
+function partLabel(part: PartKey): string {
+  if (typeof part === 'number') {
+    return part >= 6 ? 'Appendices' : `Part ${part}`;
+  }
+  return part
+    .split('-')
+    .map((w) => (w.length ? w[0].toUpperCase() + w.slice(1) : ''))
+    .join(' ');
+}
+
+function isAppendix(part: PartKey): boolean {
+  return typeof part === 'number' && part >= 6;
+}
+
+/** Per-card schema detection. Cheaper than reading BOOK_PROFILE — the shape
+ *  of the chapter's data already tells us which profile produced it. */
+function isToolsShape(data: Record<string, unknown>): boolean {
+  return 'volatility' in data && 'chapter' in data;
 }
 ---
 <Base
-  title="Chapters — Agentic Coding"
-  description="All chapters grouped by Part, with volatility, freshness, and tools-compared metadata at a glance."
+  title="Chapters"
+  description="All chapters grouped by Part."
 >
   <article class="prose chapters-index">
     <header class="chapters-index-header">
       <h1>Chapters</h1>
       <p class="chapters-index-lede">
-        Every chapter, grouped by Part. Each card shows its volatility
-        class, freshness status, and the tools it compares. Use a chapter
-        card's metadata to calibrate how much trust to place in its
-        specific claims — stable principles age slowly; feature surfaces
-        age fast.
-      </p>
-      <p class="chapters-index-cross-ref">
-        See also: <a href="/convergence/">convergence dashboard</a> —
-        which patterns have landed in which tools, when.
+        Every chapter, grouped by Part. Use the card metadata to calibrate
+        how much trust to place in a chapter's specific claims.
       </p>
     </header>
 
     <p class="chapters-filter-hint" id="filter-hint" aria-live="polite"></p>
 
     {Array.from(byPart.entries()).map(([part, list]) => {
-      const appendix = part >= 6;
+      const appendix = isAppendix(part);
       return (
         <section class="part-group">
           <h2 class="part-heading">
-            <span class="part-label">{partLabel(part, appendix)}</span>
+            <span class="part-label">{partLabel(part)}</span>
           </h2>
           <ol class="chapter-list">
             {list.map((c) => {
-              const freshness = getFreshness(c.data.last_verified, c.data.volatility);
-              const freshnessText =
-                freshness.status === 'fresh'
+              const data = c.data as Record<string, unknown>;
+              const tools = isToolsShape(data);
+              // data-tools attribute drives the ToolFilter island. Academic
+              // cards opt out by claiming "cross-tool" — always visible
+              // regardless of filter state.
+              const toolsAttr = tools
+                ? (data.tools_compared as string[]).join(' ')
+                : 'cross-tool';
+              const freshness = tools
+                ? getFreshness(data.last_verified as Date, data.volatility as Parameters<typeof getFreshness>[1])
+                : null;
+              const freshnessText = freshness
+                ? freshness.status === 'fresh'
                   ? 'Fresh'
                   : freshness.status === 'verify-soon'
                     ? 'Verify soon'
-                    : 'Stale';
-              const toolsAttr = c.data.tools_compared.join(' ');
+                    : 'Stale'
+                : null;
               return (
-                <li
-                  class="chapter-card"
-                  data-tools={toolsAttr}
-                >
+                <li class="chapter-card" data-tools={toolsAttr}>
                   <a href={`/${c.id}/`} class="chapter-card-link">
                     <div class="chapter-card-meta">
                       <span class="chapter-card-number">
-                        {appendix ? `Appendix ${String.fromCharCode(64 + c.data.chapter).toLowerCase()}` : `Chapter ${c.data.chapter}`}
-                      </span>
-                      <span
-                        class={`volatility-badge volatility-${c.data.volatility}`}
-                        title={`Volatility: ${c.data.volatility}`}
-                      >{c.data.volatility}</span>
-                      <span
-                        class="freshness-badge"
-                        data-status={freshness.status}
-                        aria-label={freshnessLabel(freshness)}
-                        title={freshnessLabel(freshness)}
-                      >{freshnessText}</span>
-                      <span class="chapter-card-verified">
-                        verified {formatDate(c.data.last_verified)}
+                        {tools
+                          ? appendix
+                            ? `Appendix ${String.fromCharCode(64 + (data.chapter as number)).toLowerCase()}`
+                            : `Chapter ${data.chapter}`
+                          : `Week ${data.week}`}
                       </span>
+                      {tools && (
+                        <span
+                          class={`volatility-badge volatility-${data.volatility}`}
+                          title={`Volatility: ${data.volatility}`}
+                        >{data.volatility}</span>
+                      )}
+                      {!tools && data.status && (
+                        <span
+                          class={`status-badge status-${data.status}`}
+                          title={`Status: ${data.status}`}
+                        >{data.status}</span>
+                      )}
+                      {freshness && freshnessText && (
+                        <span
+                          class="freshness-badge"
+                          data-status={freshness.status}
+                          aria-label={freshnessLabel(freshness)}
+                          title={freshnessLabel(freshness)}
+                        >{freshnessText}</span>
+                      )}
+                      {tools && data.last_verified && (
+                        <span class="chapter-card-verified">
+                          verified {formatDate(data.last_verified as Date)}
+                        </span>
+                      )}
                     </div>
-                    <h3 class="chapter-card-title">{c.data.title}</h3>
-                    {c.data.description && (
-                      <p class="chapter-card-description">{c.data.description}</p>
+                    <h3 class="chapter-card-title">{data.title}</h3>
+                    {data.description && (
+                      <p class="chapter-card-description">{data.description as string}</p>
+                    )}
+                    {tools && (
+                      <div class="chapter-card-tools">
+                        {(data.tools_compared as string[]).map((t) => (
+                          <span class="tool-badge">{t}</span>
+                        ))}
+                      </div>
                     )}
-                    <div class="chapter-card-tools">
-                      {c.data.tools_compared.map((t) => (
-                        <span class="tool-badge">{t}</span>
-                      ))}
-                    </div>
                   </a>
                 </li>
               );

package/scripts/validate.mjs

@@ -27,8 +27,40 @@
  */
 import { readFile, access } from 'node:fs/promises';
 import { glob } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
 
+/**
+ * Best-effort .env reader. Mirrors `readEnvFile` in src/types.ts; kept inline
+ * here because scripts/ is shipped as plain JS without compiling src/.
+ *
+ * Closes #20 — validate.mjs previously skipped the .env fallback that
+ * `resolveProfileWithSource` honors, so consumers who set BOOK_PROFILE in
+ * .env (per the SKILL.md and scaffold's create-book defaults) saw the CLI
+ * silently default to minimal, masking academic-profile errors.
+ */
+function readEnvFile(path = '.env') {
+  try {
+    if (!existsSync(path)) return {};
+    const out = {};
+    for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
+      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+      if (!m) continue;
+      let val = m[2] ?? '';
+      if (
+        (val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))
+      ) {
+        val = val.slice(1, -1);
+      }
+      out[m[1]] = val;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold validate [--preset <name>]
 
@@ -67,8 +99,20 @@ const CHAPTERS_DIR = resolve(ROOT, 'src/content/chapters');
 const PUBLIC_DIR = resolve(ROOT, 'public');
 const DATA_DIR = resolve(ROOT, 'src/data');
 
-// Preset resolution: --preset flag > BOOK_PRESET env > BOOK_PROFILE env > 'minimal'.
-const PRESET = presetFromFlag ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE ?? 'minimal';
+// Preset resolution (matches resolvePreset in src/types.ts):
+//   --preset flag > BOOK_PRESET env > BOOK_PROFILE env >
+//   .env BOOK_PRESET > .env BOOK_PROFILE > 'minimal'.
+// .env fallback closes #20 — without it, consumers who set BOOK_PROFILE in
+// .env (the documented convenience in SKILL.md + create-book defaults) saw
+// the CLI silently default to minimal, hiding academic-profile errors.
+const dotenv = readEnvFile(resolve(ROOT, '.env'));
+const PRESET =
+  presetFromFlag ??
+  process.env.BOOK_PRESET ??
+  process.env.BOOK_PROFILE ??
+  dotenv.BOOK_PRESET ??
+  dotenv.BOOK_PROFILE ??
+  'minimal';
 // Alias kept for downstream message text only; the resolution above is canonical.
 const PROFILE = PRESET;
 const REPO_ROOT = process.env.BOOK_REPO_ROOT ?? null;

package/src/lib/chapter-sort.ts

@@ -0,0 +1,55 @@
+/**
+ * src/lib/chapter-sort.ts — pure sort-key helper for chapter frontmatter.
+ *
+ * Lives in its own file (no `astro:content` imports) so tsup can include it
+ * in the toolkit's DTS bundle without trying to resolve Astro's virtual
+ * modules at build time. The Astro-context wrappers (sortKey, getAllChapters,
+ * getNeighbors) live in src/lib/chapters.ts and import from here.
+ */
+
+/**
+ * Ordinal positions for the academic-profile `part` enum (src/schemas.ts:
+ * academicParts). Order here is load-bearing: it determines the on-page
+ * grouping order of academic books. Anything outside the enum (e.g., a
+ * consumer-extended part name) sorts to the end.
+ */
+const ACADEMIC_PART_ORDINAL: Record<string, number> = {
+  foundations: 1,
+  'ssm-core': 2,
+  'beyond-ssm': 3,
+  integration: 4,
+  synthesis: 5,
+};
+
+const UNKNOWN_PART_ORDINAL = 99;
+
+/**
+ * Pure-function sort key from a chapter frontmatter object. Spans both
+ * tools and academic schemas:
+ *
+ *  - Tools: numeric `part` (0-10), numeric `chapter` (0-99). Encodes as
+ *    `part * 1000 + chapter` so chapters within a part stay grouped.
+ *  - Academic: string-enum `part` (foundations|ssm-core|...), numeric `week`
+ *    (1-99), no `chapter`. Maps `part` to a fixed ordinal then encodes as
+ *    `partOrdinal * 1000 + week`.
+ *
+ * v3.5.2 (closes #24): previously the tools-only formula crashed on
+ * academic chapters (string `part`, no `chapter`) by producing NaN sort
+ * keys.
+ */
+export function chapterSortKey(data: Record<string, unknown>): number {
+  const partRaw = data.part;
+  const partOrdinal =
+    typeof partRaw === 'number'
+      ? partRaw
+      : typeof partRaw === 'string'
+        ? (ACADEMIC_PART_ORDINAL[partRaw] ?? UNKNOWN_PART_ORDINAL)
+        : UNKNOWN_PART_ORDINAL;
+  const within =
+    typeof data.chapter === 'number'
+      ? data.chapter
+      : typeof data.week === 'number'
+        ? data.week
+        : 0;
+  return partOrdinal * 1000 + within;
+}

package/src/lib/chapters.ts

@@ -1,19 +1,26 @@
 /**
  * src/lib/chapters.ts — ordering + nav helpers for the chapters collection.
  *
- * Centralizes the sort key (part × 100 + chapter) and draft filtering so
- * components and static-path generation use the same logic.
+ * Astro-context wrappers (need `astro:content`). The pure sort-key logic
+ * lives in src/lib/chapter-sort.ts so it can be included in the toolkit's
+ * DTS bundle without dragging Astro virtual modules into the build graph.
+ *
+ * v3.5.2 (closes #24): schema-aware sort. Previously assumed tools-profile
+ * shape (numeric `part` * 1000 + numeric `chapter`); academic chapters
+ * (string `part` enum + numeric `week`, no `chapter`) crashed.
  */
 import { getCollection, type CollectionEntry } from 'astro:content';
+import { chapterSortKey } from './chapter-sort.js';
 
 export type Chapter = CollectionEntry<'chapters'>;
 
-/** Numeric sort key; chapters within a part come before a higher part. */
+/** Sort key for an Astro Chapter collection entry. Thin wrapper over the
+ *  pure `chapterSortKey` helper. */
 export function sortKey(c: Chapter): number {
-  return c.data.part * 1000 + c.data.chapter;
+  return chapterSortKey(c.data as Record<string, unknown>);
 }
 
-/** All non-draft chapters, ordered by part+chapter ascending. */
+/** All non-draft chapters, ordered by part+chapter (tools) or part+week (academic). */
 export async function getAllChapters(): Promise<Chapter[]> {
   const all = await getCollection('chapters', (entry) => !entry.data.draft);
   return all.sort((a, b) => sortKey(a) - sortKey(b));