@brandon_m_behring/book-scaffold-astro 3.6.5 → 3.7.1

package/src/profiles/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Profile registry — single source of truth for the BOOK_PROFILE enum.
+ *
+ * Each profile is a self-contained module that declares its schema + routes
+ * + styles via defineProfile(). The PROFILES object below is the only place
+ * the toolkit looks up profile config; bookScaffoldIntegration consumes
+ * PROFILES[profile] to drive injectRoute / injectScript calls.
+ *
+ * To add a new profile: create src/profiles/<name>.ts, then add two lines
+ * here (one to PROFILES, one to ChapterFor). The discriminated union of
+ * BookProfile = keyof typeof PROFILES updates automatically.
+ */
+import { academicProfile, type AcademicChapter } from './academic.js';
+import { toolsProfile, type ToolsChapter } from './tools.js';
+import { minimalProfile, type MinimalChapter } from './minimal.js';
+import { courseNotesProfile, type CourseNotesChapter } from './course-notes.js';
+import { researchPortfolioProfile, type ResearchPortfolioChapter } from './research-portfolio.js';
+
+export const PROFILES = {
+  academic: academicProfile,
+  tools: toolsProfile,
+  minimal: minimalProfile,
+  'course-notes': courseNotesProfile,
+  'research-portfolio': researchPortfolioProfile,
+} as const;
+
+export type BookProfile = keyof typeof PROFILES;
+
+export const BOOK_PROFILES = Object.keys(PROFILES) as readonly BookProfile[];
+
+/**
+ * Generic chapter-shape lookup. Consumers writing helpers parametrized over
+ * a profile can use this for narrowed typing:
+ *
+ *   function summarize<P extends BookProfile>(profile: P, chapter: ChapterFor<P>) {
+ *     // chapter is narrowed to AcademicChapter / ToolsChapter / etc.
+ *   }
+ */
+export type ChapterFor<P extends BookProfile> =
+  P extends 'academic' ? AcademicChapter :
+  P extends 'tools' ? ToolsChapter :
+  P extends 'minimal' ? MinimalChapter :
+  P extends 'course-notes' ? CourseNotesChapter :
+  P extends 'research-portfolio' ? ResearchPortfolioChapter :
+  never;
+
+// Re-export the inferred chapter types for consumer ergonomics.
+export type {
+  AcademicChapter,
+  ToolsChapter,
+  MinimalChapter,
+  CourseNotesChapter,
+  ResearchPortfolioChapter,
+};

package/src/profiles/minimal.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal profile — single-author essays / manifestos. Currently aliases
+ * the tools chapter schema (defined in src/schemas.ts as
+ * minimalChapterSchema). If minimal-specific fields emerge from a real
+ * consumer, this is where they land.
+ */
+import { defineProfile } from '../profile-kit.js';
+import { minimalChapterSchema } from '../schemas.js';
+import { fallbackChaptersRenderer } from './renderers/fallback-chapters.js';
+
+export type { MinimalChapter } from '../schemas.js';
+
+export const minimalProfile = defineProfile({
+  name: 'minimal',
+  schema: minimalChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    convergence: false,
+    frontmatter: false,     // opt-in per book; see #7
+  },
+  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
+  // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
+  chaptersRenderer: fallbackChaptersRenderer,
+});

package/src/profiles/renderers/academic-chapters.ts

