the-grid-cc 1.3.0 → 1.5.0

package/.grid/plans/blog-block-05.md

@@ -0,0 +1,235 @@
+---
+cluster: james-weatherhead-blog
+block: 05
+type: execute
+wave: 3
+depends_on: [01, 03]
+files_modified: [src/pages/rss.xml.ts, src/utils/rss.ts]
+autonomous: true
+
+must_haves:
+  truths:
+    - "RSS feed is accessible at /rss.xml"
+    - "Feed contains all published blog posts"
+    - "Feed validates against RSS 2.0 specification"
+  artifacts:
+    - path: "src/pages/rss.xml.ts"
+      provides: "RSS feed endpoint"
+      exports: ["GET"]
+    - path: "src/utils/rss.ts"
+      provides: "RSS generation utility functions"
+      min_lines: 20
+  key_links:
+    - from: "rss.xml.ts"
+      to: "@astrojs/rss"
+      via: "rss() function import"
+      pattern: "import.*@astrojs/rss"
+    - from: "rss.xml.ts"
+      to: "getCollection('blog')"
+      via: "fetch posts for feed"
+      pattern: "getCollection\\('blog'\\)"
+---
+
+<objective>
+Implement RSS feed generation for blog posts using @astrojs/rss.
+
+Purpose: Provide RSS feed for readers who prefer feed readers (Feedly, NewsBlur, etc.).
+Output: Valid RSS 2.0 feed at /rss.xml with all published posts.
+</objective>
+
+<context>
+Dependencies:
+- Block 01: @astrojs/rss installed during project setup
+- Block 03: Blog content collection configured
+
+This block adds RSS feed support - a standard feature for technical blogs. Requirements explicitly mention "RSS feed" as a feature.
+
+RSS feeds are static XML files generated at build time. Astro's @astrojs/rss integration makes this straightforward - no complex logic needed.
+
+This block runs in parallel with Block 04 (wave 3) since there's no file overlap:
+- Block 04 modifies: pages (index, blog, about, tags)
+- Block 05 modifies: rss.xml.ts, utils/rss.ts
+</context>
+
+<threads>
+
+<thread type="auto">
+  <name>Thread 1: Create RSS feed endpoint</name>
+  <files>src/pages/rss.xml.ts</files>
+  <action>
+  Create RSS feed using @astrojs/rss integration:
+
+  1. Create src/pages/rss.xml.ts (note: .ts not .astro for API route)
+
+  2. Import dependencies:
+     ```ts
+     import rss from '@astrojs/rss';
+     import { getCollection } from 'astro:content';
+     import type { APIContext } from 'astro';
+     ```
+
+  3. Export GET function:
+     ```ts
+     export async function GET(context: APIContext) {
+       const posts = await getCollection('blog', ({ data }) => !data.draft);
+       const sortedPosts = posts.sort(
+         (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
+       );
+
+       return rss({
+         title: 'James Weatherhead Blog',
+         description: 'Technical writing on web development, DevOps, and software engineering',
+         site: context.site || 'https://jamesweatherhead.com',
+         items: sortedPosts.map(post => ({
+           title: post.data.title,
+           description: post.data.description,
+           pubDate: post.data.pubDate,
+           link: `/blog/${post.slug}/`,
+           categories: post.data.tags,
+         })),
+         customData: '<language>en-us</language>',
+       });
+     }
+     ```
+
+  4. Ensure astro.config.mjs has site URL set (required for RSS):
+     - If not set, use placeholder: https://jamesweatherhead.com
+
+  AVOID: Do not add full content to RSS (use description only for preview). Do not add custom XML transformations (use @astrojs/rss defaults). WHY: Full content RSS increases bandwidth and complexity; previews encourage click-through to site.
+  </action>
+  <verify>
+  Run: npm run build
+  Check: dist/rss.xml exists
+  Run: npm run preview
+  Visit: http://localhost:4321/rss.xml
+  Check: XML renders in browser with all posts
+  Validate: Use https://validator.w3.org/feed/ or RSS validator
+  </verify>
+  <done>
+  - rss.xml.ts exports GET function returning RSS feed
+  - Feed includes all non-draft posts sorted by date
+  - Each item has title, description, pubDate, link, categories (tags)
+  - site URL configured in astro.config.mjs
+  - RSS feed accessible at /rss.xml
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 2: Create RSS utility functions (optional helpers)</name>
+  <files>src/utils/rss.ts</files>
+  <action>
+  Create optional utility functions for RSS generation:
+
+  1. Create src/utils/rss.ts
+
+  2. Add helper functions:
+     ```ts
+     import type { CollectionEntry } from 'astro:content';
+
+     export function formatPostForRSS(post: CollectionEntry<'blog'>) {
+       return {
+         title: post.data.title,
+         description: post.data.description,
+         pubDate: post.data.pubDate,
+         link: `/blog/${post.slug}/`,
+         categories: post.data.tags,
+       };
+     }
+
+     export function sortPostsByDate(posts: CollectionEntry<'blog'>[]) {
+       return posts.sort(
+         (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
+       );
+     }
+     ```
+
+  3. Refactor rss.xml.ts to use these utilities (DRY principle)
+
+  Note: This thread is optional but recommended for cleaner code. If time-constrained, inline logic in rss.xml.ts is acceptable.
+
+  AVOID: Do not add XML parsing utilities (use @astrojs/rss). Do not add feed caching (Astro handles this). WHY: @astrojs/rss provides all RSS functionality; additional abstractions add unnecessary complexity.
+  </action>
+  <verify>
+  Check: src/utils/rss.ts exports helper functions
+  Check: rss.xml.ts imports and uses utilities
+  Run: npm run build (should succeed)
+  Check: dist/rss.xml unchanged (same output, cleaner code)
+  </verify>
+  <done>
+  - src/utils/rss.ts created with helper functions
+  - formatPostForRSS converts post to RSS item format
+  - sortPostsByDate sorts posts by date descending
+  - rss.xml.ts refactored to use utilities
+  - Build output identical (cleaner code, same result)
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 3: Add RSS autodiscovery link</name>
+  <files>src/layouts/BaseLayout.astro</files>
+  <action>
+  Add RSS feed autodiscovery to site header:
+
+  1. Open src/layouts/BaseLayout.astro (created in Block 02)
+
+  2. In the <head> section, add autodiscovery link:
+     ```html
+     <link
+       rel="alternate"
+       type="application/rss+xml"
+       title="James Weatherhead Blog"
+       href="/rss.xml"
+     />
+     ```
+
+  3. This allows:
+     - Browsers to detect RSS feed (shows RSS icon in address bar)
+     - Feed readers to auto-discover feed
+     - Standard SEO best practice for blogs
+
+  4. Optional: Add visible RSS link in Footer component:
+     - Icon or text link: "RSS Feed"
+     - Links to /rss.xml
+
+  AVOID: Do not add Atom feed (RSS 2.0 sufficient). Do not add JSON Feed (RSS standard more widely supported). WHY: RSS 2.0 is universal standard; additional feed formats add maintenance overhead without significant benefit.
+  </action>
+  <verify>
+  Run: npm run dev
+  Visit: http://localhost:4321
+  Check: View page source - <link rel="alternate" type="application/rss+xml"> in <head>
+  Check: Browser RSS icon appears (if browser supports)
+  Check: Footer has RSS link (if added)
+  </verify>
+  <done>
+  - BaseLayout.astro has RSS autodiscovery link in <head>
+  - RSS feed detectable by browsers and feed readers
+  - Optional: Footer contains visible RSS link
+  - Feed properly advertised to users
+  </done>
+</thread>
+
+</threads>
+
+<verification>
+Complete verification checklist:
+1. src/pages/rss.xml.ts exports GET function
+2. RSS feed includes all non-draft posts
+3. Posts sorted by date descending (newest first)
+4. Each item has title, description, pubDate, link, categories
+5. Feed validates against RSS 2.0 spec (use validator)
+6. /rss.xml accessible after build
+7. BaseLayout.astro has autodiscovery link in <head>
+8. Optional: Footer has visible RSS link
+9. npm run build generates dist/rss.xml
+10. Feed loads in feed reader (test with Feedly or similar)
+</verification>
+
+<success_criteria>
+- RSS feed accessible at /rss.xml
+- Feed contains all published blog posts
+- Feed validates against RSS 2.0 specification
+- Autodiscovery link present in site <head>
+- Feed items have complete metadata (title, description, date, link, tags)
+- Build generates static RSS XML file
+- Feed works in standard feed readers
+</success_criteria>

