codeninja 3.1.0 → 3.2.0

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

@@ -1,11 +1,336 @@
 ---
-slash_command: @integrate-api
+slash_command: /codeninja:integrate-api
 personas: [global-orchestrator, reactjs-frontend]
-skills: [mcp-and-context, reactjs]
-description: Wire forms and action buttons to API handler functions
----
-# @integrate-api
-Delegates to: `.codeninja/commands/integrate-api.workflow.md`
-Before: `context_read`. Read target page and apiHandler.js.
-Add handler functions in apiHandler.js if missing.
-Wire buttons/forms to handlers. Add loading, error, success states.
+skills: [mcp-and-context, reactjs, api-builder]
+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.
+---
+
+# /codeninja: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
+
+## 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
+- ALWAYS add handler functions to `apiHandler.js` if the needed function doesn't exist
+- NEVER hardcode API endpoints in page files
+- ONE confirmation before any file is written
+- After writing files → call `context_write`
+
+---
+
+## 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: "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`
+
+---
+
+### 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
+
+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)
+
+---
+
+### Phase 3 — Scan the Page for Integration Points
+
+#### 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`
+
+#### 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
+
+#### 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.
+
+---
+
+### Phase 4 — Match Forms to API Routes
+
+For each integration point, determine which API route it should call:
+
+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
+
+Record: `{ form_purpose, handler_function_name, route_path, route_method, match_type }`
+
+---
+
+### Phase 5 — Design the Integration
+
+For each integration point:
+
+#### 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
+
+#### Submit handler patterns
+
+**Auth / destructive (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) {
+    navigate('/dashboard');
+  } else {
+    setError(res?.message || 'Something went wrong. Please try again.');
+  }
+};
+```
+
+**Data fetch / load (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: useEffect(() => { fetch[Resource](); }, []);
+```
+
+**Create / Update (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) {
+    setSuccessMsg(res?.message || '[Action] successful.');
+    resetForm();
+  } else {
+    setError(res?.message || 'Something went wrong. Please try again.');
+  }
+};
+```
+
+#### Loading feedback
+```jsx
+<button type="submit" disabled={loading}>
+  {loading ? 'Please wait...' : '[Original Button Text]'}
+</button>
+```
+
+#### Error display (above submit button)
+```jsx
+{error && <p className={styles.apiError}>{error}</p>}
+```
+
+#### Success display (for non-navigating actions)
+```jsx
+{successMsg && <p className={styles.successMsg}>{successMsg}</p>}
+```
+
+---
+
+### Phase 6 — Show Integration Plan
+
+```
+┌──────────────────────────────────────────────────────┐
+│             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)                          │
+│   Pattern  : destructive                             │
+│   On success: refresh user list                      │
+├──────────────────────────────────────────────────────┤
+│ GAPS (no backend route yet)                          │
+│  ③ Export CSV Button — no route exists yet           │
+│     Will add TODO placeholder                        │
+├──────────────────────────────────────────────────────┤
+│ FILES TO MODIFY                                      │
+│  → src/pages/[PageName]/index.jsx                   │
+│  → src/pages/[PageName]/[PageName].module.css       │
+│  → src/api/apiHandler.js ([n] new function(s))      │
+└──────────────────────────────────────────────────────┘
+```
+
+Ask: "Apply this integration plan? (yes / no / adjust)"
+
+---
+
+### Phase 7 — Apply Integration
+
+#### 7a — Update apiHandler.js (new functions only)
+
+For each `match_type == "new_handler"`:
+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.[method]('[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"`:
+```jsx
+/**
+ * TODO: Connect to backend route once created via /codeninja:api.
+ */
+export async function [functionName](data) {
+  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)
+
+1. Add imports for new apiHandler functions (only new ones):
+   ```jsx
+   import { webLogin, deleteUser } from '../../api/apiHandler';
+   ```
+   Add `useNavigate` if any handler navigates:
+   ```jsx
+   import { useNavigate } from 'react-router-dom';
+   ```
+
+2. Add state declarations inside component:
+   ```jsx
+   const [loading, setLoading] = React.useState(false);
+   const [error, setError] = React.useState(null);
+   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.
+
+4. Wire form `onSubmit` / button `onClick`:
+   - `<form onSubmit={handle[Action]}>`
+   - `<button onClick={handle[Action]}>`
+
+5. Add `disabled={loading}` and conditional button text to submit buttons.
+
+6. Add error and success display elements adjacent to submit buttons.
+
+7. Add `useEffect` for data-fetching handlers (load on mount).
+
+#### 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;
+}
+
+.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 8 — Finalize
+
+**Step 1.** Call `context_write`:
+- Append to `context.services[<service_name>].integrated_pages`:
+  `{ page, integrations: [{ form_purpose, handler, route }], timestamp: ISO now }`
+- Set `last_command` = "integrate-api"
+- Append to `change_log`
+
+**Step 2.** Call `context_clear_scratchpad` with keys: ["current_action"]
+
+**Step 3.** Show completion report:
+```
+/codeninja: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 /codeninja:api to create backend routes,
+  then re-run /codeninja:integrate-api to connect them.
+─────────────────────────────────────────
+```

