codeninja 2.0.0

package/tasks/generate-react-api-handler.task.md

@@ -0,0 +1,102 @@
+---
+type: task
+name: generate-react-api-handler
+agent: reactjs-agent
+---
+
+# File: src/api/apiHandler.js
+
+## Purpose
+Registry of all API call functions for this frontend service. Every
+function maps to one backend route. This is the only file in the frontend
+that knows API endpoint paths. All functions return Axios promises —
+no try/catch, no response shaping, no decryption here. All of that is
+handled upstream in `apiClient.js`.
+
+---
+
+## Dependencies to Import
+
+- `{ axiosClient }` from `"./apiClient"` — the shared Axios instance
+
+No other imports at scaffold time. If session saving is needed in a
+specific handler (e.g. after login), import `saveWebSession` from the
+pages common layer — but only add that import when generating a login
+handler specifically.
+
+---
+
+## Function Generation Rules
+
+### At scaffold time (initialize-project)
+Read `context.api_routes` filtered by `context.current_init.linked_service`.
+For each registered route, generate one exported async function.
+
+If no routes exist yet in context (fresh backend), generate only a
+scaffold comment block noting that functions will be added as routes
+are created via `@create-api`.
+
+### When a new route is added via @create-api
+Append one new exported function to this file. Never rewrite the whole
+file — surgical append only.
+
+---
+
+## Function Signature Patterns
+
+### Simple endpoint (no session, no device info)
+The function accepts a single `data` parameter and passes it straight
+to the endpoint. This pattern is used for most standard API calls like
+listing, detail, update, delete operations.
+
+### Auth / Login endpoint
+The function destructures specific fields from its parameter
+(e.g. `{ email, password }`) and builds an explicit payload object.
+This is because the login payload requires additional fields that the
+UI layer does not provide — for example, device information collected
+from a utility function `collectDeviceInfo()` imported from the pages
+layer. After a successful login (response code === 1), the handler
+calls `saveWebSession(res.data)` to persist the session token before
+returning the response.
+
+### Session-aware endpoints
+For endpoints that require the user to be logged in, no special handling
+is needed in the handler — the session token is injected automatically
+by the request interceptor in `apiClient.js`. The handler function
+looks identical to a simple endpoint.
+
+---
+
+## At Scaffold Time — Starter Function Set
+
+Generate starter functions for any routes already registered in
+`context.api_routes` for the linked service.
+
+If the linked service has no routes yet, generate this file with just
+the import line and a single comment:
+
+```
+// API handler functions will be added here as routes are created.
+// Use @create-api to scaffold a new route, then run @sync to update
+// this file.
+```
+
+---
+
+## Export Style
+
+Each function is a named export using the `export async function` syntax.
+No default export. No barrel index. The calling component imports exactly
+what it needs:
+
+`import { webLogin, getHomeStats } from "../../api/apiHandler"`
+
+---
+
+## What This File Does NOT Do
+
+- Does not import crypto-js or do any encryption/decryption
+- Does not read localStorage or manage tokens — that is apiClient.js
+- Does not handle errors — errors propagate to the calling component
+- Does not contain any JSX or React imports
+- Does not define any utility functions — only API call wrappers

package/tasks/generate-react-app-jsx.task.md

@@ -0,0 +1,56 @@
+---
+type: task
+name: generate-react-app-jsx
+agent: reactjs-agent
+---
+
+# File: src/App.jsx
+
+## Purpose
+The React Router root component. Defines the client-side routing tree
+for the entire application. All pages are registered here. This is the
+only file that imports page components for routing purposes.
+
+---
+
+## Dependencies to Import
+
+- `{ BrowserRouter, Routes, Route }` from `"react-router-dom"`
+- `Welcome` from `"./pages/Welcome"` — the default landing page
+
+---
+
+## Structure
+
+A single default-exported functional component named `App`.
+
+Inside the component, render:
+- `BrowserRouter` as the outermost wrapper
+- `Routes` inside it
+- A single `Route` with `path="/"` rendering `<Welcome />`
+
+Additional routes are added here as new pages are scaffolded via
+`@create-api` or future page generation commands.
+
+---
+
+## JSDoc Comment
+
+Include a JSDoc block above the component:
+- Description: "Root router component. Defines all client-side routes."
+- No params, no returns needed for a component
+
+---
+
+## Export
+
+Default export: `export default App`
+
+---
+
+## What This File Does NOT Do
+
+- Does not contain any business logic
+- Does not import API handler functions
+- Does not manage any state
+- Does not define layouts or navigation — those belong in components/layout/

package/tasks/generate-react-dockerfile.task.md

