agentic-loop 1.0.0

package/dist/utils/reporters.js

@@ -0,0 +1,115 @@
+/**
+ * Output formatters for CLI results
+ */
+// ANSI color codes
+const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function severityColor(severity) {
+    switch (severity) {
+        case 'error':
+            return colors.red;
+        case 'warning':
+            return colors.yellow;
+        case 'info':
+            return colors.blue;
+    }
+}
+function severityIcon(severity) {
+    switch (severity) {
+        case 'error':
+            return '✖';
+        case 'warning':
+            return '⚠';
+        case 'info':
+            return 'ℹ';
+    }
+}
+/**
+ * Pretty format - colored terminal output
+ */
+export function formatPretty(summary) {
+    const lines = [];
+    // Header
+    lines.push('');
+    lines.push(`${colors.bold}vibe-check${colors.reset}`);
+    lines.push('');
+    // Results by file
+    for (const result of summary.results) {
+        if (result.issues.length === 0)
+            continue;
+        lines.push(`${colors.cyan}${result.filePath}${colors.reset}`);
+        for (const issue of result.issues) {
+            const color = severityColor(issue.severity);
+            const icon = severityIcon(issue.severity);
+            const location = issue.column
+                ? `${issue.line}:${issue.column}`
+                : `${issue.line}`;
+            lines.push(`  ${colors.gray}${location.padEnd(8)}${colors.reset}` +
+                `${color}${icon}${colors.reset} ` +
+                `${issue.message}  ${colors.dim}${issue.ruleId}${colors.reset}`);
+        }
+        lines.push('');
+    }
+    // Summary
+    const problems = [];
+    if (summary.errorCount > 0) {
+        problems.push(`${colors.red}${summary.errorCount} error${summary.errorCount === 1 ? '' : 's'}${colors.reset}`);
+    }
+    if (summary.warningCount > 0) {
+        problems.push(`${colors.yellow}${summary.warningCount} warning${summary.warningCount === 1 ? '' : 's'}${colors.reset}`);
+    }
+    if (summary.infoCount > 0) {
+        problems.push(`${colors.blue}${summary.infoCount} info${colors.reset}`);
+    }
+    if (problems.length > 0) {
+        lines.push(`${problems.join(', ')} in ${summary.filesWithIssues} file${summary.filesWithIssues === 1 ? '' : 's'}`);
+    }
+    else {
+        lines.push(`${colors.bold}✓${colors.reset} ${summary.filesChecked} file${summary.filesChecked === 1 ? '' : 's'} checked - no issues found`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * JSON format - machine-readable output
+ */
+export function formatJson(summary) {
+    return JSON.stringify(summary, null, 2);
+}
+/**
+ * Compact format - one line per issue
+ */
+export function formatCompact(summary) {
+    const lines = [];
+    for (const result of summary.results) {
+        for (const issue of result.issues) {
+            const location = issue.column
+                ? `${issue.line}:${issue.column}`
+                : `${issue.line}`;
+            lines.push(`${result.filePath}:${location}: ${issue.severity}: ${issue.message} [${issue.ruleId}]`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format results based on output format option
+ */
+export function formatResults(summary, format) {
+    switch (format) {
+        case 'pretty':
+            return formatPretty(summary);
+        case 'json':
+            return formatJson(summary);
+        case 'compact':
+            return formatCompact(summary);
+    }
+}
+//# sourceMappingURL=reporters.js.map

package/dist/utils/reporters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporters.js","sourceRoot":"","sources":["../../src/utils/reporters.ts"],"names":[],"mappings":"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"}

package/dist/utils/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared types for agentic-loop
+ */
+export type Severity = 'error' | 'warning' | 'info';
+export interface FileContext {
+    /** Absolute path to the file */
+    filePath: string;
+    /** File content as string */
+    content: string;
+    /** File extension without dot (e.g., 'ts', 'py') */
+    extension: string;
+}
+export interface HookResult {
+    /** 1-based line number */
+    line: number;
+    /** 0-based column number */
+    column?: number;
+    /** Human-readable message */
+    message: string;
+    /** Severity level */
+    severity: Severity;
+    /** Rule identifier (e.g., 'secrets/aws-key') */
+    ruleId: string;
+    /** Optional fix suggestion */
+    fix?: string;
+}
+export interface Hook {
+    /** Unique identifier (e.g., 'secrets', 'debug-statements') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this hook checks */
+    description: string;
+    /** Default severity level */
+    severity: Severity;
+    /** File extensions this hook applies to (without dots) */
+    fileTypes: string[];
+    /** Check function that returns issues found */
+    check: (context: FileContext) => HookResult[];
+}
+export interface CheckOptions {
+    /** Only run these hooks (by id) */
+    only?: string[];
+    /** Skip these hooks (by id) */
+    skip?: string[];
+    /** Minimum severity to fail on */
+    failOn?: Severity;
+    /** Output format */
+    format?: 'pretty' | 'json' | 'compact';
+    /** Auto-fix issues where possible */
+    fix?: boolean;
+}
+export interface CheckResult {
+    /** File path */
+    filePath: string;
+    /** All issues found in this file */
+    issues: HookResult[];
+}
+export interface SummaryResult {
+    /** Total files checked */
+    filesChecked: number;
+    /** Files with issues */
+    filesWithIssues: number;
+    /** Total issues by severity */
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+    /** All results */
+    results: CheckResult[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,IAAI;IACnB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+CAA+C;IAC/C,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,UAAU,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kCAAkC;IAClC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,oBAAoB;IACpB,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,qCAAqC;IACrC,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB"}

package/dist/utils/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for agentic-loop
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "agentic-loop",
+  "version": "1.0.0",
+  "description": "Autonomous AI coding loop - PRD-driven development with Claude Code",
+  "author": "Allie Jones <allie@allthrive.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/allthriveai/agentic-loop"
+  },
+  "homepage": "https://github.com/allthriveai/agentic-loop#readme",
+  "bugs": {
+    "url": "https://github.com/allthriveai/agentic-loop/issues"
+  },
+  "keywords": [
+    "ai",
+    "agentic",
+    "autonomous",
+    "claude",
+    "claude-code",
+    "coding-agent",
+    "prd",
+    "ralph",
+    "ai-development",
+    "code-generation"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agentic-loop": "./bin/agentic-loop.sh",
+    "vibe-check": "./bin/vibe-check.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "ralph",
+    "templates",
+    ".claude",
+    ".pre-commit-hooks.yaml"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "postinstall": "./bin/postinstall.sh",
+    "release": "npm version patch && git push && git push --tags && npm publish",
+    "release:minor": "npm version minor && git push && git push --tags && npm publish",
+    "release:major": "npm version major && git push && git push --tags && npm publish"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "tsx": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "playwright": "^1.40.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  }
+}

package/ralph/api.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# api.sh - API validation for backend stories
+
+# Parse an endpoint string into method and path
+# Usage: parse_endpoint "POST /api/users" "http://localhost:3000"
+# Sets: ENDPOINT_METHOD, ENDPOINT_PATH, ENDPOINT_URL
+parse_endpoint() {
+  local endpoint="$1"
+  local base_url="${2:-}"
+
+  # Defaults
+  ENDPOINT_METHOD="GET"
+  ENDPOINT_PATH="$endpoint"
+  ENDPOINT_URL=""
+
+  # Parse method if present (e.g., "POST /api/contact")
+  if [[ "$endpoint" =~ ^(GET|POST|PUT|PATCH|DELETE)[[:space:]]+(.*) ]]; then
+    ENDPOINT_METHOD="${BASH_REMATCH[1]}"
+    ENDPOINT_PATH="${BASH_REMATCH[2]}"
+  fi
+
+  # Build full URL
+  if [[ "$ENDPOINT_PATH" =~ ^https?:// ]]; then
+    ENDPOINT_URL="$ENDPOINT_PATH"
+  elif [[ -n "$base_url" ]]; then
+    ENDPOINT_URL="${base_url}${ENDPOINT_PATH}"
+  fi
+}
+
+# Check if endpoint is a WebSocket (can't be tested with HTTP)
+is_websocket_endpoint() {
+  local endpoint="$1"
+  [[ "$endpoint" =~ ^wss?:// ]] || [[ "$endpoint" =~ ^(GET|POST|PUT|PATCH|DELETE)[[:space:]]+wss?:// ]]
+}
+
+# Validate API endpoints for a backend story
+run_api_validation() {
+  local story="$1"
+
+  # Get API endpoints from story
+  local endpoints
+  endpoints=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .apiEndpoints[]?' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  if [[ -z "$endpoints" ]]; then
+    echo "  (no apiEndpoints defined, skipping API validation)"
+    return 0
+  fi
+
+  # Get base URL from config or use default
+  local base_url
+  base_url=$(get_config '.api.baseUrl' "http://localhost:3000")
+
+  local failed=0
+
+  echo "  Validating API endpoints..."
+
+  while IFS= read -r endpoint; do
+    [[ -z "$endpoint" ]] && continue
+
+    # Skip WebSocket endpoints - they can't be tested with HTTP curl
+    if is_websocket_endpoint "$endpoint"; then
+      echo "    Skipping WebSocket endpoint: $endpoint (use integration tests)"
+      continue
+    fi
+
+    # Parse endpoint into method, path, and full URL
+    parse_endpoint "$endpoint" "$base_url"
+
+    echo -n "    $ENDPOINT_METHOD $ENDPOINT_PATH... "
+
+    # Make the request
+    local response_code
+    response_code=$(curl -sf -m "$CURL_TIMEOUT_SECONDS" -o /dev/null -w "%{http_code}" -X "$ENDPOINT_METHOD" "$ENDPOINT_URL" 2>/dev/null)
+
+    if [[ "$response_code" =~ ^2[0-9][0-9]$ ]]; then
+      print_success "$response_code"
+    elif [[ "$response_code" == "000" ]]; then
+      print_error "connection failed"
+      failed=1
+    elif [[ "$response_code" == "422" || "$response_code" == "400" ]]; then
+      # 422/400 = endpoint exists but needs params - don't fail verification
+      print_warning "$response_code (needs params)"
+    elif [[ "$response_code" == "401" || "$response_code" == "403" ]]; then
+      # Auth required - endpoint exists
+      print_warning "$response_code (auth required)"
+    else
+      print_error "$response_code"
+      failed=1
+    fi
+  done <<< "$endpoints"
+
+  return $failed
+}
+
+# Run comprehensive API tests for a story
+run_api_tests() {
+  local story="$1"
+
+  # Get test steps that look like API calls
+  local test_steps
+  test_steps=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .testSteps[]?' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  if [[ -z "$test_steps" ]]; then
+    return 0
+  fi
+
+  local failed=0
+  local log_file
+  log_file=$(create_temp_file ".log") || return 1
+
+  echo "  Running API test steps..."
+
+  while IFS= read -r step; do
+    [[ -z "$step" ]] && continue
+
+    # Check if this looks like a curl command or API test
+    if [[ "$step" =~ ^curl ]]; then
+      echo -n "    $step... "
+
+      if safe_exec "$step" "$log_file"; then
+        print_success "passed"
+      else
+        print_error "failed"
+        echo ""
+        echo "    Response:"
+        tail -"$MAX_OUTPUT_PREVIEW_LINES" "$log_file" | sed 's/^/      /'
+        failed=1
+      fi
+    fi
+  done <<< "$test_steps"
+
+  rm -f "$log_file"
+  return $failed
+}
+
+# Validate error handling for API
+run_api_error_tests() {
+  local story="$1"
+
+  # Get error handling requirements
+  local error_handling
+  error_handling=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .errorHandling[]?' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  if [[ -z "$error_handling" ]]; then
+    return 0
+  fi
+
+  # Get base URL and endpoints
+  local base_url
+  base_url=$(get_config '.api.baseUrl' "http://localhost:3000")
+
+  local endpoints
+  endpoints=$(jq -r --arg id "$story" '.stories[] | select(.id==$id) | .apiEndpoints[0]?' "$RALPH_DIR/prd.json" 2>/dev/null)
+
+  if [[ -z "$endpoints" ]]; then
+    return 0
+  fi
+
+  # Skip WebSocket endpoints
+  if is_websocket_endpoint "$endpoints"; then
+    echo "  Skipping error tests for WebSocket endpoint"
+    return 0
+  fi
+
+  # Parse endpoint (default to POST for error tests)
+  parse_endpoint "$endpoints" "$base_url"
+  [[ "$ENDPOINT_METHOD" == "GET" ]] && ENDPOINT_METHOD="POST"
+
+  local failed=0
+
+  echo "  Testing API error handling..."
+
+  # Test common error cases
+  while IFS= read -r error_case; do
+    [[ -z "$error_case" ]] && continue
+
+    # Check for 400 tests (bad input)
+    if [[ "$error_case" =~ 400 ]]; then
+      echo -n "    Testing 400 (bad request)... "
+
+      local response_code
+      response_code=$(curl -sf -m "$CURL_TIMEOUT_SECONDS" -o /dev/null -w "%{http_code}" \
+        -X "$ENDPOINT_METHOD" \
+        -H "Content-Type: application/json" \
+        -d '{}' \
+        "$ENDPOINT_URL" 2>/dev/null)
+
+      if [[ "$response_code" == "400" ]]; then
+        print_success "correctly returns 400"
+      else
+        print_warning "got $response_code (expected 400)"
+        failed=1
+      fi
+    fi
+
+    # Check for 401 tests (unauthorized)
+    if [[ "$error_case" =~ 401 ]]; then
+      echo -n "    Testing 401 (unauthorized)... "
+
+      local response_code
+      response_code=$(curl -sf -m "$CURL_TIMEOUT_SECONDS" -o /dev/null -w "%{http_code}" \
+        -X "$ENDPOINT_METHOD" \
+        "$ENDPOINT_URL" 2>/dev/null)
+
+      if [[ "$response_code" == "401" ]]; then
+        print_success "correctly returns 401"
+      else
+        print_warning "got $response_code (expected 401)"
+        failed=1
+      fi
+    fi
+  done <<< "$error_handling"
+
+  return $failed
+}