@@ -0,0 +1,102 @@
+/**
+ * src/profiles/renderers/academic-chapters.ts — ChaptersRenderer implementation
+ * for the academic profile. Owns: string-enum part grouping (foundations,
+ * ssm-core, beyond-ssm, integration, synthesis), Week N numbering, status
+ * badge (7-state). No freshness/last_verified, no tools_compared.
+ *
+ * Mirrors the v3.5.2 academic branch of pages/chapters.astro — DOM output
+ * intended to match exactly so academic visual baselines stay stable.
+ */
+import type {
+  ChaptersRenderer,
+  PartKey,
+  StatusBadge,
+} from '../../lib/chapters-renderer.js';
+
+/**
+ * Ordinal positions for the academic-profile `part` enum (src/schemas.ts:
+ * academicParts). Order is load-bearing — drives both grouping order and
+ * sort key. Must match academicParts in schemas.ts.
+ */
+const ACADEMIC_PART_ORDINAL: Record<string, number> = {
+  foundations: 1,
+  'ssm-core': 2,
+  'beyond-ssm': 3,
+  integration: 4,
+  synthesis: 5,
+};
+
+const UNKNOWN_PART_ORDINAL = 99;
+
+/** Title-case an enum string: "ssm-core" → "Ssm Core". */
+function titleCase(part: string): string {
+  return part
+    .split('-')
+    .map((w) => (w.length > 0 ? w.charAt(0).toUpperCase() + w.slice(1) : ''))
+    .join(' ');
+}
+
+export const academicChaptersRenderer: ChaptersRenderer = {
+  partKey(data) {
+    return (data.part as PartKey) ?? '';
+  },
+
+  formatPartLabel(part) {
+    if (typeof part === 'string' && part.length > 0) {
+      return titleCase(part);
+    }
+    return String(part);
+  },
+
+  isAppendix(_part) {
+    // Academic profile doesn't have appendices in the tools sense.
+    return false;
+  },
+
+  formatChapterNumber(data, _appendix) {
+    const week = (data.week as number) ?? 0;
+    return `Week ${week}`;
+  },
+
+  getToolsAttr(_data) {
+    // Academic chapters opt out of the ToolFilter island by claiming
+    // "cross-tool" — they remain visible regardless of filter selection.
+    return 'cross-tool';
+  },
+
+  getVolatilityData(_data) {
+    // Academic profile uses status, not volatility.
+    return null;
+  },
+
+  getStatusData(data): StatusBadge | null {
+    const status = data.status as string | undefined;
+    if (!status) return null;
+    return { status, label: status };
+  },
+
+  getFreshnessData(_data, _now) {
+    // Academic profile doesn't track last_verified.
+    return null;
+  },
+
+  getVerifiedDateLabel(_data) {
+    return null;
+  },
+
+  getToolsCompared(_data) {
+    return [];
+  },
+
+  sortKey(data) {
+    const partRaw = data.part;
+    const partOrdinal =
+      typeof partRaw === 'string'
+        ? (ACADEMIC_PART_ORDINAL[partRaw] ?? UNKNOWN_PART_ORDINAL)
+        : typeof partRaw === 'number'
+          ? partRaw
+          : UNKNOWN_PART_ORDINAL;
+    const week = typeof data.week === 'number' ? data.week : 0;
+    return partOrdinal * 1000 + week;
+  },
+};

package/src/profiles/renderers/fallback-chapters.ts

@@ -0,0 +1,87 @@
+/**
+ * src/profiles/renderers/fallback-chapters.ts — ChaptersRenderer used by
+ * profiles that don't ship a dedicated renderer (minimal, course-notes,
+ * research-portfolio). Dispatches by field presence — exactly the v3.5.2
+ * logic that lived inline in pages/chapters.astro before #35.
+ *
+ * Safety net for shapes we haven't designed for explicitly. If a consumer
+ * opts a course-notes or research-portfolio book into `routes.chapters: true`,
+ * the fallback renders reasonably without crashing. Custom output for those
+ * profiles is a v4+ extension point (consumer-overridable renderer).
+ */
+import type {
+  ChaptersRenderer,
+  PartKey,
+  VolatilityBadge,
+  StatusBadge,
+  FreshnessAffordance,
+} from '../../lib/chapters-renderer.js';
+import { toolsChaptersRenderer } from './tools-chapters.js';
+import { academicChaptersRenderer } from './academic-chapters.js';
+
+function isToolsShape(data: Record<string, unknown>): boolean {
+  return 'volatility' in data && 'chapter' in data;
+}
+
+function isAcademicShape(data: Record<string, unknown>): boolean {
+  return 'week' in data && 'status' in data;
+}
+
+/** Per-chapter dispatch to whichever known renderer matches the data shape. */
+function dispatch(data: Record<string, unknown>): ChaptersRenderer {
+  if (isToolsShape(data)) return toolsChaptersRenderer;
+  if (isAcademicShape(data)) return academicChaptersRenderer;
+  // Unknown shape — return tools as the most-feature-complete default. The
+  // individual method results below short-circuit to safe values when fields
+  // are missing.
+  return toolsChaptersRenderer;
+}
+
+export const fallbackChaptersRenderer: ChaptersRenderer = {
+  partKey(data) {
+    return (data.part as PartKey) ?? 0;
+  },
+
+  formatPartLabel(part) {
+    if (typeof part === 'number') {
+      return part >= 6 ? 'Appendices' : `Part ${part}`;
+    }
+    return dispatch({ part } as Record<string, unknown>).formatPartLabel(part);
+  },
+
+  isAppendix(part) {
+    return typeof part === 'number' && part >= 6;
+  },
+
+  formatChapterNumber(data, appendix) {
+    return dispatch(data).formatChapterNumber(data, appendix);
+  },
+
+  getToolsAttr(data) {
+    return dispatch(data).getToolsAttr(data);
+  },
+
+  getVolatilityData(data): VolatilityBadge | null {
+    return dispatch(data).getVolatilityData(data);
+  },
+
+  getStatusData(data): StatusBadge | null {
+    return dispatch(data).getStatusData(data);
+  },
+
+  getFreshnessData(data, now): FreshnessAffordance | null {
+    return dispatch(data).getFreshnessData(data, now);
+  },
+
+  getVerifiedDateLabel(data) {
+    return dispatch(data).getVerifiedDateLabel(data);
+  },
+
+  getToolsCompared(data) {
+    return dispatch(data).getToolsCompared(data);
+  },
+
+  sortKey(data) {
+    return dispatch(data).sortKey(data);
+  },
+};

