prjct-cli 0.18.2 → 0.19.0

package/templates/global/docs/agents.md

@@ -0,0 +1,88 @@
+# Using Agents
+
+## What Are Agents?
+
+Agents are specialized Claude configurations for different domains:
+
+| Agent | Domain | When to Use |
+|-------|--------|-------------|
+| `fe.md` | Frontend | React, CSS, UI components |
+| `be.md` | Backend | APIs, databases, servers |
+| `ux.md` | UX Design | Layouts, user flows |
+| `qa.md` | Testing | Tests, QA, bug fixes |
+| `docs.md` | Documentation | README, docs, comments |
+
+## Agent Location
+
+Agents live in global storage:
+
+```
+~/.prjct-cli/projects/{projectId}/agents/
+├── fe.md       # Frontend specialist
+├── be.md       # Backend specialist
+├── ux.md       # UX specialist
+├── qa.md       # Testing specialist
+└── docs.md     # Documentation specialist
+```
+
+## When to Read Agent Files
+
+Read the relevant agent file before working in that domain:
+
+```
+Task: "implement React component"
+→ Read agents/fe.md for React patterns
+→ Follow detected conventions
+
+Task: "add API endpoint"
+→ Read agents/be.md for API patterns
+→ Follow project architecture
+```
+
+## Agent File Structure
+
+Each agent file contains:
+
+```markdown
+---
+name: fe
+description: Frontend specialist for React/TypeScript
+tools: Read, Write, Glob, Grep, Bash
+---
+
+## Expertise
+- React components and hooks
+- TypeScript patterns
+- CSS/styling conventions
+
+## Project Patterns
+- Components in src/components/
+- Use functional components
+- CSS modules for styling
+
+## Code Conventions
+- Named exports
+- Props interfaces defined inline
+- Error boundaries for async components
+```
+
+## Auto-Detection
+
+When starting a task with `/p:now`, agents are auto-detected by keywords:
+
+| Keywords | Agent |
+|----------|-------|
+| UI, frontend, React, component, CSS | `fe` |
+| API, backend, database, server | `be` |
+| design, UX, layout, wireframe | `ux` |
+| test, QA, bug, coverage | `qa` |
+| docs, README, documentation | `docs` |
+
+## Agent Generation
+
+Agents are generated by `/p:sync` based on:
+- Detected tech stack (package.json, etc.)
+- Project structure
+- Code patterns found in codebase
+
+Re-run `/p:sync` to regenerate agents after major changes.

package/templates/global/docs/architecture.md

