codeninja 2.0.0

package/commands/test.workflow.md

@@ -0,0 +1,40 @@
+---
+type: workflow
+name: test
+description: >
+  Generate or run Jest + Supertest tests for a module in an existing NodeJS service.
+---
+
+# Workflow: @test
+
+## Goal
+Generate a complete test file for an existing API module, covering happy path,
+validation errors, auth failures, and edge cases.
+
+---
+
+## Step-by-Step Execution
+
+1. Run task: `ask-target-service`
+2. Run task: `ask-module-name` (list available modules from context)
+3. Run task: `ask-test-type`
+   - Options: generate new tests, run existing tests
+   - Stores: `context.current_test.type`
+
+4. If `generate`:
+   - Read module's `route.js`, `_validator.js`, `_service.js` from disk
+   - Read `context.api_routes` for this module
+   - Delegate to `nodejs-agent` → generate `tests/v1/<Module>.test.js`
+   - Test file covers:
+     - 200 happy path for each endpoint
+     - 400 validation failures
+     - 401 missing/invalid API key
+     - 404 not found (where applicable)
+     - 500 simulated service error
+
+5. If `run`:
+   - Execute: `npm test` inside service directory
+   - Parse results and display pass/fail summary
+
+6. Run task: `write-context` → update `context.services[<n>].tests`
+7. Run task: `show-final-summary`

package/commands/validate-page.workflow.md

