@roomi-fields/grillhouse 0.0.0-stage → 0.23.0

package/cadre/templates/projet/deployment/docs/04-TROUBLESHOOTING.md

@@ -0,0 +1,262 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### Application Won't Start
+
+#### Symptom
+Application fails to start with configuration errors.
+
+#### Solution
+1. Verify `.env` file exists
+2. Check all required variables are set
+3. Validate variable types
+
+```bash
+# Check .env file
+cat .env
+
+# Verify Node version
+node --version
+```
+
+---
+
+### Port Already in Use
+
+#### Symptom
+```
+Error: listen EADDRINUSE: address already in use :::3000
+```
+
+#### Solution
+1. Find the process using the port:
+   ```bash
+   # Linux/macOS
+   lsof -i :3000
+
+   # Windows
+   netstat -ano | findstr :3000
+   ```
+
+2. Kill the process or use a different port:
+   ```bash
+   # Change port in .env
+   PORT=3001
+   ```
+
+---
+
+### Build Errors
+
+#### Symptom
+TypeScript compilation fails.
+
+#### Solution
+1. Clear build artifacts:
+   ```bash
+   rm -rf dist node_modules
+   npm install
+   npm run build
+   ```
+
+2. Check TypeScript version:
+   ```bash
+   npx tsc --version
+   ```
+
+---
+
+### PM2 Issues
+
+#### Symptom
+PM2 daemon not starting or crashing.
+
+#### Solution
+1. Check PM2 logs:
+   ```bash
+   npm run daemon:logs
+   # or
+   pm2 logs project-name
+   ```
+
+2. Check status:
+   ```bash
+   pm2 status
+   ```
+
+3. Restart PM2:
+   ```bash
+   pm2 delete all
+   npm run daemon:start
+   ```
+
+4. Check memory usage:
+   ```bash
+   pm2 monit
+   ```
+
+---
+
+### Connection Refused
+
+#### Symptom
+```
+Error: connect ECONNREFUSED 127.0.0.1:3000
+```
+
+#### Solution
+1. Verify the application is running:
+   ```bash
+   pm2 status
+   # or
+   ps aux | grep node
+   ```
+
+2. Check the port configuration:
+   ```bash
+   echo $PORT
+   ```
+
+3. Test locally:
+   ```bash
+   curl http://localhost:3000/health
+   ```
+
+---
+
+### Out of Memory
+
+#### Symptom
+Application crashes with memory errors.
+
+#### Solution
+1. Increase Node memory limit:
+   ```bash
+   NODE_OPTIONS="--max-old-space-size=4096" npm start
+   ```
+
+2. Update PM2 memory limit in `ecosystem.config.cjs`:
+   ```javascript
+   max_memory_restart: '2G'
+   ```
+
+---
+
+### Permission Errors
+
+#### Symptom
+```
+Error: EACCES: permission denied
+```
+
+#### Solution
+1. Check file permissions:
+   ```bash
+   ls -la
+   ```
+
+2. Fix ownership:
+   ```bash
+   sudo chown -R $USER:$USER .
+   ```
+
+3. For npm global installs:
+   ```bash
+   npm config set prefix ~/.npm-global
+   ```
+
+---
+
+## Debugging
+
+### Enable Debug Logging
+
+```bash
+LOG_LEVEL=debug npm start
+```
+
+### Check Application Logs
+
+```bash
+# PM2 logs
+pm2 logs project-name --lines 100
+
+# Log files
+tail -f logs/pm2-out.log
+tail -f logs/pm2-error.log
+```
+
+### Test Endpoints
+
+```bash
+# Health check
+curl -v http://localhost:3000/health
+
+# With headers
+curl -v -H "Content-Type: application/json" http://localhost:3000/api/endpoint
+```
+
+## Performance Issues
+
+### Slow Response Times
+
+1. Check resource usage:
+   ```bash
+   pm2 monit
+   ```
+
+2. Enable debug logging to identify bottlenecks
+
+3. Profile the application:
+   ```bash
+   node --inspect dist/index.js
+   ```
+
+### High CPU Usage
+
+1. Check for infinite loops in logs
+2. Monitor with PM2:
+   ```bash
+   pm2 monit
+   ```
+
+## Getting Help
+
+If none of the above solutions work:
+
+1. **Check GitHub Issues**: Search for similar problems
+2. **Create an Issue**: Include:
+   - Node.js version
+   - OS and version
+   - Error messages
+   - Steps to reproduce
+3. **Enable Debug Logging**: Attach relevant logs
+
+## Useful Commands Reference
+
+```bash
+# Check Node version
+node --version
+
+# Check npm version
+npm --version
+
+# View all environment variables
+printenv | grep -E "NODE|PORT|LOG"
+
+# Test connectivity
+curl -v http://localhost:3000/health
+
+# View PM2 status
+pm2 status
+
+# View PM2 logs
+pm2 logs --lines 50
+
+# Restart PM2 application
+pm2 restart project-name
+
+# Kill all PM2 processes
+pm2 kill
+```

