safeword 0.2.2 → 0.2.4

package/framework/README.md

@@ -0,0 +1,131 @@
+# SAFEWORD Framework Setup Guide
+
+A single place to install and understand the SAFEWORD framework in your project.
+
+## What you get
+
+- `.safeword/SAFEWORD.md` and guides for workflows, TDD, and best practices
+- `.safeword/templates/` for user stories, test definitions, and design docs
+- `.safeword/planning/` and `.safeword/tickets/` structure
+- `.claude/` hooks and settings for:
+  - Auto-linting (PostToolUse)
+  - Quality review (Stop hook)
+  - Session start version message
+
+All scripts are idempotent and safe to re-run.
+
+## Requirements
+
+- bash
+- jq (required for hook settings merging)
+  - macOS: `brew install jq`
+  - Ubuntu/Debian: `sudo apt-get install jq`
+- Node.js + npm (only for auto-linting setup)
+
+## Recommended setup (2 commands)
+
+```bash
+cd /path/to/your/project
+
+# 1) Install SAFEWORD structure and docs (planning, guides, templates)
+bash ./framework/scripts/setup-safeword.sh
+
+# 2) Install hooks (auto-linting + quality review)
+bash ./framework/scripts/setup-claude.sh
+```
+
+Options for step 2:
+
+- Skip linting (quality review only): `bash ./framework/scripts/setup-claude.sh --skip-linting`
+- Skip quality review: `bash ./framework/scripts/setup-claude.sh --skip-quality`
+
+## What each script does
+
+### setup-safeword.sh (Project structure + docs)
+
+- Copies `framework/SAFEWORD.md` to `.safeword/SAFEWORD.md`
+- Copies `framework/guides/` and `framework/templates/` into `.safeword/`
+- Creates `.safeword/planning/` and `.safeword/tickets/` (with archives)
+- Creates or updates `AGENTS.md` with an always-read trigger for `@./.safeword/SAFEWORD.md`
+- Ensures `.gitignore` includes `.safeword` planning folders and Claude local files
+- Creates `.claude/settings.json` if missing
+
+Note: Hook binaries are created by the scripts below. Running `setup-claude.sh` installs them.
+
+### setup-claude.sh (Hooks orchestrator)
+
+- Auto-detects project type (react, astro, electron, typescript, minimal) unless `--linting-mode` is provided
+- Runs linting setup unless `--skip-linting`
+- Runs quality review setup unless `--skip-quality`
+- Seeds `.claude/skills/` and `.claude/mcp/` from `framework/skills` and `framework/mcp` if present
+- Adds a sample Arcade MCP config and environment example if missing
+- Ensures `CLAUDE.md` references `.safeword/SAFEWORD.md`
+
+### setup-linting.sh (Auto-linting)
+
+- **Auto-detects** project type from package.json and tsconfig.json
+- **Two-file architecture** for safe updates:
+  - `.safeword/eslint/eslint-base.mjs` - Auto-generated every run
+  - `eslint.config.mjs` - User-owned, never overwritten (customize freely)
+- All projects include:
+  - `eslint-plugin-boundaries` (architectural boundary enforcement)
+  - `eslint-plugin-sonarjs` (code smell detection)
+  - `@microsoft/eslint-plugin-sdl` (security rules)
+- Creates:
+  - `.claude/hooks/run-linters.sh` (shared logic)
+  - `.claude/hooks/auto-lint.sh` (PostToolUse wrapper)
+  - `.claude/commands/lint.md`
+  - `.prettierrc` and `.prettierignore`
+
+The base config is regenerated every run, so after adding/removing frameworks:
+
+```bash
+bash setup-linting.sh   # Re-detects and updates
+```
+
+Options: `--no-typescript`, `--no-react`, `--no-astro` - Override auto-detection
+
+### setup-quality.sh (Quality review)
+
+- Creates:
+  - `.claude/hooks/auto-quality-review.sh` (Stop hook that inspects transcript)
+  - `.claude/hooks/run-quality-review.sh` (prompt)
+  - `.claude/commands/quality-review.md`
+  - `.claude/settings.json` merged with Stop + SessionStart hooks
+
+Behavior:
+
+- Triggers only when changes are proposed/made (JSON blob present)
+- Skips when the assistant asked a question (waits for your answer)
+- Works in monorepos by searching upward for `SAFEWORD.md` or `CLAUDE.md`
+- Configurable via `.auto-quality-review.config`
+
+## Outputs checklist
+
+After recommended setup:
+
+- `.safeword/SAFEWORD.md` and `.safeword/guides/`
+- `.claude/hooks/auto-lint.sh`, `run-linters.sh`, `auto-quality-review.sh`, `run-quality-review.sh`, `version-check.sh`
+- `.claude/commands/lint.md`, `quality-review.md`
+- `.claude/settings.json` with:
+  - `PostToolUse` → `auto-lint.sh`
+  - `Stop` → `auto-quality-review.sh`
+  - `SessionStart` → `version-check.sh`
+
+## Updating
+
+Re-run the same scripts. Generated files include version headers like:
+
+```bash
+# Generated by setup-linting.sh v1.0.0
+# To upgrade: Re-run this script in this project
+```
+
+## Troubleshooting
+
+- jq missing: Install jq (see Requirements). Scripts will error clearly when required.
+- Node missing: Install Node.js + npm to use auto-linting.
+- Hooks not triggering:
+  - Check `.claude/settings.json`
+  - Ensure `SAFEWORD.md` or `CLAUDE.md` exists in project or parent
+  - See `.safeword/SAFEWORD.md` (methodology) and this guide (setup/troubleshooting)

