@ibalzam/codejitsu-core 0.1.0

package/modules/blog/src/index.ts

@@ -0,0 +1,201 @@
+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,
+  };
+}

package/modules/blog/templates/content/_sample-post.md

@@ -0,0 +1,18 @@
+---
+title: "Welcome to the blog"
+description: "First post — a short introduction to what we'll cover here."
+date: 2026-01-01
+slug: welcome
+author: "Codejitsu"
+image: /images/blog/welcome.webp
+tags: [Announcements]
+faqs:
+  - question: "Will posts be published on a schedule?"
+    answer: "Yes — drop a markdown file with a future `date`, and it will go live on that day after the daily deploy runs."
+---
+
+This is the first post. Replace this content with your real post.
+
+## Heading
+
+Body copy. Use standard markdown — headings, lists, links, images.

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

@@ -0,0 +1,17 @@
+import { createBlog, type BlogCategory } from '@ibalzam/codejitsu-core/blog';
+
+const categories: BlogCategory[] = [
+  // {
+  //   slug: 'guides',
+  //   tag: 'Guides',
+  //   title: 'Guides',
+  //   subtitle: 'Practical how-tos',
+  //   metaDescription: '...',
+  // },
+];
+
+export const blog = createBlog({
+  contentDir: 'content/blog',
+  defaultAuthor: 'TODO: Site Author',
+  categories,
+});

package/modules/blog/templates/pages/blog/[...slug].astro

@@ -0,0 +1,53 @@
+---
+import { blog } from '../../lib/blog';
+
+export async function getStaticPaths() {
+  const slugs = await blog.getAllPostSlugs();
+  return slugs.map((slug) => ({ params: { slug } }));
+}
+
+const { slug } = Astro.params;
+const post = await blog.getPostBySlug(slug as string);
+
+if (!post) {
+  return Astro.redirect('/404');
+}
+
+const canonical = `${Astro.site}blog/${post.slug}/`;
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>{post.title}</title>
+    <meta name="description" content={post.description} />
+    <link rel="canonical" href={canonical} />
+    {post.image && <meta property="og:image" content={`${Astro.site.origin}${post.image}`} />}
+    <meta property="og:title" content={post.title} />
+    <meta property="og:description" content={post.description} />
+    <meta property="og:type" content="article" />
+    <meta property="og:url" content={canonical} />
+  </head>
+  <body>
+    <article>
+      <header>
+        <h1>{post.title}</h1>
+        <p>{post.date} · {post.readingTime}{post.author && ` · ${post.author}`}</p>
+      </header>
+      <div set:html={post.content} />
+      {post.faqs && post.faqs.length > 0 && (
+        <section>
+          <h2>FAQs</h2>
+          <dl>
+            {post.faqs.map((faq) => (
+              <>
+                <dt>{faq.question}</dt>
+                <dd>{faq.answer}</dd>
+              </>
+            ))}
+          </dl>
+        </section>
+      )}
+    </article>
+  </body>
+</html>

package/modules/blog/templates/pages/blog/category/[category].astro

