the-grid-cc 1.3.0 → 1.5.0

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

@@ -0,0 +1,253 @@
+---
+cluster: james-weatherhead-blog
+block: 03
+type: execute
+wave: 2
+depends_on: [01]
+files_modified: [src/content/config.ts, src/content/blog/sample-post.md, src/pages/blog/[...slug].astro, src/components/PostList.astro, src/components/Tag.astro]
+autonomous: false
+
+must_haves:
+  truths:
+    - "Blog posts are defined as content collection with schema"
+    - "Individual blog posts render with frontmatter data"
+    - "Tags are extracted and displayed for each post"
+  artifacts:
+    - path: "src/content/config.ts"
+      provides: "Content collection schema for blog posts"
+      exports: ["collections"]
+    - path: "src/pages/blog/[...slug].astro"
+      provides: "Dynamic blog post page template"
+      min_lines: 50
+    - path: "src/components/PostList.astro"
+      provides: "Reusable component for listing blog posts"
+      min_lines: 30
+  key_links:
+    - from: "src/pages/blog/[...slug].astro"
+      to: "getCollection('blog')"
+      via: "Astro content collections API"
+      pattern: "getCollection\\('blog'\\)"
+    - from: "src/content/config.ts"
+      to: "zod schema"
+      via: "defineCollection"
+      pattern: "defineCollection"
+---
+
+<objective>
+Implement blog content structure using Astro Content Collections with markdown posts, frontmatter validation, and tag support.
+
+Purpose: Create the core blog functionality - content schema, post rendering, and listing capabilities.
+Output: Content collection configured, sample post created, dynamic post template working.
+</objective>
+
+<context>
+Block 01 completed: Astro project initialized with Tailwind and Vercel adapter.
+Block 02 in progress: Layout system (runs parallel with this block).
+
+This block focuses on the content layer using Astro's Content Collections API. Requirements specify:
+- Markdown-based posts
+- Tags for organization
+- Syntax highlighting (shiki installed in Block 01)
+
+Content Collections provide type-safe frontmatter, automatic routing, and built-in markdown processing. This is the canonical Astro approach for blog content.
+
+Block 02 (layouts) and Block 03 (content) can run in parallel since they modify different files with no overlap.
+</context>
+
+<threads>
+
+<thread type="auto">
+  <name>Thread 1: Configure content collection schema</name>
+  <files>src/content/config.ts, src/content/blog/sample-post.md</files>
+  <action>
+  Set up Astro Content Collections for blog posts:
+
+  1. Create src/content/config.ts with zod schema:
+     ```ts
+     import { defineCollection, z } from 'astro:content';
+
+     const blog = defineCollection({
+       type: 'content',
+       schema: z.object({
+         title: z.string(),
+         description: z.string(),
+         pubDate: z.coerce.date(),
+         updatedDate: z.coerce.date().optional(),
+         tags: z.array(z.string()).default([]),
+         draft: z.boolean().default(false),
+       }),
+     });
+
+     export const collections = { blog };
+     ```
+
+  2. Create src/content/blog/ directory
+
+  3. Create sample post: src/content/blog/sample-post.md
+     - Frontmatter with all required fields (title, description, pubDate, tags)
+     - Markdown content with headings, paragraphs, code blocks
+     - Use tags: ["javascript", "astro", "web-development"]
+     - Include code block to test syntax highlighting
+
+  AVOID: Do not add complex media fields yet (images come later if needed). Do not add author field unless multi-author (single author blog). WHY: Keep schema minimal - only add fields when content requires them.
+  </action>
+  <verify>
+  Run: npm run build (should succeed with no schema errors)
+  Check: src/content/config.ts exports 'collections' with 'blog'
+  Check: sample-post.md exists with valid frontmatter
+  Run: npx astro check (validates content schema)
+  </verify>
+  <done>
+  - src/content/config.ts defines blog collection with zod schema
+  - Schema includes: title, description, pubDate, updatedDate, tags, draft
+  - sample-post.md created with valid frontmatter
+  - Build completes without content validation errors
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 2: Create dynamic blog post template</name>
+  <files>src/pages/blog/[...slug].astro</files>
+  <action>
+  Create dynamic route for individual blog posts:
+
+  1. Create src/pages/blog/[...slug].astro
+
+  2. Implement getStaticPaths():
+     ```ts
+     import { getCollection } from 'astro:content';
+     export async function getStaticPaths() {
+       const posts = await getCollection('blog', ({ data }) => !data.draft);
+       return posts.map(post => ({
+         params: { slug: post.slug },
+         props: post,
+       }));
+     }
+     ```
+
+  3. Destructure props: const { data, render } = Astro.props;
+  4. Render post with BaseLayout:
+     - Pass title and description to layout
+     - Render metadata: title, date, tags
+     - Render content: const { Content } = await render();
+     - Style with Tailwind typography: prose dark:prose-invert max-w-3xl
+
+  5. Date formatting: use Intl.DateTimeFormat or date-fns
+  6. Tags: render as badges with Tag component (create in next thread)
+
+  AVOID: Do not add comments (requirements say "none"). Do not add related posts sidebar (keep minimal). WHY: Feature requirements explicitly exclude comments; related posts adds complexity without requirement.
+  </action>
+  <verify>
+  Run: npm run dev
+  Visit: http://localhost:4321/blog/sample-post
+  Check: Post renders with title, date, tags, and content
+  Check: Code blocks have syntax highlighting
+  Check: Prose typography applied correctly
+  </verify>
+  <done>
+  - [slug].astro implements getStaticPaths with getCollection
+  - Filters out draft posts (data.draft === false)
+  - Renders post content with proper typography
+  - Displays frontmatter data (title, date, tags)
+  - Syntax highlighting works in code blocks
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 3: Build post list and tag components</name>
+  <files>src/components/PostList.astro, src/components/Tag.astro</files>
+  <action>
+  Create reusable components for displaying posts and tags:
+
+  PostList.astro:
+  1. Props interface: posts (array of blog collection entries)
+  2. Map over posts and display:
+     - Title (link to /blog/{slug})
+     - Description
+     - Date (formatted)
+     - Tags (using Tag component)
+  3. Sort by pubDate descending (newest first)
+  4. Style: space-y-8 for vertical spacing, hover states on titles
+  5. No pagination yet (add later if needed)
+
+  Tag.astro:
+  1. Props: tag (string), variant?: 'link' | 'badge'
+  2. If variant === 'link': render as link to /blog/tags/{tag}
+  3. If variant === 'badge': render as span with badge styles
+  4. Style: rounded-full px-3 py-1 text-sm bg-gray-200 dark:bg-gray-800
+
+  AVOID: Do not add filter/search UI (add later if needed). Do not add pagination yet (YAGNI - wait until many posts exist). WHY: Premature optimization - start simple, add features when content volume requires it.
+  </action>
+  <verify>
+  Check: PostList.astro accepts posts prop and maps over entries
+  Check: Tag.astro handles both 'link' and 'badge' variants
+  Check: Tags are clickable links (variant='link') or static badges
+  Run: grep -r "variant=" src/components/Tag.astro
+  </verify>
+  <done>
+  - PostList.astro displays posts with title, description, date, tags
+  - Posts sorted by date descending (newest first)
+  - Tag.astro renders tags as links or badges based on variant prop
+  - Hover states applied to post titles
+  </done>
+</thread>
+
+<thread type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+  Complete blog content system with:
+  - Content collection schema (src/content/config.ts)
+  - Sample blog post (src/content/blog/sample-post.md)
+  - Dynamic post template ([slug].astro)
+  - PostList component (reusable post listing)
+  - Tag component (link and badge variants)
+  </what-built>
+  <how-to-verify>
+  1. cd /Users/jacweath/grid/blog && npm run dev
+  2. Visit http://localhost:4321/blog/sample-post
+  3. Check post page:
+     - Title displays correctly
+     - Date shows formatted (e.g., "January 23, 2024")
+     - Tags appear as badges or links
+     - Markdown content renders properly
+     - Code blocks have syntax highlighting (colors visible)
+     - Dark mode: check prose-invert class applies (text readable on dark bg)
+  4. Check browser console for errors (should be none)
+  5. Run: npm run build
+     - Build should complete successfully
+     - Check: npx astro check (no content schema errors)
+  6. Create test listing page:
+     - Add src/pages/blog/index.astro using PostList component
+     - Visit http://localhost:4321/blog
+     - Sample post appears in list
+  </how-to-verify>
+  <resume-signal>Type "approved" if content renders correctly and schema validates, or describe issues (e.g., "highlighting broken", "schema error", "tags not visible")</resume-signal>
+</thread>
+
+</threads>
+
+<verification>
+Complete verification checklist:
+1. src/content/config.ts defines blog collection with zod schema
+2. Schema includes all required fields (title, description, pubDate, tags, draft)
+3. src/content/blog/sample-post.md exists with valid frontmatter
+4. src/pages/blog/[slug].astro implements getStaticPaths correctly
+5. Dynamic route filters out draft posts
+6. Post template renders content with prose typography
+7. Syntax highlighting works in code blocks
+8. PostList.astro sorts posts by date (newest first)
+9. Tag.astro supports 'link' and 'badge' variants
+10. npm run build completes successfully
+11. npx astro check passes with no errors
+12. User approves content rendering and functionality
+</verification>
+
+<success_criteria>
+- Content collection configured with type-safe schema
+- Sample blog post renders at /blog/sample-post
+- Frontmatter data displays correctly (title, date, tags)
+- Markdown content styled with typography plugin
+- Syntax highlighting functional
+- PostList and Tag components work correctly
+- Build succeeds with no content validation errors
+- User approves rendering and functionality
+</success_criteria>

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>