codeninja 3.1.0 → 4.0.0

package/ide/cursor/.cursor/rules/02-mcp-and-context.mdc

@@ -1,38 +1,54 @@
 ---
-description: codeninja MCP tools and context management — always applied
+description: codeninja MCP tools and context.json schema (v4.0). Always applied.
 globs: ["**/*"]
 alwaysApply: true
 ---
 
-# codeninja — MCP and Context
+# codeninja — MCP Tools and Context (v4.0)
 
-## MCP Tools Reference
-| Tool | Use |
-|------|-----|
-| `context_read` | Load project context — FIRST on every activation |
-| `context_write` | Persist changes — deep-merge, never overwrite |
-| `context_clear_scratchpad` | Clear current_* key after operation |
-| `context_check_stale` | Detect unresolved operations — Step 0 |
-| `service_scan` | Discover services on disk |
-| `migration_next_number` | Before any migration file creation |
-| `fs_read` | Read file before modifying |
-| `fs_list` | List directory contents |
-| `fs_exists` | Check existence before conditional ops |
-| `file_insert_after` | Surgical append (route_manager, swagger) |
-| `file_contains` | Check before appending to avoid duplicates |
-| `run_drift_check` | Context vs disk comparison during @sync |
-| `lint_file` | Lint after generating JS/SQL |
-| `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 |
-| `validate_redis_connection` | Test Redis during init |
-| `validate_postgres_connection` | Test DB during init |
+## MCP Tools Quick Reference
+| Tool | Purpose | When |
+|---|---|---|
+| `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 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 |
+| `fs_read` | Read file from disk | Before modifying any file |
+| `fs_list` | List directory | When scanning structure |
+| `fs_exists` | Check file existence | Before conditional ops |
+| `file_insert_after` | Surgical insert | route_manager, swagger — never rewrite |
+| `file_contains` | Check for string | Before appending |
+| `run_drift_check` | Context vs disk | During /codeninja:sync |
+| `lint_file` | Lint generated JS/TS | After JS/TS generation |
+| `analyze_middleware_order` | Check middleware chain | During audit |
+| `analyze_encryption_library` | Verify encryption | During audit |
+| `analyze_language_keys` | Check i18n keys | During audit |
 
-## Absolute Rules
-- NEVER read context.json with fs_read — always `context_read`
-- NEVER write context.json directly — always `context_write`
-- `change_log` is append-only — never delete entries
-- Always call `context_check_stale` before starting any workflow
-- Always call `context_clear_scratchpad` after completing a workflow
+## Context Schema (v4.0)
+```json
+{
+  "db": {
+    "type": "postgres|mysql|mongodb",
+    "orm": "none|prisma"
+  },
+  "services": {
+    "<name>": {
+      "type": "nodejs|reactjs",
+      "language": "javascript|typescript",
+      "hashing_library": "bcryptjs|argon2",
+      "port": 0,
+      "encryption_key": "", "encryption_iv": "", "api_key": ""
+    }
+  }
+}
+```
+
+**v4.0 new fields:** `db.orm`, `services[name].language`, `services[name].hashing_library`
+
+## Stale Scratchpad Recovery
+If `context_check_stale` returns stale keys:
+1. Surface to user: "Unfinished [operation] detected"
+2. Ask: continue or discard?
+3. If discard: call `context_clear_scratchpad`, then proceed

package/ide/cursor/.cursor/rules/03-api-builder.mdc

@@ -1,74 +1,46 @@
 ---
-description: codeninja API builder standards — loaded for NodeJS service files
-globs: ["**/modules/**", "**/middleware/**", "**/utilities/**", "**/route_manager*", "**/app.js", "**/languages/**"]
+description: NodeJS API architecture standards — 2-layer rule, SOP, middleware order. Applied to JS/TS files.
+globs: ["**/*.js", "**/*.ts"]
 alwaysApply: false
 ---
 
-# codeninja — API Builder
+# codeninja — API Builder Standards (v4.0)
 
-## 2-Layer Architecture (enforced)
+## The 2-Layer Rule (absolute — no exceptions)
+- `route.js/ts` — HTTP only: validation, middleware, `res.json()` via sendResponse
+- `<module>_model.js/ts` — DB only: queries, business logic, no `res.json()`
 
