codeninja 3.2.0 → 4.0.0

package/ide/vscode/.github/copilot-instructions.md

@@ -1,399 +1,84 @@
-# codeninja — Project Intelligence for GitHub Copilot
+# codeninja — Project Intelligence for GitHub Copilot (v4.0)
 
 This file is auto-loaded by GitHub Copilot Agent Mode.
-It gives Copilot full awareness of this project's architecture, conventions,
-and all available slash commands.
 
 ---
 
-## Section 1 — Global Orchestrator
-
-You are a Senior Software Architect managing this project via the codeninja system.
-
-### Activation Sequence (every session)
+## Activation Sequence (every session)
 1. Call `context_check_stale` — resolve stale operations first
-2. Call `context_read` — load full context
-3. Call `service_scan` — compare with `context.services`; suggest `/codeninja:sync` if drift
-4. Load `context.project_info` for all suggestions
-
-### Routing
-| Keyword trigger | Specialist domain |
-|---|---|
-| express, node, api, service, encryption | NodeJS / API Builder |
-| react, frontend, ui, component, page | ReactJS |
-| postgres, mysql, db, schema, migration, table | Database |
-| `/codeninja:db:*` | always Database |
+2. Call `context_read` — load full project context
+3. Call `service_scan` — compare with `context.services`; if drift → suggest `/codeninja:sync`
+4. Load `context.project_info` — use for all suggestions throughout session
 
-### Context Rules
-- NEVER read/write `context.json` directly — always `context_read` / `context_write`
-- `context_write` deep-merges — never overwrites the whole file
+## Context Rules
+- NEVER read/write context.json directly — always `context_read` / `context_write`
+- `context_write` deep-merges — never overwrites
 - `change_log` is append-only
-- After every completed workflow → call `context_clear_scratchpad` for `current_*` key
+- After every completed workflow → call `context_clear_scratchpad` for relevant `current_*` key
 
-### Batch Generation Rule
-ONE confirmation per operation. After user confirms → generate all files silently.
-No per-file prompts during any scaffolding workflow.
+## Keyword Routing
+| Trigger | Specialist Domain |
+|---|---|
+| express, node, api, service, encryption, typescript | NodeJS standards |
+| react, frontend, ui, component, page | ReactJS standards |
+| postgres, mysql, db, schema, migration, table, prisma, orm | Database standards |
+| `/codeninja:db:*` | always Database standards |
+
+## Batch Generation Rule
+ONE confirmation per operation → generate ALL files silently after confirmation, no per-file prompts.
 
-### Response Style
+## Response Style
 - One question at a time
 - Confirm before creating or modifying files
-- `database/` folder ALWAYS at repository root — never inside a service folder
-- After scaffolding → always show final summary
-
----
-
-## Section 2 — MCP Tools Reference
+- `database/` folder ALWAYS at repository root
+- After every scaffolding operation → show final summary
 
+## All Available Commands
+| Command | Description |
+|---|---|
+| `/codeninja:init` | Bootstrap NodeJS service (JS/TS, raw/Prisma), ReactJS app, or database |
+| `/codeninja:api` | Add new API endpoint (route + model + swagger) |
+| `/codeninja:design` | Plan feature before coding |
+| `/codeninja:audit` | Security and quality review |
+| `/codeninja:test` | Generate Jest + Supertest tests |
+| `/codeninja:refactor` | Rename/restructure with context tracking |
+| `/codeninja:sync` | Rebuild context.json from repo |
+| `/codeninja:explain` | Explain any file, function, or concept |
+| `/codeninja:review` | Code review with severity-ranked findings |
+| `/codeninja:debug` | Diagnose and fix bugs |
+| `/codeninja:optimize` | Performance analysis with concrete fixes |
+| `/codeninja:db:create` | New table with migration file |
+| `/codeninja:db:modify` | Alter table via migration |
+| `/codeninja:db:index` | Add index |
+| `/codeninja:db:drop` | Drop table (safety-checked) |
+| `/codeninja:db:seed` | Add seed data |
+| `/codeninja:db:sync` | Rebuild DB schema context from migrations |
+| `/codeninja:modularize` | Extract ReactJS layout components |
+| `/codeninja:validate-page` | Add form validation to ReactJS page |
+| `/codeninja:integrate-api` | Wire ReactJS forms to backend |
+
+## MCP Tools Quick Reference
 | Tool | Purpose | When |
 |---|---|---|
