codeninja 2.0.0

package/tasks/generate-validator.task.md

@@ -0,0 +1,122 @@
+---
+type: task
+name: generate-validator
+agent: nodejs-agent
+---
+
+# File: utilities/validator.js
+
+## Purpose
+Provides a single reusable function for validating Express request body
+fields against a set of rules before the model function is called.
+Used inside `route.js` files — called after decryption, before any
+business logic. Returns a boolean so route handlers can exit early on
+invalid input without throwing.
+
+---
+
+## Dependencies to Import
+
+- `validatorjs` — imported as `Validator` (capital V). This is the
+  validation rules engine. Package name: `validatorjs`.
+- `../utilities/response` — imports `sendResponse` to send the validation
+  error response directly from this function
+- `../logger/logging` — imports `log`
+
+---
+
+## Functions
+
+---
+
+### checkValidationRules(req, res, rules, keywords)
+
+**Purpose**: Runs a set of validation rules against `req.body`. If any
+rule fails, sends a 200 response with the first validation error message
+and returns false. If all rules pass, returns true and the route handler
+continues.
+
+**Parameters**:
+- `req` — Express request object. Body fields are read from `req.body`.
+  `req.lang` must be set (by `extractLanguage`) for response translation.
+  `req` is also passed to `sendResponse` for language resolution.
+- `res` — Express response object. Passed to `sendResponse` if validation
+  fails.
+- `rules` — plain object defining validation rules per field.
+  Format follows validatorjs syntax:
+  e.g. `{ email: "required|email", password: "required|min:8" }`
+- `keywords` — plain object mapping rule failure types to translation
+  keyword strings.
+  e.g. `{ "required.email": "rest_keywords_email_required" }`
+  These keywords are resolved via localizify the same way all other
+  messages are resolved. If a keyword mapping is not provided for a
+  specific rule failure, the raw validatorjs error string is used as
+  fallback.
+
+**Flow**:
+
+1. Instantiate the validator:
+   Call `Validator.make(req.body, rules, keywords)`.
+   This creates a validator instance with the body data, rules, and
+   custom message keyword mappings.
+
+2. Call `.fails()` on the validator instance.
+   If it returns false — all rules passed. Log at info level: validation
+   passed. Return `true` immediately.
+
+3. If `.fails()` returns true — validation failed.
+   Call `.getErrors()` on the instance. This returns an object where keys
+   are field names and values are arrays of error message strings.
+   Extract the first error: take the first key from the errors object,
+   take the first string from its array. Store as `firstError`.
+
+4. Log at error level: the field name and first error message.
+
+5. Call `sendResponse` from `utilities/response.js`:
+   - `req` — pass through
+   - `res` — pass through
+   - `statusCode` — `200`. Validation errors always return HTTP 200 with
+     an application-level failure code. This is the established pattern
+     in this codebase.
+   - `responseCode` — `"0"` indicating failure
+   - `messageKeyword` — pass `firstError` directly as the message.
+     Note: unlike other `sendResponse` calls where a keyword is passed
+     and resolved, here the error string from validatorjs may already be
+     a resolved string if the keywords mapping resolved it, or it may be
+     a raw rule description if no mapping was provided. Pass it as-is.
+   - `messageComponents` — `{}`
+   - `responseData` — `null`
+
+6. Return `false` after calling `sendResponse`.
+   The route handler must check the return value and return immediately
+   if false — the response has already been sent.
+
+7. This function is async because `sendResponse` is async. Always await
+   the `sendResponse` call before returning false.
+
+**Usage pattern in route.js** (description only, no code):
+The route handler calls `checkValidationRules` with the rules object.
+It awaits the result. If the result is false, it returns immediately.
+If the result is true, it proceeds to call the model function.
+This means validation is always the first operation inside a route
+handler after decryption.
+
+---
+
+## Export
+```
+module.exports = { checkValidationRules }
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not define validation rules — those are defined inline in each
+  `route.js` file where the context of required fields is known
+- Does not access the database
+- Does not read headers — only reads `req.body`
+- Does not send success responses — only sends failure responses
+  and returns a boolean
+- Does not throw — returns false on validation failure, lets the route
+  handler decide what to do next

package/tasks/show-db-table-summary.task.md

@@ -0,0 +1,66 @@
+---
+type: task
+name: show-db-table-summary
+---
+
+Read all values from `context.current_db` and render a complete preview of
+the table file that will be generated.
+
+Display the exact SQL that will be written — no placeholders, real values:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                   TABLE GENERATION SUMMARY                  │
+├────────────────────────────────────────────────────────────┤
+│ File    : [file_number]-setup-tbl-[table_without_prefix].sql│
+│ Table   : public.[table_name]                               │
+│ Purpose : [table_purpose]                                   │
+└────────────────────────────────────────────────────────────┘
+
+Preview of generated SQL:
+─────────────────────────────────────────────────────────────
+-- Creating [table_name] for [table_purpose]
+DROP TABLE IF EXISTS public.[table_name] CASCADE;
+
+CREATE TABLE public.[table_name] (
+    id bigint NOT NULL GENERATED ALWAYS AS IDENTITY (...),
+    [col_name] [type],
+    [col_name] [type],
+    ...
+    [status if needed]
+    [is_deleted if needed]
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id)
+);
+
+[COMMENT lines for enum columns]
+
+[INDEX lines]
+
+ALTER TABLE public.[table_name] OWNER TO [db_user];
+GRANT ALL ON TABLE public.[table_name] TO [db_user];
+
+[SEED INSERT if applicable]
+─────────────────────────────────────────────────────────────
+
+Indexes to be created:
+  ✓ [index_name] ON ([columns])
+  ...
+
+create-schema.sql will be updated to include:
+  \i [file_number]-setup-tbl-[table_without_prefix].sql
+```
+
+Then ask exactly this question:
+
+"Generate this table? (yes / no / change a value)"
+
+- If yes → proceed to generation
+- If no → abort, nothing created, inform: "No files were created."
+- If change:
+    Ask: "Which value would you like to change?"
+    Options: table name / columns / indexes / seed data / file number
+    Re-run the specific task for that value
+    Return to show-db-table-summary
+
+Do not ask any other question beyond the confirmation.

