the-grid-cc 1.2.0 → 1.4.0

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

@@ -0,0 +1,287 @@
+---
+cluster: james-weatherhead-blog
+block: 04
+type: execute
+wave: 3
+depends_on: [02, 03]
+files_modified: [src/pages/index.astro, src/pages/blog/index.astro, src/pages/about.astro, src/pages/blog/tags/[tag].astro]
+autonomous: false
+
+must_haves:
+  truths:
+    - "Homepage displays recent blog posts"
+    - "Blog index page lists all posts"
+    - "About page contains author information"
+    - "Tag pages filter posts by tag"
+  artifacts:
+    - path: "src/pages/index.astro"
+      provides: "Homepage with recent posts"
+      min_lines: 30
+    - path: "src/pages/blog/index.astro"
+      provides: "Complete blog post listing"
+      min_lines: 25
+    - path: "src/pages/about.astro"
+      provides: "About page with author info"
+      min_lines: 20
+    - path: "src/pages/blog/tags/[tag].astro"
+      provides: "Tag-filtered post listing"
+      min_lines: 40
+  key_links:
+    - from: "index.astro"
+      to: "getCollection('blog')"
+      via: "fetch recent posts"
+      pattern: "getCollection\\('blog'\\)"
+    - from: "[tag].astro"
+      to: "posts.filter"
+      via: "tag filtering"
+      pattern: "\\.filter.*tags\\.includes"
+---
+
+<objective>
+Create static pages (homepage, blog index, about) and tag-based filtering functionality.
+
+Purpose: Connect layout system (Block 02) and content system (Block 03) into navigable pages with tag-based organization.
+Output: Complete page structure with homepage, blog listing, about page, and tag filtering.
+</objective>
+
+<context>
+Dependencies completed:
+- Block 02: Layout system (BaseLayout, Header, Footer, DarkModeToggle)
+- Block 03: Content system (blog collection, post template, PostList component)
+
+This block brings everything together into actual pages users will visit. Navigation links from Header (Home, Blog, About) now have destinations. Tag filtering enables content organization without complex search.
+
+This is where the blog becomes navigable and complete. After this block, users can:
+- Land on homepage and see recent posts
+- Browse all posts at /blog
+- Read about the author at /about
+- Filter posts by tag at /blog/tags/{tag}
+</context>
+
+<threads>
+
+<thread type="auto">
+  <name>Thread 1: Build homepage and blog index</name>
+  <files>src/pages/index.astro, src/pages/blog/index.astro</files>
+  <action>
+  Create homepage and blog listing pages:
+
+  index.astro (Homepage):
+  1. Import BaseLayout, PostList, getCollection
+  2. Fetch recent posts:
+     ```ts
+     const allPosts = await getCollection('blog', ({ data }) => !data.draft);
+     const recentPosts = allPosts
+       .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
+       .slice(0, 5); // Show 5 most recent
+     ```
+  3. Hero section:
+     - Site title: "James Weatherhead"
+     - Subtitle/tagline (e.g., "Software Engineer & Technical Writer")
+     - Brief intro paragraph (1-2 sentences)
+  4. Recent posts section:
+     - Heading: "Recent Posts"
+     - Use PostList component with recentPosts
+     - Link to /blog: "View all posts →"
+  5. Minimal design: max-w-3xl container, generous whitespace
+
+  blog/index.astro (Blog Index):
+  1. Import BaseLayout, PostList, getCollection
+  2. Fetch all posts (sorted by date descending)
+  3. Page title: "Blog"
+  4. Optional: display tag cloud (all unique tags)
+  5. Use PostList component with all posts
+  6. Style consistently with homepage
+
+  AVOID: Do not add complex hero animations (keep minimal). Do not add featured posts section yet (YAGNI). WHY: Requirements specify "minimal design" - focus on content, not embellishments.
+  </action>
+  <verify>
+  Run: npm run dev
+  Visit: http://localhost:4321 (homepage)
+  Check: Recent posts appear (up to 5)
+  Visit: http://localhost:4321/blog (blog index)
+  Check: All posts appear in list
+  Check: Both pages use BaseLayout with header/footer
+  </verify>
+  <done>
+  - index.astro displays hero section and 5 recent posts
+  - blog/index.astro lists all non-draft posts
+  - Both pages use consistent styling (max-w-3xl, Tailwind)
+  - "View all posts" link navigates to /blog
+  - Posts sorted by date descending
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 2: Create About page</name>
+  <files>src/pages/about.astro</files>
+  <action>
+  Create About page with author information:
+
+  1. Create src/pages/about.astro with BaseLayout
+  2. Page title: "About"
+  3. Content structure:
+     - Heading: "About James Weatherhead"
+     - Bio paragraphs (placeholder text for now - user will customize):
+       * Professional background
+       * Technical interests
+       * Why they write (blog purpose)
+     - Contact information (if provided)
+     - Optional: Links to GitHub, LinkedIn, Twitter (if provided)
+  4. Style with prose typography: prose dark:prose-invert max-w-3xl
+  5. Consistent container width with other pages
+
+  Placeholder content example:
+  "I'm a software engineer passionate about web development, DevOps, and technical writing. This blog is where I share insights, tutorials, and lessons learned from building software."
+
+  AVOID: Do not add contact form (YAGNI - add if requested). Do not add photo upload (user can add later). WHY: Keep initial version simple - user can customize content after deployment.
+  </action>
+  <verify>
+  Visit: http://localhost:4321/about
+  Check: Page renders with heading and bio content
+  Check: Consistent styling with other pages (max-w-3xl, prose)
+  Check: Dark mode works correctly on about page
+  Check: Header navigation links to /about works
+  </verify>
+  <done>
+  - about.astro created with BaseLayout
+  - Page contains heading and placeholder bio content
+  - Prose typography applied for readability
+  - Consistent container width (max-w-3xl)
+  - Navigation link from Header works
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 3: Implement tag-based filtering</name>
+  <files>src/pages/blog/tags/[tag].astro</files>
+  <action>
+  Create dynamic tag pages for filtering posts by tag:
+
+  1. Create src/pages/blog/tags/[tag].astro
+
+  2. Implement getStaticPaths to generate page for each unique tag:
+     ```ts
+     import { getCollection } from 'astro:content';
+     export async function getStaticPaths() {
+       const allPosts = await getCollection('blog', ({ data }) => !data.draft);
+       const uniqueTags = [...new Set(allPosts.flatMap(post => post.data.tags))];
+
+       return uniqueTags.map(tag => {
+         const filteredPosts = allPosts.filter(post =>
+           post.data.tags.includes(tag)
+         );
+         return {
+           params: { tag },
+           props: { posts: filteredPosts },
+         };
+       });
+     }
+     ```
+
+  3. Render tag page:
+     - Page title: "Posts tagged with '{tag}'"
+     - Display tag name prominently
+     - Show post count: "X posts"
+     - Use PostList component with filtered posts
+     - Breadcrumb: "Blog / Tags / {tag}"
+     - Link back to /blog
+
+  4. Update Tag component (from Block 03):
+     - When variant='link', link to /blog/tags/{tag}
+     - Ensure tags in PostList are clickable
+
+  AVOID: Do not add tag description field (YAGNI - tags are self-explanatory). Do not add "related tags" section (over-engineering). WHY: Keep tag pages simple - they're for filtering, not complex taxonomy.
+  </action>
+  <verify>
+  Run: npm run dev
+  Visit: http://localhost:4321/blog/tags/javascript (or any tag from sample post)
+  Check: Page shows only posts with that tag
+  Check: Post count displays correctly
+  Check: Tags in PostList are clickable and link to tag pages
+  Check: Breadcrumb or back link to /blog exists
+  Run: npm run build (should generate static page for each tag)
+  </verify>
+  <done>
+  - [tag].astro implements getStaticPaths with unique tags
+  - Filters posts by tag correctly
+  - Displays tag name and post count
+  - PostList shows filtered posts
+  - Tag component links to tag pages (variant='link')
+  - Build generates static page for each tag
+  </done>
+</thread>
+
+<thread type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+  Complete page structure:
+  - Homepage (index.astro) with recent posts
+  - Blog index (blog/index.astro) with all posts
+  - About page (about.astro) with author info
+  - Tag pages (blog/tags/[tag].astro) with filtered posts
+  </what-built>
+  <how-to-verify>
+  1. cd /Users/jacweath/grid/blog && npm run dev
+
+  2. Test Homepage (http://localhost:4321):
+     - Hero section displays site title and intro
+     - Recent posts section shows up to 5 posts
+     - "View all posts" link navigates to /blog
+     - Header navigation visible (Home, Blog, About)
+
+  3. Test Blog Index (http://localhost:4321/blog):
+     - All blog posts listed
+     - Posts sorted newest first
+     - Tags visible and clickable
+
+  4. Test About Page (http://localhost:4321/about):
+     - Page renders with author info
+     - Consistent styling with other pages
+     - Navigation link from Header works
+
+  5. Test Tag Filtering:
+     - Click a tag from blog index or post page
+     - Should navigate to /blog/tags/{tag}
+     - Only posts with that tag appear
+     - Post count displays correctly
+
+  6. Test Navigation:
+     - Click each nav link (Home, Blog, About)
+     - All pages load without errors
+     - Dark mode toggle works on all pages
+
+  7. Run: npm run build
+     - Build completes successfully
+     - Check dist/ contains all static pages
+  </how-to-verify>
+  <resume-signal>Type "approved" if all pages work and navigation is functional, or describe issues (e.g., "tag filtering broken", "about page missing", "homepage posts not showing")</resume-signal>
+</thread>
+
+</threads>
+
+<verification>
+Complete verification checklist:
+1. Homepage renders with hero and recent posts (max 5)
+2. Blog index lists all non-draft posts sorted by date
+3. About page displays author information
+4. Tag pages filter posts correctly by tag
+5. Navigation links work (Home, Blog, About)
+6. Tags are clickable and link to tag pages
+7. Dark mode works consistently across all pages
+8. All pages use BaseLayout with header/footer
+9. Responsive on mobile and desktop
+10. npm run build generates all static pages
+11. No console errors on any page
+12. User approves page structure and navigation
+</verification>
+
+<success_criteria>
+- Homepage displays recent posts and hero content
+- Blog index shows complete post listing
+- About page contains author information
+- Tag filtering functional (click tag → see filtered posts)
+- All navigation links work correctly
+- Build generates all static pages
+- Consistent styling and dark mode across all pages
+- User approves overall page structure and UX
+</success_criteria>

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>