@cluesmith/codev 1.1.0

package/templates/bin/agent-farm

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Thin wrapper - forwards all commands to @cluesmith/codev af
+# This script allows projects to use ./codev/bin/agent-farm without
+# having codev installed globally.
+
+# First, try the globally installed 'af' command (from @cluesmith/codev)
+if command -v af &> /dev/null; then
+  exec af "$@"
+fi
+
+# Fall back to npx if af is not globally installed
+if command -v npx &> /dev/null; then
+  exec npx @cluesmith/codev af "$@"
+fi
+
+echo "Error: Could not find 'af' command" >&2
+echo "Install @cluesmith/codev globally: npm install -g @cluesmith/codev" >&2
+exit 1

package/templates/bin/annotate-server.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * Simple annotation server for the Architect-Builder pattern.
+ * Serves the annotation viewer and handles file saves.
+ *
+ * Usage: node annotate-server.js --builder XXXX --file path/to/file.ts --port 8080
+ */
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const getArg = (name) => {
+  const idx = args.indexOf('--' + name);
+  return idx !== -1 ? args[idx + 1] : null;
+};
+
+const builderId = getArg('builder');
+const filePath = getArg('file');
+const port = parseInt(getArg('port') || '8080', 10);
+
+if (!builderId || !filePath) {
+  console.error('Usage: annotate-server.js --builder XXXX --file path/to/file.ts [--port 8080]');
+  process.exit(1);
+}
+
+// Paths
+const projectRoot = process.cwd();
+const buildersDir = path.join(projectRoot, '.builders');
+const builderDir = path.join(buildersDir, builderId);
+const fullFilePath = path.join(builderDir, filePath);
+const templatePath = path.join(projectRoot, 'codev', 'templates', 'annotate.html');
+
+// Validate builder exists
+if (!fs.existsSync(builderDir)) {
+  console.error(`Builder directory not found: ${builderDir}`);
+  process.exit(1);
+}
+
+// Validate file exists
+if (!fs.existsSync(fullFilePath)) {
+  console.error(`File not found: ${fullFilePath}`);
+  process.exit(1);
+}
+
+// Get language from extension
+const ext = path.extname(filePath).slice(1).toLowerCase();
+const langMap = {
+  js: 'javascript', ts: 'typescript', jsx: 'javascript', tsx: 'typescript',
+  py: 'python', sh: 'bash', bash: 'bash',
+  md: 'markdown', html: 'markup', css: 'css',
+  json: 'json', yaml: 'yaml', yml: 'yaml'
+};
+const lang = langMap[ext] || ext;
+
+// Create server
+const server = http.createServer((req, res) => {
+  // CORS headers
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(200);
+    res.end();
+    return;
+  }
+
+  // Serve annotation viewer
+  if (req.method === 'GET' && (req.url === '/' || req.url === '/index.html')) {
+    try {
+      let template = fs.readFileSync(templatePath, 'utf-8');
+      const fileContent = fs.readFileSync(fullFilePath, 'utf-8');
+
+      // Replace placeholders
+      template = template.replace(/\{\{BUILDER_ID\}\}/g, builderId);
+      template = template.replace(/\{\{FILE_PATH\}\}/g, filePath);
+      template = template.replace(/\{\{FILE\}\}/g, path.basename(filePath));
+      template = template.replace(/\{\{LANG\}\}/g, lang);
+
+      // Inject file content
+      const escapedContent = JSON.stringify(fileContent);
+      template = template.replace(
+        '// FILE_CONTENT will be injected by the server',
+        `init(${escapedContent});`
+      );
+
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(template);
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end('Error loading viewer: ' + err.message);
+    }
+    return;
+  }
+
+  // Handle file save
+  if (req.method === 'POST' && req.url === '/save') {
+    let body = '';
+    req.on('data', chunk => body += chunk);
+    req.on('end', () => {
+      try {
+        const { file, content } = JSON.parse(body);
+
+        // Security: only allow saving the opened file
+        if (file !== filePath) {
+          res.writeHead(403, { 'Content-Type': 'text/plain' });
+          res.end('Cannot save to different file');
+          return;
+        }
+
+        fs.writeFileSync(fullFilePath, content, 'utf-8');
+        console.log(`Saved: ${fullFilePath}`);
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Error saving file: ' + err.message);
+      }
+    });
+    return;
+  }
+
+  // 404 for everything else
+  res.writeHead(404, { 'Content-Type': 'text/plain' });
+  res.end('Not found');
+});
+
+server.listen(port, () => {
+  console.log(`\nAnnotation Viewer`);
+  console.log(`================`);
+  console.log(`Builder: ${builderId}`);
+  console.log(`File:    ${filePath}`);
+  console.log(`\nOpen in browser: http://localhost:${port}`);
+  console.log(`\nPress Ctrl+C to stop the server`);
+});

