codeninja 2.0.0 → 3.1.0

package/ide/antigravity/.agents/skills/api-builder/SKILL.md

@@ -0,0 +1,179 @@
+---
+skill: api-builder
+scope: nodejs-commands
+loaded-for:
+  - /codeninja:api
+  - /codeninja:init (nodejs type)
+  - /codeninja:audit
+  - /codeninja:test
+  - /codeninja:refactor
+  - /codeninja:sync
+description: >
+  All technical standards for Node.js/Express API development. Defines the
+  2-layer architecture, 5-step SOP, response contract, middleware chain order,
+  localizify rules, code style, and file generation standards.
+---
+
+# Skill: API Builder
+
+Technical standards for every NodeJS Express endpoint in this project.
+These rules apply to every file generated by the nodejs-backend persona.
+
+---
+
+## The 2-Layer Architecture (enforced without exception)
+
+Every API module lives in `modules/<version>/<ModuleName>/`:
+
+```
+modules/v1/<ModuleName>/
+├── route.js          ← HTTP layer ONLY
+└── <module>_model.js ← DB layer ONLY
+```
+
+**`route.js` responsibilities:**
+- Import and apply middleware
+- Define validatorjs schema
+- Call model function
+- Format and send `res.json()` response
+- Handle error boundary (try/catch)
+
+**`<module>_model.js` responsibilities:**
+- Execute parameterized SQL queries via shared pg pool
+- Implement business logic
+- Return raw data objects — never `res.json()`
+- Never import Express or touch the response object
+
+---
+
+## 5-Step SOP for Every New Endpoint
+
+Execute in this exact order — no skipping:
+
+1. **ROUTING** — append to `modules/<version>/route_manager.js`
+   - Never rewrite this file — surgical append only
+   - Use `file_insert_after` MCP tool
+
+2. **VALIDATION** — validatorjs schema in `route.js`
+   - Reference existing patterns in the service
+   - Never invent validation rules — match what already exists
+
+3. **CONTROLLER** — model call + error boundary in `route.js`
+   - Single try/catch wrapping the model call
+   - Call `sendResponse` from `utilities/response.js`
+
+4. **MODEL** — parameterized query in `<module>_model.js`
+   - pg pool from `config/database.js`
+   - Parameterized queries only — `$1`, `$2` placeholders
+   - Never string concatenation in SQL
+
+5. **LOCALIZE** — strings in `languages/en.js`
+   - Never hardcode user-facing strings in route.js or model.js
+   - Use `file_contains` to check if key already exists before adding
+
+---
+
+## Middleware Chain Order (always this order — never change)
+
+```
+Language extraction (headerValidator.js)
+→ API key validation (headerValidator.js)
+→ JWT authentication (headerValidator.js — protected routes only)
+→ Rate limiting (rateLimiter.js)
+→ Input validation (inline in route.js)
+→ Route handler
+```
+
+---
+
+## Response Contract
+
+All endpoints return the same shape:
+```javascript
+// Success
+{ status: 1, message: lang.success_key, data: result }
+
+// Error
+{ status: 0, message: lang.error_key }
+
+// Auth / session expired (triggers frontend logout)
+{ status: -1, message: lang.session_expired }
+```
+
+Use `sendResponse(req, res, status, message, data)` from `utilities/response.js`.
+Never call `res.json()` directly — always use `sendResponse`.
+
+---
+
+## Localizify Rules
+
+- `headerValidator.js` and `response.js` are the ONLY files that may import localizify or call `t()`
+- All other files use `sendResponse()`, `getMessage()`, or `req.t("keyword")`
+- Never call `setLocale` from model files — race condition under concurrent requests
+
+---
+
+## Swagger Maintenance Rules
+
+- `document/v1/swagger_doc.json` is patched — never fully rewritten
+- When adding a new endpoint: add only the new path key to `paths` object
+- Use `file_insert_after` MCP tool for surgical patch
+- Always update the `info.version` timestamp when patching
+
+---
+
+## route_manager.js Maintenance Rules
+
+- Append-only — never rewrite the entire file
+- New module import goes at top of imports section
+- New router.use() goes at end of routes section
+- Use `file_insert_after` MCP tool
+
+---
+
+## Testing Standards (Jest + Supertest)
+
+Test file location: `tests/v1/<ModuleName>.test.js`
+
+Structure:
+```javascript
+describe('<ModuleName> API', () => {
+  describe('POST /<path>', () => {
+    it('should return 200 with valid payload', async () => { ... })
+    it('should return 400 with missing required field', async () => { ... })
+    it('should return 401 with invalid api-key', async () => { ... })
+  })
+})
+```
+
+- Test the happy path first, then each validation failure
+- Test missing required fields, wrong types, out-of-range values
+- Test auth failure separately
+- Never test implementation details — test behavior via HTTP
+
+---
+
+## JSDoc Standards (enforced on every function)
+
+```javascript
+/**
+ * One-sentence description. Active voice. Present tense.
+ *
+ * @param {type} name - Description of what it expects.
+ * @returns {Promise<Object>} Description of what it returns.
+ */
+```
+
+Special cases:
+- Middleware: `@middleware` tag, no `@returns`
+- Async: `@returns {Promise<T>}`
+- Optional: `@param {string} [lang='en'] - Language code`
+
+Route-level comment (above route definition, not JSDoc):
+```javascript
+// POST /login — Authenticates user credentials and returns a session token.
+router.post('/login', async (req, res) => {
+```
+
+No inline `//` comments inside function bodies.
+No file-level headers at top of files.

