@ibalzam/codejitsu-core 0.2.0 → 0.3.0

package/MIGRATIONS/0.3.0.md

@@ -0,0 +1,66 @@
+# 0.3.0 — Blog CC API returns entries
+
+## Summary
+
+`createBlogFromCollection` now returns raw `CollectionEntry[]` (with filtering applied) instead of normalized `BlogPostMetadata[]` objects. This preserves access to `entry.data`, `entry.id`, and the ability to call `render(entry)` for `<Content />` — matching what Astro CC consumers actually need.
+
+Breaking change to the CC variant only. The fs variant (`createBlog`) is unchanged.
+
+## Required actions
+
+### If you weren't using `createBlogFromCollection` yet
+
+No action needed. The fs variant (`createBlog`) is unchanged.
+
+### If you were using `createBlogFromCollection`
+
+The method names changed and the return shape is now `CollectionEntry[]` instead of `BlogPostMetadata[]`. Map your calls:
+
+| v0.2.x | v0.3.0 |
+|---|---|
+| `getAllPosts()` | `getPublishedEntries()` |
+| `getAllPostsIncludingFuture()` | `getAllEntries()` |
+| `getPostBySlug(slug)` | `getEntryBySlug(slug)` |
+| `getPostsByTag(tag)` | `getEntriesByTag(tag)` |
+| `getPostsByCategory(slug)` | `getEntriesByCategory(slug)` |
+| `getFutureBlogSlugs()` | (unchanged) |
+| `getAllPostSlugs()` | (unchanged) |
+| `getAllTags()` | (unchanged) |
+
+The returned entries now have raw shape: `entry.id`, `entry.data.<field>`, `entry.body`. Use `astro:content`'s `render(entry)` to get `<Content />` for markdown rendering.
+
+If you want the old normalized shape for some specific use (e.g. listing cards that don't need `render()`), pass entries through `blog.toMetadata(entry)`:
+
+```ts
+const entries = await blog.getPublishedEntries();
+const cards = entries.map((e) => blog.toMetadata(e));
+```
+
+### Type-safe entries
+
+Pass your `CollectionEntry<'name'>` as a generic for full typing:
+
+```ts
+import type { CollectionEntry } from 'astro:content';
+import { createBlogFromCollection } from '@ibalzam/codejitsu-core/blog';
+
+export const blog = createBlogFromCollection<CollectionEntry<'blog'>>({
+  collectionName: 'blog',
+  dateField: 'pubDate',
+  draftField: 'draft',
+});
+```
+
+## Why
+
+v0.2.x's normalized API was modeled on the workzen (Next.js) blog and didn't fit Astro's CC pattern. Astro pages need `entry.data.faqs`, `entry.data.updatedDate`, `await render(entry)` — none of which the normalized objects exposed. Sites kept their homegrown CC loaders because the package's CC variant was unusable. v0.3.0 fixes that.
+
+## Verify
+
+```bash
+npm update @ibalzam/codejitsu-core
+npm run build
+npx codejitsu-check
+```
+
+If pages reference `post.slug` / `post.title` (normalized fields), they need to be updated to `entry.id` / `entry.data.title`. The TypeScript compiler will flag these.

package/checklist/bin/run.mjs

@@ -11,7 +11,7 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { loadConfig, isModuleEnabled } from '../../modules/config/src/load.js';
+import { loadConfig, isModuleEnabled } from '../../modules/config/src/load.mjs';
 
 const cwd = process.cwd();
 const distDir = path.join(cwd, 'dist');
@@ -163,7 +163,9 @@ const webpSet = new Set();
   }
 })(distDir);
 
