codeninja 2.0.0

package/commands/initialize-project.workflow.md

@@ -0,0 +1,500 @@
+---
+type: workflow
+name: initialize-project
+description: >
+  Interactive bootstrap workflow for a new service. Collects project
+  information first, then service details one value at a time, then scaffolds
+  database folder and service baseline. Single confirmation before generation —
+  no per-file prompts after that.
+---
+
+# Workflow: @initialize-project
+
+## Goal
+Scaffold a new service (NodeJS API, ReactJS frontend, or Database-only) with
+full context recorded in `.codeninja/context/context.json`.
+
+## Rules
+- Phase 0 runs ONCE per repository — skip entirely if `context.project_info` already populated.
+- Confirm the full summary ONCE before creating any file.
+- After confirmation → generate ALL files using wave structure, no further per-file prompts.
+- Always scaffold database folder at REPOSITORY ROOT before any service
+  code. The database/ folder is always at the same level as service
+  folders, never inside one.
+- After completion → run task: `write-context` then task: `show-final-summary`
+
+## Init Mode Rules
+- Fast mode: ask only essential questions. Auto-generate all technical
+  config silently. Show everything in summary for review.
+- Manual mode: ask every value individually, one at a time.
+- In BOTH modes: the summary shows ALL values and ALL are editable
+  before confirmation. Fast mode is not a shortcut around review —
+  it is a shortcut around data entry.
+- Auto-generated security values (api_key, encryption_key) are
+  cryptographically random and production-safe.
+  encryption_iv is always the first 16 characters of encryption_key —
+  never randomly generated independently.
+  The user does not need to provide them unless they have specific
+  requirements.
+
+---
+
+## Step-by-Step Execution
+
+---
+
+### Phase 0 — Project Information (runs ONCE per repo)
+
+Check `context.project_info` — if already populated, skip Phase 0 entirely.
+
+0a. Run task: `ask-project-info-doc`
+    Stores: `context.project_info.has_doc`, `.doc_url` or `.doc_content`, `.from_doc`
+
+0b. Run task: `ask-project-scope-of-work`
+    Stores: `context.project_info.has_sow`, `.sow_url` or `.sow_content`, `.from_sow`
+
+0c. Run task: `ask-project-figma`
+    Stores: `context.project_info.has_figma`, `.figma_url`, `.from_figma`
+
+After all three tasks:
+  Agent synthesizes all collected information and builds:
+  `context.project_info.summary` — 150–200 word plain text summary including:
+    - What the project does
+    - Key features identified
+    - Entities/modules detected
+    - Tech preferences mentioned
+    - Third-party integrations noted
+
+  `context.project_info.detected_entities[]` — flat list of data entities found
+    Example: ["users", "admins", "bots", "orders", "products"]
+
+  Agent uses this summary for ALL remaining suggestions in this and future workflows.
+
+---
+
+### Phase 1 — Project Type
+
+0. Run task: `ask-init-mode`
+   - Stores: `context.current_init.init_mode`
+   - Values: "fast" | "manual"
+
+1. Run task: `ask-project-type`
+   - Stores: `context.current_init.project_type`
+   - Valid values: `nodejs`, `reactjs`, `database-only`
+
+    1b. If `project_type == nodejs`:
+    - Run task: `ask-client-type`
+      Stores: `context.current_init.client_type`
+
+    - Run task: `ask-encrypted-transport`
+      Stores: `context.current_init.encrypted_transport`
+
+    - Run task: `ask-supported-languages`
+      Stores: `context.current_init.supported_languages[]`
+
+2. If `project_type == reactjs`:
+   - Run task: `ask-linked-service`
+     This enforces the backend requirement. If no NodeJS service exists,
+     the task aborts the workflow with instructions. Otherwise it:
+     - Stores: `context.current_init.linked_service`
+     - Stores: `context.current_init.linked_service_port`
+     - Inherits and stores: `encryption_key`, `encryption_iv`, `api_key`
+       from the selected backend service into `context.current_init`
+   - Skip Phase 2 (no DB questions for frontend)
+   - Skip Phase 4 (no package author/name questions — handled by fast defaults)
+   - Skip Phase 5 (no api-key, encryption-key, redis questions — inherited
+     from linked backend, never asked from user)
+   - Jump directly to Phase 3 (service identity)
+
+3. If `project_type == nodejs` or `database-only`:
+   - Continue to Phase 2
+
+---
+
+### Phase 2 — Database (for nodejs and database-only)
+
+4. Run task: `ask-database-type`
+   - If `context.db.type` already exists → inform user and ask:
+     use existing or configure new?
+   - Stores: `context.db.type`
+
+5. If `init_mode == "manual"`:
+   Run task: `ask-database-config`
+   - Collects: name, host, port, user in one grouped display
+   - Stores: `context.db.name`, `context.db.host`,
+     `context.db.port`, `context.db.user`
+
+   If `init_mode == "fast"`:
+   Run task: `ask-database-name`
+   - Stores: `context.db.name`
+   Run task: `ask-database-user`
+   - Stores: `context.db.user`
+   (host and port will be auto-populated by generate-fast-defaults)
+
+9. Delegate to `database-agent` — generate database folder at the
+   REPOSITORY ROOT — not inside the service folder.
+   The database/ directory is always a sibling of service folders,
+   never a child. All services share the same database directory.
+
+   Path anchor: all paths below are relative to repository root.
+
+   ## Database Folder Existence Check (CRITICAL)
+
+   Before generating ANY database files, check whether
+   `<repo_root>/database/<db_type>/` already exists on disk.
+
+   ### If database folder does NOT exist → generate everything:
+   - <repo_root>/database/<db_type>/migrations/ (empty, ready for table files)
+   - <repo_root>/database/<db_type>/create-schema.sql (header only)
+   - <repo_root>/database/<db_type>/setup-database.sh (Linux/Mac runner)
+   - <repo_root>/database/<db_type>/setup-database.ps1 (Windows runner)
+   - <repo_root>/database/<db_type>/reset-database.sh (dev-only reset)
+   - <repo_root>/database/<db_type>/seeds/ (empty with .gitkeep)
+   - <repo_root>/database/README.md
+
+   Then run task: generate-tbl-user-deviceinfo
+   (only for nodejs projects — not database-only)
+
+   ### If database folder ALREADY exists → skip folder generation entirely:
+   Inform user:
+   "Database folder already exists at database/<db_type>/. Skipping
+   folder generation — your existing migrations are untouched."
+
+   Then check: does `database/<db_type>/migrations/1-setup-tbl-user-deviceinfo.sql`
+   already exist on disk?
+   - If YES → skip generate-tbl-user-deviceinfo entirely.
+     Inform user: "tbl_user_deviceinfo migration already exists. Skipping."
+   - If NO AND project_type == nodejs → run task: generate-tbl-user-deviceinfo.
+     This handles the case where database-only was initialized first
+     and the NodeJS system table was never created.
+   - If NO AND project_type == database-only → skip. This table is
+     not needed for database-only projects.
+
+10. Inform user:
+    "Database folder initialized. You can now run @db:create-table
+    to add your first table, or continue to scaffold your service below."
+
+11. If `project_type == database-only`:
+    - Skip Phases 3–5 entirely
+    - Jump directly to Phase 6 (confirmation and final summary)
+
+---
+
+### Phase 3 — Service Identity
+
+12. Run task: `ask-service-name`
+    - Must be unique across `context.services`
+    - Agent suggests name from `context.project_info.detected_entities`
+      if relevant
+    - Stores: `context.current_init.service_name`
+
+13. If `init_mode == "manual"`:
+    Run task: `ask-service-port`
+    - Must not conflict with existing ports in `context.services`
+    - Stores: `context.current_init.port`
+
+14. Run task: `ask-service-description`
+    - Stores: `context.current_init.description`
+
+---
+
+### Phase 4 — Package Info (nodejs only, manual mode only — skipped for reactjs)
+
+15. If `init_mode == "manual"`:
+    Run task: `ask-package-name`
+    - Default: service_name
+    - Stores: `context.current_init.package_name`
+
+16. If `init_mode == "manual"`:
+    Run task: `ask-package-author`
+    - Stores: `context.current_init.author`
+
+---
+
+### Phase 5 — Runtime Config (nodejs only — skipped entirely for reactjs)
+
+17. If `init_mode == "manual"`:
+    Run task: `ask-api-key`
+    - Auto-generate suggestion (32 chars)
+    - Stores: `context.current_init.api_key`
+
+18. If `init_mode == "manual"`:
+    Run task: `ask-encryption-key`
+    - Enforce exactly 32 characters
+    - Auto-generate suggestion
+    - Stores: `context.current_init.encryption_key`
+
+19. If `init_mode == "manual"`:
+    Run task: `ask-encryption-iv`
+    - Enforce exactly 16 characters
+    - Auto-generate suggestion
+    - Stores: `context.current_init.encryption_iv`
+
+Note: KEY and IV are always generated regardless of encrypted_transport
+value. They are used for password encryption even when transport is
+not encrypted.
+
+20. If `init_mode == "manual"`:
+    Run task: `ask-redis-config`
+    - Collects: host and port in one grouped display
+    - Stores: `context.current_init.redis_host`,
+      `context.current_init.redis_port`
+    (If init_mode == "fast" → handled by generate-fast-defaults)
+
+---
+
+### Phase 5b — Auto-populate Defaults (fast mode, nodejs only)
+
+Run task: `generate-fast-defaults`
+- Condition: only runs if `context.current_init.init_mode == "fast"`
+  AND `context.current_init.project_type == "nodejs"`
+- For `project_type == "reactjs"` → skip entirely. All security values
+  were already inherited from the linked backend in ask-linked-service.
+  Only port and package defaults need auto-filling — see step 13.
+- Silently sets all values not yet in context.current_init
+- No output, no questions — values appear in summary
+- See task description for full list of what is auto-generated
+
+---
+
+### Phase 6 — Single Confirmation, Then Generate Everything
+
+22. Run task: `show-init-summary`
+    - Runs pre-generation validation before displaying anything
+    - Resolves any BLOCKERs interactively before showing the summary
+    - Displays all collected values with auto-generated markers
+    - Shows any non-blocking WARNINGs
+    - Shows the 5-wave generation plan
+    - Asks ONE question: "Confirm and generate all files?
+      (yes / no / change a value)"
+    - If yes → proceed immediately to step 23 — NO further confirmations
+    - If no → abort, nothing created
+    - If change → re-run that specific ask-* task → re-validate →
+      return to show-init-summary
+
+23. Branch on `context.current_init.project_type`:
+
+    ---
+
+    ## IF project_type == "nodejs"
+
+    Read `.codeninja/agent/nodejs-agent.md`.
+    Execute ALL generation steps below directly as the nodejs-agent.
+    Do NOT proceed to step 24 until every file listed in Waves 1–5
+    has been confirmed written to disk.
+
+    Pass values into generation:
+    - Full `context.current_init` + `context.db`
+    - `context.current_init.client_type`
+    - `context.current_init.encrypted_transport`
+    - `context.current_init.supported_languages`
+
+    Generation rules:
+    - Do NOT pause between waves
+    - Do NOT ask for confirmation on individual files or folders
+    - Do NOT skip any file — every file listed in every wave is required
+    - ALL paths below are relative to <service_name>/ — NOT repo root
+    - Step 24 MUST NOT run until ALL 5 waves are complete
+
+    ## COMPLETION GATE (nodejs)
+    Before proceeding to step 24, verify these files 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 of these are missing → generate them now before continuing.
+    Only proceed to step 24 when ALL are confirmed present.
+
+    ## Generation Wave Structure (nodejs)
+
+    ### Why waves exist
+    All files within a wave share zero generation-time dependencies on
+    each other — they all read only from context.current_init and
+    context.db which are fully loaded before Wave 1 begins.
+    Waves only exist where one file must know the output of another
+    file before it can be written correctly.
+
+    ### Wave 1 — Foundation (no dependencies, generate all simultaneously)
+    These files depend only on context values. None depend on each other.
+
+    - package.json → task: generate-package-json
+    - .env and .env.example → from context.current_init values
+    - .gitignore → task: generate-gitignore
+    - README.md → task: generate-readme
+    - config/constants.js → task: generate-constants
+    - config/template.js → task: generate-template
+    - logger/logging.js → task: generate-logging
+    - utilities/encryption.js → task: generate-encryption
+    - languages/<lang>.js for each in supported_languages[] → task: generate-language-en
+    - enc_dec.html OR enc_dec.php (based on client_type) → task: generate-enc-dec-html or generate-enc-dec-php
+    - <service_name>/pem/ directory with .gitkeep
+    - <service_name>/images/ directory with .gitkeep
+    - <service_name>/logger/logs/ directory with .gitkeep
+
+    ### Wave 2 — Infrastructure (depend on Wave 1 context, not on Wave 1 files)
+    These files reference logging.js and encryption.js at runtime but
+    their generation only needs context values — they can be written
+    while Wave 1 is still completing.
+
+    - config/database.js → task: generate-database
+    - utilities/ioRedis.js → task: generate-ioRedis
+    - utilities/response.js → task: generate-response
+
+    ### Wave 3 — Service Layer (depend on Wave 2 context)
+    These files reference database, ioRedis, and response at runtime.
+    Generation needs only context values.
+
+    - config/common.js → task: generate-common
+    - utilities/validator.js → task: generate-validator
+    - utilities/notification.js → task: generate-notification
+    - middleware/rateLimiter.js → task: generate-rateLimiter
+
+    ### Wave 4 — Middleware and Business Layer
+    headerValidator references encryption, response, ioRedis, and
+    all language files — all of which are complete by now.
+    route.js and model.js reference common, database, encryption,
+    response, validator — all complete by now.
+    swagger_doc.json skeleton needs no other generated files.
+    All four can be written simultaneously.
+
+    - middleware/headerValidator.js → task: generate-headerValidator
+    - modules/v1/<ServiceName>/route.js → task: generate-route
+    - modules/v1/<ServiceName>/<service>_model.js → task: generate-model
+    - document/v1/swagger_doc.json (skeleton) → task: generate-swagger (Mode 1)
+
+    ### Wave 5 — Orchestration Layer (must come last)
+    route_manager.js must know which module routes exist so it can
+    register them. It reads the module list from context.current_init
+    and the route files from Wave 4.
+    app.js must know the route_manager path.
+    Both depend on Wave 4 completing first. They can be written
+    simultaneously with each other.
+
+    - modules/v1/route_manager.js → task: generate-route-manager
+    - app.js → task: generate-app
+
+    ### Wave 6 — Docker Containerization (post-completion)
+    These files depend on the complete service being functional.
+    Can be written simultaneously.
+
+    - Dockerfile → task: generate-dockerfile
+    - .dockerignore → task: generate-dockerignore
+
+    ---
+
+    ## IF project_type == "reactjs"
+
+    Read `.codeninja/agent/reactjs-agent.md`.
+    Execute ALL generation steps below directly as the reactjs-agent.
+    Do NOT proceed to step 24 until every file listed in Waves 1–3
+    has been confirmed written to disk.
+
+    Pass values into generation:
+    - Full `context.current_init` including `linked_service`,
+      `linked_service_port`, `encryption_key`, `encryption_iv`, `api_key`
+
+    Generation rules:
+    - Do NOT pause between waves
+    - Do NOT ask for confirmation on individual files
+    - Do NOT skip any file — every file listed is required
+    - ALL paths are relative to <service_name>/ — NOT repo root
+    - Step 24 MUST NOT run until ALL 3 waves are complete
+
+    ## COMPLETION GATE (reactjs)
+    Before proceeding to step 24, verify these files exist on disk:
+    - <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
+    If any are missing → generate them now before continuing.
+    Only proceed to step 24 when ALL are confirmed present.
+
+    ## Generation Wave Structure (reactjs)
+
+    ### Wave 1 — Foundation (no dependencies)
+    All depend only on context values.
+
+    - package.json → task: generate-react-package-json
+    - .env and .env.example → task: generate-react-env
+      (values inherited from linked backend — no user input)
+    - .gitignore → task: generate-react-gitignore
+    - README.md → task: generate-readme
+      (agent adapts content for ReactJS: no Redis, no DB setup,
+      shows npm start instead of node app.js)
+    - public/index.html → task: generate-react-index-html
+    - public/assets/css/style.css → empty file with a reset comment
+    - public/robots.txt → standard disallow-all scaffold default
+    - public/favicon.ico → placeholder note (developer replaces)
+    - .htaccess (root) → task: generate-react-htaccess
+    - public/.htaccess → task: generate-react-htaccess
+
+    ### Wave 2 — API Layer
+    apiClient.js depends on .env values being defined (Wave 1).
+    apiHandler.js depends on apiClient.js being available.
+    Both can be written simultaneously since apiHandler only imports
+    from apiClient by reference — it does not read apiClient's content.
+
+    - src/api/apiClient.js → task: generate-react-api-client
+    - src/api/apiHandler.js → task: generate-react-api-handler
+
+    ### Wave 3 — Application Shell (must come last)
+    App.jsx must know which page components exist to import them.
+    index.jsx must import App.
+    Welcome page can be written alongside App.jsx since App only
+    imports it by reference.
+
+    - src/pages/Welcome/index.jsx → task: generate-react-welcome-page
+    - src/pages/Welcome/Welcome.module.css → task: generate-react-welcome-page
+    - src/App.jsx → task: generate-react-app-jsx
+    - src/index.jsx → task: generate-react-index-jsx
+    - src/components/ → create empty directory with .gitkeep
+
+    ### Wave 4 — Docker Containerization (post-completion)
+    These files depend on the complete React app being functional.
+    Can be written simultaneously.
+
+    - Dockerfile → task: generate-react-dockerfile
+    - nginx.conf → task: generate-react-dockerfile (same task generates both)
+    - .dockerignore → task: generate-dockerignore (reuse NodeJS task, adapted for React)
+
+23b. Run task: `generate-ide-configs`
+    - Condition: only on the FIRST @initialize-project run in this repo
+      (check: was context.initialized_at empty before this run started?)
+    - Writes: `.vscode/mcp.json` (VS Code)
+    - Writes: `.cursor/mcp.json` (Cursor)
+    - Prints: Claude Desktop config snippet for the user to add manually
+    - Skip silently if either config file already exists
+    - Do NOT block on the Claude Desktop step — it is print-only
+
+23c. Run task: `generate-docker-compose`
+    - Condition: ALWAYS run on every @initialize-project
+    - If docker-compose.yml does NOT exist at repo root → generate complete file
+    - If docker-compose.yml DOES exist → update it by adding the new service
+    - Also generate/update .env.docker and .env.docker.example at repo root
+    - Location: <repository_root>/docker-compose.yml (NOT inside service folder)
+
+24. Run task: `write-context`
+    - Set `project_name` = `context.current_init.service_name`
+      (top-level key — required for context.json to be valid)
+    - Set `initialized_at` = ISO now (top-level — first service init)
+    - Set `last_command` = "initialize-project"
+    - Append new service to `context.services[<service_name>]`
+      with all values from `context.current_init`
+    - For reactjs services: also store `linked_service` and
+      `linked_service_port` in the service entry so future commands
+      know which backend this frontend is bound to
+    - Update `context.project_info` with `initialized_at` timestamp
+    - Clear `context.current_init`
+
+25. Run task: `show-final-summary`
+    - Read `.codeninja/tasks/show-final-summary.task.md`
+    - List all files created in Waves 1–5
+    - Show startup commands
+    - Offer next steps: @db:create-table, @create-api, @design
+
+    NOTE: show-final-summary only runs AFTER step 24 (write-context)
+    completes successfully. Never show the final summary before
+    context.json has been written.