codeninja 3.1.0 → 3.2.0

package/ide/antigravity/.agents/workflows/codeninja-validate-page.md

@@ -1,11 +1,250 @@
 ---
-slash_command: @validate-page
+slash_command: /codeninja:validate-page
 personas: [global-orchestrator, reactjs-frontend]
-skills: [mcp-and-context, reactjs]
-description: Add client-side form validation to a specific React page
----
-# @validate-page
-Delegates to: `.codeninja/commands/validate-page.workflow.md`
-Before: `context_read`. Ask which page. Ask preferred validation library.
-Add per-field validation on submit. Display error messages below inputs.
-Client-side only — no backend calls.
+skills: [mcp-and-context, reactjs, code-intelligence]
+description: >
+  Add complete client-side form validation to a ReactJS page.
+  Scans all inputs, assigns name/id attributes where missing, installs
+  the chosen validation library if needed, and wires error messages.
+  Never touches API calls or business logic.
+---
+
+# /codeninja:validate-page
+
+## Before Running
+1. Call `context_check_stale`
+2. Call `context_read` — load `context.services`
+3. Call `service_scan` — verify service on disk
+
+## Rules
+- Target ONE specific page per run — never multiple pages at once
+- NEVER modify API call logic, submit handlers (beyond adding a validation gate), or non-form code
+- NEVER overwrite existing validation if the field already has it — only fill gaps
+- Assign `name` and `id` to every input/select/textarea that is missing them
+- ONE confirmation before any file is written
+
+---
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Target Selection
+
+**Step 1.** Ask: "Which ReactJS service?" (list ReactJS services from `context.services`)
+- Store: `context.current_action.service_name`
+
+**Step 2.** Ask: "Which page path?" (e.g. `src/pages/Login/index.jsx`)
+- Store: `context.current_action.page_path`, `context.current_action.page_name`
+
+**Step 3.** Ask: "Which validation library?"
+1. Yup — schema-based async validation
+2. React Hook Form — controlled forms with built-in validation
+3. Parsley — jQuery-based HTML5 validation (CDN, no npm)
+4. Validator.js — utility functions (validator npm package)
+5. Custom — plain JavaScript, no library
+- Store: `context.current_action.validation_library`
+
+---
+
+### Phase 2 — Scan the Page
+
+Read the full file at `context.current_action.page_path`.
+
+#### 2a — Find All Form Elements
+Scan JSX for every `<form>`, `<input>`, `<select>`, `<textarea>`, `<button type="submit">`.
+
+For each `<input>` record:
+- `type`, `name`, `id`, `value`/`defaultValue`, `onChange`, `required`, `placeholder`
+- Any existing validation attributes (minLength, maxLength, pattern, min, max)
+- Adjacent label text (`<label htmlFor="...">` or sibling `<label>`)
+- Any existing error display nearby (`<span className="error">`, `{errors.<n>}`, etc.)
+
+For each `<select>` record: `name`, `id`, available `<option>` values, default empty option.
+For each `<textarea>` record: `name`, `id`, `rows`, `cols`, character limit hints.
+
+#### 2b — Group Fields Into Forms
+If multiple `<form>` elements → group by parent form (each gets its own validation schema).
+If no `<form>` but inputs present → treat all as one implicit form.
+
+#### 2c — Detect Existing Validation
+Check for any existing patterns:
+- `yup.object()` / `yup.string()` imports → Yup schema exists
+- `useForm()` from react-hook-form → RHF wired
+- `.parsley()` calls → Parsley initialized
+- Manual `if (!value)` checks in submit handler
+- `errors` state object
+
+Mark fields with existing validation as "already validated" — skip them.
+
+---
+
+### Phase 3 — Infer Field Semantics and Error Messages
+
+For each field, detect semantic type using label text → name attribute → placeholder → input type:
+
+| Signal | Semantic | Required error | Format error |
+|---|---|---|---|
+| "first name" | first_name | "Please enter your first name." | "First name must be at least 2 characters." |
+| "last name" | last_name | "Please enter your last name." | "Last name must be at least 2 characters." |
+| "full name" / "name" | full_name | "Please enter your full name." | "Full name must be at least 3 characters." |
+| "email" | email | "Please enter your email address." | "Please enter a valid email address." |
+| "phone" / "mobile" | phone | "Please enter your phone number." | "Please enter a valid phone number." |
+| "password" (no "confirm") | password | "Please enter your password." | "Password must be at least 8 characters." |
+| "confirm" + "password" | confirm_password | "Please confirm your password." | "Password and confirm password do not match." |
+| "username" | username | "Please enter a username." | "Username must be 3–20 characters, letters and numbers only." |
+| "address" | address | "Please enter your address." | — |
+| "city" | city | "Please enter your city." | — |
+| "zip" / "postal" | zip_code | "Please enter your zip/postal code." | "Please enter a valid zip/postal code." |
+| "country" | country | "Please select your country." | — |
+| "state" / "province" | state | "Please select your state/province." | — |
+| "date" / "dob" / "birth" | date | "Please select a date." | "Please enter a valid date." |
+| "amount" / "price" | amount | "Please enter an amount." | "Please enter a valid amount greater than 0." |
+| "description" / "message" | description | "Please enter a description." | — |
+| "otp" / "code" / "pin" | otp | "Please enter the OTP." | "OTP must be [n] digits." |
+| type="file" | file_upload | "Please select a file." | "File size must not exceed [n]MB." |
+| "agree" / "terms" (checkbox) | terms | "Please accept the terms and conditions." | — |
+| select (no clear label) | dropdown | "Please make a selection." | — |
+| anything else | generic | "This field is required." | — |
+
+---
+
+### Phase 4 — Assign Missing name and id Attributes
+
+For each field missing `name` or `id`:
+1. Derive from label text or placeholder: strip non-alphanumeric, convert to camelCase
+   e.g. "First Name" → `firstName`, "Email Address" → `emailAddress`
+2. If no label/placeholder → use semantic type: `email`, `password`, `phone`, etc.
+3. If would duplicate → append number: `phone2`, `address2`
+4. Set both `name` and `id` to the same derived value.
+
+---
+
+### Phase 5 — Show Validation Plan
+
+```
+┌──────────────────────────────────────────────────────┐
+│              VALIDATION PLAN                         │
+├──────────────────────────────────────────────────────┤
+│ Page        : [page_name]                            │
+│ Library     : [validation_library]                   │
+│ Install pkg : [package_name] (if needed)             │
+├──────────────────────────────────────────────────────┤
+│ FIELDS TO VALIDATE                                   │
+│  ✓ firstName  (text)    — "Please enter your first name." │
+│  ✓ email      (email)   — "Please enter a valid email." │
+│  ✓ password   (password)— "Please enter your password." │
+│  ✓ confirmPw  (password)— "Passwords do not match."    │
+│                                                      │
+│ FIELDS SKIPPED (already validated)                   │
+│  — phone  (has existing required check)              │
+├──────────────────────────────────────────────────────┤
+│ ATTRIBUTES TO ASSIGN                                 │
+│  confirmPassword → add name="confirmPassword", id="confirmPassword" │
+├──────────────────────────────────────────────────────┤
+│ FILES TO MODIFY                                      │
+│  → src/pages/[PageName]/index.jsx                    │
+│  → package.json (add: [library_package])             │
+└──────────────────────────────────────────────────────┘
+```
+
+Ask: "Apply this validation plan? (yes / no / adjust)"
+
+---
+
+### Phase 6 — Apply Validation by Library
+
+Read current page file. Apply ALL edits surgically — never rewrite the whole file.
+
+#### If library == "yup"
+- Add import: `import * as Yup from 'yup';`
+- Create `validationSchema` above component:
+  ```jsx
+  const validationSchema = Yup.object({
+    firstName: Yup.string().required('Please enter your first name.').min(2, '...'),
+    email: Yup.string().required('...').email('Please enter a valid email address.'),
+    password: Yup.string().required('...').min(8, '...'),
+    confirmPassword: Yup.string().required('...').oneOf([Yup.ref('password')], '...'),
+    // one entry per field
+  });
+  ```
+- Add state: `const [errors, setErrors] = React.useState({});`
+- Add `validateForm` async function inside component
+- Add validation gate at top of submit handler: `const isValid = await validateForm({...}); if (!isValid) return;`
+- Add `{errors.<field> && <span className={styles.errorMsg}>{errors.<field>}</span>}` after each input
+- Add `.errorMsg` CSS class to page's `.module.css`
+
+#### If library == "react-hook-form"
+- Add import: `import { useForm } from 'react-hook-form';`
+- Add hook: `const { register, handleSubmit, watch, formState: { errors } } = useForm();`
+- Wrap form: `<form onSubmit={handleSubmit(onSubmit)}>`
+- Add `{...register('fieldName', { required: '...', pattern/min/validate rules })}` to each input
+- For confirmPassword: `validate: (val) => val === watch('password') || '...'`
+- Add error display after each input
+- Remove redundant `value`/`onChange` props only if purely for controlled form state
+
+#### If library == "parsley"
+- Add to `public/index.html` before `</body>`: jQuery CDN + Parsley CDN + Parsley CSS link
+- Add `data-parsley-required`, `data-parsley-required-message`, `data-parsley-type`, etc. to each input
+- Add `id` to `<form>` element (derive: `[pageName]Form`)
+- Initialize via `useEffect`: `window.$('#loginForm').parsley()`
+- Gate in submit handler: `if (!window.$('#loginForm').parsley().validate()) return;`
+
+#### If library == "validatorjs"
+- Add import: `import validator from 'validator';`
+- Add state: `const [errors, setErrors] = React.useState({});`
+- Add `validateForm` function with per-field checks using `validator.isEmail()`, `validator.isEmpty()`, etc.
+- Add gate: `if (!validateForm()) return;`
+- Add error display + `.errorMsg` CSS
+
+#### If library == "custom"
+- No imports needed — plain JavaScript only
+- Same `validateForm` pattern as validatorjs but using native JS:
+  - `value.trim().length > 0` for required
+  - `/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)` for email
+  - `value.length >= 8` for min length
+  - `value === otherValue` for match
+
+---
+
+### Phase 7 — Install Package (if needed)
+
+If library is yup/react-hook-form/validatorjs AND not in `package.json`:
+- Read current `package.json`
+- Add to dependencies:
+  - yup → `"yup": "^1.3.3"`
+  - react-hook-form → `"react-hook-form": "^7.51.0"`
+  - validatorjs → `"validator": "^13.12.0"`
+- Update `package.json` on disk
+- Display: "📦 Package added to package.json. Run `npm install` in [service_name]/ before testing."
+
+For parsley → CDN only, no npm needed.
+For custom → no package.
+
+---
+
+### Phase 8 — Finalize
+
+**Step 1.** Call `context_write`:
+- Append to `context.services[<service_name>].validated_pages`:
+  `{ page, library, fields_validated: [...], timestamp: ISO now }`
+- Set `last_command` = "validate-page"
+- Append to `change_log`
+
+**Step 2.** Call `context_clear_scratchpad` with keys: ["current_action"]
+
+**Step 3.** Show completion report:
+```
+/codeninja:validate-page Complete
+─────────────────────────────────────────
+Page       : [page_name]
+Library    : [library]
+─────────────────────────────────────────
+Fields validated : [n]
+Fields skipped   : [n] (already had validation)
+Attributes added : [n] (name/id assigned)
+─────────────────────────────────────────
+✓ src/pages/[PageName]/index.jsx — updated
+✓ src/pages/[PageName]/[PageName].module.css — .errorMsg class added
+[✓ package.json — [package] added (run npm install)]
+─────────────────────────────────────────
+Next: /codeninja:integrate-api to wire forms to the backend
+```