-const PLACEHOLDER_RE = /\b(lorem ipsum|TODO|FIXME|XXX:|placeholder)\b/i;
+// Matches actual placeholder *content*, not CSS ::placeholder or HTML
+// placeholder="..." attributes (both legitimate).
+const PLACEHOLDER_RE = /\b(lorem ipsum|TODO:|FIXME:|XXX:)\b/i;
 
 for (const file of htmlFiles) {
   const rel = path.relative(distDir, file);

package/modules/blog/CLAUDE.md

@@ -1,32 +1,53 @@
 # Blog module — instructions for Claude
 
-When the user asks to **implement codejitsu/core/blog** (or "add the blog system", "wire up the blog"), do the following.
+When the user asks to **implement codejitsu/core/blog** (or "add the blog system"), do the following.
 
 ## What this module provides
 
-A markdown blog with two loader variants — pick whichever fits the project:
+Two loader variants:
 
-- **`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.
+- **`createBlogFromCollection`** — wraps Astro Content Collections. **Use this for any Astro site.** Returns raw `CollectionEntry` objects with filtering applied, preserving `entry.data`, `entry.id`, and the ability to call `render(entry)` for `<Content />`.
+- **`createBlog`** — fs + gray-matter loader. Use for non-Astro projects. Returns normalized `BlogPostMetadata` / `BlogPost` objects.
 
-Both variants return the same `BlogAPI`:
+The two return **different shapes** because they serve different needs:
+
+| | CC (`createBlogFromCollection`) | fs (`createBlog`) |
+|---|---|---|
+| Returns | `CollectionEntry[]` | `BlogPostMetadata[]` |
+| Access | `entry.data.title`, `entry.id`, `await render(entry)` | `post.title`, `post.slug`, `post.content` (raw md) |
+| Validation | Astro CC schema (Zod) | Frontmatter parsed by gray-matter, no validation |
+| HMR | Yes (Astro) | No |
+| Filter applied | draft + future-date | draft + future-date |
+| Sort | newest first | newest first |
+| Best for | Astro sites (most cases) | Non-Astro JS projects |
+
+## CC variant API
 
 ```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)
+const blog = createBlogFromCollection({
+  collectionName: 'blog',
+  dateField: 'pubDate',         // matches your CC schema field
+  draftField: 'draft',
+});
+
+await blog.getPublishedEntries();    // CollectionEntry[] — not draft, date <= today
+await blog.getAllEntries();          // CollectionEntry[] — not draft (includes future)
+await blog.getEntryBySlug(slug);     // CollectionEntry | null
+await blog.getFutureBlogSlugs();     // string[] — for sitemap exclusion
+await blog.getAllPostSlugs();        // string[] — for getStaticPaths
+await blog.getEntriesByTag(tag);     // CollectionEntry[]
+await blog.getAllTags();             // string[]
+await blog.getEntriesByCategory(s);  // CollectionEntry[]
+blog.toMetadata(entry);              // BlogPostMetadata — normalized derivation
 ```
 
 ## Wiring into an Astro site
 
 ### 1. Set up the Content Collection
 
+`src/content.config.ts`:
+
 ```ts
-// src/content.config.ts
 import { defineCollection, z } from 'astro:content';
 import { glob } from 'astro/loaders';
 