-```
-modules/v1/<ModuleName>/
-├── route.js          ← HTTP only: validation, middleware, res.json()
-└── <module>_model.js ← DB only: parameterized queries, business logic
-```
-
-Never SQL in `route.js`. Never `res.json()` in `_model.js`.
+## 5-Step SOP for Every New Endpoint
+1. **ROUTING** — append to `route_manager.js/ts` via `file_insert_after` (never rewrite)
+2. **VALIDATION** — validatorjs schema in `route.js/ts`
+3. **CONTROLLER** — model call + try/catch in `route.js/ts`; call `sendResponse`
+4. **MODEL** — parameterized query or Prisma call in `<module>_model.js/ts`
+5. **LOCALIZE** — all strings in `languages/en.js/ts`; use `file_contains` before adding
 
-## 5-Step SOP — Every New Endpoint
-
-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`, use `file_contains` before adding
-
-## Middleware Chain Order (never change)
+## Middleware Order (enforced — never change)
 ```
-Language extraction → API key validation → JWT auth (protected only) → Rate limiting → Validation → Handler
+rateLimiter → extractLanguage → validateApiKey → [auth if protected] → decryptRequest → routeHandler
 ```
 
 ## Response Contract
 ```javascript
-{ status: 1, message: lang.key, data: result }   // success
-{ status: 0, message: lang.key }                  // error
-{ status: -1, message: lang.key }                 // session expired → triggers frontend logout
-```
-Always use `sendResponse(req, res, status, message, data)` from `utilities/response.js`.
-Never call `res.json()` directly.
-
-## Localizify Rules
-Only `headerValidator.js` and `response.js` may call `t()` or import localizify.
-All other files use `sendResponse()`, `getMessage()`, or `req.t("key")`.
-Never call `setLocale` from model files — race condition under concurrent requests.
-
-## Swagger Maintenance
-Patch `swagger_doc.json` only — never rewrite it.
-Add new path key only via `file_insert_after`. Update `info.version` timestamp.
-
-## JSDoc Standard (every exported function — no exceptions)
-```javascript
-/**
- * One-sentence description. Active voice.
- * @param {type} name - Description.
- * @returns {Promise<Object>} Description.
- */
+// Success
+sendResponse(req, res, 1, 'success_key', resultData)
+// Error
+sendResponse(req, res, 0, 'error_key', [])
+// Session expired (triggers frontend logout)
+sendResponse(req, res, -1, 'session_expired', [])
 ```
-Middleware: `@middleware` tag, no `@returns`.
-Route comment: `// POST /path — Business purpose.` above route definition.
-No inline `//` inside function bodies. No file-level headers.
 
-## Encryption Selection
-| context.services[n].client_type | Library | Demo file |
-|---------------------------------|---------|-----------|
-| reactjs | crypto-js AES-256-CBC | enc_dec.html |
-| app | cryptlib AES-256-CBC | enc_dec.php |
+## Password Handling (v4.0)
+- NEVER use `encryption.js` for passwords — AES is reversible, not safe for storage
+- ALWAYS use `utilities/hashing.js`: `hashPassword(plain)` / `verifyPassword(plain, hash)`
 
-`encrypted_transport: true` → encrypt full response payload.
-`encrypted_transport: false` → plain JSON, no transport encryption.
-KEY and IV always from context — never hardcode.
+## ORM Rule (v4.0)
+- Read `context.db.orm` before generating model files
+- orm="none": parameterized SQL (`$1`, `$2` placeholders)
+- orm="prisma": `prisma.users.create({...})` — import singleton from `config/prisma`, never `new PrismaClient()`
 
-## Test Standards (Jest + Supertest)
-File: `tests/v1/<ModuleName>.test.js`
-Cover: happy path, each validation failure, auth failure, edge cases.
+## Localizify Rules
+- ONLY `headerValidator.js/ts` and `response.js/ts` may import localizify or call `t()`
+- All other files use `sendResponse()`, `getMessage()`, or `req.t("key")`

package/ide/cursor/.cursor/rules/04-nodejs-generation.mdc

