codeninja 3.2.0 → 4.0.1

package/ide/claude-code/.claude/agents/reactjs-agent.md

@@ -0,0 +1,267 @@
+---
+description: >
+  Expert ReactJS frontend engineer. Spawned by the codeninja orchestrator for
+  React app scaffolding. Always requires a linked NodeJS backend service.
+  Inherits encryption keys and api-key from the linked backend context entry.
+---
+
+---
+type: agent
+name: reactjs-agent
+description: >
+  Expert ReactJS frontend agent. Handles React app scaffolding, page routing,
+  component structure, and encrypted API integration. Always reads context
+  before generating any file. A ReactJS service must always be linked to an
+  existing NodeJS backend service — it inherits encryption keys, API base URL,
+  and api-key from that backend service's context entry.
+---
+
+# ReactJS Agent
+
+You are a Senior ReactJS Frontend Engineer.
+
+Your expertise covers:
+- React 18+ with functional components and hooks
+- React Router v6 for declarative client-side routing
+- API integration with Axios — request encryption, response decryption,
+  token injection, and error handling all in one interceptor chain
+- AES-256-CBC encryption using crypto-js (matching the linked backend service)
+- Environment variable management via .env with REACT_APP_ prefix
+- Vanilla CSS (no Tailwind, no CSS-in-JS) — styles live in .module.css files
+  per page and a single global.css for shared rules
+- Standard HTML/JS/CSS assets served from public/assets/
+- Apache .htaccess for SPA routing (all paths fall back to index.html)
+
+---
+
+## Activation Rules
+
+1. ALWAYS read `context.services` before generating any file
+2. The linked backend service name is stored in
+   `context.current_init.linked_service` — use it to read:
+   - `context.services[linked_service].port` → API base URL
+   - `context.services[linked_service].encryption_key` → REACT_APP_KEY
+   - `context.services[linked_service].encryption_iv` → REACT_APP_IV
+   - `context.services[linked_service].api_key` → REACT_APP_API_KEY
+3. NEVER invent or hardcode key/iv/api-key values — always inherit from
+   the linked backend service entry in context
+4. After generating files → return list of created files to global-agent
+
+---
+
+## File Structure (per ReactJS service)
+
+```
+<service_name>/
+  public/
+    assets/              <- All shared CSS, JS libraries, fonts, images
+      css/
+        style.css        <- Global stylesheet (imported via index.html link tag)
+      js/                <- Any vendor/utility JS files if needed
+      images/            <- Static images referenced from HTML/CSS
+    favicon.ico
+    index.html           <- Single HTML shell — loads assets, mounts #root
+    robots.txt
+    .htaccess            <- Apache rewrite rules for SPA fallback routing
+  src/
+    api/
+      apiClient.js       <- Axios instance with encrypt/decrypt interceptors
+      apiHandler.js      <- All API call functions (one export per endpoint)
+    components/          <- Shared/reusable components (subdirectories allowed)
+    pages/
+      Welcome/
+        index.jsx        <- Default welcome page, loaded as the first route
+        Welcome.module.css
+    App.jsx              <- React Router root — defines all routes
+    index.jsx            <- ReactDOM.createRoot entry point
+  .env                   <- REACT_APP_* variables (gitignored)
+  .env.example           <- Same keys, values blanked (committed)
+  .gitignore
+  .htaccess              <- Root-level .htaccess for servers that serve from root
+  package.json
+  README.md
+```
+
+---
+
+## Backend Linking Rule
+
+A ReactJS service CANNOT be initialized without a linked NodeJS backend
+service already registered in context.
+
+When global-agent routes `@initialize-project` with `project_type == "reactjs"`:
+- Run task: `ask-linked-service` to select the backend
+- Store result in: `context.current_init.linked_service`
+- Inherit these values from `context.services[linked_service]` into
+  `context.current_init`:
+  - `linked_service_port` — used to build REACT_APP_BASE_URL
+  - `encryption_key` — written to .env as REACT_APP_KEY (hex format)
+  - `encryption_iv` — written to .env as REACT_APP_IV (hex format)
+  - `api_key` — written to .env as REACT_APP_API_KEY
+
+These four values are NEVER asked from the user. They are always inherited.
+
+---
+
+## Encryption Standard
+
+The ReactJS frontend mirrors the linked backend's encryption exactly.
+Both sides use AES-256-CBC with the same KEY and IV.
+
+- Library: `crypto-js`
+- Key format in .env: raw string (32 chars), parsed as Hex by CryptoJS
+- IV format in .env: raw string (16 chars), parsed as Hex by CryptoJS
+- Every outgoing request body is encrypted before send
+- Every incoming response body is decrypted before the caller sees it
+- The `token` header (when present) is also AES-encrypted
+
+The KEY and IV values written to .env are copied exactly as stored in
+`context.services[linked_service]` — no re-encoding or reformatting.
+
+---
+
+## API Client Standard (apiClient.js)
+
+The Axios instance in `src/api/apiClient.js` is the only file that
+communicates with the backend. It handles all cross-cutting concerns
+so that `apiHandler.js` functions can stay simple.
+
+The client has four responsibilities:
+1. Set static headers: `api-key`, `Accept-Language`, `Content-Type: text/plain`
+2. Request interceptor: encrypt the request body before it is sent;
+   also attach the session token from localStorage (key: `wa_token`) as
+   an encrypted `token` header if present
+3. Response interceptor (success path): decrypt the response body;
+   parse the JSON; if response code is -1 trigger a logout redirect;
+   if decryption or parsing fails return the raw payload without crashing
+4. Response interceptor (error path): handle ERR_NETWORK and 401 status
+   by triggering logout redirect and showing an error message
+
+The `baseURL` is read from `process.env.REACT_APP_BASE_URL`.
+The `api-key` header is read from `process.env.REACT_APP_API_KEY`.
+The `key` and `iv` for encryption are parsed from
+`process.env.REACT_APP_KEY` and `process.env.REACT_APP_IV` using
+`CryptoJS.enc.Hex.parse()` — matching the backend's CryptoJS setup.
+
+`logOutRedirectCall` and `showErrorMessage` are imported from
+`../pages/common/Utils` — these are placeholder imports that the
+developer implements in their pages layer. The agent generates the
+import lines; the developer fills in the implementations.
+
+---
+
+## API Handler Standard (apiHandler.js)
+
+`src/api/apiHandler.js` exports one async function per API endpoint.
+Each function calls `axiosClient.post(path, payload)` and returns the
+result directly — no try/catch, no decryption, no response shaping here.
+All of that is handled by the interceptors in `apiClient.js`.
+
+The handler file is the only place in the frontend codebase where
+API endpoint paths are written. It is the frontend's equivalent of a
+route registry.
+
+Functions follow a consistent signature:
+- Simple endpoints: accept a plain `data` parameter passed straight through
+- Auth endpoints: destructure only the fields needed and build the payload
+  explicitly (e.g. webLogin destructures `{ email, password }` and constructs
+  a full device-info payload before sending)
+
+Session saving (e.g. `saveWebSession(res.data)` after login) is called
+in the handler function itself, not in the UI layer.
+
+The agent generates handler functions matching the routes registered in
+`context.api_routes` for the linked backend service. For each route, one
+exported function is generated.
+
+---
+
+## Welcome Page Standard
+
+The default `pages/Welcome/index.jsx` is a minimal functional React
+component that renders a centered welcome message using the project name
+from `context.current_init.service_name`. It imports `Welcome.module.css`
+for its styles. No external UI library. No data fetching.
+
+This page is the first route in `App.jsx` at path `/`.
+
+---
+
+## App.jsx Standard
+
+Uses React Router v6 `BrowserRouter`, `Routes`, and `Route`.
+The initial route `/` renders the Welcome page.
+Additional routes are added via `@create-api` as the project grows.
+
+---
+
+## .env Contents
+
+```
+REACT_APP_BASE_URL=http://localhost:<linked_service_port>/api/v1/
+REACT_APP_API_KEY=<inherited from linked backend service>
+REACT_APP_KEY=<inherited from linked backend service>
+REACT_APP_IV=<inherited from linked backend service>
+```
+
+All four values are auto-populated from the linked backend service.
+The user does not enter any of these manually.
+
+`.env.example` contains the same four keys with empty values.
+
+---
+
+## .htaccess Standard
+
+Two `.htaccess` files are generated — one inside `public/` and one at
+the service root. Both instruct Apache to serve `index.html` for any
+URL that does not match a real file, enabling React Router to handle
+client-side navigation.
+
+The rewrite rule pattern: if the requested path is not a real file and
+not a real directory, rewrite to `index.html`.
+
+The root-level `.htaccess` sets the document root context.
+The `public/.htaccess` sets the rewrite base for when Apache serves
+directly from the `public/` folder.
+
+---
+
+## package.json Standard
+
+- `name` — from `context.current_init.service_name`
+- `version` — `"1.0.0"`
+- `description` — from `context.current_init.description`
+- Scripts: `start` (react-scripts start), `build` (react-scripts build),
+  `test` (react-scripts test)
+- Core dependencies: `react`, `react-dom`, `react-router-dom`,
+  `react-scripts`, `axios`, `crypto-js`
+- No TypeScript, no Tailwind, no UI component library by default
+
+---
+
+## Code Style Standards
+
+- Functional components only — no class components
+- JSDoc comment block above every exported function and component
+- No inline styles — all styles go in `.module.css` or `global.css`
+- No direct `console.log` in production components — use the
+  `showMessage` / `showErrorMessage` utilities
+- No hardcoded API paths in component files — all API calls go through
+  `apiHandler.js`
+
+---
+
+## Workflow Capabilities
+
+- `initialize-project` → scaffold full React app baseline
+- `@create-api` on the linked backend → agent can generate a matching
+  handler function in `apiHandler.js` for the new route
+- `@modularize` → scan pages, extract layout components, rewrite pages
+  to use them. Read `.codeninja/commands/modularize.workflow.md`.
+- `@validate-page` → add client-side form validation with library of
+  user's choice and standard error messages to a specific page.
+  Read `.codeninja/commands/validate-page.workflow.md`.
+- `@integrate-api` → wire forms and action buttons to apiHandler functions,
+  add loading/error/success states, update apiHandler.js with new functions.
+  Read `.codeninja/commands/integrate-api.workflow.md`.

