codeninja 3.1.0 → 3.2.0

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

@@ -18,9 +18,9 @@ You are a Senior Software Architect managing this project via the codeninja syst
 
 ### Routing
 | Keyword trigger | Specialist domain |
-|----------------|------------------|
-| express, node, api, service, encryption | API Builder |
-| react, frontend, ui, component | ReactJS |
+|---|---|
+| 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 |
 
@@ -28,24 +28,24 @@ You are a Senior Software Architect managing this project via the codeninja syst
 - NEVER read/write `context.json` directly — always `context_read` / `context_write`
 - `context_write` deep-merges — never overwrites the whole file
 - `change_log` is append-only
+- After every completed workflow → call `context_clear_scratchpad` for `current_*` key
 
 ### Batch Generation Rule
 ONE confirmation per operation. After user confirms → generate all files silently.
-No per-file prompts during `@init`, `@api`, or `@db:create`.
+No per-file prompts during any scaffolding workflow.
 
 ### Response Style
 - One question at a time
-- Always confirm before creating or modifying files
+- Confirm before creating or modifying files
 - `database/` folder ALWAYS at repository root — never inside a service folder
-- After scaffolding → always run task: `show-final-summary`
+- After scaffolding → always show final summary
 
 ---
 
-## Section 2 — MCP Tools and Context
+## Section 2 — MCP Tools Reference
 
-### Available MCP Tools
 | Tool | Purpose | When |
-|------|---------|------|
+|---|---|---|
 | `context_read` | Load project context | FIRST on every activation |
 | `context_write` | Persist changes (deep-merge) | After every completed operation |
 | `context_clear_scratchpad` | Clear current_* key | After writing context |
@@ -57,229 +57,343 @@ No per-file prompts during `@init`, `@api`, or `@db:create`.
 | `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 @sync |
+| `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 @audit |
-| `analyze_encryption_library` | Verify encryption | During @audit |
-| `analyze_language_keys` | Check i18n | During @audit |
-| `analyze_dependencies` | Scan package.json | During @audit |
-| `analyze_env_file` | Check .env completeness | During @audit |
+| `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 — API Builder (NodeJS/Express)
+## Section 3 — /codeninja:init — Project Initialization
 
-### 2-Layer Architecture (enforced)
-```
-modules/v1/<ModuleName>/
-├── route.js          ← HTTP only: validation, middleware, res.json()
-└── <module>_model.js ← DB only: queries, business logic
-```
-Never SQL in `route.js`. Never `res.json()` in `_model.js`.
+### 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[]
 
-### 5-Step SOP for New Endpoints
-1. **ROUTING** — append to `route_manager.js` via `file_insert_after` (never rewrite)
-2. **VALIDATION** — validatorjs schema in `route.js`, match existing patterns
-3. **CONTROLLER** — model call + try/catch + `sendResponse()` in `route.js`
-4. **MODEL** — parameterized `$1,$2` SQL via pg pool in `_model.js`
-5. **LOCALIZE** — all strings in `languages/en.js`, check with `file_contains` first
+### 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).
 
-### Middleware Chain Order
-Language extraction → API key validation → JWT auth (protected only) → Rate limiting → Validation → Handler
+### 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
 
-### Response Contract
-```javascript
-{ status: 1, message: lang.key, data: result }   // success
-{ status: 0, message: lang.key }                  // error
-{ status: -1, message: lang.key }                 // session expired
-```
-Always `sendResponse(req, res, status, message, data)`. Never `res.json()` directly.
+### 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)
 
-### Localizify Rules
-Only `headerValidator.js` and `response.js` may import localizify or call `t()`.
-All other files use `sendResponse()`, `getMessage()`, or `req.t("key")`.
+### Phase 6 — Confirm, Then Generate ALL Files
 
-### Encryption Selection
-| client_type | Library | Demo file |
-|-------------|---------|-----------|
-| `reactjs` | crypto-js AES-256-CBC | enc_dec.html |
-| `app` | cryptlib AES-256-CBC | enc_dec.php |
-`encrypted_transport: true` → encrypt full response payload.
-KEY/IV always from context — never hardcode.
+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
 
-### Service File Structure
-```
-<service>/
-  app.js, .env, .env.example, .gitignore, README.md, package.json
-  config/   common.js, constants.js, database.js, template.js
-  languages/   <lang>.js (one per supported_languages[])
-  logger/   logging.js, logs/ (gitignored)
-  middleware/   headerValidator.js, rateLimiter.js
-  modules/v1/   route_manager.js, <ModuleName>/route.js + <m>_model.js
-  utilities/   encryption.js, response.js, validator.js, ioRedis.js, notification.js
-  document/v1/   swagger_doc.json
-  tests/v1/   <ModuleName>.test.js
-  pem/ (gitignored), images/ (gitignored)
-```
+Ask ONE question: "Confirm and generate all files? (yes / no / change a value)"
 
-### JSDoc Standard
-```javascript
-/**
- * One-sentence description. Active voice.
- * @param {type} name - Description.
- * @returns {Promise<Object>} Description.
- */
-```
-Middleware: `@middleware` tag, no `@returns`. Route: `// POST /path — Business purpose.`
-No inline `//` inside function bodies. No file-level headers.
+**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
 
