@ibalzam/codejitsu-core 0.3.0 → 0.3.2

package/modules/blog/src/collection.d.ts

@@ -0,0 +1,31 @@
+import type { BlogCollectionAPI, BlogCollectionEntry, CommonBlogConfig } from './types.js';
+export interface CollectionBlogConfig extends CommonBlogConfig {
+    /** Astro Content Collection name. Default 'blog'. */
+    collectionName?: string;
+}
+/**
+ * Astro Content Collections blog loader. Use this in Astro projects.
+ *
+ * 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 declare function createBlogFromCollection<E extends BlogCollectionEntry = BlogCollectionEntry>(config?: CollectionBlogConfig): BlogCollectionAPI<E>;

package/modules/blog/src/collection.js

@@ -0,0 +1,157 @@
+import readingTime from 'reading-time';
+function getTodayUTC() {
+    const now = new Date();
+    return new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+}
+function asISO(value) {
+    if (value instanceof Date)
+        return value.toISOString().split('T')[0];
+    if (typeof value === 'string')
+        return value;
+    return '';
+}
+function asDate(value) {
+    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.
+ *
+ * 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 = {}) {
+    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() {
+        let mod;
+        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}'. Original error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return mod.getCollection(collectionName);
+    }
+    async function readAll() {
+        const all = await getCollection();
+        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 getAllEntries() {
+        return readAll();
+    }
+    async function getPublishedEntries() {
+        const today = getTodayUTC();
+        const all = await readAll();
+        return all.filter((e) => {
+            const d = asDate(e.data[dateField]);
+            return d ? d <= today : true;
+        });
+    }
+    async function getFutureBlogSlugs() {
+        const today = getTodayUTC();
+        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() {
+        const all = await readAll();
+        return all.map((e) => e.id);
+    }
+    async function getEntryBySlug(slug) {
+        const all = await readAll();
+        return all.find((e) => e.id === slug) ?? null;
+    }
+    async function getAllTags() {
+        const entries = await getPublishedEntries();
+        const tags = new Set();
+        entries.forEach((e) => {
+            const t = e.data.tags;
+            t?.forEach((tag) => tags.add(tag));
+        });
+        return Array.from(tags).sort();
+    }
+    async function getEntriesByTag(tag) {
+        const entries = await getPublishedEntries();
+        return entries.filter((e) => {
+            const t = e.data.tags;
+            return t?.includes(tag);
+        });
+    }
+    function getAllCategorySlugs() {
+        return categories.map((c) => c.slug);
+    }
+    function getCategoryBySlug(slug) {
+        return categories.find((c) => c.slug === slug);
+    }
+    async function getEntriesByCategory(slug) {
+        const cat = getCategoryBySlug(slug);
+        if (!cat)
+            return [];
+        return getEntriesByTag(cat.tag);
+    }
+    function toMetadata(entry) {
+        return {
+            slug: entry.id,
+            title: entry.data.title ?? '',
+            description: entry.data.description ?? '',
+            date: asISO(entry.data[dateField]),
+            author: entry.data.author ?? defaultAuthor,
+            image: entry.data.image,
+            tags: entry.data.tags,
+            readingTime: readingTime(entry.body ?? '').text,
+        };
+    }
+    return {
+        getPublishedEntries,
+        getAllEntries,
+        getFutureBlogSlugs,
+        getAllPostSlugs,
+        getEntryBySlug,
+        getAllTags,
+        getEntriesByTag,
+        getAllCategorySlugs,
+        getCategoryBySlug,
+        getEntriesByCategory,
+        toMetadata,
+        categories,
+    };
+}

package/modules/blog/src/collection.ts

@@ -165,7 +165,7 @@ export function createBlogFromCollection<E extends BlogCollectionEntry = BlogCol
       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,
+      readingTime: readingTime(entry.body ?? '').text,
     };
   }
 

package/modules/blog/src/components/index.d.ts

@@ -0,0 +1 @@
+export type { BlogPost, BlogPostMetadata, BlogCategory, FAQItem } from '../index.js';

package/modules/blog/src/components/index.js

@@ -0,0 +1 @@
+export {};

package/modules/blog/src/fs.d.ts

@@ -0,0 +1,12 @@
+import type { BlogFsAPI, CommonBlogConfig } from './types.js';
+export interface FsBlogConfig extends CommonBlogConfig {
+    /** Directory of .md files (relative to cwd). Default 'content/blog'. */
+    contentDir?: string;
+}
+/**
+ * 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 declare function createBlog(config?: FsBlogConfig): BlogFsAPI;

package/modules/blog/src/fs.js

@@ -0,0 +1,144 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import readingTime from 'reading-time';
+function getTodayUTC() {
+    const now = new Date();
+    return new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+}
+function fileSlug(name) {
+    return name.replace(/\.md$/, '');
+}
+function asISO(value) {
+    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 = {}) {
+    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;
+            const slug = data.slug || fileSlug(fileName);
+            return {
+                fileName,
+                fileSlug: fileSlug(fileName),
+                canonicalSlug: slug,
+                data,
+                content: parsed.content,
+            };
+        })
+            .filter((f) => (draftField ? !f.data[draftField] : true));
+    }
+    function toMetadata(f) {
+        return {
+            slug: f.canonicalSlug,
+            title: f.data.title ?? '',
+            description: f.data.description ?? '',
+            date: asISO(f.data[dateField]),
+            author: f.data.author ?? defaultAuthor,
+            image: f.data.image,
+            tags: f.data.tags,
+            readingTime: readingTime(f.content).text,
+        };
+    }
+    async function getAllPostsIncludingFuture() {
+        return readAllFiles()
+            .map(toMetadata)
+            .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+    }
+    async function getAllPosts() {
+        const today = getTodayUTC();
+        const all = await getAllPostsIncludingFuture();
+        return all.filter((p) => new Date(p.date) <= today);
+    }
+    async function getFutureBlogSlugs() {
+        const today = getTodayUTC();
+        const slugs = new Set();
+        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() {
+        const slugs = new Set();
+        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) {
+        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() {
+        const posts = await getAllPosts();
+        const tags = new Set();
+        posts.forEach((p) => p.tags?.forEach((t) => tags.add(t)));
+        return Array.from(tags).sort();
+    }
+    async function getPostsByTag(tag) {
+        const posts = await getAllPosts();
+        return posts.filter((p) => p.tags?.includes(tag));
+    }
+    function getAllCategorySlugs() {
+        return categories.map((c) => c.slug);
+    }
+    function getCategoryBySlug(slug) {
+        return categories.find((c) => c.slug === slug);
+    }
+    async function getPostsByCategory(slug) {
+        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/index.d.ts

@@ -0,0 +1,5 @@
+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/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export { createBlog } from './fs.js';
+export { createBlogFromCollection } from './collection.js';

package/modules/blog/src/types.d.ts

@@ -0,0 +1,100 @@
+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;
+    [key: string]: unknown;
+}
+/** Normalized blog post (fs variant only). */
+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. */
+    content: string;
+}
+export interface BlogCategory {
+    slug: string;
+    tag: string;
+    title: string;
+    subtitle: string;
+    metaDescription: string;
+}
+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>;
+    /** Optional — Astro's CollectionEntry types `body` as `string | undefined`. */
+    body?: string;
+}
+/** API for the fs (gray-matter) blog loader — normalized objects. */
+export interface BlogFsAPI {
+    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[];
+}
+/**
+ * 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/src/types.js

@@ -0,0 +1 @@
+export {};

package/modules/blog/src/types.ts

@@ -63,7 +63,8 @@ export interface CommonBlogConfig {
 export interface BlogCollectionEntry {
   id: string;
   data: Record<string, unknown>;
-  body: string;
+  /** Optional — Astro's CollectionEntry types `body` as `string | undefined`. */
+  body?: string;
 }
 
 /** API for the fs (gray-matter) blog loader — normalized objects. */

