codeninja 3.1.0 → 4.0.0

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

@@ -1,11 +1,334 @@
+This workflow runs when user invokes /codeninja:modularize
+
 ---
-slash_command: @modularize
-personas: [global-orchestrator, reactjs-frontend]
-skills: [mcp-and-context, reactjs]
-description: Extract repeated layout blocks into reusable React components
+type: workflow
+name: modularize
+description: >
+  Scans one or all ReactJS pages, extracts repeated layout blocks
+  (header, footer, sidebar, navbar, etc.) into reusable components,
+  and rewrites each page to import and use those components. Reuses
+  existing components when they already exist. Never rewrites component
+  logic — layout structure only.
 ---
-# @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.
+
+# Workflow: @modularize
+
+## Goal
+Identify repeated structural blocks across pages, create shared components
+for them under `src/components/`, and update each page to use the new
+components. Result: zero duplicated layout HTML across the project.
+
+## Rules
+- Read ALL target pages fully before creating any component
+- NEVER create a component that already exists under `src/components/`
+  — reuse it instead
+- NEVER modify business logic, state, API calls, or event handlers
+  in any page file — layout structure only
+- NEVER break existing imports or prop flows
+- 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-modularize-scope`
+   Stores: `context.current_action.modularize_scope`
+   If scope == "specific" → also stores `context.current_action.page_path`
+
+---
+
+### Phase 2 — Inventory Existing Components
+
+Before scanning pages, inventory what already exists:
+
+1. Scan `src/components/` in the target service.
+   For each subdirectory → record the component name and its file path.
+   Example findings:
+     - `src/components/Header/index.jsx` → component: Header
+     - `src/components/Sidebar/index.jsx` → component: Sidebar
+     - `src/components/layout/Navbar/index.jsx` → component: Navbar
+
+2. For each existing component:
+   - Read the file
+   - Identify what structural role it plays (header, footer, sidebar,
+     navbar, modal wrapper, card shell, breadcrumbs, etc.)
+   - Record: `{ name, path, role, props_accepted }`
+
+3. Store the full inventory as the "existing components registry" in memory.
+   This is the source of truth for the reuse decision in Phase 4.
+
+---
+
+### Phase 3 — Scan Target Pages
+
+#### If scope == "all":
+Scan `src/pages/` — for each subdirectory containing `index.jsx` or
+`index.js`, add it to the pages list.
+Also scan `src/views/` if it exists.
+
+#### If scope == "specific":
+Pages list = [ context.current_action.page_path ]
+
+For each page in the pages list:
+
+1. Read the full file content.
+
+2. Parse the JSX structure to identify the top-level layout blocks.
+   A layout block is a JSX subtree that:
+   - Appears at the top level of the return statement (not inside
+     a conditional or a list map)
+   - Has a clear structural role in the visual layout
+   - Does NOT contain unique per-page business logic
+
+3. Classify each block using these roles (in priority order):
+   - **header** — contains site logo, navigation links, user avatar/menu,
+     search bar. Typically rendered at the very top of every page.
+   - **footer** — copyright text, footer links, social icons. Bottom.
+   - **sidebar** — vertical navigation panel, collapsible menu, drawer.
+   - **navbar** — horizontal navigation bar, tab bar, breadcrumbs.
+   - **topbar** — page title row with action buttons (e.g. "Users | + Add New")
+   - **page-wrapper** — the outer container div that sets max-width,
+     padding, or background — wraps all page content.
+   - **card** — a bordered/shadowed container used for data display.
+     Only extract as a component if it appears in 2+ pages unchanged.
+   - **modal-shell** — the backdrop + centered box wrapper for modals.
+     Only extract if used in 2+ pages unchanged.
+
+4. Record for each block:
+   - Role (from list above)
+   - Exact JSX tree content
+   - Props/variables it references from the parent page scope
+   - Which pages it appears in (identical or near-identical)
+
+---
+
+### Phase 4 — Decide: Create vs Reuse vs Skip
+
+For each block found across all pages, make one of three decisions:
+
+**REUSE** — an existing component from Phase 2 already covers this role.
+  Condition: an existing component has the same `role` AND its structure
+  matches the block (same element types, same general layout — minor
+  class name differences are acceptable).
+  Action: the page will import the existing component. No new file created.
+
+**CREATE** — no existing component covers this role.
+  Condition: no match in existing components registry.
+  Additional condition: the block appears in at least ONE page
+  (for header/footer/sidebar/navbar/topbar/page-wrapper — always create
+  even if seen on only one page, because they are foundational layout).
+  For card/modal-shell → only create if seen on 2+ pages unchanged.
+  Action: a new component will be created.
+
+**SKIP** — the block is too unique to extract.
+  Condition: the block contains page-specific state, API calls, or
+  dynamic content that cannot be expressed as simple props.
+  Example: a sidebar that renders a different menu depending on user role
+  and reads from a page-specific hook → SKIP.
+  Action: leave the block inline in the page. Note it in the report.
+
+---
+
+### Phase 5 — Build Component Plan
+
+For each block decided as CREATE, determine:
+
+1. **Component name** — PascalCase of the role.
+   Examples: Header, Footer, Sidebar, Navbar, PageTopbar, PageWrapper,
+   DataCard, ModalShell.
+   If a more specific name is obvious from the content
+   (e.g. the sidebar contains "Admin Menu") → use AdminSidebar.
+
+2. **File path** — `src/components/<ComponentName>/index.jsx`
+   and `src/components/<ComponentName>/<ComponentName>.module.css`
+
+3. **Props** — anything the block references from the parent scope
+   that varies between pages must become a prop.
+   Examples:
+   - Page title → `title` prop
+   - Active nav item → `activeItem` prop
+   - User display name in header → `userName` prop
+   Common static content (logo, copyright text, link list) → hardcoded
+   inside the component, not a prop.
+
+4. **CSS extraction** — any inline styles or style classes that belong
+   only to this block are moved to the component's `.module.css` file.
+   Classes shared with the rest of the page remain in the page's own
+   `.module.css`. Do not break existing page styles.
+
+---
+
+### Phase 6 — Show Plan and Confirm
+
+Display the modularization plan:
+
+```
+┌──────────────────────────────────────────────────────┐
+│              MODULARIZATION PLAN                     │
+├──────────────────────────────────────────────────────┤
+│ Service     : [service_name]                         │
+│ Pages scanned: [n]                                   │
+├──────────────────────────────────────────────────────┤
+│ COMPONENTS TO CREATE                                 │
+│  → src/components/Header/index.jsx                   │
+│    Props: userName, activeItem                       │
+│    Used by: Login, Dashboard, Profile (3 pages)      │
+│                                                      │
+│  → src/components/Footer/index.jsx                   │
+│    Props: none                                       │
+│    Used by: all 3 pages                              │
+├──────────────────────────────────────────────────────┤
+│ COMPONENTS TO REUSE (already exist)                  │
+│  → src/components/Sidebar/index.jsx [existing]       │
+│    Will be imported into: Dashboard, Profile         │
+├──────────────────────────────────────────────────────┤
+│ BLOCKS SKIPPED (too page-specific to extract)        │
+│  → Dashboard hero banner — contains dynamic API data │
+├──────────────────────────────────────────────────────┤
+│ PAGES TO UPDATE                                      │
+│  → src/pages/Login/index.jsx                         │
+│  → src/pages/Dashboard/index.jsx                     │
+│  → src/pages/Profile/index.jsx                       │
+└──────────────────────────────────────────────────────┘
+```
+
+Ask exactly this question:
+"Proceed with this modularization plan? (yes / no / adjust)"
+
+- If yes → proceed to Phase 7 immediately
+- If no → abort. Nothing is created.
+- If adjust → ask: "What would you like to change?"
+  Allow the user to exclude a component, rename one, or change a
+  prop assignment. Apply the adjustment and re-display the plan.
+
+---
+
+### Phase 7 — Generate Components
+
+For each component in the CREATE list:
+
+#### Generate `src/components/<ComponentName>/index.jsx`
+
+Structure:
+- JSDoc block above the component:
+  ```
+  /**
+   * [Role] component shared across all pages.
+   *
+   * @param {Object} props
+   * @param {string} [props.<propName>] - [description]  ← one line per prop
+   * @returns {JSX.Element}
+   */
+  ```
+- Import React at the top
+- Import CSS module: `import styles from './<ComponentName>.module.css'`
+- Functional component with props destructured in the signature
+- JSX extracted verbatim from the source page, with parent-scope
+  variable references replaced by the corresponding prop name
+- Default export
+
+#### Generate `src/components/<ComponentName>/<ComponentName>.module.css`
+
+- Move all CSS classes that belong exclusively to this component's
+  block from the source page's `.module.css`
+- If no specific classes are used → generate an empty file with a
+  comment: `/* Styles for <ComponentName> */`
+
+---
+
+### Phase 8 — Update Pages
+
+For each page in the pages list that references at least one component
+(created or reused):
+
+Read the current page file. Apply these surgical edits:
+
+1. **Add imports** at the top of the file, after existing imports:
+   ```jsx
+   import Header from '../../components/Header';
+   import Footer from '../../components/Footer';
+   ```
+   Use the correct relative path from the page file's location to
+   `src/components/`. Always use `../../components/` from the standard
+   `src/pages/<PageName>/` depth.
+
+2. **Replace the extracted JSX block** with the component tag.
+   Pass any required props using the values that were previously
+   inline in the page.
+   Example:
+   Before: `<header className={styles.header}><nav>...</nav></header>`
+   After:  `<Header activeItem="dashboard" userName={user.name} />`
+
+3. **Remove orphaned imports** — if the original block used an import
+   that is no longer referenced in the page after extraction
+   (e.g. a logo image import that moved into the Header component) →
+   remove it from the page's import list.
+
+4. **Clean up orphaned CSS classes** — if classes were moved to the
+   component's CSS module, remove them from the page's `.module.css`.
+
+Never modify:
+  - Business logic functions (state, useEffect, API calls)
+  - The page's own JSX content outside the extracted blocks
+  - Event handlers, form logic, any non-layout code
+
+> **Multi-agent:** Delegate to `reactjs-frontend` via Task invocation for parallel execution.
+> Read `.codeninja/tasks/` before generating each component and updating pages.
+
+---
+
+### Phase 9 — Write Context and Report
+
+Run task: `write-context` with:
+- Append to `context.services[<service_name>].components`:
+  For each new component created:
+  `{ name, path, role, props, used_by: [page_names], created_by: "modularize" }`
+- Set `last_command` = "modularize"
+- Append to top-level `change_log`:
+  `{ timestamp, command: "modularize", action: "Created [n] components, updated [n] pages", affected_files: [...] }`
+- After write-context → call MCP tool `context_clear_scratchpad` with keys: ["current_action"]
+
+Display the modularization report:
+
+```
+@modularize Complete
+─────────────────────────────────────────
+Components created : [n]
+Components reused  : [n]
+Pages updated      : [n]
+Blocks skipped     : [n]
+─────────────────────────────────────────
+Created:
+  ✓ src/components/Header/index.jsx
+  ✓ src/components/Header/Header.module.css
+  ✓ src/components/Footer/index.jsx
+  ✓ src/components/Footer/Footer.module.css
+
+Updated:
+  ✓ src/pages/Login/index.jsx
+  ✓ src/pages/Dashboard/index.jsx
+  ✓ src/pages/Profile/index.jsx
+─────────────────────────────────────────
+```
+
+Run task: `show-final-summary`
+
+---
+
+## What This Workflow Does NOT Do
+
+- Does not create page-level components (forms, tables, charts) —
+  only layout/structural shell components
+- Does not add routing — components are not registered in App.jsx
+- Does not touch any backend files
+- Does not modify apiHandler.js or apiClient.js
+- Does not add state management (Redux, Context API)
+- Does not install any new npm packages

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

@@ -1,13 +1,126 @@
+This workflow runs when user invokes /codeninja:optimize
+
 ---
-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
+type: workflow
+name: optimize
+description: >
+  Analyse and improve performance of a route, query, or service using real
+  project context — actual table sizes, existing indexes, query patterns, and
+  middleware overhead. Produces ranked recommendations with concrete code.
 ---
-# /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.
+
+# Workflow: @optimize / /codeninja:optimize
+
+## Goal
+Find real performance bottlenecks using actual project data. Every
+recommendation includes a concrete fix and an estimated impact.
+No generic advice — only changes grounded in this codebase.
+
+## Rules
+- Check context.db.schema for existing indexes before recommending new ones
+- Reference real table names and column names from context
+- Estimate impact where possible (e.g., "seq scan → index scan on 2M rows")
+- Rank by impact: HIGH → MED → LOW
+
+---
+
+## Step-by-Step Execution
+
+### 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 `context_read` — load `context.db.schema`, `context.services`
+2. Call `fs_read` on the relevant files (route.js, _model.js)
+3. 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.
+```
+Table: tbl_scores
+Query: WHERE week_id = $1 ORDER BY score DESC
+Indexes on tbl_scores: [id, user_id]   ← week_id NOT indexed
+Fix: CREATE INDEX CONCURRENTLY idx_scores_week_id_score
+       ON tbl_scores(week_id, score DESC);
+Impact: HIGH — seq scan on every leaderboard call → index scan
+```
+
+**Check 2 — SELECT * Anti-Pattern**
+```
+Before: SELECT * FROM tbl_users WHERE user_id = $1
+After:  SELECT id, user_id, display_name, status FROM tbl_users WHERE user_id = $1
+Why: Eliminates unused column transfer; avoids fetching large text/jsonb columns
+```
+
+**Check 3 — N+1 Query Pattern**
+Flag any loop that calls a DB function per iteration.
+Suggest: single query with IN clause or JOIN.
+
+**Check 4 — Window Function Choice**
+```
+RANK()        → gaps after ties (positions: 1, 2, 2, 4)  ← usually wrong for leaderboards
+DENSE_RANK()  → no gaps (positions: 1, 2, 2, 3)          ← correct for leaderboards
+ROW_NUMBER()  → unique position per row (1, 2, 3, 4)      ← correct for pagination
+```
+
+**Check 5 — Duplicate Row Prevention**
+```
+-- Symptom: same user appears multiple times in results
+-- Fix: dedup using MIN(id) GROUP BY user_id before joining
+SELECT MIN(id) as id, user_id FROM tbl_users GROUP BY user_id
+```
+
+**Check 6 — Functional Index Trap**
+```
+-- BAD: DATE(created_at) = '2026-04-13' prevents index use
+-- GOOD: created_at >= '2026-04-13' AND created_at < '2026-04-14'
+```
+
+**Check 7 — work_mem for Sort Operations**
+If EXPLAIN shows "Sort Method: external merge  Disk:", recommend:
+```sql
+SET work_mem = '64MB';  -- session-level, before the heavy query
+```
+
+### Step 3B — API Route Analysis
+
+Check middleware chain for overhead:
+- Is heavy middleware applied to lightweight routes?
+- Any synchronous blocking in the request path?
+- Repeated DB lookups that could be cached in Redis?
+
+Check response size:
+- Is pagination applied to list endpoints?
+- Any large JSON blobs being serialized unnecessarily?
+
+### Step 4 — Output Recommendations
+
+```
+[HIGH | MED | LOW] — Impact label
+
+Target: describe 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 the developer should know
+```
+
+List all recommendations, 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_<name>.sql` migration file.
+For code changes: edit the relevant model or route file surgically.
+Always call `context_write` after applying index additions to update schema.

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