package/ide/cursor/.cursor/rules/01-global-orchestrator.mdc

@@ -1,5 +1,5 @@
 ---
-description: codeninja global orchestrator — routing, context, activation. Always applied.
+description: codeninja global orchestrator — routing, context, and command execution. Always applied.
 globs: ["**/*"]
 alwaysApply: true
 ---
@@ -10,51 +10,54 @@ You are a Senior Software Architect managing this project via the codeninja agen
 
 ## Activation Sequence (every session)
 1. Call `context_check_stale` — resolve stale operations first
-2. Call `context_read` — load full context
+2. Call `context_read` — load full project context
 3. Call `service_scan` — compare with `context.services`; if drift detected, suggest `/codeninja:sync`
-4. Load `context.project_info` for all suggestions
-
-## Routing
-| Keyword | Specialist |
-|---------|-----------|
-| express, node, api, service, encryption | nodejs-backend rules |
-| react, frontend, ui, component | reactjs-frontend rules |
-| postgres, mysql, db, schema, migration, table | database-architect rules |
-| /codeninja:db:* | always database-architect |
+4. Load `context.project_info` — use for all suggestions throughout session
 
 ## Context Rules
 - NEVER read/write context.json directly — always use `context_read` / `context_write`
 - `context_write` deep-merges — never overwrites