package/ide/antigravity/.agents/workflows/codeninja-modularize.md

@@ -1,11 +1,216 @@
 ---
-slash_command: @modularize
+slash_command: /codeninja:modularize
 personas: [global-orchestrator, reactjs-frontend]
-skills: [mcp-and-context, reactjs]
-description: Extract repeated layout blocks into reusable React components
----
-# @modularize
-Delegates to: `.codeninja/commands/modularize.workflow.md`
-Before: `context_read`. Confirm linked NodeJS service exists.
-Scan all pages, identify repeated layout blocks.
-Show user what will be extracted and confirm before changes.
+skills: [mcp-and-context, reactjs, code-intelligence]
+description: >
+  Scan ReactJS pages, extract repeated layout blocks into reusable components
+  under src/components/, and update each page to import and use them.
+  Layout structure only — never touches business logic, state, or API calls.
+---
+
+# /codeninja:modularize
+
+## Before Running
+1. Call `context_check_stale`
+2. Call `context_read` — load `context.services` to find ReactJS services
+3. Call `service_scan` — verify ReactJS service exists on disk
+
+## Rules
+- Read ALL target pages fully before creating any component
+- NEVER create a component that already exists in `src/components/` — reuse it
+- NEVER modify business logic, state, API calls, or event handlers in any page
+- NEVER break existing imports or prop flows
+- ONE confirmation before any file is written
+- After writing files → call `context_write`
+
+---
+
+## 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: "What scope?"
+1. All pages — scan every page in `src/pages/` and `src/views/`
+2. Specific page — I'll provide the path
+- Store: `context.current_action.modularize_scope`
+- If specific → also ask: "Page path?" → Store: `context.current_action.page_path`
+
+---
+
+### Phase 2 — Inventory Existing Components
+
+Before scanning any pages, inventory what already exists:
+
+**Step 1.** Scan `src/components/` in the target service.
+For each subdirectory → record component name and file path.
+
+**Step 2.** For each existing component:
+- Read the file
+- Identify structural role: header, footer, sidebar, navbar, modal wrapper, card shell, breadcrumbs, etc.
+- Record: `{ name, path, role, props_accepted }`
+
+Store this as the "existing components registry" — the source of truth for reuse decisions.
+
+---
+
+### Phase 3 — Scan Target Pages
+
+#### If scope == "all":
+Scan `src/pages/` — each subdirectory with `index.jsx` or `index.js` = one page.
+Also scan `src/views/` if it exists.
+
+#### If scope == "specific":
+Pages list = [ context.current_action.page_path ]
+
+For each page:
+
+**Step 1.** Read the full file content.
+
+**Step 2.** Identify all structural blocks (layout HTML — NOT business logic):
+- Look for repeated layout patterns: `<header>`, `<nav>`, `<footer>`, `<aside>`, sidebar wrappers
+- Look for structural patterns repeated across pages: top nav bars, breadcrumb areas, page wrappers
+- Record each structural block as: `{ block_type, jsx_content, props_needed }`
+
+**Step 3.** Cross-check against existing components registry:
+- Does a component already exist that covers this block?
+- If YES → mark as "reuse existing: <ComponentName>"
+- If NO → mark as "new component needed: <ComponentName>"
+
+---
+
+### Phase 4 — Deduplicate Across Pages
+
+After scanning all pages:
+
+**Step 1.** Group blocks by structural similarity across pages.
+- If the same header JSX appears in 3+ pages → one shared Header component
+- If a sidebar appears in 2+ pages → one shared Sidebar component
+- If a block appears in only 1 page → do NOT extract it (no duplication benefit)
+
+**Step 2.** For each component to create, decide:
+- Component name (PascalCase, descriptive: `PageHeader`, `AppSidebar`, `MainFooter`)
+- Props needed (what varies between pages: title, navLinks, userName, etc.)
+- File location: `src/components/<ComponentName>/index.jsx` and `<ComponentName>.module.css`
+
+---
+
+### Phase 5 — Show Extraction Plan
+
+Display the plan before writing anything:
+
+```
+┌─────────────────────────────────────────────────────┐
+│           MODULARIZE PLAN                           │
+├─────────────────────────────────────────────────────┤
+│ Service  : [service_name]                           │
+│ Scope    : [all pages | specific page]              │
+│ Pages    : [n] scanned                              │
+├─────────────────────────────────────────────────────┤
+│ COMPONENTS TO CREATE                                │
+│  ✦ AppHeader — appears in [n] pages                 │
+│    Props: title (string)                            │
+│    File:  src/components/AppHeader/index.jsx        │
+│                                                     │
+│  ✦ MainSidebar — appears in [n] pages               │
+│    Props: activeRoute (string)                      │
+│    File:  src/components/MainSidebar/index.jsx      │
+├─────────────────────────────────────────────────────┤
+│ COMPONENTS REUSED (already exist)                   │
+│  ✓ Footer — src/components/Footer/index.jsx         │
+├─────────────────────────────────────────────────────┤
+│ PAGES TO UPDATE                                     │
+│  → src/pages/Dashboard/index.jsx                   │
+│  → src/pages/Profile/index.jsx                     │
+│  → src/pages/Settings/index.jsx                    │
+└─────────────────────────────────────────────────────┘
+```
+
+Ask: "Apply this plan? (yes / no / adjust)"
+- If yes → proceed to Phase 6
+- If no → abort, nothing written
+- If adjust → ask what to change → re-display plan
+
+---
+
+### Phase 6 — Generate Components
+
+For each new component:
+
+**Step 1.** Generate `src/components/<ComponentName>/index.jsx`:
+```jsx
+/**
+ * <ComponentName> — <one-line description of structural role>.
+ *
+ * @param {Object} props
+ * @param {string} props.<propName> - <description>
+ * @returns {JSX.Element}
+ */
+function <ComponentName>({ <props> }) {
+  return (
+    <extracted JSX block, using props where values varied>
+  );
+}
+
+export default <ComponentName>;
+```
+
+**Step 2.** Generate `src/components/<ComponentName>/<ComponentName>.module.css`:
+- Extract any inline styles or className references that were in the original block
+- Create CSS classes for them
+- If no styles → empty file with a comment: `/* <ComponentName> styles */`
+
+---
+
+### Phase 7 — Update Pages
+
+For each page that used the extracted block:
+
+**Step 1.** Read the current page file.
+
+**Step 2.** Apply changes surgically:
+1. Add import at top of file:
+   ```jsx
+   import <ComponentName> from '../../components/<ComponentName>';
+   ```
+   (adjust relative path based on page depth)
+
+2. Replace the extracted JSX block with the component:
+   ```jsx
+   <ComponentName <prop>={<value>} />
+   ```
+
+3. Remove any now-unused imports that were only used by the extracted block.
+
+4. Remove any CSS classes in the page's `.module.css` that are now handled by the component's own CSS file.
+
+**Step 3.** Write the updated file.
+
+---
+
+### Phase 8 — Finalize
+
+**Step 1.** Call `context_write`:
+- Append to `context.services[<service_name>].components`:
+  `{ name, path, role, props_accepted, used_in: [list of page paths] }`
+- Set `last_command` = "modularize"
+- Append to `change_log`: `{ timestamp, command: "modularize", action: "Created [n] component(s) from [n] pages" }`
+
+**Step 2.** Call `context_clear_scratchpad` with keys: ["current_action"]
+
+**Step 3.** Show completion report:
+```
+/codeninja:modularize Complete
+─────────────────────────────────────────
+Components created : [n]
+Components reused  : [n]
+Pages updated      : [n]
+─────────────────────────────────────────
+[list created files]
+[list modified files]
+─────────────────────────────────────────
+Next: /codeninja:validate-page to add validation
+      /codeninja:integrate-api to wire forms to backend
+```