-| `context_read` | Load project context | FIRST on every activation |
-| `context_write` | Persist changes (deep-merge) | After every completed operation |
+| `context_read` | Load context.json | First on every activation |
+| `context_write` | Deep-merge updates | After every completed operation |
 | `context_clear_scratchpad` | Clear 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` | Next sequential migration number | Before any migration file |
-| `fs_read` | Read file from disk | Before modifying |
-| `fs_list` | List directory | When scanning structure |
-| `fs_exists` | Check existence | Before conditional ops |
-| `file_insert_after` | Surgical file insertion | route_manager.js, swagger |
-| `file_contains` | Check before appending | Avoid duplicates |
-| `run_drift_check` | Context vs disk | During /codeninja:sync |
-| `lint_file` | Lint generated file | After JS/SQL generation |
-| `analyze_middleware_order` | Check middleware chain | During /codeninja:audit |
-| `analyze_encryption_library` | Verify encryption | During /codeninja:audit |
-| `analyze_language_keys` | Check i18n | During /codeninja:audit |
-| `analyze_dependencies` | Scan package.json | During /codeninja:audit |
-| `analyze_env_file` | Check .env completeness | During /codeninja:audit |
-| `validate_redis_connection` | Test Redis | During init |
-| `validate_postgres_connection` | Test DB | During init |
-
----
-
-## Section 3 — /codeninja:init — Project Initialization
-
-### Phase 0 — Project Info (ONCE per repo — skip if context.project_info already populated)
-- Ask for project info doc (URL or paste content) → store in context.project_info
-- Ask for scope of work doc (URL or paste) → store in context.project_info
-- Ask for Figma URL → store in context.project_info
-- Synthesize: context.project_info.summary (150–200 words) and detected_entities[]
-
-### Phase 1 — Mode and Project Type
-- Ask: Fast setup (9 questions, auto-generates secure values) OR Manual setup (22 questions)
-- Ask: NodeJS service | ReactJS frontend | Database only
-- NodeJS: also ask client_type (reactjs web|mobile app), encrypted_transport, supported_languages[]
-- ReactJS: list existing NodeJS services from context.services — REQUIRE linked service.
-  Auto-inherit encryption_key, encryption_iv, api_key from linked backend — NEVER ask user.
-  Skip DB phase (no DB for ReactJS). Skip security questions (inherited).
-
-### Phase 2 — Database (NodeJS and Database-only)
-- Ask: database type (postgresql|mysql|mongodb)
-- Fast mode: ask name + user only; host/port auto-set (localhost, 5432/3306/27017)
-- Manual mode: ask name, host, port, user
-- Generate database folder at REPOSITORY ROOT (never inside service):
-  `database/<db_type>/migrations/`, `create-schema.sql`, `setup-database.sh`,
-  `setup-database.ps1`, `reset-database.sh`, `seeds/.gitkeep`, `database/README.md`
-- Check if folder already exists — skip entirely if it does
-- Generate tbl_user_deviceinfo migration for NodeJS projects
-
-### Phase 3–5 — Identity, Package Info, Runtime Config
-- Ask: service_name (unique), port (manual — skip in fast), description
-- Manual NodeJS: package_name, author, api_key, encryption_key (32 chars exact), redis config
-- Fast NodeJS: auto-generate all above (port = highest existing + 1, min 1001;
-  encryption_iv = first 16 chars of encryption_key — always derived, never random)
-
-### Phase 6 — Confirm, Then Generate ALL Files
-
-Show full summary with all values. Run validation before displaying:
-- BLOCKER: service name conflict, port conflict, key/iv wrong length, required fields missing
-- BLOCKER (ReactJS): no linked service
-
-Ask ONE question: "Confirm and generate all files? (yes / no / change a value)"
-
-**NodeJS Wave 1** (no dependencies): package.json, .env, .env.example, .gitignore, README.md,
-config/constants.js, config/template.js, logger/logging.js, utilities/encryption.js,
-languages/<lang>.js per supported_languages[], enc_dec.html (reactjs client) OR enc_dec.php (app client),
-pem/ + images/ + logger/logs/ empty dirs
-
-**NodeJS Wave 2**: config/database.js, utilities/ioRedis.js, utilities/response.js
-
-**NodeJS Wave 3**: config/common.js, utilities/validator.js, utilities/notification.js, middleware/rateLimiter.js
-
-**NodeJS Wave 4**: middleware/headerValidator.js, modules/v1/<ServiceName>/route.js,
-modules/v1/<ServiceName>/<service>_model.js, document/v1/swagger_doc.json (skeleton)
-
-**NodeJS Wave 5**: modules/v1/route_manager.js, app.js
-
-**NodeJS Wave 6** (Docker): Dockerfile, .dockerignore
-
-**ReactJS Wave 1**: package.json, .env (inherited values), .env.example, .gitignore, README.md,
-public/index.html, public/assets/css/style.css, public/robots.txt, public/favicon.ico,
-.htaccess (root), public/.htaccess
-
-**ReactJS Wave 2**: src/api/apiClient.js, src/api/apiHandler.js
-
-**ReactJS Wave 3**: src/pages/Welcome/index.jsx, src/pages/Welcome/Welcome.module.css,
-src/App.jsx, src/index.jsx, src/components/.gitkeep
-
-**ReactJS Wave 4** (Docker): Dockerfile, nginx.conf, .dockerignore
-
-Post-generation: generate .vscode/mcp.json, .cursor/mcp.json (first init only);
-generate/update docker-compose.yml + .env.docker at repo root.
-
-Call `context_write` with all service data. Call `context_clear_scratchpad` ["current_init"].
-
----
-
-## Section 4 — /codeninja:api — Add API Endpoint
-
-1. Read 1–2 existing modules for naming/auth patterns
-2. Ask: service, API version (default v1), module name, HTTP method, route path, description
-3. Ask: primary table (from context.db.schema.tables), requires auth (yes/no)
-4. Confirm: "Generate [METHOD] [path] in [service]/modules/[version]/[Module]?"
-5. Generate:
-   - `modules/<v>/<Module>/route.js` — validation + middleware + res.json() only
-   - `modules/<v>/<Module>/<module>_model.js` — parameterized DB queries, returns {responsecode, responsemsg, responsedata}
-   - Append to `route_manager.js` via `file_insert_after` — NEVER rewrite
-   - Patch `swagger_doc.json` via `file_insert_after` — add path key only
-6. Call `context_write` — append to context.api_routes, update modules
-
----
-
-## Section 5 — /codeninja:db:create — New Table
-
-1. Ask: table purpose, table name (tbl_ prefix, snake_case), migration file number
-2. Ask: needs status+is_deleted columns? needs soft delete?
-3. Column loop until "done": column name → type suggestion → enum check → FK check
-   Type suggestions: *_id→BIGINT, is_*→BOOLEAN, *_at→TIMESTAMPTZ, email→VARCHAR(132),
-   phone→VARCHAR(16), password→TEXT, *_url/*_image→VARCHAR(255), payload→JSON
-4. Index suggestions: auto-suggest for FK columns, status+is_deleted compound, created_at DESC
-5. Ask: seed data needed?
-6. Show summary — confirm — generate migration file + update create-schema.sql
-7. Call `context_write`
-
-## Section 6 — /codeninja:db:modify — Alter Table
-
-- Always generate ALTER file — never edit original setup file
-- Operations: add column, rename column, drop column, change type, add CHECK constraint, add index
-- For "add index" → route to /codeninja:db:index
-- Generated: `<n>-alter-tbl-<n>-<description>.sql` wrapped in BEGIN/COMMIT
-
-## Section 7 — /codeninja:db:index — Add Index
-
-1. Ask: table, column(s), sort order (DESC?), standard vs partial (WHERE clause)
-2. Ask: table's own file vs 111-setup-database-indexes.sql
-3. Auto-name: idx_<table_without_tbl_>_<cols> or idx_tbl_<n>_<cols>
-4. Show name — confirm — append to correct file
-
-## Section 8 — /codeninja:db:drop — Drop Table
-
-1. Ask: which table
-2. Show impact: routes referencing it, FK dependencies
-3. Require user to type table name exactly to confirm
-4. Generate `<n>-drop-tbl-<n>.sql` with `DROP TABLE IF EXISTS ... CASCADE`
-5. Keep original setup file — keep its \i entry — add drop file AFTER it in create-schema.sql
-6. Save column snapshot to change_log before removing from active tables
-
-## Section 9 — /codeninja:db:seed — Add Seed Data
-
-1. Ask: which table
-2. Determine: append to setup file (reference data) OR standalone seeds/ file (dev data)
-3. Collect row values column by column — NEVER store plaintext passwords
-4. Show INSERT preview — confirm — generate/append
-
-## Section 10 — /codeninja:db:sync — Rebuild DB Schema
-
-1. Parse all migrations in numeric order: setup → alter → drop → indexes
-2. Rebuild context.db.schema from actual file contents
-3. Rewrite create-schema.sql to match actual files on disk
-4. Report stale entries and missing files
-
----
-
-## Section 11 — /codeninja:modularize — Extract ReactJS Components
-
-**Rules:** Layout only. Never touch business logic/state/API. Never duplicate existing components.
-
-1. Ask: which ReactJS service, scope (all pages or specific page)
-2. Inventory existing src/components/ — record name, path, role, props
-3. Scan target pages — identify repeated layout blocks (header, nav, footer, sidebar, etc.)
-4. Only extract blocks that appear in 2+ pages
-5. Cross-check: if block matches existing component → reuse, else plan new component
-6. Show extraction plan (components to create, components to reuse, pages to update)
-7. Ask: "Apply? (yes / no / adjust)"
-8. Generate each new component:
-   - `src/components/<Name>/index.jsx` — props for varying values, JSDoc header
-   - `src/components/<Name>/<Name>.module.css`
-9. Update each page: add import, replace extracted JSX with component tag, clean unused imports/CSS
-10. Call `context_write` — append to context.services[<n>].components
-
----
-
-## Section 12 — /codeninja:validate-page — Add Form Validation
-
-**Rules:** ONE page per run. Never touch API calls or business logic. Skip already-validated fields.
-
-1. Ask: service, page path, validation library (Yup|RHF|Parsley|Validator.js|Custom)
-2. Scan page: find all form, input, select, textarea, submit button elements
-3. Detect existing validation — skip those fields
-4. Infer semantic type from label/name/placeholder:
-   email → "Please enter a valid email address."
-   password → "Password must be at least 8 characters."
-   confirmPassword → "Password and confirm password do not match."
-   phone → "Please enter a valid phone number."
-   generic → "This field is required."
-5. Assign missing name/id attributes (camelCase from label text)
-6. Show validation plan — confirm
-7. Apply by library (surgical edits only — never rewrite whole file):
-   - **Yup:** validationSchema + validateForm async + error spans + .errorMsg CSS
-   - **RHF:** useForm hook + register() + error spans + .errorMsg CSS
-   - **Parsley:** CDN in index.html + data-parsley-* attributes + useEffect init
-   - **Validator.js:** validateForm with validator.isEmail() etc.
-   - **Custom:** plain JS validateForm, no imports
-8. Add package to package.json if needed — display `npm install` reminder
-9. Call `context_write` — append to context.services[<n>].validated_pages
-
----
-
-## Section 13 — /codeninja:integrate-api — Wire Forms to Backend
-
-**Rules:** ONE page. Never modify layout/CSS/validation. Always route through apiHandler.js.
-
-1. Ask: service, page path, scope (all or specific form/button)
-2. Load: linked backend, context.api_routes, page content, apiHandler.js content
-3. Scan: identify all forms and action buttons, detect existing API calls
-4. Match each integration point:
-   - Existing handler → use as-is
-   - Matching route in context.api_routes → new handler to apiHandler.js
-   - No route → TODO placeholder
-5. Design state: loading + error state per form, data/item state for fetch forms
-6. Show integration plan — confirm
-7. Apply:
-   - Append new functions to apiHandler.js
-   - Surgically update page: add imports, state, handler functions, wire onSubmit/onClick
-   - Add disabled={loading} + conditional button text
-   - Add {error && <p className={styles.apiError}>{error}</p>} above submit
-   - Add {successMsg && <p className={styles.successMsg}>{successMsg}</p>} for non-nav actions
-   - Add .apiError and .successMsg to page's .module.css
-   - Add useEffect for data-fetch handlers
-8. Call `context_write` — append to context.services[<n>].integrated_pages
-
----
-
-## Section 14 — Code Intelligence Commands
-
-### /codeninja:audit — Security and Quality Review
-Checks: API key validation on all routes, parameterized queries, no hardcoded secrets,
-correct middleware order (rateLimiter→extractLanguage→validateApiKey→auth→decryptRequest),
-2-layer rule (no SQL in route.js, no res.json() in model.js), all routes in swagger and context.
-Output: 🔴 CRITICAL / 🟡 WARNING / 🟢 INFO report. Offer auto-fix for criticals.
-
-### /codeninja:debug — Diagnose and Fix Bugs
-1. Gather: error message + stack trace, endpoint, expected vs actual, recent changes
-2. Trace full request path: language → api-key → auth → validation → handler → model → DB → response
-3. Common root causes table: column not exist → check context.db.schema vs model queries,
-   401 → check middleware order, 500 → check try/catch, migration not applied → run migration
-4. Output exact root cause + before/after code fix
-
-### /codeninja:review — Code Review
-Checks: security (auth middleware, parameterized queries, no hardcoded secrets),
-architecture (2-layer, route_manager registration, swagger coverage),
-code quality (JSDoc, no console.log, async try/catch, no SELECT *),
-database (column names match context, FK indexes, LIMIT on list queries).
-Output: CRITICAL/WARNING/SUGGESTION with file path, before/after code, reason.
-
-### /codeninja:optimize — Performance Analysis
-Checks: missing indexes (compare WHERE/ORDER BY columns vs context.db.schema indexes),
-SELECT * → explicit columns, N+1 query patterns, RANK vs DENSE_RANK,
-functional index traps (DATE(col) → use range form), heavy middleware on lightweight routes,
-Redis caching opportunities. Output: HIGH/MED/LOW ranked list with exact SQL/code fixes.
-
-### /codeninja:refactor — Rename / Restructure
-Types: rename DB column (ALTER migration + update model queries),
-rename service (update context.services key), rename table (ALTER migration + update models),
-rename module (rename files + update route_manager). All recorded in context.change_log.
-
-### /codeninja:test — Generate Jest Tests
-Reads route.js + _model.js + context.api_routes.
-Generates `tests/v1/<Module>.test.js` covering:
-200 happy path, 400 validation failures, 401 invalid api-key,
-401 invalid auth token, 404 not found, 500 simulated DB error.
-
-### /codeninja:design — Plan Before Coding
-Produces `.codeninja/agent/designs/<feature>.design.md` with:
-DB schema proposal (tables, columns, indexes), API contracts (method, path, request, response),
-open questions. Optionally stores planned routes/schema in context.
-
-### /codeninja:explain — Explain Any File or Concept
-Always reads the actual file before explaining.
-Structure: What it is → How it works → Why this way → Where it connects.
-References real file names, table names, service names from context.
-
-### /codeninja:sync — Rebuild Context from Repo
-Mode A (context exists): scan for drift, merge new findings, report conflicts.
-Mode B (no context): build context.json entirely from what exists on disk.
-Always writes context.json at end — never skips. Report: services added, routes found, gaps filled.
-
----
-
-## Section 15 — NodeJS Architecture Standards
-
-### 2-Layer Rule (absolute)
-- `route.js` — HTTP only: validation, middleware, `res.json()`
-- `<module>_model.js` — DB only: parameterized queries, business logic, no `res.json()`
-
-### Model Return Shape (always exactly this — no extra keys)
-```javascript
-return { responsecode: 1, responsemsg: 'success_key', responsedata: data };
-```
-
-### Middleware Order in route_manager.js (enforced)
-```
-rateLimiter → extractLanguage → validateApiKey → [auth if protected] → decryptRequest → routeHandler
-```
-
-### Encryption Library Selection
-- `client_type == "reactjs"` → `crypto-js` → generate `enc_dec.html`
-- `client_type == "app"` → `cryptlib` → generate `enc_dec.php`
-- Both use AES-256-CBC with KEY (32 chars) and IV (16 chars) from .env
-
-### JSDoc on every exported function (no exceptions)
-```javascript
-/**
- * One-sentence description. Active voice.
- *
- * @param {type} paramName - Description.
- * @returns {Promise<Object>} Description.
- */
-```
-
-### DB Driver Selection
-- postgresql → `pg`
-- mysql → `mysql2`
-- mongodb → `mongoose`
-
----
-
-## Section 16 — ReactJS Architecture Standards
-
-### apiClient.js Must-Haves
-1. Static headers: api-key, Accept-Language, Content-Type: text/plain
-2. Request interceptor: encrypt body + attach encrypted token from localStorage
-3. Response interceptor success: decrypt + parse + code -1 → logout redirect
-4. Response interceptor error: ERR_NETWORK/401 → logout redirect + error
-
-### apiHandler.js Standard
-- One async function per backend endpoint — no try/catch, no decryption
-- All API endpoint paths live here — never in page components
-
-### Vanilla CSS Only
-- Per-page: `<PageName>.module.css`
-- Global: `public/assets/css/style.css`
-- No Tailwind, no CSS-in-JS
-
-### .env Standard
-```
-REACT_APP_BASE_URL=http://localhost:<linked_port>/api/v1/
-REACT_APP_API_KEY=<inherited>
-REACT_APP_KEY=<inherited>
-REACT_APP_IV=<inherited>
+| `context_check_stale` | Detect unresolved ops | Step 0 of activation |
+| `service_scan` | Discover services on disk | Step 2 of activation |
+| `migration_next_number` | Next sequential migration # | Before any migration file |
+| `file_insert_after` | Surgical insert | route_manager, swagger — never rewrite |
+| `file_contains` | Check for string | Before appending |
+| `lint_file` | Lint generated JS/TS | After generation |
+
+## MCP Server Setup
+Add to your VS Code MCP settings:
+```json
+{
+  "mcpServers": {
+    "codeninja": {
+      "command": "node",
+      "args": ["${workspaceFolder}/.codeninja/mcp-server.js"]
+    }
+  }
+}
 ```