@@ -0,0 +1,175 @@
+---
+type: task
+name: generate-react-dockerfile
+agent: reactjs-agent
+---
+
+# File: Dockerfile
+
+## Purpose
+Generates a multi-stage production-ready Dockerfile for the ReactJS service.
+Builds the React app and serves it via nginx with proper SPA routing support.
+
+---
+
+## Template
+
+```dockerfile
+# Stage 1: Build the React application
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy application code
+COPY . .
+
+# Build production bundle
+RUN npm run build
+
+# Stage 2: Production nginx server
+FROM nginx:alpine
+
+# Copy custom nginx config for SPA routing
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+# Copy built assets from builder stage
+COPY --from=builder /app/build /usr/share/nginx/html
+
+# Expose port 80
+EXPOSE 80
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD wget --quiet --tries=1 --spider http://localhost:80/ || exit 1
+
+# Start nginx
+CMD ["nginx", "-g", "daemon off;"]
+```
+
+---
+
+## Companion File: nginx.conf
+
+Also generate `<service_name>/nginx.conf`:
+
+```nginx
+server {
+    listen 80;
+    server_name localhost;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/javascript application/json application/xml+rss;
+
+    # Security headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Referrer-Policy "no-referrer-when-downgrade" always;
+
+    # Cache static assets
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # SPA routing - send all requests to index.html
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API proxy (optional - if backend on same host)
+    # location /api {
+    #     proxy_pass http://backend:3000;
+    #     proxy_http_version 1.1;
+    #     proxy_set_header Upgrade $http_upgrade;
+    #     proxy_set_header Connection 'upgrade';
+    #     proxy_set_header Host $host;
+    #     proxy_cache_bypass $http_upgrade;
+    # }
+}
+```
+
+---
+
+## File Locations
+
+- Write Dockerfile to: `<service_name>/Dockerfile`
+- Write nginx.conf to: `<service_name>/nginx.conf`
+
+---
+
+## Dependencies
+
+- Requires `package.json` to exist (Wave 1)
+- Requires `src/` directory and all React components (Wave 3)
+- Can be generated in Wave 4 (post-completion)
+
+---
+
+## What This Dockerfile Does
+
+1. **Multi-stage build** — discards build tools, only keeps compiled assets
+2. **Nginx Alpine** — minimal production web server (~25MB total image)
+3. **SPA routing** — all routes fallback to index.html for React Router
+4. **Gzip compression** — reduces bandwidth usage
+5. **Security headers** — XSS, clickjacking, MIME-sniffing protection
+6. **Static asset caching** — 1 year cache for JS/CSS/images
+7. **Health check** — container orchestration support
+
+---
+
+## Build Arguments (optional enhancement)
+
+For advanced builds, support build-time environment variables:
+
+```dockerfile
+# In Stage 1, before RUN npm run build
+ARG REACT_APP_BASE_URL
+ARG REACT_APP_API_KEY
+ARG REACT_APP_KEY
+ARG REACT_APP_IV
+```
+
+This allows building different images for different environments
+without changing .env files.
+
+---
+
+## Notes
+
+- Final image size: ~25-35MB (nginx + compiled React bundle)
+- Build time: 2-5 minutes depending on app size
+- The build/ directory from `npm run build` is what gets served
+- nginx handles all HTTP concerns (compression, caching, routing)
+- No Node.js runtime in production image (only build stage)
+
+---
+
+## Security Features
+
+- No source code in final image (only compiled bundle)
+- Runs as nginx user (non-root)
+- Security headers prevent common attacks
+- No unnecessary packages or tools in production image
+
+---
+
+## Production Considerations
+
+For production, consider:
+1. Add SSL/TLS configuration to nginx.conf
+2. Use multi-stage build args for different environments
+3. Add CSP (Content Security Policy) headers
+4. Configure nginx access/error logs
+5. Add rate limiting to nginx

package/tasks/generate-react-env.task.md