-- `change_log` append-only
+- `change_log` is append-only — never delete entries
+- After every completed workflow → call `context_clear_scratchpad` for the relevant `current_*` key
+
+## Keyword Routing
+| Trigger | Specialist Domain |
+|---|---|
+| express, node, api, service, encryption | NodeJS / API Builder rules |
+| react, frontend, ui, component, page | ReactJS rules |
+| postgres, mysql, db, schema, migration, table | Database rules |
+| `/codeninja:db:*` | always Database rules |
 
 ## Batch Generation Rule
-ONE confirmation per operation. After user confirms → generate all files silently.
+ONE confirmation per operation.
+After user confirms → generate ALL files silently — no per-file prompts.
 
 ## Response Style
 - One question at a time
 - Confirm before creating or modifying files
-- `database/` folder ALWAYS at repository root — never inside a service
+- `database/` folder ALWAYS at repository root — never inside a service folder
+- After every scaffolding operation → show final summary
 
-## Slash Commands
-| Command | Description |
-|---------|-------------|
+## All Available Commands
+| Command | Action |
+|---|---|
 | `/codeninja:init` | Bootstrap NodeJS service, ReactJS app, or database |
-| `/codeninja:api` | Add API endpoint (5-step SOP) |
+| `/codeninja:api` | Add new API endpoint (route.js + model.js) |
 | `/codeninja:design` | Plan feature before coding |
 | `/codeninja:audit` | Security and quality review |