package/src/profiles/renderers/tools-chapters.ts

@@ -0,0 +1,102 @@
+/**
+ * src/profiles/renderers/tools-chapters.ts — ChaptersRenderer implementation
+ * for the tools profile. Owns: numeric part grouping (with Appendix splitting
+ * at part >= 6), Chapter N numbering, volatility badge, freshness affordance
+ * from last_verified + volatility class, tools_compared tags.
+ *
+ * Mirrors the pre-v3.7.0 logic in pages/chapters.astro for tools-shape
+ * chapters — DOM output is intended to be byte-equivalent so the existing
+ * visual-regression baselines (package/tests/visual/fixture/) pass without
+ * recapture.
+ */
+import type {
+  ChaptersRenderer,
+  PartKey,
+  VolatilityBadge,
+  StatusBadge,
+  FreshnessAffordance,
+} from '../../lib/chapters-renderer.js';
+import { getFreshness, freshnessLabel, type VolatilityLevel } from '../../lib/freshness.js';
+
+function formatDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+function freshnessText(status: 'fresh' | 'verify-soon' | 'stale'): string {
+  switch (status) {
+    case 'fresh':
+      return 'Fresh';
+    case 'verify-soon':
+      return 'Verify soon';
+    case 'stale':
+      return 'Stale';
+  }
+}
+
+export const toolsChaptersRenderer: ChaptersRenderer = {
+  partKey(data) {
+    return (data.part as number) ?? 0;
+  },
+
+  formatPartLabel(part) {
+    if (typeof part === 'number') {
+      return part >= 6 ? 'Appendices' : `Part ${part}`;
+    }
+    // Defensive: unknown shape passed in. Render as-is.
+    return String(part);
+  },
+
+  isAppendix(part) {
+    return typeof part === 'number' && part >= 6;
+  },
+
+  formatChapterNumber(data, appendix) {
+    const chapter = (data.chapter as number) ?? 0;
+    if (appendix) {
+      // 'a', 'b', 'c', ... — matches pre-v3.7.0 String.fromCharCode(64 + chapter).toLowerCase()
+      return `Appendix ${String.fromCharCode(64 + chapter).toLowerCase()}`;
+    }
+    return `Chapter ${chapter}`;
+  },
+
+  getToolsAttr(data) {
+    const tools = (data.tools_compared as string[]) ?? [];
+    return tools.join(' ');
+  },
+
+  getVolatilityData(data): VolatilityBadge | null {
+    const level = data.volatility as string | undefined;
+    if (!level) return null;
+    return { level, label: level };
+  },
+
+  getStatusData(_data): StatusBadge | null {
+    // Tools profile uses volatility, not status. Status is academic-only.
+    return null;
+  },
+
+  getFreshnessData(data, now): FreshnessAffordance | null {
+    const lastVerified = data.last_verified as Date | undefined;
+    const volatility = data.volatility as VolatilityLevel | undefined;
+    if (!lastVerified || !volatility) return null;
+    const f = getFreshness(lastVerified, volatility, now);
+    if (!f) return null;
+    return { status: f.status, label: freshnessLabel(f) };
+  },
+
+  getVerifiedDateLabel(data) {
+    const lastVerified = data.last_verified as Date | undefined;
+    if (!(lastVerified instanceof Date)) return null;
+    return `verified ${formatDate(lastVerified)}`;
+  },
+
+  getToolsCompared(data) {
+    return ((data.tools_compared as string[]) ?? []).slice();
+  },
+
+  sortKey(data) {
+    const part = (data.part as number) ?? 0;
+    const chapter = (data.chapter as number) ?? 0;
+    return part * 1000 + chapter;
+  },
+};

