codeninja 2.0.0

package/tasks/generate-language-en.task.md

@@ -0,0 +1,155 @@
+---
+type: task
+name: generate-language-en
+agent: nodejs-agent
+---
+
+# File: languages/en.js
+
+## Purpose
+The base English language file. Defines all message keys used across
+the entire service as a flat key-value object. Every other language file
+mirrors this exact set of keys with translated values. This file is the
+single source of truth for all message keys — if a key exists anywhere
+in the codebase, it must be defined here.
+
+The file is divided into clearly separated sections by comment headers.
+Keys are never sorted alphabetically — they are grouped by functional
+area. This makes it easy to find and add related messages together.
+
+---
+
+## Structure and Sections
+
+### Section 1 — Validator Messages
+These keys are used by validatorjs as custom error message overrides.
+The `:attr` placeholder is replaced by the field name at runtime by
+validatorjs. These must exactly match the validatorjs rule names.
+
+Keys to include:
+- `"accepted"` — "The :attr must be accepted"
+- `"email"` — "The :attr must be a valid email address"
+- `"exists"` — "The selected :attr is invalid"
+- `"in"` — "The selected :attr is invalid"
+- `"integer"` — "The :attr must be an integer"
+- `"numeric"` — "The :attr must be a number"
+- `"required"` — "The :attr field is required"
+- `"required_if"` — "The :attr field is required when :other is :value"
+- `"required_unless"` — "The :attr field is required unless :other is
+  in :values"
+- `"min"` — "The :attr must be at least :min characters"
+- `"max"` — "The :attr may not be greater than :max characters"
+- `"string"` — "The :attr must be a string"
+- `"boolean"` — "The :attr must be true or false"
+
+---
+
+### Section 2 — System / Infrastructure Messages
+These keys are used by headerValidator, response, rateLimiter, and
+other infrastructure files. They are never used by module-level business
+logic.
+
+Keys to include:
+- `"rest_keywords_invalid_api_key"` — "Invalid API key"
+- `"rest_keywords_tokeninvalid"` — "Invalid token provided"
+- `"rest_keywords_decryption_failure"` — "Something went wrong, invalid
+  encrypted payload received"
+- `"rest_keywords_rate_limit_exceeded"` — "Too many requests. Please
+  try again later."
+- `"rest_keywords_invalidparam"` — "Invalid parameters provided"
+- `"rest_keywords_something_went_wrong"` — "Oops! Something went wrong"
+
+---
+
+### Section 3 — Common Response Messages
+These keys are used across multiple modules for standard success and
+failure responses.
+
+Keys to include:
+- `"rest_keywords_success"` — "Success!"
+- `"rest_keywords_nodata"` — "No data found!"
+- `"rest_keywords_no_data_found"` — "No data found"
+- `"rest_keywords_api_no_data"` — "No data found"
+- `"rest_keywords_invalid_details"` — "Please enter valid details"
+- `"rest_keywords_uploadfail"` — "Failed to upload image"
+- `"rest_keywords_image_success"` — "Image uploaded successfully"
+
+---
+
+### Section 4 — Authentication Messages
+These keys are used by the Auth module — login, logout, registration,
+password reset flows.
+
+Keys to include:
+- `"rest_keywords_login_success"` — "Logged in successfully"
+- `"rest_keywords_invalid_logindetails"` — "Please enter valid login
+  credentials"
+- `"rest_keywords_account_inactivated"` — "Your account has been
+  inactivated by admin, please contact admin for more details"
+- `"rest_keywords_invalid_email"` — "Please enter valid email"
+- `"rest_keywords_invalid_password"` — "Your password is incorrect,
+  please enter valid password"
+- `"rest_keywords_userlogout_success"` — "Signed out successfully"
+- `"rest_keywords_userdetails_missing"` — "Something went wrong, user
+  details missing"
+- `"rest_keywords_same_password_cant_besent"` — "You cannot set the
+  same password"
+- `"rest_keywords_password_reset_success"` — "Password reset
+  successfully"
+- `"rest_keywords_verification_sent_success"` — "Verification code sent
+  successfully"
+- `"rest_keywords_failed_sending_verification_code"` — "Something went
+  wrong sending verification code, please try again"
+
+---
+
+### Section 5 — Push Notification Messages
+These keys are used by `utilities/notification.js` for push notification
+body text. The `{symbol}` and similar placeholders in values are
+localizify interpolation tokens — replaced at runtime with actual values.
+
+Keys to include:
+- `"opportunity_success"` — "New opportunity available on {symbol}!
+  Please check the app for more details."
+
+---
+
+## File Format
+
+The file exports a plain `let messages` object (not const — to allow
+future reassignment patterns in other language files that extend from
+this one). The variable is named `messages`. The module.exports line
+at the bottom exports it directly.
+
+Format:
+```
+let messages = {
+  // Section comment header
+  "key": "value",
+  ...
+};
+module.exports = messages;
+```
+
+---
+
+## Rules for All Language Files (applies to ar.js, fr.js etc.)
+
+When agent generates additional language files for other supported
+languages:
+- Copy the exact same set of keys from en.js
+- Translate only the values — never the keys
+- Keep the same section structure and comment headers
+- Keys that cannot be translated (technical placeholders like `:attr`,
+  `{symbol}`) must be preserved exactly as they appear in the English
+  value
+- The file is otherwise identical in structure to en.js
+
+---
+
+## What This File Does NOT Do
+
+- Does not import anything
+- Does not contain any functions or logic
+- Does not define route paths, status codes, or configuration values
+- Does not use template literals — all values are plain strings

