@ibalzam/codejitsu-core 0.1.0 → 0.2.0

package/modules/blog/CLAUDE.md

@@ -1,87 +1,140 @@
 # Blog module — instructions for Claude
 
-When the user asks to **implement codejitsu/core/blog** (or "add the blog system"), do the following.
+When the user asks to **implement codejitsu/core/blog** (or "add the blog system", "wire up the blog"), do the following.
 
 ## What this module provides
 
-A markdown-based blog with:
-- File-based posts in `content/blog/*.md` (gray-matter frontmatter)
-- Scheduled publishing — future-dated posts are hidden from public pages and sitemap, but their slugs stay buildable so OG meta scrapers (Hootsuite, etc.) can hit them
-- Dual-slug resolution — filename slug (`2026-02-08-foo`) and canonical frontmatter slug (`foo`) both resolve to the same post; the frontmatter slug is canonical for SEO
-- Reading time, tags, FAQs, categories
-- Listing, tag, category pages
+A markdown blog with two loader variants — pick whichever fits the project:
 
-## Wiring it into a site
+- **`createBlogFromCollection`** — uses Astro Content Collections. **Use this for any Astro site.** Type-safe via the collection's Zod schema, schema-validated, HMR works.
+- **`createBlog`** — reads `content/blog/*.md` via gray-matter directly. Use for non-Astro projects or when CC isn't an option.
 
-### 1. Install peer deps in the site (one-time)
+Both variants return the same `BlogAPI`:
 
-```bash
-npm install gray-matter reading-time
+```ts
+getAllPosts()                  // Published posts (date <= today, not draft). Sorted newest first.
+getAllPostsIncludingFuture()   // All non-draft posts.
+getFutureBlogSlugs()           // Slugs of future-dated drafts (for sitemap exclusion).
+getAllPostSlugs()              // Every slug for getStaticPaths (includes future, excludes drafts).
+getPostBySlug(slug)            // Resolves filename-slug OR canonical (frontmatter) slug.
+getAllTags() / getPostsByTag(tag)
+getAllCategorySlugs() / getCategoryBySlug(slug) / getPostsByCategory(slug)
 ```
-(They're transitive deps of `@ibalzam/codejitsu-core`, but Astro's bundler resolves them from the site's `node_modules`.)
 
-### 2. Create the site's blog instance
+## Wiring into an Astro site
 
-Copy `templates/lib/blog.ts` → `src/lib/blog.ts` in the site. Edit the config to set the site's default author and (optionally) its category list. The whole file is ~10 lines.
+### 1. Set up the Content Collection
 
-### 3. Add page routes
+```ts
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    pubDate: z.coerce.date(),      // ← date field; configure dateField to match
+    updatedDate: z.coerce.date().optional(),
+    author: z.string().default('editor'),
+    image: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+    draft: z.boolean().default(false),
+    faqs: z.array(z.object({
+      question: z.string(),
+      answer: z.string(),
+    })).optional(),
+  }),
+});
+
+export const collections = { blog };
+```
 
-Copy these from `templates/pages/` → `src/pages/` in the site:
-- `blog/index.astro` — listing
-- `blog/[...slug].astro` — detail (handles both filename and canonical slug forms)
-- `blog/tag/[tag].astro` — tag pages
-- `blog/category/[category].astro` — category pages (skip if site has no categories)
+### 2. Configure in `codejitsu.config.ts`
 
-Adapt the markup to the site's design system. The page logic (data fetching, getStaticPaths) is the part that must stay correct — styling is the site's job.
+```ts
+import { defineConfig } from '@ibalzam/codejitsu-core/config';
+
+export default defineConfig({
+  site: { url: '...', name: '...', defaultAuthor: 'editor' },
+  blog: {
+    mode: 'collection',
+    collectionName: 'blog',
+    dateField: 'pubDate',          // matches the CC schema field
+    draftField: 'draft',
+    // categories: [...]            // optional
+  },
+});
+```
 
-### 4. Add the first post
+### 3. Create the loader
 
-Copy `templates/content/_sample-post.md` → `content/blog/<today>-<slug>.md` and edit.
+```ts
+// src/lib/blog.ts
+import { createBlogFromCollection } from '@ibalzam/codejitsu-core/blog';
+
+export const blog = createBlogFromCollection({
+  collectionName: 'blog',
+  dateField: 'pubDate',
+  draftField: 'draft',
+  defaultAuthor: 'editor',
+});
+```
+
+### 4. Use in pages
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import { blog } from '~/lib/blog';
+
+export async function getStaticPaths() {
+  const slugs = await blog.getAllPostSlugs();  // includes future-dated for OG scrapers
+  return slugs.map((slug) => ({ params: { slug } }));
+}
+
+const post = await blog.getPostBySlug(Astro.params.slug as string);
+if (!post) return Astro.redirect('/404');
+---
+```
 
 ### 5. Wire scheduled-post filter into the sitemap
 