@@ -1,23 +1,76 @@
+This workflow runs when user invokes /codeninja:refactor
+
+---
+type: workflow
+name: refactor
+description: >
+  Rename, restructure, or improve existing code. Always records changes in
+  context.change_log so all agents remain aware of the history.
 ---
-slash_command: /codeninja:refactor
-personas: [global-orchestrator, nodejs-backend]
-skills: [mcp-and-context, api-builder]
-description: Rename or restructure code with full context tracking
+
+# Workflow: @refactor
+
+## Goal
+Make a controlled change to existing code with full traceability in context.
+
+## Rules
+- Every rename is recorded in `context.change_log`
+- DB column renames generate a migration file
+- Never delete the old name from change_log
+
 ---
 
-# /codeninja:refactor
+## Step-by-Step Execution
+
+1. Run task: `ask-refactor-type`
+   - Options: rename DB column, rename service, rename module, restructure files
+   - Stores: `context.current_refactor.type`
+
+2. Run task: `ask-target-service` (if applicable)
+
+3. Based on refactor type:
+
+### rename DB column
+- Run task: `ask-table-name`
+- Run task: `ask-old-column-name`
+- Run task: `ask-new-column-name`
+- Delegate to `database-agent`:
+  - Generate ALTER TABLE migration
+  - Update `context.db.schema.tables[<table>].columns`
+  - Append to `context.db.schema.change_log`
+- Delegate to `nodejs-agent`:
+  - Find all references to old column name in service files
+  - Update model queries
+  - Update swagger_doc.json
+
+### rename service
+- Run task: `ask-old-service-name`
+- Run task: `ask-new-service-name`
+- Update `context.services` key
+- Append to `context.change_log`
+
+### rename table
+- Run task: `ask-table-name`
+- Run task: `ask-new-table-name`
+- Delegate to `database-agent`:
+  - Generate ALTER migration: `RENAME TABLE <old> TO <new>`
+  - Update `context.db.schema.tables` key
+  - Append to `context.db.schema.change_log`:
+    `{ type: "table_renamed", from: "<old>", to: "<new>", migration_file: "..." }`
+- Delegate to `nodejs-agent`:
+  - Find all references to old table name in model files
+  - Update queries in all affected services
+- Append to top-level `context.change_log`
 
