codeninja 3.1.0 → 3.2.0

package/ide/cursor/.cursor/rules/04-database.mdc

@@ -1,87 +1,90 @@
 ---
-description: codeninja database standards — loaded for SQL migration files and database work
+description: codeninja Database Architect — table design, migrations, indexes, seeds
 globs: ["**/database/**", "**/*.sql", "**/migrations/**"]
 alwaysApply: false
 ---
 
 # codeninja — Database Architect
 
-## Before Any SQL Generation
-Call `migration_next_number` MCP tool. NEVER invent table or column names.
-Load `context.db` fully. `database/` folder ALWAYS at repository root.
+## Critical Rule
+`database/` folder is ALWAYS at the repository root — NEVER inside a service folder.
+All services share the same database directory.
 
-## Naming (strict — no exceptions)
-| Element | Rule | Example |
-|---------|------|---------|
-| Table | `tbl_` prefix, lowercase, plural | `tbl_users` |
-| Column | lowercase snake_case | `user_id`, `created_at` |
-| PK | `id` bigint identity, first | always |
-| FK | `<table_singular_no_prefix>_id` | `user_id` → `tbl_users` |
-| Index (per-table) | `idx_<table_no_prefix>_<cols>` | `idx_users_email` |
-| Index (global) | `idx_tbl_<table>_<cols>` | `idx_tbl_users_email_is_deleted` |
-| Create file | `<N>-setup-tbl-<n>.sql` | `3-setup-tbl-users.sql` |
-| Alter file | `<N>-alter-tbl-<n>-<desc>.sql` | `12-alter-tbl-users-add-kyc.sql` |
-| Drop file | `<N>-drop-tbl-<n>.sql` | `13-drop-tbl-sessions.sql` |
-| Shared indexes | `111-setup-database-indexes.sql` | always last |
+## /codeninja:db:create — New Table
 
-## Primary Key (exact format)
-```sql
-id bigint NOT NULL GENERATED ALWAYS AS IDENTITY (INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 9223372036854775807 CACHE 1),
-```
-`PRIMARY KEY (id)` at END of column block — never inline.
-
-## Column Types
-| Use | Type |
-|-----|------|
-| FK | `BIGINT NOT NULL DEFAULT 0` |
-| Names | `VARCHAR(64)`–`VARCHAR(255)` |
-| Short codes | `VARCHAR(8)`–`VARCHAR(32)` |
-| Email | `VARCHAR(132)` |
-| Token/password | `TEXT` |
-| Timestamp | `TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP` |
-| Status flag | `INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0, 1))` |
-| Soft delete | `BOOLEAN NOT NULL DEFAULT FALSE` |
-| Price | `NUMERIC(18,8) NOT NULL DEFAULT 0.00000000` |
-| JSON | `JSON NOT NULL DEFAULT '{}'` |
+1. Ask: table purpose (used for column suggestions)
+2. Ask: table name (must start with `tbl_`, snake_case, lowercase)
+3. Ask: migration file number (agent reads migrations/ and suggests next via `migration_next_number`)
+4. Ask: needs `status` + `is_deleted` columns? (suggest YES for entity tables, NO for log tables)
+5. Ask: needs soft delete `is_deleted`? (auto-suggest YES if needs_status)
+6. Column collection loop (repeat until "done"):
+   - Ask column name (snake_case) + type (show suggestion by name pattern):
+     - `*_id` → BIGINT NOT NULL DEFAULT 0 (also check FK — ask if references another table)
+     - `is_*` → BOOLEAN NOT NULL DEFAULT FALSE
+     - `*_at` → TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+     - `status` → INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0,1))
+     - `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` → JSON NOT NULL DEFAULT '{}'
+   - Ask: is this an enum column? If yes → collect allowed values → CHECK constraint + COMMENT
+7. Index suggestions: auto-suggest for every FK column, status+is_deleted compound, created_at DESC for logs
+8. Ask: seed data needed? (YES only for reference/master tables)
+9. Show complete table summary — ask: "Generate? (yes / no / change)"
+10. Generate migration file at `database/<db_type>/migrations/<n>-setup-tbl-<name>.sql`
+11. Update `create-schema.sql` with `\i` entry in numeric order
+12. Call `context_write` — append to context.db.schema.tables and change_log
 