package/ide/antigravity/.agents/skills/code-intelligence/SKILL.md

@@ -0,0 +1,184 @@
+---
+skill: code-intelligence
+scope: analysis-commands
+loaded-for:
+  - /codeninja:explain
+  - /codeninja:review
+  - /codeninja:debug
+  - /codeninja:optimize
+  - /codeninja:audit
+description: >
+  Analysis and intelligence standards for explain, review, debug, optimize,
+  and audit commands. Defines how to read code with full project context,
+  how to report findings, and how to produce concrete fixes.
+---
+
+# Skill: Code Intelligence
+
+Standards for all analysis commands. Every finding is grounded in actual
+project files and real context values — never generic advice.
+
+---
+
+## Before Any Analysis
+
+1. Call `context_read` — load full context (services, DB schema, project info)
+2. Call `fs_read` on the target file(s)
+3. Read 1–2 sibling files to understand the expected pattern in this project
+4. Reference real table names, column names, and service names from context — never placeholders
+
+---
+
+## /codeninja:explain — Response Structure
+
+```
+What it is (1–2 sentences, plain English)
+How it works (step-by-step key logic — not boilerplate)
+Why this way (architectural reason specific to this project)
+Where it connects (related files, functions, context entries)
+```
+
+Rules:
+- Use real file names, real column names, real service names from context
+- Explain the "why" — the decision behind the pattern, not just what it does
+- Reference `context.project_info` to tie the explanation to the project's domain
+- End with: "Want me to explain any part in more detail, or show how to modify it?"
+
+---
+
+## /codeninja:review — Checklist and Output Format
+
+### Security (CRITICAL if failing)
+- [ ] All POST/PUT/PATCH routes have validatorjs input validation
+- [ ] API key middleware applied before any route logic
+- [ ] JWT auth middleware on protected routes
+- [ ] No hardcoded secrets, keys, or passwords in any file
+- [ ] Parameterized queries only — no string concatenation in SQL
+- [ ] Error responses don't leak stack traces or internal details
+
+### Architecture (WARNING if failing)
+- [ ] 2-layer rule: no SQL in route.js, no res.json() in _model.js
+- [ ] route_manager.js registration matches the route file
+- [ ] swagger_doc.json has entry for this endpoint
+- [ ] All user-facing strings in languages/en.js — none hardcoded in route.js
+
+### Code Quality (SUGGESTION if failing)
+- [ ] JSDoc on every exported function
+- [ ] No unused variables or dead imports
+- [ ] No console.log — project logger used
+- [ ] Async functions have try/catch
+- [ ] No SELECT * — explicit column list
+
+### Database (WARNING if failing)
+- [ ] Column names match context.db.schema exactly (snake_case)
+- [ ] Foreign key columns indexed in context.db.schema
+- [ ] Transactions used where multiple writes happen together
+- [ ] LIMIT on any unbounded query
+
+### Output format per finding:
+```
+[CRITICAL | WARNING | SUGGESTION]
+File:   path/to/file.js  (~line N)
+Issue:  one-line description
+Before: current code
+After:  corrected code
+Why:    one sentence
+```
+
+End: `Review complete: X critical · Y warnings · Z suggestions`
+Offer to apply each fix — confirm before writing.
+
+---
+
+## /codeninja:debug — Diagnosis Process
+
+### Information to gather (one at a time if missing)
+1. Full error message + stack trace
+2. Which endpoint or operation triggered it
+3. Expected vs actual behaviour
+4. Recent changes before the error appeared
+
+### Request lifecycle trace
+```
+Request received
+  → Language middleware
+  → API key middleware
+  → Auth middleware (if protected)
+  → Validation (validatorjs)
+  → Route handler
+  → Model function
+  → Database (pg pool)
+  → Response formatter
+```
+Mark the exact step where the failure occurs.
+
+### Common root causes
+| Symptom | Check |
+|---------|-------|
+| `column does not exist` | context.db.schema vs code column names |
+| `undefined is not a function` | wrong import or missing export |
+| `Cannot read property of undefined` | missing null check after 0-row query |
+| `401 Unauthorized` | middleware order, header name spelling |
+| `500 Internal Server Error` | missing try/catch on async DB call |
+| Wrong row count | missing dedup, RANK vs DENSE_RANK, missing WHERE |
+| Migration not applied | table in code but not in DB — run migration |
+| Stale context | context.db.schema outdated — suggest /codeninja:db:sync |
+
+### Fix output format:
+```
+Root cause: [one sentence — be precise]
+
+File: path/to/file.js
+Before: [buggy code]
+After:  [corrected code]
+Why:    [one sentence]
+```
+
+Confirm with user before applying. After fix: suggest one guard to prevent recurrence.
+
+---
+
+## /codeninja:optimize — Analysis Framework
+
+### DB query analysis (check all)
+1. **Missing indexes** — compare WHERE/JOIN/ORDER BY cols vs `context.db.schema.<table>.indexes`
+2. **SELECT *** — suggest explicit column list
+3. **N+1** — loop calling DB per iteration → suggest JOIN or IN clause
+4. **No LIMIT** — unbounded queries must have pagination
+5. **RANK() vs DENSE_RANK()** — flag RANK() on leaderboard queries (gaps after ties)
+6. **DATE() in WHERE** — `DATE(col) = '...'` prevents index use → use range filter
+7. **Duplicate rows** — missing dedup → `MIN(id) GROUP BY`
+8. **Sort spilling to disk** — EXPLAIN shows "external merge Disk" → suggest `work_mem = '64MB'`
+
+### API route analysis
+- Repeated DB calls that could be Redis-cached
+- Synchronous blocking in request path
+- Large response payloads without pagination
+
+### Output format per recommendation:
+```
+[HIGH | MED | LOW]
+Target:  what is slow
+Cause:   why it is slow
+Fix:     exact SQL or code change
+Gain:    concrete estimate (e.g. "seq scan → index scan, ~400x on 2M rows")
+```
+
+List highest impact first.
+For index additions: generate `<N>-add-index-<desc>.sql` migration file via `migration_next_number`.
+Always call `context_write` after applying index changes.
+
+---
+
+## /codeninja:audit — Full Service Audit
+
+Runs the full review checklist above PLUS:
+- Middleware chain order (use `analyze_middleware_order` MCP tool)
+- Encryption library consistency (use `analyze_encryption_library` MCP tool)
+- Language key completeness (use `analyze_language_keys` MCP tool)
+- Dependency health (use `analyze_dependencies` MCP tool)
+- .env completeness (use `analyze_env_file` MCP tool)
+- context.db.schema alignment with actual code table/column references
+
+Output: severity-ranked report grouped by category.
+Offer to auto-fix SUGGESTION items. Fix WARNING/CRITICAL one at a time with confirmation.

