# Fix CI Failures

You are tasked with automatically fixing CI (Continuous Integration) failures in the PostXL monorepo.

## Context

The user will provide:

- Failed CI run URL
- Failed job names
- PR number
- Branch name
- Error logs from failed jobs

## Your Task

Analyze the CI failure logs, identify the root cause, fix the issues, and commit the changes.

## Step-by-Step Process

### 1. Analyze the Failure

First, carefully read the error logs to identify the type of failure:

- **Build failures**: TypeScript compilation errors, missing dependencies
- **Type check failures**: Type errors from `pnpm run test:types`
- **Test failures**: Jest or Vitest test failures
- **Linting failures**: ESLint errors
- **Prettier failures**: Code formatting issues
- **Coverage failures**: Insufficient test coverage

### 2. Check Node Version

This project uses pnpm's automatic runtime management. The required Node.js version (24+) is specified in `package.json` under `devEngines.runtime`. pnpm (10.14+) will automatically download and use the correct version.

If you see Node version warnings (e.g., `WARN Unsupported engine: wanted: {"node":">=24"}`), ensure pnpm is updated to version 10.14 or later.

### 3. Fix the Issues

Based on the failure type, apply the appropriate fixes:

#### Prettier Failures

```bash
pnpm run prettier:format
```

#### Linting Failures

```bash
pnpm run lint -- --fix
```

#### Type Errors

1. Identify which package/project has type errors from the logs
2. Navigate to that directory and run:
   ```bash
   pnpm run test:types
   ```
3. Fix the type errors by:
   - Reading the files with errors
   - Understanding the type mismatch
   - Correcting the types or code
4. If type errors are in generated code from the demo project:
   - **CRITICAL**: Never modify generated files directly
   - Find and fix the generator source in `/packages/generators/src/`
   - Rebuild generators: `cd packages/generators && rm -rf dist && pnpm run build`
   - Regenerate: `pnpm --filter @postxl/demo run generate -f`

#### Build Failures

1. Try building from the root to rebuild all dependencies:
   ```bash
   pnpm run build
   ```
2. If specific package fails, navigate to it and fix compilation errors
3. For generator-related build failures, follow the generator development workflow:
   - Fix generator source in `/packages/generators/src/`
   - Rebuild: `cd packages/generators && rm -rf dist && pnpm run build`
   - Regenerate projects: `pnpm --filter @postxl/demo run generate`
   - Verify: `pnpm --filter @postxl/demo-api run build`

#### Test Failures

1. Identify the failing test from the logs
2. Read the test file and understand what's failing
3. Fix the issue in the source code or update the test if expectations changed
4. For snapshot failures, update snapshots if the changes are expected:
   ```bash
   cd <package-with-failing-tests>
   pnpm test:jest -u
   ```
5. Run the specific test to verify the fix:
   ```bash
   pnpm test:jest <test-file-path>
   ```

### 4. Regenerate Demo Project (if needed)

If you modified any generator code in `/packages/generators/src/`, you MUST regenerate the demo project:

```bash
# Rebuild generators first
cd packages/generators
rm -rf dist
pnpm run build

# Regenerate demo project
cd ../../projects/demo
pnpm run generate -f
```

This ensures that:

- Generated code reflects your generator fixes
- Demo project compiles correctly with the updated generators
- All generated files are in sync

### 5. Verify the Fix

After applying fixes, verify they work:

```bash
# Run the same checks that failed in CI
pnpm run check
```

If specific jobs failed, run those specific commands:

- Build: `pnpm run build`
- Type check: `pnpm run test:types`
- Tests: `pnpm run test:jest`
- Lint: `pnpm run lint`
- Prettier: `pnpm run prettier:check`

### 6. Add a Changeset (Skip in Automated Context)

**IMPORTANT**: If you are running in an automated CI context (e.g., GitHub Actions), SKIP this step entirely. The `pnpm changeset` command requires interactive input and will block automation.

For manual fixes only: If your fixes modified any packages (not demo projects), you should add a changeset:

```bash
pnpm changeset
```

When prompted:

