diff --git a/.claude/commands/error-report-summary.md b/.claude/commands/error-report-summary.md new file mode 100644 index 00000000..ec4a2945 --- /dev/null +++ b/.claude/commands/error-report-summary.md @@ -0,0 +1,57 @@ +# Error Report Summary (last 5 days) + +Fetch the last 5 days of error-report issues from the Base44 CLI GitHub repo, produce a summary report with Mermaid graphs, action items, and evaluation. Output is written to `error-reports/` (gitignored). + +## Instructions + +### 1. Compute the date range + +- "Last 5 days" = from today backward (e.g. today 2026-03-08 → `created:>=2026-03-03`). +- On macOS: `date -v-5d +%Y-%m-%d`. On Linux: `date -d '5 days ago' +%Y-%m-%d`. + +### 2. Fetch issues with GitHub CLI only + +- List issues: + ```bash + gh issue list --repo base44/cli --label "error-report" --state all --search "created:>=YYYY-MM-DD" --limit 20 + ``` +- For each issue number in the list, fetch the full body: + ```bash + gh issue view --repo base44/cli --json title,number,state,createdAt,body + ``` +- Use only the `gh` CLI; no direct GitHub API calls. + +### 3. Read and understand each issue + +- For each issue: command, error message, stack trace, environment (OS, command), and whether it is a CLI bug, backend issue, or user error (working as designed). + +### 4. Ensure report directory is gitignored + +- If `error-reports/` is not in `.gitignore`, add: + ```text + # Error report summaries (generated, do not commit) + error-reports/ + ``` +- Create the directory if needed: `mkdir -p error-reports`. + +### 5. Write the report + +Write to `error-reports/last-5-days-summary.md` (or `error-reports/YYYY-MM-DD-summary.md` for a date-stamped name) with: + +1. **Meta** — Run date, "last 5 days" window, total issue count, table of issues (title, link, created date, state). +2. **Graphs (Mermaid)** — Embed in the same file: + - **Total errors over time:** Bar or xychart with X = date (by day), Y = number of errors. Use each report's "Total errors" and the report date from the issue title. + - **Errors by type:** Pie or bar of count per type. Derive type from issue body (e.g. auth, deploy, backend 428, config not found, timeout, user validation). + - **Top N per-error:** Bar chart of the top 5–10 recurring error patterns (normalize issue titles or first error line; group and count). +3. **Per-issue summary** — Short description of what failed, root cause if evident, 1–2 bullets per issue. +4. **Main action items** — Grouped by theme (auth, deploy, entities, config, telemetry, UX). Concrete next steps with file/line references where applicable. +5. **What else to evaluate** — Trends (same error across reports), gaps (missing context, unclear reproduction), suggestions (telemetry, docs, CLI UX). + +### 6. Reply to the user + +- Give a short summary (e.g. how many issues, main themes) and the path to the report file. + +## Output + +- Report path: `error-reports/last-5-days-summary.md` (or date-stamped equivalent). +- All charts are Mermaid code blocks so they render in GitHub. diff --git a/.claude/commands/tidy-up.md b/.claude/commands/tidy-up.md new file mode 100644 index 00000000..4e304eb5 --- /dev/null +++ b/.claude/commands/tidy-up.md @@ -0,0 +1,89 @@ +# Pre-PR Tidy-Up Review + +Review all changes in this branch before pushing to PR. + +## Instructions + +First, understand the scope of changes: +1. Run `git diff main...HEAD --name-only` to list all changed files +2. Run `git log main..HEAD --oneline` to see all commits +3. Run `git diff main...HEAD` to review actual changes +4. Read `CLAUDE.md` for project standards and patterns + +Then systematically review each section below. + +--- + +## 1. Code Quality & Readability + +- [ ] Code follows patterns and conventions defined in `CLAUDE.md` +- [ ] Logic flows linearly and is easy to follow - no spaghetti code +- [ ] Functions do one thing and are appropriately sized +- [ ] No deeply nested conditionals - use early returns or extract functions +- [ ] No duplicate code - extract shared logic into utilities +- [ ] No magic numbers/strings - use named constants +- [ ] No unused variables, imports, or dead code +- [ ] Consistent naming conventions throughout + +--- + +## 2. Comments Cleanup + +Remove unnecessary comments: +- [ ] Commented-out code (use git history instead) +- [ ] Obvious comments that repeat the code +- [ ] Resolved TODO/FIXME comments +- [ ] Placeholder comments from templates + +Keep valuable comments: +- WHY explanations for non-obvious decisions +- Complex algorithm explanations +- JSDoc for exported functions + +--- + +## 3. User Experience (CLI Output) + +Review all user-facing messages: +- [ ] Messages are clear and actionable +- [ ] Error messages explain the problem AND suggest a fix +- [ ] No jargon - use language end users understand +- [ ] No typos or grammatical errors +- [ ] Consistent tone and capitalization + +--- + +## 4. Documentation Updates + +- [ ] Update `CLAUDE.md` if changes affect architecture, patterns, or folder structure +- [ ] Update `README.md` if changes affect user-facing features or commands + +--- + +## 5. Type Safety + +- [ ] No `any` types unless necessary (and documented why) +- [ ] Zod schemas validate all external data (API responses, config files) +- [ ] Use `import type` for type-only imports + +--- + +## 6. Final Checks + +Run and fix any issues: +```bash +bun run lint +bun run typecheck +bun run test +bun run build +``` + +--- + +## Output + +Provide: +1. **Summary**: Brief overview of changes reviewed +2. **Issues Found**: Problems discovered, grouped by category +3. **Fixes Applied**: What was fixed +4. **Remaining Items**: Anything needing manual decision diff --git a/.claude/commands/update-changelog.md b/.claude/commands/update-changelog.md new file mode 100644 index 00000000..6ba3e6b3 --- /dev/null +++ b/.claude/commands/update-changelog.md @@ -0,0 +1,83 @@ +# Update Changelog + +Add entries to `CHANGELOG.md` for all git versions that are tagged but not yet documented. + +## Instructions + +### 1. Read the current state + +- Read `CHANGELOG.md` and identify the **latest documented version** (the first `## [x.y.z]` heading). +- Run `git tag --sort=-v:refname` to list all version tags. +- Every tag newer than the latest documented version is **missing** and needs an entry. +- Also check if `HEAD` has a release commit (`chore: release vX.Y.Z`) beyond the latest tag — include it too. + +### 2. Collect commits for each missing version + +For each missing version, get the commits between the previous tag and the current one: + +```bash +git log --oneline --no-merges v..v +``` + +For commits past the latest tag (unreleased): + +```bash +git log --oneline --no-merges v..HEAD +``` + +Get the date of each version: + +```bash +git log -1 --format='%as' v +``` + +### 3. Categorize commits + +| Category | Trigger keywords | +|---|---| +| **Added** | `feat`, `add`, new command/resource/workflow | +| **Changed** | `refactor`, `chore` (non-release), `ci`, improvement, update, bump | +| **Fixed** | `fix`, `revert` | +| **Removed** | `remove`, `delete`, `drop` | +| **Docs** | `docs` | + +**Skip these commits entirely:** +- Release commits (`chore: release v...`) +- Changelog/lockfile/formatting-only commits +- Pure CI workflow YAML fixes that don't affect the CLI + +### 4. Write the entries + +Insert new sections at the top of the file (after `# Changelog`), newest-first: + +```markdown +## [X.Y.Z] - YYYY-MM-DD + +### Added + +- Description (#PR) + +### Changed + +- Description (#PR) + +### Fixed + +- Description (#PR) +``` + +Rules: +- Only include categories that have entries +- Write concise, user-facing descriptions — not raw commit messages +- Use imperative mood ("Add X" not "Added X") +- Match the style of existing entries in the file + +### 5. Verify + +- Versions are in descending order +- No duplicate entries +- Formatting is consistent + +## Output + +Report which versions were added and a brief summary of each.