@ibalzam/codejitsu-core 0.1.0

package/modules/images/src/optimize.mjs

@@ -0,0 +1,113 @@
+import sharp from 'sharp';
+import { readdir, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, dirname, parse, relative } from 'path';
+
+/**
+ * Recursively converts JPG/JPEG/PNG → WebP under `sourceDir`, writing
+ * matching thumbnails under `thumbDir`. Per-file rules can override
+ * defaults (quality, dimensions, AVIF generation, in-place PNG optimization).
+ *
+ * @param {object} config
+ * @param {string} config.sourceDir          Absolute path to source images.
+ * @param {string} config.thumbDir           Absolute path to write thumbnails (skipped if same as sourceDir).
+ * @param {number} [config.defaultQuality=75]
+ * @param {number} [config.defaultMaxSize=1200]
+ * @param {number} [config.thumbSize=400]
+ * @param {number} [config.thumbQuality=70]
+ * @param {Record<string, SpecialRule>} [config.specialRules]
+ *   Key = path relative to sourceDir without extension (e.g. 'logos/logo').
+ *   Each rule: { maxWidth?, maxHeight?, quality?, smartSubsample?,
+ *                generateAvif?, optimizePng? }.
+ */
+export async function optimizeImages(config) {
+  const {
+    sourceDir,
+    thumbDir,
+    defaultQuality = 75,
+    defaultMaxSize = 1200,
+    thumbSize = 400,
+    thumbQuality = 70,
+    specialRules = {},
+  } = config;
+
+  if (!existsSync(sourceDir)) {
+    console.log(`No source dir at ${sourceDir} — nothing to optimize.`);
+    return;
+  }
+
+  const generateThumbs = thumbDir && thumbDir !== sourceDir;
+  if (generateThumbs && !existsSync(thumbDir)) {
+    await mkdir(thumbDir, { recursive: true });
+  }
+
+  async function processDir(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (generateThumbs && fullPath === thumbDir) continue;
+        await processDir(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const lower = entry.name.toLowerCase();
+      if (!/\.(jpe?g|png)$/.test(lower)) continue;
+
+      const { name } = parse(entry.name);
+      const relPath = relative(sourceDir, fullPath);
+      const ruleKey = relPath.replace(/\.(jpe?g|png)$/i, '');
+      const rule = specialRules[ruleKey];
+
+      const outputDir = dirname(fullPath);
+      const webpPath = join(outputDir, `${name}.webp`);
+
+      const maxWidth = rule?.maxWidth ?? defaultMaxSize;
+      const maxHeight = rule?.maxHeight ?? defaultMaxSize;
+      const quality = rule?.quality ?? defaultQuality;
+      const smartSubsample = rule?.smartSubsample ?? false;
+
+      let pipeline = sharp(fullPath);
+      if (maxWidth || maxHeight) {
+        pipeline = pipeline.resize(maxWidth, maxHeight, {
+          fit: 'inside',
+          withoutEnlargement: true,
+        });
+      }
+      await pipeline.webp({ quality, effort: 6, smartSubsample }).toFile(webpPath);
+      console.log(`✓ ${relPath} → ${name}.webp (q=${quality})`);
+
+      if (rule?.generateAvif) {
+        const avifPath = join(outputDir, `${name}.avif`);
+        await sharp(fullPath)
+          .resize(maxWidth, maxHeight, { fit: 'inside', withoutEnlargement: true })
+          .avif({ quality, effort: 6 })
+          .toFile(avifPath);
+        console.log(`  + ${name}.avif`);
+      }
+
+      if (rule?.optimizePng && lower.endsWith('.png')) {
+        const buffer = await sharp(fullPath)
+          .resize(maxWidth, maxHeight, { fit: 'inside', withoutEnlargement: true })
+          .png({ quality, compressionLevel: 9, palette: true })
+          .toBuffer();
+        await sharp(buffer).toFile(fullPath);
+        console.log(`  ↻ optimized PNG in place`);
+      }
+
+      if (generateThumbs) {
+        const thumbOutputDir = join(thumbDir, dirname(relPath));
+        if (!existsSync(thumbOutputDir)) {
+          await mkdir(thumbOutputDir, { recursive: true });
+        }
+        await sharp(fullPath)
+          .resize(thumbSize, thumbSize, { fit: 'cover', position: 'center' })
+          .webp({ quality: thumbQuality, effort: 6 })
+          .toFile(join(thumbOutputDir, `${name}.webp`));
+      }
+    }
+  }
+
+  await processDir(sourceDir);
+  console.log('\nDone.');
+}

