codeninja 3.2.0 → 4.0.0

package/ide/antigravity/.agents/workflows/codeninja-integrate-api.md

@@ -1,115 +1,162 @@
+This workflow runs when user invokes /codeninja:integrate-api
+
 ---
-slash_command: /codeninja:integrate-api
-personas: [global-orchestrator, reactjs-frontend]
-skills: [mcp-and-context, reactjs, api-builder]
+type: workflow
+name: integrate-api
 description: >
-  Wire a ReactJS page's forms and action buttons to backend API calls
-  through apiHandler.js and apiClient.js. Adds loading states, error
-  display, and success feedback. Never touches validation or layout.
+  Wires a ReactJS page's forms and action buttons to backend API calls
+  through apiHandler.js and apiClient.js. Creates or updates submit
+  handler functions, adds loading states, and wires success/error
+  responses back to the UI. Never touches validation logic or component
+  layout — API integration only.
 ---
 
-# /codeninja:integrate-api
+# Workflow: @integrate-api
 
-## Before Running
-1. Call `context_check_stale`
-2. Call `context_read` — load `context.services` and `context.api_routes`
-3. Call `service_scan` — verify services on disk
+## Goal
+Connect the frontend page to the backend. After this workflow runs,
+every form submit and action button on the target page calls the
+correct API handler function, handles the loading state, and processes
+the response correctly.
 
 ## Rules
-- Target ONE specific page per run
+- Target one specific page per run
 - NEVER modify layout, CSS, or validation logic
-- ALWAYS use `apiHandler.js` for API calls — never call `axiosClient` directly from a page
-- ALWAYS add handler functions to `apiHandler.js` if the needed function doesn't exist
+- ALWAYS use `apiHandler.js` for API calls — never call `axiosClient`
+  directly from a page component
+- ALWAYS add handler functions to `apiHandler.js` if the needed function
+  does not already exist there — never inline API calls in the page
 - NEVER hardcode API endpoints in page files
 - ONE confirmation before any file is written
-- After writing files → call `context_write`
+- After writing files → run task: `write-context`
 
 ---
 
-## Execution — Full Step-by-Step
+## Step-by-Step Execution
+
+---
 
 ### Phase 1 — Target Selection
 
-**Step 1.** Ask: "Which ReactJS service?" (list ReactJS services from `context.services`)
-- Store: `context.current_action.service_name`
+1. Run task: `ask-react-target-service`
+   Stores: `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`
+2. Run task: `ask-page-path`
+   Stores: `context.current_action.page_path`
+   Stores: `context.current_action.page_name`
 
-**Step 3.** Ask: "What scope of integration?"
-1. All forms and buttons on this page
-2. Specific form or button only
-- Store: `context.current_action.api_integration_scope`
-- If specific → ask: "Which form or button?" → Store: `context.current_action.api_integration_target`
+3. Run task: `ask-api-integration-scope`
+   Stores: `context.current_action.api_integration_scope`
+   If scope == "specific" → also stores `context.current_action.api_integration_target`
 
 ---
 
 ### Phase 2 — Read Service Context
 
 Read from context:
-- `context.services[<service_name>].linked_service` → the NodeJS backend
-- `context.api_routes` filtered by linked NodeJS service → available API routes
+- `context.current_action.service_name` → the ReactJS service
+- `context.services[<service_name>].linked_service` → the backend NodeJS service name
+- `context.api_routes` filtered by the linked NodeJS service → available API routes
 
 Read from disk:
-- Full content of `context.current_action.page_path` (target page)
-- Full content of `src/api/apiHandler.js`
-- Full content of `src/api/apiClient.js` (read-only reference)
+- Full content of `context.current_action.page_path` (the target page)
+- Full content of `src/api/apiHandler.js` in the target service
+- Full content of `src/api/apiClient.js` in the target service (read-only reference)
 
 ---
 
 ### Phase 3 — Scan the Page for Integration Points
 
+Read the page file and identify every place that could trigger an API call:
+
 #### 3a — Forms
-For each `<form>` found:
-- Note the form's apparent purpose (infer from field names, labels, heading text)
-- Check if `onSubmit` is already connected
-- Check if form imports anything from `apiHandler.js`
+
+For each `<form>` element found:
+  - Note the form's apparent purpose (login, register, search, update
+    profile, etc.) — infer from field names, labels, heading text nearby
+  - Check if an `onSubmit` handler is already connected:
+    - `<form onSubmit={...}>` → handler exists, note the function name
+    - No `onSubmit` → no handler yet
+  - Check if a submit button exists: `<button type="submit">` or
+    `<input type="submit">`
+  - Note whether the form already imports anything from `apiHandler.js`
 
 #### 3b — Action Buttons