package/cadre/templates/projet/deployment/scripts/install.ps1

@@ -0,0 +1,100 @@
+<#
+.SYNOPSIS
+    Installation script for the project.
+
+.DESCRIPTION
+    Installs dependencies, builds the project, and sets up configuration.
+
+.EXAMPLE
+    .\install.ps1
+#>
+
+$ErrorActionPreference = "Stop"
+
+function Write-Step {
+    param([string]$Message)
+    Write-Host "`n==> $Message" -ForegroundColor Cyan
+}
+
+function Write-Success {
+    param([string]$Message)
+    Write-Host "[OK] $Message" -ForegroundColor Green
+}
+
+function Write-Error {
+    param([string]$Message)
+    Write-Host "[ERROR] $Message" -ForegroundColor Red
+}
+
+Write-Host "Project Installation" -ForegroundColor Magenta
+Write-Host "====================" -ForegroundColor Magenta
+
+# Check Node.js
+Write-Step "Checking Node.js..."
+try {
+    $nodeVersion = node --version
+    Write-Success "Node.js $nodeVersion found"
+}
+catch {
+    Write-Error "Node.js not found. Please install Node.js 18 or higher."
+    exit 1
+}
+
+# Check npm
+Write-Step "Checking npm..."
+try {
+    $npmVersion = npm --version
+    Write-Success "npm $npmVersion found"
+}
+catch {
+    Write-Error "npm not found."
+    exit 1
+}
+
+# Install dependencies
+Write-Step "Installing dependencies..."
+npm install
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Failed to install dependencies"
+    exit 1
+}
+Write-Success "Dependencies installed"
+
+# Build project
+Write-Step "Building project..."
+npm run build
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Build failed"
+    exit 1
+}
+Write-Success "Build successful"
+
+# Create .env if not exists
+Write-Step "Checking configuration..."
+if (-not (Test-Path ".env")) {
+    if (Test-Path ".env.example") {
+        Copy-Item ".env.example" ".env"
+        Write-Success "Created .env from .env.example"
+        Write-Host "Please edit .env with your configuration." -ForegroundColor Yellow
+    }
+    else {
+        Write-Host ".env.example not found, skipping .env creation" -ForegroundColor Yellow
+    }
+}
+else {
+    Write-Success ".env already exists"
+}
+
+# Create logs directory
+Write-Step "Creating logs directory..."
+if (-not (Test-Path "logs")) {
+    New-Item -ItemType Directory -Path "logs" | Out-Null
+}
+Write-Success "Logs directory ready"
+
+Write-Host "`n" -NoNewline
+Write-Host "Installation complete!" -ForegroundColor Green
+Write-Host "`nNext steps:" -ForegroundColor Yellow
+Write-Host "  1. Edit .env with your configuration"
+Write-Host "  2. Run 'npm start' to start the application"
+Write-Host "  3. Or run 'npm run daemon:start' for background mode"

package/cadre/templates/projet/deployment/scripts/start.ps1

