codeninja 2.0.0 → 3.2.0

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

@@ -0,0 +1,336 @@
+---
+slash_command: /codeninja:init
+personas: [global-orchestrator, nodejs-backend, reactjs-frontend, database-architect]
+skills: [mcp-and-context, api-builder, reactjs, database]
+description: >
+  Bootstrap a new NodeJS service, ReactJS app, or database-only project.
+  Collects project information first, then service details, then generates
+  ALL files in one pass after a single confirmation.
+---
+
+# /codeninja:init
+
+## Before Running
+1. Call `context_check_stale` — resolve any stale scratchpad keys first
+2. Call `context_read` — if context_version > 0, load existing context
+3. Call `service_scan` — detect existing service directories
+
+## Execution — Full Step-by-Step
+
+### Phase 0 — Project Information (runs ONCE per repo)
+Check `context.project_info` — if already populated, skip Phase 0 entirely.
+
+**0a.** Ask: "Do you have a project information document or requirement document?"
+- Options: Yes (provide URL or paste) / No
+- Store: `context.project_info.has_doc`, `.doc_url` or `.doc_content`, `.from_doc`
+
+**0b.** Ask: "Do you have a scope of work document?"
+- Options: Yes (provide URL or paste) / No
+- Store: `context.project_info.has_sow`, `.sow_url` or `.sow_content`, `.from_sow`
+
+**0c.** Ask: "Do you have a Figma design URL?"
+- Options: Yes (provide URL) / No
+- Store: `context.project_info.has_figma`, `.figma_url`, `.from_figma`
+
+After all three: synthesize `context.project_info.summary` (150–200 words covering
+what the project does, key features, entities/modules, tech preferences,
+third-party integrations) and `context.project_info.detected_entities[]`.
+Use this summary for all suggestions throughout the session.
+
+---
+
+### Phase 1 — Init Mode and Project Type
+
+**Step 0.** Ask: "How would you like to set up this service?"
+- Option 1: Fast setup — auto-generate secure values, only 9 essential questions
+- Option 2: Manual setup — walk through every value one at a time (22 questions)
+- Store: `context.current_init.init_mode` ("fast" | "manual")
+
+**Step 1.** Ask: "What are you initializing?"
+- Option 1: NodeJS API service
+- Option 2: ReactJS frontend app
+- Option 3: Database only (no service code)
+- Store: `context.current_init.project_type` ("nodejs" | "reactjs" | "database-only")
+
+**Step 1b.** If `project_type == nodejs`:
+- Ask: "What type of client will consume this API?"
+  - Options: ReactJS web app / Mobile app
+  - Store: `context.current_init.client_type` ("reactjs" | "app")
+- Ask: "Does this service use encrypted transport (AES response wrapping)?"
+  - Options: Yes / No
+  - Store: `context.current_init.encrypted_transport` (true | false)
+- Ask: "Which languages should this service support?"
+  - Show options + allow multi-select (en always included)
+  - Store: `context.current_init.supported_languages[]`
+
+**Step 2.** If `project_type == reactjs`:
+- Check `context.services` for any NodeJS services.
+  If none exist → ABORT: "A ReactJS service requires an existing NodeJS backend.
+  Run /codeninja:init first to create a NodeJS service."
+- Ask: "Which NodeJS service should this ReactJS app connect to?"
+  - List available NodeJS services from `context.services`
+- Store: `context.current_init.linked_service`
+- Store: `context.current_init.linked_service_port` (read from context)
+- Auto-inherit from the linked service (never ask user):
+  - `context.current_init.encryption_key`
+  - `context.current_init.encryption_iv`
+  - `context.current_init.api_key`
+- Skip Phase 2 (no DB), skip Phase 4 (no package questions), skip Phase 5 (no security questions)
+- Jump directly to Phase 3
+
+**Step 3.** If `project_type == nodejs` or `database-only` → continue to Phase 2.
+
+---
+
+### Phase 2 — Database (nodejs and database-only only)
+
+**Step 4.** Ask: "Which database type?"
+- Options: PostgreSQL / MySQL / MongoDB
+- If `context.db.type` already exists → ask: use existing or configure new?
+- Store: `context.db.type`
+
+**Step 5.** If `init_mode == manual`:
+- Ask: "Database name?", "Database host?", "Database port?", "Database user?" (grouped display)
+- Store: `context.db.name`, `context.db.host`, `context.db.port`, `context.db.user`
+
+If `init_mode == fast`:
+- Ask: "Database name?" only
+- Ask: "Database user?" only
+- (host and port auto-set by generate-fast-defaults)
+- Store: `context.db.name`, `context.db.user`
+
+**Step 9.** Delegate to database-agent — generate database folder at REPOSITORY ROOT
+(not inside the service folder — always a sibling).
+
+Check if `<repo_root>/database/<db_type>/` already exists:
+- If NOT exists → generate:
+  - `database/<db_type>/migrations/` (empty)
+  - `database/<db_type>/create-schema.sql`
+  - `database/<db_type>/setup-database.sh`
+  - `database/<db_type>/setup-database.ps1`
+  - `database/<db_type>/reset-database.sh`
+  - `database/<db_type>/seeds/` (with .gitkeep)
+  - `database/README.md`
+  - Then generate `tbl_user_deviceinfo` migration (nodejs projects only)
+- If ALREADY exists → skip generation entirely. Inform user.
+  Then check if `migrations/1-setup-tbl-user-deviceinfo.sql` exists:
+  - If NO and project_type == nodejs → generate it
+  - Otherwise → skip
+
+**Step 10.** Inform: "Database folder initialized. You can run /codeninja:db:create to add tables."
+
+**Step 11.** If `project_type == database-only` → skip Phases 3–5, jump to Phase 6.
+
+---
+
+### Phase 3 — Service Identity
+
+**Step 12.** Ask: "Service name?"
+- Must be unique across `context.services`
+- Agent suggests based on `context.project_info.detected_entities`
+- Store: `context.current_init.service_name`
+
+**Step 13.** If `init_mode == manual`:
+- Ask: "Port number?" (must not conflict with existing services)
+- Store: `context.current_init.port`
+
+**Step 14.** Ask: "Short description of this service?"
+- Store: `context.current_init.description`
+
+---
+
+### Phase 4 — Package Info (nodejs + manual mode only)
+
+**Step 15.** If `init_mode == manual`:
+- Ask: "Package name?" (default: service_name)
+- Store: `context.current_init.package_name`
+
+**Step 16.** If `init_mode == manual`:
+- Ask: "Author name?"
+- Store: `context.current_init.author`
+
+---
+
+### Phase 5 — Runtime Config (nodejs + manual mode only)
+
+**Step 17.** If `init_mode == manual`:
+- Ask: "API key?" (auto-suggest 32 random chars)
+- Store: `context.current_init.api_key`
+
+**Step 18.** If `init_mode == manual`:
+- Ask: "Encryption key?" (must be exactly 32 characters)
+- Store: `context.current_init.encryption_key`
+
+**Step 19.** If `init_mode == manual`:
+- Auto-set `encryption_iv` = first 16 chars of `encryption_key`
+- Show derived value: "Encryption IV auto-derived: [first 16 chars of key]"
+- Store: `context.current_init.encryption_iv`
+
+**Step 20.** If `init_mode == manual`:
+- Ask: "Redis host and port?" (grouped)
+- Store: `context.current_init.redis_host`, `context.current_init.redis_port`
+
+---
+
+### Phase 5b — Auto-populate Defaults (fast mode, nodejs only)
+
+If `init_mode == fast` AND `project_type == nodejs`:
+- `context.db.host` → "localhost" (if not set)
+- `context.db.port` → 5432 / 3306 / 27017 based on db type
+- Port: scan all `context.services` ports → highest + 1 → minimum 1001
+- `package_name` → same as `service_name`
+- `author` → ""
+- `api_key` → 32 cryptographically random alphanumeric chars
+- `encryption_key` → exactly 32 cryptographically random alphanumeric chars
+- `encryption_iv` → first 16 chars of `encryption_key` (always derived, never random)
+- `redis_host` → "localhost"
+- `redis_port` → 6379
+- All done silently — values shown in summary for review
+
+---
+
+### Phase 6 — Single Confirmation, Then Generate Everything
+
+**Step 22.** Show init summary — ALL collected values including auto-generated ones.
+Run pre-generation validation BEFORE displaying:
+- BLOCKER: service name conflict
+- BLOCKER: port conflict
+- BLOCKER: encryption_key not 32 chars (nodejs)
+- BLOCKER: encryption_iv not 16 chars (nodejs)
+- BLOCKER: required fields missing
+- BLOCKER: no linked service (reactjs)
+- WARNING: port below 1024
+- WARNING: service name has uppercase
+
+Resolve all BLOCKERs interactively before showing summary.
+Show the 5-wave generation plan.
+Ask ONE question: "Confirm and generate all files? (yes / no / change a value)"
+- If yes → generate immediately, NO further confirmations
+- If no → abort
+- If change → re-run specific ask-* task → re-validate → return to summary
+
+---
+
+### Phase 6b — Generation (nodejs)
+
+Read `nodejs-agent.md` persona. Execute ALL waves. Do NOT pause between waves.
+
+**Wave 1 — Foundation** (all simultaneously):
+- `package.json`
+- `.env` and `.env.example`
+- `.gitignore`
+- `README.md`
+- `config/constants.js`
+- `config/template.js`
+- `logger/logging.js`
+- `utilities/encryption.js`
+- `languages/<lang>.js` for each in supported_languages[]
+- `enc_dec.html` (if client_type == reactjs) OR `enc_dec.php` (if client_type == app)
+- `pem/` directory with .gitkeep
+- `images/` directory with .gitkeep
+- `logger/logs/` directory with .gitkeep
+
+**Wave 2 — Infrastructure**:
+- `config/database.js`
+- `utilities/ioRedis.js`
+- `utilities/response.js`
+
+**Wave 3 — Service Layer**:
+- `config/common.js`
+- `utilities/validator.js`
+- `utilities/notification.js`
+- `middleware/rateLimiter.js`
+
+**Wave 4 — Middleware and Business Layer** (all simultaneously):
+- `middleware/headerValidator.js`
+- `modules/v1/<ServiceName>/route.js`
+- `modules/v1/<ServiceName>/<service>_model.js`
+- `document/v1/swagger_doc.json` (skeleton)
+
+**Wave 5 — Orchestration Layer**:
+- `modules/v1/route_manager.js`
+- `app.js`
+
+**Wave 6 — Docker** (post-completion):
+- `Dockerfile`
+- `.dockerignore`
+
+COMPLETION GATE — before proceeding, verify these exist on disk:
+- `<service_name>/app.js`
+- `<service_name>/modules/v1/route_manager.js`
+- `<service_name>/modules/v1/<ServiceName>/route.js`
+- `<service_name>/modules/v1/<ServiceName>/<service>_model.js`
+- `<service_name>/document/v1/swagger_doc.json`
+If any missing → generate now before continuing.
+
+---
+
+### Phase 6c — Generation (reactjs)
+
+Read `reactjs-frontend.md` persona. Execute ALL waves.
+
+**Wave 1 — Foundation**:
+- `package.json`
+- `.env` and `.env.example`
+- `.gitignore`
+- `README.md`
+- `public/index.html`
+- `public/assets/css/style.css`
+- `public/robots.txt`
+- `public/favicon.ico` (placeholder note)
+- `.htaccess` (root)
+- `public/.htaccess`
+
+**Wave 2 — API Layer**:
+- `src/api/apiClient.js`
+- `src/api/apiHandler.js`
+
+**Wave 3 — Application Shell**:
+- `src/pages/Welcome/index.jsx`
+- `src/pages/Welcome/Welcome.module.css`
+- `src/App.jsx`
+- `src/index.jsx`
+- `src/components/` (empty dir with .gitkeep)
+
+**Wave 4 — Docker**:
+- `Dockerfile`
+- `nginx.conf`
+- `.dockerignore`
+
+COMPLETION GATE — verify before proceeding:
+- `<service_name>/public/index.html`
+- `<service_name>/src/api/apiClient.js`
+- `<service_name>/src/api/apiHandler.js`
+- `<service_name>/src/App.jsx`
+- `<service_name>/src/index.jsx`
+- `<service_name>/.env`
+
+---
+
+### Phase 7 — Post-Generation Steps
+
+**Step 23b.** Generate IDE configs (first init only):
+- Write `.vscode/mcp.json`
+- Write `.cursor/mcp.json`
+- Print Claude Desktop config snippet for manual addition
+
+**Step 23c.** Generate docker-compose.yml:
+- If does not exist → generate complete file at repo root
+- If exists → update by adding the new service
+- Also generate/update `.env.docker` and `.env.docker.example`
+
+**Step 24.** Call `context_write`:
+- Set `project_name` = service_name (top-level)
+- Set `initialized_at` = ISO now
+- Set `last_command` = "initialize-project"
+- Append new service to `context.services[<service_name>]`
+- For reactjs: store `linked_service` and `linked_service_port`
+- Update `context.project_info` with `initialized_at`
+- Clear `context.current_init`
+
+**Step 25.** Call `context_clear_scratchpad` with keys: ["current_init"]
+
+**Step 26.** Show final summary:
+- List all files created per wave
+- Show startup commands
+- Offer next steps: /codeninja:db:create, /codeninja:api, /codeninja:design

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

@@ -0,0 +1,336 @@
+---
+slash_command: /codeninja:integrate-api
+personas: [global-orchestrator, reactjs-frontend]
+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.
+─────────────────────────────────────────
+```