codeninja 3.2.0 → 4.0.0

package/ide/claude-code/.claude/commands/codeninja-db-drop.md

@@ -0,0 +1,109 @@
+This command runs when user types /codeninja:db-drop
+
+---
+type: workflow
+name: db-drop-table
+command: "@db:drop-table"
+description: >
+  Generate a DROP TABLE migration file for an existing table. Removes the
+  table from context, updates create-schema.sql, and records the drop in
+  change_log. Never deletes the original setup file — history is preserved.
+---
+
+# Workflow: @db:drop-table
+
+## Goal
+Safely generate a DROP TABLE migration. The original setup file is preserved
+for history. The schema runner will execute the drop when run.
+
+## Rules
+- NEVER delete the original <number>-setup-tbl-<n>.sql file
+- ALWAYS generate a new numbered drop migration file
+- ALWAYS warn the user about irreversibility
+- Records in change_log with full before-state for rollback reference
+
+---
+
+## Step-by-Step Execution
+
+### Phase 1 — Target
+1. Run task: `ask-table-name`
+   - List tables from `context.db.schema.tables`
+   - Stores: `context.current_db.table_name`
+
+---
+
+### Phase 2 — Impact Analysis
+2. Agent scans `context`:
+   - Check `context.api_routes` for any routes that reference this table as `primary_table`
+   - Check `context.services` for any modules using this table
+   - Check `context.db.schema.tables` for any other tables with FK columns pointing here
+
+3. If references found:
+   - Display warning:
+     ```
+     ⚠ WARNING: This table is referenced by:
+       - [service]/modules/[Module] (primary_table)
+       - tbl_<other_table>.user_id → tbl_users (FK dependency)
+     
+     Dropping this table will break these references.
+     Make sure to update or remove dependent code first.
+     ```
+   - Ask: "Do you still want to proceed? (yes / no)"
+   - If no → abort
+
+4. Final confirmation:
+   - Ask exactly: "Type the table name to confirm the drop."
+   - Must match exactly — if wrong → abort
+   - Stores: confirmation
+
+---
+
+### Phase 3 — File Numbering
+5. Run task: `ask-table-file-number`
+   - Suggest: next available number
+   - Stores: `context.current_db.file_number`
+
+---
+
+### Phase 4 — Generate
+6. Delegate to `database-agent`:
+
+> **Claude Code sub-agent:** Spawn sub-agent: Task(database-agent)
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+   - Generate: `<repo_root>/database/<db_type>/migrations/<number>-drop-tbl-<n>.sql`
+
+   File contents:
+   ```sql
+   -- Drop tbl_<table_name>
+   -- Migration: <number>-drop-tbl-<n>.sql
+   -- Generated: <ISO date>
+   -- WARNING: This migration is irreversible in production.
+   -- Original table definition: <original_setup_file>
+
+   BEGIN;
+
+   DROP TABLE IF EXISTS public.<table_name> CASCADE;
+
+   COMMIT;
+   ```
+
+   - Update: `database/<db_type>/create-schema.sql`
+     - Keep the original `\i <setup_file>` entry
+     - Add the drop file entry AFTER it
+
+7. Run task: `write-context`
+   - Move table from `context.db.schema.tables` → save columns snapshot
+   - Append to `context.db.schema.change_log`:
+     ```json
+     {
+       "type": "table_dropped",
+       "table": "<table_name>",
+       "snapshot": { "<full column list saved here>" },
+       "file": "<drop_file_path>"
+     }
+     ```
+   - Clear `context.current_db`
+
+8. Run task: `show-final-summary`

package/ide/claude-code/.claude/commands/codeninja-db-index.md