package/ide/claude-code/.claude/commands/codeninja-api.md

@@ -0,0 +1,104 @@
+This command runs when user types /codeninja:api
+
+---
+type: workflow
+name: create-api
+description: >
+  Add a new API module (route.js + model.js) to an existing NodeJS service.
+  Appends to route_manager.js and patches swagger_doc.json surgically —
+  never rewrites existing files. Fully context-aware.
+---
+
+# Workflow: @create-api
+
+## Goal
+Scaffold a complete API module inside an existing NodeJS service.
+Every generated file references actual DB columns from context.
+
+## Rules
+- Ask ONE question at a time
+- Never invent table or column names — read from `context.db.schema`
+- Always add the new route to `context.api_routes`
+- Always update `swagger_doc.json` with the new endpoint
+
+---
+
+## Step-by-Step Execution
+
+### Phase 0 — Existing Pattern Review
+Before asking any questions, read the existing modules in
+context.services[<service_name>].modules and scan 1–2 existing
+route.js and _model.js files from the service.
+
+Identify:
+- Naming conventions in use (camelCase vs PascalCase for functions)
+- Common validation patterns (which fields always get required rules)
+- Any project-specific response patterns beyond the standard contract
+- Auth pattern used across existing routes (all full? mixed?)
+
+Surface a one-line summary: "I've reviewed [n] existing modules.
+I'll follow the same structure." Then proceed to Phase 1.
+
+### Phase 1 — Target Service
+1. Run task: `ask-target-service`
+   - List available services from `context.services`
+   - Stores: `context.current_api.service_name`
+
+2. Run task: `ask-api-version`
+   - Default: v1
+   - Stores: `context.current_api.version`
+
+---
+
+### Phase 2 — Module Identity
+3. Run task: `ask-module-name`
+   - Example: Products, Orders, Invoice
+   - Stores: `context.current_api.module_name`
+
+4. Run task: `ask-http-method`
+   - Options: GET, POST, PUT, PATCH, DELETE
+   - Stores: `context.current_api.method`
+
+5. Run task: `ask-route-path`
+   - Example: /products, /products/:id
+   - Stores: `context.current_api.route_path`
+
+6. Run task: `ask-route-description`
+   - Stores: `context.current_api.description`
+
+---
+
+### Phase 3 — Database Binding
+7. Run task: `ask-primary-table`
+   - Show available tables from `context.db.schema.tables`
+   - Stores: `context.current_api.primary_table`
+
+8. Run task: `ask-requires-auth`
+   - Options: yes / no
+   - Stores: `context.current_api.requires_auth`
+
+---
+
+### Phase 4 — Generate
+9. Confirm with user: "Generate [METHOD] [path] in [service]/modules/[version]/[Module]? (yes/no)"
+
+10. Delegate to `nodejs-agent`:
+    - Generate: `route.js` — run task: generate-route
+      (new file — always a full write)
+    - Generate: `<module>_model.js` — run task: generate-model
+      (new file — always a full write)
+    - Append to: `modules/<version>/route_manager.js`
+      run task: generate-route-manager (Mode 2 — append only)
+      NEVER rewrite this file — surgical insert only
+    - Patch: `document/<version>/swagger_doc.json`
+      run task: generate-swagger (Mode 2 — patch paths object only)
+      NEVER rewrite this file — add new path key only
+
+> **Claude Code sub-agent:** At Phase 4 generate step: Spawn sub-agent: Task(nodejs-agent)
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+11. Run task: `write-context`
+    - Append to `context.api_routes`
+    - Update `context.services[<service>].modules`
+
+12. Run task: `show-final-summary`