package/framework/mcp/README.md

@@ -0,0 +1,96 @@
+# MCP Server Configurations
+
+Sample configurations for Model Context Protocol (MCP) servers.
+
+## Available Servers
+
+| Server         | Package                 | API Key         | Purpose                        |
+| -------------- | ----------------------- | --------------- | ------------------------------ |
+| **Context7**   | `@upstash/context7-mcp` | Required (free) | Library docs lookups           |
+| **Playwright** | `@playwright/mcp`       | None            | Browser automation (Microsoft) |
+| **Arcade**     | Arcade MCP Gateway      | Required        | Tool gateway                   |
+
+## API Keys
+
+| Server   | Get Key                                                              |
+| -------- | -------------------------------------------------------------------- |
+| Context7 | [context7.com/dashboard](https://context7.com/dashboard) (free tier) |
+| Arcade   | [arcade.dev](https://arcade.dev)                                     |
+
+## Setup
+
+### 1. Set Environment Variables
+
+Add to `~/.zshrc` (or `~/.bashrc`):
+
+```bash
+export CONTEXT7_API_KEY="your-key-here"
+export ARCADE_API_KEY="your-key-here"
+```
+
+Then reload: `source ~/.zshrc`
+
+### 2. Add MCP Config
+
+**Claude Desktop** — Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+**Cursor** — Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+MCP servers inherit environment variables from your shell automatically.
+
+## Playwright Options
+
+| Arg                                   | Description             |
+| ------------------------------------- | ----------------------- |
+| `--browser chromium\|firefox\|webkit` | Browser type            |
+| `--headless`                          | Run headless            |
+| `--user-data-dir <path>`              | Persist browser profile |
+
+Example:
+
+```json
+{
+  "command": "npx",
+  "args": ["@playwright/mcp@latest", "--browser", "chromium", "--headless"]
+}
+```
+
+## Context7 Usage
+
+Once configured, use in prompts:
+
+```
+use context7 to look up the latest React 19 useOptimistic hook documentation
+```
+
+Context7 fetches current docs directly from source repositories.

package/framework/mcp/arcade.sample.json

@@ -0,0 +1,8 @@
+{
+  "name": "arcade",
+  "transport": "http",
+  "url": "https://mcp.arcade.dev",
+  "headers": {
+    "Authorization": "Bearer YOUR_ARCADE_API_KEY"
+  }
+}

package/framework/mcp/context7.sample.json

@@ -0,0 +1,6 @@
+{
+  "name": "context7",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@upstash/context7-mcp@latest"]
+}

package/framework/mcp/playwright.sample.json

@@ -0,0 +1,6 @@
+{
+  "name": "playwright",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["@playwright/mcp@latest"]
+}

package/framework/scripts/arch-review.sh

@@ -0,0 +1,235 @@
+#!/bin/bash
+################################################################################
+# Architecture Review Script
+#
+# Sends changed files to Claude Haiku API for semantic architecture review.
+# Returns JSON verdict: clean | minor | refactor_needed
+#
+# Usage:
+#   arch-review.sh file1.ts file2.ts    # Review specific files
+#   arch-review.sh --staged             # Review git staged files
+#
+# Environment variables:
+#   ANTHROPIC_API_KEY - Required. Your Anthropic API key.
+#   ARCH_REVIEW_MODEL - Optional. Model to use (default: claude-3-haiku-20240307)
+#
+# Exit codes:
+#   0 - Clean or minor issues (commit allowed)
+#   1 - Refactor needed (commit blocked)
+#   2 - Error (missing API key, network issue, etc.)
+################################################################################
+
+set -e
+
+VERSION="v1.0.0"
+
+# Configuration
+MODEL="${ARCH_REVIEW_MODEL:-claude-3-haiku-20240307}"
+MAX_TOKENS=1024
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Check for required tools
+if ! command -v curl &> /dev/null; then
+  echo "ERROR: curl is required but not installed." >&2
+  exit 2
+fi
+
+if ! command -v jq &> /dev/null; then
+  echo "ERROR: jq is required but not installed." >&2
+  exit 2
+fi
+
+# Check for API key
+if [ -z "$ANTHROPIC_API_KEY" ]; then
+  echo "ERROR: ANTHROPIC_API_KEY environment variable is not set." >&2
+  echo "Set it with: export ANTHROPIC_API_KEY='your-api-key'" >&2
+  exit 2
+fi
+
+# Parse arguments
+FILES=()
+STAGED_MODE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --staged)
+      STAGED_MODE=true
+      ;;
+    --help|-h)
+      echo "Architecture Review Script $VERSION"
+      echo ""
+      echo "Usage:"
+      echo "  arch-review.sh file1.ts file2.ts    # Review specific files"
+      echo "  arch-review.sh --staged             # Review git staged files"
+      echo ""
+      echo "Environment variables:"
+      echo "  ANTHROPIC_API_KEY - Required. Your Anthropic API key."
+      echo "  ARCH_REVIEW_MODEL - Optional. Model (default: claude-3-haiku-20240307)"
+      exit 0
+      ;;
+    *)
+      FILES+=("$arg")
+      ;;
+  esac
+done
+
+# Get staged files if --staged mode
+if [ "$STAGED_MODE" = true ]; then
+  # Get staged files (only .js, .ts, .tsx, .jsx)
+  while IFS= read -r file; do
+    if [[ "$file" =~ \.(js|ts|tsx|jsx)$ ]]; then
+      FILES+=("$file")
+    fi
+  done < <(git diff --cached --name-only --diff-filter=ACM 2>/dev/null || true)
+fi
+
+# Check if we have files to review
+if [ ${#FILES[@]} -eq 0 ]; then
+  echo "No files to review."
+  exit 0
+fi
+
+echo "Reviewing ${#FILES[@]} file(s) for architectural issues..."
+
+# Find ARCHITECTURE.md (search upward from current directory)
+ARCH_FILE=""
+SEARCH_DIR="$PWD"
+while [ "$SEARCH_DIR" != "/" ]; do
+  if [ -f "$SEARCH_DIR/ARCHITECTURE.md" ]; then
+    ARCH_FILE="$SEARCH_DIR/ARCHITECTURE.md"
+    break
+  fi
+  SEARCH_DIR=$(dirname "$SEARCH_DIR")
+done
+
+# Build context for the prompt
+CONTEXT=""
+
+# Add ARCHITECTURE.md if found
+if [ -n "$ARCH_FILE" ]; then
+  ARCH_CONTENT=$(cat "$ARCH_FILE" | head -c 8000)  # Limit to ~8KB
+  CONTEXT+="## ARCHITECTURE.md\n\n$ARCH_CONTENT\n\n"
+fi
+
+# Add file contents
+CONTEXT+="## Changed Files\n\n"
+for file in "${FILES[@]}"; do
+  if [ -f "$file" ]; then
+    FILE_CONTENT=$(cat "$file" | head -c 4000)  # Limit each file to ~4KB
+    CONTEXT+="### $file\n\n\`\`\`\n$FILE_CONTENT\n\`\`\`\n\n"
+  fi
+done
+
+# Read the arch-review prompt
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROMPT_FILE="$SCRIPT_DIR/../prompts/arch-review.md"
+
+# Fall back to .safeword location if framework location doesn't exist
+if [ ! -f "$PROMPT_FILE" ]; then
+  # Try .safeword/prompts/ location (when installed in project)
+  PROJECT_ROOT="$PWD"
+  while [ "$PROJECT_ROOT" != "/" ]; do
+    if [ -f "$PROJECT_ROOT/.safeword/prompts/arch-review.md" ]; then
+      PROMPT_FILE="$PROJECT_ROOT/.safeword/prompts/arch-review.md"
+      break
+    fi
+    PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+  done
+fi
+
+if [ ! -f "$PROMPT_FILE" ]; then
+  echo "ERROR: arch-review.md prompt not found." >&2
+  exit 2
+fi
+
+PROMPT=$(cat "$PROMPT_FILE")
+
+# Combine prompt with context
+FULL_PROMPT="$PROMPT\n\n---\n\n$CONTEXT"
+
+# Escape for JSON
+FULL_PROMPT_ESCAPED=$(echo -e "$FULL_PROMPT" | jq -Rs .)
+
+# Make API request
+RESPONSE=$(curl -s -X POST "https://api.anthropic.com/v1/messages" \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -d "{
+    \"model\": \"$MODEL\",
+    \"max_tokens\": $MAX_TOKENS,
+    \"messages\": [
+      {
+        \"role\": \"user\",
+        \"content\": $FULL_PROMPT_ESCAPED
+      }
+    ]
+  }" 2>&1)
+
+# Check for API errors
+if echo "$RESPONSE" | jq -e '.error' > /dev/null 2>&1; then
+  ERROR_MSG=$(echo "$RESPONSE" | jq -r '.error.message // "Unknown error"')
+  echo "ERROR: API request failed: $ERROR_MSG" >&2
+  exit 2
+fi
+
+# Extract the text response
+TEXT_RESPONSE=$(echo "$RESPONSE" | jq -r '.content[0].text // empty')
+
+if [ -z "$TEXT_RESPONSE" ]; then
+  echo "ERROR: Empty response from API" >&2
+  exit 2
+fi
+
+# Try to extract JSON from the response
+JSON_RESULT=$(echo "$TEXT_RESPONSE" | grep -oP '\{[^{}]*"verdict"[^{}]*\}' | head -1 || true)
+
+# If no simple JSON found, try to extract from code block
+if [ -z "$JSON_RESULT" ]; then
+  JSON_RESULT=$(echo "$TEXT_RESPONSE" | sed -n '/```json/,/```/p' | grep -v '```' | tr -d '\n' || true)
+fi
+
+# Parse verdict
+VERDICT="clean"
+if [ -n "$JSON_RESULT" ]; then
+  VERDICT=$(echo "$JSON_RESULT" | jq -r '.verdict // "clean"' 2>/dev/null || echo "clean")
+fi
+
+# Output results
+echo ""
+echo "=== Architecture Review Results ==="
+echo ""
+
+# Show full response for debugging/context
+echo "$TEXT_RESPONSE"
+echo ""
+
+# Show verdict with color
+case "$VERDICT" in
+  clean)
+    echo -e "${GREEN}✓ Verdict: CLEAN${NC}"
+    echo "No architectural issues found."
+    exit 0
+    ;;
+  minor)
+    echo -e "${YELLOW}⚠ Verdict: MINOR${NC}"
+    echo "Minor issues noted. Commit allowed."
+    exit 0
+    ;;
+  refactor_needed)
+    echo -e "${RED}✗ Verdict: REFACTOR NEEDED${NC}"
+    echo "Significant architectural issues found. Please address before committing."
+    exit 1
+    ;;
+  *)
+    echo -e "${YELLOW}? Verdict: UNKNOWN (${VERDICT})${NC}"
+    echo "Could not parse verdict. Allowing commit."
+    exit 0
+    ;;
+esac
+

