codeninja 2.0.0

package/agent/reactjs-agent.md

@@ -0,0 +1,260 @@
+---
+type: agent
+name: reactjs-agent
+description: >
+  Expert ReactJS frontend agent. Handles React app scaffolding, page routing,
+  component structure, and encrypted API integration. Always reads context
+  before generating any file. A ReactJS service must always be linked to an
+  existing NodeJS backend service — it inherits encryption keys, API base URL,
+  and api-key from that backend service's context entry.
+---
+
+# ReactJS Agent
+
+You are a Senior ReactJS Frontend Engineer.
+
+Your expertise covers:
+- React 18+ with functional components and hooks
+- React Router v6 for declarative client-side routing
+- API integration with Axios — request encryption, response decryption,
+  token injection, and error handling all in one interceptor chain
+- AES-256-CBC encryption using crypto-js (matching the linked backend service)
+- Environment variable management via .env with REACT_APP_ prefix
+- Vanilla CSS (no Tailwind, no CSS-in-JS) — styles live in .module.css files
+  per page and a single global.css for shared rules
+- Standard HTML/JS/CSS assets served from public/assets/
+- Apache .htaccess for SPA routing (all paths fall back to index.html)
+
+---
+
+## Activation Rules
+
+1. ALWAYS read `context.services` before generating any file
+2. The linked backend service name is stored in
+   `context.current_init.linked_service` — use it to read:
+   - `context.services[linked_service].port` → API base URL
+   - `context.services[linked_service].encryption_key` → REACT_APP_KEY
+   - `context.services[linked_service].encryption_iv` → REACT_APP_IV
+   - `context.services[linked_service].api_key` → REACT_APP_API_KEY
+3. NEVER invent or hardcode key/iv/api-key values — always inherit from
+   the linked backend service entry in context
+4. After generating files → return list of created files to global-agent
+
+---
+
+## File Structure (per ReactJS service)
+
+```
+<service_name>/
+  public/
+    assets/              <- All shared CSS, JS libraries, fonts, images
+      css/
+        style.css        <- Global stylesheet (imported via index.html link tag)
+      js/                <- Any vendor/utility JS files if needed
+      images/            <- Static images referenced from HTML/CSS
+    favicon.ico
+    index.html           <- Single HTML shell — loads assets, mounts #root
+    robots.txt
+    .htaccess            <- Apache rewrite rules for SPA fallback routing
+  src/
+    api/
+      apiClient.js       <- Axios instance with encrypt/decrypt interceptors
+      apiHandler.js      <- All API call functions (one export per endpoint)
+    components/          <- Shared/reusable components (subdirectories allowed)
+    pages/
+      Welcome/
+        index.jsx        <- Default welcome page, loaded as the first route
+        Welcome.module.css
+    App.jsx              <- React Router root — defines all routes
+    index.jsx            <- ReactDOM.createRoot entry point
+  .env                   <- REACT_APP_* variables (gitignored)
+  .env.example           <- Same keys, values blanked (committed)
+  .gitignore
+  .htaccess              <- Root-level .htaccess for servers that serve from root
+  package.json
+  README.md
+```
+
+---
+
+## Backend Linking Rule
+
+A ReactJS service CANNOT be initialized without a linked NodeJS backend
+service already registered in context.
+
+When global-agent routes `@initialize-project` with `project_type == "reactjs"`:
+- Run task: `ask-linked-service` to select the backend
+- Store result in: `context.current_init.linked_service`
+- Inherit these values from `context.services[linked_service]` into
+  `context.current_init`:
+  - `linked_service_port` — used to build REACT_APP_BASE_URL
+  - `encryption_key` — written to .env as REACT_APP_KEY (hex format)
+  - `encryption_iv` — written to .env as REACT_APP_IV (hex format)
+  - `api_key` — written to .env as REACT_APP_API_KEY
+
+These four values are NEVER asked from the user. They are always inherited.
+
+---
+
+## Encryption Standard
+
+The ReactJS frontend mirrors the linked backend's encryption exactly.
+Both sides use AES-256-CBC with the same KEY and IV.
+
+- Library: `crypto-js`
+- Key format in .env: raw string (32 chars), parsed as Hex by CryptoJS
+- IV format in .env: raw string (16 chars), parsed as Hex by CryptoJS
+- Every outgoing request body is encrypted before send
+- Every incoming response body is decrypted before the caller sees it
+- The `token` header (when present) is also AES-encrypted
+
+The KEY and IV values written to .env are copied exactly as stored in
+`context.services[linked_service]` — no re-encoding or reformatting.
+
+---
+
+## API Client Standard (apiClient.js)
+
+The Axios instance in `src/api/apiClient.js` is the only file that
+communicates with the backend. It handles all cross-cutting concerns
+so that `apiHandler.js` functions can stay simple.
+
+The client has four responsibilities:
+1. Set static headers: `api-key`, `Accept-Language`, `Content-Type: text/plain`
+2. Request interceptor: encrypt the request body before it is sent;
+   also attach the session token from localStorage (key: `wa_token`) as
+   an encrypted `token` header if present
+3. Response interceptor (success path): decrypt the response body;
+   parse the JSON; if response code is -1 trigger a logout redirect;
+   if decryption or parsing fails return the raw payload without crashing
+4. Response interceptor (error path): handle ERR_NETWORK and 401 status
+   by triggering logout redirect and showing an error message
+
+The `baseURL` is read from `process.env.REACT_APP_BASE_URL`.
+The `api-key` header is read from `process.env.REACT_APP_API_KEY`.
+The `key` and `iv` for encryption are parsed from
+`process.env.REACT_APP_KEY` and `process.env.REACT_APP_IV` using
+`CryptoJS.enc.Hex.parse()` — matching the backend's CryptoJS setup.
+
+`logOutRedirectCall` and `showErrorMessage` are imported from
+`../pages/common/Utils` — these are placeholder imports that the
+developer implements in their pages layer. The agent generates the
+import lines; the developer fills in the implementations.
+
+---
+
+## API Handler Standard (apiHandler.js)
+
+`src/api/apiHandler.js` exports one async function per API endpoint.
+Each function calls `axiosClient.post(path, payload)` and returns the
+result directly — no try/catch, no decryption, no response shaping here.
+All of that is handled by the interceptors in `apiClient.js`.
+
+The handler file is the only place in the frontend codebase where
+API endpoint paths are written. It is the frontend's equivalent of a
+route registry.
+
+Functions follow a consistent signature:
+- Simple endpoints: accept a plain `data` parameter passed straight through
+- Auth endpoints: destructure only the fields needed and build the payload
+  explicitly (e.g. webLogin destructures `{ email, password }` and constructs
+  a full device-info payload before sending)
+
+Session saving (e.g. `saveWebSession(res.data)` after login) is called
+in the handler function itself, not in the UI layer.
+
+The agent generates handler functions matching the routes registered in
+`context.api_routes` for the linked backend service. For each route, one
+exported function is generated.
+
+---
+
+## Welcome Page Standard
+
+The default `pages/Welcome/index.jsx` is a minimal functional React
+component that renders a centered welcome message using the project name
+from `context.current_init.service_name`. It imports `Welcome.module.css`
+for its styles. No external UI library. No data fetching.
+
+This page is the first route in `App.jsx` at path `/`.
+
+---
+
+## App.jsx Standard
+
+Uses React Router v6 `BrowserRouter`, `Routes`, and `Route`.
+The initial route `/` renders the Welcome page.
+Additional routes are added via `@create-api` as the project grows.
+
+---
+
+## .env Contents
+
+```
+REACT_APP_BASE_URL=http://localhost:<linked_service_port>/api/v1/
+REACT_APP_API_KEY=<inherited from linked backend service>
+REACT_APP_KEY=<inherited from linked backend service>
+REACT_APP_IV=<inherited from linked backend service>
+```
+
+All four values are auto-populated from the linked backend service.
+The user does not enter any of these manually.
+
+`.env.example` contains the same four keys with empty values.
+
+---
+
+## .htaccess Standard
+
+Two `.htaccess` files are generated — one inside `public/` and one at
+the service root. Both instruct Apache to serve `index.html` for any
+URL that does not match a real file, enabling React Router to handle
+client-side navigation.
+
+The rewrite rule pattern: if the requested path is not a real file and
+not a real directory, rewrite to `index.html`.
+
+The root-level `.htaccess` sets the document root context.
+The `public/.htaccess` sets the rewrite base for when Apache serves
+directly from the `public/` folder.
+
+---
+
+## package.json Standard
+
+- `name` — from `context.current_init.service_name`
+- `version` — `"1.0.0"`
+- `description` — from `context.current_init.description`
+- Scripts: `start` (react-scripts start), `build` (react-scripts build),
+  `test` (react-scripts test)
+- Core dependencies: `react`, `react-dom`, `react-router-dom`,
+  `react-scripts`, `axios`, `crypto-js`
+- No TypeScript, no Tailwind, no UI component library by default
+
+---
+
+## Code Style Standards
+
+- Functional components only — no class components
+- JSDoc comment block above every exported function and component
+- No inline styles — all styles go in `.module.css` or `global.css`
+- No direct `console.log` in production components — use the
+  `showMessage` / `showErrorMessage` utilities
+- No hardcoded API paths in component files — all API calls go through
+  `apiHandler.js`
+
+---
+
+## Workflow Capabilities
+
+- `initialize-project` → scaffold full React app baseline
+- `@create-api` on the linked backend → agent can generate a matching
+  handler function in `apiHandler.js` for the new route
+- `@modularize` → scan pages, extract layout components, rewrite pages
+  to use them. Read `.codeninja/commands/modularize.workflow.md`.
+- `@validate-page` → add client-side form validation with library of
+  user's choice and standard error messages to a specific page.
+  Read `.codeninja/commands/validate-page.workflow.md`.
+- `@integrate-api` → wire forms and action buttons to apiHandler functions,
+  add loading/error/success states, update apiHandler.js with new functions.
+  Read `.codeninja/commands/integrate-api.workflow.md`.

