@cregis-dev/cckit 0.4.0 → 0.5.0

package/templates/ecc/skills/cpp-testing/SKILL.md

@@ -1,323 +0,0 @@
----
-name: cpp-testing
-description: Use only when writing/updating/fixing C++ tests, configuring GoogleTest/CTest, diagnosing failing or flaky tests, or adding coverage/sanitizers.
-origin: ECC
----
-
-# C++ Testing (Agent Skill)
-
-Agent-focused testing workflow for modern C++ (C++17/20) using GoogleTest/GoogleMock with CMake/CTest.
-
-## When to Use
-
-- Writing new C++ tests or fixing existing tests
-- Designing unit/integration test coverage for C++ components
-- Adding test coverage, CI gating, or regression protection
-- Configuring CMake/CTest workflows for consistent execution
-- Investigating test failures or flaky behavior
-- Enabling sanitizers for memory/race diagnostics
-
-### When NOT to Use
-
-- Implementing new product features without test changes
-- Large-scale refactors unrelated to test coverage or failures
-- Performance tuning without test regressions to validate
-- Non-C++ projects or non-test tasks
-
-## Core Concepts
-
-- **TDD loop**: red → green → refactor (tests first, minimal fix, then cleanups).
-- **Isolation**: prefer dependency injection and fakes over global state.
-- **Test layout**: `tests/unit`, `tests/integration`, `tests/testdata`.
-- **Mocks vs fakes**: mock for interactions, fake for stateful behavior.
-- **CTest discovery**: use `gtest_discover_tests()` for stable test discovery.
-- **CI signal**: run subset first, then full suite with `--output-on-failure`.
-
-## TDD Workflow
-
-Follow the RED → GREEN → REFACTOR loop:
-
-1. **RED**: write a failing test that captures the new behavior
-2. **GREEN**: implement the smallest change to pass
-3. **REFACTOR**: clean up while tests stay green
-
-```cpp
-// tests/add_test.cpp
-#include <gtest/gtest.h>
-
-int Add(int a, int b); // Provided by production code.
-
-TEST(AddTest, AddsTwoNumbers) { // RED
-  EXPECT_EQ(Add(2, 3), 5);
-}
-
-// src/add.cpp
-int Add(int a, int b) { // GREEN
-  return a + b;
-}
-
-// REFACTOR: simplify/rename once tests pass
-```
-
-## Code Examples
-
-### Basic Unit Test (gtest)
-
-```cpp
-// tests/calculator_test.cpp
-#include <gtest/gtest.h>
-
-int Add(int a, int b); // Provided by production code.
-
-TEST(CalculatorTest, AddsTwoNumbers) {
-    EXPECT_EQ(Add(2, 3), 5);
-}
-```
-
-### Fixture (gtest)
-
-```cpp
-// tests/user_store_test.cpp
-// Pseudocode stub: replace UserStore/User with project types.
-#include <gtest/gtest.h>
-#include <memory>
-#include <optional>
-#include <string>
-
-struct User { std::string name; };
-class UserStore {
-public:
-    explicit UserStore(std::string /*path*/) {}
-    void Seed(std::initializer_list<User> /*users*/) {}
-    std::optional<User> Find(const std::string &/*name*/) { return User{"alice"}; }
-};
-
-class UserStoreTest : public ::testing::Test {
-protected:
-    void SetUp() override {
-        store = std::make_unique<UserStore>(":memory:");
-        store->Seed({{"alice"}, {"bob"}});
-    }
-
-    std::unique_ptr<UserStore> store;
-};
-
-TEST_F(UserStoreTest, FindsExistingUser) {
-    auto user = store->Find("alice");
-    ASSERT_TRUE(user.has_value());
-    EXPECT_EQ(user->name, "alice");
-}
-```
-
-### Mock (gmock)
-
-```cpp
-// tests/notifier_test.cpp
-#include <gmock/gmock.h>
-#include <gtest/gtest.h>
-#include <string>
-
-class Notifier {
-public:
-    virtual ~Notifier() = default;
-    virtual void Send(const std::string &message) = 0;
-};
-
-class MockNotifier : public Notifier {
-public:
-    MOCK_METHOD(void, Send, (const std::string &message), (override));
-};
-
-class Service {
-public:
-    explicit Service(Notifier &notifier) : notifier_(notifier) {}
-    void Publish(const std::string &message) { notifier_.Send(message); }
-
-private:
-    Notifier &notifier_;
-};
-
-TEST(ServiceTest, SendsNotifications) {
-    MockNotifier notifier;
-    Service service(notifier);
-
-    EXPECT_CALL(notifier, Send("hello")).Times(1);
-    service.Publish("hello");
-}
-```
-
-### CMake/CTest Quickstart
-
-```cmake
-# CMakeLists.txt (excerpt)
-cmake_minimum_required(VERSION 3.20)
-project(example LANGUAGES CXX)
-
-set(CMAKE_CXX_STANDARD 20)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-
-include(FetchContent)
-# Prefer project-locked versions. If using a tag, use a pinned version per project policy.
-set(GTEST_VERSION v1.17.0) # Adjust to project policy.
-FetchContent_Declare(
-  googletest
-  URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
-)
-FetchContent_MakeAvailable(googletest)
-
-add_executable(example_tests
-  tests/calculator_test.cpp
-  src/calculator.cpp
-)
-target_link_libraries(example_tests GTest::gtest GTest::gmock GTest::gtest_main)
-
-enable_testing()
-include(GoogleTest)
-gtest_discover_tests(example_tests)
-```
-
-```bash
-cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
-cmake --build build -j
-ctest --test-dir build --output-on-failure
-```
-
-## Running Tests
-
-```bash
-ctest --test-dir build --output-on-failure
-ctest --test-dir build -R ClampTest
-ctest --test-dir build -R "UserStoreTest.*" --output-on-failure
-```
-
-```bash
-./build/example_tests --gtest_filter=ClampTest.*
-./build/example_tests --gtest_filter=UserStoreTest.FindsExistingUser
-```
-
-## Debugging Failures
-
-1. Re-run the single failing test with gtest filter.
-2. Add scoped logging around the failing assertion.
-3. Re-run with sanitizers enabled.
-4. Expand to full suite once the root cause is fixed.
-
-## Coverage
-
-Prefer target-level settings instead of global flags.
-
-```cmake
-option(ENABLE_COVERAGE "Enable coverage flags" OFF)
-
-if(ENABLE_COVERAGE)
-  if(CMAKE_CXX_COMPILER_ID MATCHES "GNU")
-    target_compile_options(example_tests PRIVATE --coverage)
-    target_link_options(example_tests PRIVATE --coverage)
-  elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
-    target_compile_options(example_tests PRIVATE -fprofile-instr-generate -fcoverage-mapping)
-    target_link_options(example_tests PRIVATE -fprofile-instr-generate)
-  endif()
-endif()
-```
-
-GCC + gcov + lcov:
-
-```bash
-cmake -S . -B build-cov -DENABLE_COVERAGE=ON
-cmake --build build-cov -j
-ctest --test-dir build-cov
-lcov --capture --directory build-cov --output-file coverage.info
-lcov --remove coverage.info '/usr/*' --output-file coverage.info
-genhtml coverage.info --output-directory coverage
-```
-
-Clang + llvm-cov:
-
-```bash
-cmake -S . -B build-llvm -DENABLE_COVERAGE=ON -DCMAKE_CXX_COMPILER=clang++
-cmake --build build-llvm -j
-LLVM_PROFILE_FILE="build-llvm/default.profraw" ctest --test-dir build-llvm
-llvm-profdata merge -sparse build-llvm/default.profraw -o build-llvm/default.profdata
-llvm-cov report build-llvm/example_tests -instr-profile=build-llvm/default.profdata
-```
-
-## Sanitizers
-
-```cmake
-option(ENABLE_ASAN "Enable AddressSanitizer" OFF)
-option(ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF)
-option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)
-
-if(ENABLE_ASAN)
-  add_compile_options(-fsanitize=address -fno-omit-frame-pointer)
-  add_link_options(-fsanitize=address)
-endif()
-if(ENABLE_UBSAN)
-  add_compile_options(-fsanitize=undefined -fno-omit-frame-pointer)
-  add_link_options(-fsanitize=undefined)
-endif()
-if(ENABLE_TSAN)
-  add_compile_options(-fsanitize=thread)
-  add_link_options(-fsanitize=thread)
-endif()
-```
-
-## Flaky Tests Guardrails
-
-- Never use `sleep` for synchronization; use condition variables or latches.
-- Make temp directories unique per test and always clean them.
-- Avoid real time, network, or filesystem dependencies in unit tests.
-- Use deterministic seeds for randomized inputs.
-
-## Best Practices
-
-### DO
-
-- Keep tests deterministic and isolated
-- Prefer dependency injection over globals
-- Use `ASSERT_*` for preconditions, `EXPECT_*` for multiple checks
-- Separate unit vs integration tests in CTest labels or directories
-- Run sanitizers in CI for memory and race detection
-
-### DON'T
-
-- Don't depend on real time or network in unit tests
-- Don't use sleeps as synchronization when a condition variable can be used
-- Don't over-mock simple value objects
-- Don't use brittle string matching for non-critical logs
-
-### Common Pitfalls
-
-- **Using fixed temp paths** → Generate unique temp directories per test and clean them.
-- **Relying on wall clock time** → Inject a clock or use fake time sources.
-- **Flaky concurrency tests** → Use condition variables/latches and bounded waits.
-- **Hidden global state** → Reset global state in fixtures or remove globals.
-- **Over-mocking** → Prefer fakes for stateful behavior and only mock interactions.
-- **Missing sanitizer runs** → Add ASan/UBSan/TSan builds in CI.
-- **Coverage on debug-only builds** → Ensure coverage targets use consistent flags.
-
-## Optional Appendix: Fuzzing / Property Testing
-
-Only use if the project already supports LLVM/libFuzzer or a property-testing library.
-
-- **libFuzzer**: best for pure functions with minimal I/O.
-- **RapidCheck**: property-based tests to validate invariants.
-
-Minimal libFuzzer harness (pseudocode: replace ParseConfig):
-
-```cpp
-#include <cstddef>
-#include <cstdint>
-#include <string>
-
-extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
-    std::string input(reinterpret_cast<const char *>(data), size);
-    // ParseConfig(input); // project function
-    return 0;
-}
-```
-
-## Alternatives to GoogleTest
-
-- **Catch2**: header-only, expressive matchers
-- **doctest**: lightweight, minimal compile overhead