package/tasks/show-final-summary.task.md

@@ -0,0 +1,108 @@
+---
+type: task
+name: show-final-summary
+---
+
+Read `context` and the list of files generated in the current operation.
+
+Display a summary in this format:
+
+```
+┌─────────────────────────────────────────────┐
+│              OPERATION COMPLETE              │
+└─────────────────────────────────────────────┘
+
+Read `context.last_command` to determine what to show:
+
+If last_command is a @db:* command or @sync:
+  Show only:
+    Context updated:
+      .codeninja/context/context.json ✓
+  Skip all service startup / URL / endpoint lines.
+
+If last_command involves a service (initialize-project, create-api, test, audit):
+  Show full service block:
+    To start the service:
+      cd [service_name]
+      cp .env.example .env
+      (fill in your values in .env before running npm start)
+      npm install
+      npm start
+    Service will run at: ...
+    API base path: ...
+    Demo endpoint: ...
+    Context updated: ...
+
+Service will run at:
+  http://localhost:[port]
+
+API base path:
+  http://localhost:[port]/v1
+
+Demo endpoint:
+  [METHOD] http://localhost:[port]/v1/[first_route_path]
+
+Context updated:
+  .codeninja/context/context.json ✓
+```
+
+If the operation was @initialize-project (any project_type):
+  Show IDE config confirmation block:
+  ─────────────────────────────────────────
+  IDE configuration:
+    .vscode/mcp.json                    ✓  (VS Code — auto-connected)
+    .cursor/mcp.json                    ✓  (Cursor — auto-connected)
+    ~/.gemini/antigravity/mcp_config    ✓  (Antigravity — auto-configured)
+    Claude Desktop                      →  see snippet printed above (manual step)
+
+  VS Code / Cursor: reopen this project to activate.
+  Antigravity: go to ... → MCP Servers → Manage MCP Servers → Refresh.
+  ─────────────────────────────────────────
+
+If the operation was @initialize-project and project_type == nodejs:
+  Show Redis setup instructions:
+  ─────────────────────────────────────────
+  Redis setup (run before starting the service):
+
+  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)
+  ─────────────────────────────────────────
+
+If the operation was @initialize-project and project_type == reactjs:
+  Show frontend startup instructions:
+  ─────────────────────────────────────────
+  To start the frontend:
+    cd [service_name]
+    cp .env.example .env
+    npm install
+    npm start
+
+  App will run at: http://localhost:3000
+  Make sure your linked backend ([linked_service]) is also running.
+  ─────────────────────────────────────────
+
+If the operation was @sync, show the sync report instead:
+```
+@sync complete
+─────────────────────────────────────────
+Services synced    : [n]
+Routes discovered  : [n] ([x] new)
+DB tables synced   : [n] ([x] new)
+Context gaps filled: [n]
+Unchanged          : [n]
+─────────────────────────────────────────
+Drift Analysis     : [✓ Clean / ⚠ [n] files with drift]
+─────────────────────────────────────────
+[Drift details shown below if any found]
+```
+
+After displaying the summary, ask exactly this question:
+
+"What would you like to do next?"
+
+Present options relevant to what was just done:
+- If @initialize-project → offer @create-api, @design, @sync
+- If @create-api → offer @create-api again, @test, @audit
+- If @sync → offer @create-api, @design, @audit

package/tasks/show-init-summary.task.md