@@ -0,0 +1,58 @@
+---
+description: NodeJS file generation standards — exact content for each generated file. Applied when editing service internals.
+globs: ["**/modules/**", "**/middleware/**", "**/utilities/**", "**/config/**"]
+alwaysApply: false
+---
+
+# codeninja — NodeJS File Generation Standards (v4.0)
+
+Read `.codeninja/tasks/generate-<name>.task.md` before generating each file.
+
+## Language Branch (FIRST step before generating ANY file)
+Read `context.services[name].language` (or `context.current_init.language`).
+- "javascript" → `.js` files, `require()`/`module.exports`
+- "typescript" → `.ts` files, `import`/`export`, typed parameters
+
+## utilities/hashing.js/ts
+- bcryptjs or argon2 — read `context.services[name].hashing_library`
+- Exports: `hashPassword(plain)` → `Promise<string>`, `verifyPassword(plain, hash)` → `Promise<boolean>`
+- NEVER imports from encryption.js; NEVER uses AES/KEY/IV
+
+## utilities/encryption.js/ts
+- AES-256-CBC transport encryption ONLY — never passwords
+- Exports: `encrypt(data)` → string, `decrypt(ciphertext)` → original value
+- Library: `crypto-js` (client_type=reactjs) or `cryptlib` (client_type=app)
+
+## config/database.js/ts (orm="none" only)
+- PostgreSQL: `pg.Pool` with env vars DB_HOST/PORT/NAME/USER/PASS
+- MySQL: `mysql2/promise` pool
+- MongoDB: `mongoose.connect()`
+
+## config/prisma.js/ts (orm="prisma" only)
+- Single `new PrismaClient()` instance exported as singleton
+- `log: ['query','error','warn']` in development only
+
+## middleware/headerValidator.js/ts
+- Exports: `extractLanguage`, `validateApiKey`, `validateAuthToken`, `decryptRequest`
+- Only file permitted to call localizify `t()` directly (along with response.js)
+- TypeScript: all middleware typed as `(req: Request, res: Response, next: NextFunction) => void`
+
+## utilities/response.js/ts
+- Exports: `sendResponse(req, res, code, messageKey, data)`
+- Checks `encrypted_transport` flag — encrypts payload if true
+- Only other file permitted to call localizify `t()` directly
+
+## modules/v1/<Module>/route.js/ts
+- Imports: Router, Validator, sendResponse, model functions
+- One route handler per endpoint — single try/catch wrapping model call
+- Route comment above each handler: `// POST /path — description`
+- TypeScript: `async (req: Request, res: Response) => {}`
+
+## modules/v1/<Module>/<module>_model.js/ts
+- Imports: db pool (orm=none) or prisma singleton (orm=prisma), hashing utilities
+- Returns exactly: `{ responsecode: 1|0|-1, responsemsg: 'key', responsedata: data }`
+- No `res.json()`, no Express imports
+
+## app.js/ts
+- Middleware chain: cors → helmet → express.json → express.urlencoded → /api/v1 router
+- TypeScript: `const app: Application = express()`

package/ide/cursor/.cursor/rules/05-database.mdc

@@ -0,0 +1,54 @@
+---
+description: Database standards — naming, SQL content order, index rules, Prisma conventions.
+globs: ["**/*.sql", "**/database/**", "**/prisma/**"]
+alwaysApply: false
+---
+
+# codeninja — Database Standards (v4.0)
+
+## 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 | always |
+| FK | `<ref_table_singular_no_tbl>_id` | `user_id` refs `tbl_users` |
+| Index (per-table) | `idx_<table_no_tbl>_<cols>` | `idx_users_email` |
+| Migration (create) | `<N>-setup-tbl-<name>.sql` | `3-setup-tbl-users.sql` |
+| Migration (alter) | `<N>-alter-tbl-<name>-<desc>.sql` | — |
+| Shared indexes | `111-setup-database-indexes.sql` | always last |
+
+## Column Types
+| Use | Type |
+|---|---|
+| Primary key | `bigint NOT NULL GENERATED ALWAYS AS IDENTITY (...)` |
+| Foreign key | `BIGINT NOT NULL DEFAULT 0` |
+| Email | `VARCHAR(132)` |
+| Password/token | `TEXT` |
+| 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`.
+
+## SQL File Content Order (strict)
+1. Comment: `-- Creating tbl_name for purpose`
+2. `DROP TABLE IF EXISTS public.tbl_name CASCADE;`
+3. `CREATE TABLE` block
+4. `COMMENT ON COLUMN` for every enum/flag 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 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.
+
+## Prisma Conventions (v4.0 — orm="prisma" only)
+- `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")`
+- After every model addition → `npx prisma generate`

package/ide/cursor/.cursor/rules/06-reactjs.mdc