package/framework/scripts/check-linting-sync.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+################################################################################
+# ESLint Config Sync Check (SessionStart hook)
+#
+# Checks if .safeword/eslint/eslint-base.mjs matches the frameworks in package.json.
+# Alerts user if out of sync (e.g., React added but not in ESLint config).
+#
+# Usage: Called automatically at Claude Code session start
+################################################################################
+
+# Quick exit if no eslint config
+[ ! -f ".safeword/eslint/eslint-base.mjs" ] && exit 0
+[ ! -f "package.json" ] && exit 0
+
+# Read dependencies
+if command -v jq &> /dev/null; then
+  DEPS=$(jq -r '(.dependencies // {}), (.devDependencies // {}) | keys[]' package.json 2>/dev/null || echo "")
+else
+  DEPS=$(grep -E '"[^"]+"\s*:' package.json | cut -d'"' -f2)
+fi
+
+# Detect what's installed
+HAS_TS=false
+HAS_REACT=false
+HAS_ASTRO=false
+
+{ [ -f "tsconfig.json" ] || echo "$DEPS" | grep -qx "typescript"; } && HAS_TS=true
+echo "$DEPS" | grep -qx "react" && HAS_REACT=true
+echo "$DEPS" | grep -qx "astro" && HAS_ASTRO=true
+
+# Check what's in the config
+CONFIG_HAS_TS=false
+CONFIG_HAS_REACT=false
+CONFIG_HAS_ASTRO=false
+
+grep -q "typescript-eslint" .safeword/eslint/eslint-base.mjs 2>/dev/null && CONFIG_HAS_TS=true
+grep -q "@eslint-react" .safeword/eslint/eslint-base.mjs 2>/dev/null && CONFIG_HAS_REACT=true
+grep -q "eslint-plugin-astro" .safeword/eslint/eslint-base.mjs 2>/dev/null && CONFIG_HAS_ASTRO=true
+
+# Build mismatch message
+MISMATCHES=""
+
+[ "$HAS_TS" = true ] && [ "$CONFIG_HAS_TS" = false ] && MISMATCHES+="TypeScript added. "
+[ "$HAS_TS" = false ] && [ "$CONFIG_HAS_TS" = true ] && MISMATCHES+="TypeScript removed. "
+[ "$HAS_REACT" = true ] && [ "$CONFIG_HAS_REACT" = false ] && MISMATCHES+="React added. "
+[ "$HAS_REACT" = false ] && [ "$CONFIG_HAS_REACT" = true ] && MISMATCHES+="React removed. "
+[ "$HAS_ASTRO" = true ] && [ "$CONFIG_HAS_ASTRO" = false ] && MISMATCHES+="Astro added. "
+[ "$HAS_ASTRO" = false ] && [ "$CONFIG_HAS_ASTRO" = true ] && MISMATCHES+="Astro removed. "
+
+# Alert if mismatched
+if [ -n "$MISMATCHES" ]; then
+  echo "⚠️  ESLint config out of sync: $MISMATCHES"
+  echo "   Run: bash .safeword/scripts/setup-linting.sh"
+  echo ""
+fi
+
+exit 0
+

