codeninja 2.0.0

package/tasks/generate-react-welcome-page.task.md

@@ -0,0 +1,71 @@
+---
+type: task
+name: generate-react-welcome-page
+agent: reactjs-agent
+---
+
+# Files: src/pages/Welcome/index.jsx and src/pages/Welcome/Welcome.module.css
+
+## Purpose
+The default landing page rendered at the `/` route. Displays a centered
+welcome message using the project name. This page exists purely to
+confirm the app is running correctly and to give the developer a working
+starting point. It is replaced or extended as real pages are built.
+
+---
+
+## index.jsx
+
+### Dependencies to Import
+- `React` from `"react"`
+- `styles` from `"./Welcome.module.css"` — CSS module for this page
+
+### Structure
+A single default-exported functional component named `Welcome`.
+
+Renders a full-viewport centered container with:
+- A heading displaying "Welcome to [service_name]" where `[service_name]`
+  is from `context.current_init.service_name` in title case — hardcoded
+  as a string in the generated file (not read from env at runtime)
+- A short subtext line: "Your project is ready. Start building."
+- No images, no buttons, no API calls
+
+### JSDoc Comment
+Include above the component:
+- Description: "Default landing page. Replace with your application home screen."
+
+### Export
+Default export: `export default Welcome`
+
+---
+
+## Welcome.module.css
+
+### Purpose
+Scoped styles for the Welcome page component.
+
+### Styles to Include
+
+A `.container` class:
+- Full viewport height (`height: 100vh`)
+- Flexbox column layout centered both axes
+- Background color: a clean neutral (e.g. `#f8f9fa`)
+
+A `.title` class:
+- Font size: `2rem`
+- Font weight: `600`
+- Color: a dark neutral (e.g. `#1a1a1a`)
+- Margin bottom: `0.5rem`
+
+A `.subtitle` class:
+- Font size: `1rem`
+- Color: a muted neutral (e.g. `#666666`)
+
+---
+
+## What These Files Do NOT Do
+
+- Do not make any API calls
+- Do not import from apiHandler.js
+- Do not manage any state
+- Do not include navigation or header components

package/tasks/generate-readme.task.md