@@ -0,0 +1,36 @@
+---
+description: ReactJS architecture standards — apiClient, apiHandler, component rules.
+globs: ["**/*.jsx", "**/src/**"]
+alwaysApply: false
+---
+
+# codeninja — ReactJS Architecture Standards
+
+## apiClient.js — 4 Responsibilities
+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 JSON; code -1 → logout redirect
+4. Response interceptor (error): ERR_NETWORK/401 → logout redirect + error message
+
+## apiHandler.js Standard
+- One `async` function per backend endpoint
+- No try/catch, no decryption, no response shaping here (interceptors handle it)
+- All API endpoint paths defined here — never in page components
+
+## Backend Linking Rule
+- ReactJS service CANNOT be initialized without a linked NodeJS backend
+- Inherits from linked backend: `encryption_key`, `encryption_iv`, `api_key`, `port`
+- These are NEVER asked from the user — always inherited from `context.services[linked]`
+
+## Vanilla CSS Only
+- Per-page: `<PageName>.module.css`
+- Global: `public/assets/css/style.css`
+- No Tailwind, no CSS-in-JS, no styled-components
+
+## .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/ide/cursor/.cursor/rules/07-reactjs-generation.mdc

@@ -0,0 +1,49 @@
+---
+description: ReactJS file generation standards — exact content for each generated React file.
+globs: ["**/src/pages/**", "**/src/components/**", "**/src/api/**"]
+alwaysApply: false
+---
+
+# codeninja — ReactJS File Generation Standards
+
+Read `.codeninja/tasks/generate-react-*.task.md` before generating each file.
+
+## src/api/apiClient.js
+- Axios instance with `baseURL: process.env.REACT_APP_BASE_URL`
+- Static headers: `api-key`, `Accept-Language: en`, `Content-Type: text/plain`
+- Request interceptor: `CryptoJS.AES.encrypt(JSON.stringify(data), key, {iv})` + token header
+- Response success: decrypt + JSON.parse; responsecode -1 → `logOutRedirectCall()`
+- Response error: 401 or ERR_NETWORK → `logOutRedirectCall()` + `showErrorMessage()`
+
+## src/api/apiHandler.js
+- Imports `axiosClient` from `./apiClient`
+- One exported async function per endpoint
+- No try/catch — interceptors handle errors
+- Example: `export const loginUser = (data) => axiosClient.post('/login', data)`
+
+## src/pages/Welcome/index.jsx
+- Functional component using project name from env/context
+- Imports `Welcome.module.css`
+- No data fetching, no state — pure welcome UI
+- First route in App.jsx at path `/`
+
+## src/App.jsx
+- React Router v6: `BrowserRouter` + `Routes` + `Route`
+- First route: `<Route path="/" element={<Welcome />} />`
+
+## src/index.jsx
+- `ReactDOM.createRoot(document.getElementById('root')).render(<App />)`
+
+## public/index.html
+- Single HTML shell with `<div id="root"></div>`
+- Links to `public/assets/css/style.css`
+- No inline JS or styles
+
+## .htaccess (both root and public/)
+```apache
+RewriteEngine On
+RewriteBase /
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^ index.html [L]
+```

package/ide/cursor/.cursor/rules/08-code-intelligence.mdc

@@ -0,0 +1,56 @@
+---
+description: Code intelligence commands — audit, debug, review, optimize checklists.
+alwaysApply: false
+---
+
+# codeninja — Code Intelligence Standards (v4.0)
+
+## /codeninja:audit Checklist
+
+### Security
+- [ ] API key validation on all routes?
+- [ ] Passwords HASHED using `utilities/hashing.js`? Never AES-encrypted?
+- [ ] No direct bcrypt/argon2 imports in route/model files?
+- [ ] Parameterized queries only — no string concatenation in SQL?
+- [ ] No hardcoded keys/passwords in source?
+- [ ] `.env` in `.gitignore`?
+- [ ] Middleware order: rateLimiter→extractLanguage→validateApiKey→[auth]→decryptRequest?
+
+### Architecture
+- [ ] 2-layer rule: no SQL in route.js, no res.json() in model files?
+- [ ] route_manager.js uses `file_insert_after` — never rewritten?
+- [ ] All routes in swagger_doc.json?
+- [ ] All routes in context.api_routes?
+
+### v4.0 Checks
+- [ ] If orm="prisma": no `new PrismaClient()` in model files?
+- [ ] If language="typescript": no `require()` in .ts files?
+
+## /codeninja:debug Trace Path
+1. extractLanguage (headerValidator) — language set?
+2. validateApiKey — api-key header matches .env?
+3. validateAuthToken (if protected) — token valid?
+4. rateLimiter — not throttled?
+5. validatorjs rules in route.js — all required fields present?
+6. Model function call — DB connection alive?
+7. DB query (SQL or Prisma) — column names match context.db.schema?
+8. sendResponse — encrypted_transport flag handled correctly?
+
+**Common causes:** 401=middleware order or key mismatch; 400=validation rules mismatch; 500=DB connection or column name wrong.
+
+## /codeninja:review Dimensions
+- Security: auth middleware present, parameterized queries, no hardcoded secrets
+- Architecture: 2-layer rule, route_manager registration, swagger coverage
+- Code quality: JSDoc on every function, no console.log, async try/catch
+- Database: column names match context, FK indexes present, LIMIT on list queries
+
+## /codeninja:optimize Patterns
+1. Missing index → `CREATE INDEX CONCURRENTLY`
+2. `SELECT *` → explicit column list
+3. N+1 → JOIN or IN clause
+4. `DATE(col)` in WHERE → range filter to preserve index
+5. `RANK()` with gaps → `DENSE_RANK()` for leaderboards
+6. No LIMIT on unbounded list queries
+7. Heavy middleware on lightweight routes
+8. Redis caching opportunities (repeated identical queries)
+9. `work_mem` session-level for sort-heavy queries