@@ -0,0 +1,257 @@
+---
+type: task
+name: show-init-summary
+---
+
+## Purpose
+Display all collected initialization values, run a pre-generation
+validation pass, show the generation plan, then ask for confirmation.
+This is the last checkpoint before any file is created.
+
+---
+
+## Step 1 — Run Pre-generation Validation
+
+Before displaying anything, run all validation checks silently.
+Collect all issues into a list. Categorize each as BLOCKER or WARNING.
+
+### Validation Checks
+
+The checks that apply depend on `context.current_init.project_type`.
+
+#### BLOCKER — Service name conflict (all project types)
+Check: `context.current_init.service_name` exists as a key in
+`context.services`.
+If yes → BLOCKER:
+"Service name '[name]' already exists. You must choose a different name."
+
+#### BLOCKER — Port conflict (all project types)
+Check: `context.current_init.port` matches any port value in
+`context.services`.
+If yes → BLOCKER:
+"Port [port] is already used by service '[service_name]'.
+You must choose a different port."
+
+#### BLOCKER — Encryption key length (nodejs only — skip for reactjs)
+Check: `context.current_init.encryption_key` is exactly 32 characters.
+If not → BLOCKER:
+"Encryption key is [n] characters. AES-256 requires exactly 32."
+
+#### BLOCKER — Encryption IV length (nodejs only — skip for reactjs)
+Check: `context.current_init.encryption_iv` is exactly 16 characters.
+If not → BLOCKER:
+"Encryption IV is [n] characters. AES-256-CBC requires exactly 16."
+
+#### BLOCKER — Encryption key contains spaces (nodejs only — skip for reactjs)
+Check: `context.current_init.encryption_key` has no whitespace.
+If spaces found → BLOCKER:
+"Encryption key contains spaces. This will break AES-256 encryption."
+
+#### BLOCKER — Required fields missing
+For nodejs: check service_name, description, encryption_key,
+encryption_iv, api_key are all non-empty.
+For reactjs: check service_name, description, linked_service are
+all non-empty. Do NOT check encryption_key/iv/api_key — these are
+inherited and their presence is guaranteed by ask-linked-service.
+For database-only: check only service_name and description.
+For each missing field → BLOCKER:
+"Required value '[field_name]' is missing. Cannot generate."
+
+#### BLOCKER — No linked service (reactjs only)
+Check: `context.current_init.linked_service` exists and is non-empty.
+Check: the linked service exists in `context.services` as a nodejs type.
+If missing or not found → BLOCKER:
+"No linked backend service set. Run ask-linked-service to select one."
+
+#### WARNING — DB name matches existing context.db.name (nodejs only)
+Check: `context.current_init.project_type == "nodejs"` AND
+`context.db.name` already exists in context AND
+the value matches what was just collected.
+This is not an error — it means this service will share the existing
+database. Show:
+"Note: This service will connect to existing database '[db_name]'."
+
+#### WARNING — Port is below 1024 (all project types)
+Check: `context.current_init.port` is less than 1024.
+If yes → WARNING:
+"Port [port] is below 1024 (reserved range). Consider using 1024
+or higher."
+
+#### WARNING — Service name contains uppercase (all project types)
+Check: `context.current_init.service_name` has no uppercase letters.
+If found → WARNING:
+"Service name '[name]' contains uppercase. Convention is lowercase only."
+
+#### WARNING — Author is empty (fast mode, nodejs only)
+Check: `context.current_init.init_mode == "fast"` AND
+`context.current_init.project_type == "nodejs"` AND
+`context.current_init.author` is empty string.
+Show:
+"Author is blank. You can update package.json manually after generation."
+
+---
+
+## Step 2 — If BLOCKERs exist, show them before the summary
+
+If any BLOCKER was found:
+
+Display this before the summary box:
+```
+┌──────────────────────────────────────────────┐
+│          ⛔ CANNOT GENERATE — FIX REQUIRED   │
+├──────────────────────────────────────────────┤
+│ [BLOCKER 1 message]                          │
+│ [BLOCKER 2 message if any]                   │
+└──────────────────────────────────────────────┘
+```
+
+Then ask:
+"Which value would you like to fix?"
+
+List only the fields with BLOCKERs as options.
+Re-run the specific ask-* task for the selected field.
+Return to show-init-summary after the fix.
+
+Do NOT show the full summary box or the confirm question until all
+BLOCKERs are resolved. There is nothing to confirm if the config
+is invalid.
+
+---
+
+## Step 3 — Display the Full Summary
+
+Once no BLOCKERs remain, display the summary box.
+
+The format depends on `context.current_init.project_type`:
+
+### If project_type == "nodejs" or "database-only":
+```
+┌──────────────────────────────────────────────┐
+│           INITIALIZATION SUMMARY             │
+├──────────────────────────────────────────────┤
+│ Setup mode     : [Fast / Manual]             │
+│ Project type   : [project_type]              │
+│ Service name   : [service_name]              │
+│ Port           : [port]              [* if auto] │
+│ Description    : [description]               │
+├──────────────────────────────────────────────┤
+│ DATABASE                                     │
+│ Type           : [db.type]                   │
+│ Name           : [db.name]                   │
+│ Host           : [db.host]:[db.port]         │
+│ User           : [db.user]                   │
+├──────────────────────────────────────────────┤
+│ PACKAGE                                      │
+│ Name           : [package_name]      [* if auto] │
+│ Author         : [author]                    │
+├──────────────────────────────────────────────┤
+│ RUNTIME CONFIG                               │
+│ API Key        : [first 8 chars]...  [* if auto] │
+│ Encryption Key : [first 8 chars]...  [* if auto] │
+│ Encryption IV  : [first 8 chars]...  [* if auto] │
+│ Redis          : [redis_host]:[redis_port]   │
+│ Client type    : [client_type]               │
+│ Enc. transport : [Yes / No]                  │
+│ Languages      : [en, ar, ...]               │
+└──────────────────────────────────────────────┘
+```
+
+### If project_type == "reactjs":
+```
+┌──────────────────────────────────────────────┐
+│           INITIALIZATION SUMMARY             │
+├──────────────────────────────────────────────┤
+│ Setup mode     : [Fast / Manual]             │
+│ Project type   : ReactJS Frontend            │
+│ Service name   : [service_name]              │
+│ Port           : [port]              [* if auto] │
+│ Description    : [description]               │
+├──────────────────────────────────────────────┤
+│ BACKEND LINK                                 │
+│ Linked service : [linked_service]            │
+│ API Base URL   : http://localhost:[port]/api/v1/ │
+├──────────────────────────────────────────────┤
+│ INHERITED CONFIG (from [linked_service])     │
+│ API Key        : [first 8 chars]...  [inherited] │
+│ Encryption Key : [first 8 chars]...  [inherited] │
+│ Encryption IV  : [first 8 chars]...  [inherited] │
+└──────────────────────────────────────────────┘
+```
+
+Note: For reactjs, the inherited config values cannot be changed here.
+They are owned by the linked backend service. To change them, update
+the backend service and re-run @initialize-project for this frontend.
+
+Note: Never display full API key or encryption values — show only
+first 8 characters followed by ...
+
+If init_mode == "fast" AND project_type == "nodejs": Show this note below the box:
+"⚡ Values marked * were auto-generated and are production-safe.
+Encryption IV is derived from the first 16 characters of your
+Encryption Key. Select 'change a value' to override any of them."
+
+If project_type == "reactjs": Show this note below the box:
+"🔗 Config marked [inherited] is owned by the linked backend service
+and cannot be changed here."
+
+---
+
+## Step 4 — Show Warnings (if any)
+
+If any WARNINGs exist, show them below the summary box:
+```
+⚠ Warnings (non-blocking):
+  - [WARNING 1 message]
+  - [WARNING 2 message if any]
+```
+
+Warnings do not block confirmation. They are informational only.
+
+---
+
+## Step 5 — Show Generation Plan
+
+Show the wave structure below the warnings.
+
+### If project_type == "nodejs":
+```
+Generation plan (5 waves):
+  Wave 1 — Foundation     : package.json, .env, .gitignore, README,
+                             constants, template, logging, encryption,
+                             language files, enc_dec, directories
+  Wave 2 — Infrastructure : database, ioRedis, response
+  Wave 3 — Service layer  : common, validator, notification, rateLimiter
+  Wave 4 — Middleware     : headerValidator, route, model, swagger
+  Wave 5 — Orchestration  : route_manager, app
+  Total: 26 files across 5 waves
+```
+
+### If project_type == "reactjs":
+```
+Generation plan (3 waves):
+  Wave 1 — Foundation : package.json, .env, .gitignore, README,
+                         public/index.html, style.css, .htaccess files
+  Wave 2 — API Layer  : src/api/apiClient.js, src/api/apiHandler.js
+  Wave 3 — App Shell  : src/App.jsx, src/index.jsx,
+                         src/pages/Welcome/, src/components/
+  Total: 13 files across 3 waves
+```
+
+---
+
+## Step 6 — Ask for Confirmation
+
+Ask exactly this question:
+
+"Confirm and generate all files? (yes / no / change a value)"
+
+- If yes → proceed to scaffold phase immediately
+- If no → abort. Inform: "Nothing was created. Run @initialize-project
+  to start again."
+- If change → ask: "Which value would you like to change?"
+  List all configurable fields with their current values.
+  Re-run the specific ask-* task for the selected field.
+  Return to Step 1 (re-run validation) → then back to Step 3.
+  Note: always re-run validation after any change — a fix to one
+  field could introduce a new conflict (e.g. changing port to a
+  value that is also taken).