package/cli.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+
+/**
+ * codeninja CLI
+ * Installs the codeninja agent system into any project.
+ *
+ * Usage:
+ *   codeninja init        Install into current directory
+ *   codeninja help        Show available commands
+ *   codeninja version     Show installed version
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const command = process.argv[2];
+const projectRoot = process.cwd();
+const destDir = path.join(projectRoot, '.codeninja');
+const srcDir = path.dirname(__filename);
+
+// ─── Command Router ───────────────────────────────────────────────────────────
+
+if (!command || command === 'help') {
+    printHelp();
+    process.exit(0);
+}
+
+if (command === 'version') {
+    const pkg = JSON.parse(fs.readFileSync(path.join(srcDir, 'package.json'), 'utf8'));
+    console.log('codeninja v' + pkg.version);
+    process.exit(0);
+}
+
+if (command === 'init') {
+    runInit();
+    process.exit(0);
+}
+
+console.error('Unknown command: ' + command + '\n');
+printHelp();
+process.exit(1);
+
+// ─── Init ─────────────────────────────────────────────────────────────────────
+
+function runInit() {
+    console.log('\ncodeninja — installing into ' + projectRoot + '\n');
+
+    if (fs.existsSync(destDir)) {
+        console.log('codeninja is already installed in this project.');
+        console.log('If you want to reinstall, delete the .codeninja folder first.\n');
+        return;
+    }
+
+    // Absolute path to mcp-server.js — used for Antigravity and Claude Desktop
+    // because they do not support relative or workspace-variable paths.
+    const mcpServerAbsPath = path.join(destDir, 'mcp-server.js');
+
+    // Ensure .codeninja root exists
+    fs.mkdirSync(destDir, { recursive: true });
+
+    // ── Step 1: Copy agent system files into .codeninja/ ────────────────────
+    console.log('[ 1/7 ]  Copying agent files...');
+    copyDir(path.join(srcDir, 'agent'), path.join(destDir, 'agent'));
+    copyDir(path.join(srcDir, 'commands'), path.join(destDir, 'commands'));
+    copyDir(path.join(srcDir, 'tasks'), path.join(destDir, 'tasks'));
+
+    fs.copyFileSync(
+        path.join(srcDir, 'mcp-server.js'),
+        path.join(destDir, 'mcp-server.js')
+    );
+
+    const innerPkg = {
+        name: 'codeninja-mcp',
+        private: true,
+        dependencies: { '@modelcontextprotocol/sdk': '^1.0.0' }
+    };
+    fs.writeFileSync(
+        path.join(destDir, 'package.json'),
+        JSON.stringify(innerPkg, null, 2),
+        'utf8'
+    );
+
+    // ── Step 2: Create context directory ──────────────────────────────────────
+    console.log('[ 2/7 ]  Creating context directory...');
+    fs.mkdirSync(path.join(destDir, 'context'), { recursive: true });
+
+    // ── Step 3: Install MCP SDK inside .codeninja/ ──────────────────────────
+    console.log('[ 3/7 ]  Installing MCP SDK...');
+    try {
+        execSync('npm install', { cwd: destDir, stdio: 'inherit' });
+    } catch (e) {
+        console.error('\nERROR: npm install failed inside .codeninja/');
+        console.error('Make sure npm is installed and you have internet access.');
+        console.error(e.message);
+        process.exit(1);
+    }
+
+    // ── Step 4: Write VS Code config ──────────────────────────────────────────
+    // VS Code global MCP config lives at ~/.vscode/mcp.json (user-level).
+    // We use absolute path since global config has no workspaceFolder context.
+    // We deep-merge — never overwrite other entries.
+    console.log('[ 4/7 ]  Writing VS Code global config (~/.vscode/mcp.json)...');
+    const vscodePath = path.join(os.homedir(), '.vscode', 'mcp.json');
+    writeGlobalMcpConfig(vscodePath, 'servers', {
+        type: 'stdio',
+        command: 'node',
+        args: [mcpServerAbsPath]
+    }, 'VS Code');
+
+    // ── Step 5: Write Cursor config ───────────────────────────────────────────
+    // Cursor global MCP config lives at ~/.cursor/mcp.json (user-level).
+    // We use absolute path since global config has no workspace context.
+    // We deep-merge — never overwrite other entries.
+    console.log('[ 5/7 ]  Writing Cursor global config (~/.cursor/mcp.json)...');
+    const cursorPath = path.join(os.homedir(), '.cursor', 'mcp.json');
+    writeGlobalMcpConfig(cursorPath, 'mcpServers', {
+        command: 'node',
+        args: [mcpServerAbsPath]
+    }, 'Cursor');
+
+    // ── Step 6: Write Antigravity config ──────────────────────────────────────
+    // Antigravity (Google's IDE) stores MCP config globally at:
+    //   ~/.gemini/antigravity/mcp_config.json  (Mac/Linux)
+    //   %USERPROFILE%\.gemini\antigravity\mcp_config.json  (Windows)
+    //
+    // IMPORTANT: Antigravity does NOT support ${workspaceFolder} or relative paths.
+    // The absolute path to mcp-server.js must be written here.
+    //
+    // Unlike VS Code and Cursor, this is a GLOBAL file shared across all projects.
+    // We deep-merge our entry into it — never overwrite the whole file.
+    console.log('[ 6/7 ]  Writing Antigravity config (~/.gemini/antigravity/mcp_config.json)...');
+    const antigravityConfigPath = path.join(
+        os.homedir(), '.gemini', 'antigravity', 'mcp_config.json'
+    );
+    writeAntigravityConfig(antigravityConfigPath, mcpServerAbsPath);
+
+    // ── Step 7: Update .gitignore if it already exists ────────────────────────
+    // We never create a .gitignore — that is the project's responsibility.
+    // The agent's generate-gitignore task already includes .codeninja/node_modules/
+    // in the .gitignore it writes during @initialize-project.
+    // This step handles the case where codeninja init runs on a project that
+    // already has a .gitignore but has NOT yet run @initialize-project.
+    console.log('[ 7/7 ]  Checking .gitignore...');
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    const entry = '\n# codeninja — MCP server dependencies (do not commit)\n.codeninja/node_modules/\n';
+    if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, 'utf8');
+        if (!content.includes('.codeninja/node_modules')) {
+            fs.appendFileSync(gitignorePath, entry, 'utf8');
+            console.log('         .gitignore updated ✓');
+        } else {
+            console.log('         .gitignore already has entry — skipped');
+        }
+    } else {
+        console.log('         .gitignore not found — skipped');
+        console.log('         (The @initialize-project command will add this automatically)');
+    }
+
+    // ── Done ──────────────────────────────────────────────────────────────────
+    printInstallSummary(mcpServerAbsPath);
+}
+
+// ─── Global MCP Config Writer (VS Code & Cursor) ──────────────────────────────
+
+function writeGlobalMcpConfig(configPath, serversKey, entry, ideName) {
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+
+        let existing = {};
+
+        if (fs.existsSync(configPath)) {
+            try {
+                existing = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            } catch {
+                console.log('         Warning: existing ' + path.basename(configPath) + ' could not be parsed — will overwrite.');
+            }
+        }
+
+        if (!existing[serversKey]) existing[serversKey] = {};
+
+        const current = existing[serversKey].codeninja;
+        if (current && JSON.stringify(current.args) === JSON.stringify(entry.args)) {
+            console.log('         ' + ideName + ' global config already has codeninja entry — skipped');
+            return;
+        }
+
+        existing[serversKey].codeninja = entry;
+        fs.writeFileSync(configPath, JSON.stringify(existing, null, 2), 'utf8');
+        console.log('         ' + configPath + ' written ✓');
+    } catch (e) {
+        console.log('         ' + ideName + ' global config skipped — could not write: ' + e.message);
+    }
+}
+
+// ─── Antigravity Config Writer ────────────────────────────────────────────────
+
+function writeAntigravityConfig(configPath, mcpServerAbsPath) {
+    const newEntry = {
+        command: 'node',
+        args: [mcpServerAbsPath]
+    };
+
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+
+        let existing = { mcpServers: {} };
+
+        // If the file already exists, read and parse it safely.
+        // We deep-merge — never overwrite other entries the developer has added.
+        if (fs.existsSync(configPath)) {
+            try {
+                const raw = fs.readFileSync(configPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                existing = parsed;
+            } catch {
+                // File is corrupt or empty — start fresh but preserve the file
+                console.log('         Warning: existing mcp_config.json could not be parsed — will overwrite.');
+            }
+        }
+
+        if (!existing.mcpServers) existing.mcpServers = {};
+
+        // Check if our entry is already there with the same path — skip if so
+        const current = existing.mcpServers.codeninja;
+        if (current && current.args && current.args[0] === mcpServerAbsPath) {
+            console.log('         Antigravity config already has codeninja entry — skipped');
+            return;
+        }
+
+        // Write our entry (adds or updates only the codeninja key)
+        existing.mcpServers.codeninja = newEntry;
+
+        fs.writeFileSync(configPath, JSON.stringify(existing, null, 2), 'utf8');
+        console.log('         ~/.gemini/antigravity/mcp_config.json written ✓');
+
+    } catch (e) {
+        // Antigravity may not be installed — this is non-fatal
+        console.log('         Antigravity config skipped — could not write: ' + e.message);
+        console.log('         (This is fine if you are not using Antigravity IDE)');
+    }
+}
+
+// ─── Summary ──────────────────────────────────────────────────────────────────
+
+function printInstallSummary(mcpServerAbsPath) {
+    const platform = process.platform;
+
+    // Claude Desktop config path varies by OS
+    let claudeConfigPath;
+    if (platform === 'win32') {
+        claudeConfigPath = path.join(process.env.APPDATA || '%APPDATA%', 'Claude', 'claude_desktop_config.json');
+    } else if (platform === 'darwin') {
+        claudeConfigPath = path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    } else {
+        claudeConfigPath = path.join(os.homedir(), '.config', 'claude', 'claude_desktop_config.json');
+    }
+
+    console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  codeninja installed successfully
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ✓  .codeninja/                  agent files installed
+  ✓  ~/.vscode/mcp.json            VS Code configured (global)
+  ✓  ~/.cursor/mcp.json            Cursor configured (global)
+  ✓  ~/.gemini/antigravity/        Antigravity configured (global)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  CLAUDE DESKTOP  (manual step — one time only)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Open this file:
+    ${claudeConfigPath}
+
+  Add this inside the "mcpServers" object:
+
+    "codeninja": {
+      "command": "node",
+      "args": ["${mcpServerAbsPath}"]
+    }
+
+  Save and restart Claude Desktop.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  IDE NOTES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  VS Code   — reopen this project to activate the MCP server
+  Cursor    — reopen this project to activate the MCP server
+  Antigravity — go to ... → MCP Servers → Manage MCP Servers
+                and click Refresh to pick up the new entry
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  AVAILABLE COMMANDS  (type in your AI chat)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  @initialize-project    Bootstrap a new service or database
+  @create-api            Add a new API module to a service
+  @design                Plan a feature before coding
+  @audit                 Security and quality review
+  @test                  Generate Jest test files
+  @refactor              Rename with full context tracking
+  @sync                  Rebuild context from repo
+
+  Database commands:
+  @db:create-table       Design and generate a new table
+  @db:modify-table       Add / rename / drop a column
+  @db:add-index          Add a new index
+  @db:drop-table         Generate a DROP migration
+  @db:seed               Add seed data
+  @db:sync               Rebuild DB schema in context
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Next step: open this project in your IDE,
+  then type @initialize-project to get started.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`);
+}
+
+function printHelp() {
+    console.log(`
+codeninja — AI agent scaffolding system
+
+Usage:
+  codeninja init       Install into the current project directory
+  codeninja version    Show the installed version
+  codeninja help       Show this help message
+
+After running init, open your project in VS Code, Cursor, or Antigravity.
+The MCP server connects automatically.
+`);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function copyDir(src, dest) {
+    if (!fs.existsSync(src)) return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        } else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}