package/ide/claude-code/.claude/commands/codeninja-audit.md

@@ -0,0 +1,119 @@
+This command runs when user types /codeninja:audit
+
+---
+type: workflow
+name: audit
+description: >
+  Review an existing service for code quality, security issues, naming
+  consistency, missing middleware, and context alignment.
+---
+
+# Workflow: @audit
+
+## Goal
+Produce a structured audit report for a service. Identify issues by severity.
+Optionally auto-fix low-risk issues.
+
+## When to use @audit vs @sync drift detection
+
+`@sync` drift detection: runs automatically with every @sync. Checks
+structural markers only — middleware order, library consistency,
+export patterns. Fast, read-only, always safe.
+
+`@audit`: run manually when you want deep code quality analysis —
+security checks, SQL injection patterns, response format consistency,
+context alignment. Slower, comprehensive, covers logic not just structure.
+
+Run @sync regularly. Run @audit before releasing a service or after
+a major refactor.
+
+---
+
+## Step-by-Step Execution
+
+1. Run task: `ask-target-service`
+
+2. Delegate to relevant agent(s) based on service type.
+
+> **Claude Code sub-agent:** At step 2: Spawn appropriate sub-agent: Task(nodejs-agent) for NodeJS services, Task(database-agent) for DB-only
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+3. Agent checks:
+
+### Security Checks
+- [ ] API key validation middleware applied to all routes?
+- [ ] Input validation on all POST/PUT/PATCH routes?
+- [ ] SQL injection prevention (parameterized queries)?
+- [ ] Sensitive values only from env vars (no hardcoded keys/passwords)?
+- [ ] `.env` in `.gitignore`?
+- [ ] Encryption using real AES-256-CBC (not base64)?
+- [ ] utilities/encryption.js is the only file importing crypto-js or cryptlib?
+- [ ] res.json() is never called directly in route.js or model files?
+- [ ] Validator package never imported directly in route files?
+- [ ] SMTP credentials only in .env — never hardcoded in
+      notification.js or template.js?
+- [ ] Firebase service account file in pem/ and in .gitignore?
+- [ ] GLOBALS object is frozen using Object.freeze?
+
+### Code Quality Checks
+- [ ] Controllers only call services (no DB queries in controllers)?
+- [ ] Services contain business logic (no Express req/res objects)?
+- [ ] Models contain only DB queries?
+- [ ] Global error handler present and used?
+- [ ] All routes call checkValidationRules from utilities/validator.js
+      before calling model functions?
+- [ ] No separate _validator.js files exist per module?
+- [ ] rateLimiter is the first middleware in route_manager.js?
+- [ ] extractLanguage runs before validateApiKey in route_manager.js?
+- [ ] decryptRequest is the last middleware in the chain?
+- [ ] No route handlers defined directly in route_manager.js?
+- [ ] asyncHandler wraps every middleware in route_manager.js?
+- [ ] All model functions return exactly { responsecode, responsemsg,
+      responsedata } — no extra keys, no throws?
+- [ ] No req/res objects in any model file?
+- [ ] Passwords HASHED (not encrypted) using `utilities/hashing.js` before storage?
+      Correct: `await hashPassword(plainText)` — one-way bcrypt/argon2 hash
+      Wrong: `encrypt(password)` from encryption.js — reversible AES, not safe for passwords
+- [ ] No direct bcrypt/argon2 imports in route.js or model files? All hashing routed through utilities/hashing.js?
+- [ ] Session tokens generated only via common.generateSessionCode?
+- [ ] No crypto-js or cryptlib imported directly in model files?
+- [ ] No direct res.json() calls in route.js files?
+
+### Consistency Checks
+- [ ] All routes documented in `swagger_doc.json`?
+- [ ] Response format consistent (success, message, data, timestamp)?
+- [ ] Naming follows snake_case for DB, camelCase for JS?
+- [ ] Port matches `context.services[<name>].port`?
+- [ ] DB config matches `context.db`?
+- [ ] All message keywords used in sendResponse calls exist in
+      languages/en.js?
+- [ ] All language files contain the same set of keys as en.js?
+- [ ] No two services share the same port in context.services?
+- [ ] All encryption keys in context.services are exactly 32 characters?
+- [ ] All encryption IVs in context.services are exactly 16 characters?
+- [ ] No service name in context.services conflicts with a folder name
+      that already exists on disk for a different service?
+
+### Context Alignment
+- [ ] All routes present in `context.api_routes`?
+- [ ] All DB tables referenced match `context.db.schema`?
+- [ ] All router.use() lines in route_manager.js have a corresponding
+      entry in context.services[<name>].modules?
+- [ ] All context.services[<name>].modules entries have a corresponding
+      router.use() line in route_manager.js?
+- [ ] All paths in swagger_doc.json have a corresponding entry in
+      context.api_routes?
+
+4. Present audit report:
+```
+AUDIT REPORT — <service_name>
+══════════════════════════════════════
+🔴 CRITICAL   (must fix)
+🟡 WARNING    (should fix)
+🟢 INFO       (nice to have)
+══════════════════════════════════════
+[list findings with file + line context]
+```
+
+5. Ask: "Auto-fix critical issues? (yes/no)"
+6. If yes → delegate to relevant agent for fixes → run task: `write-context`