@@ -35,7 +56,7 @@ const blog = defineCollection({
   schema: z.object({
     title: z.string(),
     description: z.string(),
-    pubDate: z.coerce.date(),      // ← date field; configure dateField to match
+    pubDate: z.coerce.date(),
     updatedDate: z.coerce.date().optional(),
     author: z.string().default('editor'),
     image: z.string().optional(),
@@ -54,32 +75,30 @@ export const collections = { blog };
 ### 2. Configure in `codejitsu.config.ts`
 
 ```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
-  },
-});
+blog: {
+  mode: 'collection',
+  collectionName: 'blog',
+  dateField: 'pubDate',
+  draftField: 'draft',
+},
 ```
 
-### 3. Create the loader
+### 3. Create the loader instance
 
 ```ts
 // src/lib/blog.ts
+import type { CollectionEntry } from 'astro:content';
 import { createBlogFromCollection } from '@ibalzam/codejitsu-core/blog';
 
-export const blog = createBlogFromCollection({
+export const blog = createBlogFromCollection<CollectionEntry<'blog'>>({
   collectionName: 'blog',
   dateField: 'pubDate',
   draftField: 'draft',
-  defaultAuthor: 'editor',
 });
+
+// Backward-compat exports for sites migrating from a homegrown loader:
+export const getPublishedPosts = () => blog.getPublishedEntries();
+export const getAllPosts = () => blog.getAllEntries();
 ```
 
 ### 4. Use in pages
@@ -87,27 +106,36 @@ export const blog = createBlogFromCollection({
 ```astro
 ---
 // src/pages/blog/[slug].astro
+import { render } from 'astro:content';
 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 entries = await blog.getAllEntries();  // includes future-dated for OG scrapers
+  return entries.map((entry) => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
 }
 
-const post = await blog.getPostBySlug(Astro.params.slug as string);
-if (!post) return Astro.redirect('/404');
+const { entry } = Astro.props;
+const { Content } = await render(entry);
 ---
+<article>
+  <h1>{entry.data.title}</h1>
+  <Content />
+</article>
 ```
 
 ### 5. Wire scheduled-post filter into 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';
+// astro.config.mjs
+import { createBlog } from '@ibalzam/codejitsu-core/blog';
+import { excludeFuturePosts, defaultPriorityRules } from '@ibalzam/codejitsu-core/seo';
 
-const futureSlugs = await blog.getFutureBlogSlugs();
+// Use the fs loader here — astro.config runs before Astro's CC is initialized.
+const fsBlog = createBlog({ contentDir: 'src/content/blog', dateField: 'pubDate', draftField: 'draft' });
+const futureSlugs = await fsBlog.getFutureBlogSlugs();
 
 sitemap({
   filter: excludeFuturePosts(futureSlugs),
@@ -115,25 +143,13 @@ sitemap({
 });
 ```
 
-## Frontmatter shape
-
-Required: `title`, `description`, date (default field name `date`, configurable via `dateField`).
-Recommended: `image`, `tags`, `author`.
-Optional: `slug` (canonical override), `faqs`, `draft`, `updatedDate`.
-
-Field names are flexible — set `dateField` and `draftField` in your CC schema and they'll flow through.
-
-## 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 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.
+- **Don't use `createBlog` (fs) inside Astro pages.** You lose Astro's `render()` (needed for `<Content />`) and CC schema validation. Always prefer `createBlogFromCollection` in pages.
+- **Don't access raw `getCollection('blog')` directly.** Go through the blog instance from `src/lib/blog.ts` so filtering/sorting/date logic stays in one place.
+- **Don't use `getPublishedEntries()` for `getStaticPaths`** — use `getAllEntries()` so future-dated posts stay buildable (OG scrapers need to reach them before publish day).
+- **Don't change `dateField` mid-project** without renaming the frontmatter field in every existing post AND updating the CC schema field name to match.
+- **Don't rely on the CC variant's filtering for security.** A draft post's URL is still discoverable if anyone shares it. Use middleware/headers for true access control.
 
 ## Verify
 

package/modules/blog/src/collection.ts

@@ -1,8 +1,8 @@
 import readingTime from 'reading-time';
 import type {
-  BlogAPI,
   BlogCategory,
-  BlogPost,
+  BlogCollectionAPI,
+  BlogCollectionEntry,
   BlogPostMetadata,
   CommonBlogConfig,
 } from './types.js';
@@ -12,14 +12,6 @@ export interface CollectionBlogConfig extends CommonBlogConfig {
   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()));
@@ -31,118 +23,123 @@ function asISO(value: unknown): string {
   return '';
 }
 
+function asDate(value: unknown): Date | null {
+  if (value instanceof Date) return value;
+  if (typeof value === 'string') {
+    const d = new Date(value);
+    return Number.isNaN(d.valueOf()) ? null : d;
+  }
+  return null;
+}
+
 /**
  * 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.
+ * Returns raw CollectionEntry objects (preserving `entry.data`, `entry.id`,
+ * and the ability to call `render(entry)` from astro:content). Filtering and
+ * sorting are applied:
+ *   - Drafts excluded (when `draftField` is set)
+ *   - Sorted newest first by `dateField`
+ *   - `getPublishedEntries()` further excludes future-dated entries
+ *
+ * The collection's actual entry type is `CollectionEntry<'<name>'>` from
+ * `astro:content`. Pass it as the generic to get full typed `data`:
+ *
+ * ```ts
+ * import type { CollectionEntry } from 'astro:content';
+ * export const blog = createBlogFromCollection<CollectionEntry<'blog'>>({
+ *   collectionName: 'blog',
+ *   dateField: 'pubDate',
+ *   draftField: 'draft',
+ * });
+ * ```
+ *
+ * Dynamically imports `astro:content` at call time so the package stays
+ * usable in non-Astro projects.
  */
-export function createBlogFromCollection(config: CollectionBlogConfig = {}): BlogAPI {
+export function createBlogFromCollection<E extends BlogCollectionEntry = BlogCollectionEntry>(
+  config: CollectionBlogConfig = {}
+): BlogCollectionAPI<E> {
   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[]> };
+  async function getCollection(): Promise<E[]> {
+    let mod: { getCollection: (name: string) => Promise<E[]> };
     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)}`
+          `named '${collectionName}'. Original error: ${err instanceof Error ? err.message : String(err)}`
       );
     }
     return mod.getCollection(collectionName);
   }
 
-  async function readAll(): Promise<AstroCollectionEntry[]> {
+  async function readAll(): Promise<E[]> {
     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,
-    };
+    const filtered = draftField ? all.filter((e) => !e.data[draftField]) : all;
+    return filtered.sort((a, b) => {
+      const da = asDate(a.data[dateField])?.valueOf() ?? 0;
+      const db = asDate(b.data[dateField])?.valueOf() ?? 0;
+      return db - da;
+    });
   }
 
-  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 getAllEntries(): Promise<E[]> {
+    return readAll();
   }
 
-  async function getAllPosts(): Promise<BlogPostMetadata[]> {
+  async function getPublishedEntries(): Promise<E[]> {
     const today = getTodayUTC();
-    const all = await getAllPostsIncludingFuture();
-    return all.filter((p) => new Date(p.date) <= today);
+    const all = await readAll();
+    return all.filter((e) => {
+      const d = asDate(e.data[dateField]);
+      return d ? d <= today : true;
+    });
   }
 
   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);
+    const all = await readAll();
+    return all
+      .filter((e) => {
+        const d = asDate(e.data[dateField]);
+        return d ? d > today : false;
+      })
+      .map((e) => e.id);
   }
 
   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);
+    const all = await readAll();
+    return all.map((e) => e.id);
   }
 
-  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 getEntryBySlug(slug: string): Promise<E | null> {
+    const all = await readAll();
+    return all.find((e) => e.id === slug) ?? null;
   }
 
   async function getAllTags(): Promise<string[]> {
-    const posts = await getAllPosts();
+    const entries = await getPublishedEntries();
     const tags = new Set<string>();
-    posts.forEach((p) => p.tags?.forEach((t) => tags.add(t)));
+    entries.forEach((e) => {
+      const t = e.data.tags as string[] | undefined;
+      t?.forEach((tag) => tags.add(tag));
+    });
     return Array.from(tags).sort();
   }
 
-  async function getPostsByTag(tag: string): Promise<BlogPostMetadata[]> {
-    const posts = await getAllPosts();
-    return posts.filter((p) => p.tags?.includes(tag));
+  async function getEntriesByTag(tag: string): Promise<E[]> {
+    const entries = await getPublishedEntries();
+    return entries.filter((e) => {
+      const t = e.data.tags as string[] | undefined;
+      return t?.includes(tag);
+    });
   }
 
   function getAllCategorySlugs(): string[] {
@@ -153,24 +150,37 @@ export function createBlogFromCollection(config: CollectionBlogConfig = {}): Blo
     return categories.find((c) => c.slug === slug);
   }
 
-  async function getPostsByCategory(slug: string): Promise<BlogPostMetadata[]> {
+  async function getEntriesByCategory(slug: string): Promise<E[]> {
     const cat = getCategoryBySlug(slug);
     if (!cat) return [];
-    const posts = await getAllPosts();
-    return posts.filter((p) => p.tags?.includes(cat.tag));
+    return getEntriesByTag(cat.tag);
+  }
+
+  function toMetadata(entry: E): BlogPostMetadata {
+    return {
+      slug: entry.id,
+      title: (entry.data.title as string) ?? '',
+      description: (entry.data.description as string) ?? '',
+      date: asISO(entry.data[dateField]),
+      author: (entry.data.author as string) ?? defaultAuthor,
+      image: entry.data.image as string | undefined,
+      tags: entry.data.tags as string[] | undefined,
+      readingTime: readingTime(entry.body).text,
+    };
   }
 
   return {
-    getAllPosts,
-    getAllPostsIncludingFuture,
+    getPublishedEntries,
+    getAllEntries,
     getFutureBlogSlugs,
     getAllPostSlugs,
-    getPostBySlug,
+    getEntryBySlug,
     getAllTags,
-    getPostsByTag,
+    getEntriesByTag,
     getAllCategorySlugs,
     getCategoryBySlug,
-    getPostsByCategory,
+    getEntriesByCategory,
+    toMetadata,
     categories,
   };
 }

package/modules/blog/src/fs.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import matter from 'gray-matter';
 import readingTime from 'reading-time';
 import type {
-  BlogAPI,
+  BlogFsAPI,
   BlogCategory,
   BlogPost,
   BlogPostMetadata,
@@ -36,7 +36,7 @@ function asISO(value: unknown): string {
  *
  * For Astro projects with Content Collections (recommended), use `createBlogFromCollection`.
  */
-export function createBlog(config: FsBlogConfig = {}): BlogAPI {
+export function createBlog(config: FsBlogConfig = {}): BlogFsAPI {
   const contentDir = path.resolve(process.cwd(), config.contentDir ?? 'content/blog');
   const defaultAuthor = config.defaultAuthor;
   const categories = config.categories ?? [];

package/modules/blog/src/types.ts

@@ -13,10 +13,10 @@ export interface BlogPostFrontmatter {
   tags?: string[];
   faqs?: FAQItem[];
   draft?: boolean;
-  /** Additional fields. */
   [key: string]: unknown;
 }
 
+/** Normalized blog post (fs variant only). */
 export interface BlogPostMetadata {
   slug: string;
   title: string;
@@ -31,7 +31,7 @@ export interface BlogPostMetadata {
 
 export interface BlogPost extends BlogPostMetadata {
   faqs?: FAQItem[];
-  /** Raw markdown body (fs mode) or rendered HTML (CC mode). See per-function notes. */
+  /** Raw markdown body. */
   content: string;
 }
 
@@ -43,14 +43,34 @@ export interface BlogCategory {
   metaDescription: string;
 }
 
-export interface BlogAPI {
-  /** Published posts only (date <= today, not draft). Sorted newest first. */
+export interface CommonBlogConfig {
+  defaultAuthor?: string;
+  categories?: BlogCategory[];
+  /** Frontmatter field name for the date. Default 'date'. */
+  dateField?: string;
+  /** Frontmatter field name for the draft flag. Default null (no draft support). */
+  draftField?: string | null;
+}
+
+/**
+ * Minimal shape of an Astro CollectionEntry that the package depends on.
+ * In modern Astro (5+ with the glob loader), `id` is the slug (filename minus
+ * extension). `data` is the parsed frontmatter. `body` is the raw markdown.
+ *
+ * Sites can cast this to `CollectionEntry<'blog'>` from `astro:content` at use
+ * site to get full type information from their CC schema.
+ */
+export interface BlogCollectionEntry {
+  id: string;
+  data: Record<string, unknown>;
+  body: string;
+}
+
+/** API for the fs (gray-matter) blog loader — normalized objects. */
+export interface BlogFsAPI {
   getAllPosts(): Promise<BlogPostMetadata[]>;
-  /** All non-draft posts including future-dated ones. Sorted newest first. */
   getAllPostsIncludingFuture(): Promise<BlogPostMetadata[]>;
-  /** Slugs of non-draft posts with a future date. */
   getFutureBlogSlugs(): Promise<string[]>;
-  /** Every slug needed for static path generation (includes future-dated, excludes drafts). */
   getAllPostSlugs(): Promise<string[]>;
   getPostBySlug(slug: string): Promise<BlogPost | null>;
   getAllTags(): Promise<string[]>;
@@ -61,11 +81,27 @@ export interface BlogAPI {
   categories: BlogCategory[];
 }
 
-export interface CommonBlogConfig {
-  defaultAuthor?: string;
-  categories?: BlogCategory[];
-  /** Frontmatter field name for the date. Default 'date'. */
-  dateField?: string;
-  /** Frontmatter field name for the draft flag. Default null (no draft support). */
-  draftField?: string | null;
+/**
+ * API for the Astro Content Collections blog loader — raw entries.
+ * Preserves full access to entry.data, entry.id, and Astro's `render()`.
+ * Filtering (draft + future-date) is applied; sorting is newest-first by `dateField`.
+ */
+export interface BlogCollectionAPI<E extends BlogCollectionEntry = BlogCollectionEntry> {
+  /** Published entries: not draft, date <= today. Sorted newest first. */
+  getPublishedEntries(): Promise<E[]>;
+  /** All non-draft entries (includes future-dated). Sorted newest first. */
+  getAllEntries(): Promise<E[]>;
+  /** Slugs of non-draft entries with a future date. */
+  getFutureBlogSlugs(): Promise<string[]>;
+  /** Every slug needed for static path generation (non-draft, includes future). */
+  getAllPostSlugs(): Promise<string[]>;
+  getEntryBySlug(slug: string): Promise<E | null>;
+  getAllTags(): Promise<string[]>;
+  getEntriesByTag(tag: string): Promise<E[]>;
+  getAllCategorySlugs(): string[];
+  getCategoryBySlug(slug: string): BlogCategory | undefined;
+  getEntriesByCategory(slug: string): Promise<E[]>;
+  /** Convert a CollectionEntry into a normalized BlogPostMetadata. */
+  toMetadata(entry: E): BlogPostMetadata;
+  categories: BlogCategory[];
 }

package/modules/blog/templates/lib/blog.ts

@@ -1,6 +1,4 @@
-// Astro Content Collections variant — recommended for Astro sites.
-// For non-Astro projects, see `blog-fs.ts` (uses gray-matter directly).
-
+import type { CollectionEntry } from 'astro:content';
 import { createBlogFromCollection, type BlogCategory } from '@ibalzam/codejitsu-core/blog';
 
 const categories: BlogCategory[] = [
@@ -13,13 +11,17 @@ const categories: BlogCategory[] = [
   // },
 ];
 
-export const blog = createBlogFromCollection({
+export const blog = createBlogFromCollection<CollectionEntry<'blog'>>({
   collectionName: 'blog',
-  // Match the field name from your Astro CC schema (`src/content.config.ts`).
-  // Common choices: 'date' (default) or 'pubDate'.
+  // Match the field name in your Astro CC schema (`src/content.config.ts`).
   dateField: 'pubDate',
   // Set to null if your schema has no `draft` field.
   draftField: 'draft',
   defaultAuthor: 'TODO: Site Author',
   categories,
 });
+
+// Optional backward-compat exports for sites migrating from a homegrown loader.
+// Delete these if you don't need them.
+export const getPublishedPosts = () => blog.getPublishedEntries();
+export const getAllPosts = () => blog.getAllEntries();

package/modules/config/src/define.mjs

@@ -0,0 +1,14 @@
+/**
+ * Identity helper that types your `codejitsu.config.ts` export.
+ *
+ * @example
+ * // codejitsu.config.ts
+ * import { defineConfig } from '@ibalzam/codejitsu-core/config';
+ * export default defineConfig({ site: { url: '...', name: '...' } });
+ *
+ * @param {import('./types.js').CodejitsuConfig} config
+ * @returns {import('./types.js').CodejitsuConfig}
+ */
+export function defineConfig(config) {
+  return config;
+}

package/modules/config/src/index.ts

@@ -1,3 +1,5 @@
-export * from './types.js';
-export { defineConfig } from './define.js';
-export { loadConfig, isModuleEnabled } from './load.js';
+export type * from './types.js';
+// @ts-expect-error - .mjs runtime resolves at use time
+export { defineConfig } from './define.mjs';
+// @ts-expect-error - .mjs runtime resolves at use time
+export { loadConfig, isModuleEnabled } from './load.mjs';

package/modules/config/src/{load.ts → load.mjs}

@@ -1,7 +1,6 @@
 import fs from 'fs';
 import path from 'path';
 import { pathToFileURL } from 'url';
-import type { CodejitsuConfig } from './types.js';
 
 const CANDIDATES = [
   'codejitsu.config.ts',
@@ -12,43 +11,41 @@ const CANDIDATES = [
 ];
 
 /**
- * Loads the Codejitsu config from the current working directory (or `cwd`).
+ * Loads the Codejitsu config from the current working directory.
  *
  * Search order:
  *   1. `codejitsu.config.{ts,mts,mjs,js,json}` at cwd root.
  *   2. `codejitsu` key in `package.json`.
  *
- * `.ts` and `.mts` files are loaded via `jiti` (peer-installable). If `jiti`
- * isn't available, the loader skips `.ts` candidates and warns once.
+ * `.ts` and `.mts` files load via `jiti`. If `jiti` isn't installed, the
+ * loader warns once and falls through to other candidates.
  *
- * Throws if no config is found.
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<import('./types.js').CodejitsuConfig>}
  */
-export async function loadConfig(cwd: string = process.cwd()): Promise<CodejitsuConfig> {
+export async function loadConfig(cwd = process.cwd()) {
   for (const name of CANDIDATES) {
     const filePath = path.join(cwd, name);
     if (!fs.existsSync(filePath)) continue;
 
     if (name.endsWith('.json')) {
-      return JSON.parse(fs.readFileSync(filePath, 'utf8')) as CodejitsuConfig;
+      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
     }
 
     if (name.endsWith('.ts') || name.endsWith('.mts')) {
       const config = await loadWithJiti(filePath);
       if (config) return config;
-      // jiti unavailable; fall through to other candidates.
       continue;
     }
 
-    // .mjs / .js — Node can load these directly.
     const mod = await import(pathToFileURL(filePath).href);
-    return (mod.default ?? mod) as CodejitsuConfig;
+    return mod.default ?? mod;
   }
 
-  // Fallback: package.json `codejitsu` key.
   const pkgPath = path.join(cwd, 'package.json');
   if (fs.existsSync(pkgPath)) {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    if (pkg.codejitsu) return pkg.codejitsu as CodejitsuConfig;
+    if (pkg.codejitsu) return pkg.codejitsu;
   }
 
   throw new Error(
@@ -58,16 +55,16 @@ export async function loadConfig(cwd: string = process.cwd()): Promise<Codejitsu
 }
 
 let jitiWarned = false;
-async function loadWithJiti(filePath: string): Promise<CodejitsuConfig | null> {
+async function loadWithJiti(filePath) {
   try {
     const jitiMod = await import('jiti');
-    const jitiFactory = (jitiMod as any).default ?? (jitiMod as any).createJiti ?? jitiMod;
-    const jiti = typeof jitiFactory === 'function' ? jitiFactory(process.cwd(), { interopDefault: true }) : null;
-    if (!jiti) {
+    const factory = jitiMod.createJiti ?? jitiMod.default ?? jitiMod;
+    if (typeof factory !== 'function') {
       throw new Error('Unexpected jiti API shape.');
     }
+    const jiti = factory(process.cwd(), { interopDefault: true });
     const mod = await jiti.import(filePath, { default: true });
-    return (mod as any) as CodejitsuConfig;
+    return mod;
   } catch (err) {
     if (!jitiWarned) {
       const reason = err instanceof Error ? err.message : String(err);
@@ -83,14 +80,13 @@ async function loadWithJiti(filePath: string): Promise<CodejitsuConfig | null> {
 
 /**
  * Returns true if the named module is enabled in the config.
- * A module is enabled if its key is present and not `false` and not `enabled: false`.
+ * @param {import('./types.js').CodejitsuConfig} config
+ * @param {'blog'|'seo'|'images'|'llms'|'deploy'} module
+ * @returns {boolean}
  */
-export function isModuleEnabled(
-  config: CodejitsuConfig,
-  module: 'blog' | 'seo' | 'images' | 'llms' | 'deploy'
-): boolean {
+export function isModuleEnabled(config, module) {
   const value = config[module];
   if (value === undefined || value === false) return false;
-  if (typeof value === 'object' && value !== null && (value as { enabled?: boolean }).enabled === false) return false;
+  if (typeof value === 'object' && value !== null && value.enabled === false) return false;
   return true;
 }

package/modules/images/bin/optimize.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import path from 'path';
-import { loadConfig, isModuleEnabled } from '../../config/src/load.js';
+import { loadConfig, isModuleEnabled } from '../../config/src/load.mjs';
 import { optimizeImages } from '../src/optimize.mjs';
 import { autoBlogImages } from '../src/auto-blog.mjs';
 

package/modules/llms/bin/generate.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import path from 'path';
-import { loadConfig, isModuleEnabled } from '../../config/src/load.js';
+import { loadConfig, isModuleEnabled } from '../../config/src/load.mjs';
 import { generateLlms } from '../src/generate.mjs';
 
 const cwd = process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibalzam/codejitsu-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Shared core for Codejitsu Astro sites — reusable code and Claude-facing instructions for blog, SEO, images, deploy, and llms.txt.",
   "keywords": [

package/modules/config/src/define.ts

@@ -1,18 +0,0 @@
-import type { CodejitsuConfig } from './types.js';
-
-/**
- * Identity helper that types your `codejitsu.config.ts` export.
- *
- * @example
- * // codejitsu.config.ts
- * import { defineConfig } from '@ibalzam/codejitsu-core/config';
- *
- * export default defineConfig({
- *   site: { url: 'https://example.com', name: 'Example' },
- *   blog: { mode: 'collection', dateField: 'pubDate', draftField: 'draft' },
- *   // ...
- * });
- */
-export function defineConfig(config: CodejitsuConfig): CodejitsuConfig {
-  return config;
-}