package/modules/config/src/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export { defineConfig } from './define.mjs';
+export { loadConfig, isModuleEnabled } from './load.mjs';

package/modules/config/src/index.js

@@ -0,0 +1,4 @@
+// @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/types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Unified Codejitsu config — the shape of `codejitsu.config.ts` at site root.
+ *
+ * One config drives every module. Each top-level module key (`blog`, `seo`,
+ * `images`, `llms`, `deploy`) is optional: omit it to disable that module,
+ * or include it (even as `{}`) to enable with defaults. Set `enabled: false`
+ * to explicitly disable while keeping the section for documentation.
+ */
+export interface CodejitsuConfig {
+    /** Site-wide identity and metadata, used by multiple modules. */
+    site: SiteConfig;
+    blog?: BlogConfig | false;
+    seo?: SeoConfig | false;
+    images?: ImagesConfig | false;
+    llms?: LlmsConfig | false;
+    deploy?: DeployConfig | false;
+}
+export interface SiteConfig {
+    /** Absolute site URL, no trailing slash. e.g. 'https://example.com'. */
+    url: string;
+    /** Brand name. e.g. 'Pearl Remodeling'. */
+    name: string;
+    /** Appended to <title> tags. e.g. ' — Pearl Remodeling'. */
+    titleSuffix?: string;
+    /** Default author when blog posts don't specify one. */
+    defaultAuthor?: string;
+    /** Default OG image (relative path or absolute URL). */
+    defaultOgImage?: string;
+    /** HTML lang attribute. e.g. 'en-US', 'en'. */
+    locale?: string;
+    /** Optional structured business info for Organization / LocalBusiness schema. */
+    business?: BusinessInfo;
+}
+export interface BusinessInfo {
+    legalName?: string;
+    telephone?: string;
+    email?: string;
+    /** Used for LocalBusiness schema and contact pages. */
+    address?: PostalAddress;
+    geo?: {
+        latitude: number;
+        longitude: number;
+    };
+    /** Social profile URLs. */
+    sameAs?: string[];
+    /** e.g. '$$', '$$$'. */
+    priceRange?: string;
+    /** Service areas. Strings (city names) or objects. */
+    areaServed?: string[];
+    /** License number for licensed trades. */
+    license?: string;
+    /** Schema.org type override, e.g. 'HVACBusiness', 'HomeAndConstructionBusiness'. */
+    schemaType?: string;
+}
+export interface PostalAddress {
+    streetAddress?: string;
+    addressLocality: string;
+    addressRegion?: string;
+    postalCode?: string;
+    addressCountry: string;
+}
+export interface BlogConfig {
+    enabled?: boolean;
+    /**
+     * 'collection' — use Astro Content Collections (recommended for Astro sites).
+     * 'fs' — read .md files directly via gray-matter (for non-Astro projects).
+     * Defaults to 'collection' if the site has astro as a dep; otherwise 'fs'.
+     */
+    mode?: 'collection' | 'fs';
+    /** For 'fs' mode: where the .md files live. Default 'content/blog'. */
+    contentDir?: string;
+    /** For 'collection' mode: name of the Astro CC. Default 'blog'. */
+    collectionName?: string;
+    /** Frontmatter field for the post date. Default 'date'. Pearl uses 'pubDate'. */
+    dateField?: string;
+    /** Frontmatter field for draft state. Default null (no draft support). Pearl uses 'draft'. */
+    draftField?: string | null;
+    /** Category definitions for /blog/category/[slug] pages. */
+    categories?: BlogCategory[];
+}
+export interface BlogCategory {
+    slug: string;
+    tag: string;
+    title: string;
+    subtitle: string;
+    metaDescription: string;
+}
+export interface SeoConfig {
+    enabled?: boolean;
+    sitemap?: {
+        /** Regex patterns to exclude from the sitemap. */
+        excludePatterns?: RegExp[];
+        /**
+         * Site-specific priority rules, evaluated before defaults.
+         * First matching pattern wins.
+         */
+        priorityRules?: Array<{
+            pattern: RegExp;
+            priority: number;
+            changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+        }>;
+    };
+    /**
+     * Default schemas to inject site-wide when not overridden per-page.
+     * e.g. always-on Organization or LocalBusiness on every page.
+     */
+    defaultSchemas?: ('organization' | 'localBusiness' | 'website')[];
+}
+export interface ImagesConfig {
+    enabled?: boolean;
+    /** Source dir for the recursive optimizer. Default 'public/images'. */
+    sourceDir?: string;
+    /** Thumbnail output dir. Set to null to disable thumb generation. Default null. */
+    thumbDir?: string | null;
+    defaultQuality?: number;
+    defaultMaxSize?: number;
+    thumbSize?: number;
+    thumbQuality?: number;
+    /**
+     * Per-file rule overrides. Key = path relative to sourceDir without extension.
+     * e.g. 'logos/logo': { maxWidth: 329, quality: 35, generateAvif: true }
+     */
+    specialRules?: Record<string, SpecialRule>;
+    /**
+     * Blog-post image automation. Replaces hand-maintained title→slug maps.
+     * If set, the optimizer scans `contentDir` for post filenames and looks for
+     * matching source images in `sourceImageDir`, optimizing them into `outputDir`.
+     */
+    autoBlogImages?: {
+        contentDir: string;
+        sourceImageDir: string;
+        outputDir: string;
+        width: number;
+        height?: number | null;
+        quality?: number;
+    };
+}
+export interface SpecialRule {
+    maxWidth?: number | null;
+    maxHeight?: number | null;
+    quality?: number;
+    smartSubsample?: boolean;
+    generateAvif?: boolean;
+    optimizePng?: boolean;
+}
+export interface LlmsConfig {
+    enabled?: boolean;
+    /**
+     * 'config' — sections are listed explicitly in this config (simplest sites).
+     * 'content-scan' — modules scan content dirs to enumerate URLs (pearl pattern).
+     * Default 'config'.
+     */
+    mode?: 'config' | 'content-scan';
+    /** One-line tagline appended to the title in the output. */
+    tagline?: string;
+    /** Short "About" paragraph (used in llms.txt). */
+    about?: string;
+    /** Longer "About" content (used in llms-full.txt; falls back to `about`). */
+    aboutFull?: string;
+    /** Sections for 'config' mode. Ignored in 'content-scan' mode. */
+    sections?: LlmsSection[];
+    /** "For AI Assistants" block content (both modes). */
+    aiGuidance?: string;
+    /** Blog directory (auto-included in both modes). */
+    blogDir?: string;
+    blogLimit?: number;
+    blogFullLimit?: number;
+    /** Settings for 'content-scan' mode. */
+    contentScan?: {
+        servicesDir?: string;
+        locationsDir?: string;
+        pagesDir?: string;
+    };
+}
+export interface LlmsSection {
+    title: string;
+    description?: string;
+    items: LlmsSectionItem[];
+}
+export interface LlmsSectionItem {
+    title: string;
+    description: string;
+    url: string;
+    fullDescription?: string;
+}
+export interface DeployConfig {
+    enabled?: boolean;
+    /** Cloudflare Pages project name. Used for documentation only. */
+    cloudflarePagesName?: string;
+}

