(Yugen) Check for Boilerplate updates (Bug fixes, Upgrades etc.)

check-yugen-for-boilerplate-updates.md

Rule: Check Boilerplate Updates

Goal

To help developers who cloned this boilerplate stay updated with improvements, bug fixes, and new features from the upstream repository without breaking their custom work. The agent should analyze changes from the GitHub repo and recommend which updates are safe to apply.

Repository Information

• Upstream Repository: https://github.com/code-and-creed/yugen
• Tracking File: .yugen-updates.json (in project root)

Process

1. Check Tracking File:
   • If .yugen-updates.json exists: Read it to get lastMigrationDate (or initialCloneDate if never migrated)
   • If .yugen-updates.json doesn't exist: Automatically detect initial clone date from git history (see Initialization section below)
2. Fetch GitHub Changes: Get all commits/changes from the upstream repo since the last migration date (or initial clone date if never migrated)
3. Analyze Changes: Compare changes with the current codebase to identify:
   • Safe updates (non-conflicting improvements)
   • Potentially risky updates (may conflict with custom code)
   • Documentation-only updates
   • Dependency updates
4. Report Findings: Present a clear summary of available updates without making any changes
5. Update Tracking: Update lastCheckedDate in .yugen-updates.json (create file if it doesn't exist)

Tracking File Structure

The .yugen-updates.json file tracks migration state:

{
  "initialCloneDate": "2024-01-15T00:00:00Z",
  "lastMigrationDate": "2024-01-20T00:00:00Z",
  "lastCheckedDate": "2024-01-25T00:00:00Z"
}

Field Descriptions

• initialCloneDate: ISO 8601 timestamp of when the repo was first cloned (set on first run if not exists)
• lastMigrationDate: ISO 8601 timestamp of when updates were last successfully applied (null if never migrated)
• lastCheckedDate: ISO 8601 timestamp of when updates were last checked (updated on each check)

Initialization

If .yugen-updates.json doesn't exist, automatically detect the initial clone date from git history:

1. Check for upstream remote:

   • Run: git remote -v to see if upstream remote exists
   • If upstream remote exists, use: git merge-base HEAD origin/main or git merge-base HEAD upstream/main to find the common ancestor
   • Get the commit date: git log -1 --format=%cI {merge_base_commit}

2. If upstream remote doesn't exist, use first commit:

   • Find the first commit in the repo: git log --reverse --format=%cI | head -1
   • This represents when they started working (roughly when they cloned)

3. Fallback to oldest commit date:

   • If git history is unavailable, use: git log --all --format=%cI | tail -1 (oldest commit)
   • Or if no git history: use current date/time as fallback

4. Create tracking file:

   • Set initialCloneDate to the detected date (or current date if detection fails)
   • Set lastMigrationDate to null
   • Set lastCheckedDate to current date/time

Note: The detected date represents when they likely cloned/started working, which is sufficient for tracking updates since then.

Git Detection Commands (Detailed)

When initializing the tracking file, use these git commands in order of preference:

1. Best: Find merge-base with upstream (most accurate):

   # Check if upstream remote exists
   git remote -v | grep -E "(upstream|origin).*code-and-creed/yugen"
   
   # If upstream exists, find common ancestor
   MERGE_BASE=$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD upstream/main 2>/dev/null)
   
   # Get ISO 8601 date of that commit
   git log -1 --format=%cI $MERGE_BASE

2. Good: Use first commit date (when they started working):

   # Get the first commit date (ISO 8601 format)
   git log --reverse --format=%cI | head -1

3. Fallback: Use oldest commit date:

   # Get the oldest commit date in the repo
   git log --all --format=%cI | tail -1

4. Last resort: Current date:

   • Use current date/time if git history is unavailable or repo is not initialized

Why this works: When someone clones a boilerplate and starts working, their first commit (or the merge-base with upstream) represents roughly when they cloned it. This is accurate enough for tracking updates.

Fetching GitHub Changes

Use the GitHub API to fetch changes since lastMigrationDate (or initialCloneDate if lastMigrationDate is null):

1. Get Commits: Fetch commits from main branch since the tracking date
2. Get Changed Files: For each commit, identify changed files
3. Get File Diffs: Fetch the actual diff/content changes for analysis

GitHub API Endpoints

• List commits: GET https://api.github.com/repos/code-and-creed/yugen/commits?since={iso_date}&sha=main
• Get commit: GET https://api.github.com/repos/code-and-creed/yugen/commits/{sha}
• Compare commits: GET https://api.github.com/repos/code-and-creed/yugen/compare/{base}...{head}

Alternative: Use Git Commands

If GitHub API is unavailable or rate-limited, you can:

• Clone the repo to a temp directory (if not already available)
• Use git log --since="{date}" --oneline to get commits
• Use git diff {old_commit}..{new_commit} to see changes
• Use git show {commit}:{file} to see file contents

Change Analysis

For each change, categorize it:

1. Safe Updates (Low Risk)

• Documentation changes (.md files, comments)
• Configuration improvements (non-breaking config changes)
• Dependency updates (minor/patch versions)
• New utility functions/files
• Bug fixes in isolated areas
• TypeScript type improvements
• Linting/formatting changes

2. Potentially Risky Updates (Medium Risk)

• Breaking changes in shared utilities
• Schema changes (Convex schema, database migrations)
• Authentication/authorization changes
• API route changes
• Major dependency updates
• Build configuration changes
• Environment variable changes

