@ibalzam/codejitsu-core 0.5.0 → 0.7.0

package/bin/codejitsu.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { runBlog } from '../modules/cli/src/blog.mjs';
+import { runDeploySetup } from '../modules/cli/src/deploy.mjs';
 import { runAudit } from '../modules/audit/src/run.mjs';
 
 const subcommand = process.argv[2];
@@ -9,6 +10,7 @@ const rest = process.argv.slice(3);
 const COMMANDS = {
   'blog:list': () => runBlog('blog:list'),
   'blog:drafts': () => runBlog('blog:drafts'),
+  'deploy:setup': () => runDeploySetup(),
   audit: () => {
     const { values } = parseArgs({
       args: rest,
@@ -52,6 +54,8 @@ function printHelp() {
   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(``);
+  console.log(`  deploy:setup        Wire up daily Cloudflare deploy (prompts for hook URL)`);
+  console.log(``);
   console.log(`  audit               Run pre-delivery audit. Flags:`);
   console.log(`    --live <url>      Add live-URL checks (SSL, headers, 404, broken links)`);
   console.log(`    --a11y            Add axe-core WCAG 2.1 AA scan (with --live)`);

package/modules/audit/src/groups/forms.mjs

@@ -92,6 +92,16 @@ export async function runForms(ctx) {
     );
   }
 
+  // Static-site reCAPTCHA reminder. We can't check EmailJS's dashboard from
+  // here, but we can flag the assumption so the human verifies it.
+  const recaptchaForms = forms.filter((x) => x.hasCaptcha);
+  if (recaptchaForms.length > 0) {
+    results.push(info(
+      `${recaptchaForms.length} form(s) use reCAPTCHA`,
+      'Verify EmailJS template has "Verify reCAPTCHA" toggle ON with the SECRET key — otherwise the widget is theater on a static site (no server-side validation).'
+    ));
+  }
+
   // Consent (if required).
   if (formCfg.requireConsent === true) {
     const noConsent = forms.filter((x) => !x.hasConsent);

package/modules/audit/src/groups/structure.mjs

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { spawn } from 'child_process';
 import { pass, fail, warn, info } from '../util.mjs';
 
 export async function runStructure(ctx) {
@@ -51,11 +52,40 @@ export async function runStructure(ctx) {
         ? pass('wrangler.toml at site root')
         : fail('wrangler.toml missing')
     );
+    const workflowExists = fs.existsSync(path.join(cwd, '.github/workflows/daily-deploy.yml'));
     results.push(
-      fs.existsSync(path.join(cwd, '.github/workflows/daily-deploy.yml'))
+      workflowExists
         ? pass('Daily deploy workflow present')
         : warn('No .github/workflows/daily-deploy.yml')
     );
+
+    // Daily deploy needs CLOUDFLARE_DEPLOY_HOOK_URL set as a GH secret.
+    // We can only verify this via `gh secret list`. Skip silently if gh is
+    // unavailable; only run when the workflow file exists (otherwise the
+    // secret is moot).
+    if (workflowExists) {
+      const repo = detectGitHubRepo(cwd);
+      if (!repo) {
+        results.push(info('Skipped GH secret check (no GitHub remote detected)'));
+      } else {
+        const ghAvailable = await commandExists('gh');
+        if (!ghAvailable) {
+          results.push(info('Skipped GH secret check (gh CLI not installed)'));
+        } else {
+          const secrets = await listSecrets(repo);
+          if (secrets === null) {
+            results.push(info('Skipped GH secret check (gh not authenticated for this repo)'));
+          } else if (secrets.includes('CLOUDFLARE_DEPLOY_HOOK_URL')) {
+            results.push(pass(`CLOUDFLARE_DEPLOY_HOOK_URL set in ${repo}`));
+          } else {
+            results.push(warn(
+              'CLOUDFLARE_DEPLOY_HOOK_URL secret missing',
+              'Daily deploy workflow will fail. Run `npx codejitsu deploy:setup` to configure.'
+            ));
+          }
+        }
+      }
+    }
   }
 
   // Astro config sanity + trailing-slash plugin agreement
@@ -103,3 +133,32 @@ export async function runStructure(ctx) {
 
   return results;
 }
+
+function detectGitHubRepo(cwd) {
+  const cfgPath = path.join(cwd, '.git/config');
+  if (!fs.existsSync(cfgPath)) return null;
+  const cfg = fs.readFileSync(cfgPath, 'utf8');
+  const m = cfg.match(/github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/m);
+  return m ? m[1] : null;
+}
+
+function commandExists(cmd) {
+  return new Promise((resolve) => {
+    const proc = spawn('which', [cmd], { stdio: 'ignore' });
+    proc.on('close', (code) => resolve(code === 0));
+    proc.on('error', () => resolve(false));
+  });
+}
+
+function listSecrets(repo) {
+  return new Promise((resolve) => {
+    const proc = spawn('gh', ['secret', 'list', '--repo', repo], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    proc.stdout.on('data', (d) => { stdout += d.toString(); });
+    proc.on('close', (code) => {
+      if (code !== 0) return resolve(null);
+      resolve(stdout.split('\n').map((l) => l.split(/\s+/)[0]).filter(Boolean));
+    });
+    proc.on('error', () => resolve(null));
+  });
+}

package/modules/cli/src/deploy.mjs

@@ -0,0 +1,210 @@
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { spawn } from 'child_process';
+import { loadConfig, isModuleEnabled } from '../../config/src/load.mjs';
+import { c } from './format.mjs';
+
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(new URL(import.meta.url).pathname),
+  '..', '..', '..'
+);
+
+/**
+ * `codejitsu deploy:setup` — interactive wizard for Cloudflare Pages + daily
+ * deploy hook. Copies the workflow + wrangler templates, prompts for the
+ * Cloudflare deploy hook URL, and stores it as a GitHub Actions secret.
+ *
+ * Idempotent: re-running with everything already in place is a no-op (just
+ * verifies state).
+ */
+export async function runDeploySetup() {
+  const cwd = process.cwd();
+
+  let config;
+  try { config = await loadConfig(cwd); }
+  catch (err) {
+    console.error(c.red('✗ No codejitsu.config found in ' + cwd));
+    process.exit(1);
+  }
+
+  if (!isModuleEnabled(config, 'deploy')) {
+    console.error(c.red('✗ deploy module is disabled in codejitsu.config'));
+    process.exit(1);
+  }
+
+  console.log(c.bold('\nCodejitsu Deploy Setup\n'));
+
+  // ─── Detect environment ──────────────────────────────────────────────
+  if (!fs.existsSync(path.join(cwd, '.git'))) {
+    console.error(c.red('✗ Not a git repository. Initialise git first.'));
+    process.exit(1);
+  }
+
+  const repo = detectGitHubRepo(cwd);
+  if (!repo) {
+    console.error(c.red('✗ Could not detect GitHub repo from git remote.'));
+    console.error('  Set up: git remote add origin git@github.com:owner/name.git');
+    process.exit(1);
+  }
+  console.log(c.green('✓') + ` GitHub repo: ${c.bold(repo)}`);
+
+  const ghAvailable = await commandExists('gh');
+  if (!ghAvailable) {
+    console.error(c.red('✗ `gh` CLI not in PATH.'));
+    console.error('  Install: https://cli.github.com/');
+    process.exit(1);
+  }
+  const ghAuthed = await ghIsAuthed();
+  if (!ghAuthed) {
+    console.error(c.red('✗ `gh` not authenticated.'));
+    console.error('  Run: gh auth login');
+    process.exit(1);
+  }
+  console.log(c.green('✓') + ' gh CLI authenticated');
+
+  const pagesName = config.deploy?.cloudflarePagesName;
+  if (pagesName) console.log(c.green('✓') + ` Cloudflare Pages name: ${c.bold(pagesName)}`);
+  else console.log(c.yellow('!') + ' No deploy.cloudflarePagesName in codejitsu.config (wrangler.toml will need a manual name)');
+
+  // ─── Workflow + wrangler files ───────────────────────────────────────
+  console.log('\nChecking files…');
+
+  const workflowDest = path.join(cwd, '.github/workflows/daily-deploy.yml');
+  const wranglerDest = path.join(cwd, 'wrangler.toml');
+
+  if (fs.existsSync(workflowDest)) {
+    console.log(c.green('✓') + ' .github/workflows/daily-deploy.yml exists');
+  } else {
+    const workflowSrc = path.join(PACKAGE_ROOT, 'modules/deploy/templates/daily-deploy.yml');
+    fs.mkdirSync(path.dirname(workflowDest), { recursive: true });
+    fs.copyFileSync(workflowSrc, workflowDest);
+    console.log(c.green('+') + ' Created .github/workflows/daily-deploy.yml');
+  }
+
+  if (fs.existsSync(wranglerDest)) {
+    console.log(c.green('✓') + ' wrangler.toml exists');
+  } else {
+    const wranglerSrc = path.join(PACKAGE_ROOT, 'modules/deploy/templates/wrangler.toml');
+    let contents = fs.readFileSync(wranglerSrc, 'utf8');
+    if (pagesName) contents = contents.replace('TODO-site-name', pagesName);
+    fs.writeFileSync(wranglerDest, contents);
+    console.log(c.green('+') + ' Created wrangler.toml' + (pagesName ? '' : ' (edit `name` field)'));
+  }
+
+  // ─── GitHub secret ───────────────────────────────────────────────────
+  console.log('\nChecking GitHub Actions secrets…');
+  const secrets = await listSecrets(repo);
+  const hasSecret = secrets.includes('CLOUDFLARE_DEPLOY_HOOK_URL');
+
+  if (hasSecret) {
+    console.log(c.green('✓') + ' CLOUDFLARE_DEPLOY_HOOK_URL is set');
+    const rotate = await prompt('\nRotate the deploy hook URL? [y/N]: ');
+    if (!/^y(es)?$/i.test(rotate.trim())) {
+      console.log(c.gray('\nNothing to do. The daily deploy is configured.\n'));
+      await offerTestRun(repo);
+      return;
+    }
+  }
+
+  // Prompt for URL.
+  console.log('');
+  console.log('Get a deploy hook URL from Cloudflare Pages:');
+  console.log(c.gray('  1. Open Cloudflare dashboard → Pages → ' + (pagesName ?? 'your project') + ' → Settings'));
+  console.log(c.gray('  2. Builds & deployments → Deploy hooks → "Add deploy hook"'));
+  console.log(c.gray('  3. Name: "daily-scheduled-content" — Branch: main'));
+  console.log(c.gray('  4. Copy the URL'));
+  console.log('');
+
+  const url = (await prompt('Paste the deploy hook URL: ')).trim();
+  if (!url.startsWith('https://api.cloudflare.com/client/v4/pages/webhooks/deploy_hooks/')) {
+    console.error(c.red('\n✗ That doesn\'t look like a Cloudflare Pages deploy hook URL.'));
+    console.error('  Expected prefix: https://api.cloudflare.com/client/v4/pages/webhooks/deploy_hooks/');
+    process.exit(1);
+  }
+
+  const setOk = await setSecret(repo, 'CLOUDFLARE_DEPLOY_HOOK_URL', url);
+  if (!setOk) {
+    console.error(c.red('\n✗ Failed to set GitHub secret.'));
+    process.exit(1);
+  }
+  console.log(c.green('✓') + ` Secret CLOUDFLARE_DEPLOY_HOOK_URL set in ${repo}`);
+
+  await offerTestRun(repo);
+}
+
+async function offerTestRun(repo) {
+  const test = await prompt('\nTrigger the workflow once now to test? [y/N]: ');
+  if (!/^y(es)?$/i.test(test.trim())) {
+    console.log(c.gray('\nDone. Daily deploy fires at 13:00 UTC (06:00 PDT / 05:00 PST).\n'));
+    return;
+  }
+  const result = await runGh(['workflow', 'run', 'Daily Deploy', '--repo', repo]);
+  if (result.code === 0) {
+    console.log(c.green('✓') + ' Workflow "Daily Deploy" triggered');
+    console.log(c.gray('  Watch: ') + c.gray(`https://github.com/${repo}/actions`));
+  } else {
+    console.error(c.yellow('!') + ' Could not trigger workflow: ' + result.stderr.trim());
+    console.error('  You can trigger it manually from the GitHub Actions tab.');
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function detectGitHubRepo(cwd) {
+  const cfgPath = path.join(cwd, '.git/config');
+  if (!fs.existsSync(cfgPath)) return null;
+  const cfg = fs.readFileSync(cfgPath, 'utf8');
+  // Match SSH (git@github.com:owner/repo.git) and HTTPS (https://github.com/owner/repo.git)
+  const m = cfg.match(/github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/m);
+  return m ? m[1] : null;
+}
+
+function commandExists(cmd) {
+  return new Promise((resolve) => {
+    const proc = spawn('which', [cmd], { stdio: 'ignore' });
+    proc.on('close', (code) => resolve(code === 0));
+    proc.on('error', () => resolve(false));
+  });
+}
+
+async function ghIsAuthed() {
+  const r = await runGh(['auth', 'status']);
+  return r.code === 0;
+}
+
+async function listSecrets(repo) {
+  const r = await runGh(['secret', 'list', '--repo', repo]);
+  if (r.code !== 0) return [];
+  return r.stdout
+    .split('\n')
+    .map((line) => line.split(/\s+/)[0])
+    .filter(Boolean);
+}
+
+async function setSecret(repo, name, value) {
+  const r = await runGh(['secret', 'set', name, '--repo', repo, '--body', value]);
+  return r.code === 0;
+}
+
+function runGh(args) {
+  return new Promise((resolve) => {
+    const proc = spawn('gh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => { stdout += d.toString(); });
+    proc.stderr.on('data', (d) => { stderr += d.toString(); });
+    proc.on('close', (code) => resolve({ code, stdout, stderr }));
+    proc.on('error', (err) => resolve({ code: 1, stdout: '', stderr: err.message }));
+  });
+}
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}

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

@@ -14,8 +14,24 @@ export interface CodejitsuConfig {
     images?: ImagesConfig | false;
     llms?: LlmsConfig | false;
     deploy?: DeployConfig | false;
+    contact?: ContactConfig | false;
     audit?: AuditConfig;
 }
+export interface ContactConfig {
+    enabled?: boolean;
+    emailjs: {
+        /** EmailJS service ID, e.g. 'service_abc123'. */
+        serviceId: string;
+        /** EmailJS template ID, e.g. 'template_xyz789'. Template variables must be {{name}}, {{email}}, {{phone}}, {{message}}. */
+        templateId: string;
+        /** EmailJS public key. Safe to ship to the browser. */
+        publicKey: string;
+    };
+    /** Optional reCAPTCHA v2 sitekey. If set, the modal renders a captcha widget and blocks submit until solved. */
+    recaptcha?: {
+        siteKey: string;
+    };
+}
 export interface AuditConfig {
     /** Per-provider requirement. 'optional' = pass either way; 'required' = fail if absent; 'banned' = fail if present. */
     analytics?: {

package/modules/config/src/types.ts

@@ -15,9 +15,26 @@ export interface CodejitsuConfig {
   images?: ImagesConfig | false;
   llms?: LlmsConfig | false;
   deploy?: DeployConfig | false;
+  contact?: ContactConfig | false;
   audit?: AuditConfig;
 }
 
+export interface ContactConfig {
+  enabled?: boolean;
+  emailjs: {
+    /** EmailJS service ID, e.g. 'service_abc123'. */
+    serviceId: string;
+    /** EmailJS template ID, e.g. 'template_xyz789'. Template variables must be {{name}}, {{email}}, {{phone}}, {{message}}. */
+    templateId: string;
+    /** EmailJS public key. Safe to ship to the browser. */
+    publicKey: string;
+  };
+  /** Optional reCAPTCHA v2 sitekey. If set, the modal renders a captcha widget and blocks submit until solved. */
+  recaptcha?: {
+    siteKey: string;
+  };
+}
+
 export interface AuditConfig {
   /** Per-provider requirement. 'optional' = pass either way; 'required' = fail if absent; 'banned' = fail if present. */
   analytics?: {

package/modules/contact/CLAUDE.md

@@ -0,0 +1,164 @@
+# Contact module — instructions for Claude
+
+When the user asks to **add a contact form** (or quote modal, lead capture, "implement codejitsu/core/contact"), do the following.
+
+## What this module provides
+
+A single, accessible contact modal component that:
+
+- Renders a centered modal with optional left-side image
+- Configurable fields (name, email, phone, message) — each enabled/required
+- Configurable title, submit button text, thank-you toast
+- HTML5 validation + custom hidden honeypot
+- Optional Google reCAPTCHA v2
+- Submits via [EmailJS](https://www.emailjs.com/) (`emailjs.sendForm`)
+- Dispatches `codejitsu-contact-submitted` event on success (sites wire analytics)
+- Full focus trap, Esc to close, backdrop click, focus restoration
+
+One modal per page (per id). Triggered from any `<button data-codejitsu-contact-trigger>` element.
+
+## Wiring it into an Astro site
+
+### 1. Set up EmailJS
+
+(Site owner does this once, not Claude.) Sign up at https://www.emailjs.com/, create:
+- a service (e.g. Gmail, SMTP)
+- a template that uses these template variables: `{{name}}`, `{{email}}`, `{{phone}}`, `{{message}}`
+- copy the service ID, template ID, and public key
+
+### 1a. CRITICAL — reCAPTCHA on a static site only works if EmailJS verifies it
+
+The modal shows the reCAPTCHA widget client-side, but **without server-side
+verification of the token, the widget is theater**. A static site has no server
+to run the verification. EmailJS provides this verification as a service — you
+must enable it explicitly:
+
+1. EmailJS dashboard → **Email Templates** → your template → **Settings** tab
+2. Toggle **"Verify reCAPTCHA"** on
+3. Paste your reCAPTCHA **secret key** (NOT the sitekey — the secret key, found
+   alongside the sitekey in Google's reCAPTCHA admin)
+4. Save
+
+Now EmailJS rejects submissions with invalid tokens before sending the email.
+
+If you SKIP this step, leave reCAPTCHA out of the modal entirely. Use the
+honeypot (always on) + EmailJS rate limits as your spam defense. A
+non-verified reCAPTCHA widget is friction with no real benefit and breaks on
+localhost during dev.
+
+### 2. Drop the modal into a layout
+
+In a layout that wraps every page (e.g. `src/layouts/BaseLayout.astro`), import and place the component **once**, anywhere inside `<body>` (typically just before `</body>`):
+
+```astro
+---
+import ContactModal from '@ibalzam/codejitsu-core/contact/ContactModal.astro';
+import config from '../../codejitsu.config';
+---
+
+<!-- ... existing layout content ... -->
+
+<ContactModal
+  title="Get a Free Quote"
+  image={{ src: '/assets/images/contact.webp', alt: 'Our team' }}
+  fields={{
+    name:    { required: true },
+    email:   { required: true },
+    phone:   { required: true },
+    message: { required: false },
+  }}
+  submitText="Submit Quote Request"
+  thankYouMessage="Thanks! We'll be in touch within 24 hours."
+  emailjs={{
+    serviceId: config.contact.emailjs.serviceId,
+    templateId: config.contact.emailjs.templateId,
+    publicKey: config.contact.emailjs.publicKey,
+  }}
+  recaptcha={config.contact.recaptcha}
+/>
+```
+
+Pass the EmailJS keys via `codejitsu.config.ts` so they're declared once, not hardcoded in every layout.
+
+### 3. Add EmailJS keys to `codejitsu.config.ts`
+
+```ts
+import { defineConfig } from '@ibalzam/codejitsu-core/config';
+
+export default defineConfig({
+  // ...
+  contact: {
+    emailjs: {
+      serviceId: 'service_xxx',
+      templateId: 'template_xxx',
+      publicKey: 'xxx',          // safe to ship to browser (public)
+    },
+    recaptcha: {
+      siteKey: '6Lxxxxxxxxxxxxxxx',  // optional
+    },
+  },
+});
+```
+
+### 4. Add triggers anywhere
+
+Any clickable element with `data-codejitsu-contact-trigger`:
+
+```html
+<button data-codejitsu-contact-trigger>Get a quote</button>
+<a href="#contact" data-codejitsu-contact-trigger>Talk to us</a>
+```
+
+### 5. Optional: wire analytics
+
+The component dispatches a `codejitsu-contact-submitted` event on success. Add a listener for GA4 / Google Ads / etc.:
+
+```html
+<script is:inline>
+  window.addEventListener('codejitsu-contact-submitted', (e) => {
+    // e.detail = { modalId, formData: { name, email, phone, message } }
+    if (typeof gtag === 'function') {
+      gtag('event', 'conversion', { send_to: 'AW-XXXXXXXX/XXXXXX' });
+    }
+  });
+</script>
+```
+
+The component itself stays generic — no analytics inside it.
+
+## Theming
+
+The component uses Tailwind classes for layout and CSS variables for brand colors. Set on `:root` in your global CSS:
+
+```css
+:root {
+  --codejitsu-modal-accent: #YOUR_BRAND;        /* button bg + focus ring */
+  --codejitsu-modal-accent-hover: #DARKER;
+  --codejitsu-modal-on-accent: #ffffff;          /* text on the button */
+}
+```
+
+If you don't set them, defaults are blue (`#2563eb`).
+
+## What must NOT be done
+
+- **Don't put the modal in every page** — put it in a single layout that wraps all pages. Multiple instances per page break (duplicate DOM ids).
+- **Don't hardcode EmailJS keys in the component invocation.** Read from `codejitsu.config.ts` so rotating keys touches one file.
+- **Don't put `secretKey` or sensitive EmailJS values in the config.** Only the public key is safe to ship to the browser. EmailJS Service ID + Template ID + Public Key are all public.
+- **Don't disable the honeypot.** It's invisible to humans and catches a meaningful slice of bot submissions for free.
+- **Don't add analytics calls inside the modal.** Use the `codejitsu-contact-submitted` event from outside.
+- **Don't replace the focus trap or Esc handler with custom logic.** Both are accessibility-required.
+
+## Verify
+
+- [ ] Modal opens when trigger clicked (any `data-codejitsu-contact-trigger`)
+- [ ] Esc closes it
+- [ ] Backdrop click closes it
+- [ ] Tab cycles within the modal (focus trap)
+- [ ] Required fields show `*` and HTML5 validation fires on empty submit
+- [ ] Submit calls EmailJS and shows toast on success
+- [ ] On submit success, `codejitsu-contact-submitted` event fires
+- [ ] reCAPTCHA (if configured) blocks submit until completed
+- [ ] Honeypot field is visually hidden (off-screen) and not focusable
+
+Run `npx codejitsu audit` — the Forms group will detect the modal, count its fields, verify the JS submit hook is present.

package/modules/contact/checklist.md

@@ -0,0 +1,35 @@
+# Contact module — checklist
+
+## Setup
+
+- [ ] `codejitsu.config.ts` has a `contact.emailjs` block with serviceId, templateId, publicKey.
+- [ ] (Optional) `contact.recaptcha.siteKey` set if site uses reCAPTCHA.
+- [ ] EmailJS template variables match what the modal sends: `name`, `email`, `phone`, `message`.
+
+## Wiring
+
+- [ ] Exactly **one** `<ContactModal>` per page (placed in a layout that wraps every page).
+- [ ] At least one trigger exists with `data-codejitsu-contact-trigger`.
+- [ ] (If site has GA4/Ads) A `codejitsu-contact-submitted` event listener fires the conversion.
+
+## Behaviour (manual or browser-tested)
+
+- [ ] Modal opens when trigger clicked.
+- [ ] Esc closes it.
+- [ ] Backdrop click closes it.
+- [ ] Tab cycles within the modal (focus trap).
+- [ ] First field gets focus when opened.
+- [ ] Required fields show `*` and HTML5 validation blocks empty submit.
+- [ ] Submit shows "Sending…" state on the button.
+- [ ] Successful submit shows the thank-you toast.
+- [ ] Failed submit shows an error alert.
+
+## Spam protection
+
+- [ ] Honeypot input present at `name="cj_hp_website"`, off-screen, `tabindex="-1"`.
+- [ ] If reCAPTCHA configured: widget visible inside the form, submit blocked until solved.
+
+## Theming
+
+- [ ] Site's `:root` CSS sets `--codejitsu-modal-accent` (otherwise it uses default blue).
+- [ ] Modal's image (if used) is in `public/` and < 200KB.

package/modules/contact/templates/ContactModal.astro

@@ -0,0 +1,420 @@
+---
+/**
+ * Codejitsu contact modal.
+ *
+ * Drop one instance into a layout that wraps every page (e.g. BaseLayout).
+ * Trigger from anywhere with:
+ *
+ *   <button data-codejitsu-contact-trigger>Get a quote</button>
+ *
+ * On success: dispatches a `codejitsu-contact-submitted` custom event on
+ * `window`. Sites add their own listener for analytics (GA4 conversion,
+ * Google Ads, etc.) so this component stays generic.
+ *
+ * Theming via CSS variables (set on `:root` in your global CSS):
+ *   --codejitsu-modal-accent          (focus ring + button bg; default #2563eb)
+ *   --codejitsu-modal-accent-hover    (default #1d4ed8)
+ *   --codejitsu-modal-on-accent       (text on button; default #ffffff)
+ */
+
+interface FieldProps {
+  enabled?: boolean;
+  required?: boolean;
+  label?: string;
+  placeholder?: string;
+}
+
+interface Props {
+  /** Unique id (lets multiple modals coexist if ever needed). Default 'codejitsu-contact'. */
+  id?: string;
+  title: string;
+  image?: {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+  };
+  fields?: {
+    name?: FieldProps;
+    email?: FieldProps;
+    phone?: FieldProps;
+    message?: FieldProps;
+  };
+  submitText?: string;
+  thankYouMessage?: string;
+  emailjs: {
+    serviceId: string;
+    templateId: string;
+    publicKey: string;
+  };
+  recaptcha?: { siteKey: string };
+}
+
+const {
+  id = 'codejitsu-contact',
+  title,
+  image,
+  fields = {},
+  submitText = 'Send Message',
+  thankYouMessage = "Thanks! We'll get back to you shortly.",
+  emailjs,
+  recaptcha,
+} = Astro.props as Props;
+
+// Field defaults — all fields enabled, name+email+phone required, message optional.
+const f = {
+  name:    { enabled: true,  required: true,  label: 'Name',    placeholder: 'Your full name',          ...fields.name },
+  email:   { enabled: true,  required: true,  label: 'Email',   placeholder: 'you@email.com',           ...fields.email },
+  phone:   { enabled: true,  required: true,  label: 'Phone',   placeholder: '(xxx) xxx-xxxx',          ...fields.phone },
+  message: { enabled: true,  required: false, label: 'Message', placeholder: 'How can we help?',        ...fields.message },
+};
+
+const overlayId = `${id}-overlay`;
+const cardId = `${id}-card`;
+const closeId = `${id}-close`;
+const formId = `${id}-form`;
+const toastId = `${id}-toast`;
+const titleId = `${id}-title`;
+
+const config = {
+  serviceId: emailjs.serviceId,
+  templateId: emailjs.templateId,
+  publicKey: emailjs.publicKey,
+  recaptchaSiteKey: recaptcha?.siteKey ?? null,
+};
+---
+
+<div
+  id={overlayId}
+  class="cj-modal-overlay fixed inset-0 z-[100] flex items-center justify-center bg-black/60 backdrop-blur-sm opacity-0 pointer-events-none transition-opacity duration-300"
+  aria-hidden="true"
+  inert
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby={titleId}
+>
+  <div
+    id={cardId}
+    class="bg-white rounded-2xl shadow-2xl w-full max-w-3xl mx-4 max-h-[90vh] overflow-y-auto p-6 sm:p-8 transform scale-95 transition-transform duration-300"
+  >
+    <div class="flex items-center justify-between mb-4">
+      <h2 id={titleId} class="text-xl font-bold text-gray-900">{title}</h2>
+      <button
+        type="button"
+        id={closeId}
+        class="text-gray-400 hover:text-gray-700 transition-colors p-1"
+        aria-label="Close modal"
+      >
+        <svg class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-hidden="true">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12"></path>
+        </svg>
+      </button>
+    </div>
+
+    <div class={image ? 'flex flex-col md:flex-row gap-6' : ''}>
+      {image && (
+        <div class="hidden md:block md:w-1/2 shrink-0">
+          <img
+            src={image.src}
+            alt={image.alt}
+            width={image.width ?? 600}
+            height={image.height ?? 600}
+            class="w-full h-full rounded-xl object-cover"
+            loading="lazy"
+          />
+        </div>
+      )}
+
+      <div class="flex-1">
+        <form id={formId} class="cj-emailjs-form space-y-4" novalidate>
+          {f.name.enabled && (
+            <div>
+              <label for={`${id}-name`} class="block text-sm font-medium text-gray-700 mb-1">
+                {f.name.label}{f.name.required && <span class="text-red-500"> *</span>}
+              </label>
+              <input
+                type="text"
+                id={`${id}-name`}
+                name="name"
+                required={f.name.required}
+                autocomplete="name"
+                class="cj-modal-input w-full border border-gray-300 rounded-lg px-4 py-2.5 text-gray-900 outline-none transition-shadow"
+                placeholder={f.name.placeholder}
+              />
+            </div>
+          )}
+
+          {f.email.enabled && (
+            <div>
+              <label for={`${id}-email`} class="block text-sm font-medium text-gray-700 mb-1">
+                {f.email.label}{f.email.required && <span class="text-red-500"> *</span>}
+              </label>
+              <input
+                type="email"
+                id={`${id}-email`}
+                name="email"
+                required={f.email.required}
+                autocomplete="email"
+                class="cj-modal-input w-full border border-gray-300 rounded-lg px-4 py-2.5 text-gray-900 outline-none transition-shadow"
+                placeholder={f.email.placeholder}
+              />
+            </div>
+          )}
+
+          {f.phone.enabled && (
+            <div>
+              <label for={`${id}-phone`} class="block text-sm font-medium text-gray-700 mb-1">
+                {f.phone.label}{f.phone.required && <span class="text-red-500"> *</span>}
+              </label>
+              <input
+                type="tel"
+                id={`${id}-phone`}
+                name="phone"
+                required={f.phone.required}
+                autocomplete="tel"
+                class="cj-modal-input w-full border border-gray-300 rounded-lg px-4 py-2.5 text-gray-900 outline-none transition-shadow"
+                placeholder={f.phone.placeholder}
+              />
+            </div>
+          )}
+
+          {f.message.enabled && (
+            <div>
+              <label for={`${id}-message`} class="block text-sm font-medium text-gray-700 mb-1">
+                {f.message.label}{f.message.required && <span class="text-red-500"> *</span>}
+              </label>
+              <textarea
+                id={`${id}-message`}
+                name="message"
+                required={f.message.required}
+                rows="3"
+                class="cj-modal-input w-full border border-gray-300 rounded-lg px-4 py-2.5 text-gray-900 outline-none transition-shadow resize-y"
+                placeholder={f.message.placeholder}
+              ></textarea>
+            </div>
+          )}
+
+          {/* Honeypot — bots fill this; humans don't see it */}
+          <div aria-hidden="true" style="position:absolute;left:-9999px;width:1px;height:1px;overflow:hidden;">
+            <label for={`${id}-website`}>Website (leave blank)</label>
+            <input type="text" id={`${id}-website`} name="cj_hp_website" tabindex="-1" autocomplete="off" />
+          </div>
+
+          {recaptcha && (
+            <div class="g-recaptcha" data-sitekey={recaptcha.siteKey}></div>
+          )}
+
+          <button
+            type="submit"
+            class="cj-modal-submit w-full text-center font-semibold py-3 rounded-lg transition-colors"
+          >
+            {submitText}
+          </button>
+        </form>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div
+  id={toastId}
+  class="cj-modal-toast fixed bottom-6 right-6 z-[110] bg-green-600 text-white px-6 py-3 rounded-lg shadow-lg transform translate-y-20 opacity-0 transition-all duration-300 pointer-events-none"
+  role="status"
+  aria-live="polite"
+>
+  {thankYouMessage}
+</div>
+
+<style is:global>
+  :root {
+    --codejitsu-modal-accent: #2563eb;
+    --codejitsu-modal-accent-hover: #1d4ed8;
+    --codejitsu-modal-on-accent: #ffffff;
+  }
+  .cj-modal-input:focus {
+    border-color: var(--codejitsu-modal-accent);
+    box-shadow: 0 0 0 3px color-mix(in oklab, var(--codejitsu-modal-accent) 25%, transparent);
+  }
+  .cj-modal-submit {
+    background-color: var(--codejitsu-modal-accent);
+    color: var(--codejitsu-modal-on-accent);
+  }
+  .cj-modal-submit:hover:not(:disabled) {
+    background-color: var(--codejitsu-modal-accent-hover);
+  }
+  .cj-modal-submit:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+</style>
+
+{recaptcha && (
+  <script is:inline src="https://www.google.com/recaptcha/api.js" async defer></script>
+)}
+
+<script is:inline src="https://cdn.jsdelivr.net/npm/@emailjs/browser@4/dist/email.min.js"></script>
+<script is:inline define:vars={{ modalId: id, cfg: config }}>
+  // Per-modal IDs (one modal per page expected; this scopes to its DOM).
+  const overlay = document.getElementById(modalId + '-overlay');
+  const card = document.getElementById(modalId + '-card');
+  const closeBtn = document.getElementById(modalId + '-close');
+  const form = document.getElementById(modalId + '-form');
+  const toast = document.getElementById(modalId + '-toast');
+
+  if (!overlay || !card || !form) {
+    // Modal not present on this page; bail silently.
+  } else {
+    // Initialise EmailJS once per page load.
+    function initEmailJS() {
+      if (window.emailjs && !window.__cjEmailjsInitialized) {
+        window.emailjs.init({ publicKey: cfg.publicKey });
+        window.__cjEmailjsInitialized = true;
+      }
+    }
+    initEmailJS();
+    document.addEventListener('DOMContentLoaded', initEmailJS);
+
+    let previouslyFocused = null;
+
+    function getFocusable() {
+      return Array.from(card.querySelectorAll(
+        'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])'
+      ));
+    }
+
+    function open() {
+      previouslyFocused = document.activeElement;
+      overlay.classList.remove('opacity-0', 'pointer-events-none');
+      overlay.classList.add('opacity-100');
+      overlay.setAttribute('aria-hidden', 'false');
+      overlay.removeAttribute('inert');
+      card.classList.remove('scale-95');
+      card.classList.add('scale-100');
+      document.body.style.overflow = 'hidden';
+      setTimeout(function () {
+        const f = getFocusable();
+        if (f.length) f[0].focus();
+      }, 100);
+    }
+
+    function close() {
+      overlay.classList.add('opacity-0', 'pointer-events-none');
+      overlay.classList.remove('opacity-100');
+      overlay.setAttribute('aria-hidden', 'true');
+      overlay.setAttribute('inert', '');
+      card.classList.add('scale-95');
+      card.classList.remove('scale-100');
+      document.body.style.overflow = '';
+      if (previouslyFocused && previouslyFocused.focus) {
+        previouslyFocused.focus();
+        previouslyFocused = null;
+      }
+    }
+
+    function showToast() {
+      if (!toast) return;
+      toast.classList.remove('translate-y-20', 'opacity-0');
+      toast.classList.add('translate-y-0', 'opacity-100');
+      setTimeout(function () {
+        toast.classList.add('translate-y-20', 'opacity-0');
+        toast.classList.remove('translate-y-0', 'opacity-100');
+      }, 4000);
+    }
+
+    // Triggers: data-codejitsu-contact-trigger or data-codejitsu-contact-trigger="<id>".
+    document.addEventListener('click', function (e) {
+      const trigger = e.target.closest('[data-codejitsu-contact-trigger]');
+      if (trigger) {
+        const wanted = trigger.getAttribute('data-codejitsu-contact-trigger');
+        if (!wanted || wanted === modalId) {
+          e.preventDefault();
+          open();
+        }
+        return;
+      }
+      if (e.target.closest('#' + modalId + '-close')) {
+        close();
+        return;
+      }
+      if (e.target === overlay) close();
+    });
+
+    // Esc + focus trap.
+    document.addEventListener('keydown', function (e) {
+      if (overlay.classList.contains('pointer-events-none')) return;
+      if (e.key === 'Escape') { close(); return; }
+      if (e.key === 'Tab') {
+        const f = getFocusable();
+        if (!f.length) return;
+        const first = f[0], last = f[f.length - 1];
+        if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+        else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+      }
+    });
+
+    // Submit handler.
+    form.addEventListener('submit', function (e) {
+      e.preventDefault();
+
+      // Honeypot
+      const hp = form.querySelector('input[name="cj_hp_website"]');
+      if (hp && hp.value) {
+        // Bot detected — pretend success, don't actually send.
+        form.reset();
+        close();
+        showToast();
+        return;
+      }
+
+      if (!form.checkValidity()) {
+        form.reportValidity();
+        return;
+      }
+
+      if (cfg.recaptchaSiteKey) {
+        const captchaResponse = form.querySelector('textarea[name="g-recaptcha-response"]');
+        if (!captchaResponse || !captchaResponse.value) {
+          alert('Please complete the reCAPTCHA before submitting.');
+          return;
+        }
+      }
+
+      initEmailJS();
+      if (!window.emailjs) {
+        console.error('[codejitsu-contact] EmailJS SDK not loaded');
+        return;
+      }
+
+      const submitBtn = form.querySelector('button[type="submit"]');
+      const originalText = submitBtn ? submitBtn.textContent : '';
+      if (submitBtn) {
+        submitBtn.disabled = true;
+        submitBtn.textContent = 'Sending…';
+      }
+
+      window.emailjs.sendForm(cfg.serviceId, cfg.templateId, form).then(function () {
+        // Fire custom event for site-side analytics / conversion tracking.
+        window.dispatchEvent(new CustomEvent('codejitsu-contact-submitted', {
+          detail: {
+            modalId,
+            formData: Object.fromEntries(new FormData(form).entries()),
+          },
+        }));
+        form.reset();
+        close();
+        showToast();
+      }).catch(function (err) {
+        console.error('[codejitsu-contact] EmailJS send failed', err);
+        alert('Sorry, something went wrong. Please call us or try again.');
+      }).finally(function () {
+        if (submitBtn) {
+          submitBtn.disabled = false;
+          submitBtn.textContent = originalText;
+        }
+        if (window.grecaptcha && typeof window.grecaptcha.reset === 'function') {
+          try { window.grecaptcha.reset(); } catch (e) {}
+        }
+      });
+    });
+  }
+</script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibalzam/codejitsu-core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Shared core for Codejitsu Astro sites — reusable code and Claude-facing instructions for blog, SEO, images, deploy, and llms.txt.",
   "keywords": [
@@ -16,13 +16,13 @@
   ],
   "license": "MIT",
   "author": "Ika Balzam <ika@codejitsu.ca>",
-  "homepage": "https://github.com/ibalzam/codejitsu-site-kit#readme",
+  "homepage": "https://github.com/ikanc/codejitsu-site-kit#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ibalzam/codejitsu-site-kit.git"
+    "url": "git+https://github.com/ikanc/codejitsu-site-kit.git"
   },
   "bugs": {
-    "url": "https://github.com/ibalzam/codejitsu-site-kit/issues"
+    "url": "https://github.com/ikanc/codejitsu-site-kit/issues"
   },
   "engines": {
     "node": ">=20"
@@ -60,6 +60,7 @@
       "default": "./modules/seo/src/sitemap.js"
     },
     "./seo/Head.astro": "./modules/seo/templates/Head.astro",
+    "./contact/ContactModal.astro": "./modules/contact/templates/ContactModal.astro",
     "./rehype/trailing-slash": "./modules/rehype/src/trailing-slash.mjs",
     "./images": {
       "types": "./modules/images/src/index.d.ts",