@@ -0,0 +1,40 @@
+---
+import { blog } from '../../../lib/blog';
+
+export async function getStaticPaths() {
+  return blog.getAllCategorySlugs().map((category) => ({ params: { category } }));
+}
+
+const { category } = Astro.params;
+const cat = blog.getCategoryBySlug(category as string);
+const posts = await blog.getPostsByCategory(category as string);
+
+if (!cat) {
+  return Astro.redirect('/404');
+}
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>{cat.title}</title>
+    <meta name="description" content={cat.metaDescription} />
+    <link rel="canonical" href={`${Astro.site}blog/category/${cat.slug}/`} />
+  </head>
+  <body>
+    <main>
+      <h1>{cat.title}</h1>
+      <p>{cat.subtitle}</p>
+      <ul>
+        {posts.map((post) => (
+          <li>
+            <a href={`/blog/${post.slug}/`}>
+              <h2>{post.title}</h2>
+              <p>{post.description}</p>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </main>
+  </body>
+</html>

package/modules/blog/templates/pages/blog/index.astro

@@ -0,0 +1,30 @@
+---
+import { blog } from '../../lib/blog';
+
+const posts = await blog.getAllPosts();
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Blog</title>
+    <meta name="description" content="Latest posts" />
+    <link rel="canonical" href={`${Astro.site}blog/`} />
+  </head>
+  <body>
+    <main>
+      <h1>Blog</h1>
+      <ul>
+        {posts.map((post) => (
+          <li>
+            <a href={`/blog/${post.slug}/`}>
+              <h2>{post.title}</h2>
+              <p>{post.description}</p>
+              <small>{post.date} · {post.readingTime}</small>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </main>
+  </body>
+</html>

package/modules/blog/templates/pages/blog/tag/[tag].astro

@@ -0,0 +1,35 @@
+---
+import { blog } from '../../../lib/blog';
+
+export async function getStaticPaths() {
+  const tags = await blog.getAllTags();
+  return tags.map((tag) => ({ params: { tag } }));
+}
+
+const { tag } = Astro.params;
+const posts = await blog.getPostsByTag(tag as string);
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Posts tagged "{tag}"</title>
+    <meta name="description" content={`Articles tagged with ${tag}`} />
+    <link rel="canonical" href={`${Astro.site}blog/tag/${tag}/`} />
+  </head>
+  <body>
+    <main>
+      <h1>Tag: {tag}</h1>
+      <ul>
+        {posts.map((post) => (
+          <li>
+            <a href={`/blog/${post.slug}/`}>
+              <h2>{post.title}</h2>
+              <p>{post.description}</p>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </main>
+  </body>
+</html>

package/modules/deploy/CLAUDE.md

@@ -0,0 +1,58 @@
+# Deploy module — instructions for Claude
+
+When the user asks to **set up codejitsu/core/deploy** (or "wire up the Cloudflare deploy", "add the daily deploy"), do the following.
+
+## What this module provides
+
+- `templates/wrangler.toml` — minimal Cloudflare Pages config.
+- `templates/daily-deploy.yml` — GitHub Action that pings a Cloudflare deploy hook every morning so scheduled blog posts (or any time-gated content) graduate from hidden to public on their publish date.
+
+## Wiring it into a site
+
+### 1. Copy templates
+
+- `templates/wrangler.toml` → `wrangler.toml` at site root. Edit the `name` field to match the Cloudflare Pages project name.
+- `templates/daily-deploy.yml` → `.github/workflows/daily-deploy.yml`. No edits needed (cron is set for 13:00 UTC = 06:00 PDT / 05:00 PST).
+
+### 2. Create the Cloudflare deploy hook
+
+Tell the user to do this manually (Claude can't):
+
+1. Open the Cloudflare dashboard → Pages → the site's project → **Settings → Builds & deployments → Deploy hooks**.
+2. Create a new hook (any name, e.g. `daily-scheduled-content`). Branch: `main`.
+3. Copy the generated URL.
+
+### 3. Set the GH secret
+
+```bash
+gh secret set CLOUDFLARE_DEPLOY_HOOK_URL --body "<paste URL>"
+```
+
+Or via the GitHub UI: Settings → Secrets and variables → Actions → New repository secret, named `CLOUDFLARE_DEPLOY_HOOK_URL`.
+
+### 4. Verify
+
+- Trigger the workflow manually: `gh workflow run "Daily Deploy"` (or via the GH UI).
+- A Cloudflare Pages deployment should kick off within seconds.
+
+## Build command (for Cloudflare Pages git integration)
+
+If using Cloudflare's git integration (preferred for push-driven deploys):
+- **Build command:** `npm run build`
+- **Build output directory:** `dist`
+- **Root directory:** `/`
+- **Node version:** 20 (set via `NODE_VERSION=20` env var in Pages settings)
+
+## What must NOT be done
+
+- **Don't commit the deploy hook URL.** It belongs in `CLOUDFLARE_DEPLOY_HOOK_URL` secret only.
+- **Don't change the cron without reason.** 13:00 UTC is intentional — early-morning Pacific so posts are live by the time users wake up. If a site is on a different timezone, change it explicitly and note why in a comment in the workflow file.
+- **Don't add a `wrangler deploy` step to the cron workflow.** The workflow only *pings* the deploy hook; Cloudflare does the actual build via git integration. Doing the build twice causes drift.
+- **Don't skip the daily-deploy workflow even if the site has no scheduled content yet.** It's the safety net for when the user adds a scheduled post six months later.
+
+## Verify
+
+- [ ] `wrangler.toml` present at site root with correct `name`.
+- [ ] `.github/workflows/daily-deploy.yml` present.
+- [ ] `CLOUDFLARE_DEPLOY_HOOK_URL` secret set in the repo (check with `gh secret list`).
+- [ ] Cloudflare Pages project exists and is connected to the git repo.

package/modules/deploy/checklist.md

@@ -0,0 +1,9 @@
+# Deploy module — checklist
+
+- [ ] `wrangler.toml` exists at site root with the correct Cloudflare Pages project `name`.
+- [ ] `pages_build_output_dir = "dist"` in `wrangler.toml`.
+- [ ] `.github/workflows/daily-deploy.yml` exists and is unmodified from the template (or modifications are documented in a comment).
+- [ ] `CLOUDFLARE_DEPLOY_HOOK_URL` secret is set in the repo (`gh secret list`).
+- [ ] Cloudflare Pages project exists and is connected to the GitHub repo (git integration).
+- [ ] Pages build command is `npm run build`, output dir is `dist`, Node version is 20.
+- [ ] Manual run of `gh workflow run "Daily Deploy"` triggers a Cloudflare deployment within seconds.

package/modules/deploy/templates/daily-deploy.yml

@@ -0,0 +1,29 @@
+name: Daily Deploy
+
+# Triggers a Cloudflare Pages rebuild each morning so any scheduled content
+# whose publish date has arrived graduates from hidden to public.
+#
+# Requires a repository secret named CLOUDFLARE_DEPLOY_HOOK_URL holding
+# the Deploy Hook URL from Cloudflare Pages (Project settings -> Builds &
+# deployments -> Deploy hooks).
+
+on:
+  schedule:
+    # 13:00 UTC = 06:00 PDT / 05:00 PST
+    - cron: '0 13 * * *'
+  workflow_dispatch: {}
+
+jobs:
+  trigger-cloudflare-build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Ping Cloudflare deploy hook
+        env:
+          HOOK: ${{ secrets.CLOUDFLARE_DEPLOY_HOOK_URL }}
+        run: |
+          if [ -z "$HOOK" ]; then
+            echo "CLOUDFLARE_DEPLOY_HOOK_URL secret is not set"
+            exit 1
+          fi
+          curl --fail-with-body -X POST "$HOOK"

package/modules/deploy/templates/wrangler.toml

@@ -0,0 +1,2 @@
+name = "TODO-site-name"
+pages_build_output_dir = "dist"

package/modules/images/CLAUDE.md

@@ -0,0 +1,77 @@
+# Images module — instructions for Claude
+
+When the user asks to **set up codejitsu/core/images** (or "wire up the image pipeline", "convert PNGs to WebP"), do the following.
+
+## What this module provides
+
+Two complementary layers:
+
+1. **Astro sharp service** (runtime, automatic) — handles `<Image>` imports and `<Picture>` components inside `.astro` files. Configured in `astro.config.mjs`.
+2. **Pre-pass CLI** (`npx codejitsu-optimize-images`) — recursively converts every `.png`/`.jpg`/`.jpeg` in `public/images/` to `.webp` (plus thumbnails). For images referenced by URL (in HTML strings, CSS `background-image`, or `<img src>` outside Astro processing).
+
+Both layers are needed. Astro's service can't reach files referenced by URL; the pre-pass can't add the responsive variants Astro generates.
+
+## Wiring it into a site
+
+### 1. Configure Astro
+
+In `astro.config.mjs`:
+
+```ts
+export default defineConfig({
+  // ...
+  image: {
+    service: { entrypoint: 'astro/assets/services/sharp' },
+    defaults: { quality: 82, format: 'webp' },
+  },
+});
+```
+
+### 2. Copy the optimizer config
+
+Copy `templates/codejitsu-images.config.mjs` → site root. Edit `specialRules` for any images that need special handling (logo, OG share images, hero images that need aggressive compression).
+
+### 3. Wire the pre-pass into the build
+
+In the site's `package.json`:
+
+```json
+{
+  "scripts": {
+    "prebuild": "codejitsu-optimize-images",
+    "build": "astro build"
+  }
+}
+```
+
+If the site already has a `prebuild` script, chain: `"prebuild": "codejitsu-optimize-images && existing-script"`.
+
+### 4. Run once
+
+```bash
+npm run prebuild
+```
+
+Every PNG/JPG in `public/images/` now has a `.webp` sibling. References in HTML/CSS should use the `.webp` filename.
+
+## How to reference images in templates
+
+- **In Astro `<Image>` / `<Picture>`:** import from `src/assets/` or `~/assets/`. Astro processes them. Format defaults to WebP.
+- **In raw `<img>` / CSS `background-image`:** reference the `.webp` file directly. Don't reference `.png` if a `.webp` exists.
+- **OG / share images:** these are referenced by absolute URL on a CDN. Set `optimizePng: true` in `specialRules` so the original PNG is also compressed (Facebook scrapers sometimes prefer PNG over WebP).
+
+## What must NOT be done
+
+- **Don't reference `.png` in production HTML when the same image exists as `.webp`.** The `<img src="/images/x.png">` should be `<img src="/images/x.webp">`. Checklist enforces this.
+- **Don't commit the generated `.webp` files... actually, DO commit them.** They're build artifacts but committing avoids forcing CI to install sharp. (Re-evaluate if `public/images` grows huge.)
+- **Don't run the optimizer manually expecting it to skip already-converted files.** Sharp re-processes each run; this is intentional (so quality changes propagate). Re-running is cheap because outputs are written to siblings, not appended.
+- **Don't put the optimizer in a `postinstall` hook.** Building on every `npm install` is annoying.
+- **Don't add raw PNG/JPG to `src/assets/` for Astro `<Image>` use.** Astro handles those fine; the pre-pass is only for `public/`.
+
+## Verify
+
+- [ ] `astro.config.mjs` has `image.defaults: { format: 'webp' }`.
+- [ ] `codejitsu-images.config.mjs` exists at site root.
+- [ ] `package.json` calls `codejitsu-optimize-images` in `prebuild`.
+- [ ] Every `.png`/`.jpg` in `public/images/` has a `.webp` sibling after build.
+- [ ] No `<img src="*.png">` in built HTML where a `.webp` sibling exists.

package/modules/images/bin/optimize.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import path from 'path';
+import { existsSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { optimizeImages } from '../src/optimize.mjs';
+
+const cwd = process.cwd();
+const configCandidates = [
+  'codejitsu-images.config.mjs',
+  'codejitsu-images.config.js',
+];
+
+const defaults = {
+  sourceDir: path.join(cwd, 'public/images'),
+  thumbDir: path.join(cwd, 'public/images/thumbs'),
+  defaultQuality: 75,
+  defaultMaxSize: 1200,
+  thumbSize: 400,
+  thumbQuality: 70,
+  specialRules: {},
+};
+
+let userConfig = {};
+for (const name of configCandidates) {
+  const p = path.join(cwd, name);
+  if (existsSync(p)) {
+    userConfig = (await import(pathToFileURL(p).href)).default ?? {};
+    console.log(`Loaded config: ${name}`);
+    break;
+  }
+}
+
+const config = {
+  ...defaults,
+  ...userConfig,
+  sourceDir: userConfig.sourceDir
+    ? path.resolve(cwd, userConfig.sourceDir)
+    : defaults.sourceDir,
+  thumbDir: userConfig.thumbDir
+    ? path.resolve(cwd, userConfig.thumbDir)
+    : defaults.thumbDir,
+};
+
+await optimizeImages(config);

package/modules/images/checklist.md

@@ -0,0 +1,23 @@
+# Images module — checklist
+
+## Astro
+
+- [ ] `astro.config.mjs` has `image.service: { entrypoint: 'astro/assets/services/sharp' }`.
+- [ ] `astro.config.mjs` has `image.defaults: { quality: 82, format: 'webp' }` (or justified deviation).
+
+## Pre-pass
+
+- [ ] `codejitsu-images.config.mjs` exists at site root.
+- [ ] `package.json` calls `codejitsu-optimize-images` in `prebuild` (or `build`).
+- [ ] Every PNG/JPG in `public/images/` has a `.webp` sibling.
+
+## Production HTML
+
+- [ ] No `<img src>` references `.png` or `.jpg` where a `.webp` exists for the same path.
+- [ ] CSS `background-image` URLs reference `.webp`.
+- [ ] OG / Twitter share images have both PNG (for legacy scrapers) and WebP variants; the `og:image` meta tag points to the PNG (more compatible).
+
+## Sizes
+
+- [ ] No single image in `public/images/` is > 500KB. If so, it has a `specialRules` entry tuning quality/dimensions.
+- [ ] Hero images have `width` and `height` attributes set (CLS).

package/modules/images/src/index.ts

@@ -0,0 +1,21 @@
+export interface SpecialRule {
+  maxWidth?: number | null;
+  maxHeight?: number | null;
+  quality?: number;
+  smartSubsample?: boolean;
+  generateAvif?: boolean;
+  optimizePng?: boolean;
+}
+
+export interface OptimizeImagesConfig {
+  sourceDir: string;
+  thumbDir?: string;
+  defaultQuality?: number;
+  defaultMaxSize?: number;
+  thumbSize?: number;
+  thumbQuality?: number;
+  specialRules?: Record<string, SpecialRule>;
+}
+
+// @ts-expect-error - .mjs file resolved by Node at runtime
+export { optimizeImages } from './optimize.mjs';