package/.grid/plans/blog-block-06.md

@@ -0,0 +1,325 @@
+---
+cluster: james-weatherhead-blog
+block: 06
+type: execute
+wave: 4
+depends_on: [02, 04, 05]
+files_modified: [.gitignore, README.md, vercel.json]
+autonomous: false
+
+must_haves:
+  truths:
+    - "Project builds successfully for production"
+    - "All pages render without errors"
+    - "Vercel configuration is deployment-ready"
+  artifacts:
+    - path: "README.md"
+      provides: "Project documentation for setup and deployment"
+      min_lines: 30
+    - path: ".gitignore"
+      provides: "Git ignore rules for build artifacts and secrets"
+      min_lines: 10
+    - path: "vercel.json"
+      provides: "Vercel deployment configuration"
+      min_lines: 5
+  key_links:
+    - from: "vercel.json"
+      to: "astro.config.mjs"
+      via: "framework detection"
+      pattern: "astro"
+---
+
+<objective>
+Finalize project for production deployment - verification, documentation, and deployment configuration.
+
+Purpose: Ensure blog is production-ready with comprehensive documentation and verified build.
+Output: Deployment-ready blog with README, verified build, and Vercel config.
+</objective>
+
+<context>
+All feature blocks completed:
+- Block 01: Project initialization ✓
+- Block 02: Layout system with dark mode ✓
+- Block 03: Content collection and blog posts ✓
+- Block 04: Static pages and tag filtering ✓
+- Block 05: RSS feed ✓
+
+This final block:
+1. Verifies entire site builds without errors
+2. Creates comprehensive README for users/developers
+3. Confirms Vercel configuration from Block 01
+4. Tests production build locally
+5. Prepares for Vercel deployment
+
+This is a verification and documentation block - no new features, just ensuring everything works together.
+</context>
+
+<threads>
+
+<thread type="auto">
+  <name>Thread 1: Comprehensive production build verification</name>
+  <files>.gitignore</files>
+  <action>
+  Verify production build and clean up configuration:
+
+  1. Run full build pipeline:
+     ```bash
+     cd /Users/jacweath/grid/blog
+     npm run build
+     ```
+
+  2. Verify build outputs:
+     - Check dist/ directory created
+     - Verify all pages generated (index, blog, about, posts, tags, rss.xml)
+     - Check for build warnings or errors
+     - Verify syntax highlighting assets included
+
+  3. Test production build locally:
+     ```bash
+     npm run preview
+     ```
+     - Visit all pages: /, /blog, /about, /blog/sample-post, /blog/tags/{tag}, /rss.xml
+     - Test dark mode toggle on each page
+     - Check for console errors
+     - Verify navigation links work
+
+  4. Update .gitignore if needed:
+     - Ensure dist/ excluded
+     - Ensure .astro/ excluded
+     - Ensure .vercel/ excluded
+     - Add any OS-specific files (.DS_Store, Thumbs.db)
+
+  AVOID: Do not ignore node_modules in package-lock.json (commit lock file). Do not add IDE configs to gitignore (use global gitignore). WHY: Lock files ensure reproducible builds; IDE configs are personal preference, not project-level.
+  </action>
+  <verify>
+  Run: npm run build
+  Check: Exit code 0 (success)
+  Check: dist/ contains index.html, blog/, rss.xml
+  Run: npm run preview
+  Visit: All pages load without errors
+  Check: Console has no errors
+  Check: Dark mode works on all pages
+  </verify>
+  <done>
+  - npm run build completes successfully
+  - All pages generated in dist/ directory
+  - npm run preview serves production build
+  - All pages accessible and functional
+  - No console errors or build warnings
+  - .gitignore updated with all necessary exclusions
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 2: Create comprehensive README documentation</name>
+  <files>README.md</files>
+  <action>
+  Create README.md with project documentation:
+
+  1. Project overview section:
+     - Project name: James Weatherhead Blog
+     - Description: Minimal technical blog built with Astro
+     - Tech stack: Astro, Tailwind CSS, TypeScript
+     - Features: Dark mode, markdown posts, tags, RSS feed
+
+  2. Prerequisites section:
+     - Node.js 18+ required
+     - npm or pnpm
+
+  3. Getting Started section:
+     ```bash
+     # Install dependencies
+     npm install
+
+     # Start dev server
+     npm run dev
+
+     # Build for production
+     npm run build
+
+     # Preview production build
+     npm run preview
+     ```
+
+  4. Project Structure:
+     ```
+     /
+     ├── src/
+     │   ├── components/       # Reusable components
+     │   ├── content/
+     │   │   └── blog/        # Markdown blog posts
+     │   ├── layouts/         # Layout components
+     │   ├── pages/           # Route pages
+     │   └── styles/          # Global styles
+     ├── public/              # Static assets
+     └── astro.config.mjs     # Astro configuration
+     ```
+
+  5. Content Management:
+     - How to add new blog post (create .md in src/content/blog/)
+     - Frontmatter schema explanation
+     - Tag usage
+
+  6. Deployment section:
+     - Vercel deployment instructions
+     - Environment variables (if any)
+     - Custom domain setup (brief)
+
+  7. Features section:
+     - Dark mode toggle
+     - Syntax highlighting
+     - RSS feed at /rss.xml
+     - Tag-based filtering
+
+  AVOID: Do not add contributing guidelines yet (single author). Do not add license section unless specified. WHY: Personal blog doesn't need complex governance docs; add if project becomes open source.
+  </action>
+  <verify>
+  Check: README.md exists with all sections
+  Check: Installation commands are accurate
+  Check: Project structure matches actual structure
+  Run: Follow getting started steps to verify accuracy
+  </verify>
+  <done>
+  - README.md created with comprehensive documentation
+  - All sections present: overview, prerequisites, getting started, structure, deployment
+  - Installation and build commands verified
+  - Content management instructions clear
+  - Deployment instructions for Vercel included
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 3: Verify and document Vercel configuration</name>
+  <files>vercel.json</files>
+  <action>
+  Verify Vercel deployment configuration:
+
+  1. Check vercel.json from Block 01:
+     - Ensure framework: "astro"
+     - Ensure buildCommand: "npm run build"
+     - Ensure outputDirectory: "dist"
+
+  2. Verify astro.config.mjs:
+     - Adapter: @astrojs/vercel/serverless (or /static if fully static)
+     - Site URL: Update if final domain known (e.g., https://jamesweatherhead.com)
+
+  3. Create deployment checklist in README:
+     ```markdown
+     ## Deployment to Vercel
+
+     1. Push code to GitHub repository
+     2. Import project in Vercel dashboard
+     3. Vercel auto-detects Astro framework
+     4. Set environment variables (if any):
+        - SITE_URL: https://yourdomain.com
+     5. Deploy
+     6. Configure custom domain (optional)
+     ```
+
+  4. Test local build mimics Vercel:
+     - Ensure no local-only dependencies
+     - Verify all imports are relative (not absolute)
+     - Check no hardcoded localhost URLs
+
+  AVOID: Do not add CI/CD pipelines yet (Vercel handles this). Do not add preview deployment config (Vercel provides automatically). WHY: Vercel's built-in CI/CD is sufficient for blog; manual configuration adds complexity.
+  </action>
+  <verify>
+  Check: vercel.json has correct framework and build settings
+  Check: astro.config.mjs has site URL configured
+  Check: README.md has deployment instructions
+  Run: npm run build (simulate Vercel build)
+  Check: No errors referencing localhost or local paths
+  </verify>
+  <done>
+  - vercel.json verified with correct configuration
+  - astro.config.mjs has site URL set
+  - README.md includes deployment checklist
+  - Build succeeds without local-only dependencies
+  - Project ready for Vercel deployment
+  </done>
+</thread>
+
+<thread type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+  Production-ready blog with:
+  - Verified production build (all pages generate correctly)
+  - Comprehensive README documentation
+  - Vercel deployment configuration
+  - Complete project ready for deployment
+  </what-built>
+  <how-to-verify>
+  1. cd /Users/jacweath/grid/blog
+
+  2. Clean build test:
+     ```bash
+     rm -rf dist/
+     npm run build
+     ```
+     - Should complete without errors
+     - Check dist/ contains all expected files
+
+  3. Preview production build:
+     ```bash
+     npm run preview
+     ```
+     - Visit http://localhost:4321
+     - Test all pages: /, /blog, /about, /blog/sample-post
+     - Test tag filtering: click tags, verify filtered posts
+     - Test RSS feed: visit /rss.xml
+     - Test dark mode toggle on each page
+     - Check browser console for errors (should be none)
+
+  4. Review documentation:
+     - Read README.md
+     - Verify instructions are clear and accurate
+     - Check project structure matches reality
+
+  5. Verify deployment readiness:
+     - Check vercel.json exists with correct settings
+     - Check .gitignore excludes build artifacts
+     - Verify no hardcoded localhost URLs in code
+
+  6. Final checklist:
+     - [ ] Build completes successfully
+     - [ ] All pages load in preview
+     - [ ] Dark mode works everywhere
+     - [ ] Navigation links functional
+     - [ ] Tags filter correctly
+     - [ ] RSS feed validates
+     - [ ] README accurate
+     - [ ] No console errors
+  </how-to-verify>
+  <resume-signal>Type "approved" if blog is production-ready and documentation is complete, or describe issues (e.g., "build fails", "page missing", "README unclear")</resume-signal>
+</thread>
+
+</threads>
+
+<verification>
+Complete verification checklist:
+1. npm run build completes with exit code 0
+2. dist/ directory contains all pages and assets
+3. npm run preview serves production build successfully
+4. All pages load without errors (/, /blog, /about, posts, tags, rss.xml)
+5. Dark mode toggle works on all pages
+6. Navigation links functional across site
+7. Tag filtering displays correct posts
+8. RSS feed accessible and validates
+9. README.md complete with all sections
+10. vercel.json configured correctly
+11. .gitignore excludes all build artifacts
+12. No hardcoded localhost or local-only dependencies
+13. Browser console has no errors
+14. User approves blog is deployment-ready
+</verification>
+
+<success_criteria>
+- Production build succeeds without errors
+- All pages render correctly in preview
+- Dark mode functional across entire site
+- Navigation and filtering work as expected
+- RSS feed validates and loads in feed readers
+- README provides clear setup and deployment instructions
+- Vercel configuration ready for deployment
+- No console errors or warnings
+- User confirms blog is ready to deploy to Vercel
+</success_criteria>