rhachet-roles-ehmpathy 1.9.0 → 1.9.1

package/dist/logic/roles/mechanic/.skills/declapract.upgrade.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = upgrade declapract and apply latest best practices
+#
+# .why  = declapract manages development best practices and tooling
+#         configuration across projects, ensuring consistency and
+#         enabling easy upgrades to latest standards.
+#
+#         this skill upgrades declapract packages and reapplies
+#         practices, then validates the build still passes.
+#
+# guarantee:
+#   ✔ verifies declapract.use.yml exists before proceeding
+#   ✔ upgrades to latest declapract packages
+#   ✔ applies practices twice (ensures idempotency)
+#   ✔ reinstalls dependencies after application
+#   ✔ fail-fast on any error
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+CONFIG_FILE="$PROJECT_ROOT/declapract.use.yml"
+
+# Verify declapract config exists
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "❌ no declapract.use.yml found in project root"
+  echo "   $CONFIG_FILE"
+  echo "➡️  first configure declapract for this project"
+  exit 1
+fi
+
+echo "📦 upgrading declapract packages..."
+npm install --save-dev declapract@latest declapract-typescript-ehmpathy@latest
+
+echo ""
+echo "✨ applying best practices..."
+npx declapract apply && npx declapract apply
+
+echo ""
+echo "📦 reinstalling dependencies..."
+npm install
+
+echo ""
+echo "✅ declapract upgrade complete!"
+echo ""
+echo "⚠️  next steps:"
+echo "   1. verify build passes: npm run test:types && npm run build"
+echo "   2. review changes for breaking updates"
+echo "   3. test that all still behaves as expected"

