codeninja 2.0.0

package/commands/integrate-api.workflow.md

@@ -0,0 +1,448 @@
+---
+type: workflow
+name: integrate-api
+description: >
+  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.
+---
+
+# Workflow: @integrate-api
+
+## 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
+- NEVER modify layout, CSS, or validation logic
+- 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 → run task: `write-context`
+
+---
+
+## 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-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.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` (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>` 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>` 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 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 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.
+
+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.
+
+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, design what needs to be generated:
+
+#### 5a — State requirements
+
+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
+
+Identify existing state in the page to avoid duplicates. Only add
+state that does not already exist.
+
+#### 5b — Submit handler pattern
+
+**Auth / destructive action pattern (login, delete, logout):**
+```jsx
+const handle[Action] = async (e) => {
+  e?.preventDefault();
+  setLoading(true);
+  setError(null);
+  const res = await [handlerFunction]({ ...formData });
+  setLoading(false);
+  if (res?.code === 1) {
+    // success — navigate or show confirmation
+    navigate('/dashboard'); // use react-router useNavigate
+  } else {
+    setError(res?.message || 'Something went wrong. Please try again.');
+  }
+};
+```
+
+**Data fetch / load pattern (get list, get details):**
+```jsx
+const fetch[Resource] = async () => {
+  setLoading(true);
+  setError(null);
+  const res = await [handlerFunction]({ ...filters });
+  setLoading(false);
+  if (res?.code === 1) {
+    setData(res?.data ?? []);
+  } else {
+    setError(res?.message || 'Failed to load data. Please try again.');
+  }
+};
+```
+Also add a `useEffect(() => { fetch[Resource](); }, [])` call to
+load data on component mount if appropriate.
+
+**Create / Update pattern (form submit):**
+```jsx
+const handle[Action] = async (e) => {
+  e?.preventDefault();
+  setLoading(true);
+  setError(null);
+  const res = await [handlerFunction](formData);
+  setLoading(false);
+  if (res?.code === 1) {
+    // success — show message or reset form
+    setSuccessMsg(res?.message || '[Action] successful.');
+    resetForm(); // only if a form reset function exists
+  } else {
+    setError(res?.message || 'Something went wrong. Please try again.');
+  }
+};
+```
+
+#### 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>
+```
+
+#### 5d — Error display
+
+Add an error display block just above the submit button:
+```jsx
+{error && <p className={styles.apiError}>{error}</p>}
+```
+
+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 — Build and Show Integration Plan
+
+Display the integration plan before writing anything:
+
+```
+┌──────────────────────────────────────────────────────┐
+│             API INTEGRATION PLAN                     │
+├──────────────────────────────────────────────────────┤
+│ Page        : [page_name]                            │
+│ Service     : [service_name]                         │
+│ Backend     : [linked_service] (port [port])         │
+├──────────────────────────────────────────────────────┤
+│ INTEGRATIONS                                         │
+│                                                      │
+│ ① Login Form → webLogin()                            │
+│   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)                         │
+│   State add : deleteLoading, deleteError             │
+│   Pattern   : destructive                            │
+│   On success: refresh user list                      │
+├──────────────────────────────────────────────────────┤
+│ 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 (add deleteUser function)   │
+└──────────────────────────────────────────────────────┘
+```
+
+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 (if new functions needed)
+
+For each integration with `match_type == "new_handler"`:
+Surgically append to `src/api/apiHandler.js`:
+
+```jsx
+/**
+ * [Route description from context.api_routes or inferred].
+ *
+ * @param {Object} data - Request payload.
+ * @returns {Promise<Object>} API response.
+ */
+export async function [functionName](data) {
+  const res = await axiosClient.post('[route_path]', data);
+  return res;
+}
+```
+
+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 @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
+
+Read the current page file. Apply all changes surgically:
+
+1. **Add imports** for apiHandler functions (only the new ones):
+   ```jsx
+   import { webLogin, deleteUser } from '../../api/apiHandler';
+   ```
+   Also add `useNavigate` from react-router-dom if any handler navigates:
+   ```jsx
+   import { useNavigate } from 'react-router-dom';
+   ```
+
+2. **Add state declarations** inside the component function:
+   ```jsx
+   const [loading, setLoading] = React.useState(false);
+   const [error, setError] = React.useState(null);
+   ```
+   Add `const navigate = useNavigate();` if navigate is used.
+
+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 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 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**:
+   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** if applicable (Phase 5b).
+
+#### 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 — Write Context and Report
+
+Run task: `write-context` with:
+- Append to `context.services[<service_name>].integrated_pages`:
+  `{ page, integrations: [list of { form_purpose, handler, route }], timestamp: ISO now }`
+- Set `last_command` = "integrate-api"
+- 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"]
+
+Display completion report:
+
+```
+@integrate-api Complete
+─────────────────────────────────────────
+Page          : [page_name]
+Integrations  : [n] connected, [n] placeholders
+─────────────────────────────────────────
+✓ src/pages/[PageName]/index.jsx — updated
+✓ src/pages/[PageName]/[PageName].module.css — error/success styles added
+[✓ src/api/apiHandler.js — [n] new function(s) added]
+─────────────────────────────────────────
+[If gaps exist:]
+⚠ [n] action(s) have no backend route yet.
+  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")