@@ -0,0 +1,160 @@
+---
+type: task
+name: generate-readme
+agent: nodejs-agent
+---
+
+# File: README.md
+
+## Purpose
+Service-level documentation file. Describes what the service does, how
+to set it up from scratch, how to run it, and key architectural
+decisions. Generated once during `@initialize-project`. Uses information
+from context to produce a readme specific to this service.
+
+---
+
+## Sections to Include
+
+---
+
+### 1. Service Title and Description
+- Heading: the service name from `context.current_init.service_name`
+  in title case
+- One paragraph description from `context.current_init.description`
+- A metadata line showing: Type, Port, Database, Client Type,
+  Encrypted Transport, Languages
+
+---
+
+### 2. Prerequisites
+List what must be installed before running the service:
+- Node.js (v18 or higher)
+- npm
+- The relevant database based on `context.db.type`:
+  - postgresql → PostgreSQL 14+
+  - mysql → MySQL 8+
+  - mongodb → MongoDB 6+
+- Redis (with install commands per OS — same as shown in
+  show-final-summary Redis block)
+- PHP (only if `client_type == "app"` — needed to run enc_dec.php)
+
+---
+
+### 3. Installation
+```
+git clone <repository>
+cd <service_name>
+npm install
+```
+
+---
+
+### 4. Environment Setup
+Instructions to create the `.env` file:
+```
+cp .env.example .env
+```
+
+Then fill in the required values. List every key from the `.env`
+template defined in nodejs-agent with a one-line description of each.
+Group them the same way they appear in the `.env` file.
+
+---
+
+### 5. Database Setup
+Show the database setup commands based on `context.db.type`:
+
+**PostgreSQL**:
+```
+cd database/postgresql
+bash setup-database.sh      # Linux/Mac
+.\setup-database.ps1        # Windows
+```
+
+**MySQL**:
+```
+cd database/mysql
+bash setup-database.sh
+```
+
+**MongoDB**:
+No migration runner — connection is automatic on service start.
+
+---
+
+### 6. Redis Setup
+Same Redis setup block as in show-final-summary:
+```
+macOS:   brew install redis && brew services start redis
+Linux:   sudo apt install redis-server && sudo systemctl start redis
+Windows: winget install Redis.Redis && redis-server
+Verify:  redis-cli ping   (expected: PONG)
+```
+
+---
+
+### 7. Running the Service
+```
+# Development (with auto-restart)
+npm run dev
+
+# Production
+npm start
+```
+
+Service runs at: `http://localhost:<port>`
+API base path: `http://localhost:<port>/api/v1`
+
+---
+
+### 8. Project Structure
+Show the full file structure tree using the structure from
+nodejs-agent.md, filled in with the actual service name and the
+actual language files generated.
+
+---
+
+### 9. API Documentation
+Mention that Swagger documentation is available:
+```
+http://localhost:<port>/api/v1/docs
+```
+Note: Swagger UI route is added when the first module is created via
+`@create-api`.
+
+---
+
+### 10. Encryption & Decryption Testing
+
+If `client_type == "reactjs"`:
+```
+Open enc_dec.html directly in your browser.
+Pre-filled with your service KEY and IV.
+```
+
+If `client_type == "app"`:
+```
+Run enc_dec.php on a local PHP server:
+php -S localhost:8080 enc_dec.php
+Then open http://localhost:8080/enc_dec.php
+```
+
+---
+
+### 11. Key Architecture Decisions
+Short bullet list covering:
+- 2-layer module pattern (route + model, no controller/service)
+- All responses go through utilities/response.js
+- All encryption through utilities/encryption.js
+- Session management via JWT + Redis version (no DB query per request)
+- Language support via localizify with per-language files
+- Custom file-based logger with 10-day rotation
+
+---
+
+## What This File Does NOT Do
+
+- Does not document individual API endpoints — that is Swagger's job
+- Does not include code samples beyond setup commands
+- Does not reference internal implementation details like column names

package/tasks/generate-response.task.md