package/dist/logic/roles/mechanic/.skills/init.claude.hooks.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic SessionStart hook to Claude settings
+#
+# .why  = the mechanic role needs to boot on every Claude session
+#         to ensure project context and briefs are loaded.
+#
+#         this script "findserts" (find-or-insert) the SessionStart
+#         hook into .claude/settings.local.json, ensuring:
+#           • the hook is present after running this skill
+#           • no duplication if already present
+#           • idempotent: safe to rerun
+#
+# .how  = uses jq to merge the SessionStart hook configuration
+#         into the existing hooks structure, creating it if absent.
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (permissions, other hooks)
+#   ✔ idempotent: no-op if hook already present
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+
+# Define the hook configuration to findsert
+HOOK_CONFIG=$(cat <<'EOF'
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx rhachet roles boot --repo ehmpathy --role mechanic",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+)
+
+# Ensure .claude directory exists
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+# Initialize settings file if it doesn't exist
+if [[ ! -f "$SETTINGS_FILE" ]]; then
+  echo "{}" > "$SETTINGS_FILE"
+fi
+
+# Findsert: merge the hook configuration if not already present
+# Strategy: deep merge with existing hooks, creating structure if needed
+jq --argjson hook "$HOOK_CONFIG" '
+  # Define the target command for comparison
+  def targetCmd: "npx rhachet roles boot --repo ehmpathy --role mechanic";
+
+  # Check if hook already exists
+  def hookExists:
+    (.hooks.SessionStart // [])
+    | map(select(.matcher == "*") | .hooks // [])
+    | flatten
+    | map(.command)
+    | index(targetCmd) != null;
+
+  # If hook already exists, return unchanged
+  if hookExists then
+    .
+  else
+    # Ensure .hooks exists
+    .hooks //= {} |
+
+    # Ensure .hooks.SessionStart exists
+    .hooks.SessionStart //= [] |
+
+    # Check if our matcher already exists
+    if (.hooks.SessionStart | map(.matcher) | index("*")) then
+      # Matcher exists, add our hook to its hooks array
+      .hooks.SessionStart |= map(
+        if .matcher == "*" then
+          .hooks += $hook.hooks.SessionStart[0].hooks
+        else
+          .
+        end
+      )
+    else
+      # Matcher does not exist, add the entire entry
+      .hooks.SessionStart += $hook.hooks.SessionStart
+    end
+  end
+' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp"
+
+# Check if any changes were made
+if diff -q "$SETTINGS_FILE" "$SETTINGS_FILE.tmp" >/dev/null 2>&1; then
+  rm "$SETTINGS_FILE.tmp"
+  echo "👌 mechanic SessionStart hook already bound"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 mechanic SessionStart hook bound successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ next time you start a Claude session, the mechanic will boot automatically"

package/dist/logic/roles/mechanic/.skills/link.claude.transcripts.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = link Claude transcripts into project-local structure
+#
+# .why  = Claude stores transcripts in ~/.claude/projects/<encoded-path>
+#         which makes them hard to browse, version-control, and sync.
+#
+#         this script creates a symlink so transcripts appear under:
+#           <project>/.rhachet/claude/transcripts
+#
+#         without altering, moving, or creating files in Claude storage.
+#
+# guarantee:
+#   ✔ zero mutation to Claude's storage
+#   ✔ fail-fast if transcripts don't exist yet
+#   ✔ safe to rerun (idempotent)
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+DEST="$PROJECT_ROOT/.rhachet/claude/transcripts"
+
+# Resolve where Claude stores transcripts for this project’s cwd
+ENCODED_PATH="$(echo "$PROJECT_ROOT" | sed 's#/#-#g')"
+CLAUDE_STORAGE="$HOME/.claude/projects/$ENCODED_PATH"
+
+# Fail if Claude hasn't created the storage dir yet
+if [[ ! -d "$CLAUDE_STORAGE" ]]; then
+  echo "❌ no Claude transcripts found for this project:"
+  echo "   $CLAUDE_STORAGE"
+  echo "➡️  first run 'claude' once in this directory to create them"
+  exit 1
+fi
+
+# Ensure our local parent folder exists (not Claude’s)
+mkdir -p "$(dirname "$DEST")"
+
+# Create symlink pointing into Claude-managed storage
+ln -sfn "$CLAUDE_STORAGE" "$DEST"
+
+echo "🔗 linked:"
+echo "  $DEST → $CLAUDE_STORAGE"

package/dist/logic/roles/mechanic/.skills/run.test.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+######################################################################
+# # tldr
+#
+# .what: run tests with proper setup, logs, and context preservation
+# .why:  preserve test output for review without rerun, auto-configure AWS and testdb
+# .how:  ./run.test.sh unit
+#        ./run.test.sh integration "pattern"
+#        ./run.test.sh acceptance
+#
+######################################################################
+# # full
+#
+# .what
+#
+# run tests with proper setup, logs, and context preservation
+#
+# supports unit, integration, and acceptance tests with automatic:
+# - output logs to .log/test/ for repeated review
+# - scope filter and THOROUGH mode
+# - AWS profile configuration (for repos with AWS resources)
+# - test database provision (when start:testdb is available)
+#
+#
+# .why
+#
+# tests require different setup depending on their type:
+#
+# unit tests:
+#   - isolated, no external dependencies
+#   - fast execution
+#   - use --changedSince by default for speed
+#
+# integration tests:
+#   - interact with databases and remote resources
+#   - require AWS credentials (if repo uses AWS)
+#   - require test databases (if repo uses a testdb)
+#   - test interactions between components
+#
+# acceptance tests:
+#   - end-to-end testing
+#   - require AWS credentials (if repo uses AWS)
+#   - require test database provisioning
+#   - verify complete user workflows
+#
+# all tests benefit from:
+#   - output logs via tee to .log/test/{type}/run.{timestamp}.out
+#   - preserved context for review without rerun
+#   - comparison of results across test runs
+#
+#
+# .howto.use
+#
+# ## unit tests
+#
+# run all unit tests (uses --changedSince for speed):
+#   ./run.test.sh unit
+#
+# run unit tests that match a pattern (automatically THOROUGH):
+#   ./run.test.sh unit "syncPhone"
+#   ./run.test.sh unit "relate.*Path"
+#
+# run all unit tests thoroughly (no --changedSince):
+#   THOROUGH=true ./run.test.sh unit
+#
+# behavior:
+#   - no AWS_PROFILE configuration
+#   - no test database provision
+#   - uses --changedSince by default (unless scope provided or THOROUGH=true)
+#   - logs to .log/test/unit/run.{timestamp}.out
+#
+#
+# ## integration tests
+#
+# run all integration tests:
+#   ./run.test.sh integration
+#
+# run integration tests that match a pattern:
+#   ./run.test.sh integration "database.*sync"
+#   ./run.test.sh integration "whodis"
+#
+# behavior:
+#   - sets AWS_PROFILE=$org.dev (if awsAccountId in declapract.use.yml)
+#   - runs start:testdb (if available in package.json)
+#   - uses --changedSince by default (unless scope provided or THOROUGH=true)
+#   - logs to .log/test/integration/run.{timestamp}.out
+#
+#
+# ## acceptance tests
+#
+# run all acceptance tests locally:
+#   ./run.test.sh acceptance
+#
+# run acceptance tests that match a pattern:
+#   ./run.test.sh acceptance "user.*flow"
+#
+# behavior:
+#   - sets AWS_PROFILE=$org.dev (if awsAccountId in declapract.use.yml)
+#   - runs start:testdb (if available in package.json)
+#   - uses test:acceptance:locally (local execution only for now)
+#   - logs to .log/test/acceptance/run.{timestamp}.out
+#
+#
+# ## review test output
+#
+# all test output is logged via tee to .log/test/{type}/run.{timestamp}.out
+#
+# review the latest test run:
+#   cat .log/test/unit/run.*.out | tail -n 1 | xargs cat
+#
+# compare test results across runs:
+#   ls -t .log/test/unit/
+#   diff .log/test/unit/run.2025-11-23T15-00-00Z.out \
+#        .log/test/unit/run.2025-11-23T15-10-00Z.out
+#
+# search for failures in logs:
+#   grep -r "FAIL" .log/test/unit/
+#
+#
+# .guarantee
+#
+#   ✔ configure AWS_PROFILE only if awsAccountId in declapract.use.yml
+#   ✔ provision test database only if start:testdb in package.json
+#   ✔ log output to .log/test/{type}/run.{timestamp}.out via tee
+#   ✔ preserve context for repeated review without rerun
+#   ✔ support jest pattern/scope filter
+#   ✔ automatically set THOROUGH=true when scope is provided
+#   ✔ fail-fast on test failures
+#   ✔ show relative paths for easy navigation
+######################################################################
+
+set -euo pipefail
+
+# Parse arguments
+TEST_TYPE="${1:-}"
+SCOPE="${2:-}"
+
+# Default to THOROUGH mode when scope is provided (unless explicitly set)
+if [[ -n "$SCOPE" ]] && [[ -z "${THOROUGH:-}" ]]; then
+  export THOROUGH=true
+fi
+
+# Validate test type
+if [[ -z "$TEST_TYPE" ]]; then
+  echo "✗ test type required"
+  echo ""
+  echo "usage: $0 <type> [pattern]"
+  echo ""
+  echo "types:"
+  echo "  unit         - run unit tests"
+  echo "  integration  - run integration tests"
+  echo "  acceptance   - run acceptance tests"
+  echo ""
+  echo "examples:"
+  echo "  $0 unit"
+  echo "  $0 integration 'database.*sync'"
+  echo "  THOROUGH=true $0 unit"
+  exit 1
+fi
+
+if [[ ! "$TEST_TYPE" =~ ^(unit|integration|acceptance)$ ]]; then
+  echo "✗ invalid test type: $TEST_TYPE"
+  echo "   valid types: unit, integration, acceptance"
+  exit 1
+fi
+
+PROJECT_ROOT="$PWD"
+LOG_DIR="$PROJECT_ROOT/.log/test/$TEST_TYPE"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
+LOG_FILE="$LOG_DIR/run.$TIMESTAMP.out"
+
+# Ensure log directory exists
+mkdir -p "$LOG_DIR"
+
+echo "→ run $TEST_TYPE tests"
+echo "→ log to: ${LOG_FILE#$PROJECT_ROOT/}"
+echo ""
+
+# Configure AWS profile and provision test database for integration/acceptance tests
+if [[ "$TEST_TYPE" == "integration" ]] || [[ "$TEST_TYPE" == "acceptance" ]]; then
+  # Check if awsAccountId is specified in declapract.use.yml
+  if [[ -f "declapract.use.yml" ]] && grep -q "awsAccountId:" declapract.use.yml; then
+    # Extract organization from declapract.use.yml
+    ORGANIZATION=$(grep -E '^\s*organizationName:' declapract.use.yml | sed "s/.*organizationName:[[:space:]]*['\"]*//" | sed "s/['\"].*//")
+
+    if [[ -n "$ORGANIZATION" ]]; then
+      # Configure AWS profile for dev resources
+      export AWS_PROFILE="$ORGANIZATION.dev"
+      echo "→ AWS_PROFILE=$AWS_PROFILE"
+    fi
+  fi
+
+  # Start test database if available in package.json
+  if npm run | grep -q "start:testdb"; then
+    echo "→ start:testdb"
+    echo ""
+    npm run start:testdb 2>&1 | tee -a "$LOG_FILE"
+  fi
+fi
+
+# Build the test command
+case "$TEST_TYPE" in
+  unit)
+    TEST_COMMAND="npm run test:unit"
+    ;;
+  integration)
+    TEST_COMMAND="npm run test:integration"
+    ;;
+  acceptance)
+    # only support local acceptance tests for now
+    TEST_COMMAND="npm run test:acceptance:locally"
+    ;;
+esac
+
+# Add scope filter if provided
+if [[ -n "$SCOPE" ]]; then
+  echo "→ scope filter: $SCOPE"
+  echo ""
+  TEST_COMMAND="$TEST_COMMAND -- '$SCOPE'"
+else
+  echo "→ scope: all tests"
+  echo ""
+fi
+
+# Run tests with output logged via tee
+echo "> $TEST_COMMAND" | tee -a "$LOG_FILE"
+echo "" | tee -a "$LOG_FILE"
+
+eval "$TEST_COMMAND" 2>&1 | tee -a "$LOG_FILE"
+TEST_EXIT_CODE=${PIPESTATUS[0]}
+
+echo "" | tee -a "$LOG_FILE"
+
+if [[ $TEST_EXIT_CODE -eq 0 ]]; then
+  echo "✓ $TEST_TYPE tests complete!" | tee -a "$LOG_FILE"
+  echo "→ log saved: ${LOG_FILE#$PROJECT_ROOT/}"
+  exit 0
+else
+  echo "✗ $TEST_TYPE tests failed" | tee -a "$LOG_FILE"
+  echo "→ log saved: ${LOG_FILE#$PROJECT_ROOT/}"
+  echo ""
+  echo "→ review the log file for details:"
+  echo "   cat ${LOG_FILE#$PROJECT_ROOT/}"
+  exit $TEST_EXIT_CODE
+fi