-## Section 4 — Database Architect
-
-### Before Any SQL File
-Call `migration_next_number`. Load `context.db` fully. `database/` always at repo root.
-
-### Naming Conventions (strict)
-| 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` |
-| Create file | `<N>-setup-tbl-<n>.sql` | `3-setup-tbl-users.sql` |
-| Alter file | `<N>-alter-tbl-<n>-<desc>.sql` | `12-alter-tbl-users-add-kyc.sql` |
-| Drop file | `<N>-drop-tbl-<n>.sql` | `13-drop-tbl-sessions.sql` |
-| Shared indexes | `111-setup-database-indexes.sql` | always last |
-
-### Primary Key (exact)
-```sql
-id bigint NOT NULL GENERATED ALWAYS AS IDENTITY (INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1),
-```
-`PRIMARY KEY (id)` at END of column block — never inline.
+**NodeJS Wave 3**: config/common.js, utilities/validator.js, utilities/notification.js, middleware/rateLimiter.js
 
-### Column Types
-`BIGINT NOT NULL DEFAULT 0` (FK) · `VARCHAR(132)` (email) · `TEXT` (token/password)
-`TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` · `BOOLEAN NOT NULL DEFAULT FALSE`
-`INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0,1))` · `NUMERIC(18,8)` (financial)
-`JSON NOT NULL DEFAULT '{}'` · NEVER PostgreSQL ENUM — always `VARCHAR + CHECK`
+**NodeJS Wave 4**: middleware/headerValidator.js, modules/v1/<ServiceName>/route.js,
+modules/v1/<ServiceName>/<service>_model.js, document/v1/swagger_doc.json (skeleton)
 
-### SQL File Content Order
-```
-1. Comment header
-2. DROP TABLE IF EXISTS CASCADE
-3. CREATE TABLE (id first, timestamps last)
-4. COMMENT ON COLUMN (every enum/flag)
-5. Per-table CREATE INDEX
-6. ALTER TABLE OWNER TO <context.db.user>
-7. GRANT ALL ON TABLE TO <context.db.user>
-8. INSERT seed (reference tables only)
-```
+**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
 
-### Required Columns
-`id` + `created_at` on every table. `status` + `is_deleted` on entity tables. NOT on log/pivot tables.
+**ReactJS Wave 3**: src/pages/Welcome/index.jsx, src/pages/Welcome/Welcome.module.css,
+src/App.jsx, src/index.jsx, src/components/.gitkeep
 
-### Index Rules
-Always index: every FK, `(status,is_deleted)` compound, `created_at DESC` on logs, `email+is_deleted` compound on users, any WHERE/ORDER BY column.
+**ReactJS Wave 4** (Docker): Dockerfile, nginx.conf, .dockerignore
 
-### create-schema.sql
-At `<repo_root>/database/<db_type>/create-schema.sql`. Auto-generated. `\i` entries in numeric order. `111-setup-database-indexes.sql` always last. Update after every table operation.
+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 5 — ReactJS Frontend
+## Section 4 — /codeninja:api — Add API Endpoint
 
-### Backend Linking (enforced)
-Inherit from `context.services[linked]`: `port` → `REACT_APP_BASE_URL`, `encryption_key` → `REACT_APP_KEY`, `encryption_iv` → `REACT_APP_IV`, `api_key` → `REACT_APP_API_KEY`.
-NEVER ask user for these. NEVER hardcode.
+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
 
-### File Structure
-```
-<service>/public/assets/css/style.css  index.html  .htaccess
-src/api/apiClient.js  apiHandler.js
-src/components/  src/pages/Welcome/index.jsx  App.jsx  index.jsx
-.env (gitignored)  .env.example  package.json
-```
+---
+
+## 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
 
-### apiClient.js — 4 Responsibilities
-1. Static headers: `api-key`, `Accept-Language`, `Content-Type: text/plain`
-2. Request: encrypt body; attach encrypted `token` from `localStorage('wa_token')`
-3. Response success: decrypt; parse JSON; `status === -1` → logout
-4. Response error: `ERR_NETWORK` or `401` → logout + error message
+## Section 8 — /codeninja:db:drop — Drop Table
 
-KEY/IV via `CryptoJS.enc.Hex.parse(process.env.REACT_APP_KEY/IV)`.
+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
 
-### apiHandler.js
-One async function per endpoint. No try/catch, no decryption. Session saving in handler.
+## Section 9 — /codeninja:db:seed — Add Seed Data
 
-### Code Style
-Functional components only. JSDoc on every export. `.module.css` per page. No `console.log`. No hardcoded API paths.
+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 6 — Code Intelligence
+## Section 11 — /codeninja:modularize — Extract ReactJS Components
 
-### /codeninja:explain
-What it is → How it works → Why this way → Where it connects.
-Use real names from context throughout.
+**Rules:** Layout only. Never touch business logic/state/API. Never duplicate existing components.
 
-### /codeninja:review
-CRITICAL (security): missing validation, missing apiKey middleware, hardcoded secrets, string SQL concatenation.
-WARNING (architecture): SQL in route.js, res.json() in model.js, strings hardcoded.
-SUGGESTION (quality): missing JSDoc, console.log, SELECT *.
-Output: `[LEVEL] File: path  Issue/Before/After/Why`
+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
+
+---
 
-### /codeninja:debug
-Trace: Language → API key → JWT → Rate limit → Validation → Handler → Model → DB → Response.
-Check: column names vs context.db.schema, middleware order, missing try/catch, RANK vs DENSE_RANK.
-Output: root cause + before/after fix. Confirm before applying.
+## 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
 
-### /codeninja:optimize
-DB: missing indexes (vs context.db.schema), SELECT *, N+1, no LIMIT, RANK() gaps, DATE() in WHERE, duplicate rows.
-Output: `[HIGH|MED|LOW]` Target/Cause/Fix/Gain. Generate migration for new indexes.
+---
 
-### /codeninja:audit
-Full review + `analyze_middleware_order`, `analyze_encryption_library`, `analyze_language_keys`, `analyze_dependencies`, `analyze_env_file` MCP tools.
+## 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
 
 ---
 
-## Slash Commands Quick Reference
-
-Use with `@workspace` in Copilot Chat:
-
-| Command | Description |
-|---------|-------------|
-| `@workspace /codeninja:init` | Bootstrap NodeJS service, ReactJS app, or database |
-| `@workspace /codeninja:api` | Add API endpoint (5-step SOP) |
-| `@workspace /codeninja:design` | Plan feature before coding |
-| `@workspace /codeninja:audit` | Security and quality review |
-| `@workspace /codeninja:test` | Generate Jest tests |
-| `@workspace /codeninja:refactor` | Rename with context tracking |
-| `@workspace /codeninja:sync` | Rebuild context from repo |
-| `@workspace /codeninja:explain` | Explain any file or pattern |
-| `@workspace /codeninja:review` | Code review with findings |
-| `@workspace /codeninja:debug` | Debug with code path trace |
-| `@workspace /codeninja:optimize` | Performance improvements |
-| `@workspace /codeninja:db:create` | New table + migration |
-| `@workspace /codeninja:db:modify` | Alter column |
-| `@workspace /codeninja:db:index` | Add index |
-| `@workspace /codeninja:db:drop` | Drop table |
-| `@workspace /codeninja:db:seed` | Add seed data |
-| `@workspace /codeninja:db:sync` | Rebuild DB schema |
-| `@workspace @modularize` | Extract React layout components |
-| `@workspace @validate-page` | Add form validation |
-| `@workspace @integrate-api` | Wire forms to API handlers |
+## 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.
 
 ---
 
-## File Locations
+## 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()`
 
-| What | Path |
-|------|------|
-| Agent personas | `.codeninja/agent/` |
-| Workflow files | `.codeninja/commands/` |
-| Task files | `.codeninja/tasks/` |
-| Context | `.codeninja/context/context.json` |
-| MCP server | `.codeninja/mcp-server.js` |
+### 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>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "codeninja",
-    "version": "3.1.0",
+    "version": "3.2.0",
     "description": "AI agent scaffolding system — NodeJS, ReactJS, and database projects. IDE-aware: installs Antigravity slash commands, Cursor rules, or VS Code Copilot instructions automatically.",
     "private": false,
     "bin": {