@@ -0,0 +1,61 @@
+<#
+.SYNOPSIS
+    Start the application server.
+
+.DESCRIPTION
+    Starts the application in foreground or daemon mode.
+
+.PARAMETER Daemon
+    Run in daemon mode using PM2.
+
+.EXAMPLE
+    .\start.ps1
+    .\start.ps1 -Daemon
+#>
+
+param(
+    [switch]$Daemon
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Step {
+    param([string]$Message)
+    Write-Host "`n==> $Message" -ForegroundColor Cyan
+}
+
+function Write-Success {
+    param([string]$Message)
+    Write-Host "[OK] $Message" -ForegroundColor Green
+}
+
+# Navigate to project root
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectRoot = Resolve-Path (Join-Path $ScriptDir "..\..")
+Set-Location $ProjectRoot
+
+# Check if built
+if (-not (Test-Path "dist/index.js")) {
+    Write-Step "Building project..."
+    npm run build
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "[ERROR] Build failed" -ForegroundColor Red
+        exit 1
+    }
+}
+
+if ($Daemon) {
+    Write-Step "Starting in daemon mode..."
+    npm run daemon:start
+    if ($LASTEXITCODE -eq 0) {
+        Write-Success "Application started in daemon mode"
+        Write-Host "`nUseful commands:" -ForegroundColor Yellow
+        Write-Host "  npm run daemon:status  - Check status"
+        Write-Host "  npm run daemon:logs    - View logs"
+        Write-Host "  npm run daemon:stop    - Stop daemon"
+    }
+}
+else {
+    Write-Step "Starting application..."
+    npm start
+}

package/cadre/templates/projet/deployment/scripts/stop.ps1

@@ -0,0 +1,37 @@
+<#
+.SYNOPSIS
+    Stop the application server.
+
+.DESCRIPTION
+    Stops the application running in daemon mode.
+
+.EXAMPLE
+    .\stop.ps1
+#>
+
+$ErrorActionPreference = "Stop"
+
+function Write-Step {
+    param([string]$Message)
+    Write-Host "`n==> $Message" -ForegroundColor Cyan
+}
+
+function Write-Success {
+    param([string]$Message)
+    Write-Host "[OK] $Message" -ForegroundColor Green
+}
+
+# Navigate to project root
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectRoot = Resolve-Path (Join-Path $ScriptDir "..\..")
+Set-Location $ProjectRoot
+
+Write-Step "Stopping application..."
+npm run daemon:stop
+
+if ($LASTEXITCODE -eq 0) {
+    Write-Success "Application stopped"
+}
+else {
+    Write-Host "[WARN] Application may not have been running" -ForegroundColor Yellow
+}

package/cadre/templates/projet/deployment/scripts/test.ps1