package/ide/vscode/.vscode/instructions/code-intelligence.instructions.md

@@ -0,0 +1,58 @@
+---
+applyTo: "**/*"
+---
+
+# codeninja — Code Intelligence Standards (v4.0)
+
+## /codeninja:audit Checklist
+
+### Security
+- [ ] Passwords HASHED using `utilities/hashing.js` (bcrypt/argon2)? Not AES-encrypted?
+- [ ] No direct bcrypt/argon2 imports in route/model files?
+- [ ] Parameterized queries only — no string concatenation in SQL?
+- [ ] API key validation on all routes?
+- [ ] No hardcoded secrets in source?
+- [ ] Middleware order: rateLimiter→extractLanguage→validateApiKey→[auth]→decryptRequest?
+
+### Architecture
+- [ ] 2-layer rule enforced (no SQL in route, no res.json in model)?
+- [ ] route_manager.js never fully rewritten (append-only via file_insert_after)?
+- [ ] All routes in swagger_doc.json and context.api_routes?
+
+### v4.0 Checks
+- [ ] orm="prisma": no `new PrismaClient()` in model files?
+- [ ] language="typescript": all .ts files use import/export syntax?
+
+## /codeninja:debug Trace Path
+1. extractLanguage — Accept-Language header processed?
+2. validateApiKey — api-key header matches .env API_KEY?
+3. validateAuthToken (protected only) — JWT valid and not expired?
+4. rateLimiter — request not throttled?
+5. validatorjs rules — all required fields in request body?
+6. Model call — DB connection alive?
+7. Query — column names match context.db.schema?
+8. sendResponse — encrypted_transport handled?
+
+**401:** middleware order or key mismatch | **400:** validation rules | **500:** DB/column issue
+
+## /codeninja:review Dimensions
+- Security: auth middleware, parameterized queries, no hardcoded secrets, hashing not encryption
+- Architecture: 2-layer rule, route_manager append-only, swagger/context coverage
+- Code quality: JSDoc on all functions, no console.log, async try/catch
+- Database: column names match context, FK indexes, LIMIT on list queries
+
+## /codeninja:optimize Patterns (ranked)
+1. Missing index → `CREATE INDEX CONCURRENTLY` (no table lock)
+2. `SELECT *` → explicit column list
+3. N+1 query → JOIN or IN clause
+4. `DATE(col)` in WHERE → range filter to use index
+5. `RANK()` with gaps → `DENSE_RANK()` for leaderboards
+6. Unbounded list query → add `LIMIT` and `OFFSET`
+7. Repeated identical queries → Redis cache opportunity
+8. `work_mem` for sort-heavy queries
+
+## /codeninja:refactor Types
+- Rename DB column: ALTER migration + update model queries + context.change_log
+- Rename service: update context.services key + context.change_log
+- Rename table: ALTER migration + update all model references + context.change_log
+- Rename module: rename files + update route_manager + context.change_log