package/framework/scripts/load-env.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Load environment variables from .env file
+# Source this in other scripts: source "$(dirname "$0")/load-env.sh"
+#
+# Priority: Shell env > .env.local > .env
+# Does NOT override existing shell variables
+
+set -euo pipefail
+
+# Find project root (look for .git or package.json)
+find_project_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" ]] || [[ -d "$dir/.git" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  echo "$PWD"
+}
+
+PROJECT_ROOT="${PROJECT_ROOT:-$(find_project_root)}"
+
+# Load .env file (does not override existing vars)
+load_env_file() {
+  local env_file="$1"
+  if [[ -f "$env_file" ]]; then
+    while IFS='=' read -r key value; do
+      # Skip comments and empty lines
+      [[ "$key" =~ ^#.*$ ]] && continue
+      [[ -z "$key" ]] && continue
+      
+      # Trim whitespace
+      key="${key// /}"
+      value="${value%"${value##*[![:space:]]}"}"
+      
+      # Only set if not already in environment
+      if [[ -z "${!key:-}" ]]; then
+        export "$key=$value"
+      fi
+    done < "$env_file"
+  fi
+}
+
+# Load in priority order (first wins due to skip-if-exists logic)
+load_env_file "$PROJECT_ROOT/.env.local"
+load_env_file "$PROJECT_ROOT/.env"
+