@@ -0,0 +1,118 @@
+<#
+.SYNOPSIS
+    Test the application endpoints.
+
+.DESCRIPTION
+    Runs basic tests against the running application.
+
+.PARAMETER BaseUrl
+    Base URL of the application. Default: http://localhost:3000
+
+.EXAMPLE
+    .\test.ps1
+    .\test.ps1 -BaseUrl "http://localhost:8080"
+#>
+
+param(
+    [string]$BaseUrl = "http://localhost:3000"
+)
+
+$ErrorActionPreference = "Continue"
+
+function Write-Step {
+    param([string]$Message)
+    Write-Host "`n==> $Message" -ForegroundColor Cyan
+}
+
+function Write-Success {
+    param([string]$Message)
+    Write-Host "[PASS] $Message" -ForegroundColor Green
+}
+
+function Write-Fail {
+    param([string]$Message)
+    Write-Host "[FAIL] $Message" -ForegroundColor Red
+}
+
+function Test-Endpoint {
+    param(
+        [string]$Name,
+        [string]$Method,
+        [string]$Url,
+        [string]$Body = $null,
+        [int]$ExpectedStatus = 200
+    )
+
+    Write-Host "  Testing: $Name... " -NoNewline
+
+    try {
+        $params = @{
+            Uri = $Url
+            Method = $Method
+            ContentType = "application/json"
+            UseBasicParsing = $true
+        }
+
+        if ($Body) {
+            $params.Body = $Body
+        }
+
+        $response = Invoke-WebRequest @params
+        $status = $response.StatusCode
+
+        if ($status -eq $ExpectedStatus) {
+            Write-Host "[PASS]" -ForegroundColor Green
+            return $true
+        }
+        else {
+            Write-Host "[FAIL] Expected $ExpectedStatus, got $status" -ForegroundColor Red
+            return $false
+        }
+    }
+    catch {
+        $status = $_.Exception.Response.StatusCode.value__
+        if ($status -eq $ExpectedStatus) {
+            Write-Host "[PASS]" -ForegroundColor Green
+            return $true
+        }
+        else {
+            Write-Host "[FAIL] $($_.Exception.Message)" -ForegroundColor Red
+            return $false
+        }
+    }
+}
+
+Write-Host "API Endpoint Tests" -ForegroundColor Magenta
+Write-Host "==================" -ForegroundColor Magenta
+Write-Host "Base URL: $BaseUrl"
+
+$passed = 0
+$failed = 0
+
+# Health Check
+Write-Step "Health Check"
+if (Test-Endpoint -Name "GET /health" -Method "GET" -Url "$BaseUrl/health") {
+    $passed++
+}
+else {
+    $failed++
+}
+
+# Add more tests as needed
+# Write-Step "API Endpoints"
+# if (Test-Endpoint -Name "GET /api/resources" -Method "GET" -Url "$BaseUrl/api/resources") {
+#     $passed++
+# } else {
+#     $failed++
+# }
+
+# Summary
+Write-Host "`n" -NoNewline
+Write-Host "Results" -ForegroundColor Magenta
+Write-Host "=======" -ForegroundColor Magenta
+Write-Host "Passed: $passed" -ForegroundColor Green
+Write-Host "Failed: $failed" -ForegroundColor $(if ($failed -gt 0) { "Red" } else { "Green" })
+
+if ($failed -gt 0) {
+    exit 1
+}

package/cadre/templates/projet/docs/agents/issue-tracker.md