-Delegates to: `.codeninja/commands/refactor.workflow.md`
+### rename module
+- Run task: `ask-old-module-name`
+- Run task: `ask-new-module-name`
+- Delegate to `nodejs-agent` → rename files and update route_manager
 
-## Before Running
-1. Call `context_read`
-2. Ask: "What are you refactoring?" — field rename, file restructure, module rename?
+4. Confirm: "Apply refactor? (yes/no)"
 
-## Execution
-Read and execute `refactor.workflow.md`.
-Show full list of affected files before making any change.
-ONE confirmation, then apply all changes.
-Update `context.change_log` with before/after record.
+> **Multi-agent:** Delegate to `database-architect` (DB refactors) or `nodejs-backend` (service/module refactors) via Task invocation for parallel execution.
+> Read `.codeninja/tasks/` before applying each change.
 
-## After Running
-Call `context_write` with updated service/module names if renamed.
+5. If yes → make changes → run task: `write-context`
+6. Run task: `show-final-summary`

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

@@ -1,12 +1,87 @@
+This workflow runs when user invokes /codeninja:review
+
 ---
-slash_command: /codeninja:review
-personas: [global-orchestrator, nodejs-backend]
-skills: [mcp-and-context, api-builder, code-intelligence]
-description: Code review — severity-ranked findings with exact before/after fixes
+type: workflow
+name: review
+description: >
+  Deep code review of any file or module — security, architecture, naming
+  conventions, and alignment with project patterns. Outputs severity-ranked
+  findings with exact fixes.
 ---