@@ -0,0 +1,103 @@
+This command runs when user types /codeninja:db-index
+
+---
+type: workflow
+name: db-add-index
+command: "@db:add-index"
+description: >
+  Add a new index to an existing table. Determines whether the index belongs
+  in the table's own file (new tables) or in 111-setup-database-indexes.sql
+  (shared/cross-service indexes). Updates context and create-schema.sql.
+---
+
+# Workflow: @db:add-index
+
+## Goal
+Generate a properly named CREATE INDEX statement and place it in the correct
+file. Follow all index naming conventions from database-agent.md.
+
+---
+
+## Step-by-Step Execution
+
+### Phase 1 — Target Table
+1. Run task: `ask-table-name`
+   - List tables from `context.db.schema.tables`
+   - Stores: `context.current_db.table_name`
+
+---
+
+### Phase 2 — Index Columns
+2. Run task: `ask-index-columns`
+   - Ask: "Which column(s) should this index cover?"
+   - List available columns from `context.db.schema.tables[<table>].columns`
+   - Allow selecting one or multiple columns (compound index)
+   - Stores: `context.current_db.index_columns[]`
+
+3. Run task: `ask-index-sort-order`
+   - Ask: "Should any column in this index be sorted descending?"
+   - Common case: `created_at DESC`, `time DESC`
+   - If yes → ask which column(s) should be DESC
+   - Stores: `context.current_db.index_desc_columns[]`
+
+4. Run task: `ask-index-type`
+   - Ask: "Is this a standard index or a partial index?"
+   - Options:
+     1. Standard index (covers all rows)
+     2. Partial index (only indexes rows matching a condition)
+   - If partial → ask: "Enter the WHERE condition."
+     Example: `WHERE is_deleted = FALSE`
+   - Stores: `context.current_db.index_where_clause`
+
+---
+
+### Phase 3 — File Placement
+5. Run task: `ask-index-file-placement`
+   - Ask: "Where should this index be defined?"
+   - Options:
+     1. In the table's own setup file (for new/just-created tables)
+     2. In 111-setup-database-indexes.sql (for existing tables, shared use)
+   - Auto-suggest option 2 if table already has a setup file in migrations
+   - Stores: `context.current_db.index_file`
+
+---
+
+### Phase 4 — Generate
+6. Agent auto-generates the index name following convention:
+   - In table file: `idx_<table_without_tbl_prefix>_<columns_joined>`
+   - In shared file: `idx_tbl_<table_without_tbl_prefix>_<columns_joined>`
+   - Show name to user: "Index will be named: <n> — OK? (yes / rename)"
+
+7. Confirm: "Generate this index? (yes / no)"
+
+8. Delegate to `database-agent`:
+
+> **Claude Code sub-agent:** Spawn sub-agent: Task(database-agent)
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+   - If table file placement → append to `<repo_root>/database/<db_type>/migrations/<table_file>.sql`
+   - If shared file → append to `<repo_root>/database/<db_type>/migrations/111-setup-database-indexes.sql`
+
+   Generated SQL:
+   ```sql
+   -- Standard
+   CREATE INDEX <index_name> ON public.<table_name> (<col> [DESC], ...);
+
+   -- Partial
+   CREATE INDEX <index_name> ON public.<table_name> (<col> [DESC], ...)
+     WHERE <where_clause>;
+   ```
+
+   With standard header comment:
+   ```sql
+   --
+   -- Name: <index_name>; Type: INDEX; Schema: public
+   --
+   ```
+
+9. Run task: `write-context`
+   - Append index name to `context.db.schema.tables[<table>].indexes`
+   - Append to `context.db.schema.change_log`
+   - Clear `context.current_db`
+
+10. Run task: `show-final-summary`

package/ide/claude-code/.claude/commands/codeninja-db-modify.md