-For each `<button>` NOT a submit button:
-- Check if `onClick` is connected
-- Infer action from button text: Delete/Remove → delete, Edit/Update → update,
-  Save → save/create, Logout → logout, Load more/Next → pagination, Export/Download → export
+
+For each `<button>` or clickable element that is NOT a submit button:
+  - Check if an `onClick` handler is connected
+  - Infer the action from button text or aria-label:
+    - "Delete", "Remove" → delete action
+    - "Edit", "Update" → update action
+    - "Save" → save/create action
+    - "Logout", "Sign out" → logout action
+    - "Load more", "Next page" → pagination/fetch action
+    - "Export", "Download" → export action
+    - "Approve", "Reject" → status change action
+  - Note if the handler already contains an API call
 
 #### 3c — Existing API Calls
-Detect any existing API calls:
-- Imports from `apiHandler.js` (existing — note them)
-- Direct `axiosClient` calls (flag — should be moved to apiHandler)
-- `fetch(` or `axios.` direct calls (flag — should be moved)
 
-If scope == "specific" → focus only on the matching form/button.
+Detect any API calls already in the file:
+  - Imports from `apiHandler.js`
+  - `axiosClient` direct calls (flag these — they should be moved to apiHandler)
+  - `fetch(` or `axios.` calls (flag — should be moved to apiHandler)
+
+If scope == "specific":
+  Apply the same scan but focus only on the form or action matching
+  `context.current_action.api_integration_target`. Other forms/buttons
+  are noted but not modified.
 
 ---
 
 ### Phase 4 — Match Forms to API Routes
 
-For each integration point, determine which API route it should call:
+For each integration point found, determine which backend API route it
+should call. Use this priority:
+
+1. **Exact match** — an `apiHandler.js` function already exists for
+   this purpose (e.g. `webLogin` for a login form). Use it as-is.
 
-1. **Exact match** — `apiHandler.js` function already exists for this purpose → use as-is
-2. **Route match** — matching route exists in `context.api_routes` for linked backend →
-   new handler function will be added to `apiHandler.js`
-3. **No match** — no suitable route exists yet → scaffold with TODO placeholder
+2. **Route match** — a route exists in `context.api_routes` for the
+   linked backend service that matches the form's apparent purpose.
+   A new handler function will be added to `apiHandler.js` for it.
 
-Record: `{ form_purpose, handler_function_name, route_path, route_method, match_type }`
+3. **No match** — no suitable route exists yet in either place.
+   The integration plan will note this as a gap. The form's submit
+   handler will be scaffolded with a `// TODO: connect to API` comment
+   and a placeholder structure so the page is functional once the
+   route is added. Do NOT create a route in the backend — that is
+   `@create-api`'s job.
+
+For each match or gap, record:
+  `{ form_purpose, handler_function_name, route_path, route_method,
+     match_type: "existing_handler" | "new_handler" | "no_route" }`
 
 ---
 
 ### Phase 5 — Design the Integration
 
-For each integration point:
+For each integration point, design what needs to be generated:
+
+#### 5a — State requirements
 
-#### State requirements
-- `loading` state — boolean, false by default
-- `error` state — string or null
-- Response data state based on form type:
-  - Auth forms → no data state (session stored by apiHandler)
-  - List/search → `data` state (array, [])
-  - Single item → `item` state (object, null)
-  - Delete/update → list refresh or redirect
+Every API call needs at minimum:
+- `loading` state — boolean, `false` by default
+- `error` state — string or null, for displaying API error messages
+  to the user
+- Response data state — depends on the form type:
+  - Auth forms (login/register) → no response data state needed
+    (session is stored by apiHandler)
+  - List/search forms → `data` state (array, `[]` default)
+  - Single-item fetch → `item` state (object, `null` default)
+  - Delete/update → may use a list refresh or a redirect
 
-#### Submit handler patterns
+Identify existing state in the page to avoid duplicates. Only add
+state that does not already exist.
 