package/ide/cursor/.cursor/rules/09-workflow-steps.mdc

@@ -0,0 +1,53 @@
+---
+description: Full workflow steps for all codeninja commands — init phases, api creation, DB operations.
+alwaysApply: false
+---
+
+# codeninja — Workflow Steps Reference (v4.0)
+
+Read `.codeninja/commands/<workflow>.workflow.md` for the full step-by-step execution of each command.
+Read `.codeninja/tasks/<task>.task.md` before generating any file.
+
+## /codeninja:init — Key Phases
+
+**Phase 0** (once per repo): ask-project-info-doc → ask-project-scope-of-work → ask-project-figma → synthesize summary
+
+**Phase 1** (mode + type): ask-init-mode → ask-project-type
+- NodeJS: ask-client-type → ask-language-type → ask-encrypted-transport → ask-supported-languages
+- ReactJS: ask-linked-service → inherit encryption/api values from linked backend
+
+**Phase 2** (database, skip for ReactJS): ask-database-type → ask-orm-type → ask-database-config
+- Fast mode: ask-database-name + ask-database-user only
+
+**Phase 3–5** (service identity + config): ask-service-name → ask-service-port → ask-service-description
+- Manual NodeJS: ask-package-name → ask-package-author → ask-api-key → ask-encryption-key → ask-redis-config → ask-hashing-library
+- Fast NodeJS: generate-fast-defaults (auto-sets port, api_key, encryption_key, language="javascript", hashing_library="bcryptjs", orm="none")
+
+**Phase 6** (confirm + generate): show-init-summary → single confirmation → ALL files generated silently
+
+**NodeJS Wave 1** (Foundation): package.json, .env, .gitignore, README.md, config/constants, config/template, logger/logging, utilities/encryption, **utilities/hashing**, languages/*, enc_dec.html/php, **tsconfig.json (TS only)**
+
+**NodeJS Wave 2** (Infrastructure): config/database (or config/prisma if orm=prisma), utilities/ioRedis, utilities/response
+
+**NodeJS Wave 3** (Service): config/common, utilities/validator, utilities/notification, middleware/rateLimiter
+
+**NodeJS Wave 4** (Middleware + Business): middleware/headerValidator, modules/v1/<Name>/route, modules/v1/<Name>/<name>_model, document/v1/swagger_doc.json
+
+**NodeJS Wave 5** (Orchestration): modules/v1/route_manager, app.js/ts
+
+**NodeJS Wave 6** (Docker): Dockerfile, .dockerignore
+
+## /codeninja:api — Key Steps
+1. Review existing modules (Phase 0)
+2. ask-target-service → ask-api-version → ask-module-name → ask-http-method → ask-route-path → ask-route-description
+3. ask-primary-table → ask-requires-auth
+4. Confirm → generate route.js/ts + _model.js/ts + append route_manager + patch swagger
+
+## /codeninja:db:create — Key Steps
+1. ask-table-purpose → ask-table-name → ask-table-file-number
+2. ask-table-needs-status → ask-table-needs-soft-delete
+3. Column loop: ask-column-name → ask-column-type → ask-column-is-enum → repeat until done
+4. ask-table-indexes
+5. ask-table-seed-data → if yes: collect-seed-data
+6. show-db-table-summary → confirm → generate SQL file + update create-schema.sql
+7. If orm=prisma: also append model to prisma/schema.prisma + `npx prisma generate`