package/ide/antigravity/.agents/skills/database/SKILL.md

@@ -0,0 +1,165 @@
+---
+skill: database
+scope: database-commands
+loaded-for:
+  - /codeninja:db:create
+  - /codeninja:db:modify
+  - /codeninja:db:index
+  - /codeninja:db:drop
+  - /codeninja:db:seed
+  - /codeninja:db:sync
+  - /codeninja:init (database type)
+  - /codeninja:optimize (DB queries)
+description: >
+  All database standards: naming conventions, migration file rules, index
+  strategy, column rules, SQL content order, create-schema.sql maintenance,
+  and seed data rules. The database-architect persona uses this skill for
+  every SQL file it generates.
+---
+
+# Skill: Database
+
+Technical standards for every SQL file and migration in this project.
+Apply without exception.
+
+---
+
+## Before Generating Any File
+
+1. Call `context_read` — load `context.db` fully
+2. Call `context.project_info` — use entities/features to suggest columns
+3. Call `migration_next_number` MCP tool — get the next sequential number
+4. NEVER invent table or column names
+
+---
+
+## Naming Quick Reference
+
+| Element | Rule | Example |
+|---------|------|---------|
+| Table | `tbl_` prefix, lowercase, plural | `tbl_users` |
+| Column | lowercase snake_case | `user_id`, `created_at` |
+| PK | `id`, bigint identity, first column | always |
+| FK | `<table_singular_no_prefix>_id` | `user_id` refs `tbl_users` |
+| Index (per-table) | `idx_<table_no_prefix>_<cols>` | `idx_users_email` |
+| Index (global) | `idx_tbl_<table>_<cols>` | `idx_tbl_users_email_is_deleted` |
+| Migration (create) | `<N>-setup-tbl-<name>.sql` | `3-setup-tbl-users.sql` |
+| Migration (alter) | `<N>-alter-tbl-<name>-<desc>.sql` | `12-alter-tbl-users-add-kyc.sql` |
+| Migration (drop) | `<N>-drop-tbl-<name>.sql` | `13-drop-tbl-sessions.sql` |
+| Shared indexes | `111-setup-database-indexes.sql` | always last, always 111 |
+
+---
+
+## Column Type Reference
+
+| Use Case | PostgreSQL Type |
+|----------|----------------|
+| Primary key | `bigint NOT NULL GENERATED ALWAYS AS IDENTITY (INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1)` |
+| Foreign key | `BIGINT NOT NULL DEFAULT 0` |
+| Names, labels | `VARCHAR(64)` to `VARCHAR(255)` |
+| Short codes, symbols | `VARCHAR(8)` to `VARCHAR(32)` |
+| Emails | `VARCHAR(132)` |
+| Tokens, passwords | `TEXT` |
+| URLs, paths | `VARCHAR(255)` |
+| Timestamps | `TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` |
+| Status/flag | `INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0, 1))` |
+| Soft delete | `BOOLEAN NOT NULL DEFAULT FALSE` |
+| Price/financial | `NUMERIC(18,8) NOT NULL DEFAULT 0.00000000` |
+| Percentage | `NUMERIC(6,2) NOT NULL DEFAULT 0.00` |
+| Count/integer | `BIGINT NOT NULL DEFAULT 0` |
+| JSON data | `JSON NOT NULL DEFAULT '{}'` |
+
+**NEVER use PostgreSQL ENUM** — always `VARCHAR + CHECK constraint`.
+
+---
+
+## Required Columns by Table Type
+
+| Column | Every table | Entity tables | Log/event tables |
+|--------|------------|---------------|-----------------|
+| `id` | ✓ | ✓ | ✓ |
+| `created_at` | ✓ | ✓ | ✓ |
+| `status` | — | ✓ | — |
+| `is_deleted` | — | ✓ (soft delete) | — |
+| `updated_at` | — | ✓ (tracked edits) | — |
+
+---
+
+## SQL File Content Order (STRICT)
+
+```sql
+-- 1. Comment: Creating <table> for <purpose>
+-- 2. DROP TABLE IF EXISTS public.<table> CASCADE;
+-- 3. CREATE TABLE block (id first, timestamps last)
+-- 4. COMMENT ON COLUMN for every enum/flag column
+-- 5. Per-table CREATE INDEX statements
+-- 6. ALTER TABLE public.<table> OWNER TO <db_user>;
+-- 7. GRANT ALL ON TABLE public.<table> TO <db_user>;
+-- 8. INSERT seed data (reference tables only)
+```
+
+---
+
+## Primary Key Block (exact format)
+
+```sql
+id bigint NOT NULL GENERATED ALWAYS AS IDENTITY (INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1),
+```
+
+Primary key constraint at END of column list:
+```sql
+    PRIMARY KEY (id)
+```
+Never declare `PRIMARY KEY` inline on the `id` column.
+
+---
+
+## Index Strategy
+
+Always index:
+- Every FK column (`user_id`, `bot_id`, etc.)
+- `(status, is_deleted)` compound on entity tables
+- `created_at DESC` on log/event tables
+- `email` compound with `is_deleted` on user tables
+- Any column used in WHERE or ORDER BY in business queries
+
+Compound index — most selective column first.
+Descending index — use `(<col> DESC)` when always sorted descending.
+
+Per-table indexes go in the table file.
+Cross-table / multi-service indexes go in `111-setup-database-indexes.sql`.
+
+---
+
+## create-schema.sql Rules
+
+- Lives at `<repo_root>/database/<db_type>/create-schema.sql`
+- Auto-generated — never edited manually
+- Contains `\i <filename>` in strict numeric order
+- `111-setup-database-indexes.sql` always last
+
+After EVERY table operation — update this file:
+1. `fs_read` the current file
+2. Insert/remove/reorder `\i` entries
+3. ALTER files immediately after CREATE for that table
+4. DROP files after ALTER files for that table
+5. Write back via `fs_read` + `file_insert_after` MCP tool
+6. Log to `context.change_log`
+
+---
+
+## Query Optimisation Patterns
+
+When asked to optimise a query (via `/codeninja:optimize`):
+
+1. Check `context.db.schema.<table>.indexes` against WHERE/JOIN/ORDER BY columns
+2. Flag seq scans → suggest `CREATE INDEX CONCURRENTLY`
+3. Flag `SELECT *` → suggest explicit column list
+4. Flag N+1 patterns → suggest JOIN or IN clause
+5. Flag missing `LIMIT` on unbounded queries
+6. Flag `RANK()` with gaps → suggest `DENSE_RANK()` for leaderboards
+7. Flag `DATE(col)` in WHERE → suggest range filter to preserve index use
+8. Flag duplicate rows → suggest dedup with `MIN(id) GROUP BY`
+9. Suggest `work_mem = '64MB'` session-level if sort spilling to disk
+
+Always provide: before/after query, estimated improvement, migration file if new index.

