@brandon_m_behring/book-scaffold-astro 3.2.0 → 3.4.0

package/dist/index.mjs

@@ -118,9 +118,232 @@ var init_katex_macros = __esm({
 import mdx from "@astrojs/mdx";
 import preact from "@astrojs/preact";
 
+// src/profile-kit.ts
+function defineProfile(p) {
+  return p;
+}
+
+// src/schemas.ts
+import { z } from "astro/zod";
+var toolSlugs = [
+  "claude-code",
+  "gemini-cli",
+  "codex-cli",
+  "cross-tool"
+];
+var volatilityLevels = [
+  "stable-principle",
+  "architectural-pattern",
+  "feature-surface"
+];
+var sourceTiers = [
+  "T1-official",
+  "T2-release-notes",
+  "T3-practitioner",
+  "T4-conjecture"
+];
+var changeKinds = ["added", "removed", "changed", "deprecated"];
+var patternCategories = [
+  "safety",
+  "scale",
+  "context",
+  "interaction",
+  "extension",
+  "other"
+];
+var academicParts = [
+  "foundations",
+  "ssm-core",
+  "beyond-ssm",
+  "integration",
+  "synthesis"
+];
+var chapterStatus = [
+  "implemented",
+  "chapter_only",
+  "reading_only",
+  "prose_only",
+  "code_only",
+  "scaffolded",
+  "planned"
+];
+var 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)
+});
+var 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()
+});
+var minimalChapterSchema = toolsChapterSchema;
+var 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)
+});
+var 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()
+});
+var 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([])
+});
+var patternsSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  category: z.enum(patternCategories).optional(),
+  convergence_date: z.date().nullable().optional()
+});
+
+// src/profiles/academic.ts
+var academicProfile = defineProfile({
+  name: "academic",
+  schema: academicChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // academic consumers ship their own week-based /chapters listing
+    convergence: false,
+    // tools-profile-specific
+    frontmatter: false
+    // opt-in per book; see #7
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  katex: true
+});
+
+// src/profiles/tools.ts
+var 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"
+  ]
+});
+
+// src/profiles/minimal.ts
+var 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"]
+});
+
+// src/profiles/course-notes.ts
+var courseNotesProfile = defineProfile({
+  name: "course-notes",
+  schema: courseNotesChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // multi-book consumers route via [book]/[slug] themselves
+    convergence: false,
+    frontmatter: false
+    // opt-in per book; see #7
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
+});
+
+// src/profiles/index.ts
+var PROFILES = {
+  academic: academicProfile,
+  tools: toolsProfile,
+  minimal: minimalProfile,
+  "course-notes": courseNotesProfile
+};
+var BOOK_PROFILES = Object.keys(PROFILES);
+
 // src/types.ts
 import { existsSync, readFileSync } from "fs";
-var BOOK_PROFILES = ["academic", "tools", "minimal"];
+var BOOK_PRESETS = BOOK_PROFILES;
 var BookConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -145,74 +368,131 @@ function readEnvFile(path = ".env") {
     return {};
   }
 }