-| `/codeninja:test` | Generate Jest tests |
-| `/codeninja:refactor` | Rename with context tracking |
-| `/codeninja:sync` | Rebuild context from repo |
-| `/codeninja:explain` | Explain any file or pattern |
-| `/codeninja:review` | Code review with findings |
-| `/codeninja:debug` | Debug with code path trace |
-| `/codeninja:optimize` | Performance improvements |
-| `/codeninja:db:create` | New table + migration |
-| `/codeninja:db:modify` | Alter column |
+| `/codeninja:test` | Generate Jest + Supertest tests |
+| `/codeninja:refactor` | Rename/restructure with context tracking |
+| `/codeninja:sync` | Rebuild context.json from entire repo |
+| `/codeninja:explain` | Explain any file, function, or concept |
+| `/codeninja:review` | Code review with severity-ranked findings |
+| `/codeninja:debug` | Diagnose and fix bugs |
+| `/codeninja:optimize` | Performance analysis |
+| `/codeninja:db:create` | New table with migration file |
+| `/codeninja:db:modify` | Alter table via migration |
 | `/codeninja:db:index` | Add index |
-| `/codeninja:db:drop` | Drop table |
+| `/codeninja:db:drop` | Drop table (safety-checked) |
 | `/codeninja:db:seed` | Add seed data |
-| `/codeninja:db:sync` | Rebuild DB schema |
-| `@modularize` | Extract React layout components |
-| `@validate-page` | Add form validation |
-| `@integrate-api` | Wire forms to API handlers |
+| `/codeninja:db:sync` | Rebuild DB schema from migration files |
+| `/codeninja:modularize` | Extract ReactJS layout components |
+| `/codeninja:validate-page` | Add form validation to ReactJS page |
+| `/codeninja:integrate-api` | Wire ReactJS page forms to backend |