package/src/profiles/research-portfolio.ts

@@ -0,0 +1,44 @@
+/**
+ * Research-portfolio profile — books that combine academic structure (week/
+ * part/status + math + BibTeX + Theorem family) with tools-style provenance
+ * (volatility class, tier-tagged sources, last_verified freshness signal).
+ *
+ * Closes issue #6 (v3.5.0). Reference consumer (forthcoming):
+ * prompt-injection-portfolio.
+ *
+ * Schema + inferred type live in src/schemas.ts; this module composes with
+ * routes + styles + katex flag.
+ *
+ * Distinguishing features vs other profiles:
+ *
+ * - Routes: /references + /search + /print + /frontmatter all auto-injected
+ *   by default (research portfolios universally need a title-page /
+ *   ai-disclosure / pre-release-banner under /frontmatter). /chapters and
+ *   /convergence stay off — portfolios typically have a custom landing
+ *   page enumerating chapters by part.
+ * - Styles: same as academic (chapter.css/typography.css/etc.) — KaTeX
+ *   math is on by default since most portfolio chapters reference equations.
+ * - katex: true — math typesetting wired in (same as academic).
+ */
+import { defineProfile } from '../profile-kit.js';
+import { researchPortfolioChapterSchema } from '../schemas.js';
+import { fallbackChaptersRenderer } from './renderers/fallback-chapters.js';
+
+export type { ResearchPortfolioChapter } from '../schemas.js';
+
+export const researchPortfolioProfile = defineProfile({
+  name: 'research-portfolio',
+  schema: researchPortfolioChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,             // portfolio books ship their own landing/index
+    convergence: false,          // tools-profile-specific
+    frontmatter: true,           // portfolios universally need title/disclosure/banner pages
+  },
+  styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
+  katex: true,                   // math is common in research content
+  // v3.7.0 (#35): portfolio schema is a union of academic + tools shapes — fallback renderer dispatches per chapter via field presence
+  chaptersRenderer: fallbackChaptersRenderer,
+});

package/src/profiles/tools.ts

@@ -0,0 +1,29 @@
+/**
+ * Tools profile — AI-CLI comparison content with volatility + sources.
+ *
+ * Reference consumer: book-template-astro. Schema + inferred type live in
+ * src/schemas.ts; this module composes with routes + styles.
+ */
+import { defineProfile } from '../profile-kit.js';
+import { toolsChapterSchema } from '../schemas.js';
+import { toolsChaptersRenderer } from './renderers/tools-chapters.js';
+
+export type { ToolsChapter } from '../schemas.js';
+
+export const toolsProfile = defineProfile({
+  name: 'tools',
+  schema: toolsChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: true,         // tools profile ships a flat chapter index
+    convergence: true,      // tools profile ships convergence dashboard
+    frontmatter: false,     // opt-in per book; see #7
+  },
+  styles: [
+    'tokens.css', 'layout.css', 'callouts.css', 'chapter.css',
+    'typography.css', 'print.css', 'convergence.css', 'tool-filter.css',
+  ],
+  chaptersRenderer: toolsChaptersRenderer,   // v3.7.0 (#35) — owns /chapters semantics for tools shape
+});