-function resolveProfile(explicit) {
-  let candidate = explicit ?? process.env.BOOK_PROFILE;
+function resolvePreset(explicitPreset, explicitProfile) {
+  let candidate = explicitPreset ?? explicitProfile ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE;
   let source = "default";
-  if (explicit) source = "param";
-  else if (process.env.BOOK_PROFILE) source = "env";
+  if (explicitPreset || explicitProfile) source = "param";
+  else if (process.env.BOOK_PRESET || process.env.BOOK_PROFILE) source = "env";
   if (!candidate) {
-    const fromFile = readEnvFile().BOOK_PROFILE;
+    const env = readEnvFile();
+    const fromFile = env.BOOK_PRESET ?? env.BOOK_PROFILE;
     if (fromFile) {
       candidate = fromFile;
       source = "dotenv";
     }
   }
   candidate = candidate ?? "minimal";
-  if (!BOOK_PROFILES.includes(candidate)) {
+  if (!BOOK_PRESETS.includes(candidate)) {
     throw new BookConfigError(
-      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
+      `preset must be one of ${BOOK_PRESETS.join(" | ")} (got ${JSON.stringify(candidate)})`
     );
   }
   if (source === "default") {
-    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
+    console.warn("book-scaffold-astro: BOOK_PRESET not set; falling back to 'minimal'.");
   }
   return candidate;
 }
+function resolveProfile(explicit) {
+  return resolvePreset(void 0, explicit);
+}
 
 // src/integration.ts
 import { fileURLToPath } from "url";
-var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
-var ALWAYS_ON_STYLES = [
-  "tokens.css",
-  "layout.css",
-  "callouts.css",
-  "chapter.css",
-  "typography.css",
-  "print.css"
-];
-var TOOLS_ONLY_STYLES = ["convergence.css", "tool-filter.css"];
-var DEFAULT_ROUTES_ALL = [
-  { pattern: "/references", file: "references.astro" },
-  { pattern: "/search", file: "search.astro" },
-  { pattern: "/print", file: "print.astro" }
-];
-var DEFAULT_ROUTES_TOOLS = [
-  { pattern: "/chapters", file: "chapters.astro" },
-  { pattern: "/convergence", file: "convergence.astro" }
+
+// src/mdx-components-resolver.ts
+import { existsSync as existsSync2 } from "fs";
+import { resolve } from "path";
+var CANDIDATE_FILES = [
+  "src/mdx-components.ts",
+  "src/mdx-components.js",
+  "src/mdx-components.mjs"
 ];
+var VIRTUAL_ID = "virtual:book-scaffold/mdx-components";
+var RESOLVED_ID = "\0" + VIRTUAL_ID;
+function resolveMdxComponentsPath(consumerRoot, explicit) {
+  if (explicit) {
+    const p = resolve(consumerRoot, explicit);
+    return existsSync2(p) ? p : null;
+  }
+  for (const candidate of CANDIDATE_FILES) {
+    const p = resolve(consumerRoot, candidate);
+    if (existsSync2(p)) return p;
+  }
+  return null;
+}
+function makeMdxComponentsVitePlugin(consumerPath) {
+  return {
+    name: "book-scaffold:mdx-components",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+      return null;
+    },
+    load(id) {
+      if (id !== RESOLVED_ID) return null;
+      if (consumerPath === null) {
+        return "export default {};";
+      }
+      return `export { default } from ${JSON.stringify(consumerPath)};`;
+    }
+  };
+}
+function defineMdxComponents(components) {
+  return components;
+}
+
+// src/integration.ts
+var PACKAGE_NAME = "@brandon_m_behring/book-scaffold-astro";
+var ROUTE_REGISTRY = {
+  references: { pattern: "/references", file: "references.astro" },
+  search: { pattern: "/search", file: "search.astro" },
+  print: { pattern: "/print", file: "print.astro" },
+  chapters: { pattern: "/chapters", file: "chapters.astro" },
+  convergence: { pattern: "/convergence", file: "convergence.astro" },
+  // v3.4.0 (#7): consumer-collection-backed frontmatter route. Opt-in via
+  // routes: { frontmatter: true } AND content.config.ts defining the
+  // collection (use frontmatterCollection() helper from /schemas subpath).
+  frontmatter: { pattern: "/frontmatter/[slug]", file: "frontmatter/[...slug].astro" }
+};
 function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
 }
 function bookScaffoldIntegration(opts) {
-  const { profile, extraStyles = [] } = opts;
+  const { profile, routes: userOverrides = {}, extraStyles = [], mdxComponentsModule } = opts;
+  const def = PROFILES[profile];
+  const enabledRoutes = { ...def.routes, ...userOverrides };
   return {
     name: "book-scaffold-astro",
     hooks: {
-      "astro:config:setup": ({ injectScript, injectRoute }) => {
-        const styles = profile === "tools" ? [...ALWAYS_ON_STYLES, ...TOOLS_ONLY_STYLES, ...extraStyles] : [...ALWAYS_ON_STYLES, ...extraStyles];
+      "astro:config:setup": ({ injectScript, injectRoute, updateConfig, config }) => {
+        const styles = [...def.styles, ...extraStyles];
         for (const sheet of styles) {
           injectScript("page-ssr", `import '${PACKAGE_NAME}/styles/${sheet}';`);
         }
-        if (profile === "academic") {
+        if (def.katex) {
           injectScript("page-ssr", "import 'katex/dist/katex.min.css';");
         }
-        const routes = profile === "tools" ? [...DEFAULT_ROUTES_ALL, ...DEFAULT_ROUTES_TOOLS] : [...DEFAULT_ROUTES_ALL];
-        for (const route of routes) {
+        for (const [name, on] of Object.entries(enabledRoutes)) {
+          if (!on) continue;
+          const route = ROUTE_REGISTRY[name];
+          if (!route) continue;
           injectRoute({
             pattern: route.pattern,
             entrypoint: resolvePage(route.file)
           });
         }
+        const consumerRoot = fileURLToPath(config.root);
+        const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
+        const presetLiteral = JSON.stringify(profile);
+        updateConfig({
+          vite: {
+            plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)],
+            define: {
+              "import.meta.env.BOOK_PRESET": presetLiteral,
+              "import.meta.env.BOOK_PROFILE": presetLiteral
+            }
+          }
+        });
       }
     }
   };
@@ -220,7 +500,7 @@ function bookScaffoldIntegration(opts) {
 
 // src/config.ts
 async function defineBookConfig(opts) {
-  const profile = resolveProfile(opts.profile);
+  const profile = resolvePreset(opts.preset, opts.profile);
   const remarkPlugins = [];
   const rehypePlugins = [];
   if (profile === "academic") {
@@ -249,7 +529,14 @@ async function defineBookConfig(opts) {
   const integrations = [
     mdx(),
     preact(),
-    bookScaffoldIntegration({ profile, extraStyles: opts.extraStyles }),
+    bookScaffoldIntegration({
+      profile,
+      routes: opts.routes,
+      // v3.3.0 — per-route override (issue #3)
+      mdxComponentsModule: opts.mdxComponentsModule,
+      // v3.3.0 — explicit mdx-components path (issue #2)
+      extraStyles: opts.extraStyles
+    }),
     ...opts.extraIntegrations ?? []
   ];
   const userMarkdown = opts.markdown ?? {};
@@ -266,13 +553,22 @@ async function defineBookConfig(opts) {
     ...userMarkdown
   };
   const {
+    preset: _preset,
+    // v3.4.0
     profile: _profile,
+    routes: _routes,
+    // v3.3.0
+    mdxComponentsModule: _mdxComponentsModule,
+    // v3.3.0
     extraIntegrations: _extraIntegrations,
     extraStyles: _extraStyles,
     markdown: _markdown,
     ...rest
   } = opts;
+  void _preset;
   void _profile;
+  void _routes;
+  void _mdxComponentsModule;
   void _extraIntegrations;
   void _extraStyles;
   void _markdown;
@@ -293,110 +589,41 @@ async function defineBookConfig(opts) {
   return config;
 }
 
-// src/schemas.ts
-import { z } from "astro/zod";
-var toolSlugs = [
-  "claude-code",
-  "gemini-cli",
-  "codex-cli",
-  "cross-tool"
-];
-var volatilityLevels = [
-  "stable-principle",
-  "architectural-pattern",
-  "feature-surface"
-];
-var sourceTiers = [
-  "T1-official",
-  "T2-release-notes",
-  "T3-practitioner",
-  "T4-conjecture"
-];
-var changeKinds = ["added", "removed", "changed", "deprecated"];
-var patternCategories = [
-  "safety",
-  "scale",
-  "context",
-  "interaction",
-  "extension",
-  "other"
-];
-var academicParts = [
-  "foundations",
-  "ssm-core",
-  "beyond-ssm",
-  "integration",
-  "synthesis"
-];
-var chapterStatus = [
-  "implemented",
-  "chapter_only",
-  "reading_only",
-  "prose_only",
-  "code_only",
-  "scaffolded",
-  "planned"
-];
-var 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)
-});
-var 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()
-});
-var 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()
-});
-var 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([])
-});
-var patternsSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().optional(),
-  category: z.enum(patternCategories).optional(),
-  convergence_date: z.date().nullable().optional()
-});
+// src/lib/freshness.ts
+var THRESHOLDS = {
+  "stable-principle": 365,
+  "architectural-pattern": 180,
+  "feature-surface": 90
+};
+var MS_PER_DAY = 1e3 * 60 * 60 * 24;
+function getFreshness(lastVerified, volatility, now = /* @__PURE__ */ new Date()) {
+  if (!(lastVerified instanceof Date)) return null;
+  const thresholdDays = THRESHOLDS[volatility];
+  const daysOld = Math.floor((now.getTime() - lastVerified.getTime()) / MS_PER_DAY);
+  const daysUntil = thresholdDays - daysOld;
+  let status;
+  if (daysOld < thresholdDays * 0.75) {
+    status = "fresh";
+  } else if (daysOld < thresholdDays) {
+    status = "verify-soon";
+  } else {
+    status = "stale";
+  }
+  return { status, daysOld, thresholdDays, daysUntil };
+}
+function freshnessLabel(f) {
+  if (f === null) return "Verification status unknown";
+  switch (f.status) {
+    case "fresh":
+      return `Fresh (${f.daysOld}d old; verify within ${f.daysUntil}d)`;
+    case "verify-soon":
+      return `Verify soon (${f.daysOld}d old; ${f.daysUntil}d until stale)`;
+    case "stale":
+      return `Stale (${f.daysOld}d old; ${Math.abs(f.daysUntil)}d past threshold)`;
+  }
+}
 export {
+  BOOK_PRESETS,
   BOOK_PROFILES,
   BookConfigError,
   academicChapterSchema,
@@ -405,9 +632,16 @@ export {
   changeKinds,
   changelogSchema,
   chapterStatus,
+  courseNotesChapterSchema,
   defineBookConfig,
+  defineMdxComponents,
+  defineProfile,
+  freshnessLabel,
+  getFreshness,
+  minimalChapterSchema,
   patternCategories,
   patternsSchema,
+  resolvePreset,
   resolveProfile,
   sourceTiers,
   sourcesSchema,

package/dist/schemas.d.ts

@@ -1,6 +1,40 @@
-import { e as BookSchemasOptions } from './types-BoCXCvBy.js';
+import { defineCollection } from 'astro:content';
+import { g as BookSchemasOptions } from './types-Bb97Na9S.js';
 import 'astro';
+import 'astro/zod';
 
+/**
+ * v3.4.0 (closes #7): consumer-facing helper to define a `frontmatter`
+ * content collection that the scaffold's auto-injected
+ * `/frontmatter/[slug]` route can render.
+ *
+ * Usage in consumer's content.config.ts:
+ *
+ *   import { defineBookSchemas, frontmatterCollection } from
+ *     '@brandon_m_behring/book-scaffold-astro/schemas';
+ *   import { z } from 'astro:content';
+ *
+ *   export const { collections } = {
+ *     collections: {
+ *       ...defineBookSchemas().collections,
+ *       frontmatter: frontmatterCollection(z.object({
+ *         slug: z.string(),
+ *         title: z.string(),
+ *         order: z.number(),
+ *         description: z.string().optional(),
+ *       })),
+ *     },
+ *   };
+ *
+ * Then enable the route via `defineBookConfig({ routes: { frontmatter: true } })`
+ * and drop MDX files under `src/content/frontmatter/`. The scaffold-injected
+ * route renders each entry with the consumer's mdx-components in scope (issue #2
+ * plumbing applies).
+ *
+ * Default loader: `**\/*.{md,mdx}` under `./src/content/frontmatter` (excluding
+ * underscore-prefixed files). Override `base` via the second arg.
+ */
+declare function frontmatterCollection(schema: Parameters<typeof defineCollection>[0]['schema'], base?: string): unknown;
 /**
  * Returns the package's default content collections. Closed shape per Q5;
  * consumer extends via object spread and Zod `.extend()` (see PACKAGE_DESIGN.md §5).
@@ -9,4 +43,4 @@ declare function defineBookSchemas(opts?: BookSchemasOptions): {
     collections: Record<string, unknown>;
 };
 
-export { defineBookSchemas };
+export { defineBookSchemas, frontmatterCollection };