package/tasks/generate-logging.task.md

@@ -0,0 +1,257 @@
+---
+type: task
+name: generate-logging
+agent: nodejs-agent
+---
+
+# File: logger/logging.js
+
+## Purpose
+Custom file-based logger for the service. Every other file in the service
+imports this module and calls its level functions directly. No third-party
+logging library is used — this is a pure Node.js implementation using fs,
+path, and moment. It writes structured JSON log entries simultaneously to
+the console and to a daily rotating log file. It auto-deletes files older
+than 10 days.
+
+---
+
+## Dependencies to Import
+
+- `fs` — Node.js built-in. Used for file existence checks, directory
+  creation, appending log entries, reading directory contents, and
+  deleting old files.
+- `path` — Node.js built-in. Used to construct absolute file paths for
+  the logs directory and individual log files.
+- `moment` — third-party. Used for all date/time formatting. All
+  operations use UTC via `moment.utc()` — never local time.
+
+---
+
+## Module-Level Definitions
+
+### levels
+A plain object that maps each log level name to its numeric severity value.
+The defined levels in ascending severity order are:
+- `debug` → 10
+- `info` → 20
+- `warning` → 30
+- `error` → 40
+- `critical` → 50
+- `alert` → 60
+
+These numeric values are stored in every log entry alongside the level
+name string. This allows log consumers and analysis tools to filter by
+numeric threshold without string comparison.
+
+---
+
+## Internal Functions (not exported)
+
+---
+
+### getLogFileName()
+
+**Purpose**: Returns the filename string for today's log file.
+
+**Flow**:
+1. Get the current UTC date using `moment.utc()`.
+2. Format it as `YYYY-MM-DD`.
+3. Return the string `<formatted_date>.log.json`.
+   Example return value: `2026-03-16.log.json`
+
+This function is called on every write — it always reflects the current
+UTC date at the time of the log call, not the date when the module loaded.
+This ensures that log entries written after midnight go into the new day's
+file automatically without any restart.
+
+---
+
+### ensureLogsDir()
+
+**Purpose**: Guarantees the `logs/` directory exists before any file
+write is attempted. Returns the absolute path to the logs directory.
+
+**Flow**:
+1. Construct the absolute path to the logs directory using `path.join`
+   with `__dirname` and the string `'logs'`. The logs directory sits
+   inside the same directory as `logging.js` itself — which is `logger/`.
+   So the final path resolves to `<service_root>/logger/logs/`.
+2. Check if the directory exists using `fs.existsSync`.
+3. If it does not exist — create it using `fs.mkdirSync` with the option
+   `{ recursive: true }`. The recursive option ensures no error is thrown
+   if a parent directory is also missing.
+4. Return the absolute path string.
+
+---
+
+### logToFile(logEntry)
+
+**Purpose**: Writes a single log entry object to the current day's log
+file. Triggers old file cleanup when a new file is created for the day.
+
+**Parameters**:
+- `logEntry` — a plain object representing one log entry. Already fully
+  formed by `doLog` before being passed here.
+
+**Flow**:
+1. Call `ensureLogsDir()` to get the logs directory path.
+2. Call `getLogFileName()` to get today's filename.
+3. Construct the full file path by joining the directory and filename.
+4. Check if the file already exists using `fs.existsSync`. Store the
+   result as `isNewFile` — true if the file does not yet exist.
+5. Append the log entry to the file using `fs.appendFileSync`.
+   The format is: `JSON.stringify(logEntry)` followed by a newline
+   character `\n`. Encoding is `utf8`.
+   Using `appendFileSync` means each log entry is one line. The file is
+   a newline-delimited JSON file (NDJSON format) — one JSON object per
+   line, not a JSON array.
+6. If `isNewFile` is true — call `cleanOldLogs(logsDir)`. Old log
+   cleanup only runs when a new daily file is first created, not on
+   every write. This avoids the performance cost of scanning the
+   directory on every single log call.
+7. Wrap the entire function body in a try/catch. On any error — write
+   to `console.error` with two lines: one describing the write failure
+   and one dumping the failed log entry. This is the last-resort fallback.
+   The logger must never throw or crash the application.
+
+---
+
+### doLog(levelName, loggerData, message, data)
+
+**Purpose**: Core formatter and dispatcher. Normalizes the input,
+builds the structured log entry object, writes to console, and writes
+to file.
+
+**Parameters**:
+- `levelName` — string key from the levels object. e.g. `"info"`,
+  `"error"`.
+- `loggerData` — plain object of static context fields bound to this
+  logger instance. Spread into every entry this logger produces.
+  For the default logger this is an empty object.
+- `message` — string describing what happened.
+- `data` — additional context object. Defaults to empty object if not
+  provided.
+
+**Flow**:
+1. Normalize the `data` parameter:
+   - If `data` itself is an instance of `Error` — replace it with
+     `{ error: data }` so it becomes a keyed object.
+   - If `data.error` exists and is an instance of `Error` — replace
+     `data.error` with a plain object containing two keys:
+     `message` (the error's message string) and `stack` (the error's
+     stack trace string). This serializes the Error object since
+     `JSON.stringify` on a raw Error produces `{}`.
+
+2. Build the log entry object by spreading in this exact order:
+   - `time`: current UTC datetime formatted as `YYYY-MM-DD HH:mm:ss`
+     using `moment.utc()`.
+   - `level`: the numeric value from the levels object for this levelName.
+   - `levelName`: the string level name.
+   - All keys from `loggerData` spread in (static context fields).
+   - `message`: the message string.
+   - All keys from `data` spread in (dynamic context fields).
+   The spread order means that `data` keys can technically overwrite
+   `loggerData` keys if they share the same name. This is intentional —
+   per-call context takes priority over instance-level context.
+
+3. Write the entry to console: call `console.log` with
+   `JSON.stringify(logEntry)`. This produces a single-line JSON string
+   on stdout. This happens on every log call regardless of level —
+   there is no console level filtering.
+
+4. Call `logToFile(logEntry)` to write to the file.
+
+---
+
+### cleanOldLogs(logsDir)
+
+**Purpose**: Scans the logs directory and deletes any log files that are
+older than 10 days from the current UTC date.
+
+**Parameters**:
+- `logsDir` — absolute path string to the logs directory.
+
+**Flow**:
+1. Read all filenames in the directory using `fs.readdirSync`. This
+   returns an array of filename strings.
+2. Calculate the cutoff date: `moment.utc().subtract(10, 'days')`. Store
+   as `tenDaysAgo`.
+3. For each filename in the array:
+   a. Check if the filename ends with `.log.json`. Skip any file that
+      does not match — never delete non-log files from this directory.
+   b. Extract the date portion of the filename by splitting on `.log.json`
+      and taking the first segment. This gives the `YYYY-MM-DD` date
+      string.
+   c. Parse the date string using `moment.utc(datePart, 'YYYY-MM-DD')`.
+   d. If the parsed date is before `tenDaysAgo` using `.isBefore()` —
+      delete the file using `fs.unlinkSync` with the full path.
+   e. Wrap the delete in a try/catch. On failure — write to
+      `console.error` with the filename. Never throw. A failed delete
+      of an old log file must not affect anything else.
+
+---
+
+## Logger Factory Function
+
+### Logger(loggerData)
+
+**Purpose**: Factory function that creates a logger instance. Each instance
+is a plain object where every key is a level name and every value is a
+function that logs at that level. The `loggerData` parameter allows creating
+named or contextualized sub-loggers, though the default export uses an
+empty context.
+
+**Parameters**:
+- `loggerData` — plain object. Default is empty object `{}`. Any keys
+  provided here are spread into every log entry produced by this instance.
+  Useful for adding a `module` or `service` field to all entries from a
+  specific context.
+
+**Flow**:
+1. Use `Object.keys(levels)` to get all level name strings.
+2. Use `Object.fromEntries` combined with `.map` to build an object where:
+   - Each key is a level name string (e.g. `"info"`, `"error"`).
+   - Each value is a function that accepts `(message, data = {})` and
+     calls `doLog(levelName, loggerData, message, data)`.
+3. Return the resulting object.
+
+The returned object has exactly these callable methods:
+`debug(message, data)`, `info(message, data)`, `warning(message, data)`,
+`error(message, data)`, `critical(message, data)`, `alert(message, data)`.
+
+All parameters for all methods follow the same pattern:
+- `message` — required string describing the event.
+- `data` — optional plain object with additional context. Defaults to
+  empty object if not provided. Can also be an Error instance directly.
+
+---
+
+## Module Export
+```
+const log = Logger();
+module.exports = log;
+```
+
+A single default logger instance is created with empty context and
+exported. Every file in the service imports this same instance.
+The `Logger` factory itself is not exported — only the instance.
+
+This means all files share one logger with no per-file context fields.
+If a future need arises for per-module logging context, `Logger` can
+be exported and instantiated per file — but the default pattern is the
+single shared instance.
+
+---
+
+## What This File Does NOT Do
+
+- Does not use winston, bunyan, pino, or any other logging library
+- Does not filter log entries by level — all levels write to both
+  console and file always
+- Does not support log streaming, remote transports, or webhooks
+- Does not rotate files mid-day — one file per UTC day only
+- Does not compress old log files before deletion
+- Does not read or parse existing log entries — write-only
+- Does not throw under any circumstance — all errors are caught and
+  written to stderr as a last resort