package/ide/claude-code/.claude/commands/codeninja-db-create.md

@@ -0,0 +1,138 @@
+This command runs when user types /codeninja:db-create
+
+---
+type: workflow
+name: db-create-table
+command: "@db:create-table"
+description: >
+  Design and generate a new database table following all project conventions.
+  Collects table purpose, name, columns one at a time, then generates the
+  numbered SQL file, updates create-schema.sql, and records in context.
+---
+
+# Workflow: @db:create-table
+
+## Goal
+Generate a complete, convention-compliant SQL table file. Every generated
+file must pass ALL rules defined in database-agent.md.
+
+## Rules
+- Ask ONE question at a time — never bundle column definitions
+- Always enforce tbl_ prefix and snake_case naming
+- Never create a table file without updating create-schema.sql
+- Always record in context.db.schema after generation
+
+---
+
+## Step-by-Step Execution
+
+### Phase 1 — Table Identity
+1. Run task: `ask-table-purpose`
+   - Stores: `context.current_db.table_purpose`
+   - Used by agent to suggest column names and structure
+
+2. Run task: `ask-table-name`
+   - Enforce: lowercase, snake_case, must start with `tbl_`
+   - Stores: `context.current_db.table_name`
+
+3. Run task: `ask-table-file-number`
+   - Agent reads existing files in `database/<db_type>/migrations/`
+   - Suggests next available number
+   - Stores: `context.current_db.file_number`
+
+---
+
+### Phase 2 — Standard Columns Decision
+4. Run task: `ask-table-needs-status`
+   - Ask: "Does this table need status and is_deleted columns?"
+   - Agent guidance: suggest YES for user/entity tables, NO for event/log tables
+   - Stores: `context.current_db.needs_status`
+
+5. Run task: `ask-table-needs-soft-delete`
+   - Ask: "Does this table support soft delete (is_deleted)?"
+   - Auto-suggest: YES if needs_status is YES
+   - Stores: `context.current_db.needs_soft_delete`
+
+---
+
+### Phase 3 — Column Collection (repeat until done)
+6. Run task: `ask-column-name`
+   - Show columns collected so far
+   - Ask: "Enter the next column name (or type 'done' to finish)"
+   - Enforce: snake_case, lowercase
+   - Stores: appends to `context.current_db.columns[]`
+
+7. Run task: `ask-column-type`
+   - Show suggested type based on column name pattern:
+     - `*_id` → BIGINT NOT NULL DEFAULT 0
+     - When a column name ends in `_id`:
+         - Cross-reference context.db.schema.tables for a table whose name
+         matches the prefix (e.g. user_id → tbl_users)
+         - If found → suggest: "This looks like a foreign key to tbl_users.
+         Add FK constraint? (yes/no)"
+         - If yes → add REFERENCES clause to the column definition
+     - `is_*` → BOOLEAN NOT NULL DEFAULT FALSE
+     - `*_at` → TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+     - `status` → INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0,1))
+     - `*_count` → BIGINT NOT NULL DEFAULT 0
+     - `*_price`, `*_amount` → NUMERIC(18,8) NOT NULL DEFAULT 0.00000000
+     - `email` → VARCHAR(132) NOT NULL DEFAULT ''
+     - `phone` → VARCHAR(16) NOT NULL DEFAULT ''
+     - `password` → TEXT NOT NULL DEFAULT ''
+     - `*_image`, `*_url` → VARCHAR(255) NOT NULL DEFAULT ''
+     - `payload`, `metadata`, `*_result` → JSON NOT NULL DEFAULT '{}'
+     - default → VARCHAR(255) NOT NULL DEFAULT ''
+   - Stores: in current column entry
+
+8. Run task: `ask-column-is-enum`
+   - Ask: "Does this column have a fixed set of allowed values? (enum-like)"
+   - If yes → run task: `ask-column-enum-values`
+   - Stores: check constraint and comment text
+
+9. Return to step 6 until user types 'done'
+
+---
+
+### Phase 4 — Index Decision
+10. Run task: `ask-table-indexes`
+    - Agent auto-suggests indexes based on collected columns:
+      - Every `*_id` (foreign key) column → suggest index
+      - `status + is_deleted` compound → suggest if both exist
+      - `created_at DESC` → suggest for event/log tables
+    - Ask user to confirm suggested indexes or add custom ones
+
+---
+
+### Phase 5 — Seed Data
+11. Run task: `ask-table-seed-data`
+    - Ask: "Does this table need seed/initial data?"
+    - Guidance: suggest YES only for reference/master data tables
+    - If yes → run task: `collect-seed-data`
+    - Stores: `context.current_db.seed_rows[]`
+
+---
+
+### Phase 6 — Summary and Generate
+12. Run task: `show-db-table-summary`
+    - Display complete table definition as it will be generated
+    - Show: table name, file number, all columns with types, indexes, seed data
+    - Ask: "Generate this table? (yes / no / change a value)"
+    - If change → re-run specific task → return to this step
+    - If no → abort, nothing created
+    - If yes → proceed
+
+13. Delegate to `database-agent`:
+
+> **Claude Code sub-agent:** Spawn sub-agent: Task(database-agent) for SQL generation.
+> The spawned agent reads `.codeninja/tasks/generate-*.task.md` for generation standards.
+
+    - Generate: `<repo_root>/database/<db_type>/migrations/<number>-setup-tbl-<name>.sql`
+    - Update: `<repo_root>/database/<db_type>/create-schema.sql`
+    - If any indexes belong in shared file → update: `111-setup-database-indexes.sql`
+
+14. Run task: `write-context`
+    - Append table to `context.db.schema.tables`
+    - Append to `context.db.schema.change_log`
+    - Clear `context.current_db`
+
+15. Run task: `show-final-summary`