-In `astro.config.mjs`, import the site's blog instance and exclude future-dated slugs from the sitemap:
+In `astro.config.mjs`, get future slugs from the blog instance and pass to the sitemap's `excludeFuturePosts` filter:
 
 ```ts
 import { blog } from './src/lib/blog';
+import { excludeFuturePosts, defaultPriorityRules } from '@ibalzam/codejitsu-core/seo/sitemap';
+
 const futureSlugs = await blog.getFutureBlogSlugs();
 
-// in sitemap integration:
-filter: (page) => {
-  const m = page.match(/\/blog\/([^/]+)\/?$/);
-  return !(m && futureSlugs.includes(m[1]));
-}
+sitemap({
+  filter: excludeFuturePosts(futureSlugs),
+  serialize: defaultPriorityRules(SITE),
+});
 ```
 
-### 6. Wire the daily-deploy GH Action
+## Frontmatter shape
 
-See `modules/deploy/CLAUDE.md`. The cron rebuilds the site so scheduled posts graduate from hidden to public on their publish date.
+Required: `title`, `description`, date (default field name `date`, configurable via `dateField`).
+Recommended: `image`, `tags`, `author`.
+Optional: `slug` (canonical override), `faqs`, `draft`, `updatedDate`.
 
-## Post frontmatter shape
+Field names are flexible — set `dateField` and `draftField` in your CC schema and they'll flow through.
 
-```yaml
----
-title: "How to size a furnace"            # required
-description: "Quick guide to BTU sizing"  # required (used as meta description)
-date: 2026-03-15                          # required; future date = hidden until that day
-slug: how-to-size-a-furnace               # optional; if set, this is the canonical URL
-author: "Pearl Remodeling"                # optional; falls back to defaultAuthor in config
-image: /images/blog/furnace-sizing.webp   # optional; used for OG + listing card
-tags: [HVAC, Heating, Guides]             # optional
-faqs:                                      # optional; rendered as FAQ schema + section
-  - question: "What BTU do I need?"
-    answer: "Roughly 30 BTU per sq ft as a starting point..."
----
-```
+## Dual-slug behavior
+
+If a post's frontmatter has `slug: 'short-form'` and its filename is `2026-02-08-long-form.md`, **both URLs resolve to the same post** but `slug` (frontmatter) is canonical. This lets you ship short URLs while keeping date-prefixed URLs alive. Set `<link rel="canonical">` to the frontmatter slug.
 
 ## What must NOT be done
 
-- **Don't reimplement the loader.** Always import from `@ibalzam/codejitsu-core/blog` via the site's `src/lib/blog.ts`.
-- **Don't bypass `getAllPosts()` for the listing.** It's already filtering future-dated posts; bypassing means drafts leak.
-- **Don't add `getStaticPaths` that calls `getAllPosts()` alone for the detail page** — it'll exclude future-dated posts and break OG scraping for scheduled releases. Use `getAllPostSlugs()` for path generation.
-- **Don't put `.mdx` files in `content/blog/`.** The loader is `.md` only. If MDX support is needed, raise it as a feature request — it's a deliberate scope decision.
-- **Don't change the dual-slug resolution.** Old date-prefixed URLs must keep working alongside short canonical slugs.
+- **Don't use `createBlog` (fs mode) in an Astro project.** You lose schema validation, HMR, type safety. Always prefer `createBlogFromCollection`.
+- **Don't bypass `getAllPosts()` for the listing.** It filters future-dated and drafts; bypassing leaks drafts.
+- **Don't use `getAllPosts()` for `getStaticPaths`** — use `getAllPostSlugs()` so future-dated posts stay buildable (OG scrapers need to reach them before publish day).
+- **Don't read the collection directly** (e.g. `await getCollection('blog')`) in pages. Use the `blog` instance from `src/lib/blog.ts` so filtering/sorting/date logic stays in one place.
+- **Don't change `dateField` mid-project** without renaming the frontmatter field in every existing post.
 
 ## Verify
 