@@ -0,0 +1,165 @@
+This command runs when user types /codeninja:db-modify
+
+---
+type: workflow
+name: db-modify-table
+command: "@db:modify-table"
+description: >
+  Modify an existing table via a numbered ALTER migration file. Supports
+  adding columns, renaming columns, dropping columns, changing types,
+  and adding check constraints. Always generates a migration file and
+  updates context.
+---
+
+# Workflow: @db:modify-table
+
+## Goal
+Generate a properly numbered ALTER TABLE migration file that modifies an
+existing table. Record the change in context.db.schema.change_log so all
+agents have the updated schema.
+
+## Rules
+- ALWAYS generate an ALTER file — never edit the original table setup file
+- ALTER files are numbered sequentially after the last existing file
+- Every change is recorded in context.db.schema.change_log
+- create-schema.sql is updated after every ALTER file generated
+
+---
+
+## Step-by-Step Execution
+
+### Phase 1 — Target
+1. Run task: `ask-table-name`
+   - List tables from `context.db.schema.tables`
+   - Stores: `context.current_db.table_name`
+
+2. Run task: `ask-modify-operation`
+   - Ask: "What do you want to do?"
+   - Options:
+     1. Add a new column
+     2. Rename a column
+     3. Drop a column
+     4. Change a column type
+     5. Add a CHECK constraint to an existing column
+     6. Add a new index
+   - Stores: `context.current_db.modify_operation`
+
+   2b. If `context.current_db.modify_operation == "add_index"`:
+      → Immediately route to `@db:add-index` workflow.
+      → End this workflow (no further steps needed).
+
+---
+
+### Phase 2 — Operation-Specific Collection
+
+#### If "Add a new column":
+3. Run task: `ask-column-name`
+4. Run task: `ask-column-type`
+5. Run task: `ask-column-is-enum`
+6. Run task: `ask-column-position`
+   - Ask: "Add column after which existing column?"
+   - List current columns from context
+   - Stores: `context.current_db.after_column`
+
+Generated SQL pattern:
+```sql
+ALTER TABLE public.<table_name>
+  ADD COLUMN <col_name> <type> NOT NULL DEFAULT <default>;
+```
+
+#### If "Rename a column":
+3. Run task: `ask-old-column-name`
+   - List current columns from context
+4. Run task: `ask-new-column-name`
+   - Enforce: snake_case, lowercase
+
+Generated SQL pattern:
+```sql
+ALTER TABLE public.<table_name>
+  RENAME COLUMN <old_name> TO <new_name>;
+```
+
+#### If "Drop a column":
+3. Run task: `ask-old-column-name`
+   - List current columns from context
+   - WARN: "This will generate a DROP COLUMN migration. This is irreversible
+     in production. Make sure you have removed all code references first."
+   - Ask: "Confirm dropping column '<col>'? (yes/no)"
+
+Generated SQL pattern:
+```sql
+ALTER TABLE public.<table_name>
+  DROP COLUMN IF EXISTS <col_name>;
+```
+
+#### If "Change a column type":
+3. Run task: `ask-old-column-name`
+4. Run task: `ask-column-type` (new type)
+   - WARN agent about potential data loss if changing to narrower type
+
+Generated SQL pattern:
+```sql
+ALTER TABLE public.<table_name>
+  ALTER COLUMN <col_name> TYPE <new_type> USING <col_name>::<new_type>;
+```
+
+#### If "Add a CHECK constraint":
+3. Run task: `ask-old-column-name`
+4. Run task: `ask-column-enum-values`
+
+Generated SQL pattern:
+```sql
+ALTER TABLE public.<table_name>
+  ADD CONSTRAINT chk_<table>_<col> CHECK (<col_name> IN (<values>));
+COMMENT ON COLUMN public.<table_name>.<col_name> IS '<enum explanation>';
+```
+
+#### If "Add a new index":
+→ Route to `@db:add-index` workflow instead.
+
+---
+
+### Phase 3 — File Numbering
+7. Run task: `ask-table-file-number`
+   - Suggest: next available number after all existing files
+   - Stores: `context.current_db.file_number`
+
+---
+
+### Phase 4 — Confirm and Generate
+8. Show summary of the ALTER operation
+   - Display the exact SQL that will be generated
+   - Ask: "Generate this migration? (yes / no)"
+
+9. Delegate to `database-agent`:
+
+> **Claude Code sub-agent:** Spawn sub-agent: Task(database-agent)
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+   - Generate: `<repo_root>/database/<db_type>/migrations/<number>-alter-tbl-<n>-<description>.sql`
+
+   Full file structure:
+   ```sql
+   -- Alter tbl_<table>: <description>
+   -- Migration: <number>-alter-tbl-<n>-<description>.sql
+   -- Generated: <ISO date>
+
+   BEGIN;
+
+   ALTER TABLE public.<table_name>
+     <operation>;
+
+   -- Optional: COMMENT ON COLUMN if enum/flag column
+   -- Optional: CREATE INDEX if new column needs one
+
+   COMMIT;
+   ```
+
+   - Update: `database/<db_type>/create-schema.sql`
+
+10. Run task: `write-context`
+    - Update `context.db.schema.tables[<table>].columns`
+    - Append to `context.db.schema.change_log`
+    - Clear `context.current_db`
+
+11. Run task: `show-final-summary`