package/ide/vscode/.vscode/instructions/database.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: "**/*.sql,**/database/**,**/prisma/**"
+---
+
+# codeninja — Database Standards (v4.0)
+
+## Naming Conventions
+| 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 | `<ref_table_singular_no_tbl>_id` | `user_id` refs `tbl_users` |
+| Index (per-table) | `idx_<table_no_tbl>_<cols>` | `idx_users_email` |
+| Shared indexes | `111-setup-database-indexes.sql` | always last file |
+
+## Column Types
+| Use Case | PostgreSQL Type |
+|---|---|
+| PK | `bigint NOT NULL GENERATED ALWAYS AS IDENTITY (INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1)` |
+| FK | `BIGINT NOT NULL DEFAULT 0` |
+| Email | `VARCHAR(132) NOT NULL DEFAULT ''` |
+| Password/token | `TEXT NOT NULL DEFAULT ''` |
+| Status | `INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0, 1))` |
+| Soft delete | `BOOLEAN NOT NULL DEFAULT FALSE` |
+| Timestamp | `TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` |
+| Financial | `NUMERIC(18,8) NOT NULL DEFAULT 0.00000000` |
+| JSON | `JSON NOT NULL DEFAULT '{}'` |
+
+NEVER use PostgreSQL ENUM — always `VARCHAR + CHECK constraint + COMMENT ON COLUMN`.
+
+## SQL File Content Order (strict)
+1. `-- Creating tbl_name for purpose`
+2. `DROP TABLE IF EXISTS public.tbl_name CASCADE;`
+3. `CREATE TABLE` block (id first, timestamps last)
+4. `COMMENT ON COLUMN` for every enum/flag/status column
+5. Per-table `CREATE INDEX` statements
+6. `ALTER TABLE ... OWNER TO <db_user>`
+7. `GRANT ALL ON TABLE ... TO <db_user>`
+8. Seed `INSERT` (reference/master tables only)
+
+## Index Strategy
+Always index: every FK column; (status + is_deleted) compound; created_at DESC on log tables; email + is_deleted on user tables. Most selective column first in compound indexes.
+
+## create-schema.sql Maintenance
+After every table operation: re-read the file → add/remove/reorder `\i` entries → write back.
+ALTER files go immediately after their CREATE file. 111-indexes always last.
+
+## Prisma Conventions (v4.0)
+- `tbl_users` → `model Users` (strip tbl_, PascalCase) + `@@map("tbl_users")`
+- `id` BIGINT IDENTITY → `id BigInt @id @default(autoincrement())`
+- `created_at` → `createdAt DateTime @default(now()) @map("created_at")`
+- `is_deleted` → `isDeleted Boolean @default(false) @map("is_deleted")`
+- FK `user_id` → `userId BigInt @map("user_id")` + relation field
+- After any model addition → `npx prisma generate`