@@ -0,0 +1,103 @@
+# prjct Architecture
+
+## Write-Through Pattern
+
+All data flows through three layers:
+
+```
+User Action → Storage (JSON) → Context (MD) → Sync Events (JSONL)
+```
+
+### Layer Responsibilities
+
+| Layer | Path | Purpose | Format |
+|-------|------|---------|--------|
+| **Storage** | `storage/*.json` | Source of truth | JSON |
+| **Context** | `context/*.md` | Claude-readable summaries | Markdown |
+| **Sync** | `sync/pending.json` | Backend event queue | JSON array |
+| **Memory** | `memory/events.jsonl` | Audit trail | JSONL (append-only) |
+
+### Data Flow Example
+
+When user runs `/p:now "implement auth"`:
+
+1. **Storage**: Write to `storage/state.json`
+   ```json
+   { "currentTask": { "description": "implement auth", ... } }
+   ```
+
+2. **Context**: Generate `context/now.md`
+   ```markdown
+   # NOW
+   **implement auth**
+   Started: 2025-12-20T10:30:00.000Z
+   ```
+
+3. **Sync**: Append to `sync/pending.json`
+   ```json
+   { "type": "task.started", "data": {...} }
+   ```
+
+4. **Memory**: Append to `memory/events.jsonl`
+   ```json
+   {"timestamp":"...","action":"task_started","task":"implement auth"}
+   ```
+
+## File Structure
+
+```
+~/.prjct-cli/projects/{projectId}/
+├── storage/                    # SOURCE OF TRUTH
+│   ├── state.json             # Current task state
+│   ├── shipped.json           # Shipped features
+│   ├── ideas.json             # Ideas backlog
+│   └── queue.json             # Task queue
+│
+├── context/                    # CLAUDE-READABLE (generated)
+│   ├── now.md                 # Current task summary
+│   ├── shipped.md             # Recent ships
+│   └── next.md                # Priority queue
+│
+├── sync/                       # BACKEND EVENTS
+│   └── pending.json           # Events waiting for sync
+│
+├── memory/                     # AUDIT TRAIL
+│   └── events.jsonl           # Append-only log
+│
+├── agents/                     # DOMAIN SPECIALISTS
+│   ├── fe.md                  # Frontend agent
+│   ├── be.md                  # Backend agent
+│   └── ...
+│
+└── CLAUDE.md                   # Project context (read first)
+```
+
+## Storage vs Context
+
+| Aspect | Storage (JSON) | Context (MD) |
+|--------|----------------|--------------|
+| Format | Structured JSON | Human-readable Markdown |
+| Purpose | Source of truth | Claude summaries |
+| Updates | Direct writes | Generated from storage |
+| Read by | Code, Claude | Primarily Claude |
+
+## Timestamps
+
+All timestamps use ISO 8601 format:
+
+```bash
+# Prefer bun, fallback to node
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+# Output: "2025-12-20T10:30:00.000Z"
+```
+
+**NEVER** hardcode timestamps. Always generate dynamically.
+
+## IDs
+
+Use UUID v4 for all IDs:
+
+```bash
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+# Output: "550e8400-e29b-41d4-a716-446655440000"
+```

package/templates/global/docs/commands.md

@@ -0,0 +1,98 @@
+# prjct Commands Reference
+
+## Command Table
+
+| Command | Purpose | Arguments |
+|---------|---------|-----------|
+| `/p:sync` | Analyze project, generate agents | - |
+| `/p:now [task] [estimate]` | Start/show current task | task: string, estimate: "2h", "30m" |
+| `/p:done` | Complete current task | - |
+| `/p:ship [feature]` | Ship with quality checks | feature: string |
+| `/p:next` | Show priority queue | - |
+| `/p:feature [desc]` | Add feature to roadmap | desc: string |
+| `/p:idea [text]` | Quick idea capture | text: string |
+| `/p:recap` | Project overview | - |
+| `/p:progress [period]` | Show metrics | period: "week", "month" |
+| `/p:pause [reason]` | Pause current task | reason: string |
+| `/p:resume` | Resume paused task | - |
+| `/p:bug [desc]` | Report bug | desc: string |
+
+## Recommended Workflow
+
+```
+1. /p:sync      → Analyze project, generate agents
+2. /p:feature   → Plan what to build
+3. /p:now       → Start working on task
+4. [code...]    → Do the actual work
+5. /p:done      → Mark task complete
+6. /p:ship      → Ship and celebrate
+```
+
+## Command Examples
+
+### Starting Work
+```
+/p:now "implement user authentication" 2h
+```
+- Sets current task
+- Optional estimate for tracking accuracy
+
+### Completing Work
+```
+/p:done
+```
+- Calculates duration
+- Logs metrics (files changed, commits)
+- Clears current task
+
+### Shipping
+```
+/p:ship "user authentication"
+```
+- Runs lint/tests (optional)
+- Bumps version
+- Creates git commit
+- Updates CHANGELOG
+
+### Quick Capture
+```
+/p:idea "add dark mode support"
+```
+- Saves to ideas backlog
+- Doesn't interrupt current work
+
+## Natural Language Trigger
+
+Start message with `p.` for natural language:
+
+```
+p. start working on login form
+→ Executes /p:now "login form"
+
+p. done with this
+→ Executes /p:done
+
+p. ship authentication feature
+→ Executes /p:ship "authentication"
+```
+
+## Command Output Format
+
+All commands output concise responses:
+
+```
+✅ [What was done]
+
+[Key metrics if applicable]
+
+Next: [suggested action]
+```
+
+Example:
+```
+✅ implement auth (2h 15m)
+
+Files: 5 | +120/-30 | Commits: 3
+
+Next: /p:ship or /p:now
+```