package/templates/bin/codev-doctor

@@ -0,0 +1,335 @@
+#!/usr/bin/env bash
+#
+# codev-doctor - Verify Codev installation and dependencies
+#
+# Usage: ./codev/bin/codev-doctor
+#
+# Checks:
+#   - Core dependencies: node, tmux, ttyd, git, gh, python
+#   - AI CLI dependencies: claude, gemini, codex (at least one required)
+#   - Python packages: typer (for consult tool)
+#
+# Exit codes:
+#   0 - All required dependencies OK
+#   1 - Missing required dependencies
+#
+
+set -euo pipefail
+
+# Colors (disable if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    BOLD='\033[1m'
+    NC='\033[0m' # No Color
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    BOLD=''
+    NC=''
+fi
+
+# Counters
+ERRORS=0
+WARNINGS=0
+
+# Detect OS for install hints
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    IS_MACOS=true
+else
+    IS_MACOS=false
+fi
+
+# Print header
+echo -e "${BOLD}Codev Doctor${NC} - Checking your environment"
+echo "============================================"
+echo ""
+
+# Helper function to check if a command exists
+command_exists() {
+    command -v "$1" &> /dev/null
+}
+
+# Helper function to print status
+print_status() {
+    local name="$1"
+    local status="$2"
+    local version="${3:-}"
+    local note="${4:-}"
+
+    case "$status" in
+        ok)
+            printf "  ${GREEN}%s${NC} %-12s %s" "✓" "$name" "$version"
+            ;;
+        warn)
+            printf "  ${YELLOW}%s${NC} %-12s %s" "⚠" "$name" "$version"
+            ((WARNINGS++))
+            ;;
+        fail)
+            printf "  ${RED}%s${NC} %-12s %s" "✗" "$name" "$version"
+            ((ERRORS++))
+            ;;
+        skip)
+            printf "  ${BLUE}%s${NC} %-12s %s" "○" "$name" "$version"
+            ;;
+    esac
+
+    if [[ -n "$note" ]]; then
+        printf " ${BLUE}(%s)${NC}" "$note"
+    fi
+    echo ""
+}
+
+# Compare semantic versions: returns 0 if $1 >= $2
+version_gte() {
+    local v1="$1"
+    local v2="$2"
+
+    # Split versions into arrays
+    IFS='.' read -ra v1_parts <<< "$v1"
+    IFS='.' read -ra v2_parts <<< "$v2"
+
+    # Compare each part
+    for i in 0 1 2; do
+        local p1="${v1_parts[$i]:-0}"
+        local p2="${v2_parts[$i]:-0}"
+        # Remove non-numeric suffixes (e.g., "3a" -> "3")
+        p1="${p1%%[!0-9]*}"
+        p2="${p2%%[!0-9]*}"
+        p1="${p1:-0}"
+        p2="${p2:-0}"
+
+        if (( p1 > p2 )); then
+            return 0
+        elif (( p1 < p2 )); then
+            return 1
+        fi
+    done
+    return 0
+}
+
+# Extract version from various command outputs
+get_node_version() {
+    node --version 2>/dev/null | sed 's/^v//'
+}
+
+get_tmux_version() {
+    tmux -V 2>/dev/null | sed 's/tmux //' | sed 's/[a-z]$//'
+}
+
+get_ttyd_version() {
+    ttyd --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1
+}
+
+get_git_version() {
+    git --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1
+}
+
+get_python_version() {
+    python3 --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1
+}
+
+# Check core dependencies
+echo -e "${BOLD}Core Dependencies${NC} (required for Agent Farm)"
+echo ""
+
+# Node.js
+if command_exists node; then
+    version=$(get_node_version)
+    if version_gte "$version" "18.0.0"; then
+        print_status "Node.js" "ok" "$version"
+    else
+        print_status "Node.js" "fail" "$version" "need >= 18.0.0"
+    fi
+else
+    if $IS_MACOS; then
+        print_status "Node.js" "fail" "not installed" "brew install node"
+    else
+        print_status "Node.js" "fail" "not installed" "apt install nodejs npm"
+    fi
+fi
+
+# tmux
+if command_exists tmux; then
+    version=$(get_tmux_version)
+    if version_gte "$version" "3.0"; then
+        print_status "tmux" "ok" "$version"
+    else
+        print_status "tmux" "fail" "$version" "need >= 3.0"
+    fi
+else
+    if $IS_MACOS; then
+        print_status "tmux" "fail" "not installed" "brew install tmux"
+    else
+        print_status "tmux" "fail" "not installed" "apt install tmux"
+    fi
+fi
+
+# ttyd
+if command_exists ttyd; then
+    version=$(get_ttyd_version)
+    if [[ -n "$version" ]] && version_gte "$version" "1.7.0"; then
+        print_status "ttyd" "ok" "$version"
+    elif [[ -n "$version" ]]; then
+        print_status "ttyd" "fail" "$version" "need >= 1.7.0"
+    else
+        print_status "ttyd" "warn" "(version unknown)" "may be incompatible"
+    fi
+else
+    if $IS_MACOS; then
+        print_status "ttyd" "fail" "not installed" "brew install ttyd"
+    else
+        print_status "ttyd" "fail" "not installed" "build from source"
+    fi
+fi
+
+# git
+if command_exists git; then
+    version=$(get_git_version)
+    if version_gte "$version" "2.5.0"; then
+        print_status "git" "ok" "$version"
+    else
+        print_status "git" "warn" "$version" "need >= 2.5.0"
+    fi
+else
+    if $IS_MACOS; then
+        print_status "git" "fail" "not installed" "xcode-select --install"
+    else
+        print_status "git" "fail" "not installed" "apt install git"
+    fi
+fi
+
+# gh (GitHub CLI)
+if command_exists gh; then
+    # Check if authenticated
+    if gh auth status &>/dev/null; then
+        print_status "gh" "ok" "authenticated"
+    else
+        print_status "gh" "warn" "not authenticated" "gh auth login"
+    fi
+else
+    if $IS_MACOS; then
+        print_status "gh" "fail" "not installed" "brew install gh"
+    else
+        print_status "gh" "fail" "not installed" "apt install gh"
+    fi
+fi
+
+# Python
+if command_exists python3; then
+    version=$(get_python_version)
+    if version_gte "$version" "3.10.0"; then
+        print_status "Python" "ok" "$version"
+    else
+        print_status "Python" "warn" "$version" "need >= 3.10"
+    fi
+else
+    if $IS_MACOS; then
+        print_status "Python" "fail" "not installed" "brew install python"
+    else
+        print_status "Python" "fail" "not installed" "apt install python3"
+    fi
+fi
+
+echo ""
+
+# Check AI CLI dependencies
+echo -e "${BOLD}AI CLI Dependencies${NC} (at least one required)"
+echo ""
+
+AI_CLI_COUNT=0
+
+# Helper to verify AI CLI actually works (not just installed)
+verify_ai_cli() {
+    local cmd="$1"
+    local test_args="$2"
+    # Run the command with test args and capture exit code
+    # Don't use timeout (not available on macOS)
+    if "$cmd" $test_args &>/dev/null; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Claude Code
+if command_exists claude; then
+    if verify_ai_cli "claude" "--version"; then
+        print_status "Claude" "ok" "working"
+        ((AI_CLI_COUNT++))
+    else
+        print_status "Claude" "warn" "installed but not working" "check config"
+    fi
+else
+    print_status "Claude" "skip" "not installed" "npm i -g @anthropic-ai/claude-code"
+fi
+
+# Gemini CLI
+if command_exists gemini; then
+    if verify_ai_cli "gemini" "--version"; then
+        print_status "Gemini" "ok" "working"
+        ((AI_CLI_COUNT++))
+    else
+        print_status "Gemini" "warn" "installed but not working" "check GOOGLE_API_KEY"
+    fi
+else
+    print_status "Gemini" "skip" "not installed" "see github.com/google-gemini/gemini-cli"
+fi
+
+# Codex CLI
+if command_exists codex; then
+    if verify_ai_cli "codex" "--version"; then
+        print_status "Codex" "ok" "working"
+        ((AI_CLI_COUNT++))
+    else
+        print_status "Codex" "warn" "installed but not working" "check OPENAI_API_KEY"
+    fi
+else
+    print_status "Codex" "skip" "not installed" "npm i -g @openai/codex"
+fi
+
+if (( AI_CLI_COUNT == 0 )); then
+    echo ""
+    echo -e "  ${RED}✗${NC} No AI CLI working! Install and configure at least one to use Codev."
+    ((ERRORS++))
+fi
+
+echo ""
+
+# Check Python packages (for consult tool)
+echo -e "${BOLD}Python Packages${NC} (for consult tool)"
+echo ""
+
+if command_exists python3; then
+    # Check for typer
+    if python3 -c "import typer" 2>/dev/null; then
+        print_status "typer" "ok" "installed"
+    else
+        print_status "typer" "warn" "not installed" "pip install typer"
+    fi
+else
+    print_status "typer" "skip" "Python not available"
+fi
+
+echo ""
+
+# Summary
+echo "============================================"
+if (( ERRORS > 0 )); then
+    echo -e "${RED}${BOLD}FAILED${NC} - $ERRORS required dependency/dependencies missing"
+    echo ""
+    echo "Install missing dependencies and run this command again."
+    exit 1
+elif (( WARNINGS > 0 )); then
+    echo -e "${YELLOW}${BOLD}OK with warnings${NC} - $WARNINGS dependency/dependencies below recommended version"
+    echo ""
+    echo "Consider upgrading for best experience."
+    exit 0
+else
+    echo -e "${GREEN}${BOLD}ALL OK${NC} - Your environment is ready for Codev!"
+    exit 0
+fi

package/templates/builders.md

@@ -0,0 +1,30 @@
+# Active Builders
+
+Track active builder agents here. Update manually or via `architect status`.
+
+## Status Values
+
+- **spawning**: Worktree being created, ttyd starting
+- **implementing**: Builder is working
+- **blocked**: Builder waiting for architect input
+- **pr-ready**: Builder has created a PR
+- **reviewing**: Architect is reviewing the PR
+- **complete**: PR merged, ready for cleanup
+
+---
+
+## Builders
+
+<!-- Add builders below as they are spawned -->
+
+<!-- Example:
+## Builder 0003: Feature Name
+- **Branch**: builder/0003-feature-name
+- **Port**: 7681
+- **Status**: implementing
+- **Phase**: 2/4
+- **Started**: 2025-12-02 11:30
+- **PR**: (none yet)
+-->
+
+(No active builders)

package/templates/config.json

@@ -0,0 +1,7 @@
+{
+  "shell": {
+    "architect": "claude",
+    "builder": "claude",
+    "shell": "bash"
+  }
+}