package/ide/antigravity/.agents/workflows/codeninja-optimize.md

@@ -2,12 +2,83 @@
 slash_command: /codeninja:optimize
 personas: [global-orchestrator, nodejs-backend, database-architect]
 skills: [mcp-and-context, api-builder, database, code-intelligence]
-description: Find and fix performance bottlenecks with concrete impact estimates
+description: Analyse and improve performance using real project context.
 ---
+
 # /codeninja:optimize
-Delegates to: `.codeninja/commands/optimize.workflow.md`
-Before: `context_read` for `context.db.schema` and `context.services`.
-Ask: slow endpoint / heavy query / startup / describe it.
-Cross-reference existing indexes. Generate migration via `migration_next_number`.
-Output: [HIGH|MED|LOW] ranked. Confirm before applying.
-`context_write` after index additions.
+
+## Before Running
+1. Call `context_read` — load `context.db.schema`, `context.services`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Step 1 — Identify Target
+If not specified, ask:
+"What would you like to optimise?
+(a) A slow API endpoint — paste the route path
+(b) A heavy SQL query — paste the query or file path
+(c) Overall service startup / memory usage
+(d) Something else — describe it"
+
+### Step 2 — Load Context
+1. Call `fs_read` on the relevant files (route.js, _model.js)
+2. For DB queries: list existing indexes from `context.db.schema.<table>.indexes`
+
+### Step 3A — Database Query Analysis
+
+For each query in the target:
+
+**Check 1 — Missing Indexes**
+Compare WHERE / JOIN / ORDER BY columns against existing indexes.
+Generate `CREATE INDEX CONCURRENTLY` for missing ones.
+
+**Check 2 — SELECT * Anti-Pattern**
+Replace with explicit column list. Show before/after.
+
+**Check 3 — N+1 Query Pattern**
+Flag any loop calling a DB function per iteration. Suggest single query with IN or JOIN.
+
+**Check 4 — Window Function Choice**
+- `RANK()` → gaps after ties (wrong for leaderboards)
+- `DENSE_RANK()` → no gaps (correct for leaderboards)
+- `ROW_NUMBER()` → unique position (correct for pagination)
+
+**Check 5 — Duplicate Row Prevention**
+Flag duplicate rows from missing dedup. Suggest `MIN(id) GROUP BY user_id`.
+
+**Check 6 — Functional Index Trap**
+Flag `DATE(created_at) = '...'` → suggest range form for index usage.
+
+**Check 7 — work_mem for Sort Operations**
+If EXPLAIN shows external merge disk sort → suggest `SET work_mem = '64MB'`.
+
+### Step 3B — API Route Analysis
+
+- Is heavy middleware on lightweight routes?
+- Synchronous blocking in request path?
+- Repeated DB lookups that could be cached in Redis?
+- Pagination missing on list endpoints?
+
+### Step 4 — Output Recommendations
+
+```
+[HIGH | MED | LOW] — Impact label
+
+Target: what's being optimised
+Root cause: why it's slow right now
+Fix:
+  [exact SQL or code change]
+Estimated gain: concrete estimate
+Side effects: anything developer should know
+```
+
+List all, highest impact first.
+
+### Step 5 — Offer to Apply
+"I've found [N] optimisations. Want me to apply them?
+I'll implement each one and show you the change before writing."
+
+For index changes → generate `NNN_add_index_<n>.sql` migration file.
+For code changes → edit the relevant model or route file surgically.
+Always call `context_write` after applying index additions.