package/dist/logic/roles/mechanic/.skills/test.integration.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = run integration tests thoroughly with optional scope filter
+#
+# .why  = integration tests verify interactions between components
+#         and external systems. running them thoroughly (without
+#         --changedSince) ensures all tests pass, not just changed ones.
+#
+#         this is critical before releases, after major changes, or
+#         when verifying the entire test suite.
+#
+# usage for agents:
+#   - run all integration tests:
+#       ./test.integration.sh
+#
+#   - run tests matching a specific scope/pattern:
+#       ./test.integration.sh <pattern>
+#       example: ./test.integration.sh "user.*auth"
+#       example: ./test.integration.sh "database"
+#
+#   - the THOROUGH=true flag forces ALL tests to run, not just
+#     those changed since main branch
+#
+# guarantee:
+#   ✔ runs ALL integration tests (ignores --changedSince)
+#   ✔ supports optional jest pattern/scope filtering
+#   ✔ uses verbose output for debugging
+#   ✔ passes with no tests if scope matches nothing
+#   ✔ fail-fast on test failures
+######################################################################
+
+set -euo pipefail
+
+SCOPE="${1:-}"
+
+echo "🧪 running integration tests thoroughly..."
+echo ""
+
+if [[ -n "$SCOPE" ]]; then
+  echo "📍 scope filter: $SCOPE"
+  echo ""
+  THOROUGH=true npm run test:integration -- "$SCOPE"
+else
+  echo "📍 scope: all tests"
+  echo ""
+  THOROUGH=true npm run test:integration
+fi
+
+echo ""
+echo "✅ integration tests complete!"

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [
@@ -26,7 +26,7 @@
     "fix:lint": "eslint -c ./.eslintrc.js src/**/*.ts --fix",
     "build:clean": "rm dist/ -rf",
     "build:compile": "tsc -p ./tsconfig.build.json",
-    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --include='**/*.template.md' --include='**/.briefs/**/*.md' --include='**/.briefs/*.md' --exclude='*' src/ dist/",
+    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --include='**/*.template.md' --include='**/.briefs/**/*.md' --include='**/.briefs/*.md' --include='**/.skills/**/*.sh' --include='**/.skills/*.sh' --exclude='*' src/ dist/",
     "build": "npm run build:clean && npm run build:compile && npm run build:complete",
     "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
     "test:types": "tsc -p ./tsconfig.build.json --noEmit",