package/ide/claude-code/.claude/commands/codeninja-db-seed.md

@@ -0,0 +1,104 @@
+This command runs when user types /codeninja:db-seed
+
+---
+type: workflow
+name: db-seed
+command: "@db:seed"
+description: >
+  Add or update seed data for a table. For reference/master data tables,
+  seed goes inside the table setup file. For all others, a standalone seed
+  file is generated in the seeds/ folder.
+---
+
+# Workflow: @db:seed
+
+## Goal
+Generate properly formatted INSERT seed data for a table. Determine whether
+seed belongs in the table file or a standalone seed file.
+
+## Rules
+- Passwords in seed data must be pre-encrypted — agent must ask for encrypted value
+- Never generate plaintext passwords in any file
+- Multi-row INSERT format always (single INSERT with multiple value tuples)
+- Seed file naming: `<repo_root>/database/<db_type>/seeds/<table_name>_seed.sql`
+
+---
+
+## Step-by-Step Execution
+
+### Phase 1 — Target
+1. Run task: `ask-table-name`
+   - List tables from `context.db.schema.tables`
+   - Stores: `context.current_db.table_name`
+
+---
+
+### Phase 2 — Seed File Type
+2. Agent checks if table is a reference/master table:
+   - Reference tables (seed goes IN setup file): tbl_country, tbl_app_content,
+     tbl_strategy_modules, tbl_admin, any lookup table
+   - All others: standalone seed file in seeds/
+
+   Ask: "Where should this seed data go?"
+   Options:
+   1. Append to the table's setup file (for reference/master data)
+   2. Create a standalone seed file in seeds/ (for dev/test data)
+
+   Stores: `context.current_db.seed_target`
+
+---
+
+### Phase 3 — Data Collection
+3. Show column list for the table from context.
+   
+4. Run task: `ask-seed-rows-count`
+   - Ask: "How many rows do you want to seed?"
+   - Stores: `context.current_db.seed_count`
+
+5. For each row (repeat seed_count times):
+   Run task: `ask-seed-row-values`
+   - For each column (excluding `id` and `created_at` — auto-generated):
+     - Ask the value one column at a time
+     - If column is `password` → warn: "Enter the encrypted/hashed value only. Never store plaintext."
+     - If column has CHECK constraint → show allowed values
+     - If column has DEFAULT → offer to use default (user can press enter to skip)
+   - Stores: appends to `context.current_db.seed_rows[]`
+
+---
+
+### Phase 4 — Generate
+6. Show full INSERT preview to user
+   - Ask: "Generate this seed data? (yes / no)"
+
+7. Delegate to `database-agent`:
+
+> **Claude Code sub-agent:** Spawn sub-agent: Task(database-agent)
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+   If appending to setup file:
+   - Read existing setup file
+   - Append after the GRANT line:
+   ```sql
+   INSERT INTO public.<table_name> (<col1>, <col2>, ...) VALUES
+   (<val1a>, <val2a>, ...),
+   (<val1b>, <val2b>, ...);
+   ```
+
+   If standalone seed file:
+   - Generate: `database/<db_type>/seeds/<table_name>_seed.sql`
+   ```sql
+   -- Seed data for <table_name>
+   -- Environment: development
+   -- Generated: <ISO date>
+
+   INSERT INTO public.<table_name> (<col1>, <col2>, ...) VALUES
+   (<val1a>, <val2a>, ...),
+   (<val1b>, <val2b>, ...);
+   ```
+
+8. Run task: `write-context`
+   - Append to `context.db.schema.change_log`:
+     `{ "type": "seed_added", "table": "<n>", "rows": <count> }`
+   - Clear `context.current_db`
+
+9. Run task: `show-final-summary`