package/tasks/generate-model.task.md

@@ -0,0 +1,180 @@
+---
+type: task
+name: generate-model
+agent: nodejs-agent
+---
+
+# File: modules/v1/<ModuleName>/<module>_model.js
+
+## Purpose
+Contains all business logic and all database queries for a single API
+module. No Express objects (req, res, next) exist in this file. Every
+function receives plain parameters and returns a plain object with a
+fixed three-key shape. The route.js file calls these functions and passes
+the results directly to sendResponse.
+
+This file is generated fresh for every `@create-api` command. The agent
+reads `context.current_api` and `context.db.schema` to know the module
+name, primary table, and available columns.
+
+---
+
+## Dependencies to Import
+
+- `../../../config/database` — imported as `con`. Used for all DB
+  queries.
+- `../../../config/constants` — imported as `GLOBALS`. Used for any
+  constants needed in business logic.
+- `../../../config/common` — imported as `common`. Used for generic
+  helpers like createRecords, updateRecords, randomOtpGenerator,
+  generateSessionCode.
+- `../../../config/template` — imported as `template`. Used when this
+  module sends emails.
+- `../../../utilities/notification` — imported as `notification`. Used
+  when this module sends emails, SMS, or push notifications.
+- `../../../utilities/encryption` — imported as `{ encrypt, decrypt }`.
+  Used for password encryption and any field-level encryption. Never
+  use crypto-js or cryptlib directly.
+- `../../../logger/logging` — imported as `log`.
+- `pg-format` — imported as `format`. Used for dynamic query building.
+- `moment` — imported as `moment`. Used for date manipulation and
+  formatting.
+
+Only import what is actually used. During `@initialize-project` when
+generating the default test model, only import `log` and `GLOBALS`.
+
+---
+
+## Return Value Contract
+
+Every function in the model returns a plain object with exactly these
+three keys:
+```
+{
+  responsecode: "1" | "0",
+  responsemsg: { keyword: "...", components: {} },
+  responsedata: <data object> | null
+}
+```
+
+- `responsecode` — string `"1"` for success, string `"0"` for any
+  failure condition including expected business failures (user not found,
+  wrong password, etc.).
+- `responsemsg` — object with `keyword` (translation key string from
+  languages/en.js) and `components` (interpolation object, empty `{}`
+  when no interpolation needed).
+- `responsedata` — the data to return to the client, or `null` when
+  there is nothing to return (e.g. logout, status updates).
+
+This contract is fixed. Route.js destructures exactly these three keys.
+Never return additional keys. Never throw from a model function —
+catch all errors and return the failure shape.
+
+---
+
+## Default Test Function (generated during @initialize-project)
+
+When the model file is first generated as part of
+`@initialize-project`, it contains one default function that the
+default test route in route.js calls.
+
+**Function**: `async getTest(request)`
+
+**Parameters**: `request` — the request object passed from route.js.
+Not used in the default implementation.
+
+Every model function — including the default getTest — must have a
+JSDoc comment block directly above it following the format defined
+in nodejs-agent.md Code Style Standards.
+
+**Flow**:
+1. Log at info level: module name + "getTest called"
+2. Return success shape:
+   - `responsecode`: `"1"`
+   - `responsemsg`: `{ keyword: "rest_keywords_success", components: {} }`
+   - `responsedata`: `{ message: "Module is working correctly", module: "<ModuleName>" }`
+
+---
+
+## Function Pattern for Generated Functions (used by @create-api)
+
+Every function generated by `@create-api` follows this pattern:
+
+### Function signature
+`async <functionName>(request, user_id, user_type)`
+
+- `request` — plain object containing the request data. For GET routes
+  this is query/path params. For POST routes this is the decrypted body.
+- `user_id` — the authenticated user's ID passed from route.js. Always
+  present on protected routes. Use `0` as default for public routes.
+- `user_type` — the authenticated user's type. Always present on
+  protected routes.
+
+### General function flow pattern
+
+1. Log at info level at the start of the function with function name
+   and relevant request fields. Never log passwords or sensitive data.
+
+2. Perform all database operations using `con.query(text, params)` with
+   parameterized queries. Never concatenate user input into query strings.
+   Column names referenced in queries must come from
+   `context.db.schema.tables[primaryTable].columns` — never invented.
+
+3. Build the response data object from query results. Only include
+   fields the client actually needs — never return raw database rows
+   with all columns if only some are needed.
+
+4. Return the three-key response shape on all paths — both success and
+   expected failure. Wrap in try/catch. In the catch block — log at
+   error level with function name and error, then return the failure
+   shape with keyword `rest_keywords_something_went_wrong`.
+
+### Password handling
+When the function receives or stores passwords:
+- For storing: call `encrypt(password)` from utilities/encryption.js.
+  Never store plaintext passwords.
+- For comparing: encrypt the incoming password and compare against the
+  stored encrypted value. Never decrypt stored passwords for comparison.
+
+### Session generation (login/signup)
+When a function completes a successful login or signup:
+- Call `await common.generateSessionCode(user_id, user_type)` to get
+  the JWT token.
+- Include the token in `responsedata`.
+- Never generate JWT tokens directly in the model — always use common.
+
+### Notification sending
+When a function needs to send an email:
+1. Call the relevant template function from `config/template.js` using
+   the callback pattern: `template.<templateName>(data, (html) => { ... })`
+2. Inside the callback, call `notification.sendEmail(to, subject, html)`.
+3. Do not await the notification — fire and forget. Notification failure
+   must never block the API response.
+
+---
+
+## Module Object Name Convention
+
+The model object is named after the module in PascalCase.
+Example: module `Auth` → object named `Auth`.
+Example: module `Products` → object named `Products`.
+
+---
+
+## Export
+```
+module.exports = <ModuleName>
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not import express — no router, no req, no res, no next
+- Does not call sendResponse — returns data, never sends HTTP responses
+- Does not import headerValidator — no middleware in model files
+- Does not call crypto-js or cryptlib directly — uses encryption.js
+- Does not use hardcoded strings for messages — always uses keyword
+  strings that exist in languages/en.js
+- Does not throw — all errors are caught and returned as failure shape
+- Does not invent column names — always reads from context.db.schema