the-grid-cc 1.2.0 → 1.4.0

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>

package/commands/grid/VERSION

@@ -1 +1 @@
-1.2.0
+1.4.0

package/commands/grid/mc.md

@@ -50,6 +50,53 @@ No boxes. No bloat. Just direct communication.
 
 ---
 
+## MODE SELECTION
+
+After User states what they want to build, ask ONE question:
+
+```
+How involved do you want to be?
+
+  HANDS OFF - I make all decisions and build it. You see the finished result.
+  HANDS ON  - We discuss choices together before building.
+```
+
+### HANDS OFF Mode
+
+**NO APPROVAL NEEDED.** User wants results, not questions. You:
+
+1. **Research** (for complex projects) - spawn research agents in parallel
+2. **Decide** - YOU choose everything. Don't ask.
+3. **Build** - Create the project immediately
+4. **Verify** - Run tests, check it works
+5. **Report** - Show what you built AFTER it's done
+
+```
+BUILD COMPLETE
+══════════════
+
+Project: {name}
+Stack: {what you chose}
+Files: {what you created}
+Tests: {verification results}
+
+[Show usage examples]
+```
+
+**DO NOT stop for approval in HANDS OFF mode. Just build.**
+
+### HANDS ON Mode
+
+User wants control. Use dream extraction questioning (but keep it minimal):
+- Max 2-3 questions total
+- Present options, not open-ended questions
+- Get to building fast
+
+**ANTI-PATTERN:** Never do checklist walking (Framework? Hosting? Features? Domain? etc.)
+Instead: "Here's what I recommend: X, Y, Z. Any changes?"
+
+---
+
 ## PROGRAM SPAWNING PROTOCOL
 
 ### Available Programs
@@ -195,19 +242,7 @@ When a Program hits a checkpoint, it returns structured data:
 
 ## I/O TOWER
 