@@ -0,0 +1,58 @@
+---
+type: task
+name: generate-react-env
+agent: reactjs-agent
+---
+
+# File: .env and .env.example
+
+## Purpose
+Environment variables for the ReactJS service. All values are inherited
+from the linked backend service — none are typed by the user.
+`.env` is gitignored. `.env.example` is committed with all values blanked
+so other developers know what variables are required.
+
+---
+
+## .env Contents
+
+```
+REACT_APP_BASE_URL=http://localhost:<linked_service_port>/api/v1/
+REACT_APP_API_KEY=<context.current_init.api_key>
+REACT_APP_KEY=<context.current_init.encryption_key>
+REACT_APP_IV=<context.current_init.encryption_iv>
+```
+
+Values are read from:
+- `REACT_APP_BASE_URL` — constructed from `context.current_init.linked_service_port`
+- `REACT_APP_API_KEY` — from `context.current_init.api_key`
+  (inherited from `context.services[linked_service].api_key`)
+- `REACT_APP_KEY` — from `context.current_init.encryption_key`
+  (inherited from `context.services[linked_service].encryption_key`)
+- `REACT_APP_IV` — from `context.current_init.encryption_iv`
+  (inherited from `context.services[linked_service].encryption_iv`)
+
+Never ask the user for these values. They are always inherited.
+
+---
+
+## .env.example Contents
+
+Same four keys, all values set to empty string:
+
+```
+REACT_APP_BASE_URL=
+REACT_APP_API_KEY=
+REACT_APP_KEY=
+REACT_APP_IV=
+```
+
+---
+
+## What This File Does NOT Do
+
+- Does not include any other environment variables at scaffold time
+- Does not use VITE_ prefix — this project uses Create React App
+  (REACT_APP_ prefix)
+- Does not expose any backend secrets beyond what is already required
+  to run the frontend

package/tasks/generate-react-gitignore.task.md

@@ -0,0 +1,49 @@
+---
+type: task
+name: generate-react-gitignore
+agent: reactjs-agent
+---
+
+# File: .gitignore
+
+## Purpose
+Defines which files Git should never track for this ReactJS service.
+Generated once during `@initialize-project`.
+
+---
+
+## Contents
+
+### Dependencies
+- `node_modules/`
+
+### Environment variables (sensitive — never commit)
+- `.env`
+- `.env.local`
+- `.env.*.local`
+
+### Build output
+- `build/`
+
+### OS files
+- `.DS_Store`
+- `Thumbs.db`
+
+### IDE files
+- `.vscode/`
+- `.idea/`
+- `*.swp`
+- `*.swo`
+
+### Create React App debug logs
+- `npm-debug.log*`
+- `yarn-debug.log*`
+- `yarn-error.log*`
+
+---
+
+## What This File Does NOT Do
+
+- Does not ignore `.env.example` — that file is committed intentionally
+- Does not ignore `public/assets/` — static assets are committed
+- Does not ignore `src/` — all source code is committed

package/tasks/generate-react-htaccess.task.md

@@ -0,0 +1,54 @@
+---
+type: task
+name: generate-react-htaccess
+agent: reactjs-agent
+---
+
+# Files: .htaccess (root) and public/.htaccess
+
+## Purpose
+Apache server configuration for SPA (Single Page Application) routing.
+React Router handles all client-side navigation, but Apache serves files
+from disk. Without these rules, refreshing any non-root URL returns a 404
+because the file does not exist on disk — only `index.html` does.
+
+Two files are generated — one at the service root and one inside `public/`.
+This covers both server configurations: where Apache's document root points
+to the project root, and where it points to the `public/` folder.
+
+---
+
+## Root-level .htaccess
+
+Purpose: handles routing when Apache's document root is the project root.
+Rewrites all non-file, non-directory requests to `public/index.html`.
+
+Rules to include:
+- Enable the rewrite engine
+- Set rewrite base to `/`
+- If the request is not a real file and not a real directory,
+  rewrite the request to `public/index.html` internally
+
+---
+
+## public/.htaccess
+
+Purpose: handles routing when Apache's document root is the `public/`
+folder (more common in shared hosting and cPanel environments).
+Rewrites all non-file, non-directory requests to `index.html`.
+
+Rules to include:
+- Enable the rewrite engine
+- Set rewrite base to `/`
+- If the request is not a real file and not a real directory,
+  rewrite the request to `index.html` internally
+
+---
+
+## What These Files Do NOT Do
+
+- Do not configure SSL or HTTPS redirects — that is server-level config
+- Do not set cache headers — that is handled at the CDN or server level
+- Do not restrict access to any directory
+- Do not apply to Nginx — a separate `nginx.conf` would be needed
+  (out of scope for scaffold)

package/tasks/generate-react-index-html.task.md