1. **Select packages**: Choose all packages you modified (e.g., `@postxl/generators`, `@postxl/cli`)
2. **Version bump type**:
   - `patch` - Bug fixes and minor changes (most CI fixes)
   - `minor` - New features that are backwards compatible
   - `major` - Breaking changes
3. **Summary**: Write a clear description of what was fixed

Example changeset summary:

```
fix: resolve type errors in seed generator

- Fixed incorrect return type in SeedService
- Updated Prisma enum defaults to match schema
```

**Note**:
- Demo projects (`@postxl/demo`, `@postxl/demo-api`, etc.) are ignored in changeset config, so don't select them.
- In automated contexts, changesets should be added manually after reviewing the auto-fix PR.
- Mention in your commit message if a changeset may be needed so reviewers can add it.

### 7. Commit the Changes

Once fixes are verified:

1. Stage all changed files:

   ```bash
   git add .
   ```

2. Create a descriptive commit message that explains what was fixed:

   ```bash
   git commit -m "fix(ci): <brief description of what was fixed>

   - Fixed <specific issue 1>
   - Fixed <specific issue 2>

   Fixes CI run: <CI run URL>

   Note: If packages were modified, a changeset may be needed. Please review and add manually if required.

   🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
   ```

3. Push the changes:
   ```bash
   git push origin HEAD
   ```

### 8. Report Summary

After completing the fixes, provide a concise summary:

- What failures were detected
- What fixes were applied
- What commands were run to verify
- Commit hash and message

## Important Notes

- **Never modify generated files directly**: If errors are in generated code, fix the generator source
- **Generator workflow**: Always rebuild generators (`rm -rf dist && pnpm run build`) before regenerating
- **Node version**: pnpm 10.14+ manages Node.js automatically via `devEngines.runtime`
- **Verify before committing**: Run the same checks that failed in CI to ensure fixes work
- **Be thorough**: Multiple types of failures may exist - fix them all
- **Follow project patterns**: Respect the monorepo structure and existing code patterns

## Common Failure Scenarios

### Scenario: "Prettier formatting errors"

→ Run `pnpm run prettier:format` and commit

### Scenario: "Type errors in demo backend"

→ Could be generator issue. Find generator, fix it, rebuild, regenerate, verify

### Scenario: "Linting errors"

→ Run `pnpm run lint -- --fix`, review changes, commit

### Scenario: "Test snapshots out of date"

→ Verify changes are expected, run `pnpm test:jest -u` in affected package

### Scenario: "Build failure after generator changes"

→ Rebuild generators with `rm -rf dist`, regenerate demo, verify compilation

### Scenario: "Demo project is out of sync with generators"

This error occurs when the CI's "Verify demo project is up to date" step fails, showing files like `package.json` have changed after regeneration.

**Root cause**: The committed generated files don't match what the generators actually produce. This can happen when:
- Someone committed files with incorrect formatting
- Turbo remote cache served stale generator builds during a previous commit

**Solution**:

1. **Build without turbo remote cache** to ensure completely fresh generator output:
   ```bash
   rm -rf packages/*/dist packages/*/.turbo .turbo
   TURBO_API="" TURBO_TOKEN="" pnpm turbo run build:packages --force
   ```

2. **Regenerate the demo project**:
   ```bash
   cd projects/demo
   pnpm run generate:project -f
   ```

3. **Check the diff** to understand what changed:
   ```bash
   git diff projects/demo/
   ```

4. **Commit the regenerated files** - these are the correct versions that match generator output

**Key insight**: If running `pnpm run generate:project -f` locally shows no diff, but CI reports changes, the turbo remote cache may be serving stale builds. Always use `TURBO_API="" TURBO_TOKEN=""` to bypass remote cache when debugging this issue.

## Final Checklist

Before you consider the task complete:

- [ ] All error logs have been analyzed
- [ ] Root cause identified for each failure
- [ ] Fixes applied following project conventions
- [ ] Fixes verified with appropriate commands
- [ ] All changes committed with descriptive message
- [ ] Changes pushed to the branch
- [ ] Summary provided to user
