thrivekit 2.0.0

package/.claude/settings.json

@@ -0,0 +1,75 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/protect-prd.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/warn-debug.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/warn-secrets.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/warn-urls.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/warn-empty-catch.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/log-tools.sh",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/inject-context.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/allierays/Sites/vibe-and-thrive/ralph/hooks/save-learnings.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:x.com)",
+      "WebSearch",
+      "WebFetch(domain:creatoreconomy.so)",
+      "Bash(cat:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.pre-commit-hooks.yaml

@@ -0,0 +1,102 @@
+# thrivekit pre-commit hooks
+# All hooks use language: node for consistency
+
+# Database backup (non-blocking - creates backup before commit)
+- id: backup-db
+  name: Backup databases
+  entry: bash -c 'npx --yes ralph backup --quiet 2>/dev/null || true'
+  language: system
+  pass_filenames: false
+  always_run: true
+  stages: [pre-commit]
+
+# Build check (blocking - ensures code compiles)
+# Checks common locations for build script: root, frontend/, client/, apps/web/
+- id: build
+  name: Build check
+  entry: bash -c 'if grep -q "\"build\":" package.json 2>/dev/null; then npm run build; elif grep -q "\"build\":" frontend/package.json 2>/dev/null; then cd frontend && npm run build; elif grep -q "\"build\":" client/package.json 2>/dev/null; then cd client && npm run build; elif grep -q "\"build\":" apps/web/package.json 2>/dev/null; then cd apps/web && npm run build; else echo "No build script found, skipping"; fi'
+  language: system
+  pass_filenames: false
+  always_run: true
+
+# Security checks (blocking - these will fail the commit)
+- id: check-env-files
+  name: Block .env files from commit
+  entry: bash -c 'echo "ERROR: .env files should not be committed. Add to .gitignore." && exit 1'
+  language: system
+  files: '\.env($|\.)'
+  pass_filenames: false
+
+- id: check-secrets
+  name: Check for hardcoded secrets
+  entry: npx vibe-check --only secrets --fail-on error
+  language: node
+  types_or: [python, javascript, ts, json, yaml]
+  pass_filenames: true
+
+- id: check-hardcoded-urls
+  name: Check for hardcoded URLs
+  entry: npx vibe-check --only urls --fail-on error
+  language: node
+  types_or: [python, javascript, ts]
+  pass_filenames: true
+
+- id: check-unsafe-html
+  name: Check for unsafe HTML manipulation
+  entry: npx vibe-check --only unsafe-html --fail-on error
+  language: node
+  types_or: [javascript, ts]
+  pass_filenames: true
+
+# Code quality checks (warnings - informational)
+- id: check-debug
+  name: Check for debug statements
+  entry: npx vibe-check --only debug --fail-on error
+  language: node
+  types_or: [python, javascript, ts]
+  pass_filenames: true
+
+- id: check-empty-catch
+  name: Check for empty catch blocks
+  entry: npx vibe-check --only empty-catch --fail-on warning
+  language: node
+  types_or: [python, javascript, ts]
+  pass_filenames: true
+
+- id: check-any-types
+  name: Check for any types in TypeScript
+  entry: npx vibe-check --only any-types --fail-on warning
+  language: node
+  types: [ts]
+  pass_filenames: true
+
+- id: check-snake-case
+  name: Check for snake_case in TypeScript
+  entry: npx vibe-check --only snake-case --fail-on warning
+  language: node
+  types: [ts]
+  pass_filenames: true
+
+# Comprehensive check (all hooks)
+- id: vibe-check
+  name: Vibe Check (all)
+  entry: npx vibe-check
+  language: node
+  types_or: [python, javascript, ts, json, yaml]
+  pass_filenames: true
+
+# Quick security-only check
+- id: vibe-check-security
+  name: Vibe Check (security only)
+  entry: npx vibe-check --only secrets,urls,unsafe-html --fail-on error
+  language: node
+  types_or: [python, javascript, ts, json, yaml]
+  pass_filenames: true
+
+# Quality-only check (non-blocking)
+- id: vibe-check-quality
+  name: Vibe Check (quality only)
+  entry: npx vibe-check --skip secrets,urls,unsafe-html --fail-on none
+  language: node
+  types_or: [python, javascript, ts]
+  pass_filenames: true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AllThrive AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# ThriveKit
+
+**Tools to thrive with agentic coding.**
+
+A toolkit for implementing [RALPH](https://ghuntley.com/ralph/) with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that helps you go from idea to shipped code.
+
+> You focus on what matters: your ideas. Brainstorm with `/idea`, then let Ralph handle the rest - coding, testing, and committing in an iterative loop until everything passes.
+
+### This repo includes:
+#### Customize
+- **`/my-dna`** - Add your own voice and values to your claude.md (This helps you personalize your experience and output)
+- **`/styleguide`** - Generate a UI component reference for consistent design (Stop AI from generating everything in purple add your unique style in an html and then reference it)
+
+#### Autonomous Code Loops with RALPH principles
+Run this in the terminal not in a claude cli session. It will use your claude subscription not an API key.
+- **`npx thrivekit run`** - RALPH Autonomous loop: Brainstorm ideas → turn ideas into atomic prds → implement → verify → commit → repeat
+
+#### Guardrails
+- **`/vibe-check`** - manually run the same automated tests and guardrail checks at any time
+- **`/review`** - manually run the same automated Security-focused code review with OWASP checks
+- **Pre-commit hooks** - Automatically block secrets, hardcoded URLs, and security issues with precommit hooks from entering into your git repo. Catch and fix issues before your CI/CD does
+- **Claude Code hooks** - Real-time warnings while coding (debug statements, secrets, hardcoded URLs)
+
+---
+See More for on how the [RALPH loop](docs/RALPH.md) works in this repo
+
+---
+
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated
+- `jq` (for config management): `brew install jq` or `apt install jq`
+- Optional: [Playwright](https://playwright.dev/) for browser verification (installed automatically by `/tour`)
+
+
+## Step 0: Install
+
+```bash
+cd [your-project]
+npm install thrivekit
+npx thrivekit setup
+```
+
+This sets up:
+- Slash commands (`/idea`, `/review`, etc.)
+- Pre-commit hooks (secrets, URLs, debug statements)
+- Claude Code hooks (real-time warnings)
+- Ralph configuration files
+
+> **Note:** Claude Code hooks require `jq`. On macOS with Homebrew, it's installed automatically. On Linux, if you see a warning, run `sudo apt install jq` (or your package manager) then `npx thrivekit setup`.
+
+## Step 1: Start claude (--dangerously-skip-permissions is optional)
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+## Step 1b: Optional run tour and customizations
+Inside of a claude session run
+```
+ /tour
+```
+1. The tour auto-detects your project settings and walks you through the workflow.
+2. You can set up your own styleguide for all your frontend work to reference. I highly recommend you do this.
+3. run /my-dna to add your own writing style, core values, and things you want represented in your application so that your app represents you and what you want.
+
+### Step 2: Brainstorm Your Idea
+
+```
+/idea [describe your next feature]
+```
+
+Claude asks clarifying questions, explores your codebase, then generates:
+- `docs/ideas/your-feature.md` - The documented idea
+- `.ralph/prd.json` - Atomic stories for Ralph
+
+Review and approve when prompted.
+
+> **Note:** If Claude skips writing to `docs/ideas/`, tell it: "Please write the idea to docs/ideas/ and generate the PRD as the /idea command specifies"
+
+### Step 3: Execute with Ralph
+
+Type `/exit` or open a new terminal, then run:
+
+```bash
+npx thrivekit run
+```
+
+Ralph loops through stories one at a time, writes tests, verifies, and commits.
+
+> **Pro tip:** Use two terminals - plan with Claude in one, run Ralph in another.
+
+## Ralph Details
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        RALPH LOOP                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Read prd.json → find next story where passes=false      │
+│  2. Build prompt (story + context + failures + signs)       │
+│  3. Spawn Claude with prompt                                │
+│  4. Run verification (build, tests, browser, code review)   │
+│  5. Pass? → commit, next story                              │
+│     Fail? → save error, retry with failure context          │
+│  6. Repeat until all stories pass                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [How Ralph Works](docs/RALPH.md) | Architecture, config, troubleshooting |
+| [Cheatsheet](docs/CHEATSHEET.md) | All commands, quick reference |
+| [Workflow Guide](docs/WORKFLOW.md) | End-to-end development process |
+| [Hooks Reference](docs/HOOKS.md) | Pre-commit and Claude Code hooks |
+| [Bad Patterns](docs/BAD-PATTERNS.md) | AI code issues to avoid |
+| [Prompting Guide](docs/PROMPTING-GUIDE.md) | Writing effective PROMPT.md |
+| [TDD Guide](docs/TDD.md) | Test-driven development with Ralph |
+| [Styleguide](docs/STYLEGUIDE.md) | Creating UI component references |
+| [Contributing](docs/CONTRIBUTING.md) | How to contribute |
+
+## Project Structure
+
+```
+thrivekit/
+├── .claude/commands/       # Slash commands (/idea, /review, etc.)
+├── ralph/                  # Autonomous loop (Bash)
+│   ├── hooks/              # Claude Code hooks (real-time warnings)
+│   ├── browser-verify/     # Playwright verification
+│   └── setup/              # Setup wizards (/tour)
+├── src/                    # Pre-commit checks (TypeScript)
+│   └── checks/             # Check implementations (secrets, urls, etc.)
+├── templates/              # Files for user projects
+│   ├── PROMPT.md           # Base prompt for Ralph sessions
+│   ├── config/             # Project type configs (node, python)
+│   ├── optional/           # Extra configs (eslint, vscode, etc.)
+│   └── examples/           # Example CLAUDE.md files by stack
+├── docs/                   # Documentation
+└── bin/                    # CLI entry points (thrivekit, vibe-check)
+```
+
+### Three Layers of Quality Checks
+
+| Layer | When | What |
+|-------|------|------|
+| **Slash commands** | In Claude Code CLI | `/vibe-check`, `/review` - on-demand checks |
+| **Claude Code hooks** | While Claude writes code | Real-time warnings (debug statements, secrets) |
+| **Pre-commit hooks** | At `git commit` | Blocks secrets, URLs, debug statements |
+
+---
+
+## Troubleshooting
+
+### "SessionStart: startup hook error"
+
+This means Claude Code hooks are configured but the hook scripts can't be found. Fix with:
+
+```bash
+# Reinstall project hooks
+npx thrivekit setup
+```
+
+### Hooks not working after moving project
+
+Claude Code hooks use absolute paths. After moving a project or cloning on a new machine, reinstall hooks:
+
+```bash
+npx thrivekit setup
+```
+
+### Team members getting hook errors
+
+`.claude/settings.json` contains machine-specific paths and should not be committed to git. The setup script automatically adds it to `.gitignore`. Each team member's hooks are configured when they run `npx thrivekit setup`.
+
+If `.claude/settings.json` was accidentally committed:
+```bash
+git rm --cached .claude/settings.json
+echo ".claude/settings.json" >> .gitignore
+git commit -m "Remove machine-specific settings from git"
+```
+
+### jq not installed
+
+Claude Code hooks require `jq` for JSON manipulation. On macOS with Homebrew, the setup installs it automatically. On Linux:
+
+```bash
+# Ubuntu/Debian
+sudo apt install jq
+
+# Fedora/RHEL
+sudo dnf install jq
+
+# Then run setup
+npx thrivekit setup
+```
+
+---
+
+## License
+
+MIT - see [LICENSE](LICENSE)
+
+---
+
+Built by [AllThrive AI](https://allthrive.ai)

package/bin/postinstall.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Postinstall: just show next step message
+
+set -euo pipefail
+
+# Skip in CI environments
+if [[ "${CI:-}" == "true" ]] || [[ "${GITHUB_ACTIONS:-}" == "true" ]]; then
+  exit 0
+fi
+
+# Get the package directory (where thrivekit is installed)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PKG_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Get the project root (go up from node_modules/thrivekit)
+PROJECT_ROOT="$(cd "$PKG_ROOT/../.." && pwd)"
+
+# Don't run in the thrivekit package itself
+if [[ -f "$PROJECT_ROOT/package.json" ]] && grep -q '"name": "thrivekit"' "$PROJECT_ROOT/package.json" 2>/dev/null; then
+  exit 0
+fi
+
+# Just show the next step
+echo "" >&2
+echo "  ✨ thrivekit installed!" >&2
+echo "" >&2
+echo "  Run setup:" >&2
+echo "    npx thrivekit setup" >&2
+echo "" >&2

package/bin/ralph.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# ralph.sh - Autonomous AI Development Loop
+#
+# A CLI tool that orchestrates Claude CLI for autonomous development loops.
+# Part of thrivekit: https://github.com/allthriveai/thrivekit
+
+set -euo pipefail
+
+# Handle Ctrl+C - kill all child processes
+trap 'echo ""; echo "Interrupted. Stopping..."; kill 0 2>/dev/null; exit 130' INT TERM
+
+# Get the directory where ralph.sh is installed (works even via symlink)
+get_script_dir() {
+  local source="${BASH_SOURCE[0]}"
+  while [[ -L "$source" ]]; do
+    local dir
+    dir=$(cd -P "$(dirname "$source")" && pwd)
+    source=$(readlink "$source")
+    [[ "$source" != /* ]] && source="$dir/$source"
+  done
+  cd -P "$(dirname "$source")" && pwd
+}
+
+SCRIPT_DIR="$(get_script_dir)"
+RALPH_LIB="$SCRIPT_DIR/../ralph"
+RALPH_TEMPLATES="$SCRIPT_DIR/../templates"
+
+# Project-local directories (can be overridden by environment)
+RALPH_DIR="${RALPH_DIR:-.ralph}"
+PROMPT_FILE="${PROMPT_FILE:-PROMPT.md}"
+
+# Export for use in sourced files
+export RALPH_DIR PROMPT_FILE RALPH_LIB RALPH_TEMPLATES
+
+# Ensure minimal setup exists (in case postinstall was skipped or global install)
+if [[ ! -d ".ralph" ]]; then
+  mkdir -p ".ralph/archive" ".ralph/screenshots"
+fi
+# Always ensure config.json exists and run auto-detection if newly created
+if [[ ! -f ".ralph/config.json" ]]; then
+  echo '{}' > ".ralph/config.json"
+  # Run auto-detection (function is in init.sh, sourced below)
+  _ralph_needs_autoconfig=true
+fi
+[[ ! -f ".ralph/signs.json" ]] && echo '{"signs": []}' > ".ralph/signs.json"
+if [[ ! -f "PROMPT.md" ]] && [[ -f "$RALPH_TEMPLATES/PROMPT.md" ]]; then
+  cp "$RALPH_TEMPLATES/PROMPT.md" "PROMPT.md"
+fi
+
+# Source function libraries
+source "$RALPH_LIB/utils.sh"
+source "$RALPH_LIB/init.sh"
+source "$RALPH_LIB/setup.sh"
+source "$RALPH_LIB/loop.sh"
+source "$RALPH_LIB/verify.sh"
+source "$RALPH_LIB/prd.sh"
+source "$RALPH_LIB/signs.sh"
+
+# Run auto-config if config.json was just created
+if [[ "${_ralph_needs_autoconfig:-}" == "true" ]]; then
+  echo "Auto-detecting project configuration..." >&2
+  auto_configure_project
+  unset _ralph_needs_autoconfig
+fi
+
+# Main entry point
+main() {
+  local cmd="${1:-help}"
+  shift || true
+
+  case "$cmd" in
+    setup)
+      ralph_setup "$@"
+      ;;
+    init)
+      ralph_init "$@"
+      ;;
+    prd)
+      ralph_prd "$@"
+      ;;
+    run)
+      # Clear any previous stop signal
+      rm -f "$RALPH_DIR/.stop"
+      run_loop "$@"
+      ;;
+    stop)
+      # Signal the loop to stop after current story
+      mkdir -p "$RALPH_DIR"
+      touch "$RALPH_DIR/.stop"
+      echo "Stop signal sent. Ralph will stop after current story completes."
+      echo "(Use Ctrl+C to force stop immediately)"
+      ;;
+    status)
+      ralph_status "$@"
+      ;;
+    check)
+      ralph_check "$@"
+      ;;
+    verify)
+      if [[ $# -lt 1 ]]; then
+        print_error "Usage: ralph verify <story-id>"
+        exit 1
+      fi
+      run_verification "$1"
+      ;;
+    sign)
+      ralph_sign "$@"
+      ;;
+    signs)
+      ralph_signs "$@"
+      ;;
+    unsign)
+      ralph_unsign "$@"
+      ;;
+    notify)
+      ralph_notify "$@"
+      ;;
+    backup)
+      source "$RALPH_LIB/backup.sh"
+      ralph_backup "$@"
+      ;;
+    restore)
+      source "$RALPH_LIB/backup.sh"
+      ralph_restore "$@"
+      ;;
+    backups)
+      source "$RALPH_LIB/backup.sh"
+      ralph_list_backups
+      ;;
+    hooks)
+      bash "$RALPH_LIB/hooks/install.sh" "$@"
+      ;;
+    progress)
+      if [[ -f "$RALPH_DIR/progress.txt" ]]; then
+        tail -50 "$RALPH_DIR/progress.txt"
+      else
+        echo "No progress log found. Run 'ralph init' first."
+      fi
+      ;;
+    config)
+      if [[ ! -f "$RALPH_DIR/config.json" ]]; then
+        print_error "Ralph not initialized. Run 'ralph init' first."
+        exit 1
+      fi
+      echo "Auto-detecting project configuration..."
+      auto_configure_project
+      echo ""
+      echo "Current config:"
+      jq '.' "$RALPH_DIR/config.json"
+      ;;
+    help|-h|--help)
+      ralph_help
+      ;;
+    version|-v|--version)
+      # Read version from package.json
+      local version
+      version=$(jq -r '.version // "unknown"' "$SCRIPT_DIR/../package.json" 2>/dev/null || echo "unknown")
+      echo "ralph $version (thrivekit)"
+      ;;
+    *)
+      print_error "Unknown command: $cmd"
+      echo ""
+      ralph_help
+      exit 1
+      ;;
+  esac
+}
+
+# Run main
+main "$@"

package/bin/thrivekit.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# thrivekit - Tools to thrive with agentic coding
+#
+# Main CLI - wraps ralph.sh for the autonomous dev loop.
+
+set -euo pipefail
+
+# Get the directory where this script is installed (handles symlinks)
+get_script_dir() {
+  local source="${BASH_SOURCE[0]}"
+  while [[ -L "$source" ]]; do
+    local dir
+    dir=$(cd -P "$(dirname "$source")" && pwd)
+    source=$(readlink "$source")
+    [[ "$source" != /* ]] && source="$dir/$source"
+  done
+  cd -P "$(dirname "$source")" && pwd
+}
+
+SCRIPT_DIR="$(get_script_dir)"
+
+# Pass through to ralph.sh
+exec "$SCRIPT_DIR/ralph.sh" "$@"

package/bin/vibe-check.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+/**
+ * vibe-check CLI
+ *
+ * Usage:
+ *   npx vibe-check .
+ *   npx vibe-check src/app.ts
+ *   npx vibe-check . --only secrets,urls
+ *   npx vibe-check . --skip any-types
+ *   npx vibe-check . --format json
+ */
+
+import { main } from '../dist/cli.js';
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error('Fatal error:', error.message);
+  process.exit(2);
+});

package/dist/checks/check-any-types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Check for 'any' type usage in TypeScript
+ */
+import type { Hook } from '../utils/types.js';
+export declare const checkAnyTypes: Hook;
+//# sourceMappingURL=check-any-types.d.ts.map

package/dist/checks/check-any-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-any-types.d.ts","sourceRoot":"","sources":["../../src/checks/check-any-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAA2B,MAAM,mBAAmB,CAAC;AAEvE,eAAO,MAAM,aAAa,EAAE,IA8E3B,CAAC"}