-**Auth / destructive (login, delete, logout):**
+#### 5b — Submit handler pattern
+
+**Auth / destructive action pattern (login, delete, logout):**
 ```jsx
 const handle[Action] = async (e) => {
   e?.preventDefault();
@@ -118,14 +165,15 @@ const handle[Action] = async (e) => {
   const res = await [handlerFunction]({ ...formData });
   setLoading(false);
   if (res?.code === 1) {
-    navigate('/dashboard');
+    // success — navigate or show confirmation
+    navigate('/dashboard'); // use react-router useNavigate
   } else {
     setError(res?.message || 'Something went wrong. Please try again.');
   }
 };
 ```
 
-**Data fetch / load (get list, get details):**
+**Data fetch / load pattern (get list, get details):**
 ```jsx
 const fetch[Resource] = async () => {
   setLoading(true);
@@ -138,10 +186,11 @@ const fetch[Resource] = async () => {
     setError(res?.message || 'Failed to load data. Please try again.');
   }
 };
-// Also add: useEffect(() => { fetch[Resource](); }, []);
 ```
+Also add a `useEffect(() => { fetch[Resource](); }, [])` call to
+load data on component mount if appropriate.
 
-**Create / Update (form submit):**
+**Create / Update pattern (form submit):**
 ```jsx
 const handle[Action] = async (e) => {
   e?.preventDefault();
@@ -150,34 +199,72 @@ const handle[Action] = async (e) => {
   const res = await [handlerFunction](formData);
   setLoading(false);
   if (res?.code === 1) {
+    // success — show message or reset form
     setSuccessMsg(res?.message || '[Action] successful.');
-    resetForm();
+    resetForm(); // only if a form reset function exists
   } else {
     setError(res?.message || 'Something went wrong. Please try again.');
   }
 };
 ```
 
-#### Loading feedback
+#### 5c — Loading state feedback
+
+Add a `disabled={loading}` prop to the submit button or action trigger.
+Also add visual feedback text inside the button:
 ```jsx
 <button type="submit" disabled={loading}>
   {loading ? 'Please wait...' : '[Original Button Text]'}
 </button>
 ```
 
-#### Error display (above submit button)
+#### 5d — Error display
+
+Add an error display block just above the submit button:
 ```jsx
 {error && <p className={styles.apiError}>{error}</p>}
 ```
 
-#### Success display (for non-navigating actions)
+Add to the page's `.module.css`:
+```css
+.apiError {
+  color: #dc3545;
+  font-size: 0.875rem;
+  margin-bottom: 0.75rem;
+  padding: 0.5rem 0.75rem;
+  background-color: #fff5f5;
+  border: 1px solid #f5c6cb;
+  border-radius: 4px;
+}
+```
+
+#### 5e — Success feedback (for non-navigating actions)
+
+If the action does not navigate away after success, add a success
+message state and display:
+```jsx
+const [successMsg, setSuccessMsg] = React.useState('');
+```
 ```jsx
 {successMsg && <p className={styles.successMsg}>{successMsg}</p>}
 ```
+```css
+.successMsg {
+  color: #155724;
+  font-size: 0.875rem;
+  margin-bottom: 0.75rem;
+  padding: 0.5rem 0.75rem;
+  background-color: #d4edda;
+  border: 1px solid #c3e6cb;
+  border-radius: 4px;
+}
+```
 
 ---
 
-### Phase 6 — Show Integration Plan
+### Phase 6 — Build and Show Integration Plan
+
+Display the integration plan before writing anything:
 
 ```
 ┌──────────────────────────────────────────────────────┐
@@ -190,40 +277,48 @@ const handle[Action] = async (e) => {
 │ INTEGRATIONS                                         │
 │                                                      │
 │ ① Login Form → webLogin()                            │
-│   Route    : POST /login                             │
-│   Handler  : webLogin (already in apiHandler.js)     │
-│   State add: loading, error                          │
-│   Pattern  : auth/destructive                        │
+│   Route     : POST /login                            │
+│   Handler   : webLogin (already in apiHandler.js)    │
+│   State add : loading, error                         │
+│   Pattern   : auth/destructive                       │
 │   On success: navigate('/dashboard')                 │
 │                                                      │
 │ ② Delete Button → deleteUser()                       │
-│   Route    : DELETE /users/:id                       │
-│   Handler  : deleteUser (NEW → will add to           │
-│              apiHandler.js)                          │
-│   Pattern  : destructive                             │
+│   Route     : DELETE /users/:id                      │
+│   Handler   : deleteUser (NEW — will add to           │
+│               apiHandler.js)                         │
+│   State add : deleteLoading, deleteError             │
+│   Pattern   : destructive                            │
 │   On success: refresh user list                      │
 ├──────────────────────────────────────────────────────┤
-│ GAPS (no backend route yet)                          │
-│  ③ Export CSV Button — no route exists yet           │
-│     Will add TODO placeholder                        │
+│ GAPS (no matching route yet)                         │
+│  ③ Export CSV Button — no backend route for this yet │
+│     Will add a TODO placeholder                      │
 ├──────────────────────────────────────────────────────┤
 │ FILES TO MODIFY                                      │
-│  → src/pages/[PageName]/index.jsx                   │
-│  → src/pages/[PageName]/[PageName].module.css       │
-│  → src/api/apiHandler.js ([n] new function(s))      │
+│  → src/pages/[PageName]/index.jsx                    │
+│  → src/pages/[PageName]/[PageName].module.css        │
+│  → src/api/apiHandler.js (add deleteUser function)   │
 └──────────────────────────────────────────────────────┘
 ```
 