package/modules/config/src/types.js

@@ -0,0 +1 @@
+export {};

package/modules/images/src/index.d.ts

@@ -0,0 +1,3 @@
+export type { ImagesConfig, SpecialRule } from '../../config/src/types.js';
+export { optimizeImages } from './optimize.mjs';
+export { autoBlogImages } from './auto-blog.mjs';

package/modules/images/src/index.js

@@ -0,0 +1,4 @@
+// @ts-expect-error - .mjs file resolved by Node at runtime
+export { optimizeImages } from './optimize.mjs';
+// @ts-expect-error - .mjs file resolved by Node at runtime
+export { autoBlogImages } from './auto-blog.mjs';

package/modules/seo/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schema.js';
+export * from './sitemap.js';

package/modules/seo/src/index.js

@@ -0,0 +1,2 @@
+export * from './schema.js';
+export * from './sitemap.js';

package/modules/seo/src/schema.d.ts

@@ -0,0 +1,175 @@
+/**
+ * JSON-LD schema.org builders. Each function returns a plain object ready
+ * to `JSON.stringify` and inject into a `<script type="application/ld+json">`.
+ *
+ * Helper at the bottom: `jsonLd(obj)` returns the stringified script body.
+ */
+export interface OrganizationInput {
+    name: string;
+    url: string;
+    logo?: string;
+    sameAs?: string[];
+    email?: string;
+    telephone?: string;
+}
+export declare function organization(input: OrganizationInput): {
+    telephone?: string | undefined;
+    email?: string | undefined;
+    sameAs?: string[] | undefined;
+    logo?: string | undefined;
+    '@context': string;
+    '@type': string;
+    name: string;
+    url: string;
+};
+export interface PostalAddress {
+    streetAddress?: string;
+    addressLocality: string;
+    addressRegion?: string;
+    postalCode?: string;
+    addressCountry: string;
+}
+export interface GeoCoordinates {
+    latitude: number;
+    longitude: number;
+}
+export interface LocalBusinessInput {
+    name: string;
+    url: string;
+    telephone: string;
+    image?: string;
+    priceRange?: string;
+    address: PostalAddress;
+    geo?: GeoCoordinates;
+    openingHours?: string[];
+    areaServed?: string[];
+    sameAs?: string[];
+    /** Override @type to a more specific LocalBusiness subtype, e.g. 'HVACBusiness', 'HomeAndConstructionBusiness'. */
+    type?: string;
+}
+export declare function localBusiness(input: LocalBusinessInput): {
+    sameAs?: string[] | undefined;
+    areaServed?: string[] | undefined;
+    openingHoursSpecification?: string[] | undefined;
+    geo?: {
+        latitude: number;
+        longitude: number;
+        '@type': string;
+    } | undefined;
+    address: {
+        streetAddress?: string;
+        addressLocality: string;
+        addressRegion?: string;
+        postalCode?: string;
+        addressCountry: string;
+        '@type': string;
+    };
+    priceRange?: string | undefined;
+    image?: string | undefined;
+    '@context': string;
+    '@type': string;
+    name: string;
+    url: string;
+    telephone: string;
+};
+export interface WebSiteInput {
+    name: string;
+    url: string;
+    /** If set, adds SearchAction pointing to this URL template (with `{search_term_string}`). */
+    searchUrlTemplate?: string;
+}
+export declare function website(input: WebSiteInput): Record<string, unknown>;
+export interface BlogPostingInput {
+    title: string;
+    description: string;
+    url: string;
+    datePublished: string;
+    dateModified?: string;
+    image?: string;
+    authorName?: string;
+    publisherName: string;
+    publisherLogo?: string;
+}
+export declare function blogPosting(input: BlogPostingInput): {
+    publisher: {
+        logo?: {
+            '@type': string;
+            url: string;
+        } | undefined;
+        '@type': string;
+        name: string;
+    };
+    author?: {
+        '@type': string;
+        name: string;
+    } | undefined;
+    image?: string | undefined;
+    '@context': string;
+    '@type': string;
+    headline: string;
+    description: string;
+    mainEntityOfPage: {
+        '@type': string;
+        '@id': string;
+    };
+    url: string;
+    datePublished: string;
+    dateModified: string;
+};
+export interface FAQ {
+    question: string;
+    answer: string;
+}
+export declare function faqPage(faqs: FAQ[]): {
+    '@context': string;
+    '@type': string;
+    mainEntity: {
+        '@type': string;
+        name: string;
+        acceptedAnswer: {
+            '@type': string;
+            text: string;
+        };
+    }[];
+};
+export interface BreadcrumbItem {
+    name: string;
+    url: string;
+}
+export declare function breadcrumbList(items: BreadcrumbItem[]): {
+    '@context': string;
+    '@type': string;
+    itemListElement: {
+        '@type': string;
+        position: number;
+        name: string;
+        item: string;
+    }[];
+};
+export interface ServiceInput {
+    name: string;
+    description: string;
+    url: string;
+    provider: {
+        name: string;
+        url: string;
+    };
+    areaServed?: string[];
+    serviceType?: string;
+}
+export declare function service(input: ServiceInput): {
+    serviceType?: string | undefined;
+    areaServed?: string[] | undefined;
+    '@context': string;
+    '@type': string;
+    name: string;
+    description: string;
+    url: string;
+    provider: {
+        '@type': string;
+        name: string;
+        url: string;
+    };
+};
+/** Stringify a schema object for safe injection into <script type="application/ld+json">. */
+export declare function jsonLd(schema: unknown): string;