@@ -0,0 +1,543 @@
+---
+type: workflow
+name: validate-page
+description: >
+  Adds complete client-side form validation to a specific ReactJS page.
+  Scans all input, select, and textarea fields, assigns name and id
+  attributes where missing, installs the chosen validation library if
+  needed, wires up validation logic, and generates standard user-facing
+  error messages for every field. Never touches API calls or business logic.
+---
+
+# Workflow: @validate-page
+
+## Goal
+Take a page that has a form and make every field fully validated with
+clear, user-friendly error messages before the form is ever submitted.
+
+## 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 any 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 — id = name = the field's semantic name in camelCase
+- ONE confirmation before any file is written
+
+---
+
+## Step-by-Step Execution
+
+---
+
+### Phase 1 — Target Selection
+
+1. Run task: `ask-react-target-service`
+   Stores: `context.current_action.service_name`
+
+2. Run task: `ask-page-path`
+   Stores: `context.current_action.page_path`
+   Stores: `context.current_action.page_name`
+
+3. Run task: `ask-validation-library`
+   Stores: `context.current_action.validation_library`
+
+---
+
+### Phase 2 — Scan the Page
+
+Read the full page file at `context.current_action.page_path`.
+
+#### 2a — Find All Form Elements
+
+Scan the JSX for every `<form>`, `<input>`, `<select>`, `<textarea>`,
+and `<button type="submit">` element.
+
+For each `<input>` found, record:
+  - `type` attribute (text, email, password, number, tel, checkbox,
+    radio, file, hidden, date, etc.)
+  - `name` attribute (if present)
+  - `id` attribute (if present)
+  - `value` or `defaultValue` binding (if present)
+  - `onChange` handler (if present)
+  - `required` attribute (if present)
+  - `placeholder` text (if present)
+  - Any existing validation attributes (minLength, maxLength, pattern, min, max)
+  - Any adjacent label text (look for `<label htmlFor="...">` or a
+    `<label>` immediately before/after the input in the JSX)
+  - Any existing error display element nearby
+    (look for `<span className="error">`, `<p className={styles.error}>`,
+    `{errors.<n>}` patterns, etc.)
+
+For each `<select>` found, record:
+  - `name`, `id`
+  - The `<option>` values available
+  - Whether a default empty option exists
+
+For each `<textarea>` found, record:
+  - `name`, `id`
+  - `rows`, `cols`
+  - Any character limit hints
+
+#### 2b — Group Fields Into Forms
+
+If multiple `<form>` elements exist on the page, group fields by their
+parent `<form>`. Each form gets its own validation schema.
+
+If no `<form>` element exists but inputs are present → treat all inputs
+as belonging to one implicit form. Note this in the plan.
+
+#### 2c — Detect Existing Validation
+
+Check for any of these patterns already in the file:
+  - `yup.object()` or `yup.string()` imports → Yup schema exists
+  - `useForm()` from react-hook-form → RHF already wired
+  - `.parsley()` calls → Parsley already initialized
+  - Manual `if (!value)` style checks in submit handler
+  - Any `errors` state object
+
+If validation already exists for a field → mark that field as
+"already validated" and skip it. Only add what is missing.
+
+---
+
+### Phase 3 — Infer Field Semantics and Error Messages
+
+For each field, determine its semantic type to generate the correct
+error message. Use label text first, then name attribute, then
+placeholder, then input type as fallback.
+
+#### Semantic type detection rules:
+
+| Signal | Semantic type |
+|---|---|
+| label/name/placeholder contains "first name" | first_name |
+| label/name/placeholder contains "last name" | last_name |
+| label/name/placeholder contains "full name" or just "name" | full_name |
+| label/name/placeholder contains "email" | email |
+| label/name/placeholder contains "phone" or "mobile" | phone |
+| label/name/placeholder contains "password" and no "confirm" | password |
+| label/name/placeholder contains "confirm" and "password" | confirm_password |
+| label/name/placeholder contains "username" | username |
+| label/name/placeholder contains "address" | address |
+| label/name/placeholder contains "city" | city |
+| label/name/placeholder contains "zip" or "postal" | zip_code |
+| label/name/placeholder contains "country" | country |
+| label/name/placeholder contains "state" or "province" | state |
+| label/name/placeholder contains "date" or "dob" or "birth" | date |
+| label/name/placeholder contains "amount" or "price" | amount |
+| label/name/placeholder contains "description" or "message" | description |
+| label/name/placeholder contains "otp" or "code" or "pin" | otp |
+| input type == "file" | file_upload |
+| input type == "checkbox" and label contains "agree" or "terms" | terms |
+| select with no clear label | dropdown |
+| anything else | generic |
+
+#### Standard error messages per semantic type:
+
+| Semantic type | Required error | Format/constraint error |
+|---|---|---|
+| first_name | "Please enter your first name." | "First name must be at least 2 characters." |
+| last_name | "Please enter your last name." | "Last name must be at least 2 characters." |
+| full_name | "Please enter your full name." | "Full name must be at least 3 characters." |
+| email | "Please enter your email address." | "Please enter a valid email address." |
+| phone | "Please enter your phone number." | "Please enter a valid phone number." |
+| password | "Please enter your password." | "Password must be at least 8 characters." |
+| confirm_password | "Please confirm your password." | "Password and confirm password do not match." |
+| username | "Please enter a username." | "Username must be 3–20 characters, letters and numbers only." |
+| address | "Please enter your address." | — |
+| city | "Please enter your city." | — |
+| zip_code | "Please enter your zip/postal code." | "Please enter a valid zip/postal code." |
+| country | "Please select your country." | — |
+| state | "Please select your state/province." | — |
+| date | "Please select a date." | "Please enter a valid date." |
+| amount | "Please enter an amount." | "Please enter a valid amount greater than 0." |
+| description | "Please enter a description." | — |
+| otp | "Please enter the OTP." | "OTP must be [n] digits." (n from maxLength) |
+| file_upload | "Please select a file." | "File size must not exceed [n]MB." (only if max is known) |
+| terms | "Please accept the terms and conditions." | — |
+| dropdown | "Please make a selection." | — |
+| generic | "This field is required." | — |
+
+These messages are hardcoded strings in the generated validation logic.
+Do not use i18n keys for validation messages — they are frontend-only,
+not served by the backend language system.
+
+---
+
+### Phase 4 — Assign Missing name and id Attributes
+
+For each field that is missing `name` or `id`:
+
+1. Derive the field name from its label text or placeholder (in that order):
+   - Strip non-alphanumeric characters
+   - Convert to camelCase
+   - Examples: "First Name" → `firstName`, "Email Address" → `emailAddress`,
+     "Date of Birth" → `dateOfBirth`
+
+2. If no label or placeholder → use semantic type as the name:
+   `email`, `password`, `phone`, etc.
+
+3. If the field name would duplicate another field in the same form →
+   append a number: `phone2`, `address2`
+
+4. Set both `name` and `id` to the same derived value.
+
+Record: `{ original_element_position, assigned_name, assigned_id }`
+
+---
+
+### Phase 5 — Build Validation Plan
+
+Show the user a complete plan before writing anything:
+
+```
+┌──────────────────────────────────────────────────────┐
+│              VALIDATION PLAN                         │
+├──────────────────────────────────────────────────────┤
+│ Page        : [page_name]                            │
+│ Library     : [validation_library]                   │
+│ Install pkg : [package_name] (if needed)             │
+├──────────────────────────────────────────────────────┤
+│ FIELDS FOUND                                         │
+│  ✓ firstName  (text)    — "Please enter your         │
+│                           first name."               │
+│  ✓ lastName   (text)    — "Please enter your         │
+│                           last name."                │
+│  ✓ email      (email)   — "Please enter your         │
+│                           email address."            │
+│  ✓ password   (password)— "Please enter your         │
+│                           password."                 │
+│  ✓ confirmPw  (password)— "Password and confirm      │
+│                           password do not match."    │
+│                                                      │
+│ FIELDS SKIPPED (already validated)                   │
+│  — phone  (has existing required check)              │
+├──────────────────────────────────────────────────────┤
+│ ATTRIBUTES TO ASSIGN                                 │
+│  confirmPassword input → add name="confirmPassword"  │
+│                          add id="confirmPassword"    │
+├──────────────────────────────────────────────────────┤
+│ FILES TO MODIFY                                      │
+│  → src/pages/[PageName]/index.jsx                    │
+│  → package.json (add: [library_package])             │
+└──────────────────────────────────────────────────────┘
+```
+
+Ask exactly this question:
+"Apply this validation plan? (yes / no / adjust)"
+
+- If yes → proceed to Phase 6
+- If no → abort. Nothing is written.
+- If adjust → ask what to change (field name, error message, skip a
+  field). Apply and re-display.
+
+---
+
+### Phase 6 — Apply Validation by Library
+
+Read the current page file. Apply all edits surgically. Never rewrite
+the whole file — only insert and modify what is needed.
+
+---
+
+#### If validation_library == "yup"
+
+**Imports to add at the top of the file:**
+```jsx
+import * as Yup from 'yup';
+```
+
+**Schema to create above the component function:**
+```jsx
+const validationSchema = Yup.object({
+  firstName: Yup.string()
+    .required('Please enter your first name.')
+    .min(2, 'First name must be at least 2 characters.'),
+  email: Yup.string()
+    .required('Please enter your email address.')
+    .email('Please enter a valid email address.'),
+  password: Yup.string()
+    .required('Please enter your password.')
+    .min(8, 'Password must be at least 8 characters.'),
+  confirmPassword: Yup.string()
+    .required('Please confirm your password.')
+    .oneOf([Yup.ref('password')], 'Password and confirm password do not match.'),
+  // ... one entry per field
+});
+```
+
+**State to add inside the component:**
+```jsx
+const [errors, setErrors] = React.useState({});
+```
+
+**Validation function to add inside the component:**
+```jsx
+const validateForm = async (values) => {
+  try {
+    await validationSchema.validate(values, { abortEarly: false });
+    setErrors({});
+    return true;
+  } catch (err) {
+    const newErrors = {};
+    err.inner.forEach((e) => { newErrors[e.path] = e.message; });
+    setErrors(newErrors);
+    return false;
+  }
+};
+```
+
+**Validation gate to add in the submit handler:**
+Locate the existing submit handler (look for `onSubmit`, `handleSubmit`,
+`onClick` on a submit button). Add a validation gate at the very top:
+```jsx
+const isValid = await validateForm({ firstName, lastName, email, ... });
+if (!isValid) return;
+```
+
+**Error display elements to add under each input:**
+```jsx
+{errors.firstName && <span className={styles.errorMsg}>{errors.firstName}</span>}
+```
+
+**CSS class to add to the page's `.module.css`:**
+```css
+.errorMsg {
+  display: block;
+  color: #dc3545;
+  font-size: 0.813rem;
+  margin-top: 0.25rem;
+}
+```
+
+---
+
+#### If validation_library == "parsley"
+
+**In `public/index.html` (add before `</body>`):**
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/parsley.js/2.9.2/parsley.min.js"></script>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/parsley.js/2.9.2/parsley.min.css"/>
+```
+
+**Add `data-parsley-*` attributes to each field in JSX:**
+```jsx
+<input
+  type="email"
+  name="email"
+  id="email"
+  required
+  data-parsley-required="true"
+  data-parsley-required-message="Please enter your email address."
+  data-parsley-type="email"
+  data-parsley-type-message="Please enter a valid email address."
+/>
+```
+
+**Initialize Parsley on the form via useEffect:**
+```jsx
+React.useEffect(() => {
+  if (window.$) {
+    window.$('#[formId]').parsley();
+  }
+}, []);
+```
+
+**Add `id` to the `<form>` element** if not already present.
+Derive form id from: `[pageName]Form` in camelCase (e.g. `loginForm`).
+
+**Validation gate in submit handler:**
+```jsx
+if (window.$ && !window.$('#loginForm').parsley().validate()) return;
+```
+
+---
+
+#### If validation_library == "react-hook-form"
+
+**Imports to add:**
+```jsx
+import { useForm } from 'react-hook-form';
+```
+
+**Hook setup inside component (add near top of function body):**
+```jsx
+const { register, handleSubmit, watch, formState: { errors } } = useForm();
+```
+
+**Replace or wrap the existing form's onSubmit:**
+```jsx
+<form onSubmit={handleSubmit(onSubmit)}>
+```
+Where `onSubmit` is the existing submit handler — rename it if needed
+to avoid conflict with RHF's `handleSubmit` parameter name.
+
+**Add `{...register(...)}` to each input:**
+```jsx
+<input
+  type="email"
+  id="email"
+  {...register('email', {
+    required: 'Please enter your email address.',
+    pattern: {
+      value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+      message: 'Please enter a valid email address.'
+    }
+  })}
+/>
+```
+
+**For confirm password — use `watch`:**
+```jsx
+{...register('confirmPassword', {
+  required: 'Please confirm your password.',
+  validate: (val) => val === watch('password') ||
+    'Password and confirm password do not match.'
+})}
+```
+
+**Error display elements after each input:**
+```jsx
+{errors.email && <span className={styles.errorMsg}>{errors.email.message}</span>}
+```
+
+**CSS class** (same `.errorMsg` class as Yup — add to module.css if not present).
+
+**Remove any now-redundant `value` and `onChange` props** from inputs
+that are fully managed by RHF's `register()`. Only remove these if they
+were purely for controlled form state — never remove them if they are
+used for other purposes (e.g. to drive conditional rendering).
+
+---
+
+#### If validation_library == "validatorjs"
+
+**Imports to add:**
+```jsx
+import validator from 'validator';
+```
+
+**State to add inside component:**
+```jsx
+const [errors, setErrors] = React.useState({});
+```
+
+**Validation function to add inside component:**
+Generate one validation function that checks each field individually:
+```jsx
+const validateForm = () => {
+  const newErrors = {};
+  if (!firstName || firstName.trim().length < 2) {
+    newErrors.firstName = 'Please enter your first name.';
+  }
+  if (!email || !validator.isEmail(email)) {
+    newErrors.email = validator.isEmpty(email ?? '')
+      ? 'Please enter your email address.'
+      : 'Please enter a valid email address.';
+  }
+  if (!password || password.length < 8) {
+    newErrors.password = !password
+      ? 'Please enter your password.'
+      : 'Password must be at least 8 characters.';
+  }
+  if (password !== confirmPassword) {
+    newErrors.confirmPassword = 'Password and confirm password do not match.';
+  }
+  setErrors(newErrors);
+  return Object.keys(newErrors).length === 0;
+};
+```
+
+**Validation gate in submit handler:**
+```jsx
+if (!validateForm()) return;
+```
+
+**Error display and CSS** — same pattern as Yup.
+
+---
+
+#### If validation_library == "custom"
+
+Generate the same `validateForm` function as the validatorjs pattern
+but WITHOUT any library imports. Use only native JavaScript:
+  - `value.trim().length > 0` for required checks
+  - `/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)` for email format
+  - `value.length >= 8` for minimum length
+  - `value === otherValue` for match checks
+  - `/^\d+$/.test(value)` for numeric checks
+
+No new packages. No imports beyond React.
+
+**Error display and CSS** — same pattern as Yup.
+
+---
+
+### Phase 7 — Install Package (if needed)
+
+If `validation_library` is one of: `yup`, `react-hook-form`, `validatorjs`
+AND the package is NOT already in the service's `package.json`:
+
+Read the current `package.json` for the target service.
+Add the package 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 to user:
+"📦 Package added to package.json. Run `npm install` in [service_name]/
+before testing."
+
+For `parsley` → scripts added to `public/index.html` via CDN. No npm install needed.
+For `custom` → no package needed.
+
+---
+
+### Phase 8 — Write Context and Report
+
+Run task: `write-context` with:
+- Append to `context.services[<service_name>].validated_pages`:
+  `{ page, library, fields_validated: [list], timestamp: ISO now }`
+- Set `last_command` = "validate-page"
+- Append to top-level `change_log`:
+  `{ timestamp, command: "validate-page", action: "Added [library] validation to [page]", affected_files: [...] }`
+- After write-context → call MCP tool `context_clear_scratchpad` with keys: ["current_action"]
+
+Display completion report:
+
+```
+@validate-page Complete
+─────────────────────────────────────────
+Page       : [page_name]
+Library    : [validation_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)]
+─────────────────────────────────────────
+```
+
+Run task: `show-final-summary`
+
+---
+
+## What This Workflow Does NOT Do
+
+- Does not add server-side validation — backend validation is
+  handled by the NodeJS service's validators
+- Does not add validation to non-form elements (buttons, nav links)
+- Does not modify apiHandler.js or apiClient.js
+- Does not add authentication logic
+- Does not add success/error toast notifications — those belong in
+  the API integration layer (@integrate-api)
+- Does not validate dynamic fields (fields added/removed at runtime) —
+  only static JSX fields present in the file at analysis time