-Run `modules/blog/checklist.md` after wiring. Run `checklist/core.md` (sitewide).
+Run `modules/blog/checklist.md` after wiring.

package/modules/blog/src/collection.ts

@@ -0,0 +1,176 @@
+import readingTime from 'reading-time';
+import type {
+  BlogAPI,
+  BlogCategory,
+  BlogPost,
+  BlogPostMetadata,
+  CommonBlogConfig,
+} from './types.js';
+
+export interface CollectionBlogConfig extends CommonBlogConfig {
+  /** Astro Content Collection name. Default 'blog'. */
+  collectionName?: string;
+}
+
+/** Minimal shape of an Astro CollectionEntry that we depend on. */
+interface AstroCollectionEntry {
+  id: string;
+  slug: string;
+  data: Record<string, unknown>;
+  body: string;
+}
+
+function getTodayUTC(): Date {
+  const now = new Date();
+  return new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+}
+
+function asISO(value: unknown): string {
+  if (value instanceof Date) return value.toISOString().split('T')[0];
+  if (typeof value === 'string') return value;
+  return '';
+}
+
+/**
+ * Astro Content Collections blog loader. Use this in Astro projects.
+ *
+ * Dynamically imports `astro:content` at call time so the rest of this package
+ * stays usable in non-Astro environments. Throws a clear error if Astro is missing.
+ */
+export function createBlogFromCollection(config: CollectionBlogConfig = {}): BlogAPI {
+  const collectionName = config.collectionName ?? 'blog';
+  const defaultAuthor = config.defaultAuthor;
+  const categories = config.categories ?? [];
+  const dateField = config.dateField ?? 'date';
+  const draftField = config.draftField ?? null;
+
+  async function getCollection(): Promise<AstroCollectionEntry[]> {
+    let mod: { getCollection: (name: string) => Promise<AstroCollectionEntry[]> };
+    try {
+      // @ts-expect-error - 'astro:content' is a virtual module resolved by Astro at build time.
+      mod = await import('astro:content');
+    } catch (err) {
+      throw new Error(
+        `createBlogFromCollection() requires Astro and a configured content collection ` +
+          `named '${collectionName}'. Add Astro to the project or use createBlog() (fs+gray-matter) instead. ` +
+          `Original error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return mod.getCollection(collectionName);
+  }
+
+  async function readAll(): Promise<AstroCollectionEntry[]> {
+    const all = await getCollection();
+    if (!draftField) return all;
+    return all.filter((e) => !e.data[draftField]);
+  }
+
+  function toMetadata(e: AstroCollectionEntry): BlogPostMetadata {
+    const canonicalSlug = (e.data.slug as string | undefined) || e.slug;
+    return {
+      slug: canonicalSlug,
+      title: (e.data.title as string) ?? '',
+      description: (e.data.description as string) ?? '',
+      date: asISO(e.data[dateField]),
+      author: (e.data.author as string) ?? defaultAuthor,
+      image: e.data.image as string | undefined,
+      tags: e.data.tags as string[] | undefined,
+      readingTime: readingTime(e.body).text,
+    };
+  }
+
+  async function getAllPostsIncludingFuture(): Promise<BlogPostMetadata[]> {
+    const entries = await readAll();
+    return entries
+      .map(toMetadata)
+      .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+  }
+
+  async function getAllPosts(): Promise<BlogPostMetadata[]> {
+    const today = getTodayUTC();
+    const all = await getAllPostsIncludingFuture();
+    return all.filter((p) => new Date(p.date) <= today);
+  }
+
+  async function getFutureBlogSlugs(): Promise<string[]> {
+    const today = getTodayUTC();
+    const entries = await readAll();
+    const slugs = new Set<string>();
+    for (const e of entries) {
+      const date = asISO(e.data[dateField]);
+      if (!date) continue;
+      if (new Date(date) > today) {
+        const canonical = (e.data.slug as string | undefined) || e.slug;
+        slugs.add(canonical);
+        if (e.slug !== canonical) slugs.add(e.slug);
+      }
+    }
+    return Array.from(slugs);
+  }
+
+  async function getAllPostSlugs(): Promise<string[]> {
+    const entries = await readAll();
+    const slugs = new Set<string>();
+    for (const e of entries) {
+      slugs.add(e.slug);
+      const canonical = (e.data.slug as string | undefined) || e.slug;
+      if (canonical !== e.slug) slugs.add(canonical);
+    }
+    return Array.from(slugs);
+  }
+
+  async function getPostBySlug(slug: string): Promise<BlogPost | null> {
+    const entries = await readAll();
+    const match = entries.find((e) => {
+      const canonical = (e.data.slug as string | undefined) || e.slug;
+      return canonical === slug || e.slug === slug;
+    });
+    if (!match) return null;
+    return {
+      ...toMetadata(match),
+      faqs: match.data.faqs as BlogPost['faqs'],
+      content: match.body,
+    };
+  }
+
+  async function getAllTags(): Promise<string[]> {
+    const posts = await getAllPosts();
+    const tags = new Set<string>();
+    posts.forEach((p) => p.tags?.forEach((t) => tags.add(t)));
+    return Array.from(tags).sort();
+  }
+
+  async function getPostsByTag(tag: string): Promise<BlogPostMetadata[]> {
+    const posts = await getAllPosts();
+    return posts.filter((p) => p.tags?.includes(tag));
+  }
+
+  function getAllCategorySlugs(): string[] {
+    return categories.map((c) => c.slug);
+  }
+
+  function getCategoryBySlug(slug: string): BlogCategory | undefined {
+    return categories.find((c) => c.slug === slug);
+  }
+
+  async function getPostsByCategory(slug: string): Promise<BlogPostMetadata[]> {
+    const cat = getCategoryBySlug(slug);
+    if (!cat) return [];
+    const posts = await getAllPosts();
+    return posts.filter((p) => p.tags?.includes(cat.tag));
+  }
+
+  return {
+    getAllPosts,
+    getAllPostsIncludingFuture,
+    getFutureBlogSlugs,
+    getAllPostSlugs,
+    getPostBySlug,
+    getAllTags,
+    getPostsByTag,
+    getAllCategorySlugs,
+    getCategoryBySlug,
+    getPostsByCategory,
+    categories,
+  };
+}

package/modules/blog/src/fs.ts

@@ -0,0 +1,167 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import readingTime from 'reading-time';
+import type {
+  BlogAPI,
+  BlogCategory,
+  BlogPost,
+  BlogPostMetadata,
+  CommonBlogConfig,
+} from './types.js';
+
+export interface FsBlogConfig extends CommonBlogConfig {
+  /** Directory of .md files (relative to cwd). Default 'content/blog'. */
+  contentDir?: string;
+}
+
+function getTodayUTC(): Date {
+  const now = new Date();
+  return new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+}
+
+function fileSlug(name: string): string {
+  return name.replace(/\.md$/, '');
+}
+
+function asISO(value: unknown): string {
+  if (value instanceof Date) return value.toISOString().split('T')[0];
+  if (typeof value === 'string') return value;
+  return '';
+}
+
+/**
+ * Markdown + gray-matter blog loader. Reads .md files directly from disk.
+ * Use this for non-Astro projects, or Astro projects that don't want Content Collections.
+ *
+ * For Astro projects with Content Collections (recommended), use `createBlogFromCollection`.
+ */
+export function createBlog(config: FsBlogConfig = {}): BlogAPI {
+  const contentDir = path.resolve(process.cwd(), config.contentDir ?? 'content/blog');
+  const defaultAuthor = config.defaultAuthor;
+  const categories = config.categories ?? [];
+  const dateField = config.dateField ?? 'date';
+  const draftField = config.draftField ?? null;
+
+  function readAllFiles() {
+    if (!fs.existsSync(contentDir)) return [];
+    return fs
+      .readdirSync(contentDir)
+      .filter((n) => n.endsWith('.md'))
+      .map((fileName) => {
+        const raw = fs.readFileSync(path.join(contentDir, fileName), 'utf8');
+        const parsed = matter(raw);
+        const data = parsed.data as Record<string, unknown>;
+        const slug = (data.slug as string | undefined) || fileSlug(fileName);
+        return {
+          fileName,
+          fileSlug: fileSlug(fileName),
+          canonicalSlug: slug,
+          data,
+          content: parsed.content,
+        };
+      })
+      .filter((f) => (draftField ? !f.data[draftField] : true));
+  }
+
+  function toMetadata(f: ReturnType<typeof readAllFiles>[number]): BlogPostMetadata {
+    return {
+      slug: f.canonicalSlug,
+      title: (f.data.title as string) ?? '',
+      description: (f.data.description as string) ?? '',
+      date: asISO(f.data[dateField]),
+      author: (f.data.author as string) ?? defaultAuthor,
+      image: f.data.image as string | undefined,
+      tags: f.data.tags as string[] | undefined,
+      readingTime: readingTime(f.content).text,
+    };
+  }
+
+  async function getAllPostsIncludingFuture(): Promise<BlogPostMetadata[]> {
+    return readAllFiles()
+      .map(toMetadata)
+      .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+  }
+
+  async function getAllPosts(): Promise<BlogPostMetadata[]> {
+    const today = getTodayUTC();
+    const all = await getAllPostsIncludingFuture();
+    return all.filter((p) => new Date(p.date) <= today);
+  }
+
+  async function getFutureBlogSlugs(): Promise<string[]> {
+    const today = getTodayUTC();
+    const slugs = new Set<string>();
+    for (const f of readAllFiles()) {
+      const date = asISO(f.data[dateField]);
+      if (!date) continue;
+      if (new Date(date) > today) {
+        slugs.add(f.canonicalSlug);
+        if (f.fileSlug !== f.canonicalSlug) slugs.add(f.fileSlug);
+      }
+    }
+    return Array.from(slugs);
+  }
+
+  async function getAllPostSlugs(): Promise<string[]> {
+    const slugs = new Set<string>();
+    for (const f of readAllFiles()) {
+      slugs.add(f.fileSlug);
+      if (f.canonicalSlug !== f.fileSlug) slugs.add(f.canonicalSlug);
+    }
+    return Array.from(slugs);
+  }
+
+  async function getPostBySlug(slug: string): Promise<BlogPost | null> {
+    const match = readAllFiles().find(
+      (f) => f.canonicalSlug === slug || f.fileSlug === slug
+    );
+    if (!match) return null;
+    return {
+      ...toMetadata(match),
+      faqs: match.data.faqs as BlogPost['faqs'],
+      content: match.content,
+    };
+  }
+
+  async function getAllTags(): Promise<string[]> {
+    const posts = await getAllPosts();
+    const tags = new Set<string>();
+    posts.forEach((p) => p.tags?.forEach((t) => tags.add(t)));
+    return Array.from(tags).sort();
+  }
+
+  async function getPostsByTag(tag: string): Promise<BlogPostMetadata[]> {
+    const posts = await getAllPosts();
+    return posts.filter((p) => p.tags?.includes(tag));
+  }
+
+  function getAllCategorySlugs(): string[] {
+    return categories.map((c) => c.slug);
+  }
+
+  function getCategoryBySlug(slug: string): BlogCategory | undefined {
+    return categories.find((c) => c.slug === slug);
+  }
+
+  async function getPostsByCategory(slug: string): Promise<BlogPostMetadata[]> {
+    const cat = getCategoryBySlug(slug);
+    if (!cat) return [];
+    const posts = await getAllPosts();
+    return posts.filter((p) => p.tags?.includes(cat.tag));
+  }
+
+  return {
+    getAllPosts,
+    getAllPostsIncludingFuture,
+    getFutureBlogSlugs,
+    getAllPostSlugs,
+    getPostBySlug,
+    getAllTags,
+    getPostsByTag,
+    getAllCategorySlugs,
+    getCategoryBySlug,
+    getPostsByCategory,
+    categories,
+  };
+}