-# /codeninja:review
-Delegates to: `.codeninja/commands/review.workflow.md`
-Before: `context_read`, `fs_read` target, read 1–2 sibling modules.
-Run full checklist: Security → Architecture → Code Quality → Database.
-Output: [CRITICAL|WARNING|SUGGESTION] with before/after code.
-Offer to apply fixes. Confirm each before writing.
+
+# Workflow: @review / /codeninja:review
+
+## Goal
+Produce a structured code review that finds real issues using actual project
+context — not generic best practices. Every finding references the real file
+and line, and every fix is concrete code, not advice.
+
+## Rules
+- Read the actual file before reviewing it
+- Cross-reference `context.db.schema` for table/column accuracy
+- Compare against 1–2 existing modules to check pattern consistency
+- Never flag something as an issue if it's the established pattern in this project
+
+---
+
+## Step-by-Step Execution
+
+### Step 1 — Identify Target
+If not specified, ask: "Which file or module would you like me to review?"
+
+### Step 2 — Load Context
+1. Call `context_read`
+2. Call `fs_read` on the target file
+3. Read 1–2 similar modules from `context.services[<service>].modules` for comparison
+
+### Step 3 — Run Review Checklist
+
+#### Security (flag as CRITICAL if failing)
+- [ ] All POST/PUT/PATCH routes have validatorjs input validation
+- [ ] API key middleware applied before any route logic
+- [ ] JWT auth middleware present on protected routes
+- [ ] No hardcoded secrets, keys, or passwords
+- [ ] Parameterized queries only — no string concatenation in SQL
+- [ ] Error responses don't leak stack traces or internal details
+
+#### Architecture (flag as WARNING if failing)
+- [ ] 2-layer rule: no SQL in route.js, no res.json() in model.js
+- [ ] route_manager.js registration matches route file
+- [ ] swagger_doc.json has entry for this endpoint
+- [ ] All user-facing strings in languages/en.js — none hardcoded in route.js
+
+#### Code Quality (flag as SUGGESTION if failing)
+- [ ] JSDoc on every exported function
+- [ ] No unused variables or dead imports
+- [ ] No console.log — project logger used instead
+- [ ] Async functions have try/catch blocks
+- [ ] SELECT * not used — explicit column list
+
+#### Database (flag as WARNING if failing)
+- [ ] Column names match context.db.schema exactly (snake_case)
+- [ ] Foreign key columns indexed
+- [ ] Transactions used where multiple writes occur together
+- [ ] LIMIT clause on any query that could return unbounded rows
+
+### Step 4 — Output Findings
+
+For each issue:
+```
+[CRITICAL|WARNING|SUGGESTION]
+File:   path/to/file.js  (~line N)
+Issue:  clear one-line description
+Before: the current code
+After:  the corrected code
+Why:    one sentence explanation
+```
+
+End with summary line:
+```
+Review complete: X critical · Y warnings · Z suggestions
+```
+
+### Step 5 — Offer Auto-Fix
+"Would you like me to apply any of these fixes? I'll confirm each change before writing."
+
+For SUGGESTION-level items: offer to apply all at once.
+For WARNING/CRITICAL items: apply one at a time, confirm each.