codeninja 2.0.0 → 3.2.0

package/ide/antigravity/.agents/workflows/codeninja-db-modify.md

@@ -0,0 +1,106 @@
+---
+slash_command: /codeninja:db:modify
+personas: [global-orchestrator, database-architect]
+skills: [mcp-and-context, database]
+description: Modify an existing table via a numbered ALTER migration file.
+---
+
+# /codeninja:db:modify
+
+## Before Running
+1. Call `context_read` — load `context.db.schema` fully
+2. Call `context_check_stale`
+3. Call `migration_next_number` to get next sequential number
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Target
+
+**Step 1.** Ask: "Which table?" (list from `context.db.schema.tables`)
+- Store: `context.current_db.table_name`
+
+**Step 2.** Ask: "What operation?"
+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 → route to /codeninja:db:index instead
+- Store: `context.current_db.modify_operation`
+
+---
+
+### Phase 2 — Operation Details
+
+#### If "Add a new column":
+- Ask: "New column name?" (snake_case, lowercase)
+- Ask: "Column type?" (show type suggestions from naming patterns — same as db:create)
+- Ask: "Is this an enum column?" — if yes, collect allowed values
+- Ask: "Add column after which existing column?" (list current columns from context)
+- SQL generated: `ALTER TABLE public.<table> ADD COLUMN <col> <type> NOT NULL DEFAULT <default>;`
+
+#### If "Rename a column":
+- Ask: "Which column to rename?" (list current columns from context)
+- Ask: "New column name?" (snake_case)
+- SQL generated: `ALTER TABLE public.<table> RENAME COLUMN <old> TO <new>;`
+
+#### If "Drop a column":
+- Ask: "Which column to drop?" (list current columns)
+- 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)"
+- SQL generated: `ALTER TABLE public.<table> DROP COLUMN IF EXISTS <col>;`
+
+#### If "Change a column type":
+- Ask: "Which column?" (list current columns)
+- Ask: "New type?" (warn about potential data loss for narrower types)
+- SQL generated: `ALTER TABLE public.<table> ALTER COLUMN <col> TYPE <new_type> USING <col>::<new_type>;`
+
+#### If "Add CHECK constraint":
+- Ask: "Which column?" (list current columns)
+- Ask: "Allowed values?" (comma-separated)
+- SQL generated: `ALTER TABLE public.<table> ADD CONSTRAINT chk_<table>_<col> CHECK (<col> IN (<values>));`
+  Plus: `COMMENT ON COLUMN public.<table>.<col> IS '<enum explanation>';`
+
+---
+
+### Phase 3 — File Numbering
+
+**Step 7.** Ask: "Migration file number?" (agent suggests next available)
+- Store: `context.current_db.file_number`
+
+---
+
+### Phase 4 — Confirm and Generate
+
+**Step 8.** Show the exact SQL that will be generated. Ask: "Generate? (yes / no)"
+
+**Step 9.** Delegate to database-agent:
+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>;
+
+-- COMMENT ON COLUMN if enum/flag column
+-- CREATE INDEX if new column needs one
+
+COMMIT;
+```
+Update: `database/<db_type>/create-schema.sql`
+
+**Step 10.** Call `context_write`:
+- Update `context.db.schema.tables[<table>].columns`
+- Append to `context.db.schema.change_log`
+- Clear `context.current_db`
+
+**Step 11.** Call `context_clear_scratchpad` with keys: ["current_db"]
+
+**Step 12.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-db-seed.md

@@ -0,0 +1,76 @@
+---
+slash_command: /codeninja:db:seed
+personas: [global-orchestrator, database-architect]
+skills: [mcp-and-context, database]
+description: Add seed/initial data to a table.
+---
+
+# /codeninja:db:seed
+
+## Before Running
+1. Call `context_read` — load `context.db.schema`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Target
+
+**Step 1.** Ask: "Which table?" (list from `context.db.schema.tables`)
+- Store: `context.current_db.table_name`
+
+### Phase 2 — Seed File Type
+
+**Step 2.** Determine seed target:
+- Reference tables (seed goes IN setup file): lookup tables, master/config tables
+- All other tables: standalone seed file in seeds/
+
+Ask: "Where should this seed data go?"
+1. Append to the table's setup file (for reference/master data)
+2. Create standalone seed file in seeds/ (for dev/test data)
+- Store: `context.current_db.seed_target`
+
+### Phase 3 — Data Collection
+
+**Step 3.** Show column list from context (excluding `id` and `created_at` — auto-generated).
+
+**Step 4.** Ask: "How many rows do you want to seed?"
+- Store: `context.current_db.seed_count`
+
+**Step 5.** For each row (repeat seed_count times):
+- Ask value for each column one 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 (press Enter to skip)
+- Append to: `context.current_db.seed_rows[]`
+
+### Phase 4 — Generate
+
+**Step 6.** Show full INSERT preview. Ask: "Generate this seed data? (yes / no)"
+
+**Step 7.** Delegate to database-agent:
+
+If appending to 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>, ...);
+```
+
+**Step 8.** Call `context_write`:
+- Append to `context.db.schema.change_log`: `{ type: "seed_added", table: "<n>", rows: <count> }`
+- Clear `context.current_db`
+
+**Step 9.** Call `context_clear_scratchpad` with keys: ["current_db"]
+
+**Step 10.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-db-sync.md