package/modules/seo/src/schema.js

@@ -0,0 +1,120 @@
+/**
+ * JSON-LD schema.org builders. Each function returns a plain object ready
+ * to `JSON.stringify` and inject into a `<script type="application/ld+json">`.
+ *
+ * Helper at the bottom: `jsonLd(obj)` returns the stringified script body.
+ */
+export function organization(input) {
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'Organization',
+        name: input.name,
+        url: input.url,
+        ...(input.logo && { logo: input.logo }),
+        ...(input.sameAs && { sameAs: input.sameAs }),
+        ...(input.email && { email: input.email }),
+        ...(input.telephone && { telephone: input.telephone }),
+    };
+}
+export function localBusiness(input) {
+    return {
+        '@context': 'https://schema.org',
+        '@type': input.type ?? 'LocalBusiness',
+        name: input.name,
+        url: input.url,
+        telephone: input.telephone,
+        ...(input.image && { image: input.image }),
+        ...(input.priceRange && { priceRange: input.priceRange }),
+        address: { '@type': 'PostalAddress', ...input.address },
+        ...(input.geo && { geo: { '@type': 'GeoCoordinates', ...input.geo } }),
+        ...(input.openingHours && { openingHoursSpecification: input.openingHours }),
+        ...(input.areaServed && { areaServed: input.areaServed }),
+        ...(input.sameAs && { sameAs: input.sameAs }),
+    };
+}
+export function website(input) {
+    const base = {
+        '@context': 'https://schema.org',
+        '@type': 'WebSite',
+        name: input.name,
+        url: input.url,
+    };
+    if (input.searchUrlTemplate) {
+        base.potentialAction = {
+            '@type': 'SearchAction',
+            target: { '@type': 'EntryPoint', urlTemplate: input.searchUrlTemplate },
+            'query-input': 'required name=search_term_string',
+        };
+    }
+    return base;
+}
+export function blogPosting(input) {
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'BlogPosting',
+        headline: input.title,
+        description: input.description,
+        mainEntityOfPage: { '@type': 'WebPage', '@id': input.url },
+        url: input.url,
+        datePublished: input.datePublished,
+        dateModified: input.dateModified ?? input.datePublished,
+        ...(input.image && { image: input.image }),
+        ...(input.authorName && {
+            author: { '@type': 'Person', name: input.authorName },
+        }),
+        publisher: {
+            '@type': 'Organization',
+            name: input.publisherName,
+            ...(input.publisherLogo && {
+                logo: { '@type': 'ImageObject', url: input.publisherLogo },
+            }),
+        },
+    };
+}
+export function faqPage(faqs) {
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'FAQPage',
+        mainEntity: faqs.map((faq) => ({
+            '@type': 'Question',
+            name: faq.question,
+            acceptedAnswer: {
+                '@type': 'Answer',
+                text: faq.answer,
+            },
+        })),
+    };
+}
+export function breadcrumbList(items) {
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement: items.map((item, i) => ({
+            '@type': 'ListItem',
+            position: i + 1,
+            name: item.name,
+            item: item.url,
+        })),
+    };
+}
+export function service(input) {
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'Service',
+        name: input.name,
+        description: input.description,
+        url: input.url,
+        provider: {
+            '@type': 'Organization',
+            name: input.provider.name,
+            url: input.provider.url,
+        },
+        ...(input.areaServed && { areaServed: input.areaServed }),
+        ...(input.serviceType && { serviceType: input.serviceType }),
+    };
+}
+/** Stringify a schema object for safe injection into <script type="application/ld+json">. */
+export function jsonLd(schema) {
+    // Escape `</` to prevent breakout from the script tag.
+    return JSON.stringify(schema).replace(/<\//g, '<\\/');
+}

package/modules/seo/src/sitemap.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Helpers for the `@astrojs/sitemap` integration.
+ *
+ * Two complementary functions:
+ *   - `defaultPriorityRules(site)` produces a `serialize` function that sets
+ *     priority and changefreq based on URL shape (home, top-level hubs,
+ *     service/area pages, blog posts).
+ *   - `excludeFuturePosts(futureSlugs)` produces a `filter` function that
+ *     drops scheduled blog posts whose slugs are in the supplied set.
+ *
+ * Compose both like:
+ *
+ *   sitemap({
+ *     filter: excludeFuturePosts(await blog.getFutureBlogSlugs()),
+ *     serialize: defaultPriorityRules(SITE),
+ *   })
+ */
+export interface SitemapItem {
+    url: string;
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+    lastmod?: string;
+}
+export interface PriorityRulesOptions {
+    /** Extra patterns appended to the defaults. Earlier entries win. */
+    rules?: Array<{
+        pattern: RegExp;
+        priority: number;
+        changefreq?: SitemapItem['changefreq'];
+    }>;
+}
+/**
+ * Returns a `serialize` function that assigns priority/changefreq based on
+ * URL shape. Tune via `options.rules` for site-specific top-level paths.
+ *
+ * @param site The site origin (no trailing slash), e.g. 'https://example.com'.
+ */
+export declare function defaultPriorityRules(site: string, options?: PriorityRulesOptions): (item: SitemapItem) => SitemapItem;
+/**
+ * Returns a `filter` function for `@astrojs/sitemap` that excludes any URL
+ * whose final path segment matches a future-dated blog slug.
+ *
+ * Pass `await blog.getFutureBlogSlugs()` to the constructor.
+ */
+export declare function excludeFuturePosts(futureSlugs: string[]): (url: string) => boolean;
+/** Compose multiple filter functions with AND semantics. */
+export declare function composeFilters(...filters: Array<(url: string) => boolean>): (url: string) => boolean;
+/** Filter helper: exclude URLs matching any of the supplied patterns. */
+export declare function excludePatterns(patterns: RegExp[]): (url: string) => boolean;

package/modules/seo/src/sitemap.js

@@ -0,0 +1,81 @@
+/**
+ * Helpers for the `@astrojs/sitemap` integration.
+ *
+ * Two complementary functions:
+ *   - `defaultPriorityRules(site)` produces a `serialize` function that sets
+ *     priority and changefreq based on URL shape (home, top-level hubs,
+ *     service/area pages, blog posts).
+ *   - `excludeFuturePosts(futureSlugs)` produces a `filter` function that
+ *     drops scheduled blog posts whose slugs are in the supplied set.
+ *
+ * Compose both like:
+ *
+ *   sitemap({
+ *     filter: excludeFuturePosts(await blog.getFutureBlogSlugs()),
+ *     serialize: defaultPriorityRules(SITE),
+ *   })
+ */
+/**
+ * Returns a `serialize` function that assigns priority/changefreq based on
+ * URL shape. Tune via `options.rules` for site-specific top-level paths.
+ *
+ * @param site The site origin (no trailing slash), e.g. 'https://example.com'.
+ */
+export function defaultPriorityRules(site, options = {}) {
+    const homeUrl = `${site}/`;
+    const extra = options.rules ?? [];
+    return (item) => {
+        if (item.url === homeUrl) {
+            return { ...item, priority: 1.0, changefreq: 'daily' };
+        }
+        for (const rule of extra) {
+            if (rule.pattern.test(item.url)) {
+                return {
+                    ...item,
+                    priority: rule.priority,
+                    ...(rule.changefreq && { changefreq: rule.changefreq }),
+                };
+            }
+        }
+        // Default heuristics.
+        if (/\/(services|service-areas|industries)\/$/.test(item.url)) {
+            return { ...item, priority: 0.9, changefreq: 'weekly' };
+        }
+        if (/\/(services|service-areas|industries)\/[^/]+\/$/.test(item.url)) {
+            return { ...item, priority: 0.8, changefreq: 'weekly' };
+        }
+        if (/\/blog\/$/.test(item.url)) {
+            return { ...item, priority: 0.7, changefreq: 'daily' };
+        }
+        if (/\/blog\/[^/]+\/$/.test(item.url)) {
+            return { ...item, priority: 0.6, changefreq: 'monthly' };
+        }
+        if (/\/blog\/(tag|category)\/[^/]+\/$/.test(item.url)) {
+            return { ...item, priority: 0.5, changefreq: 'weekly' };
+        }
+        return item;
+    };
+}
+/**
+ * Returns a `filter` function for `@astrojs/sitemap` that excludes any URL
+ * whose final path segment matches a future-dated blog slug.
+ *
+ * Pass `await blog.getFutureBlogSlugs()` to the constructor.
+ */
+export function excludeFuturePosts(futureSlugs) {
+    const set = new Set(futureSlugs);
+    return (url) => {
+        const m = url.match(/\/blog\/([^/]+)\/?$/);
+        if (!m)
+            return true;
+        return !set.has(m[1]);
+    };
+}
+/** Compose multiple filter functions with AND semantics. */
+export function composeFilters(...filters) {
+    return (url) => filters.every((f) => f(url));
+}
+/** Filter helper: exclude URLs matching any of the supplied patterns. */
+export function excludePatterns(patterns) {
+    return (url) => !patterns.some((p) => p.test(url));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibalzam/codejitsu-core",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "Shared core for Codejitsu Astro sites — reusable code and Claude-facing instructions for blog, SEO, images, deploy, and llms.txt.",
   "keywords": [
@@ -31,14 +31,35 @@
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./config": "./modules/config/src/index.ts",
-    "./blog": "./modules/blog/src/index.ts",
-    "./blog/components": "./modules/blog/src/components/index.ts",
-    "./seo": "./modules/seo/src/index.ts",
-    "./seo/schema": "./modules/seo/src/schema.ts",
-    "./seo/sitemap": "./modules/seo/src/sitemap.ts",
-    "./images": "./modules/images/src/index.ts",
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./config": {
+      "types": "./modules/config/src/index.d.ts",
+      "default": "./modules/config/src/index.js"
+    },
+    "./blog": {
+      "types": "./modules/blog/src/index.d.ts",
+      "default": "./modules/blog/src/index.js"
+    },
+    "./seo": {
+      "types": "./modules/seo/src/index.d.ts",
+      "default": "./modules/seo/src/index.js"
+    },
+    "./seo/schema": {
+      "types": "./modules/seo/src/schema.d.ts",
+      "default": "./modules/seo/src/schema.js"
+    },
+    "./seo/sitemap": {
+      "types": "./modules/seo/src/sitemap.d.ts",
+      "default": "./modules/seo/src/sitemap.js"
+    },
+    "./seo/Head.astro": "./modules/seo/templates/Head.astro",
+    "./images": {
+      "types": "./modules/images/src/index.d.ts",
+      "default": "./modules/images/src/index.js"
+    },
     "./llms": "./modules/llms/src/generate.mjs",
     "./package.json": "./package.json"
   },
@@ -58,7 +79,8 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck"
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run typecheck && npm run build"
   },
   "peerDependencies": {
     "astro": ">=5.0.0"

package/src/index.d.ts

@@ -0,0 +1 @@
+export declare const CORE_VERSION = "0.2.0";

package/src/index.js

@@ -0,0 +1 @@
+export const CORE_VERSION = '0.2.0';