package/ide/antigravity/.agents/skills/mcp-and-context/SKILL.md

@@ -0,0 +1,111 @@
+---
+skill: mcp-and-context
+scope: always-loaded
+description: >
+  MCP tool usage rules and context management protocol. Loaded on every
+  session. Governs how every persona reads, writes, and protects context.json.
+---
+
+# Skill: MCP and Context Management
+
+This skill governs all interaction with the codeninja MCP server and
+context.json. Every persona must follow these rules without exception.
+
+---
+
+## Available MCP Tools
+
+| Tool | Purpose | When to use |
+|------|---------|-------------|
+| `context_read` | Load full project context | First thing on every activation |
+| `context_write` | Persist changes (deep-merge) | After every completed operation |
+| `context_clear_scratchpad` | Clear a current_* key | After writing context |
+| `context_check_stale` | Detect unresolved scratchpad | Step 0 of activation |
+| `service_scan` | Discover all services on disk | Step 2 of activation |
+| `migration_next_number` | Get next sequential migration number | Before creating any migration file |
+| `fs_read` | Read a file from disk | Before modifying any existing file |
+| `fs_list` | List directory contents | When scanning structure |
+| `fs_exists` | Check if file/directory exists | Before conditional operations |
+| `file_insert_after` | Surgical file insertion | Appending to route_manager.js, etc. |
+| `file_contains` | Check if string exists in file | Before appending to avoid duplicates |
+| `run_drift_check` | Compare context vs disk | During @sync workflow |
+| `lint_file` | Lint a generated file | After generating JS/SQL files |
+| `npm_check_package` | Look up npm package info | When verifying dependencies |
+| `npm_install` | Install a package | When adding new dependencies |
+| `validate_redis_connection` | Test Redis connectivity | During service init |
+| `validate_postgres_connection` | Test DB connectivity | During service init |
+| `analyze_middleware_order` | Check middleware chain | During @audit |
+| `analyze_encryption_library` | Verify encryption setup | During @audit |
+| `analyze_language_keys` | Check i18n completeness | During @audit |
+| `analyze_dependencies` | Scan package.json | During @audit / @sync |
+| `analyze_env_file` | Check .env completeness | During @audit |
+
+---
+
+## Absolute Rules
+
+- NEVER read `context.json` directly with `fs_read` — always use `context_read`
+- NEVER write `context.json` directly — always use `context_write`
+- `context_write` deep-merges — it never overwrites the whole file
+- `change_log` is append-only — never delete entries
+- NEVER assume a stored value — always read from loaded context object
+- `context_version` is managed automatically — if `context_read` returns a
+  higher version than expected, the file was modified externally — re-read before acting
+
+---
+
+## Context Schema Reference
+
+```json
+{
+  "context_version": 0,
+  "project_name": "",
+  "project_info": {
+    "summary": "",
+    "detected_entities": [],
+    "features": [],
+    "from_doc": { "project_name": "", "domain": "", "purpose": "", "features": [], "entities": [], "tech_preferences": [] },
+    "from_sow": { "integrations": [] },
+    "from_figma": { "screens": [] }
+  },
+  "db": {
+    "type": "",
+    "name": "",
+    "host": "",
+    "port": 0,
+    "user": "",
+    "schema": {}
+  },
+  "services": {},
+  "api_routes": [],
+  "change_log": []
+}
+```
+
+---
+
+## Scratchpad Keys (current_* pattern)
+
+Temporary keys written during multi-step workflows:
+
+| Key | Used by |
+|-----|---------|
+| `current_init` | initialize-project workflow |
+| `current_api` | create-api workflow |
+| `current_table` | db-create-table workflow |
+| `current_modify` | db-modify-table workflow |
+| `current_index` | db-add-index workflow |
+| `current_design` | design workflow |
+
+After `context_write` with final results → always call `context_clear_scratchpad`
+for the relevant key. This prevents stale data from persisting across sessions.
+
+---
+
+## Stale Scratchpad Recovery
+
+When `context_check_stale` returns stale keys:
+1. Show the user what was in progress
+2. Ask: "Resume this operation or discard it?"
+3. If resume → re-read the scratchpad and continue from where it left off
+4. If discard → call `context_clear_scratchpad` and start fresh