@@ -0,0 +1,70 @@
+---
+slash_command: /codeninja:db:sync
+personas: [global-orchestrator, database-architect]
+skills: [mcp-and-context, database]
+description: Scan all migration files and rebuild context.db.schema from actual file contents.
+---
+
+# /codeninja:db:sync
+
+## Before Running
+1. Call `context_read`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Locate Files
+
+**Step 1.** Read `context.db.type` → find `<repo_root>/database/<db_type>/migrations/`
+**Step 2.** List all `.sql` files, sort by numeric prefix (1, 2, 3… 111)
+**Step 3.** Categorize:
+- 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
+- Extract all column names and types
+- Extract CHECK constraints and 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):
+- ADD COLUMN → add to that table's columns
+- RENAME COLUMN → update name, record in change_log
+- DROP COLUMN → remove from columns
+- ADD CONSTRAINT → update column constraint info
+
+For each drop file: mark table as dropped.
+
+For the index file: parse all CREATE INDEX, associate each with its table.
+
+### Phase 3 — Rebuild Context
+
+For each discovered table (not dropped):
+- Compare with existing `context.db.schema.tables[<table>]`
+- Add tables not already in context
+- Add columns not already tracked
+- Add indexes not already tracked
+- For renames 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
+
+### Phase 4 — Rebuild create-schema.sql
+
+- Re-read all filenames in correct numeric order
+- Rewrite `create-schema.sql` to match actual files on disk
+- Report: any `\i` entries in create-schema.sql missing from disk (stale)
+- Report: any files on disk not in create-schema.sql (missing)
+
+### Phase 5 — Finalize
+
+**Step 5.** Show sync report: tables synced, columns added, indexes added, stale entries, missing files.
+
+**Step 6.** Call `context_write` with rebuilt `context.db.schema`.
+
+**Step 7.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-debug.md

@@ -0,0 +1,82 @@
+---
+slash_command: /codeninja:debug
+personas: [global-orchestrator, nodejs-backend]
+skills: [mcp-and-context, api-builder, code-intelligence]
+description: Diagnose and fix bugs using full project context and code path tracing.
+---
+
+# /codeninja:debug
+
+## Before Running
+1. Call `context_read` — load services, DB schema, project config
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Step 1 — Gather Error Information (ask one at a time if not 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 vs what actually happened?"
+4. "What changed recently before this error appeared?"
+
+### Step 2 — Load Context
+1. Call `fs_read` on the relevant `route.js`
+2. Call `fs_read` on the relevant `_model.js`
+3. 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 — mark the exact step where failure occurs:
+```
+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 / mysql2 / mongoose)
+  → Response formatter
+```
+
+### 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, 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
+
+```
+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 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)

package/ide/antigravity/.agents/workflows/codeninja-design.md

@@ -0,0 +1,54 @@
+---
+slash_command: /codeninja:design
+personas: [global-orchestrator, nodejs-backend, database-architect]
+skills: [mcp-and-context, api-builder, database]
+description: Plan a feature, API contract, or database change before writing any code.
+---
+
+# /codeninja:design
+
+## Before Running
+1. Call `context_read`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Scope
+
+**Step 1.** Ask: "What are you designing?"
+- Options: new feature / new API endpoint / database change / full module
+- Store: `context.current_design.type`
+
+**Step 2.** Ask: "Feature or module name?"
+- Store: `context.current_design.feature_name`
+
+**Step 3.** Ask: "What should this feature do?" (free text)
+- Store: `context.current_design.description`
+
+### Phase 2 — Database Design (if applicable)
+
+**Step 4.** If design involves data storage:
+- Delegate to database-agent
+- Design table structure, column types, indexes, relationships
+- Present schema proposal for feedback
+- Allow changes one at a time
+
+### Phase 3 — API Design (if applicable)
+
+**Step 5.** If design involves API endpoints:
+- Delegate to nodejs-agent
+- Propose: method, path, request body, response shape, auth requirement
+- Present for feedback
+
+### Phase 4 — Output
+
+**Step 6.** Generate `.codeninja/agent/designs/<feature_name>.design.md`:
+- Feature summary
+- DB schema proposal (tables, columns, indexes, relationships)
+- API contracts (method, path, request, response shape)
+- Open questions / decisions needed
+
+**Step 7.** Ask: "Save this design and mark planned routes/schema in context? (yes/no)"
+If yes → call `context_write` with operation "design", then `context_clear_scratchpad` ["current_design"]
+
+**Step 8.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-explain.md

@@ -0,0 +1,40 @@
+---
+slash_command: /codeninja:explain
+personas: [global-orchestrator]
+skills: [mcp-and-context, code-intelligence]
+description: Explain any file, function, pattern, or concept using full project context.
+---
+
+# /codeninja:explain
+
+## Before Running
+1. Call `context_read`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Step 1 — Identify Target
+If not specified, ask: "What would you like me to explain?
+(e.g., a file path, a function name, a pattern like 'the auth middleware',
+or a concept like 'why we use DENSE_RANK')"
+
+### Step 2 — Load Context
+1. Call `fs_read` on the target file (if a file was specified)
+2. Read 1 related file to understand how the target fits in the system
+3. Reference `context.db.schema` for any table/column mentions
+4. Reference `context.services` for service names and ports
+
+### Step 3 — Explain
+
+Structure every explanation as:
+
+**What it is** (1–2 sentences — plain English)
+
+**How it works** (step-by-step walkthrough of the key logic)
+
+**Why this way** (the architectural decision behind it)
+
+**Where it connects** (related files and functions in this project — use real names)
+
+### Step 4 — Offer Follow-up
+End with: "Want me to explain any part in more detail, or show how to modify it?"