package/templates/global/docs/validation.md

@@ -0,0 +1,95 @@
+# Validation Patterns
+
+## Before Any Command
+
+```javascript
+// 1. Check project exists
+const config = await Read('.prjct/prjct.config.json')
+if (!config) {
+  return "No prjct project. Run /p:init first."
+}
+
+// 2. Extract projectId
+const { projectId } = JSON.parse(config)
+
+// 3. Construct global path
+const globalPath = `~/.prjct-cli/projects/${projectId}`
+```
+
+## Before /p:done
+
+```javascript
+const state = await Read(`${globalPath}/storage/state.json`)
+
+if (!state || !state.currentTask) {
+  return "Not working on anything. Use /p:now to start a task."
+}
+
+if (state.currentTask.status !== 'active') {
+  return "No active task. Use /p:now to start one."
+}
+```
+
+## Before /p:ship
+
+```javascript
+// Check git status
+const gitStatus = await Bash('git status --porcelain')
+
+if (!gitStatus.trim()) {
+  return "No changes to ship. Make some commits first."
+}
+
+// Verify git repo
+const isGitRepo = await Bash('git rev-parse --is-inside-work-tree')
+if (!isGitRepo) {
+  return "Not a git repository. Initialize git first."
+}
+```
+
+## Before /p:pause
+
+```javascript
+const state = await Read(`${globalPath}/storage/state.json`)
+
+if (!state?.currentTask || state.currentTask.status !== 'active') {
+  return "No active task to pause."
+}
+```
+
+## Before /p:resume
+
+```javascript
+const state = await Read(`${globalPath}/storage/state.json`)
+
+if (!state?.pausedTask) {
+  return "No paused task to resume. Use /p:now to start a new task."
+}
+```
+
+## Error Handling
+
+| Error | Response | Action |
+|-------|----------|--------|
+| Config not found | "No prjct project" | STOP |
+| No current task | "Not working on anything" | STOP |
+| No paused task | "No paused task" | STOP |
+| Git fails | Use defaults for metrics | CONTINUE |
+| Write fails | Log warning | CONTINUE |
+| File not found | Return empty/default state | CONTINUE |
+
+## Path Resolution
+
+**CRITICAL**: All paths resolve to global storage.
+
+```javascript
+// Template says:
+"Read: storage/state.json"
+
+// Actually reads:
+`~/.prjct-cli/projects/${projectId}/storage/state.json`
+
+// NEVER:
+".prjct/storage/state.json"  // Wrong - local
+"./storage/state.json"       // Wrong - current dir
+```

package/templates/mcp-config.json

@@ -4,6 +4,14 @@
       "command": "npx",
       "args": ["-y", "@upstash/context7-mcp@latest"],
       "description": "Library documentation lookup - use for framework/library docs"
+    },
+    "testsprite": {
+      "command": "npx",
+      "args": ["-y", "@testsprite/testsprite-mcp@latest"],
+      "env": {
+        "API_KEY": "${TESTSPRITE_API_KEY}"
+      },
+      "description": "AI-powered test generation and execution"
     }
   },
   "usage": {
@@ -22,6 +30,34 @@
         "resolve-library-id('nextjs') → get-library-docs('/vercel/next.js', 'app router')",
         "resolve-library-id('tailwindcss') → get-library-docs('/tailwindlabs/tailwindcss', 'configuration')"
       ]
