From cceb4ec1d27e7a9c0a45f25a21f4d30a2fb22d93 Mon Sep 17 00:00:00 2001 From: Andrew Beveridge Date: Thu, 25 Dec 2025 14:41:37 -0500 Subject: [PATCH] Migrate Cursor rules to CLAUDE.md for cross-tool compatibility - Add CLAUDE.md with consolidated project guidelines - Remove .cursor/rules/*.mdc files - CLAUDE.md works with both Cursor and Claude Code --- .cursor/rules/branching-workflow.mdc | 21 ------- .cursor/rules/infrastructure-changes.mdc | 31 ---------- .cursor/rules/version-management.mdc | 56 ----------------- CLAUDE.md | 78 ++++++++++++++++++++++++ pyproject.toml | 2 +- 5 files changed, 79 insertions(+), 109 deletions(-) delete mode 100644 .cursor/rules/branching-workflow.mdc delete mode 100644 .cursor/rules/infrastructure-changes.mdc delete mode 100644 .cursor/rules/version-management.mdc create mode 100644 CLAUDE.md diff --git a/.cursor/rules/branching-workflow.mdc b/.cursor/rules/branching-workflow.mdc deleted file mode 100644 index 3dd76d0e..00000000 --- a/.cursor/rules/branching-workflow.mdc +++ /dev/null @@ -1,21 +0,0 @@ ---- -description: Git branching and PR workflow -alwaysApply: true ---- - -# Branching Workflow - -**Never commit directly to `main`.** Always work on a feature branch. - -Create descriptive branch names like `feature/add-discord-notifications`, `fix/audio-sync-issue`, or `refactor/cleanup-api-routes`. - -# Creating a Pull Request - -Once all changes are complete, tests pass, and commits are pushed, create a PR with: - -1. **Summary** - Brief overview of the changes -2. **Changes Made** - List of specific modifications -3. **Testing** - How changes were tested (unit tests, manual testing) -4. **Related Issues** - Reference any GitHub issues (e.g., "Fixes #123") - -Only merge after review and CI checks pass. diff --git a/.cursor/rules/infrastructure-changes.mdc b/.cursor/rules/infrastructure-changes.mdc deleted file mode 100644 index 8d992d73..00000000 --- a/.cursor/rules/infrastructure-changes.mdc +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: Infrastructure as Code requirements using Pulumi -alwaysApply: true ---- - -# Infrastructure Changes - -All Google Cloud infrastructure (IAM, Cloud Storage, Cloud Run, Secret Manager, Artifact Registry, etc.) must be managed via **Pulumi IaC** in the `infrastructure/` folder. - -## Rules - -- **Reading/querying** with `gcloud` CLI is fine for investigation and debugging -- **Temporary changes** via `gcloud` CLI or Console are acceptable for urgent fixes or experimentation, but **must be cleaned up** and properly codified in the IaC afterward -- **Permanent changes** must go through Pulumi — never leave `gcloud` or Console changes as the final state - -## Workflow - -1. Make changes in `infrastructure/` -2. Run `pulumi preview` and verify the output -3. Run `pulumi up` to apply - -## Authentication Issues - -If you encounter any authentication issues with `gcloud` or `pulumi` (e.g., expired tokens, permission errors), **stop and notify the user** so they can run the appropriate auth commands in their external terminal: - -```bash -gcloud auth login -gcloud auth application-default login -``` - -Do not attempt to work around auth issues or make assumptions about credentials. diff --git a/.cursor/rules/version-management.mdc b/.cursor/rules/version-management.mdc deleted file mode 100644 index 4ec15ccd..00000000 --- a/.cursor/rules/version-management.mdc +++ /dev/null @@ -1,56 +0,0 @@ ---- -description: Version bumping rule for commits -alwaysApply: true ---- - -# Version Management - -When committing and pushing changes, always bump the patch version in `pyproject.toml`. - -The version is located at `tool.poetry.version` in `pyproject.toml`. For example, if the current version is `0.70.3`, bump it to `0.70.4`. - -This ensures every commit pushed to the repository has a unique version number for tracking and deployment purposes. - -# Testing Requirements - -**Before committing and pushing ANY changes, you MUST run the full test suite.** - -## Quick Test Command (Use This!) - -```bash -make test -``` - -This runs ALL tests: unit tests, backend tests, and E2E integration tests with emulators. - -## Manual Test Commands (if make isn't available) - -1. **Unit tests (karaoke_gen package) - 70% coverage required:** -```bash -poetry run pytest tests/unit/ -v --cov=karaoke_gen --cov-report=term-missing --cov-fail-under=70 -``` - -2. **Backend unit tests:** -```bash -poetry run pytest backend/tests/ --ignore=backend/tests/emulator -v -``` - -3. **E2E integration tests with emulators:** -```bash -./scripts/start-emulators.sh -export FIRESTORE_EMULATOR_HOST=127.0.0.1:8080 -export STORAGE_EMULATOR_HOST=http://127.0.0.1:4443 -export GOOGLE_CLOUD_PROJECT=test-project -poetry run pytest backend/tests/emulator/ -v -./scripts/stop-emulators.sh -``` - -## Pre-commit Checklist - -- [ ] All unit tests pass (`make test-unit`) -- [ ] All backend tests pass (`make test-backend`) -- [ ] E2E integration tests pass (`make test-e2e`) -- [ ] Coverage is at least 70% -- [ ] Version in `pyproject.toml` has been bumped - -**Do not commit or push code that fails tests. Fix any test failures before proceeding.** diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..e28ecfdd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,78 @@ +# Project Guidelines for AI Assistants + +This document contains guidelines and rules for AI assistants working on this codebase. + +## Branching Workflow + +**Never commit directly to `main`.** Always work on a feature branch. + +Create descriptive branch names like `feature/add-discord-notifications`, `fix/audio-sync-issue`, or `refactor/cleanup-api-routes`. + +### Creating a Pull Request + +Once all changes are complete, tests pass, and commits are pushed, create a PR with: + +1. **Summary** - Brief overview of the changes +2. **Changes Made** - List of specific modifications +3. **Testing** - How changes were tested (unit tests, manual testing) +4. **Related Issues** - Reference any GitHub issues (e.g., "Fixes #123") + +Only merge after review and CI checks pass. + +## Infrastructure Changes + +All Google Cloud infrastructure (IAM, Cloud Storage, Cloud Run, Secret Manager, Artifact Registry, etc.) must be managed via **Pulumi IaC** in the `infrastructure/` folder. + +### Rules + +- **Reading/querying** with `gcloud` CLI is fine for investigation and debugging +- **Temporary changes** via `gcloud` CLI or Console are acceptable for urgent fixes or experimentation, but **must be cleaned up** and properly codified in the IaC afterward +- **Permanent changes** must go through Pulumi — never leave `gcloud` or Console changes as the final state + +### Workflow + +1. Make changes in `infrastructure/` +2. Run `pulumi preview` and verify the output +3. Run `pulumi up` to apply + +### Authentication Issues + +If you encounter any authentication issues with `gcloud` or `pulumi` (e.g., expired tokens, permission errors), **stop and notify the user** so they can run the appropriate auth commands in their external terminal: + +```bash +gcloud auth login +gcloud auth application-default login +``` + +Do not attempt to work around auth issues or make assumptions about credentials. + +## Version Management + +When committing and pushing changes, always bump the patch version in `pyproject.toml`. + +The version is located at `tool.poetry.version` in `pyproject.toml`. For example, if the current version is `0.70.3`, bump it to `0.70.4`. + +This ensures every commit pushed to the repository has a unique version number for tracking and deployment purposes. + +## Testing Requirements + +**Before committing and pushing ANY changes, you MUST run the full test suite.** + +### Test Command + +```bash +make test +``` + +This is the **only command you need**. It runs all tests in order and fails fast if any test fails: +1. Unit tests (karaoke_gen package) with coverage check +2. Backend unit tests +3. E2E integration tests with emulators (auto-starts/stops emulators) + +### Pre-commit Checklist + +- [ ] `make test` passes +- [ ] Version in `pyproject.toml` has been bumped + +**Do not commit or push code that fails tests. Fix any test failures before proceeding.** + diff --git a/pyproject.toml b/pyproject.toml index d918a2b2..13917b55 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "karaoke-gen" -version = "0.75.56" +version = "0.75.57" description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens." authors = ["Andrew Beveridge "] license = "MIT"