package/ide/cursor/.cursor/rules/03-api-builder.mdc

@@ -1,74 +1,124 @@
 ---
-description: codeninja API builder standards — loaded for NodeJS service files
-globs: ["**/modules/**", "**/middleware/**", "**/utilities/**", "**/route_manager*", "**/app.js", "**/languages/**"]
+description: codeninja NodeJS API Builder — service scaffolding and API creation
+globs: ["**/app.js", "**/route.js", "**/*_model.js", "**/route_manager.js", "**/middleware/**", "**/utilities/**", "**/config/**"]
 alwaysApply: false
 ---
 
-# codeninja — API Builder
+# codeninja — NodeJS API Builder
 
 ## 2-Layer Architecture (enforced)
-
 ```
 modules/v1/<ModuleName>/
 ├── route.js          ← HTTP only: validation, middleware, res.json()
-└── <module>_model.js ← DB only: parameterized queries, business logic
+└── <module>_model.js ← DB only: queries, business logic
 ```
-
 Never SQL in `route.js`. Never `res.json()` in `_model.js`.
 
-## 5-Step SOP — Every New Endpoint
+## /codeninja:init — NodeJS Service Scaffolding
 
-1. **ROUTING** — append to `route_manager.js` via `file_insert_after` (never rewrite)
-2. **VALIDATION** — validatorjs schema in `route.js`, match existing patterns
-3. **CONTROLLER** — model call + try/catch + `sendResponse()` in `route.js`
-4. **MODEL** — parameterized `$1,$2` SQL via pg pool in `_model.js`
-5. **LOCALIZE** — all strings in `languages/en.js`, use `file_contains` before adding
+### Phase 0 — Project Info (runs ONCE per repo, skip if context.project_info populated)
+- Ask for project info doc (URL or paste) — store in context.project_info
+- Ask for scope of work doc — store in context.project_info
+- Ask for Figma URL — store in context.project_info
+- Synthesize project summary and detected_entities[] from all provided docs
 
-## Middleware Chain Order (never change)
-```
-Language extraction → API key validation → JWT auth (protected only) → Rate limiting → Validation → Handler
-```
+### Phase 1 — Mode and Type
+- Ask: Fast setup (9 questions, auto-generate secure values) OR Manual setup (22 questions)
+- Ask: NodeJS service | ReactJS app | Database only
+- For NodeJS: ask client_type (reactjs|app), encrypted_transport, supported_languages[]
 
-## Response Contract
-```javascript
-{ status: 1, message: lang.key, data: result }   // success
-{ status: 0, message: lang.key }                  // error
-{ status: -1, message: lang.key }                 // session expired → triggers frontend logout
-```
-Always use `sendResponse(req, res, status, message, data)` from `utilities/response.js`.
-Never call `res.json()` directly.
+### Phase 2 — Database
+- Ask: database type (postgresql|mysql|mongodb)
+- Fast mode: ask db name and user only; auto-set host/port
+- Manual mode: ask name, host, port, user individually
+- Generate database folder at REPOSITORY ROOT (never inside service folder):
+  `database/<db_type>/migrations/`, `create-schema.sql`, `setup-database.sh`,
+  `setup-database.ps1`, `reset-database.sh`, `seeds/`, `database/README.md`
+- Only if folder doesn't already exist — skip if it does
+- Generate tbl_user_deviceinfo migration for nodejs projects
+
+### Phase 3–5 — Service Identity, Package Info, Runtime Config
+- Ask: service_name, port (manual), description
+- Manual mode also: package_name, author, api_key, encryption_key (32 chars), redis config
+- Fast mode: auto-generate all above values; encryption_iv = first 16 chars of encryption_key
+
+### Phase 6 — Single Confirmation, Then Generate ALL Files
+
+Show summary with ALL values (auto-generated marked). Run validation:
+- BLOCKER: service name conflict, port conflict, key/iv wrong length, required fields missing
+Ask: "Confirm and generate all files? (yes / no / change a value)"
+ONE confirmation only — no per-file prompts after this.
+
+**Wave 1:** package.json, .env, .env.example, .gitignore, README.md,
+config/constants.js, config/template.js, logger/logging.js,
+utilities/encryption.js, languages/<lang>.js for each language,
+enc_dec.html (reactjs client) OR enc_dec.php (app client),
+pem/ + images/ + logger/logs/ directories
+
+**Wave 2:** config/database.js, utilities/ioRedis.js, utilities/response.js
+
+**Wave 3:** config/common.js, utilities/validator.js,
+utilities/notification.js, middleware/rateLimiter.js
+
+**Wave 4:** middleware/headerValidator.js,
+modules/v1/<ServiceName>/route.js, modules/v1/<ServiceName>/<service>_model.js,
+document/v1/swagger_doc.json (skeleton)
+
+**Wave 5:** modules/v1/route_manager.js, app.js
+
+**Wave 6:** Dockerfile, .dockerignore
 
