codeninja 2.0.0

package/tasks/generate-route.task.md

@@ -0,0 +1,203 @@
+---
+type: task
+name: generate-route
+agent: nodejs-agent
+---
+
+# File: modules/v1/<ModuleName>/route.js
+
+## Purpose
+The Express router for a single API module. Defines all HTTP routes for
+this module, handles input validation inline using checkValidationRules,
+calls the model function, and sends the response via sendResponse. This
+file contains no business logic — it is purely a request/response
+coordinator. Every route in this file follows the same structural pattern.
+
+This file is generated fresh for every `@create-api` command. The agent
+reads `context.current_api` to know the method, path, module name,
+primary table, and auth requirements for the new route being added.
+
+---
+
+## Dependencies to Import
+
+- `express` — for `express.Router()`
+- `./<module>_model` — imported using the lowercase module name.
+  e.g. for module `Auth` → `require('./auth_model')`
+- `../../../utilities/response` — imported as `{ sendResponse }`.
+  Used to send all responses. Never call `res.json()` directly.
+- `../../../utilities/validator` — imported as `{ checkValidationRules }`.
+  Used for input validation on POST/PUT/PATCH routes.
+- `../../../logger/logging` — imported as `log`. Used at the start of
+  every route handler.
+
+---
+
+## Router Initialization
+
+Create the router: `const router = express.Router()`
+Assign model: `const <moduleName>Model = require('./<module>_model')`
+
+---
+
+## Default Routes (generated during @initialize-project)
+
+```
+The default route file must have a file-level header comment as
+the first line of the file:
+```javascript
+//  <ModuleName> module routes. Handles validation and delegates to model.
+```
+
+Each route handler must have a single-line comment above it
+following the pattern defined in nodejs-agent.md Code Style Standards.
+```
+
+---
+
+When the route.js file is first generated as part of
+`@initialize-project`, it contains TWO default routes:
+
+### 1. Health Check Route (for Docker/monitoring)
+
+**Route**: `GET /health`
+
+**Handler flow**:
+1. Log at info level: module name + "health check called"
+2. Return JSON directly (no model, no sendResponse):
+```javascript
+res.status(200).json({
+  status: 'healthy',
+  timestamp: new Date().toISOString(),
+  service: process.env.npm_package_name || 'unknown',
+  uptime: process.uptime()
+});
+```
+
+This route is PUBLIC (no auth middleware) and placed FIRST in the file.
+
+### 2. Test Route (for API testing)
+
+**Route**: `GET /test`
+
+**Handler flow**:
+1. Log at info level: module name + "test route called"
+2. Call `sendResponse` with:
+   - `req` and `res` passed through
+   - `statusCode` — `200`
+   - `responseCode` — `"1"`
+   - `messageKeyword` — `"rest_keywords_success"`
+   - `messageComponents` — `{}`
+   - `responseData` — object with one key: `{ service: process.env.PROJECT_NAME, module: "<ModuleName>", status: "ok" }`
+
+These default routes are extended (not replaced) when `@create-api` generates
+actual routes.
+
+---
+
+## Route Pattern for Generated Routes (used by @create-api)
+
+Every route generated by @create-api follows the comment pattern
+from nodejs-agent.md Code Style Standards — one single-line comment
+above each router.get/post/put/patch/delete call.
+
+Every route generated by `@create-api` follows this exact pattern:
+
+### GET route pattern
+
+Handler receives `req` and `res`. Handler is async.
+
+Flow:
+1. Extract query parameters or path params from `req.query` or
+   `req.params` as needed. Store as `request` object.
+2. Log at info level: route name + "request" with the request object.
+3. Call the model function:
+   `const { responsecode, responsemsg, responsedata } = await
+   <moduleName>Model.<functionName>(request, req.user_id, req.user_type)`
+   `req.user_id` and `req.user_type` are set by validateToken and always
+   available on protected routes. Pass them to model explicitly.
+4. Call `sendResponse(req, res, 200, responsecode, responsemsg, responsedata)`.
+
+### POST / PUT / PATCH route pattern
+
+Handler receives `req` and `res`. Handler is async.
+
+Flow:
+1. Assign `let request = req.body`. The body is already decrypted by
+   `decryptRequest` middleware if encrypted_transport is true.
+2. Define `rules` object — keys are field names, values are validatorjs
+   rule strings. Agent reads `context.current_api.primary_table` columns
+   from `context.db.schema` to suggest relevant rules.
+3. Define `messages` object — keys are rule names like `'required'`
+   and `'email'`, values use `req.languageData.<key>` to get the
+   translated rule message. For example:
+   `'required': req.languageData.required`
+   `'email': req.languageData.email`
+   Only include message overrides for rules actually used in `rules`.
+4. Log at info level: route name + "request" with the request object.
+5. Call `await checkValidationRules(req, res, rules, messages)`.
+   Store result as `isValid`.
+6. If `isValid` is false — return immediately. Response already sent.
+7. If `isValid` is true — call the model function same as GET pattern.
+8. Call `sendResponse`.
+
+### DELETE route pattern
+
+Same as GET pattern. No body, no validation. Path params only.
+
+---
+
+## Auth Middleware Application (per-route)
+
+Read `context.current_api.requires_auth`:
+
+- If `"full"` — no extra middleware needed in route.js. validateToken
+  in route_manager already handles this globally. `req.user_id` and
+  `req.user_type` will be set.
+- If `"api_key_only"` — same as full, validateToken is bypassed via
+  bypassMethod in headerValidator for this route. Document this in a
+  comment above the route.
+- If `"none"` — same, bypass is configured in headerValidator. Document
+  in a comment above the route.
+
+No middleware is applied directly inside route.js. All auth is
+handled at the route_manager level via headerValidator. Route.js only
+documents the auth requirement in a comment.
+
+---
+
+## Response Pattern Contract
+
+Every route handler must call `sendResponse` exactly once and
+immediately return after. Never call `sendResponse` inside a conditional
+without a return. The model always returns three values destructured as:
+`{ responsecode, responsemsg, responsedata }`
+
+- `responsecode` — string `"1"` for success, `"0"` for failure
+- `responsemsg` — object with `keyword` and `components` keys
+- `responsedata` — the data payload or null
+
+These are passed directly to `sendResponse` — route.js never inspects
+or modifies them.
+
+---
+
+## Export
+```
+module.exports = router
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not import config/database — no DB queries in route files
+- Does not import encryption utilities — decryption already done by
+  middleware before this runs
+- Does not contain business logic — all logic is in the model file
+- Does not import config/common — common is for model files
+- Does not call res.json() directly — always uses sendResponse
+- Does not import middleware from headerValidator for sendresponse or
+  checkValidationRules — those are now in their own utility files
+- Does not define more than one module's routes — one route.js per
+  module always

package/tasks/generate-swagger.task.md

@@ -0,0 +1,290 @@
+---
+type: task
+name: generate-swagger
+agent: nodejs-agent
+---
+
+# File: document/v1/swagger_doc.json
+
+## Purpose
+OpenAPI 3.0 specification file for the service. Documents all API
+endpoints, request/response schemas, authentication requirements, and
+error responses. Generated as an empty skeleton during
+`@initialize-project` and updated every time `@create-api` adds a new
+route. This file is the single source of API documentation — developers
+and frontend teams reference it to understand what the API expects and
+returns.
+
+---
+
+## Generation Modes
+
+This task is called in two different situations. The agent reads the
+call context to determine which mode applies:
+
+### Mode 1 — Skeleton (called from @initialize-project)
+Generates the base swagger_doc.json with service metadata, security
+scheme definitions, and no paths. Called once.
+
+### Mode 2 — Update (called from @create-api)
+Reads the existing swagger_doc.json, adds the new endpoint path entry,
+and writes the file back. Called every time a new route is created.
+
+---
+
+## Mode 1 — Skeleton Structure
+
+Generate a valid OpenAPI 3.0 JSON file with this exact top-level
+structure:
+
+### openapi
+Value: `"3.0.0"` — always this version string.
+
+### info
+Object with these keys:
+- `title` — from `process.env.PROJECT_NAME` / `context.current_init.service_name`
+- `description` — from `context.current_init.description`
+- `version` — `"1.0.0"`
+- `contact` — object with:
+  - `name` — from `context.current_init.author`
+
+### servers
+Array with one entry:
+- `url` — constructed as `http://localhost:<port>/api/v1` where port
+  comes from `context.current_init.port`
+- `description` — `"Local development server"`
+
+### components
+
+#### securitySchemes
+Define two security schemes:
+
+**ApiKeyAuth**:
+```json
+{
+  "type": "apiKey",
+  "in": "header",
+  "name": "api-key",
+  "description": "AES encrypted API key. Encrypt the raw API_KEY value before sending."
+}
+```
+
+**TokenAuth**:
+```json
+{
+  "type": "apiKey",
+  "in": "header",
+  "name": "token",
+  "description": "AES encrypted JWT token. Encrypt the JWT before sending."
+}
+```
+
+Note: Both use `apiKey` type because the headers are custom (`api-key`
+and `token`) not the standard `Authorization: Bearer` pattern. OpenAPI
+does not have a built-in type for custom encrypted headers — apiKey is
+the closest match.
+
+#### schemas
+Define three reusable response schemas:
+
+**SuccessResponse**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": { "type": "string", "example": "1" },
+    "message": { "type": "string", "example": "Success!" },
+    "data": { "type": "object" }
+  }
+}
+```
+
+**ErrorResponse**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": { "type": "string", "example": "0" },
+    "message": { "type": "string", "example": "Something went wrong" }
+  }
+}
+```
+
+**UnauthorizedResponse**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": { "type": "string", "example": "-1" },
+    "message": { "type": "string", "example": "Invalid token provided" }
+  }
+}
+```
+
+Note on `encrypted_transport`: If `encrypted_transport == true`, add
+a note in the `info.description` field stating:
+`"All request bodies must be AES-256-CBC encrypted. All response data
+is AES-256-CBC encrypted. Use the enc_dec tool to test payloads."`
+
+#### paths
+Empty object `{}`. Populated by Mode 2 calls.
+
+---
+
+## Mode 2 — Adding a New Path Entry
+
+Called from `@create-api` after the user confirms the new route.
+The agent reads `context.current_api` for all values.
+
+### Steps
+1. Read the existing `document/v1/swagger_doc.json` file.
+2. Find or create the path key in `paths` using
+   `context.current_api.route_path` as the key.
+   Example: `"/products"` or `"/products/{id}"`
+   Note: path parameters use `{param}` format in OpenAPI, not `:param`
+   Express format. Convert `:id` → `{id}`, `:orderId` → `{orderId}`.
+3. Under the path key, add the HTTP method key in lowercase:
+   `context.current_api.method.toLowerCase()`
+4. Build the operation object as described below.
+5. Write the updated file back to disk.
+
+## Append Safety Rules for Mode 2
+
+NEVER rewrite swagger_doc.json. The file grows with every @create-api
+call. A full rewrite risks losing manually added documentation,
+custom schema definitions, or endpoint notes that developers added
+outside the agent.
+
+The only permitted operation in Mode 2 is:
+1. Read the file into memory as a parsed JSON object
+2. Check if the path key already exists in `paths`
+   - If it exists → do not overwrite it. Log:
+     "Path [method] [path] already exists in swagger_doc.json.
+     Skipping to avoid overwriting existing documentation."
+   - If it does not exist → add the new path key and operation object
+3. Write the updated JSON object back to the file with 2-space
+   indentation (preserving formatting consistency)
+4. Never sort or reformat existing keys — preserve their order
+
+The only change to the file is the addition of one new key in the
+`paths` object. Everything else remains byte-for-byte identical.
+
+### Operation Object Structure
+
+**summary**:
+From `context.current_api.description`.
+
+**tags**:
+Array with one entry: `context.current_api.module_name`.
+Tags group endpoints by module in the Swagger UI.
+
+**security**:
+Determined by `context.current_api.requires_auth`:
+- `"full"` → `[{ "ApiKeyAuth": [] }, { "TokenAuth": [] }]`
+- `"api_key_only"` → `[{ "ApiKeyAuth": [] }]`
+- `"none"` → `[]` (empty array — no security on this endpoint)
+
+**parameters** (for GET and DELETE routes):
+If the route path contains `{param}` variables — add a parameters
+array. For each path parameter:
+```json
+{
+  "name": "",
+  "in": "path",
+  "required": true,
+  "schema": { "type": "integer" }
+}
+```
+For query parameters — agent reads `context.current_api.primary_table`
+columns from `context.db.schema` to suggest relevant query params.
+Common ones: `page`, `limit`, `search`. Add as `"in": "query"`,
+`"required": false`.
+
+**requestBody** (for POST, PUT, PATCH routes only):
+```json
+{
+  "required": true,
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "properties": {}
+      }
+    }
+  }
+}
+```
+Agent reads `context.current_api.primary_table` columns from
+`context.db.schema` to populate the `properties` object with the
+relevant columns for this operation. Exclude system columns: `id`,
+`created_at`, `is_deleted`, `status`. Include columns appropriate
+for the HTTP method (e.g. POST includes all required fields, PUT/PATCH
+includes updatable fields only).
+
+If `encrypted_transport == true` — change the schema to:
+```json
+{
+  "type": "string",
+  "description": "AES-256-CBC encrypted JSON payload"
+}
+```
+Because the body is a cipher string, not a JSON object.
+
+**responses**:
+Always include these three response codes:
+
+`"200"`:
+```json
+{
+  "description": "Successful operation",
+  "content": {
+    "application/json": {
+      "schema": { "$ref": "#/components/schemas/SuccessResponse" }
+    }
+  }
+}
+```
+
+`"401"`:
+```json
+{
+  "description": "Unauthorized",
+  "content": {
+    "application/json": {
+      "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" }
+    }
+  }
+}
+```
+
+`"200"` for validation failure (separate from success — same HTTP code
+but different application code):
+Add a note in the `"200"` response description:
+`"Returns code 1 on success, code 0 on validation/business failure"`
+
+---
+
+## File Location
+
+Always: `<service_name>/document/v1/swagger_doc.json`
+
+The `document/v1/` folder is created during `@initialize-project`.
+The file is created in Mode 1 and updated in Mode 2.
+
+---
+
+## Export
+
+This is a JSON file. No module.exports. Read and written by the agent
+using file system operations.
+
+---
+
+## What This File Does NOT Do
+
+- Does not serve the Swagger UI — that requires a separate route
+  using `swagger-ui-express`. Adding a Swagger UI route is out of
+  scope for scaffolding — developer adds it manually when needed.
+- Does not validate requests at runtime — it is documentation only
+- Does not auto-generate from code — the agent writes it from context
+- Does not include deprecated endpoints — only active routes