package/ide/claude-code/.claude/commands/codeninja-db-sync.md

@@ -0,0 +1,106 @@
+This command runs when user types /codeninja:db-sync
+
+---
+type: workflow
+name: db-sync
+command: "@db:sync"
+description: >
+  Scan all migration files in the database folder and rebuild context.db.schema
+  from actual file contents. Safe to run at any time. Never destructive —
+  only adds or updates, never removes existing context entries.
+---
+
+# Workflow: @db:sync
+
+## Goal
+Make context.db.schema an accurate reflection of what is actually on disk.
+Parse every migration file in order and reconstruct the full schema state.
+
+---
+
+## Step-by-Step Execution
+
+### Phase 1 — Locate Files
+1. Read `context.db.type` to find the correct folder:
+   `<repo_root>/database/<db_type>/migrations/`
+   The database folder is always at repository root, never inside
+   a service folder.
+2. List all `.sql` files in that folder
+3. Sort them in numeric order by filename prefix (1, 2, 3... 111)
+4. Separate into categories:
+   - setup files: `*-setup-tbl-*.sql`
+   - alter files: `*-alter-tbl-*.sql`
+   - drop files: `*-drop-tbl-*.sql`
+   - index file: `111-setup-database-indexes.sql`
+
+---
+
+### Phase 2 — Parse Each File
+For each setup file (in order):
+- Extract table name from CREATE TABLE statement
+- Extract all column names and types
+- Extract CHECK constraints (enum values)
+- Extract COMMENT ON COLUMN lines (enum descriptions)
+- Extract per-file CREATE INDEX lines
+- Note if table has `status`, `is_deleted`, `created_at`
+
+For each alter file (in order after its setup file):
+- Parse ADD COLUMN → add to that table's columns
+- Parse RENAME COLUMN → update column name, record in change_log
+- Parse DROP COLUMN → remove from columns
+- Parse ADD CONSTRAINT → update column's constraint info
+
+For each drop file:
+- Mark that table as dropped in the scan result
+
+For the index file:
+- Parse all CREATE INDEX statements
+- Associate each index with its table
+
+---
+
+### Phase 3 — Rebuild Context
+
+> **Claude Code sub-agent:** Spawn sub-agent: Task(database-agent)
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+For each discovered table (not dropped):
+- Compare with existing `context.db.schema.tables[<table>]`
+- Add any tables not already in context
+- Add any columns not already tracked
+- Add any indexes not already tracked
+- For renames found in ALTER files → append to change_log if not already there
+
+For dropped tables:
+- If still in `context.db.schema.tables` → move to change_log snapshot
+- Remove from active tables list
+
+---
+
+### Phase 4 — Rebuild create-schema.sql
+- Re-read all file names in correct numeric order
+- Rewrite `create-schema.sql` to match actual files on disk
+- Report any \i entries that are in create-schema.sql but missing from disk (stale)
+- Report any files on disk not in create-schema.sql (missing)
+
+---
+
+### Phase 5 — Write and Report
+1. Run task: `write-context` with all schema deltas
+2. Display sync report:
+```
+@db:sync complete
+─────────────────────────────────────────
+Migration files scanned : [n]
+Tables discovered       : [n] ([x] new)
+Columns synced          : [n] ([x] new)
+Indexes synced          : [n] ([x] new)
+Renames detected        : [n]
+Dropped tables          : [n]
+create-schema.sql       : updated
+Context gaps filled     : [n]
+─────────────────────────────────────────
+```
+3. If any conflicts found (e.g. column exists in context with different type than file):
+   - List each conflict
+   - Ask user which to keep (file or context) — one at a time