@@ -0,0 +1,202 @@
+---
+type: task
+name: generate-response
+agent: nodejs-agent
+---
+
+# File: utilities/response.js
+
+## Purpose
+Single function responsible for building and sending every HTTP response
+in the service. No route handler or middleware calls `res.json()` or
+`res.status()` directly — all responses go through this file.
+Handles translation resolution, conditional encryption, and consistent
+response shape in one place.
+
+---
+
+## Dependencies to Import
+
+- `../utilities/encryption` — imports `encrypt` only
+- `localizify` — imports `{ default: localizify }` and `{ t }` separately.
+  Both are needed — localizify for setLocale/add calls, t for translation.
+- All language files from `../languages/` — imported individually the
+  same way headerValidator does. Agent generates one require line per
+  language in `context.services[<n>].supported_languages`.
+  Build a `languageMap` object at module load mapping code to object.
+- `../logger/logging` — imports `log`
+
+---
+
+## Module-Level Constants
+
+### languageMap
+Built once at module load time. Maps language code strings to their
+imported language objects. Identical in structure to the languageMap
+in headerValidator.js — both read SUPPORTED_LANGUAGES from process.env
+and import the same language files.
+Example: `{ "en": en, "ar": ar }`
+Used by `getMessage` to look up the correct language object before
+calling localizify.add and setLocale.
+
+### DEFAULT_LANGUAGE
+Read `process.env.DEFAULT_LANGUAGE` once at module load.
+Used by `getMessage` as fallback when the requested lang code is
+not found in languageMap.
+
+### ENCRYPTED_TRANSPORT
+Read `process.env.ENCRYPTED_TRANSPORT` once at module load.
+Parse it as a boolean: the string `"true"` becomes `true`, anything
+else becomes `false`. Store as a module-level constant.
+This is checked on every `sendResponse` call to decide whether to
+encrypt the outgoing payload.
+
+### RESPONSE_MODE
+Read `process.env.RESPONSE_MODE` once at module load.
+Valid values: `"http"` | `"company"`. Default to `"company"` if unset.
+This determines what value goes in the response body's `code` field:
+
+- `"http"` mode — `code` echoes the HTTP status code integer.
+  The client reads `code === 200` for success, `code === 401` for auth
+  errors, etc. No internal 0/1 values are used.
+
+- `"company"` mode — `code` uses internal string values:
+  `"1"` for success, `"0"` for failure, `"-1"` for auth error.
+  The HTTP status code is still sent correctly on the wire — this
+  only controls the body field.
+
+---
+
+## Functions
+
+---
+
+### sendResponse(req, res, statusCode, responseCode, messageKeyword, messageComponents, responseData)
+
+**Purpose**: The single exit point for all API responses. Resolves the
+message keyword to a translated string, builds the standard response
+shape, conditionally encrypts the payload, and sends the HTTP response.
+
+**Parameters**:
+- `req` — Express request object. Used to read `req.lang` for translation
+  locale. Must have `req.lang` set by `extractLanguage` before this is
+  called.
+- `res` — Express response object. Used to call `.status().json()`.
+- `statusCode` — HTTP status code integer. e.g. `200`, `401`, `500`.
+- `responseCode` — application-level code. In `"company"` mode this is
+  a string: `"1"` success, `"0"` failure, `"-1"` auth error. In `"http"`
+  mode this parameter is ignored — the code field is derived from
+  `statusCode` instead.
+- `messageKeyword` — translation key string from the language file.
+  e.g. `"rest_keywords_invalid_api_key"`. Never a raw message string.
+- `messageComponents` — plain object for keyword interpolation.
+  e.g. `{ name: "John" }`. Pass empty object `{}` when no interpolation
+  needed. Never null.
+- `responseData` — the data payload to include. Pass `null` when there
+  is no data to return (error responses, auth failures).
+
+**Flow**:
+
+1. Resolve the message string:
+   Call `getMessage(req.lang, messageKeyword, messageComponents)`.
+   Store result as `message`.
+
+2. Determine the `code` value for the response body:
+   - If `RESPONSE_MODE === "http"` → `code = statusCode` (integer)
+   - If `RESPONSE_MODE === "company"` → `code = responseCode` (string)
+
+3. Build the response shape:
+   Always include: `{ code, message }`
+   If `responseData` is not null — add `data: responseData` to the object.
+   If `responseData` is null — omit the `data` key entirely. Do not send
+   `data: null`.
+
+4. Check `ENCRYPTED_TRANSPORT`:
+   If `true` — call `encrypt(responseShape)` from `utilities/encryption.js`.
+   Send the result directly as the response body:
+   `res.status(statusCode).json(encryptedString)`
+   Note: the entire encrypted cipher string becomes the JSON body — the
+   client receives a JSON string value, not a JSON object.
+
+   If `false` — send the plain response shape object directly:
+   `res.status(statusCode).json(responseShape)`
+
+5. Log at info level: statusCode, code value used, messageKeyword.
+   Do not log responseData — it may contain sensitive information.
+
+6. This function is async because `getMessage` involves localizify
+   operations. Use await internally.
+
+---
+
+### getMessage(lang, keyword, components)
+
+**Purpose**: Resolves a translation keyword to a human-readable string
+using localizify. Internal helper — not exported.
+
+**Parameters**:
+- `lang` — language code string from `req.lang`. e.g. `"en"`, `"ar"`.
+- `keyword` — translation key string.
+- `components` — interpolation object.
+
+**Flow**:
+
+1. Load the language object for the requested language:
+   Read the `languageMap` from `headerValidator` — but since
+   `getMessage` lives in `response.js` which cannot import
+   `headerValidator` (circular dependency), the language registration
+   is done inline here instead.
+
+   Call `localizify.add(lang, languageObject)` to register the
+   translations for this language code. The `languageObject` must be
+   loaded from the languages directory.
+
+   How to load the language object:
+   At module load time in response.js, build a `languageMap` the same
+   way headerValidator does — import each language file individually
+   based on `process.env.SUPPORTED_LANGUAGES` and map them by code.
+   Use this map in `getMessage` to look up the correct language object.
+
+   If `lang` is not found in the map — fall back to DEFAULT_LANGUAGE.
+
+2. Call `localizify.setLocale(lang)` to activate this language.
+   This must happen before every `t()` call — not just once at
+   request start. This makes getMessage self-contained and safe
+   under concurrent requests where multiple locales may be active.
+
+3. Call `t(keyword, components)`.
+
+4. Return the result string.
+
+5. If `t()` returns the keyword string unchanged — the key does not
+   exist in the language file. Return the keyword as-is. Log at debug
+   level so missing keys are visible during development.
+
+6. This function is synchronous internally but declared async for
+   consistency with `sendResponse`.
+
+---
+
+## Export
+```
+module.exports = { sendResponse, getMessage }
+```
+
+`getMessage` is exported so that files outside the request lifecycle
+(such as `notification.js`) can resolve translation keywords without
+importing localizify directly. Any file that needs a translated string
+must use `getMessage` — never call `t()` or `localizify` directly.
+
+---
+
+## What This File Does NOT Do
+
+- Does not import or use `req.body` — response only, never reads body
+- Does not make database queries
+- Does not import language files directly — relies on localizify state
+  set by `extractLanguage`
+- Does not decide what HTTP status code to use — that is the caller's
+  responsibility
+- Does not catch errors from `encrypt()` — if encryption fails the
+  response will fail. This is correct behavior — a broken encryption
+  setup should surface immediately, not be swallowed silently