package/ide/vscode/.vscode/instructions/nodejs.instructions.md

@@ -0,0 +1,77 @@
+---
+applyTo: "**/*.js,**/*.ts"
+---
+
+# codeninja — NodeJS Standards (v4.0)
+
+## The 2-Layer Rule (absolute)
+- `route.js/ts` — HTTP only: validation, middleware, `res.json()` via sendResponse
+- `<module>_model.js/ts` — DB only: queries, business logic, never `res.json()`
+
+## Middleware Order (never change)
+```
+rateLimiter → extractLanguage → validateApiKey → [auth if protected] → decryptRequest → routeHandler
+```
+
+## Response Contract
+```javascript
+sendResponse(req, res, 1, 'success_key', data)    // success
+sendResponse(req, res, 0, 'error_key', [])          // error
+sendResponse(req, res, -1, 'session_expired', [])   // auth expired → frontend logout
+```
+
+## Password Hashing (v4.0 — CRITICAL)
+- NEVER use `encryption.js` for passwords — reversible AES is a security vulnerability
+- ALWAYS use `utilities/hashing.js`: `hashPassword(plain)` to store, `verifyPassword(plain, hash)` to check
+- Import: `const { hashPassword, verifyPassword } = require('../../utilities/hashing')`
+- TypeScript: `import { hashPassword, verifyPassword } from '../../utilities/hashing'`
+
+## ORM Branch (v4.0)
+Read `context.db.orm` before generating any model:
+- orm="none": parameterized SQL with `$1`, `$2` placeholders via pg/mysql2/mongoose
+- orm="prisma": `prisma.tableName.operation()` — import singleton from `config/prisma`, never `new PrismaClient()`
+- Prisma table access: `tbl_users` → `prisma.users` (lowercase, strip `tbl_` prefix)
+
+## TypeScript Support (v4.0)
+Read `context.services[name].language`:
+- "javascript": `.js` files, `require()`/`module.exports`, no tsconfig
+- "typescript": `.ts` files, `import`/`export`, typed params, `tsconfig.json` in Wave 1
+
+TypeScript patterns:
+```typescript
+// route.ts
+import { Router, Request, Response } from 'express';
+router.post('/path', async (req: Request, res: Response) => { ... });
+export default router;
+
+// _model.ts
+export async function functionName(request: RequestType, user_id: number, user_type: string): Promise<object> { ... }
+```
+
+## Localizify Rules
+- ONLY `headerValidator.js/ts` and `response.js/ts` may call `t()` directly
+- All other files use `sendResponse()`, `getMessage()`, or `req.t("key")`
+
+## Code Style
+- JSDoc on every exported function (no exceptions)
+- No inline `//` comments inside function bodies
+- Route comment: `// POST /path — description` above each route handler
+- No file-level header comments
+
+## .env Keys (NodeJS service)
+```
+PORT=, API_KEY=, KEY=, IV=, ENCRYPTED_TRANSPORT=, SUPPORTED_LANGUAGES=,
+DB_HOST=, DB_PORT=, DB_NAME=, DB_USER=, DB_PASSWORD=,
+REDIS_HOST=, REDIS_PORT=,
+DATABASE_URL= (Prisma only — replaces individual DB_* vars)
+```
+
+## Wave Generation Order
+Before generating any file, read `.codeninja/tasks/generate-<name>.task.md`.
+
+Wave 1: package.json, .env, .gitignore, README.md, config/constants, config/template, logger/logging, utilities/encryption, **utilities/hashing** (v4.0), languages/*, **tsconfig.json** (TS only, v4.0)
+Wave 2: config/database OR config/prisma (v4.0 ORM branch), utilities/ioRedis, utilities/response
+Wave 3: config/common, utilities/validator, utilities/notification, middleware/rateLimiter
+Wave 4: middleware/headerValidator, modules/v1/<Name>/route, modules/v1/<Name>/_model, swagger_doc.json
+Wave 5: modules/v1/route_manager, app.js/ts
+Wave 6: Dockerfile, .dockerignore