+    },
+    "testsprite": {
+      "when": [
+        "User runs /p:test ai or /p:test --testsprite",
+        "Project needs AI-generated tests for frontend or backend",
+        "Auto-fixing flaky or broken tests",
+        "Generating comprehensive test coverage"
+      ],
+      "tools": [
+        "testsprite_bootstrap_tests: Initialize testing environment",
+        "testsprite_generate_code_summary: Analyze project architecture",
+        "testsprite_generate_standardized_prd: Generate structured requirements",
+        "testsprite_generate_frontend_test_plan: Create frontend test plan",
+        "testsprite_generate_backend_test_plan: Create backend test plan",
+        "testsprite_generate_code_and_execute: Generate and run tests",
+        "testsprite_rerun_tests: Re-run tests with auto-healing"
+      ],
+      "examples": [
+        "testsprite_bootstrap_tests(projectPath, 'frontend', 'diff')",
+        "testsprite_generate_code_and_execute(projectName, projectPath)"
+      ],
+      "apiKeySetup": "Get free API key at https://testsprite.com/dashboard/api-keys",
+      "configFields": {
+        "testspriteApiKey": "API key (optional)",
+        "testspriteSkip": "'never' | 'later' | null",
+        "testspriteSkipUntil": "ISO timestamp for snooze"
+      },
+      "nonBlocking": true
     }
   }
 }

package/bin/dev.js