package/tasks/generate-tbl-user-deviceinfo.task.md

@@ -0,0 +1,75 @@
+---
+type: task
+name: generate-tbl-user-deviceinfo
+agent: database-agent
+---
+
+# File: <repo_root>/database/<db_type>/migrations/1-setup-tbl-user-deviceinfo.sql
+
+## Path Note
+This file is generated at the REPOSITORY ROOT database directory,
+not inside the service folder. The full path relative to repo root is:
+`database/<db_type>/migrations/1-setup-tbl-user-deviceinfo.sql`
+
+## Purpose
+Generates the default system table required by every NodeJS service.
+This table stores device information and the JWT token per user per
+user_type. It is the foundation of the session management system used
+by common.generateSessionCode and validateToken. Always generated as
+migration file number 1.
+
+## Table Name
+`tbl_user_deviceinfo`
+
+## Columns
+
+Follow all database-agent naming and type conventions exactly.
+
+- `id` — bigint GENERATED ALWAYS AS IDENTITY, PRIMARY KEY
+- `user_id` — BIGINT NOT NULL DEFAULT 0. Foreign key reference to the
+  users table conceptually, but no hard FK constraint — services may
+  have multiple user types.
+- `user_type` — VARCHAR(32) NOT NULL DEFAULT ''. The user role or type
+  string. Combined with user_id forms the unique session key.
+- `token` — TEXT NOT NULL DEFAULT ''. The signed JWT token string.
+  TEXT because JWT tokens are long.
+- `version` — BIGINT NOT NULL DEFAULT 0. The current session version
+  for this user/type combination. Must match the version stored in
+  Redis and the version inside the JWT payload for validateToken to
+  pass.
+- `uuid` — VARCHAR(255) NOT NULL DEFAULT ''. Device UUID.
+- `ip` — VARCHAR(45) NOT NULL DEFAULT ''. Client IP address.
+  VARCHAR(45) to support IPv6.
+- `os_version` — VARCHAR(64) NOT NULL DEFAULT ''. Operating system
+  version string.
+- `model_name` — VARCHAR(128) NOT NULL DEFAULT ''. Device model name.
+- `device_type` — VARCHAR(32) NOT NULL DEFAULT ''. Platform identifier
+  e.g. "ios", "android", "web".
+- `device_token` — TEXT NOT NULL DEFAULT ''. FCM or APNs push
+  notification token. TEXT because push tokens are long.
+- `is_deleted` — BOOLEAN NOT NULL DEFAULT FALSE
+- `created_at` — TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+
+## Indexes
+
+- `idx_user_deviceinfo_user_id` ON (user_id)
+- `idx_user_deviceinfo_user_id_user_type` ON (user_id, user_type)
+  — compound index. Most queries filter by both columns together.
+
+## File Number
+Always 1. This is always the first migration file in any NodeJS service.
+
+## Database Type Handling
+Generate SQL syntax appropriate for `context.db.type`:
+- postgresql → use BIGINT GENERATED ALWAYS AS IDENTITY, TIMESTAMPTZ,
+  BOOLEAN, TEXT, parameterized queries with $1 style
+- mysql → use BIGINT AUTO_INCREMENT, DATETIME DEFAULT CURRENT_TIMESTAMP,
+  TINYINT(1) for boolean, parameterized queries with ? style
+- mongodb → generate a Mongoose schema file instead of SQL, placed in
+  database/mongodb/schemas/userDeviceinfo.schema.js
+
+## After Generation
+- Update `<repo_root>/database/<db_type>/create-schema.sql` to
+  include this file as the first \i entry
+- Update `context.db.schema.tables` with this table's full definition
+- Append to `context.db.schema.change_log`

