@brandon_m_behring/book-scaffold-astro 3.6.4 → 3.7.0

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
+});

package/src/schemas.ts

@@ -0,0 +1,291 @@
+/**
+ * Zod schemas + enum constants for book content collections.
+ *
+ * All Zod schemas live in this single file (single `astro/zod` import) so
+ * tsup's DTS bundler doesn't traverse Zod's dual CJS/ESM package multiple
+ * times — rollup-plugin-dts can't resolve Zod v4's `default` export when
+ * the same Zod import appears in multiple entry-graph files.
+ *
+ * Per-profile organization lives at src/profiles/<name>.ts which imports
+ * these schemas as values + declares the inferred chapter type + the
+ * route/style defaults. See ~/.claude/plans/address-and-finish-moonlit-shell.md.
+ *
+ * Imports `z` from `astro/zod` (a real module re-export) so schemas can
+ * be constructed at package-load time outside an Astro runtime context.
+ * `defineBookSchemas` in schemas-entry.ts wraps these into Astro
+ * `defineCollection` calls at the consumer's content-config load time.
+ */
+import { z } from 'astro/zod';
+
+// ===== Tools-profile enums =====
+
+export const toolSlugs = [
+  'claude-code',
+  'gemini-cli',
+  'codex-cli',
+  'cross-tool',
+] as const;
+
+export const volatilityLevels = [
+  'stable-principle',
+  'architectural-pattern',
+  'feature-surface',
+] as const;
+
+export const sourceTiers = [
+  'T1-official',
+  'T2-release-notes',
+  'T3-practitioner',
+  'T4-conjecture',
+] as const;
+
+export const changeKinds = ['added', 'removed', 'changed', 'deprecated'] as const;
+
+export const patternCategories = [
+  'safety',
+  'scale',
+  'context',
+  'interaction',
+  'extension',
+  'other',
+] as const;
+
+// ===== Academic-profile enums =====
+
+export const academicParts = [
+  'foundations',
+  'ssm-core',
+  'beyond-ssm',
+  'integration',
+  'synthesis',
+] as const;
+
+export const chapterStatus = [
+  'implemented',
+  'chapter_only',
+  'reading_only',
+  'prose_only',
+  'code_only',
+  'scaffolded',
+  'planned',
+] as const;
+
+// ===== Chapter schemas — one per profile =====
+
+export const academicChapterSchema = z.object({
+  week: z.number().int().min(1).max(99),
+  part: z.enum(academicParts),
+  title: z.string().min(1),
+  status: z.enum(chapterStatus),
+  roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
+  code_path: z.string().optional(),
+  tests_path: z.string().optional(),
+  notebook_path: z.string().optional(),
+  description: z.string().optional(),
+  draft: z.boolean().default(false),
+});
+
+export const toolsChapterSchema = z.object({
+  title: z.string().min(1),
+  part: z.number().int().min(0).max(10),
+  chapter: z.number().int().min(0).max(99),
+  volatility: z.enum(volatilityLevels),
+  tools_compared: z.array(z.enum(toolSlugs)).min(1),
+  last_verified: z.date(),
+  sources: z.array(z.string()).default([]),
+  description: z.string().optional(),
+  draft: z.boolean().default(false),
+  updated: z.date().optional(),
+});
+
+/** Minimal profile currently aliases the tools schema. */
+export const minimalChapterSchema = toolsChapterSchema;
+
+/**
+ * Research-portfolio source tiers (v3.5.0, closes issue #6).
+ *
+ * Lighter shape than the tools-profile `sourceTiers` enum (`'T1-official'` etc.)
+ * — research portfolios cite primary sources inline per-chapter, so short
+ * `'T1'`/`'T2'` is more compact and readable. Semantics overlap (T1 = official
+ * primary, T2 = secondary, T3 = practitioner / community, T4 = conjecture).
+ */
+export const sourceTiersResearch = ['T1', 'T2', 'T3', 'T4'] as const;
+
+/**
+ * Course-notes profile schema (v3.3.0, closes issue #4). Designed for
+ * course-derived study notes (DLAI, Coursera, Manning, ...). Key fields:
+ * - `course`/`instructor`/`source_url` — attribution
+ * - `learning_outcomes` — structured Bloom-tag-ready outcomes
+ * - `tags` — freeform string array (NOT tools_compared enum)
+ */
+export const courseNotesChapterSchema = z.object({
+  // Identity
+  title: z.string().min(1),
+  chapter: z.number().int().min(0).max(99),
+  part: z.number().int().min(0).max(20).default(1),
+  description: z.string().optional(),
+
+  // Source attribution
+  course: z.string().optional(),
+  instructor: z.string().optional(),
+  source_url: z.string().url().optional(),
+
+  // Pedagogy
+  learning_outcomes: z
+    .array(
+      z.object({
+        id: z.string(),
+        verb: z.string(),
+        text: z.string(),
+      }),
+    )
+    .default([]),
+  tags: z.array(z.string()).default([]),
+
+  // Provenance + status (shared shape with tools profile)
+  last_verified: z.date(),
+  volatility: z.enum(volatilityLevels).default('architectural-pattern'),
+  sources: z.array(z.string()).default([]),
+  draft: z.boolean().default(false),
+});
+
+/**
+ * Research-portfolio profile schema (v3.5.0, closes issue #6).
+ *
+ * Union of academic + tools field shapes, modernized: uses `tags` (freeform
+ * string array) instead of `tools_compared` (CLI-enum, doesn't fit research
+ * content). Designed for research-portfolio books that need BOTH academic-
+ * style structure (week/part/status, math/BibTeX/Theorem support via the
+ * `katex: true` profile flag) AND tools-style provenance (volatility class,
+ * tier-tagged sources, last_verified freshness signal).
+ *
+ * Reference (forthcoming) consumer: prompt-injection-portfolio.
+ *
+ * Hierarchy fields are all optional — chapters can use academic-style
+ * (`week` + part-enum string) OR tools-style (`chapter` + part-number) OR
+ * minimal (just title). The route templates dispatch on which is set.
+ *
+ * Sources are STRUCTURED INLINE (each chapter cites primary sources directly)
+ * rather than referencing a sources collection — saves cross-file lookup +
+ * matches research-paper citation conventions. Tier shorthand T1/T2/T3/T4
+ * (per sourceTiersResearch) over the tools-profile long form.
+ */
+export const researchPortfolioChapterSchema = z.object({
+  // Identity
+  title: z.string().min(1),
+  slug: z.string().optional(),                 // explicit slug override (otherwise filename)
+  description: z.string().optional(),
+
+  // Hierarchy — accept either academic-style or tools-style; all optional.
+  // The academic 'part' field is a string enum; tools 'part' is a number.
+  // Use z.union to permit either type.
+  part: z.union([z.number().int().min(0).max(20), z.string()]).optional(),
+  week: z.number().int().min(0).max(99).optional(),
+  chapter: z.number().int().min(0).max(99).optional(),
+
+  // Academic-style status (optional for research-portfolio — books may track
+  // chapters as 'prose_only' / 'experimental-result' / etc.).
+  status: z
+    .enum([
+      'implemented',
+      'chapter_only',
+      'reading_only',
+      'prose_only',
+      'code_only',
+      'scaffolded',
+      'planned',
+    ])
+    .optional(),
+
+  // Research-portfolio specific: nature of the chapter's content.
+  // Distinct from academic's 'status' (which tracks authoring state) — this
+  // describes the EVIDENCE TYPE the chapter rests on.
+  freshness: z
+    .enum([
+      'experimental-result',   // primary data the author produced
+      'literature-survey',     // synthesis of others' work
+      'theoretical',           // analytical / mathematical argument
+      'reference',             // canonical material (definitions, taxonomy)
+    ])
+    .optional(),
+
+  // Provenance (tools-style — overlap with tools/course-notes profiles).
+  volatility: z.enum(volatilityLevels).optional(),
+  tags: z.array(z.string()).default([]),       // freeform; replaces tools_compared
+
+  // Structured inline sources with T1-T4 tiers.
+  sources: z
+    .array(
+      z.object({
+        tier: z.enum(sourceTiersResearch),
+        url: z.string().url(),
+        label: z.string().min(1),
+      }),
+    )
+    .default([]),
+
+  // Status + dates.
+  last_verified: z.date(),
+  updated: z.date().optional(),
+  draft: z.boolean().default(false),
+});
+
+// ===== Inferred chapter types — one per schema =====
+//
+// Exported here so per-profile modules can re-export under a common name
+// (AcademicChapter, ToolsChapter, etc.) without each touching `z.infer`
+// in its own file (which would multiply the Zod import points and trip
+// rollup-plugin-dts).
+
+export type AcademicChapter = z.infer<typeof academicChapterSchema>;
+export type ToolsChapter = z.infer<typeof toolsChapterSchema>;
+export type MinimalChapter = z.infer<typeof minimalChapterSchema>;
+export type CourseNotesChapter = z.infer<typeof courseNotesChapterSchema>;
+export type ResearchPortfolioChapter = z.infer<typeof researchPortfolioChapterSchema>;
+
+// ===== Collateral collection schemas (tools-profile; always-defined) =====
+
+export const sourcesSchema = z.object({
+  url: z.string().url(),
+  title: z.string().min(1),
+  author: z.string().optional(),
+  publish_date: z.date().optional(),
+  captured_at: z.date(),
+  content_hash: z
+    .string()
+    .regex(/^sha256:[a-f0-9]+$/)
+    .optional(),
+  tier: z.enum(sourceTiers),
+  tool: z.enum(toolSlugs),
+  perma_cc: z.string().url().nullable().optional(),
+  local_cache: z.string().nullable().optional(),
+});
+
+export const changelogSchema = z.object({
+  tool: z.enum(toolSlugs),
+  versions: z
+    .array(
+      z.object({
+        version: z.string().min(1),
+        date: z.date(),
+        changes: z
+          .array(
+            z.object({
+              pattern: z.string(),
+              kind: z.enum(changeKinds),
+              note: z.string().min(1),
+              source_key: z.string().optional(),
+            }),
+          )
+          .default([]),
+      }),
+    )
+    .default([]),
+});
+
+export const patternsSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  category: z.enum(patternCategories).optional(),
+  convergence_date: z.date().nullable().optional(),
+});