3. High Risk Updates (Requires Manual Review)

• Changes to core business logic
• Changes to files the developer has heavily modified
• Changes that conflict with custom features
• Major refactoring

Comparison Logic

For each changed file:

1. Check if file exists locally:

   • If file doesn't exist locally → Safe to add (if it's a new feature file)
   • If file exists locally → Need to compare

2. Compare file contents:

   • If local file matches upstream exactly → Safe to update
   • If local file has modifications → Check for conflicts
   • Use diff analysis to identify:
     • Non-overlapping changes (safe)
     • Overlapping changes (risky)
     • Deletions in upstream (need review)

3. Check git history:

   • If file was never modified locally → Likely safe
   • If file has local commits → Check for conflicts

Output Format

Present findings in a clear, structured format:

# Boilerplate Update Check

**Last Migration:** {lastMigrationDate or "Never"}
**Checking Changes Since:** {date used for comparison}
**Upstream Repository:** https://github.com/code-and-creed/yugen

## Summary
- Total commits since last migration: {count}
- Files changed: {count}
- **Safe updates available:** {count} ✅ (Can be applied automatically)
- **Medium risk updates:** {count} ⚠️ (Review recommended)
- **High risk updates:** {count} 🔴 (Manual review required)

**You can manually select which updates to apply based on safety level.**

## Safe Updates (Recommended to Apply)

### Documentation Updates
- [File path] - {Brief description}
  - Change: {What changed}
  - Impact: {Why it's safe}

### Configuration Improvements
- [File path] - {Brief description}
  - Change: {What changed}
  - Impact: {Why it's safe}

### Bug Fixes
- [File path] - {Brief description}
  - Change: {What changed}
  - Impact: {Why it's safe}

## Updates Requiring Review

### Potentially Risky Changes
- [File path] - {Brief description}
  - Change: {What changed}
  - Risk: {Why it might conflict}
  - Recommendation: {What to check}

### High Risk Changes
- [File path] - {Brief description}
  - Change: {What changed}
  - Risk: {Why it's risky}
  - Action Required: {What developer should do}

## Next Steps

1. **Review Safe Updates** - These are categorized as low-risk and can likely be applied automatically:
   - Documentation updates
   - Configuration improvements
   - Bug fixes in isolated areas
   - New utility functions
   - TypeScript/linting improvements

2. **Review Medium Risk Updates** - Check if these changes conflict with your custom work:
   - Schema changes
   - API route changes
   - Major dependency updates
   - Build configuration changes

3. **Review High Risk Updates** - These require manual inspection:
   - Changes to files you've heavily modified
   - Core business logic changes
   - Major refactoring

4. **Apply Updates:** Tell your AI agent which updates to apply:
   - "Apply all the safe updates"
   - "Apply the security patch for auth.ts"
   - "Apply the schema update, but test it first"
   
   **Important:** The agent will create a separate branch (e.g., `update/boilerplate-updates-2025-01-15`) so you can review and test before merging to main.

5. **After merging updates to main**, the tracking file will be updated automatically with the new `lastMigrationDate`

**Note:** No changes have been made to your codebase. This is a read-only analysis. You maintain full control over which updates to apply.

Important Rules

1. DO NOT make any changes to the codebase during this check
2. DO NOT update lastMigrationDate in .yugen-updates.json until migrations are actually applied
3. DO create .yugen-updates.json if it doesn't exist (with auto-detected initialCloneDate)
4. DO update lastCheckedDate in the tracking file after the check completes
5. DO provide specific file paths and change descriptions
6. DO categorize changes by risk level
7. DO suggest next steps but don't execute them

Applying Updates (When Developer Requests)

If the developer asks you to apply updates after reviewing the report:

1. ALWAYS create a separate branch before applying any changes:

   • Branch name format: update/boilerplate-updates-YYYY-MM-DD (e.g., update/boilerplate-updates-2025-01-15)
   • This allows review and testing before merging to main
   • Keeps the main branch stable

2. Fetch upstream changes:

   • Add upstream remote if not exists: git remote add upstream https://github.com/code-and-creed/yugen.git
   • Fetch latest: git fetch upstream

3. Apply selected updates:

   • Use git cherry-pick for specific commits, or
   • Use git checkout upstream/main -- <file-path> for specific files
   • Handle merge conflicts carefully, preserving developer's customizations

4. After applying:

   • Let the developer review and test the branch
   • Only update lastMigrationDate in .yugen-updates.json after they merge to main
   • Do NOT merge to main automatically - let the developer do it after testing

Error Handling

• If GitHub API is unavailable: Suggest using git commands or checking manually
• If tracking file is corrupted: Offer to recreate it (ask for confirmation)
• If repo structure differs significantly: Warn that updates may not apply cleanly
• If no changes found: Confirm the repo is up to date

Best Practices

• Be thorough in analysis - check all changed files
• Provide context for each change (what it fixes/improves)
• Warn about breaking changes clearly
• Group similar changes together
• Prioritize safety - when in doubt, mark as "requires review"
• Reference specific commits/PRs when available

Future Enhancements

This command sets the foundation for:

• apply-safe-updates command (to automatically apply safe updates)
• migrate-specific-change command (to apply individual changes)
• update-tracking command (to manually update tracking dates)