package/tasks/generate-route-manager.task.md

@@ -0,0 +1,173 @@
+---
+type: task
+name: generate-route-manager
+agent: nodejs-agent
+---
+
+# File: modules/v1/route_manager.js
+
+## Purpose
+The versioned router that sits between app.js and all module route files.
+It applies the full middleware chain in the correct order to every request,
+then delegates to each module's route.js. It is the single place where
+middleware is mounted and where module routes are registered. Adding a
+new module means adding exactly one line to this file.
+
+---
+
+## Dependencies to Import
+
+- `express` — for `express.Router()`.
+- `../../middleware/headerValidator` — imported as `middleware`. Three or four middleware functions depending on encrypted_transport value.
+- `../../middleware/rateLimiter` — imported as `rateLimiter`. Applied
+  as the first middleware in the chain.
+- One import per module route file. Each import follows the pattern:
+  `require('./<ModuleName>/route')`. Agent generates one line per
+  module in `context.services[<name>].modules`.
+  During `@initialize-project` when no modules exist yet, this section
+  is empty — no module imports, no route registrations.
+
+---
+
+## asyncHandler Utility
+
+Define a local utility function called `asyncHandler` at the top of
+the file after the imports.
+
+Purpose: wraps any async middleware or route handler function in a
+try/catch that passes errors to Express's `next` function. This prevents
+unhandled promise rejections from crashing the process when an async
+middleware throws.
+
+Behavior: accepts a function `fn`. Returns a new function that accepts
+`(req, res, next)`. Inside, it calls `Promise.resolve(fn(req, res, next))`
+and chains `.catch(next)`. Any thrown error or rejected promise is
+forwarded to Express's error handling via `next`.
+
+This utility is defined locally in this file only. It is not exported
+and not imported from elsewhere.
+
+---
+
+## Middleware Chain
+
+Apply the middleware chain using `router.use('/', ...)` in this exact
+order. Every middleware is wrapped with `asyncHandler`:
+
+1. `rateLimiter` — must be first. Rejects over-limit requests before
+   any other processing.
+2. `middleware.extractLanguage` — language detection and localizify
+   setup. Must run before any function that sends a response, so that
+   translation is available to all subsequent middleware.
+3. `middleware.validateApiKey` — API key check. Runs after language
+   extraction so that the 401 response is translated correctly.
+4. `middleware.validateToken` — JWT and Redis version check. Runs after
+   API key so that unauthenticated routes bypass correctly.
+5. If `encrypted_transport == true` → apply `middleware.decryptRequest`
+   as the last item in the chain.
+   If `encrypted_transport == false` → this line does not exist.
+   The chain ends at validateToken.
+
+All five use `router.use('/', asyncHandler(...))` with the `/` path.
+This applies them to every route registered on this router.
+
+---
+
+## Route Registration
+
+After the middleware chain, register each module's router using
+`router.use('/<modulename>/', <moduleRouter>)`.
+
+Route name convention:
+- Use lowercase
+- Use the module name as the route segment directly
+- No version prefix here — the version is already in the mount path
+  from app.js (`/api/v1`)
+- No comments on route registration lines — the module name and
+  path are fully self-documenting at this level.
+  Exception: add a file-level comment header as the first line
+  of the file per Code Style Standards in nodejs-agent.md.
+
+Example pattern (for an Auth module):
+`router.use('/auth/', auth)`
+
+---
+
+## Generation vs Update Mode
+
+### Mode 1 — Generation (called from @initialize-project)
+The route registration section starts empty — no module imports,
+no router.use lines for routes. The middleware chain is written
+in full. This is a complete file write. Safe because the file
+does not exist yet.
+
+### Mode 2 — Append (called from @create-api)
+NEVER rewrite route_manager.js when adding a new module.
+Instead perform two precise surgical insertions:
+
+**Insertion 1 — Import line**
+Read the file. Find the last `require(` line in the imports block
+at the top of the file. Insert one new line immediately after it:
+`const <ModuleName> = require('./<ModuleName>/route');`
+
+Use the module name in camelCase for the variable name.
+Example: module "Products" → `const Products = require('./Products/route');`
+
+**Insertion 2 — Route registration line**
+Read the file. Find the last `router.use(` line in the route
+registration block. Insert one new line immediately after it:
+`router.use('/<modulename>/', <ModuleName>);`
+
+Use lowercase for the route segment, camelCase for the variable.
+Example: `router.use('/products/', Products);`
+
+**Safety Rules for Append Mode:**
+- Read the file first — always verify it exists before editing
+- Never touch the middleware chain lines — only the imports block
+  and the route registration block
+- Never remove or reorder existing lines
+- Never add comments
+- If the module is already registered (duplicate check) — skip
+  silently, do not add it again
+- The two insertions happen sequentially — import first,
+  then route registration
+
+**Duplicate Detection:**
+Before inserting, scan the file for:
+- An existing require line containing the module name
+- An existing router.use line containing the module path
+If either exists → this module is already registered.
+Log at info level: "Module [name] already registered in
+route_manager.js — skipping." Do not modify the file.
+
+---
+
+## File Header
+
+The first line of route_manager.js must be:
+```javascript
+// Mounts all module routers and applies the global middleware chain.
+```
+
+---
+
+## Export
+```
+module.exports = router
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not define any route handlers directly — all handlers live in
+  module route.js files
+- Does not import encryption, response, or validator utilities — those
+  are used inside route.js and middleware files
+- Does not apply middleware selectively per route — all middleware
+  applies to all routes. Per-route middleware (like decryptRequest for
+  specific endpoints) is applied inside the module's route.js
+- Does not version routes itself — versioning is done by the mount
+  path in app.js
+- Does not contain any comments on route registration lines — route
+  names are self-documenting per the module naming convention