@@ -0,0 +1,44 @@
+# Issue tracker: Beads (`bd`)
+
+Issues for this repo live in Beads, a git-backed tracker: data under `.beads/`, commands via the `bd` CLI, ids `<prefix>-xxx` (the prefix is set by `grillhouse init`). No remote service. The project owner opens the work; agents take tickets, never invent them.
+
+## Conventions
+
+- One ticket = one agent session's worth of work; the body holds the brief, the plan, and (on close) the answer.
+- Every ticket opens with an **Architecture** section, three answers written before any code: the mature model (how the mature product of the domain handles it, named), the address (where it lives in the specified architecture), the common mechanism (existing, or missing — then the missing mechanism is the work, and the reported case only its witness). A ticket without it does not start.
+- A realisation ticket is created with its **Acceptance criteria** section (`## Critères d'acceptation`) after « Architecture »: criteria numbered `1.`, `2.`… (cited « critère 1 » in tests and comments), each a checkable statement answering a real need of the current use, edge cases and refusals included, covering every place that applies the same rule (found through the index). So the flow starts on criteria already numbered, and no agent rewrites the ticket to number them; a ticket does not go to the `testwriter` without them.
+- A change of behaviour is one ticket that passes from agent to agent, never a ticket per post: in the ticket's copy, the `testwriter` writes the tests; the `developpeur` finds them there and writes the code; the `relecteur` gives its verdict (`ACCEPTÉ` or `RENDU`, each finding naming its recipient, a role and a component) in its sheet, which the circuit writes on the same ticket; the circuit (`packages/grillhouse/scripts/circuit.mjs`) leads them, sends a lot RENDU back to the agents its findings name, and on `ACCEPTÉ` builds both lots from the copy and commits them in one commit on the branch `agent/<ticket>` through `packages/grillhouse/scripts/integration/integrer.mjs` (the ticket is labelled `en-file`); the queue (`packages/grillhouse/scripts/integration/file.mjs`) brings that branch onto main, closes the ticket and pushes main.
+- One ticket, one delivery: a goal whose split is unknown opens an exploration ticket (no code, agent `explorateur`), which closes on the realisation tickets it proposes, recorded closed and labelled `decouverte`; the supervisor reopens those the owner validates. A realisation ticket names the components it touches (« Numéros et titres ») and enters in one commit, under its own number alone; the `commit-msg` hook refuses a second commit for a closed ticket whose delivery stands, and lets a ticket reopened after its delivery (open in Beads) take correction commits; a revert (`Revert "…"`, `Reapply "…"`) passes and withdraws the delivery it names.
+- An open ticket is born of the owner's word, or of a direct need of a project that uses the frame (a defect it meets). A discovery during work is recorded, with its example and address, in a closed ticket under the ticket that found it, labelled `decouverte` (see « Numéros et titres »); it reopens on the owner's word. A discovery that blocks stops the agent, and its handoff names it. The supervisor brings to the owner the discoveries that touch a real use.
+- Types: `epic` (a chantier, always at the root: an epic has no mother), `task`, `bug`, `decision`. A mother under a chantier is a `task`; the session start lists an epic that has a mother. Priority `0`-`4`, 0 highest.
+- Comments carry progress and handoffs: `bd comments add <id> "<text>"`. In a ticket's circuit, each comment carries its author: the circuit launches each session with `BEADS_ACTOR` naming its role (`testwriter <composant>`, `developpeur <composant>`, `relecteur`, `regulateur`), writes its own lines (`Circuit · …`) as `circuit` and the reviewer's verdict as `relecteur`; the queue (`packages/grillhouse/scripts/integration/file.mjs`) writes as `file`; a verdict is a comment of the author `relecteur` whose first word is `ACCEPTÉ` or `RENDU`. An agent does not change its author: its rights refuse bd's `--actor`, `-a`/`--author` and the variable `BEADS_ACTOR`.
+- Labels used by the skills: `a-valider` (proposed, waits for the owner), `decouverte` (a discovery recorded closed; it reopens on the owner's word), `circuit` (the owner said to launch it: the ticket is in the flow, and only such a ticket waits in the pane's AGENTS), `attend-responsable` (a rule waits for the owner's word), `arbitrage` (a design question went to the `referent-technique` agent; the lot enters only with its verdict).
+
+## Numéros et titres
+
+- A chantier is an `epic` at the root; under it, every subject has a mother ticket (a `task`), open while work remains under it. Every ticket is created under its mother, so Beads numbers it natively: `320.1`, `320.2`, `320.2.1`.
+- The title reads `<number> — <subject> — <components>`, the number being the id without the whole prefix of the project (`bd config get issue_prefix`, which may hold dashes: `bp-mono-`). The components are the ones the ticket touches, separated by commas, the provider first, then its readers (charte, « Un ticket de réalisation nomme ses composants »): `320.5.2 — Publie l'objet de la scène — 020-loader, 050-emitter`. A mother takes `parent` as its component. The survey of the components (`npx grillhouse composants-affectes --description <file>` on a draft, `npx grillhouse composants-affectes <id>` on a ticket) gives that list from the elements the Architecture section and the criteria name: for each, its provider and its readers (the consumers its INTERFACE.md declares, the packages that import it, the tests of other packages that name it). A component it finds that the ticket does not change is admitted out of the title, with its reason, once the ticket exists: `npx grillhouse composants-affectes <id> --admettre <component> --raison "<reason>"`, a line at the ticket. The circuit runs the survey again before the first testwriter, and stops at `composants-manquants` (21) on a component it finds that the title misses and no admission covers.
+- Creating one: `npx grillhouse ticket <mother> <subject> <components> <body> [label]` prints its id; the label is `a-valider` by default, and `decouverte` creates it closed (« découverte consignée »).
+
+- A ticket goes through the tree of its circuit, the « auto » steps included (`packages/grillhouse/scripts/etapes.mjs`, the one list): 0 Exploration (`explorateur`); 1 Ouverture: 1.1 Relevé des composants, 1.2 Questionnement (`questionneur` ⇄ `referent-technique`); 2 Composants, for each component: 2.1 Tests (`testwriter`), 2.2 Preuve du rouge, 2.3 Code (`developpeur`), 2.4 Contrôles; 3 Passe finale; 4 Relecture (`relecteur`); 5 Intégration: 5.1 Commit, 5.2 File : main, poussée, CI. Out of the sequence, under the stopped step, the Arbitrage de l'arrêt (`regulateur` ⇄ `questionneur`). The `referent-technique` also settles a design question the supervisor asks him. One says « 320.2.1, step 2.3 »; the pane shows each ticket at its step.
+
+## When a skill says "publish to the issue tracker"
+
+`npx grillhouse ticket` (« Numéros et titres »); a child never inherits its mother's `circuit`.
+
+## When a skill says "fetch the relevant ticket"
+
+`bd show <id>`, then `bd comments <id>` (the handoff lives there). `bd list --parent <id>` lists an epic's children; `bd list --pretty` shows the tree.
+
+## Working a ticket
+
+- **Frontier**: `bd ready` → open, unblocked, unclaimed, in order.
+- **Claim**: `bd update <id> --claim` (assignee = you, status in_progress) **before any work**.
+- **Blocking**: `bd dep add <blocked-id> <blocker-id>`; `bd blocked` shows what waits.
+- **Resolve**: `bd comments add <id> "Réponse : …"` then `bd close <id> --reason "<motif>"`.
+
+## Handoff
+
+The handoff is a comment on the ticket being worked, written by `bd comments add <id>`, not a temp file or a skill's document: the next session finds it with `bd show` or `bd comments <id>`.
+
+The time each session takes is the register's (`packages/grillhouse/scripts/registre.mjs`), which reads its transcript: the handoff does not declare it. A session the circuit leads ends on its sheet, the structured output its role's schema describes (`packages/grillhouse/scripts/resultats.mjs`), which the circuit reads; the handoff is for the human and the next session of its author. A discovery of such a session goes into its sheet (`decouvertes`), which the circuit files closed under the ticket.

package/cadre/templates/projet/ecosystem.config.cjs

@@ -0,0 +1,73 @@
+/**
+ * PM2 Ecosystem Configuration
+ *
+ * This file configures PM2 for running the application as a background daemon.
+ *
+ * Usage:
+ *   npm run daemon:start   - Start the daemon
+ *   npm run daemon:stop    - Stop the daemon
+ *   npm run daemon:restart - Restart the daemon
+ *   npm run daemon:logs    - View logs
+ *   npm run daemon:status  - Check status
+ *   npm run daemon:delete  - Remove from PM2
+ *
+ * @see https://pm2.keymetrics.io/docs/usage/application-declaration/
+ */
+
+module.exports = {
+  apps: [
+    {
+      // Application name (used in PM2 commands)
+      name: 'project-name',
+
+      // Entry point script
+      script: 'dist/index.js',
+
+      // Working directory
+      cwd: __dirname,
+
+      // Process mode: 'fork' for single instance, 'cluster' for multiple
+      exec_mode: 'fork',
+      instances: 1,
+
+      // Auto-restart configuration
+      autorestart: true,
+      watch: false,
+      max_memory_restart: '1G',
+
+      // Restart delay strategy
+      exp_backoff_restart_delay: 100,
+      max_restarts: 10,
+      restart_delay: 3000,
+
+      // Environment variables
+      env: {
+        NODE_ENV: 'production',
+        PORT: 3000
+      },
+      env_development: {
+        NODE_ENV: 'development',
+        PORT: 3000
+      },
+
+      // Logging configuration
+      log_date_format: 'YYYY-MM-DD HH:mm:ss',
+      error_file: 'logs/pm2-error.log',
+      out_file: 'logs/pm2-out.log',
+      merge_logs: true,
+
+      // Process identification
+      pid_file: 'logs/pm2.pid',
+
+      // Graceful shutdown
+      kill_timeout: 5000,
+      listen_timeout: 10000,
+
+      // Health monitoring
+      min_uptime: '10s',
+
+      // Node.js specific
+      node_args: '--enable-source-maps'
+    }
+  ]
+};