package/modules/images/templates/codejitsu-images.config.mjs

@@ -0,0 +1,18 @@
+/** @type {import('@ibalzam/codejitsu-core/images').OptimizeImagesConfig} */
+export default {
+  sourceDir: 'public/images',
+  thumbDir: 'public/images/thumbs',
+  defaultQuality: 75,
+  defaultMaxSize: 1200,
+  thumbSize: 400,
+  thumbQuality: 70,
+
+  // Per-file overrides. Key = path relative to sourceDir, without extension.
+  specialRules: {
+    // Example: aggressively compress the logo, also generate AVIF.
+    // 'logos/logo': { maxWidth: 329, maxHeight: 70, quality: 35, generateAvif: true },
+    //
+    // Example: OG share image — keep quality high, optimize the PNG in place too.
+    // 'sharing/og-default': { maxWidth: 1200, maxHeight: 630, quality: 85, optimizePng: true },
+  },
+};

package/modules/llms/CLAUDE.md

@@ -0,0 +1,57 @@
+# llms.txt module — instructions for Claude
+
+When the user asks to **set up codejitsu/core/llms** (or "add llms.txt", "generate the AI files"), do the following.
+
+## What this module provides
+
+A CLI (`npx codejitsu-llms`) that reads a site config and generates:
+- `public/llms.txt` — concise navigation overview for AI assistants.
+- `public/llms-full.txt` — detailed content dump for LLM ingestion.
+
+Both files are recognized by an emerging convention for AI-friendly websites (similar to `robots.txt` for crawlers). They make the site discoverable and citable by AI assistants without those assistants having to crawl HTML.
+
+## Wiring it into a site
+
+### 1. Copy the config template
+
+`templates/codejitsu-llms.config.mjs` → site root. Edit:
+- `siteUrl`, `siteName`, `tagline`
+- `about` (short, used in concise file) and `aboutFull` (longer, in detailed file)
+- `sections` — the high-level structure of the site (services, key pages, etc.)
+- `blogDir` — set if the site has a blog (auto-pulls recent posts)
+- `aiGuidance` — the "When referencing us..." block
+
+### 2. Wire into prebuild
+
+In the site's `package.json`:
+
+```json
+{
+  "scripts": {
+    "prebuild": "codejitsu-llms && codejitsu-optimize-images",
+    "build": "astro build"
+  }
+}
+```
+
+### 3. Run once
+
+```bash
+npm run prebuild
+ls public/llms.txt public/llms-full.txt
+```
+
+## What must NOT be done
+
+- **Don't write the llms.txt files by hand.** They're regenerated every build; manual edits get blown away.
+- **Don't reference URLs with no trailing slash.** Internal URLs in `sections` should end with `/`.
+- **Don't omit the blog section just because there's only one post.** A single post is fine; an empty blog gracefully renders as no Blog section.
+- **Don't put `aiGuidance` text that contradicts the site copy.** If the site says "free plan available," `aiGuidance` should too.
+
+## Verify
+
+- [ ] `codejitsu-llms.config.mjs` exists at site root.
+- [ ] `public/llms.txt` exists after `npm run build` and is < 50KB.
+- [ ] `public/llms-full.txt` exists and is < 500KB (otherwise split or trim).
+- [ ] `llms.txt` lists every major top-level section of the site.
+- [ ] `aiGuidance` block answers: who we are, who we serve, key differentiator, how to contact / sign up.