-NEVER use PostgreSQL ENUM — always `VARCHAR + CHECK constraint`.
-Apply `NOT NULL` to every column by default.
+## /codeninja:db:modify — Alter Table
+- Always generate an ALTER file — NEVER edit the original setup file
+- Operations: add column, rename column, drop column, change type, add CHECK constraint, add index
+- For "add index" → route to /codeninja:db:index instead
+- Generated file: `<n>-alter-tbl-<name>-<description>.sql`
+- Wrap in `BEGIN; ... COMMIT;`
 
-## SQL File Content Order (strict)
-```
-1. -- Comment: Creating <table> for <purpose>
-2. DROP TABLE IF EXISTS public.<table> CASCADE;
-3. CREATE TABLE block (id first, timestamps last)
-4. COMMENT ON COLUMN for every enum/flag column
-5. Per-table CREATE INDEX statements
-6. ALTER TABLE public.<table> OWNER TO <context.db.user>;
-7. GRANT ALL ON TABLE public.<table> TO <context.db.user>;
-8. INSERT seed data (reference tables only)
-```
+## /codeninja:db:index — Add Index
+- Ask: table, column(s), sort order (DESC?), standard vs partial (WHERE clause?)
+- Ask: table's own file vs `111-setup-database-indexes.sql` (auto-suggest shared file for existing tables)
+- Index naming: `idx_<table_without_tbl_prefix>_<columns>` (table file) or `idx_tbl_<name>_<columns>` (shared)
+- Always show generated name and confirm before writing
 
-## Required Columns
-| Column | Every table | Entity tables | Log tables |
-|--------|------------|---------------|------------|
-| `id` | ✓ | ✓ | ✓ |
-| `created_at` | ✓ | ✓ | ✓ |
-| `status` | — | ✓ | — |
-| `is_deleted` | — | ✓ | — |
+## /codeninja:db:drop — Drop Table
+- NEVER delete original setup file — generate new drop migration
+- Show impact analysis: routes referencing table, FK dependencies
+- Require user to type table name exactly to confirm
+- Generated file: `<n>-drop-tbl-<name>.sql` with `DROP TABLE IF EXISTS ... CASCADE`
+- Keep original `\i <setup_file>` in create-schema.sql — add drop file AFTER it
+- Save full column snapshot to change_log before removing from active tables
 
-## Index Rules — Always Index
-- Every FK column
-- `(status, is_deleted)` compound on entity tables
-- `created_at DESC` on log/event tables
-- `email` compound with `is_deleted` on user tables
-- Any WHERE or ORDER BY column in business queries
+## /codeninja:db:seed — Add Seed Data
+- Determine: append to setup file (reference/master data) OR standalone seeds/ file (dev data)
+- NEVER store plaintext passwords — warn user to provide encrypted value
+- Multi-row INSERT only (single INSERT with multiple value tuples)
+- File: `database/<db_type>/seeds/<table_name>_seed.sql`
 
-## create-schema.sql
-Lives at `<repo_root>/database/<db_type>/create-schema.sql`. Auto-generated, never hand-edited.
-After every table operation: update `\i` entries in numeric order.
-`111-setup-database-indexes.sql` always last.
+## /codeninja:db:sync — Rebuild Schema from Files
+- Parse all migration files in numeric order: setup → alter → drop → indexes
+- Rebuild context.db.schema from actual file contents
+- Rewrite create-schema.sql to match actual files on disk
+- Report stale entries (in create-schema.sql but not on disk) and missing entries
 