-## Localizify Rules
-Only `headerValidator.js` and `response.js` may call `t()` or import localizify.
-All other files use `sendResponse()`, `getMessage()`, or `req.t("key")`.
-Never call `setLocale` from model files — race condition under concurrent requests.
+**After all waves:** generate IDE configs (.vscode/mcp.json, .cursor/mcp.json),
+generate/update docker-compose.yml at repo root.
 
-## Swagger Maintenance
-Patch `swagger_doc.json` only — never rewrite it.
-Add new path key only via `file_insert_after`. Update `info.version` timestamp.
+Call `context_write` → append service to context.services. Call `context_clear_scratchpad`.
 
-## JSDoc Standard (every exported function — no exceptions)
+---
+
+## /codeninja:api — Add API Endpoint
+
+1. Review 1–2 existing modules for naming/auth patterns — surface summary
+2. Ask: which service, API version (default v1)
+3. Ask: module name, HTTP method, route path, description
+4. Ask: primary table (from context.db.schema.tables), requires auth (yes/no)
+5. Confirm: "Generate [METHOD] [path] in [service]/modules/[version]/[Module]?"
+6. Generate:
+   - `modules/<v>/<Module>/route.js` — validation, middleware, res.json()
+   - `modules/<v>/<Module>/<module>_model.js` — parameterized queries only
+   - Append to `route_manager.js` via `file_insert_after` MCP — NEVER rewrite
+   - Patch `swagger_doc.json` via `file_insert_after` MCP — add path key only
+7. Call `context_write` — append to context.api_routes, update modules list
+
+---
+
+## Code Standards (every generated file)
+
+### JSDoc (every exported function — no exceptions)
 ```javascript
 /**
  * One-sentence description. Active voice.
- * @param {type} name - Description.
+ *
+ * @param {type} paramName - Description.
  * @returns {Promise<Object>} Description.
  */
 ```
-Middleware: `@middleware` tag, no `@returns`.
-Route comment: `// POST /path — Business purpose.` above route definition.
-No inline `//` inside function bodies. No file-level headers.
-
-## Encryption Selection
-| context.services[n].client_type | Library | Demo file |
-|---------------------------------|---------|-----------|
-| reactjs | crypto-js AES-256-CBC | enc_dec.html |
-| app | cryptlib AES-256-CBC | enc_dec.php |
-
-`encrypted_transport: true` → encrypt full response payload.
-`encrypted_transport: false` → plain JSON, no transport encryption.
-KEY and IV always from context — never hardcode.
-
-## Test Standards (Jest + Supertest)
-File: `tests/v1/<ModuleName>.test.js`
-Cover: happy path, each validation failure, auth failure, edge cases.
+
+### Route comments
+```javascript
+// POST /login — Authenticates user credentials and returns a session token.
+router.post('/login', async (req, res) => {
+```
+
+### Model return shape (always exactly this — no extra keys)
+```javascript
+return { responsecode: 1, responsemsg: 'success', responsedata: data };
+```
+
+### Encryption library selection
+- `client_type == "reactjs"` → use `crypto-js` + generate `enc_dec.html`
+- `client_type == "app"` → use `cryptlib` + generate `enc_dec.php`
+
+### DB driver selection
+- postgresql → `pg`
+- mysql → `mysql2`
+- mongodb → `mongoose`