@@ -0,0 +1,53 @@
+---
+type: task
+name: generate-react-index-html
+agent: reactjs-agent
+---
+
+# File: public/index.html
+
+## Purpose
+The single HTML shell for the entire React application. This is the only
+HTML file in the project. It mounts the React app into the `#root` div.
+All page content is rendered by React from `src/index.jsx` onward.
+
+---
+
+## Structure
+
+Standard HTML5 document with the following elements:
+
+### `<head>`
+- `charset` meta tag: UTF-8
+- `viewport` meta tag: width=device-width, initial-scale=1
+- `theme-color` meta tag: a neutral default (e.g. `#000000`)
+- `<title>` — from `context.current_init.service_name` in title case
+- Link tag for `%PUBLIC_URL%/favicon.ico`
+- Link tag for `%PUBLIC_URL%/assets/css/style.css` — the global
+  stylesheet in the assets folder
+
+### `<body>`
+- A `<noscript>` tag with a message: "You need to enable JavaScript to
+  run this app."
+- A `<div id="root"></div>` — this is the React mount point
+
+No other scripts or stylesheets. React injects its bundle via
+`react-scripts` at build time.
+
+---
+
+## %PUBLIC_URL% Usage
+
+All paths to public assets use the `%PUBLIC_URL%` prefix provided by
+Create React App. This ensures correct paths in both development and
+production builds regardless of the deployment subdirectory.
+
+---
+
+## What This File Does NOT Do
+
+- Does not import React directly — that is handled by `src/index.jsx`
+- Does not include any inline JavaScript
+- Does not include CDN links for external libraries — all dependencies
+  go through npm in `package.json`
+- Does not include any page content — all content is rendered by React

package/tasks/generate-react-index-jsx.task.md

@@ -0,0 +1,51 @@
+---
+type: task
+name: generate-react-index-jsx
+agent: reactjs-agent
+---
+
+# File: src/index.jsx
+
+## Purpose
+The JavaScript entry point for the React application. This is the file
+that `react-scripts` targets when bundling. It mounts the React app
+into the `#root` div defined in `public/index.html`.
+
+---
+
+## Dependencies to Import
+
+- `React` from `"react"` — required for JSX in React 17 and below;
+  included for compatibility even though React 18 does not require it
+  in most cases
+- `{ createRoot }` from `"react-dom/client"` — React 18 concurrent root
+- `App` from `"./App"` — the router root component
+
+---
+
+## Structure
+
+Read the `#root` DOM element via `document.getElementById('root')`.
+Call `createRoot(rootElement)` to create a React 18 concurrent root.
+Call `.render(<App />)` on it.
+
+No `React.StrictMode` wrapper at scaffold time — the developer adds
+it if needed. Strict mode causes double-renders in development which
+can be confusing when debugging API calls.
+
+---
+
+## Export
+
+No exports. This file is the entry point — it is never imported by
+another file.
+
+---
+
+## What This File Does NOT Do
+
+- Does not import global CSS — styles are linked in `public/index.html`
+  via the `public/assets/css/style.css` link tag
+- Does not configure any providers (Redux, Context) at scaffold time —
+  those are added as the project grows
+- Does not contain any business logic

package/tasks/generate-react-package-json.task.md

@@ -0,0 +1,77 @@
+---
+type: task
+name: generate-react-package-json
+agent: reactjs-agent
+---
+
+# File: package.json
+
+## Purpose
+Defines the React project metadata and all dependencies. Generated once
+during `@initialize-project` for a ReactJS service. Uses context values
+for name, description, and author. Includes only packages that are
+actually used in the generated file set — no extras.
+
+---
+
+## Metadata Fields
+
+- `name` — from `context.current_init.service_name`
+- `version` — `"1.0.0"`
+- `description` — from `context.current_init.description`
+- `private` — `true`
+- `author` — from `context.current_init.author` (may be empty string)
+
+---
+
+## Scripts
+
+- `start` — `react-scripts start`
+- `build` — `react-scripts build`
+- `test` — `react-scripts test`
+- `eject` — `react-scripts eject`
+- `docker:build` — `docker build -t <service_name>:latest .`
+- `docker:run` — `docker run -p 80:80 <service_name>:latest`
+- `docker:stop` — `docker stop $(docker ps -q --filter ancestor=<service_name>:latest)`
+
+Replace `<service_name>` with `context.current_init.service_name`.
+
+---
+
+## Dependencies
+
+Always include:
+- `react` — core React library
+- `react-dom` — DOM renderer
+- `react-router-dom` — client-side routing (v6)
+- `react-scripts` — Create React App build toolchain
+- `axios` — HTTP client used in apiClient.js
+- `crypto-js` — AES-256-CBC encryption matching the linked backend
+
+No other dependencies. Do not add UI libraries, state management
+libraries, or form libraries by default. The developer adds those
+as needed.
+
+---
+
+## Dev Dependencies
+
+None required at scaffold time. The developer adds testing libraries
+when they set up tests.
+
+---
+
+## Browserslist
+
+Include the standard Create React App browserslist config:
+- Production: `>0.2%`, `not dead`, `not op_mini all`
+- Development: `last 1 chrome version`, `last 1 firefox version`,
+  `last 1 safari version`
+
+---
+
+## What This File Does NOT Do
+
+- Does not pin exact versions — uses `^` caret ranges
+- Does not include TypeScript configuration
+- Does not configure Jest in package.json