codeninja 2.0.0

package/commands/modularize.workflow.md

@@ -0,0 +1,329 @@
+---
+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.
+---
+
+# 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
+
+---
+
+### 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/commands/refactor.workflow.md

@@ -0,0 +1,70 @@
+---
+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.
+---
+
+# 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
+
+---
+
+## 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`
+
+### rename module
+- Run task: `ask-old-module-name`
+- Run task: `ask-new-module-name`
+- Delegate to `nodejs-agent` → rename files and update route_manager
+
+4. Confirm: "Apply refactor? (yes/no)"
+5. If yes → make changes → run task: `write-context`
+6. Run task: `show-final-summary`