@ibalzam/codejitsu-core 0.1.0 → 0.2.1

package/modules/blog/src/index.ts

@@ -1,201 +1,5 @@
-import fs from 'fs';
-import path from 'path';
-import matter from 'gray-matter';
-import readingTime from 'reading-time';
-
-export interface FAQItem {
-  question: string;
-  answer: string;
-}
-
-export interface BlogPostFrontmatter {
-  title: string;
-  description: string;
-  date: string;
-  slug?: string;
-  author?: string;
-  image?: string;
-  tags?: string[];
-  faqs?: FAQItem[];
-}
-
-export interface BlogPostMetadata {
-  slug: string;
-  title: string;
-  description: string;
-  date: string;
-  author?: string;
-  image?: string;
-  tags?: string[];
-  readingTime: string;
-}
-
-export interface BlogPost extends BlogPostMetadata {
-  faqs?: FAQItem[];
-  content: string;
-}
-
-export interface BlogCategory {
-  slug: string;
-  tag: string;
-  title: string;
-  subtitle: string;
-  metaDescription: string;
-}
-
-export interface BlogConfig {
-  contentDir?: string;
-  defaultAuthor?: string;
-  categories?: BlogCategory[];
-}
-
-export interface BlogAPI {
-  getAllPosts(): Promise<BlogPostMetadata[]>;
-  getAllPostsIncludingFuture(): Promise<BlogPostMetadata[]>;
-  getFutureBlogSlugs(): Promise<string[]>;
-  getAllPostSlugs(): Promise<string[]>;
-  getPostBySlug(slug: string): Promise<BlogPost | null>;
-  getAllTags(): Promise<string[]>;
-  getPostsByTag(tag: string): Promise<BlogPostMetadata[]>;
-  getAllCategorySlugs(): string[];
-  getCategoryBySlug(slug: string): BlogCategory | undefined;
-  getPostsByCategory(slug: string): Promise<BlogPostMetadata[]>;
-  categories: BlogCategory[];
-}
-
-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 canonicalSlugFor(name: string, fm: { slug?: string }): string {
-  return fm.slug || fileSlug(name);
-}
-
-export function createBlog(config: BlogConfig = {}): BlogAPI {
-  const contentDir = path.resolve(process.cwd(), config.contentDir ?? 'content/blog');
-  const defaultAuthor = config.defaultAuthor;
-  const categories = config.categories ?? [];
-
-  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 Partial<BlogPostFrontmatter>;
-        return {
-          fileName,
-          fileSlug: fileSlug(fileName),
-          canonicalSlug: canonicalSlugFor(fileName, data),
-          data,
-          content: parsed.content,
-        };
-      });
-  }
-
-  function toMetadata(f: ReturnType<typeof readAllFiles>[number]): BlogPostMetadata {
-    return {
-      slug: f.canonicalSlug,
-      title: f.data.title ?? '',
-      description: f.data.description ?? '',
-      date: f.data.date ?? '',
-      author: f.data.author ?? defaultAuthor,
-      image: f.data.image,
-      tags: f.data.tags,
-      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()) {
-      if (!f.data.date) continue;
-      if (new Date(f.data.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,
-      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,
-  };
-}
+export * from './types.js';
+export { createBlog } from './fs.js';
+export type { FsBlogConfig } from './fs.js';
+export { createBlogFromCollection } from './collection.js';
+export type { CollectionBlogConfig } from './collection.js';

package/modules/blog/src/types.ts

@@ -0,0 +1,71 @@
+export interface FAQItem {
+  question: string;
+  answer: string;
+}
+
+export interface BlogPostFrontmatter {
+  title: string;
+  description: string;
+  date: string | Date;
+  slug?: string;
+  author?: string;
+  image?: string;
+  tags?: string[];
+  faqs?: FAQItem[];
+  draft?: boolean;
+  /** Additional fields. */
+  [key: string]: unknown;
+}
+
+export interface BlogPostMetadata {
+  slug: string;
+  title: string;
+  description: string;
+  /** ISO date string (YYYY-MM-DD or full ISO). */
+  date: string;
+  author?: string;
+  image?: string;
+  tags?: string[];
+  readingTime: string;
+}
+
+export interface BlogPost extends BlogPostMetadata {
+  faqs?: FAQItem[];
+  /** Raw markdown body (fs mode) or rendered HTML (CC mode). See per-function notes. */
+  content: string;
+}
+
+export interface BlogCategory {
+  slug: string;
+  tag: string;
+  title: string;
+  subtitle: string;
+  metaDescription: string;
+}
+
+export interface BlogAPI {
+  /** Published posts only (date <= today, not draft). Sorted newest first. */
+  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[]>;
+  getPostsByTag(tag: string): Promise<BlogPostMetadata[]>;
+  getAllCategorySlugs(): string[];
+  getCategoryBySlug(slug: string): BlogCategory | undefined;
+  getPostsByCategory(slug: string): Promise<BlogPostMetadata[]>;
+  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;
+}

package/modules/blog/templates/content.config.ts

@@ -0,0 +1,27 @@
+// Drop into `src/content.config.ts` (Astro). Adjust schema to your needs.
+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(),
+    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 };

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

@@ -0,0 +1,14 @@
+// FS + gray-matter variant — use for non-Astro projects (Next.js, etc.).
+// For Astro, see `blog.ts` (uses Content Collections).
+
+import { createBlog, type BlogCategory } from '@ibalzam/codejitsu-core/blog';
+
+const categories: BlogCategory[] = [];
+
+export const blog = createBlog({
+  contentDir: 'content/blog',
+  dateField: 'date',           // 'date' or 'pubDate' depending on your frontmatter
+  draftField: null,            // set to 'draft' if your frontmatter uses it
+  defaultAuthor: 'TODO: Site Author',
+  categories,
+});

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

@@ -1,4 +1,7 @@
-import { createBlog, type BlogCategory } from '@ibalzam/codejitsu-core/blog';
+// Astro Content Collections variant — recommended for Astro sites.
+// For non-Astro projects, see `blog-fs.ts` (uses gray-matter directly).
+
+import { createBlogFromCollection, type BlogCategory } from '@ibalzam/codejitsu-core/blog';
 
 const categories: BlogCategory[] = [
   // {
@@ -10,8 +13,13 @@ const categories: BlogCategory[] = [
   // },
 ];
 
-export const blog = createBlog({
-  contentDir: 'content/blog',
+export const blog = createBlogFromCollection({
+  collectionName: 'blog',
+  // Match the field name from your Astro CC schema (`src/content.config.ts`).
+  // Common choices: 'date' (default) or 'pubDate'.
+  dateField: 'pubDate',
+  // Set to null if your schema has no `draft` field.
+  draftField: 'draft',
   defaultAuthor: 'TODO: Site Author',
   categories,
 });

package/modules/config/CLAUDE.md

@@ -0,0 +1,121 @@
+# Config module — instructions for Claude
+
+The unified config drives every other module. When you set up a Codejitsu site, **always create `codejitsu.config.ts` first** — every other module reads from it.
+
+## What this module provides
+
+- `defineConfig(config)` — identity helper that types your config (autocomplete + validation in editors).
+- `loadConfig(cwd?)` — used internally by the CLIs to resolve the config from the site's working directory.
+- `isModuleEnabled(config, name)` — utility for module-aware code paths.
+- Full type definitions (`CodejitsuConfig`, `SiteConfig`, `BlogConfig`, etc.).
+
+## Wiring into a site
+
+### 1. Create `codejitsu.config.ts` at the site root
+
+```ts
+import { defineConfig } from '@ibalzam/codejitsu-core/config';
+
+export default defineConfig({
+  site: {
+    url: 'https://example.com',
+    name: 'Example',
+    titleSuffix: ' — Example',
+    defaultAuthor: 'editor',
+    defaultOgImage: '/og-image.webp',
+    locale: 'en-US',
+    business: {
+      telephone: '+1-555-555-5555',
+      email: 'hello@example.com',
+      address: { addressLocality: 'Las Vegas', addressRegion: 'NV', addressCountry: 'US' },
+      areaServed: ['Las Vegas', 'Henderson'],
+    },
+  },
+
+  blog: {
+    mode: 'collection',         // Astro Content Collections
+    collectionName: 'blog',
+    dateField: 'pubDate',        // pearl pattern
+    draftField: 'draft',
+  },
+
+  seo: {
+    sitemap: {
+      excludePatterns: [/\/lp\//],
+    },
+    defaultSchemas: ['localBusiness', 'website'],
+  },
+
+  images: {
+    sourceDir: 'public/assets/images',
+    defaultQuality: 82,
+    defaultMaxSize: 1376,
+    specialRules: {
+      'logos/logo': { maxWidth: 400, quality: 35 },
+    },
+  },
+
+  llms: {
+    mode: 'content-scan',
+    contentScan: {
+      servicesDir: 'src/content/services',
+      locationsDir: 'src/content/locations',
+      pagesDir: 'src/pages',
+    },
+    blogDir: 'src/content/blog',
+  },
+
+  deploy: { cloudflarePagesName: 'example' },
+});
+```
+
+### 2. Install jiti (only if using `.ts`)
+
+```bash
+npm install -D jiti
+```
+
+`.mjs` and `.json` configs work without jiti.
+
+### 3. The CLIs find it automatically
+
+`codejitsu-optimize-images`, `codejitsu-llms`, and `codejitsu-check` all read from this one file. No more per-module config files.
+
+## Search order
+
+The loader looks for, in order:
+1. `codejitsu.config.ts`
+2. `codejitsu.config.mts`
+3. `codejitsu.config.mjs`
+4. `codejitsu.config.js`
+5. `codejitsu.config.json`
+6. `codejitsu` key in `package.json`
+
+First match wins. Stop searching after one is found.
+
+## Disabling a module
+
+Two ways:
+
+```ts
+// Explicit:
+export default defineConfig({
+  site: {...},
+  blog: { enabled: false },
+});
+
+// Or omit the key entirely:
+export default defineConfig({
+  site: {...},
+  // no blog → blog module is disabled
+});
+```
+
+The checklist runner uses `isModuleEnabled()` to skip checks for disabled modules.
+
+## What must NOT be done
+
+- **Don't keep old per-module config files alongside the new one.** v0.2.0 hard-breaks `codejitsu-images.config.mjs` and `codejitsu-llms.config.mjs`. Delete them.
+- **Don't store secrets in this config.** It ships to the client in some module configurations (e.g. business info → schema.org). Use env vars for anything sensitive.
+- **Don't put computed values that depend on runtime state.** The config loads once at CLI start. If you need dynamic values (e.g. fetched from an API), do it inside the CLI's invocation, not in the config.
+- **Don't duplicate `site.url` in module configs.** All modules read it from `site.url`. Setting it once means changing it once.

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

@@ -0,0 +1,5 @@
+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.mjs

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+const CANDIDATES = [
+  'codejitsu.config.ts',
+  'codejitsu.config.mts',
+  'codejitsu.config.mjs',
+  'codejitsu.config.js',
+  'codejitsu.config.json',
+];
+
+/**
+ * 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 load via `jiti`. If `jiti` isn't installed, the
+ * loader warns once and falls through to other candidates.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<import('./types.js').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'));
+    }
+
+    if (name.endsWith('.ts') || name.endsWith('.mts')) {
+      const config = await loadWithJiti(filePath);
+      if (config) return config;
+      continue;
+    }
+
+    const mod = await import(pathToFileURL(filePath).href);
+    return mod.default ?? mod;
+  }
+
+  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;
+  }
+
+  throw new Error(
+    `No Codejitsu config found in ${cwd}. Create codejitsu.config.ts (or .mjs/.json) ` +
+      `at the site root, or add a "codejitsu" key to package.json.`
+  );
+}
+
+let jitiWarned = false;
+async function loadWithJiti(filePath) {
+  try {
+    const jitiMod = await import('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;
+  } catch (err) {
+    if (!jitiWarned) {
+      const reason = err instanceof Error ? err.message : String(err);
+      console.warn(
+        `[@ibalzam/codejitsu-core] Could not load TypeScript config (${reason}). ` +
+          `Install \`jiti\` as a dev dependency, or rename to codejitsu.config.mjs.`
+      );
+      jitiWarned = true;
+    }
+    return null;
+  }
+}
+
+/**
+ * Returns true if the named module is enabled in the config.
+ * @param {import('./types.js').CodejitsuConfig} config
+ * @param {'blog'|'seo'|'images'|'llms'|'deploy'} module
+ * @returns {boolean}
+ */
+export function isModuleEnabled(config, module) {
+  const value = config[module];
+  if (value === undefined || value === false) return false;
+  if (typeof value === 'object' && value !== null && value.enabled === false) return false;
+  return true;
+}