safeword 0.2.4 → 0.2.6

package/framework/README.md

@@ -1,131 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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

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

package/framework/mcp/context7.sample.json

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

package/framework/mcp/playwright.sample.json

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

package/framework/scripts/arch-review.sh

@@ -1,235 +0,0 @@
-#!/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

@@ -1,58 +0,0 @@
-#!/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

@@ -1,49 +0,0 @@
-#!/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"
-