-Ask: "Apply this integration plan? (yes / no / adjust)"
+Ask exactly this question:
+"Apply this integration plan? (yes / no / adjust)"
+
+- If yes → proceed to Phase 7
+- If no → abort. Nothing is written.
+- If adjust → ask what to change (different handler, different on-success
+  action, skip an integration point). Apply and re-display.
 
 ---
 
 ### Phase 7 — Apply Integration
 
-#### 7a — Update apiHandler.js (new functions only)
+#### 7a — Update apiHandler.js (if new functions needed)
+
+For each integration with `match_type == "new_handler"`:
+Surgically append to `src/api/apiHandler.js`:
 
-For each `match_type == "new_handler"`:
-Append to `src/api/apiHandler.js`:
 ```jsx
 /**
  * [Route description from context.api_routes or inferred].
@@ -232,94 +327,100 @@ Append to `src/api/apiHandler.js`:
  * @returns {Promise<Object>} API response.
  */
 export async function [functionName](data) {
-  const res = await axiosClient.[method]('[route_path]', data);
+  const res = await axiosClient.post('[route_path]', data);
   return res;
 }
 ```
-Use correct method: `.get`, `.post`, `.put`, `.patch`, `.delete`.
-For DELETE/GET with ID: `axiosClient.delete(\`/users/${data.id}\`)`
 
-For `match_type == "no_route"`:
+Use the correct HTTP method — `axiosClient.get`, `.post`, `.put`,
+`.patch`, `.delete` — matching the route method.
+
+For DELETE or GET with ID: use template string for the path:
+```jsx
+const res = await axiosClient.delete(`/users/${data.id}`);
+```
+
+For gaps (`match_type == "no_route"`):
 ```jsx
 /**
- * TODO: Connect to backend route once created via /codeninja:api.
+ * TODO: Connect to backend route once created via @create-api.
+ *
+ * @param {Object} data - Request payload.
+ * @returns {Promise<Object>} API response.
  */
 export async function [functionName](data) {
+  // TODO: Replace with actual route when backend is ready.
+  // Suggested: POST /[suggested_path]
   console.warn('[functionName] is not yet connected to a backend route.');
   return { code: 0, message: 'API not connected yet.' };
 }
 ```
 
-#### 7b — Update the page file (surgical edits only)
+#### 7b — Update the page file
+
+Read the current page file. Apply all changes surgically:
 
-1. Add imports for new apiHandler functions (only new ones):
+1. **Add imports** for apiHandler functions (only the new ones):
    ```jsx
    import { webLogin, deleteUser } from '../../api/apiHandler';
    ```
-   Add `useNavigate` if any handler navigates:
+   Also add `useNavigate` from react-router-dom if any handler navigates:
    ```jsx
    import { useNavigate } from 'react-router-dom';
    ```
 
-2. Add state declarations inside component:
+2. **Add state declarations** inside the component function:
    ```jsx
    const [loading, setLoading] = React.useState(false);
    const [error, setError] = React.useState(null);
-   const navigate = useNavigate(); // if navigate is used
    ```
+   Add `const navigate = useNavigate();` if navigate is used.
 