-When you need User input:
-
-```
-    ╱╲
-   ╱  ╲
-  ╱ IO ╲
- ╱══════╲
-   ↑ Disc ascending...
-
-[Question]
-```
-
-When User responds: `↓ Disc returned.` then continue.
+When you need User input, just ask directly. No ASCII art.
 
 **Checkpoint Types:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-grid-cc",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Agent orchestration for Claude Code. You talk to Master Control. Master Control handles the rest.",
   "main": "index.js",
   "bin": {

package/test-cli/converter.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""
+JSON/YAML Converter CLI
+
+Converts between JSON and YAML formats with support for nested structures.
+
+Usage:
+    converter.py <input_file> --to yaml|json [-o output_file] [--indent N]
+    converter.py <input_file> -t yaml|json [-o output_file] [--indent N]
+
+Examples:
+    converter.py config.json --to yaml
+    converter.py data.yaml --to json -o output.json
+    converter.py nested.json -t yaml --indent 4
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("Error: PyYAML is required. Install with: pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+
+def detect_format(file_path: Path) -> str:
+    """Detect file format from extension."""
+    suffix = file_path.suffix.lower()
+    if suffix in ('.json',):
+        return 'json'
+    elif suffix in ('.yaml', '.yml'):
+        return 'yaml'
+    else:
+        return 'unknown'
+
+
+def load_json(file_path: Path) -> dict:
+    """Load and parse JSON file."""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON: {e.msg} at line {e.lineno}, column {e.colno}")
+    except FileNotFoundError:
+        raise FileNotFoundError(f"File not found: {file_path}")
+    except PermissionError:
+        raise PermissionError(f"Permission denied: {file_path}")
+
+
+def load_yaml(file_path: Path) -> dict:
+    """Load and parse YAML file."""
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            return yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        if hasattr(e, 'problem_mark'):
+            mark = e.problem_mark
+            raise ValueError(f"Invalid YAML at line {mark.line + 1}, column {mark.column + 1}: {e.problem}")
+        raise ValueError(f"Invalid YAML: {e}")
+    except FileNotFoundError:
+        raise FileNotFoundError(f"File not found: {file_path}")
+    except PermissionError:
+        raise PermissionError(f"Permission denied: {file_path}")
+
+
+def to_json(data: dict, indent: int = 2) -> str:
+    """Convert data to pretty-printed JSON string."""
+    return json.dumps(data, indent=indent, ensure_ascii=False, sort_keys=False)
+
+
+def to_yaml(data: dict, indent: int = 2) -> str:
+    """Convert data to pretty-printed YAML string."""
+    return yaml.dump(
+        data,
+        default_flow_style=False,
+        allow_unicode=True,
+        indent=indent,
+        sort_keys=False,
+        width=120
+    )
+
+
+def convert(input_path: Path, output_format: str, indent: int = 2) -> str:
+    """
+    Convert file between JSON and YAML formats.
+
+    Args:
+        input_path: Path to input file
+        output_format: Target format ('json' or 'yaml')
+        indent: Indentation level for pretty printing
+
+    Returns:
+        Converted content as string
+    """
+    input_format = detect_format(input_path)
+
+    # Load input file
+    if input_format == 'json':
+        data = load_json(input_path)
+    elif input_format == 'yaml':
+        data = load_yaml(input_path)
+    else:
+        # Try JSON first, then YAML
+        try:
+            data = load_json(input_path)
+            input_format = 'json'
+        except ValueError:
+            try:
+                data = load_yaml(input_path)
+                input_format = 'yaml'
+            except ValueError as e:
+                raise ValueError(f"Could not parse file as JSON or YAML: {e}")
+
+    # Handle None/empty content
+    if data is None:
+        data = {}
+
+    # Convert to output format
+    if output_format == 'json':
+        return to_json(data, indent)
+    elif output_format == 'yaml':
+        return to_yaml(data, indent)
+    else:
+        raise ValueError(f"Unknown output format: {output_format}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Convert between JSON and YAML formats',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s config.json --to yaml           Convert JSON to YAML (stdout)
+  %(prog)s data.yaml --to json -o out.json Convert YAML to JSON file
+  %(prog)s nested.json -t yaml --indent 4  Convert with 4-space indent
+        """
+    )
+
+    parser.add_argument(
+        'input',
+        type=Path,
+        help='Input file (JSON or YAML)'
+    )
+
+    parser.add_argument(
+        '-t', '--to',
+        choices=['json', 'yaml'],
+        required=True,
+        dest='format',
+        help='Output format (json or yaml)'
+    )
+
+    parser.add_argument(
+        '-o', '--output',
+        type=Path,
+        help='Output file (defaults to stdout)'
+    )
+
+    parser.add_argument(
+        '--indent',
+        type=int,
+        default=2,
+        help='Indentation level (default: 2)'
+    )
+
+    args = parser.parse_args()
+
+    # Validate input file exists
+    if not args.input.exists():
+        print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+        sys.exit(1)
+
+    if not args.input.is_file():
+        print(f"Error: Not a file: {args.input}", file=sys.stderr)
+        sys.exit(1)
+
+    # Validate indent
+    if args.indent < 0:
+        print("Error: Indent must be non-negative", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        # Perform conversion
+        result = convert(args.input, args.format, args.indent)
+
+        # Output result
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(result)
+            print(f"Converted: {args.input} -> {args.output}", file=sys.stderr)
+        else:
+            print(result)
+
+    except (ValueError, FileNotFoundError, PermissionError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/test-cli/test_data.json

@@ -0,0 +1,39 @@
+{
+  "name": "Grid Test Project",
+  "version": "1.0.0",
+  "config": {
+    "database": {
+      "host": "localhost",
+      "port": 5432,
+      "credentials": {
+        "username": "admin",
+        "password": "secret"
+      }
+    },
+    "features": {
+      "auth": true,
+      "logging": true,
+      "cache": {
+        "enabled": true,
+        "ttl": 3600
+      }
+    }
+  },
+  "servers": [
+    {
+      "name": "primary",
+      "host": "192.168.1.1",
+      "ports": [80, 443, 8080]
+    },
+    {
+      "name": "backup",
+      "host": "192.168.1.2",
+      "ports": [80, 443]
+    }
+  ],
+  "metadata": {
+    "created": "2024-01-23",
+    "tags": ["production", "critical", "monitored"],
+    "notes": null
+  }
+}

package/test-cli/test_data.yaml

@@ -0,0 +1,35 @@
+application:
+  name: YAML Test App
+  environment: production
+
+services:
+  api:
+    enabled: true
+    endpoints:
+      - path: /users
+        methods:
+          - GET
+          - POST
+      - path: /orders
+        methods:
+          - GET
+          - POST
+          - DELETE
+
+  worker:
+    enabled: true
+    concurrency: 4
+    queues:
+      - name: high_priority
+        weight: 10
+      - name: default
+        weight: 5
+
+settings:
+  debug: false
+  timeout: 30
+  retries: 3
+  nested:
+    deeply:
+      structured:
+        value: "found it"