@@ -1,216 +0,0 @@
-#!/usr/bin/env bun
-
-/**
- * prjct dev - Start prjct web development environment
- *
- * Launches Next.js fullstack app on port 9472
- * - Frontend + API routes + WebSocket for PTY
- *
- * Usage: prjct dev [--no-open]
- */
-
-const { spawn, exec } = require('child_process')
-const path = require('path')
-const os = require('os')
-
-// Configuration
-const PORT = process.env.PRJCT_PORT || 9472
-const WEB_URL = `http://localhost:${PORT}`
-
-// Colors for terminal output
-const colors = {
-  reset: '\x1b[0m',
-  bright: '\x1b[1m',
-  dim: '\x1b[2m',
-  cyan: '\x1b[36m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  red: '\x1b[31m',
-  magenta: '\x1b[35m'
-}
-
-// Find prjct-cli root (where packages/ lives)
-function findPrjctRoot() {
-  const locations = [
-    path.join(__dirname, '..'),
-    path.join(os.homedir(), 'Apps', 'prjct', 'prjct-cli'),
-    path.join(os.homedir(), '.prjct-cli', 'source'),
-  ]
-
-  for (const loc of locations) {
-    const pkgPath = path.join(loc, 'packages')
-    try {
-      require('fs').accessSync(pkgPath)
-      return loc
-    } catch {}
-  }
-
-  return locations[0]
-}
-
-const PRJCT_ROOT = findPrjctRoot()
-const WEB_PATH = path.join(PRJCT_ROOT, 'packages', 'web')
-
-// Print banner
-function printBanner() {
-  console.log(`
-${colors.cyan}${colors.bright}╔═══════════════════════════════════════════════╗
-║                                               ║
-║   ⚡ prjct dev                                 ║
-║                                               ║
-║   App:     ${colors.green}http://localhost:${PORT}${colors.cyan}            ║
-║                                               ║
-║   ${colors.dim}Press Ctrl+C to stop${colors.cyan}${colors.bright}                        ║
-║                                               ║
-╚═══════════════════════════════════════════════╝${colors.reset}
-`)
-}
-
-// Open browser based on OS
-function openBrowser(url) {
-  const platform = os.platform()
-  let command
-
-  switch (platform) {
-    case 'darwin':
-      command = `open "${url}"`
-      break
-    case 'win32':
-      command = `start "" "${url}"`
-      break
-    default:
-      command = `xdg-open "${url}"`
-  }
-
-  exec(command, (err) => {
-    if (err) {
-      console.log(`${colors.yellow}Could not open browser automatically. Visit: ${url}${colors.reset}`)
-    }
-  })
-}
-
-// Check if port is available
-function checkPort(port) {
-  return new Promise((resolve) => {
-    const net = require('net')
-    const server = net.createServer()
-
-    server.once('error', () => resolve(false))
-    server.once('listening', () => {
-      server.close()
-      resolve(true)
-    })
-
-    server.listen(port)
-  })
-}
-
-// Wait for server to be ready
-function waitForServer(port, maxAttempts = 60) {
-  return new Promise((resolve, reject) => {
-    let attempts = 0
-
-    const check = () => {
-      const http = require('http')
-      const req = http.get(`http://localhost:${port}`, (res) => {
-        resolve(true)
-      })
-
-      req.on('error', () => {
-        attempts++
-        if (attempts >= maxAttempts) {
-          reject(new Error(`Server on port ${port} did not start`))
-        } else {
-          setTimeout(check, 500)
-        }
-      })
-
-      req.end()
-    }
-
-    check()
-  })
-}
-
-// Main function
-async function main() {
-  const args = process.argv.slice(2)
-  const noOpen = args.includes('--no-open')
-
-  // Check port
-  const portAvailable = await checkPort(PORT)
-
-  if (!portAvailable) {
-    console.log(`${colors.red}Port ${PORT} is already in use. Stop other services or set PRJCT_PORT.${colors.reset}`)
-    process.exit(1)
-  }
-
-  printBanner()
-
-  // Start Next.js with custom server
-  console.log(`${colors.cyan}Starting prjct...${colors.reset}`)
-  const webProc = spawn('npm', ['run', 'dev'], {
-    cwd: WEB_PATH,
-    env: { ...process.env, PORT: PORT.toString() },
-    stdio: ['ignore', 'pipe', 'pipe'],
-  })
-
-  webProc.stdout.on('data', (data) => {
-    const lines = data.toString().split('\n').filter(Boolean)
-    lines.forEach(line => {
-      // Show relevant output
-      if (line.includes('ready') || line.includes('Ready') || line.includes('[WS]')) {
-        console.log(`${colors.green}${line}${colors.reset}`)
-      } else if (!line.includes('╔') && !line.includes('║') && !line.includes('╚')) {
-        console.log(`${colors.dim}${line}${colors.reset}`)
-      }
-    })
-  })
-
-  webProc.stderr.on('data', (data) => {
-    const msg = data.toString().trim()
-    // Filter out common non-error messages
-    if (!msg.includes('ExperimentalWarning') && !msg.includes('punycode')) {
-      console.log(`${colors.red}${msg}${colors.reset}`)
-    }
-  })
-
-  // Wait for server and open browser
-  try {
-    console.log(`${colors.dim}Waiting for server to start...${colors.reset}`)
-    await waitForServer(PORT)
-
-    console.log(`${colors.green}${colors.bright}Ready!${colors.reset}\n`)
-
-    if (!noOpen) {
-      setTimeout(() => openBrowser(WEB_URL), 500)
-    }
-  } catch (err) {
-    console.log(`${colors.red}${err.message}${colors.reset}`)
-  }
-
-  // Handle shutdown
-  const cleanup = () => {
-    console.log(`\n${colors.yellow}Shutting down...${colors.reset}`)
-    webProc.kill()
-    process.exit(0)
-  }
-
-  process.on('SIGINT', cleanup)
-  process.on('SIGTERM', cleanup)
-
-  webProc.on('error', (err) => {
-    console.log(`${colors.red}Error: ${err.message}${colors.reset}`)
-  })
-
-  webProc.on('exit', (code) => {
-    if (code !== 0 && code !== null) {
-      console.log(`${colors.red}Exited with code ${code}${colors.reset}`)
-    }
-  })
-}
-
-main().catch((err) => {
-  console.error(`${colors.red}Error: ${err.message}${colors.reset}`)
-  process.exit(1)
-})