package/modules/llms/bin/generate.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import path from 'path';
+import { existsSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { generateLlms } from '../src/generate.mjs';
+
+const cwd = process.cwd();
+const candidates = ['codejitsu-llms.config.mjs', 'codejitsu-llms.config.js'];
+
+let configPath = null;
+for (const name of candidates) {
+  const p = path.join(cwd, name);
+  if (existsSync(p)) {
+    configPath = p;
+    break;
+  }
+}
+
+if (!configPath) {
+  console.error('No codejitsu-llms.config.mjs found in current directory.');
+  console.error('Copy the template from node_modules/@ibalzam/codejitsu-core/modules/llms/templates/');
+  process.exit(1);
+}
+
+const userConfig = (await import(pathToFileURL(configPath).href)).default;
+
+await generateLlms({
+  ...userConfig,
+  outDir: userConfig.outDir
+    ? path.resolve(cwd, userConfig.outDir)
+    : path.join(cwd, 'public'),
+  blogDir: userConfig.blogDir
+    ? path.resolve(cwd, userConfig.blogDir)
+    : undefined,
+});

package/modules/llms/checklist.md

@@ -0,0 +1,10 @@
+# llms.txt module — checklist
+
+- [ ] `codejitsu-llms.config.mjs` exists at site root.
+- [ ] `siteUrl`, `siteName`, `about` are set (no placeholders).
+- [ ] `prebuild` script in `package.json` invokes `codejitsu-llms`.
+- [ ] `public/llms.txt` and `public/llms-full.txt` exist after build.
+- [ ] `llms.txt` is < 50KB; `llms-full.txt` is < 500KB.
+- [ ] Both files are served with `Content-Type: text/plain` (verify in browser DevTools → Network).
+- [ ] `llms.txt` is linked from `robots.txt` (optional but recommended): add `LLMs: https://site.com/llms.txt` line.
+- [ ] If site has a blog: `blogDir` is set and recent posts appear in the output.

package/modules/llms/src/generate.mjs

@@ -0,0 +1,179 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+
+/**
+ * Generates /llms.txt (concise) and /llms-full.txt (detailed) into `outDir`.
+ *
+ * @param {object} config
+ * @param {string} config.siteUrl              e.g. 'https://acme.com'
+ * @param {string} config.siteName
+ * @param {string} config.tagline              Short one-line description.
+ * @param {string} config.about                Longer "About" paragraph (used in concise file).
+ * @param {string} [config.aboutFull]          Full "About" content (used in full file; falls back to `about`).
+ * @param {Section[]} [config.sections]
+ * @param {string} [config.aiGuidance]         "For AI Assistants" block content.
+ * @param {string} [config.blogDir]            If set, auto-includes recent blog posts.
+ * @param {number} [config.blogLimit=10]       How many recent posts to include in concise file.
+ * @param {number} [config.blogFullLimit=20]   How many in full file.
+ * @param {string} config.outDir               Where to write the files (typically the site's `public/`).
+ *
+ * @typedef {object} Section
+ * @property {string} title
+ * @property {string} [description]      Short intro for the full file.
+ * @property {SectionItem[]} items
+ *
+ * @typedef {object} SectionItem
+ * @property {string} title
+ * @property {string} description
+ * @property {string} url                Relative or absolute.
+ * @property {string} [fullDescription]  Longer text for llms-full.txt.
+ */
+export async function generateLlms(config) {
+  const {
+    siteUrl,
+    siteName,
+    tagline,
+    about,
+    aboutFull,
+    sections = [],
+    aiGuidance,
+    blogDir,
+    blogLimit = 10,
+    blogFullLimit = 20,
+    outDir,
+  } = config;
+
+  if (!outDir) throw new Error('generateLlms: outDir is required.');
+  if (!siteUrl) throw new Error('generateLlms: siteUrl is required.');
+  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+
+  const today = new Date().toISOString().split('T')[0];
+  const blogPosts = blogDir ? readBlog(blogDir) : [];
+
+  const concise = renderConcise({
+    siteUrl,
+    siteName,
+    tagline,
+    about,
+    sections,
+    aiGuidance,
+    today,
+    blogPosts: blogPosts.slice(0, blogLimit),
+  });
+
+  const full = renderFull({
+    siteUrl,
+    siteName,
+    tagline,
+    about: aboutFull ?? about,
+    sections,
+    aiGuidance,
+    today,
+    blogPosts: blogPosts.slice(0, blogFullLimit),
+  });
+
+  fs.writeFileSync(path.join(outDir, 'llms.txt'), concise);
+  fs.writeFileSync(path.join(outDir, 'llms-full.txt'), full);
+  console.log(`✓ wrote ${path.relative(process.cwd(), path.join(outDir, 'llms.txt'))}`);
+  console.log(`✓ wrote ${path.relative(process.cwd(), path.join(outDir, 'llms-full.txt'))}`);
+}
+
+function readBlog(blogDir) {
+  const abs = path.resolve(process.cwd(), blogDir);
+  if (!fs.existsSync(abs)) return [];
+  const now = new Date();
+  const today = new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()));
+
+  return fs
+    .readdirSync(abs)
+    .filter((n) => n.endsWith('.md'))
+    .map((fileName) => {
+      const raw = fs.readFileSync(path.join(abs, fileName), 'utf8');
+      const parsed = matter(raw);
+      const data = parsed.data;
+      return {
+        slug: data.slug || fileName.replace(/\.md$/, ''),
+        title: data.title,
+        description: data.description,
+        date: data.date,
+        author: data.author,
+        tags: data.tags,
+      };
+    })
+    .filter((p) => p.date && new Date(p.date) <= today)
+    .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+}
+
+function absoluteUrl(siteUrl, url) {
+  if (/^https?:\/\//.test(url)) return url;
+  return `${siteUrl.replace(/\/$/, '')}${url.startsWith('/') ? '' : '/'}${url}`;
+}
+
+function renderConcise({ siteUrl, siteName, tagline, about, sections, aiGuidance, today, blogPosts }) {
+  let out = `# ${siteName}${tagline ? ` — ${tagline}` : ''}\n`;
+  out += `Last Updated: ${today}\n\n`;
+  out += `> ${about}\n\n`;
+
+  for (const section of sections) {
+    if (!section.items?.length) continue;
+    out += `## ${section.title}\n`;
+    for (const item of section.items) {
+      out += `- [${item.title}](${absoluteUrl(siteUrl, item.url)}): ${item.description}\n`;
+    }
+    out += '\n';
+  }
+
+  if (blogPosts.length) {
+    out += `## Recent Blog Posts\n`;
+    for (const post of blogPosts) {
+      out += `- [${post.title}](${siteUrl}/blog/${post.slug}/): ${post.description}\n`;
+    }
+    out += '\n';
+  }
+
+  if (aiGuidance) {
+    out += `## For AI Assistants\n\n${aiGuidance}\n\n`;
+  }
+
+  out += `---\nGenerated automatically during build\n`;
+  return out;
+}
+
+function renderFull({ siteUrl, siteName, tagline, about, sections, aiGuidance, today, blogPosts }) {
+  let out = `# ${siteName} — Complete Documentation\n`;
+  out += `Last Updated: ${today}\n\n`;
+  out += `> This file contains the complete content of ${siteName}'s website for AI/LLM ingestion. For a concise navigation overview, see /llms.txt\n\n`;
+  out += `---\n\n# About\n\n${about}\n\n---\n\n`;
+
+  for (const section of sections) {
+    if (!section.items?.length) continue;
+    out += `# ${section.title}\n\n`;
+    if (section.description) out += `${section.description}\n\n`;
+    for (const item of section.items) {
+      out += `## ${item.title}\n\n`;
+      out += `**URL**: ${absoluteUrl(siteUrl, item.url)}\n\n`;
+      out += `${item.fullDescription ?? item.description}\n\n`;
+      out += `---\n\n`;
+    }
+  }
+
+  if (blogPosts.length) {
+    out += `# Blog Posts\n\n`;
+    for (const post of blogPosts) {
+      out += `## ${post.title}\n\n`;
+      out += `**Published**: ${post.date}\n`;
+      if (post.author) out += `**Author**: ${post.author}\n`;
+      if (post.tags?.length) out += `**Tags**: ${post.tags.join(', ')}\n`;
+      out += `**URL**: ${siteUrl}/blog/${post.slug}/\n\n`;
+      out += `${post.description}\n\n---\n\n`;
+    }
+  }
+
+  if (aiGuidance) {
+    out += `# For AI Assistants\n\n${aiGuidance}\n\n`;
+  }
+
+  out += `---\nGenerated automatically during build\n`;
+  return out;
+}

package/modules/llms/templates/codejitsu-llms.config.mjs

@@ -0,0 +1,39 @@
+export default {
+  siteUrl: 'https://example.com',
+  siteName: 'Example Co.',
+  tagline: 'What we do in one line',
+
+  about: `Short paragraph describing what the site is. Used at the top of llms.txt.`,
+
+  aboutFull: `Longer about content, used in llms-full.txt. Can include multiple paragraphs,
+key differentiators, history, etc.`,
+
+  // Set to your blog directory to auto-include recent posts.
+  blogDir: 'content/blog',
+  blogLimit: 10,
+  blogFullLimit: 20,
+
+  sections: [
+    {
+      title: 'Services',
+      description: 'What we offer.',
+      items: [
+        // { title: 'Example service', description: 'One line.', url: '/services/example/' },
+      ],
+    },
+    {
+      title: 'Key Pages',
+      items: [
+        { title: 'About', description: 'About the company.', url: '/about/' },
+        { title: 'Contact', description: 'Get in touch.', url: '/contact/' },
+      ],
+    },
+  ],
+
+  aiGuidance: `When referencing this company:
+- We are <industry/type>
+- Target audience: <who>
+- Key differentiator: <what>
+- Pricing: <if relevant>
+- Contact: <how>`,
+};

package/modules/seo/CLAUDE.md

@@ -0,0 +1,95 @@
+# SEO module — instructions for Claude
+
+When the user asks to **set up codejitsu/core/seo** (or "wire up SEO", "add schema.org to every page", "set up the sitemap"), do the following.
+
+## What this module provides
+
+Three layers:
+
+1. **`@ibalzam/codejitsu-core/seo/schema`** — typed JSON-LD builders: `organization()`, `localBusiness()`, `website()`, `blogPosting()`, `faqPage()`, `breadcrumbList()`, `service()`. Plus `jsonLd(obj)` for safe stringification.
+2. **`@ibalzam/codejitsu-core/seo/sitemap`** — helpers for `@astrojs/sitemap`: `defaultPriorityRules()`, `excludeFuturePosts()`, `composeFilters()`, `excludePatterns()`.
+3. **`templates/Head.astro`** — reusable head component that takes `{ title, description, canonical, ogImage, ogType, schema }` and injects everything.
+
+## Wiring it into a site
+
+### 1. Copy the Head component
+
+`templates/Head.astro` → `src/components/Head.astro` in the site. This is the single place that renders title, meta, OG, Twitter, canonical, and JSON-LD. Every layout `<head>` should include `<Head ... />`.
+
+### 2. Use it on every page
+
+```astro
+---
+import Head from '~/components/Head.astro';
+import { organization, blogPosting } from '@ibalzam/codejitsu-core/seo/schema';
+
+const SITE = { name: 'Acme Co.', url: 'https://acme.com' };
+---
+<html lang="en">
+  <head>
+    <Head
+      title="Page title — Acme Co."
+      description="..."
+      schema={[organization(SITE)]}
+    />
+  </head>
+  <body>...</body>
+</html>
+```
+
+### 3. Wire the sitemap
+
+In `astro.config.mjs`:
+
+```ts
+import sitemap from '@astrojs/sitemap';
+import { defaultPriorityRules, excludeFuturePosts, composeFilters, excludePatterns } from '@ibalzam/codejitsu-core/seo/sitemap';
+import { blog } from './src/lib/blog';
+
+const SITE = 'https://acme.com';
+const futureSlugs = await blog.getFutureBlogSlugs();
+
+export default defineConfig({
+  site: SITE,
+  integrations: [
+    sitemap({
+      filter: composeFilters(
+        excludeFuturePosts(futureSlugs),
+        excludePatterns([/\/lp\//, /\/draft\//]),  // site-specific exclusions
+      ),
+      serialize: defaultPriorityRules(SITE),
+    }),
+  ],
+});
+```
+
+### 4. Copy robots.txt
+
+`templates/robots.txt` → `public/robots.txt`. Edit the `Sitemap:` line to point to the site's actual sitemap URL.
+
+### 5. Per-page schema cheatsheet
+
+| Page type | Schema to inject |
+|---|---|
+| Home | `organization()`, `website()` |
+| Local business home | `localBusiness()` instead of `organization()` |
+| Blog index | `website()` |
+| Blog post | `blogPosting()` + `faqPage(post.faqs)` if FAQs present + `breadcrumbList()` |
+| Service page | `service()` + `breadcrumbList()` |
+| Service area page | `localBusiness()` with `areaServed` set + `breadcrumbList()` |
+| FAQ-heavy landing page | `faqPage()` + page-type schema |
+
+A single `<Head schema={[a, b, c]} />` accepts multiple schemas. Each renders as its own `<script type="application/ld+json">`.
+
+## What must NOT be done
+
+- **Don't inline schema objects.** Always use the builders so types catch missing required fields (e.g. `BlogPosting` requires `publisher`).
+- **Don't hand-write the canonical URL.** Use `Head`'s default (it builds from `Astro.url.pathname` + `Astro.site`) unless overriding for a specific reason.
+- **Don't `JSON.stringify` schemas yourself.** Use `jsonLd()` — it escapes `</` so the script tag can't be broken out of.
+- **Don't reference relative URLs in `og:image`.** OG scrapers require absolute URLs. `Head` resolves this automatically when you pass a relative path.
+- **Don't add `og:image` to a page without an actual image at that path.** Empty OG images render as blank cards on socials.
+- **Don't omit the canonical tag on alternative-URL pages** (filename slug + canonical slug both exist for blog posts). The canonical must point to the frontmatter slug version.
+
+## Verify
+
+Run `modules/seo/checklist.md`.

package/modules/seo/checklist.md

@@ -0,0 +1,30 @@
+# SEO module — checklist
+
+## Setup
+
+- [ ] `src/components/Head.astro` exists and imports from `@ibalzam/codejitsu-core/seo/schema`.
+- [ ] Every Astro layout calls `<Head ... />` in its `<head>`.
+- [ ] `astro.config.mjs` uses `@astrojs/sitemap` with helpers from `@ibalzam/codejitsu-core/seo/sitemap`.
+- [ ] `public/robots.txt` exists and points to the correct sitemap URL.
+
+## Per-page (sample 5+ pages)
+
+- [ ] `<title>` is unique, < 60 chars including suffix.
+- [ ] `<meta name="description">` is unique, < 160 chars.
+- [ ] `<link rel="canonical">` is absolute, has trailing slash, matches the current URL (or is the chosen canonical of N alternatives).
+- [ ] `og:title`, `og:description`, `og:url`, `og:type`, `og:image` (absolute) present.
+- [ ] `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` present.
+- [ ] At least one `<script type="application/ld+json">` per page; type matches the page (Organization on home, BlogPosting on posts, etc.).
+
+## Sitemap
+
+- [ ] `sitemap-index.xml` and `sitemap-0.xml` (or named variants) exist after build.
+- [ ] No future-dated blog post appears in the sitemap.
+- [ ] No URLs matching the site's documented exclusions appear.
+- [ ] Priority + changefreq differentiated by page type (home highest, blog posts lower).
+
+## Schema validation
+
+- [ ] Run a sample blog post URL through https://search.google.com/test/rich-results — `BlogPosting` and (if applicable) `FAQPage` show as valid.
+- [ ] Run the home URL — `Organization`/`LocalBusiness` and `WebSite` show as valid.
+- [ ] No "missing required field" warnings.

package/modules/seo/src/index.ts

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