-## Permissions (end of every file)
+## SQL Standards
 ```sql
-ALTER TABLE public.<table> OWNER TO <context.db.user>;
-GRANT ALL ON TABLE public.<table> TO <context.db.user>;
+-- Standard table structure
+CREATE TABLE public.tbl_<name> (
+  id           BIGSERIAL PRIMARY KEY,
+  -- ... columns ...
+  status       INTEGER NOT NULL DEFAULT 0 CHECK (status IN (0,1)),
+  is_deleted   BOOLEAN NOT NULL DEFAULT FALSE,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+COMMENT ON COLUMN public.tbl_<name>.<col> IS 'Values: 0=<label>, 1=<label>';
+
+CREATE INDEX idx_<name>_<col> ON public.tbl_<name> (<col>);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.tbl_<name> TO <db_user>;
 ```
-Always from `context.db.user` — never hardcode username.
+
+All ALTER and DROP migrations wrapped in `BEGIN; ... COMMIT;`.

package/ide/cursor/.cursor/rules/05-reactjs.mdc

@@ -1,83 +1,147 @@
 ---
-description: codeninja ReactJS standards — loaded for React app files
-globs: ["**/src/**", "**/public/**", "**/*.jsx", "**/*.css", "**/apiClient*", "**/apiHandler*"]
+description: codeninja ReactJS Frontend — scaffolding, modularize, validate-page, integrate-api
+globs: ["**/src/**/*.jsx", "**/src/**/*.js", "**/public/**", "**/.htaccess"]
 alwaysApply: false
 ---
 
 # codeninja — ReactJS Frontend
 