package/tasks/generate-template.task.md

@@ -0,0 +1,129 @@
+---
+type: task
+name: generate-template
+agent: nodejs-agent
+---
+
+# File: config/template.js
+
+## Purpose
+Defines HTML email template functions for all transactional emails sent
+by the service. Each template is a function that accepts a data object
+and a callback. The callback is called with the complete HTML string.
+All templates use GLOBALS from constants.js for branding values like
+APP_NAME, LOGO, BASE_URL, and legal links. Templates are professional,
+fully responsive, and styled for modern email clients.
+
+---
+
+## Dependencies to Import
+
+- `./constants` — imported as `GLOBALS`. Used for APP_NAME, LOGO,
+  BASE_URL, UNSUBSCRIBE, TERMS_OF_USE, and PRIVACY_POLICY in all
+  templates.
+
+---
+
+## Template Structure Rules
+
+Every template function follows this exact signature:
+`exports.<templateName> = function(result, callback)`
+
+Where:
+- `result` — plain object containing the dynamic values specific to
+  this email (name, OTP, link, etc.)
+- `callback` — function called with the complete HTML string as its
+  only argument: `callback(htmlString)`
+
+The HTML structure for every template must follow this layout order:
+1. Full HTML document with DOCTYPE, head, viewport meta, and inline CSS
+2. Email container centered at max-width 600px
+3. Header section — dark background, logo image from `GLOBALS.LOGO`
+4. Body section — main content area with the email message
+5. Footer section — unsubscribe link, legal links, sent-to address
+
+The CSS must be fully inlined or in a style block in head. No external
+stylesheets. Use a professional color scheme derived from the project —
+the agent reads `context.project_info.from_figma.color_theme` if
+available, otherwise uses a professional neutral dark/light scheme.
+Font: use a Google Fonts import for a clean sans-serif such as Lato
+or Inter with a fallback stack.
+
+---
+
+## Templates to Generate
+
+---
+
+### exports.welcome(result, callback)
+
+**Purpose**: Sent to a new user immediately after successful registration.
+
+**Dynamic values in result**:
+- `result.first_name` — the user's first name for the greeting
+- `result.email` — the user's email address, shown in the footer
+
+**Content**:
+Header: APP_NAME logo
+Body:
+- Greeting: "Hello [first_name]!"
+- Welcome message thanking the user for joining APP_NAME
+- A brief description of what the platform offers (agent uses
+  `context.project_info.summary` to write one relevant sentence here)
+- A closing line encouraging the user to explore the platform
+- "Thank You!" sign-off
+
+Footer:
+- "This message was sent to [email]"
+- Unsubscribe link using `GLOBALS.UNSUBSCRIBE`
+- Terms of use and privacy policy links
+
+---
+
+### exports.forgotPassword(result, callback)
+
+**Purpose**: Sent when a user requests a password reset OTP.
+
+**Dynamic values in result**:
+- `result.first_name` — user's first name
+- `result.otp_code` — the generated OTP code to display
+- `result.email` — shown in footer
+- `result.encoded_user_id` — appended to the unsubscribe URL
+
+**Content**:
+Header: APP_NAME logo
+Body:
+- Greeting: "Hello [first_name]!"
+- Explanation that they requested a verification code
+- The OTP displayed prominently in a centered block, bold, large text
+- Instruction to use this code to reset their password
+- Note that this code expires (agent adds a sensible expiry note)
+- "Thank You!" sign-off
+
+Footer:
+- Sent-to address with the user's email
+- Unsubscribe link with encoded_user_id appended
+
+---
+
+## Email Client Compatibility Requirements
+
+All templates must include:
+- `xmlns` attributes on the html element for Outlook compatibility
+- `border="0" cellspacing="0" cellpadding="0"` on all table elements
+- `width="100%"` on outer tables
+- Inline width constraints on inner divs for Gmail compatibility
+- `@media` queries for mobile breakpoints at 320px, 375px, and 414px
+- `content-type` meta for IE compatibility
+- Apple mail data detector disabling via CSS
+
+---
+
+## What This File Does NOT Do
+
+- Does not send emails — sending is done in `utilities/notification.js`
+- Does not import nodemailer or any mail transport
+- Does not generate plain text versions — HTML only
+- Does not validate the result object — assumes caller provides correct
+  fields
+- Does not use external template engines like Handlebars or EJS