package/ide/claude-code/.claude/commands/codeninja-debug.md

@@ -0,0 +1,99 @@
+This command runs when user types /codeninja:debug
+
+---
+type: workflow
+name: debug
+description: >
+  Diagnose and fix bugs using full project context — DB schema, middleware
+  chain, service config, and established patterns. Traces the exact failure
+  path and produces a concrete fix.
+---
+
+# Workflow: @debug / /codeninja:debug
+
+## Goal
+Find the root cause of a bug and produce a concrete fix using actual project
+context. Never guess — trace the real code path.
+
+## Rules
+- Trace the full request path before concluding anything
+- Cross-reference context.db.schema before assuming a DB mismatch
+- Check middleware chain order before assuming an auth issue
+- One question at a time when gathering information
+
+---
+
+## Step-by-Step Execution
+
+### Step 1 — Gather Error Information
+Ask (one at a time if not already provided):
+1. "Paste the full error message and stack trace."
+2. "Which endpoint or operation triggered it? (e.g., POST /v1/scores/submit)"
+3. "What did you expect to happen vs what actually happened?"
+4. "What changed recently before this error appeared?"
+
+### Step 2 — Load Context
+1. Call `context_read` — load services, DB schema, project config
+2. Call `fs_read` on the relevant route.js
+3. Call `fs_read` on the relevant _model.js
+4. Call `fs_exists` on the migration file for any table mentioned in the error
+
+### Step 3 — Trace the Failure Path
+
+Walk the request lifecycle in order:
+```
+Request received
+  → Language middleware (extracts Accept-Language)
+  → API key middleware (validates api-key header)
+  → Auth middleware (validates JWT, if protected)
+  → Validation (validatorjs schema)
+  → Route handler (calls model)
+  → Model function (executes query)
+  → Database (pg pool)
+  → Response formatter
+```
+
+Mark the exact step where the error occurs.
+
+### Step 4 — Check Common Root Causes
+
+| Symptom | Check |
+|---|---|
+| `column does not exist` | context.db.schema vs actual column names in model.js |
+| `undefined is not a function` | wrong import path or missing export in model |
+| `Cannot read property of undefined` | missing null check after DB query returns 0 rows |
+| `401 Unauthorized` | middleware order — apiKey middleware applied? header name correct? |
+| `500 Internal Server Error` | missing try/catch around async DB call |
+| `Wrong number of rows` | missing dedup query, RANK vs DENSE_RANK, missing WHERE clause |
+| `Migration not applied` | table exists in code but not in DB — run migration |
+| Stale context data | context.db.schema out of date — suggest /codeninja:db:sync |
+
+### Step 5 — Produce Fix
+
+> **Claude Code sub-agent:** No spawning — analysis only.
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+```
+Root cause: [one sentence — be precise]
+
+Fix:
+File: path/to/file.js
+
+Before:
+[the buggy code]
+
+After:
+[the corrected code]
+
+Why this fixes it: [one sentence]
+```
+
+If multiple files need changes, show each one in order.
+
+### Step 6 — Verify Plan
+"Before I apply this fix, confirm: does this match what you're seeing?
+Once confirmed, I'll make the changes."
+
+### Step 7 — Prevent Recurrence
+After fixing: suggest one guard that prevents this class of bug in the future.
+(e.g., a missing index, an added null check helper, a context convention)