-## Backend Linking (enforced before any generation)
-```
-context.current_init.linked_service → backend service name
-context.services[linked].port       → REACT_APP_BASE_URL
-context.services[linked].encryption_key → REACT_APP_KEY
-context.services[linked].encryption_iv  → REACT_APP_IV
-context.services[linked].api_key        → REACT_APP_API_KEY
-```
-These 4 values are ALWAYS inherited. NEVER ask the user. NEVER hardcode.
+## Backend Linking Rule (enforced)
+ReactJS service CANNOT initialize without a linked NodeJS service.
+Security values (KEY, IV, API_KEY) are ALWAYS inherited from the linked backend — never asked from user.
+
+## /codeninja:init — ReactJS App Scaffolding
+
+### Phase 1 — Linking
+- List available NodeJS services from context.services
+- Ask: which NodeJS service to link to?
+- Auto-inherit: encryption_key, encryption_iv, api_key from linked service
+- Ask: service name, description
+
+### Phase 2 — Single Confirmation, Then Generate ALL Files
+
+**Wave 1:** package.json, .env (inherited values), .env.example, .gitignore, README.md,
+public/index.html, public/assets/css/style.css (empty reset), public/robots.txt,
+public/favicon.ico (placeholder), .htaccess (root), public/.htaccess
+
+**Wave 2:** src/api/apiClient.js, src/api/apiHandler.js
+
+**Wave 3:** src/pages/Welcome/index.jsx, src/pages/Welcome/Welcome.module.css,
+src/App.jsx, src/index.jsx, src/components/.gitkeep
+
+**Wave 4:** Dockerfile, nginx.conf, .dockerignore
+
+Completion gate — verify before proceeding:
+- public/index.html, src/api/apiClient.js, src/api/apiHandler.js, src/App.jsx, src/index.jsx, .env
+
+### apiClient.js — 4 Responsibilities
+1. Static headers: `api-key` (from REACT_APP_API_KEY), `Accept-Language`, `Content-Type: text/plain`
+2. Request interceptor: encrypt body; attach AES-encrypted `token` from localStorage (`wa_token`) if present
+3. Response interceptor (success): decrypt body; parse JSON; code -1 → logout redirect
+4. Response interceptor (error): ERR_NETWORK / 401 → logout redirect + error message
+
+### apiHandler.js Standard
+- One async function per API endpoint
+- Each calls `axiosClient.post/get/put/patch/delete(path, payload)` and returns directly
+- No try/catch, no decryption, no response shaping in this file
+- Only place in frontend where API endpoint paths are written
+
+---
+
+## /codeninja:modularize — Extract Layout Components
+
+**Rule:** Layout structure only — NEVER touch business logic, state, API calls, event handlers.
+NEVER create a component that already exists — reuse it.
+
+1. Ask: which ReactJS service
+2. Ask: all pages OR specific page
+3. Inventory existing `src/components/` — record name, path, structural role, props
+4. Scan target pages — identify repeated layout blocks (header, nav, footer, sidebar, etc.)
+5. Cross-check: if block matches existing component → mark "reuse", else "new component needed"
+6. Group blocks by similarity across pages — only extract if appears in 2+ pages
+7. Show extraction plan with component names, props, files to create, pages to update
+8. Ask: "Apply? (yes / no / adjust)"
+9. Generate each new component:
+   - `src/components/<ComponentName>/index.jsx` — props for varying values
+   - `src/components/<ComponentName>/<ComponentName>.module.css`
+10. Update each page: add import, replace extracted JSX with `<ComponentName prop={value} />`,
+    remove now-unused imports, remove moved CSS classes
+11. Call `context_write` — append to context.services[<n>].components
+
+---
+
+## /codeninja:validate-page — Add Form Validation
+
+**Rule:** ONE page per run. NEVER modify API calls or business logic. NEVER overwrite existing validation.
+
+1. Ask: which ReactJS service, which page path
+2. Ask: validation library (Yup | React Hook Form | Parsley | Validator.js | Custom)
+3. Scan page: find all `<form>`, `<input>`, `<select>`, `<textarea>`, `<button type="submit">`
+4. For each field: record type, name, id, placeholder, label text, existing validation
+5. Detect existing validation patterns — skip already-validated fields
+6. Infer semantic type from label/name/placeholder → assign standard error messages:
+   - email: "Please enter a valid email address."
+   - password: "Password must be at least 8 characters."
+   - confirmPassword: "Password and confirm password do not match."
+   - phone: "Please enter a valid phone number."
+   - required generic: "This field is required."
+7. Assign missing `name` and `id` attributes (camelCase from label text)
+8. Show validation plan — ask: "Apply? (yes / no / adjust)"
+9. Apply by library:
+   - **Yup:** validationSchema above component, validateForm async function, `{errors.field && <span>...}`
+   - **RHF:** useForm hook, `{...register('field', rules)}`, `{errors.field && <span>...}`
+   - **Parsley:** CDN scripts in index.html, data-parsley-* attributes, useEffect init
+   - **Validator.js:** import validator, validateForm function with validator.isEmail() etc.
+   - **Custom:** plain JS validateForm — no imports
+10. Add `.errorMsg` class to page's `.module.css`
+11. Add package to package.json if needed (yup/react-hook-form/validator)
+12. Call `context_write` — append to context.services[<n>].validated_pages
+
+---
+
+## /codeninja:integrate-api — Wire Forms to Backend
+
+**Rule:** ONE page per run. NEVER modify layout, CSS, or validation. ALWAYS use apiHandler.js.
+
+1. Ask: which ReactJS service, which page path
+2. Ask: all forms/buttons OR specific form/button
+3. Load: linked backend service, context.api_routes for that backend, page content, apiHandler.js
+4. Scan page: identify all forms, action buttons, existing API calls
+5. For each integration point, determine match type:
+   - existing handler → use as-is
+   - matching route in context.api_routes → add new handler to apiHandler.js
+   - no route exists → add TODO placeholder
+6. Design state requirements (loading, error, data states) per form
+7. Show integration plan with handler names, routes, match types, files to modify
+8. Ask: "Apply? (yes / no / adjust)"
+9. Apply:
+   - Append new functions to apiHandler.js (for new_handler and no_route matches)
+   - Add imports, state declarations, handler functions to page file (surgically — never rewrite)
+   - Wire form onSubmit / button onClick
+   - Add `disabled={loading}` and conditional button text
+   - Add `{error && <p className={styles.apiError}>{error}</p>}` above submit button
+   - Add `{successMsg && <p className={styles.successMsg}>{successMsg}</p>}` for non-nav actions
+   - Add useEffect for data-fetching handlers
+   - Add .apiError and .successMsg CSS classes to page's .module.css
+10. Call `context_write` — append to context.services[<n>].integrated_pages
 
 ## File Structure
 ```
-<service>/
+<service_name>/
   public/
-    assets/css/style.css   ← global styles
-    index.html             ← single HTML shell
-    .htaccess              ← Apache SPA rewrite
+    assets/css/style.css    ← global styles
+    index.html              ← single HTML shell
+    .htaccess               ← SPA routing
   src/
     api/
-      apiClient.js         ← Axios + encrypt/decrypt interceptors
-      apiHandler.js        ← one export per API endpoint
-    components/            ← shared reusable components
-    pages/Welcome/
+      apiClient.js          ← Axios + encrypt/decrypt interceptors
+      apiHandler.js         ← all API call functions
+    components/             ← shared reusable components
+    pages/<PageName>/       ← one directory per page
       index.jsx
-      Welcome.module.css
-    App.jsx                ← React Router root
-    index.jsx              ← ReactDOM.createRoot
-  .env                     ← gitignored
-  .env.example             ← committed, values blank
-```
-
-## apiClient.js — 4 Responsibilities
-1. Static headers: `api-key`, `Accept-Language`, `Content-Type: text/plain`
-2. Request: encrypt body via AES-256-CBC; attach encrypted `token` from `localStorage('wa_token')` if present
-3. Response success: decrypt body; parse JSON; if `status === -1` → `logOutRedirectCall()`; if decrypt fails → return raw
-4. Response error: `ERR_NETWORK` or `401` → `logOutRedirectCall()` + `showErrorMessage()`
-
-KEY/IV: `CryptoJS.enc.Hex.parse(process.env.REACT_APP_KEY/IV)`.
-`logOutRedirectCall` and `showErrorMessage` imported from `../pages/common/Utils`.
-
-## apiHandler.js — Pattern
-```javascript
-export const functionName = async (data) => {
-  const res = await axiosClient.post('/path', data);
-  return res.data;
-};
-```
-- One async function per endpoint — no try/catch, no decryption
-- Session saving in handler, not in UI components
-- Functions match routes in `context.api_routes` for linked service
-
-## Code Style
-- Functional components only — no class components
-- JSDoc above every exported function and component
-- No inline styles — `.module.css` per page, `global.css` shared
-- No `console.log` — use `showMessage` / `showErrorMessage`
-- No hardcoded API paths — all calls through `apiHandler.js`
-
-## .env Contents
+      <PageName>.module.css
+    App.jsx                 ← React Router root
+    index.jsx               ← ReactDOM.createRoot entry
+  .env                      ← REACT_APP_* (gitignored)
+  .env.example
 ```
-REACT_APP_BASE_URL=http://localhost:<linked_port>/api/v1/
-REACT_APP_API_KEY=<inherited>
-REACT_APP_KEY=<inherited>
-REACT_APP_IV=<inherited>
-```
-
-## @modularize
-Scan pages, find repeated layout blocks, extract to `src/components/<Name>/`.
-Rewrite pages to use component. Never change data-fetching or state.
-
-## @validate-page
-Client-side only. Per-field error messages below inputs. Preferred library from user.
-
-## @integrate-api
-Add handler in `apiHandler.js`. Wire buttons/forms. Add loading, error, success states.