@ibalzam/codejitsu-core 0.9.0 → 0.11.0

package/CLAUDE.md

@@ -10,6 +10,10 @@ Shared core for every Codejitsu site. When the user invokes a module by name (e.
 4. If the module has a `templates/` directory, copy those files into the site at the locations the module's CLAUDE.md specifies. Adapt templates for the site's brand and content.
 5. After the change, walk through the module's `checklist.md` plus `checklist/core.md` (sitewide). Run `npx codejitsu-check` from the site root.
 
+## How to act on a SETUP request
+
+If the user asks to **set up codejitsu**, **init**, **migrate \<site\> to codejitsu**, or **start a new Codejitsu site** — open `node_modules/@ibalzam/codejitsu-core/SETUP.md` and follow the step-by-step playbook. It covers detection, install, config generation, module wiring, deploy, and verify for both greenfield and migration scenarios.
+
 ## Module subpaths
 
 | Subpath | Provides |

package/SETUP.md

@@ -0,0 +1,533 @@
+# Codejitsu Setup — Claude playbook
+
+End-to-end procedure for adding `@ibalzam/codejitsu-core` to any project.
+Works for both **greenfield** (brand new site) and **migration** (existing
+Astro site with its own scaffolding).
+
+> **For Claude**: This file is the cookbook. When the user says any of:
+> "set up codejitsu", "add codejitsu", "init codejitsu", "migrate <site> to
+> codejitsu", "start a new Codejitsu site" — open this file and follow the
+> steps top-down. Don't improvise from training-data memory.
+
+---
+
+## Pre-flight: never trust version memory
+
+Before any step that mentions a package version:
+
+```bash
+npm view @ibalzam/codejitsu-core version    # what's actually latest right now
+node --version                               # must be ≥ 20 LTS
+```
+
+Use `@latest` in install commands rather than typing a version number you
+think is current. If the project already has the package, run:
+
+```bash
+npx codejitsu doctor
+```
+
+Surface anything outdated to the user **before** doing setup. Fixing drift
+on a stale codebase is worse than starting from current.
+
+---
+
+## Step 1 — Detect current state
+
+Don't ask the user what's there. Look:
+
+```bash
+cat package.json | head -40            # what's installed + scripts
+cat astro.config.mjs                    # framework + integrations
+ls src/content.config.ts 2>/dev/null && cat src/content.config.ts
+ls src/content/ 2>/dev/null             # collections present?
+ls src/pages/                           # route shape
+cat .git/config | grep url              # github remote
+cat wrangler.toml 2>/dev/null           # cloudflare project name
+ls codejitsu.config.ts codejitsu.config.mjs 2>/dev/null  # already set up?
+```
+
+Build a one-screen summary for the user:
+
+```
+Detected:
+  Astro:        6.3.5
+  Has blog:     Yes (Content Collections, dateField: pubDate, draftField: draft)
+  Has services: Yes (src/content/services/, 9 .md files)
+  Has locations: Yes (src/content/locations/, 7 .md files)
+  GitHub:       ikanc/example
+  Cloudflare:   wrangler.toml present, project: example
+  Codejitsu:    Not installed yet
+
+Greenfield or migration: MIGRATION
+```
+
+State this back to the user **before making changes**. Ask one question:
+
+> "Above is what I detected — anything missing or wrong before I proceed?"
+
+If they say "go" → continue. If they correct something → update your model.
+
+---
+
+## Step 2 — Install the package
+
+```bash
+npm install @ibalzam/codejitsu-core@latest
+npm install -D jiti        # only if codejitsu.config.ts (TS) will be used
+```
+
+Then immediately:
+
+```bash
+npx codejitsu doctor
+```
+
+Confirm:
+- `✓ @ibalzam/codejitsu-core ✓ On latest`
+- No critical outdated deps (Astro / TypeScript / React / Tailwind etc.)
+
+If critical deps are outdated, **stop and surface to user**. Major bumps
+get their own sessions. Don't bundle a codejitsu setup with an Astro 5→6
+upgrade.
+
+---
+
+## Step 3 — Generate `codejitsu.config.ts`
+
+At the project root. Use detected values; prompt only for unknowns.
+
+```ts
+import { defineConfig } from '@ibalzam/codejitsu-core/config';
+
+export default defineConfig({
+  site: {
+    url: '<from astro.config.mjs site:>',
+    name: '<ask user>',
+    titleSuffix: ' | <site name>',
+    defaultAuthor: '<ask user; default "editor">',
+    defaultOgImage: '/assets/images/og-image.webp',
+    locale: 'en_US',
+    business: {              // optional — fill if it's a local business
+      legalName: '...',
+      telephone: '...',
+      email: '...',
+      address: { addressLocality: '...', addressRegion: '...', addressCountry: 'US' },
+      areaServed: ['...'],
+    },
+  },
+
+  blog: {                    // omit entirely if no blog
+    mode: 'collection',
+    collectionName: 'blog',
+    dateField: '<detected from content config; usually pubDate>',
+    draftField: '<detected; usually draft or null>',
+  },
+
+  seo: {
+    sitemap: {
+      excludePatterns: [/* /\/lp\//, etc. — anything to hide from search */],
+    },
+  },
+
+  images: {
+    sourceDir: '<usually public/assets/images>',
+    defaultQuality: 82,
+    defaultMaxSize: 1376,
+    // autoBlogImages — add only if site has a "blog source images live outside public/" workflow
+  },
+
+  llms: {
+    mode: 'content-scan',    // sites with services/locations content; use 'config' for simpler sites
+    tagline: '<ask user>',
+    about: '<ask user>',
+    aboutFull: '<ask user, longer version>',
+    aiGuidance: '<ask user, "When referencing us..." block>',
+    blogDir: 'src/content/blog',
+    contentScan: {
+      servicesDir: 'src/content/services',
+      locationsDir: 'src/content/locations',
+      pagesDir: 'src/pages',
+      dynamicRoutes: [
+        // expand based on detected page routes
+      ],
+    },
+  },
+
+  deploy: {
+    cloudflarePagesName: '<from wrangler.toml, or ask>',
+  },
+
+  contact: {                 // omit if no contact form
+    emailjs: {
+      serviceId: '<ask user, or read from existing modal if migrating>',
+      templateId: '<ask user>',
+      publicKey: '<ask user>',
+    },
+    recaptcha: {              // optional
+      siteKey: '<ask user>',
+    },
+  },
+});
+```
+
+Strategy:
+- Auto-fill from existing state (site URL, blog field names, Cloudflare name).
+- Tagline / about / aiGuidance / EmailJS keys — **ask the user**, don't invent.
+- For migrations, read existing components (e.g. pearl's `QuoteModal.astro`)
+  to extract EmailJS keys already in use.
+
+---
+
+## Step 4 — Wire `astro.config.mjs`
+
+For an **existing** config, preserve everything custom (integrations,
+vite config, output settings). Only refactor:
+
+### 4a. Replace inline future-blog scanner
+
+If the existing config has a `readdirSync` loop scanning blog frontmatter
+for future dates, replace it:
+
+```js
+import { createBlog } from '@ibalzam/codejitsu-core/blog';
+
+const fsBlog = createBlog({
+  contentDir: 'src/content/blog',
+  dateField: 'pubDate',     // match the codejitsu.config
+  draftField: 'draft',
+});
+const futureSlugs = await fsBlog.getFutureBlogSlugs();
+```
+
+### 4b. Sitemap → package helpers
+
+Replace the existing `@astrojs/sitemap` `serialize`/`filter` with:
+
+```js
+import {
+  defaultPriorityRules,
+  excludeFuturePosts,
+  composeFilters,
+  excludePatterns,
+} from '@ibalzam/codejitsu-core/seo';
+
+sitemap({
+  filter: composeFilters(
+    excludePatterns([/\/lp\//]),
+    excludeFuturePosts(futureSlugs),
+  ),
+  serialize: defaultPriorityRules(SITE, {
+    rules: [
+      // any site-specific priority overrides
+    ],
+  }),
+})
+```
+
+### 4c. Add rehype trailing-slash plugin
+
+```js
+import rehypeTrailingSlash from '@ibalzam/codejitsu-core/rehype/trailing-slash';
+
+// inside defineConfig({}):
+markdown: {
+  rehypePlugins: [rehypeTrailingSlash],
+},
+```
+
+### 4d. Verify defaults
+
+```js
+output: 'static',
+trailingSlash: 'always',
+image: {
+  service: { entrypoint: 'astro/assets/services/sharp' },
+  defaults: { quality: 82, format: 'webp' },
+},
+build: { assets: 'assets', inlineStylesheets: 'always' },
+```
+
+For migrations, these often already exist. For greenfield, add them.
+
+---
+
+## Step 5 — Wire the blog (if site has one)
+
+### 5a. Content Collection schema
+
+`src/content.config.ts` — copy from
+`node_modules/@ibalzam/codejitsu-core/modules/blog/templates/content.config.ts`.
+Adapt to the site's existing frontmatter shape.
+
+**On Astro 6+**: import `z` from `'astro/zod'`, NOT `'astro:content'`
+(deprecated). `import { defineCollection } from 'astro:content';`
+plus `import { z } from 'astro/zod';`.
+
+### 5b. Loader
+
+`src/lib/blog.ts`:
+
+```ts
+import type { CollectionEntry } from 'astro:content';
+import { createBlogFromCollection } from '@ibalzam/codejitsu-core/blog/collection';
+
+export const blog = createBlogFromCollection<CollectionEntry<'blog'>>({
+  collectionName: 'blog',
+  dateField: 'pubDate',
+  draftField: 'draft',
+  defaultAuthor: 'editor',
+});
+
+// Backward-compat exports if migrating existing pages:
+export const getPublishedPosts = () => blog.getPublishedEntries();
+export const getAllPosts = () => blog.getAllEntries();
+```
+
+If migrating, page routes like `src/pages/blog/[slug].astro` should already
+import these names — keep the exports.
+
+### 5c. Page routes
+
+For **greenfield**, copy from `node_modules/@ibalzam/codejitsu-core/modules/blog/templates/pages/blog/`:
+- `[...slug].astro` — detail
+- `index.astro` — listing
+- `tag/[tag].astro` (optional)
+- `category/[category].astro` (optional)
+
+For **migrations**, leave existing page routes — they already work via the
+backward-compat exports.
+
+---
+
+## Step 6 — Wire the SEO Head
+
+### 6a. SiteHead wrapper
+
+`src/components/SiteHead.astro` — pulls site defaults from
+`codejitsu.config.ts` and forwards to the package's `Head.astro`. Template
+in `modules/seo/CLAUDE.md`.
+
+### 6b. Use it on every page
+
+Every layout's `<head>` should have:
+
+```astro
+<SiteHead title="..." description="..." schema={[...]} />
+```
+
+For **greenfield**: create one BaseLayout with SiteHead.
+For **migrations**: the existing site likely has its own `Head.astro`.
+Don't replace it wholesale — instead:
+1. Import `jsonLd` from `@ibalzam/codejitsu-core/seo` and use it for JSON-LD injection (fixes XSS risk).
+2. Import schema builders (`blogPosting`, `breadcrumbList`, `service`, etc.) from `@ibalzam/codejitsu-core/seo` and delegate.
+3. Pages stay calling the existing Head; only the implementation gets thinner.
+
+---
+
+## Step 7 — Wire contact (if site has one)
+
+If `contact` is in the config:
+
+In a layout that wraps every page (e.g. BaseLayout), near `</body>`:
+
+```astro
+---
+import ContactModal from '@ibalzam/codejitsu-core/contact/ContactModal.astro';
+import cjConfig from '../../codejitsu.config';
+---
+
+<ContactModal
+  title="Get a Quote"
+  image={{ src: '/assets/images/contact.webp', alt: '...' }}
+  fields={{
+    name:    { required: true },
+    email:   { required: true },
+    phone:   { required: true },
+    message: { required: false },
+  }}
+  submitText="Submit"
+  thankYouMessage="Thanks! We'll be in touch."
+  emailjs={cjConfig.contact.emailjs}
+  recaptcha={cjConfig.contact.recaptcha}
+/>
+```
+
+Trigger from anywhere: `<button data-codejitsu-contact-trigger>...</button>`.
+
+For **migrations**, the existing site has its own modal. Either:
+- (a) replace it with the package modal + remove the old, OR
+- (b) leave the existing modal and skip the contact module.
+
+Migrating: update trigger classes/data attributes to match the new pattern.
+
+---
+
+## Step 8 — Wire package scripts
+
+Update `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "astro dev",
+    "prebuild": "codejitsu-optimize-images && codejitsu-llms",
+    "build": "astro check && astro build",
+    "preview": "astro preview"
+  }
+}
+```
+
+For **migrations**, replace any existing `generate-llms-txt`, `optimize-images`,
+or similar scripts. Delete the old script files (`scripts/optimize-images.js`,
+`scripts/generate-llms-txt.mjs`, etc.) — they're now superseded.
+
+---
+
+## Step 9 — Set up the daily deploy
+
+```bash
+npx codejitsu deploy:setup
+```
+
+Interactive wizard:
+- Copies `.github/workflows/daily-deploy.yml` + `wrangler.toml` from
+  package templates if missing.
+- Prompts for the Cloudflare deploy hook URL.
+- Stores it as a GH Actions secret via `gh secret set`.
+- Optionally triggers a test run.
+
+If the user doesn't have `gh` CLI authed yet, they need:
+
+```bash
+gh auth login
+```
+
+Tell them this **before** running `deploy:setup` — it'll fail otherwise.
+
+---
+
+## Step 10 — Verify
+
+In sequence:
+
+```bash
+npm run build
+```
+
+Must complete with 0 errors. Note warnings (e.g. deprecation warnings from
+upstream deps) — surface to user if they need attention.
+
+```bash
+npx codejitsu audit
+```
+
+Read the output. Pearl's baseline: 50 pass · ~8 warn · 0 fail · ~10 info.
+Comparable shape on a fresh site = healthy. Treat any `✗ fail` as a blocker.
+
+For a more thorough check (production-ready):
+
+```bash
+npx codejitsu audit --live https://<deployed-url> --a11y
+```
+
+(Use the production URL or a local preview server. Skip --a11y if axe-core
+not desired.)
+
+---
+
+## Step 11 — Commit + push
+
+`git status` to see what changed. Common files:
+
+```
+M  astro.config.mjs
+M  package.json
+M  package-lock.json
+M  src/components/Head.astro       (if migration)
+M  src/data/schemas.ts              (if migration)
+M  src/lib/blog.ts                  (if migration; or new)
+A  codejitsu.config.ts              (new)
+A  src/components/SiteHead.astro    (greenfield)
+A  src/components/Footer.astro      (greenfield)
+A  .github/workflows/daily-deploy.yml  (from deploy:setup)
+A  wrangler.toml                    (from deploy:setup)
+D  scripts/generate-llms-txt.mjs    (deleted; superseded)
+D  scripts/optimize-images.js       (deleted; superseded)
+```
+
+Commit message structure (single commit for the migration):
+
+```
+Adopt @ibalzam/codejitsu-core for shared primitives
+
+- codejitsu.config.ts: site info, blog/seo/images/llms/deploy/contact config
+- astro.config.mjs: sitemap helpers, rehype trailing-slash plugin, blog
+  future-slug filter via the package
+- src/lib/blog.ts: createBlogFromCollection (preserves API for existing pages)
+- src/data/schemas.ts: delegate to package schema builders; jsonLd safe injection
+- package.json: codejitsu-optimize-images + codejitsu-llms in prebuild
+- Remove redundant scripts: generate-llms-txt, optimize-images
+```
+
+**Don't push without the user's explicit "yes, push"** — pushing to main
+triggers production deploy via Cloudflare Pages.
+
+---
+
+## Anti-checklist — common mistakes
+
+- **Don't** invent version numbers for packages from memory. Always `@latest`.
+- **Don't** bundle major-version bumps (Astro N→N+1, TypeScript major)
+  into a codejitsu setup commit. Separate concerns.
+- **Don't** wholesale-replace a site's existing `Head.astro` if it has
+  custom site-specific things (analytics, fonts, etc.). Selectively migrate
+  the JSON-LD injection + schema builder calls.
+- **Don't** modify `src/pages/*` unless necessary. The backward-compat
+  exports in `src/lib/blog.ts` mean page code usually doesn't need changes.
+- **Don't** commit the deploy hook URL to git. Use `gh secret set`.
+- **Don't** set `recaptcha` in the contact config unless EmailJS's
+  server-side verification is enabled — otherwise it's just friction.
+  See `modules/contact/CLAUDE.md`.
+- **Don't** push without explicit user permission. Per the user's global rule.
+
+---
+
+## Greenfield-specific shortcuts
+
+For brand-new sites, after Step 2 (install):
+
+```bash
+npm create astro@latest --template minimal --typescript strict --yes
+# Then steps 3 through 11
+```
+
+The greenfield path is simpler because there's nothing to migrate — every
+file is new from a template.
+
+For greenfield blog setup specifically:
+
+```bash
+# Astro CC schema
+cp node_modules/@ibalzam/codejitsu-core/modules/blog/templates/content.config.ts src/
+
+# Page routes
+mkdir -p src/pages/blog
+cp -r node_modules/@ibalzam/codejitsu-core/modules/blog/templates/pages/blog/ src/pages/
+
+# Sample post
+cp node_modules/@ibalzam/codejitsu-core/modules/blog/templates/content/_sample-post.md src/content/blog/welcome.md
+```
+
+---
+
+## When done
+
+The site should pass:
+- `npm run build` → 0 errors
+- `npx codejitsu doctor` → all deps current
+- `npx codejitsu audit` → 0 fail
+- Browser smoke test: open `npm run dev`, click through home + blog + contact
+
+Hand back to the user with the audit + doctor summaries. Don't push until
+they say "push".

package/bin/codejitsu.mjs

@@ -3,6 +3,7 @@ import { parseArgs } from 'node:util';
 import { runBlog } from '../modules/cli/src/blog.mjs';
 import { runDeploySetup, runDeployTrigger } from '../modules/cli/src/deploy.mjs';
 import { runDoctor } from '../modules/cli/src/doctor.mjs';
+import { runBlogInit } from '../modules/cli/src/blog-init.mjs';
 import { runAudit } from '../modules/audit/src/run.mjs';
 
 const subcommand = process.argv[2];
@@ -11,6 +12,7 @@ const rest = process.argv.slice(3);
 const COMMANDS = {
   'blog:list': () => runBlog('blog:list'),
   'blog:drafts': () => runBlog('blog:drafts'),
+  'blog:init': () => runBlogInit(),
   'deploy:setup': () => runDeploySetup(),
   'deploy:run': () => runDeployTrigger(),
   doctor: () => runDoctor(),
@@ -56,6 +58,7 @@ function printHelp() {
   console.log(`Subcommands:`);
   console.log(`  blog:list           List every non-draft post with URL + image check`);
   console.log(`  blog:drafts         List future-dated (pending) posts only`);
+  console.log(`  blog:init           Install /blog, /blog-batch, /blog-images slash commands`);
   console.log(``);
   console.log(`  deploy:setup        Wire up daily Cloudflare deploy (prompts for hook URL)`);
   console.log(`  deploy:run          Trigger the Daily Deploy workflow once now`);

package/modules/blog-writer/BLOG_BATCH.md

@@ -0,0 +1,142 @@
+# Blog batch generation — Claude playbook
+
+> Triggered when the user runs `/blog-batch <N>` in a Codejitsu site
+> (default N = 20).
+>
+> Generates a **schedule + outline** for N future-dated posts. It does NOT
+> write the full body of every post — that's `/blog` per row. The goal here
+> is to produce a publishable roadmap that the user reviews + edits before
+> any prose is committed.
+
+## Step 0 — Read site config
+
+Same as `BLOG_WRITING.md` Step 0: load `codejitsu.config.ts.blogWriter`.
+
+Also read:
+- `src/content/blog/` — existing posts (find the latest `pubDate`)
+- `src/content.config.ts` — confirm the schema shape
+
+## Step 1 — Decide cadence
+
+Default cadence is **4 days between posts** (matches workzen / pearl /
+veteran). If existing posts have a different rhythm, infer from the last
+10 and match it.
+
+Starting date = max(`latest existing pubDate`, today) + cadence.
+
+## Step 2 — Generate N topics
+
+Brainstorm `N` topics, balancing across:
+
+- **Service × location** combinations — cycle through `services` and
+  `locations` from config so coverage is even
+- **Topic format** mix — roughly:
+  - 30% comparison / "X vs Y" posts
+  - 30% how-to / guides
+  - 20% troubleshooting
+  - 20% seasonal / news
+- **Season awareness** — apply `seasonalRules` from config. A post landing
+  in July shouldn't be about "winterize"; one in December shouldn't be
+  about "pre-summer".
+- **Unique titles** — no two posts in the batch should target the same slug
+  or near-duplicate keyword. Read all existing post titles before
+  brainstorming to avoid collisions.
+- **Approved tag balance** — distribute tags so no single tag is over 40% of
+  the batch.
+
+For each topic, derive:
+- `slug` — kebab-case, includes the city when applicable
+- `title` — natural, clickable, ≤70 chars
+- `pubDate` — assigned by cadence walk
+- `tags` — 2-3 from `approvedTags`, primary first
+- `service` + `city` — for internal-link planning
+
+## Step 3 — Produce the schedule table
+
+Write to `Blog/BLOG_SCHEDULE.md` (create the `Blog/` directory if needed).
+Append to it if it already exists — never overwrite without asking.
+
+Format:
+
+```markdown
+# <Site Name> — Blog Schedule (<start month> - <end month> <year>)
+
+Offline publishing calendar. N posts on a <cadence>-day cadence,
+<start date> through <end date>.
+
+## How to use
+
+1. Pick a row. Slug = filename → `src/content/blog/<slug>.md`.
+2. `pubDate: <date>` in frontmatter controls visibility.
+3. Run `/blog "<title>"` to flesh out the post body.
+4. Run `/blog-images` once a batch of posts is drafted.
+
+## Schedule
+
+| # | Date       | Category       | City      | Slug | Title |
+|---|------------|----------------|-----------|------|-------|
+| 1 | YYYY-MM-DD | <primary tag>  | <city>    | `<slug>` | <Title> |
+| 2 | ...        | ...            | ...       | ...      | ...     |
+```
+
+## Step 4 — Produce per-post outlines
+
+In the same file or a sibling `Blog/BLOG_OUTLINES.md`, expand each row into
+an outline:
+
+```markdown
+## <Slug>
+
+**pubDate**: YYYY-MM-DD
+**target words**: <from config.wordCount.default>
+**tags**: [primary, secondary]
+**service**: <slug>
+**city**: <slug or 'general'>
+
+**Angle / hook**: <one-sentence framing of the reader's pain>
+
+**Outline**:
+- Intro — 1-2 paragraphs hooking <hook>
+- ## <H2 #1>
+  - 2-3 paragraphs covering <points>
+- ## <H2 #2>
+  - Comparison table of <X vs Y>
+- ## <H2 #3>
+  - ...
+- Closing CTA + 5-8 FAQs
+
+**FAQ seeds**: list of 5-8 question stems
+```
+
+## Step 5 — Show + approve
+
+Present the full schedule + outline file to the user. Ask:
+
+> "Here's the schedule. Anything to adjust before we lock it in?
+>  Want me to flesh out the first N posts now, or stop here for review?"
+
+If the user says go: run `/blog` for each row (one post at a time). If they
+say stop: leave the file and exit. They can run `/blog` row by row whenever.
+
+## Hard rules
+
+- **Don't write the full prose for all N in one shot.** Too long, too
+  expensive, hard to review. Schedule + outlines first; prose per row on
+  demand.
+- **Don't push or commit.** The user reviews + commits.
+- **Respect existing posts.** If `Blog/BLOG_SCHEDULE.md` already has rows,
+  append the new batch and don't renumber.
+- **Don't invent services or locations.** Use only what's in
+  `blogWriter.services` and `blogWriter.locations`.
+- **Don't invent tags.** Only from `approvedTags`.
+- **Don't bunch up topic types.** Reject your own first draft if it has 5
+  comparison posts in a row.
+
+## Verify
+
+- [ ] N rows, all unique slugs
+- [ ] Dates respect cadence; no collisions with existing posts
+- [ ] Tags balanced across `approvedTags`
+- [ ] Service + city distribution covers most of the config lists
+- [ ] Season fits each `pubDate`'s month
+- [ ] No duplicate or near-duplicate topics