package/templates/ecc/skills/database-migrations/SKILL.md

@@ -1,335 +0,0 @@
----
-name: database-migrations
-description: Database migration best practices for schema changes, data migrations, rollbacks, and zero-downtime deployments across PostgreSQL, MySQL, and common ORMs (Prisma, Drizzle, Django, TypeORM, golang-migrate).
-origin: ECC
----
-
-# Database Migration Patterns
-
-Safe, reversible database schema changes for production systems.
-
-## When to Activate
-
-- Creating or altering database tables
-- Adding/removing columns or indexes
-- Running data migrations (backfill, transform)
-- Planning zero-downtime schema changes
-- Setting up migration tooling for a new project
-
-## Core Principles
-
-1. **Every change is a migration** — never alter production databases manually
-2. **Migrations are forward-only in production** — rollbacks use new forward migrations
-3. **Schema and data migrations are separate** — never mix DDL and DML in one migration
-4. **Test migrations against production-sized data** — a migration that works on 100 rows may lock on 10M
-5. **Migrations are immutable once deployed** — never edit a migration that has run in production
-
-## Migration Safety Checklist
-
-Before applying any migration:
-
-- [ ] Migration has both UP and DOWN (or is explicitly marked irreversible)
-- [ ] No full table locks on large tables (use concurrent operations)
-- [ ] New columns have defaults or are nullable (never add NOT NULL without default)
-- [ ] Indexes created concurrently (not inline with CREATE TABLE for existing tables)
-- [ ] Data backfill is a separate migration from schema change
-- [ ] Tested against a copy of production data
-- [ ] Rollback plan documented
-
-## PostgreSQL Patterns
-
-### Adding a Column Safely
-
-```sql
--- GOOD: Nullable column, no lock
-ALTER TABLE users ADD COLUMN avatar_url TEXT;
-
--- GOOD: Column with default (Postgres 11+ is instant, no rewrite)
-ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;
-
--- BAD: NOT NULL without default on existing table (requires full rewrite)
-ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
--- This locks the table and rewrites every row
-```
-
-### Adding an Index Without Downtime
-
-```sql
--- BAD: Blocks writes on large tables
-CREATE INDEX idx_users_email ON users (email);
-
--- GOOD: Non-blocking, allows concurrent writes
-CREATE INDEX CONCURRENTLY idx_users_email ON users (email);
-
--- Note: CONCURRENTLY cannot run inside a transaction block
--- Most migration tools need special handling for this
-```
-
-### Renaming a Column (Zero-Downtime)
-
-Never rename directly in production. Use the expand-contract pattern:
-
-```sql
--- Step 1: Add new column (migration 001)
-ALTER TABLE users ADD COLUMN display_name TEXT;
-
--- Step 2: Backfill data (migration 002, data migration)
-UPDATE users SET display_name = username WHERE display_name IS NULL;
-
--- Step 3: Update application code to read/write both columns
--- Deploy application changes
-
--- Step 4: Stop writing to old column, drop it (migration 003)
-ALTER TABLE users DROP COLUMN username;
-```
-
-### Removing a Column Safely
-
-```sql
--- Step 1: Remove all application references to the column
--- Step 2: Deploy application without the column reference
--- Step 3: Drop column in next migration
-ALTER TABLE orders DROP COLUMN legacy_status;
-
--- For Django: use SeparateDatabaseAndState to remove from model
--- without generating DROP COLUMN (then drop in next migration)
-```
-
-### Large Data Migrations
-
-```sql
--- BAD: Updates all rows in one transaction (locks table)
-UPDATE users SET normalized_email = LOWER(email);
-
--- GOOD: Batch update with progress
-DO $$
-DECLARE
-  batch_size INT := 10000;
-  rows_updated INT;
-BEGIN
-  LOOP
-    UPDATE users
-    SET normalized_email = LOWER(email)
-    WHERE id IN (
-      SELECT id FROM users
-      WHERE normalized_email IS NULL
-      LIMIT batch_size
-      FOR UPDATE SKIP LOCKED
-    );
-    GET DIAGNOSTICS rows_updated = ROW_COUNT;
-    RAISE NOTICE 'Updated % rows', rows_updated;
-    EXIT WHEN rows_updated = 0;
-    COMMIT;
-  END LOOP;
-END $$;
-```
-
-## Prisma (TypeScript/Node.js)
-
-### Workflow
-
-```bash
-# Create migration from schema changes
-npx prisma migrate dev --name add_user_avatar
-
-# Apply pending migrations in production
-npx prisma migrate deploy
-
-# Reset database (dev only)
-npx prisma migrate reset
-
-# Generate client after schema changes
-npx prisma generate
-```
-
-### Schema Example
-
-```prisma
-model User {
-  id        String   @id @default(cuid())
-  email     String   @unique
-  name      String?
-  avatarUrl String?  @map("avatar_url")
-  createdAt DateTime @default(now()) @map("created_at")
-  updatedAt DateTime @updatedAt @map("updated_at")
-  orders    Order[]
-
-  @@map("users")
-  @@index([email])
-}
-```
-
-### Custom SQL Migration
-
-For operations Prisma cannot express (concurrent indexes, data backfills):
-
-```bash
-# Create empty migration, then edit the SQL manually
-npx prisma migrate dev --create-only --name add_email_index
-```
-
-```sql
--- migrations/20240115_add_email_index/migration.sql
--- Prisma cannot generate CONCURRENTLY, so we write it manually
-CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (email);
-```
-
-## Drizzle (TypeScript/Node.js)
-
-### Workflow
-
-```bash
-# Generate migration from schema changes
-npx drizzle-kit generate
-
-# Apply migrations
-npx drizzle-kit migrate
-
-# Push schema directly (dev only, no migration file)
-npx drizzle-kit push
-```
-
-### Schema Example
-
-```typescript
-import { pgTable, text, timestamp, uuid, boolean } from "drizzle-orm/pg-core";
-
-export const users = pgTable("users", {
-  id: uuid("id").primaryKey().defaultRandom(),
-  email: text("email").notNull().unique(),
-  name: text("name"),
-  isActive: boolean("is_active").notNull().default(true),
-  createdAt: timestamp("created_at").notNull().defaultNow(),
-  updatedAt: timestamp("updated_at").notNull().defaultNow(),
-});
-```
-
-## Django (Python)
-
-### Workflow
-
-```bash
-# Generate migration from model changes
-python manage.py makemigrations
-
-# Apply migrations
-python manage.py migrate
-
-# Show migration status
-python manage.py showmigrations
-
-# Generate empty migration for custom SQL
-python manage.py makemigrations --empty app_name -n description
-```
-
-### Data Migration
-
-```python
-from django.db import migrations
-
-def backfill_display_names(apps, schema_editor):
-    User = apps.get_model("accounts", "User")
-    batch_size = 5000
-    users = User.objects.filter(display_name="")
-    while users.exists():
-        batch = list(users[:batch_size])
-        for user in batch:
-            user.display_name = user.username
-        User.objects.bulk_update(batch, ["display_name"], batch_size=batch_size)
-
-def reverse_backfill(apps, schema_editor):
-    pass  # Data migration, no reverse needed
-
-class Migration(migrations.Migration):
-    dependencies = [("accounts", "0015_add_display_name")]
-
-    operations = [
-        migrations.RunPython(backfill_display_names, reverse_backfill),
-    ]
-```
-
-### SeparateDatabaseAndState
-
-Remove a column from the Django model without dropping it from the database immediately:
-
-```python
-class Migration(migrations.Migration):
-    operations = [
-        migrations.SeparateDatabaseAndState(
-            state_operations=[
-                migrations.RemoveField(model_name="user", name="legacy_field"),
-            ],
-            database_operations=[],  # Don't touch the DB yet
-        ),
-    ]
-```
-
-## golang-migrate (Go)
-
-### Workflow
-
-```bash
-# Create migration pair
-migrate create -ext sql -dir migrations -seq add_user_avatar
-
-# Apply all pending migrations
-migrate -path migrations -database "$DATABASE_URL" up
-
-# Rollback last migration
-migrate -path migrations -database "$DATABASE_URL" down 1
-
-# Force version (fix dirty state)
-migrate -path migrations -database "$DATABASE_URL" force VERSION
-```
-
-### Migration Files
-
-```sql
--- migrations/000003_add_user_avatar.up.sql
-ALTER TABLE users ADD COLUMN avatar_url TEXT;
-CREATE INDEX CONCURRENTLY idx_users_avatar ON users (avatar_url) WHERE avatar_url IS NOT NULL;
-
--- migrations/000003_add_user_avatar.down.sql
-DROP INDEX IF EXISTS idx_users_avatar;
-ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;
-```
-
-## Zero-Downtime Migration Strategy
-
-For critical production changes, follow the expand-contract pattern:
-
-```
-Phase 1: EXPAND
-  - Add new column/table (nullable or with default)
-  - Deploy: app writes to BOTH old and new
-  - Backfill existing data
-
-Phase 2: MIGRATE
-  - Deploy: app reads from NEW, writes to BOTH
-  - Verify data consistency
-
-Phase 3: CONTRACT
-  - Deploy: app only uses NEW
-  - Drop old column/table in separate migration
-```
-
-### Timeline Example
-
-```
-Day 1: Migration adds new_status column (nullable)
-Day 1: Deploy app v2 — writes to both status and new_status
-Day 2: Run backfill migration for existing rows
-Day 3: Deploy app v3 — reads from new_status only
-Day 7: Migration drops old status column
-```
-
-## Anti-Patterns
-
-| Anti-Pattern | Why It Fails | Better Approach |
-|-------------|-------------|-----------------|
-| Manual SQL in production | No audit trail, unrepeatable | Always use migration files |
-| Editing deployed migrations | Causes drift between environments | Create new migration instead |
-| NOT NULL without default | Locks table, rewrites all rows | Add nullable, backfill, then add constraint |
-| Inline index on large table | Blocks writes during build | CREATE INDEX CONCURRENTLY |
-| Schema + data in one migration | Hard to rollback, long transactions | Separate migrations |
-| Dropping column before removing code | Application errors on missing column | Remove code first, drop column next deploy |