-3. Add handler functions just before the return statement.
-   If a handler already exists → add API call logic inside it, don't create duplicate.
+3. **Add or update handler functions** inside the component:
+   Insert each handler function just before the return statement.
+   If a handler already exists (from validation or prior code) →
+   add only the API call logic inside it, not a new function.
 
-4. Wire form `onSubmit` / button `onClick`:
-   - `<form onSubmit={handle[Action]}>`
-   - `<button onClick={handle[Action]}>`
+4. **Wire the form's onSubmit / button's onClick**:
+   - If `<form onSubmit={existing}>` → rename existing handler and
+     call it inside the new handler (after the API call succeeds)
+   - If no onSubmit → add `onSubmit={handle[Action]}`
+   - If button has no onClick → add `onClick={handle[Action]}`
 
-5. Add `disabled={loading}` and conditional button text to submit buttons.
+5. **Add loading state to buttons**:
+   Locate each submit button / action button. Add `disabled={loading}`
+   and the conditional button text as designed in Phase 5c.
 
-6. Add error and success display elements adjacent to submit buttons.
+6. **Add error and success display elements**:
+   Place the error `<p>` above the submit button.
+   Place the success `<p>` below the submit button (for non-nav actions).
 
-7. Add `useEffect` for data-fetching handlers (load on mount).
+7. **Add useEffect for data fetching** if applicable (Phase 5b).
 
-#### 7c — Update page CSS module
-Add `.apiError` and `.successMsg` classes (if not already present):
-```css
-.apiError {
-  color: #dc3545;
-  font-size: 0.875rem;
-  margin-bottom: 0.75rem;
-  padding: 0.5rem 0.75rem;
-  background-color: #fff5f5;
-  border: 1px solid #f5c6cb;
-  border-radius: 4px;
-}
+> **Multi-agent:** Delegate to `reactjs-frontend` via Task invocation for parallel execution.
+> Read `.codeninja/tasks/` before applying API integration changes.
 
-.successMsg {
-  color: #155724;
-  font-size: 0.875rem;
-  margin-bottom: 0.75rem;
-  padding: 0.5rem 0.75rem;
-  background-color: #d4edda;
-  border: 1px solid #c3e6cb;
-  border-radius: 4px;
-}
-```
+#### 7c — Update the page's CSS module
+
+Add `.apiError` and `.successMsg` classes to the page's `.module.css`
+if they are not already there. Do not overwrite existing definitions.
 
 ---
 
-### Phase 8 — Finalize
+### Phase 8 — Write Context and Report
 
-**Step 1.** Call `context_write`:
+Run task: `write-context` with:
 - Append to `context.services[<service_name>].integrated_pages`:
-  `{ page, integrations: [{ form_purpose, handler, route }], timestamp: ISO now }`
+  `{ page, integrations: [list of { form_purpose, handler, route }], timestamp: ISO now }`
 - Set `last_command` = "integrate-api"
-- Append to `change_log`
+- Append to top-level `change_log`:
+  `{ timestamp, command: "integrate-api", action: "Wired [n] API calls in [page]", affected_files: [...] }`
+- After write-context → call MCP tool `context_clear_scratchpad` with keys: ["current_action"]
 
-**Step 2.** Call `context_clear_scratchpad` with keys: ["current_action"]
+Display completion report:
 
-**Step 3.** Show completion report:
 ```
-/codeninja:integrate-api Complete
+@integrate-api Complete
 ─────────────────────────────────────────
 Page          : [page_name]
 Integrations  : [n] connected, [n] placeholders
@@ -330,7 +431,23 @@ Integrations  : [n] connected, [n] placeholders
 ─────────────────────────────────────────
 [If gaps exist:]
 ⚠ [n] action(s) have no backend route yet.
-  Placeholders added. Run /codeninja:api to create backend routes,
-  then re-run /codeninja:integrate-api to connect them.
+  Placeholders added — run @create-api to scaffold the backend routes,
+  then re-run @integrate-api to connect them.
 ─────────────────────────────────────────
 ```
+
+Run task: `show-final-summary`
+
+---
+
+## What This Workflow Does NOT Do
+
+- Does not add or modify form validation — that is `@validate-page`'s job
+- Does not create new pages or components
+- Does not modify App.jsx routing
+- Does not touch backend files (NodeJS service)
+- Does not add authentication/session management beyond what apiHandler
+  already provides
+- Does not add global state (Redux, Context API)
+- Does not handle file uploads (beyond wiring the existing input to
+  an API call with FormData if the input type is "file")