@codeyam/codeyam-cli 0.1.0-bleeding-edge.8afd3ee

package/codeyam-cli/templates/codeyam-stop-hook.sh

@@ -0,0 +1,284 @@
+#!/bin/bash
+# CodeYam Stop Hook (portable, jq-free, last-stop tracking)
+# - Reads input JSON from stdin
+# - Gets conversation start from:
+#   1. Last stop time (if available from .codeyam/.last-stop-time)
+#   2. Transcript line 2 ISO-8601 timestamp (session start)
+# - If any relevant files changed since then, blocks with message to run `codeyam verify`
+# - Saves current time to .codeyam/.last-stop-time for next continuation
+# - Toggle logs with CODEYAM_HOOK_DEBUG=1
+
+set -uo pipefail
+
+exit 0
+
+# =========================
+# Debugging (toggleable) Change to 1 to enable
+# =========================
+DEBUG_ON="0"
+DEBUG_LOG="/tmp/codeyam-stop-hook-debug.log"
+log() { [[ "$DEBUG_ON" == "1" ]] && echo "$@" >> "$DEBUG_LOG"; }
+if [[ "$DEBUG_ON" == "1" ]]; then
+  {
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "🔍 Stop Hook Fired at $(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+    echo "PWD: $(pwd)"
+    echo "USER: ${USER:-unknown}"
+    echo "SHELL: ${SHELL:-unknown}"
+  } >> "$DEBUG_LOG"
+fi
+
+# =========================
+# Helpers
+# =========================
+
+json_get_str() {
+  local key="$1" json="$2"
+  printf '%s' "$json" \
+    | sed -nE 's/.*"'$key'":[[:space:]]*"(([^"\\]|\\.)*)".*/\1/p' \
+    | sed 's/\\"/"/g'
+}
+
+json_get_bool() {
+  local key="$1" json="$2"
+  printf '%s' "$json" \
+    | sed -nE 's/.*"'$key'":[[:space:]]*(true|false).*/\1/p'
+}
+
+extract_iso8601() {
+  local line="$1"
+  if command -v grep >/dev/null 2>&1; then
+    printf '%s\n' "$line" \
+      | grep -Eo '[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[+\-][0-9]{2}(:?[0-9]{2})?)' \
+      | head -n1
+  else
+    printf '%s\n' "$line" \
+      | awk '
+        match($0, /[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[+\-][0-9]{2}(:?[0-9]{2})?)/, m) { print m[0] }
+      ' | head -n1
+  fi
+}
+
+date_is_gnu() { date --version >/dev/null 2>&1; }
+
+normalize_for_bsd() {
+  local ts="$1"
+  # drop fractional seconds
+  ts="${ts%%.*}$(printf '%s' "$ts" | sed -nE 's/^[^.]*((\.[0-9]+)?)(.*)$/\3/p')"
+  # Z -> +0000
+  ts="$(printf '%s' "$ts" | sed -E 's/Z$/+0000/')"
+  # remove colon in tz offset
+  ts="$(printf '%s' "$ts" | sed -E 's/([+\-][0-9]{2}):?([0-9]{2})$/\1\2/')"
+  printf '%s' "$ts"
+}
+
+iso_to_epoch() {
+  local in="$1"
+  if date_is_gnu; then
+    date -d "$in" +%s 2>/dev/null && return 0
+  fi
+  local ts_bsd
+  ts_bsd="$(normalize_for_bsd "$in")"
+  if ! printf '%s' "$ts_bsd" | grep -Eq '(Z|[+\-][0-9]{4})$'; then
+    ts_bsd="${ts_bsd}+0000"
+  fi
+  date -j -f "%Y-%m-%dT%H:%M:%S%z" "$ts_bsd" "+%s" 2>/dev/null && return 0
+  return 1
+}
+
+file_mtime_epoch() {
+  local f="$1"
+  stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0
+}
+
+# Try multiple ways to run `codeyam verify`
+run_codeyam_verify_bg() {
+  local root="$1"
+  local logfile="$2"
+  local cmd=""
+  if command -v codeyam >/dev/null 2>&1; then
+    cmd="codeyam verify"
+  elif command -v pnpm >/dev/null 2>&1 && [[ -f "$root/package.json" ]]; then
+    # prefer direct bin if present, otherwise script
+    if [[ -x "$root/node_modules/.bin/codeyam" ]]; then
+      cmd="$root/node_modules/.bin/codeyam verify"
+    else
+      cmd="pnpm codeyam verify"
+    fi
+  elif command -v npm >/dev/null 2>&1 && [[ -f "$root/package.json" ]]; then
+    if [[ -x "$root/node_modules/.bin/codeyam" ]]; then
+      cmd="$root/node_modules/.bin/codeyam verify"
+    else
+      cmd="npm run --silent codeyam -- verify"
+    fi
+  else
+    # last resort: npx fetch
+    cmd="npx -y codeyam verify"
+  fi
+
+  log "▶️ Launching verify command: (cd \"$root\" && $cmd)"
+  # Detach: nohup + background, independent of the hook lifecycle
+  ( cd "$root" && nohup bash -lc "$cmd" >> "$logfile" 2>&1 & ) >/dev/null 2>&1
+}
+
+# Simple lock to avoid parallel verify runs
+acquire_lock() {
+  local lock="$1"
+  if ( set -o noclobber; : > "$lock" ) 2>/dev/null; then
+    echo $$ > "$lock"
+    return 0
+  fi
+  return 1
+}
+release_lock() {
+  local lock="$1"
+  rm -f "$lock" 2>/dev/null || true
+}
+
+# =========================
+# Read input JSON
+# =========================
+
+INPUT="$(cat)"
+log "📥 Received input: $INPUT"
+
+STOP_HOOK_ACTIVE="$(json_get_bool 'stop_hook_active' "$INPUT")"
+TRANSCRIPT_PATH="$(json_get_str 'transcript_path' "$INPUT")"
+REQUEST_CWD="$(json_get_str 'cwd' "$INPUT")"
+
+log "Parsed stop_hook_active=${STOP_HOOK_ACTIVE:-}"
+log "Parsed transcript_path=${TRANSCRIPT_PATH:-}"
+log "Parsed cwd=${REQUEST_CWD:-}"
+
+# If already in continuation loop, allow stop
+if [[ "${STOP_HOOK_ACTIVE:-false}" == "true" ]]; then
+  log "⚠️ stop_hook_active=true - allow stop"
+  exit 0
+fi
+
+# cd to provided cwd if valid
+if [[ -n "${REQUEST_CWD:-}" && -d "${REQUEST_CWD}" ]]; then
+  log "📂 cd $REQUEST_CWD"
+  cd "$REQUEST_CWD" || log "❌ cd failed"
+fi
+
+# Discover project root
+PROJECT_ROOT="$(pwd)"
+while [[ ! -d "$PROJECT_ROOT/.codeyam" && "$PROJECT_ROOT" != "/" ]]; do
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+if [[ "$PROJECT_ROOT" == "/" ]]; then
+  log "❌ No .codeyam found; allow stop"
+  exit 0
+fi
+log "✅ Project root: $PROJECT_ROOT"
+
+# Determine conversation start time
+# Use the MORE RECENT of: last stop time OR session start time
+LAST_STOP_FILE="$PROJECT_ROOT/.codeyam/.last-stop-time"
+CONVERSATION_START_TIME=""
+SESSION_START_TIME=""
+LAST_STOP_TIME=""
+
+# Get transcript session start time
+if [[ -z "${TRANSCRIPT_PATH:-}" || ! -f "${TRANSCRIPT_PATH}" ]]; then
+  log "❌ transcript_path missing or file not found; allow stop"
+  exit 0
+fi
+
+SECOND_LINE="$(sed -n '2p' -- "$TRANSCRIPT_PATH" 2>/dev/null || true)"
+log "Line2 (<=200 chars): ${SECOND_LINE:0:200}"
+
+ISO_TS="$(extract_iso8601 "$SECOND_LINE" || true)"
+log "ISO8601: ${ISO_TS:-<none>}"
+
+if [[ -z "$ISO_TS" ]]; then
+  log "❌ Could not extract timestamp; allow stop"
+  exit 0
+fi
+
+if ! SESSION_START_TIME="$(iso_to_epoch "$ISO_TS")"; then
+  log "❌ Could not convert timestamp to epoch; allow stop"
+  exit 0
+fi
+log "🕒 Session start epoch: $SESSION_START_TIME"
+
+# Get last stop time if it exists
+if [[ -f "$LAST_STOP_FILE" ]]; then
+  LAST_STOP_TIME="$(cat "$LAST_STOP_FILE" 2>/dev/null || true)"
+  if [[ -n "$LAST_STOP_TIME" ]] && [[ "$LAST_STOP_TIME" =~ ^[0-9]+$ ]]; then
+    log "🕒 Last stop epoch: $LAST_STOP_TIME"
+  else
+    LAST_STOP_TIME=""
+  fi
+fi
+
+# Use whichever is more recent (higher epoch number)
+if [[ -n "$LAST_STOP_TIME" ]] && [[ $LAST_STOP_TIME -gt $SESSION_START_TIME ]]; then
+  CONVERSATION_START_TIME="$LAST_STOP_TIME"
+  log "✅ Using last stop time (more recent): $CONVERSATION_START_TIME"
+else
+  CONVERSATION_START_TIME="$SESSION_START_TIME"
+  log "✅ Using session start time: $CONVERSATION_START_TIME"
+fi
+
+# Gather changed files since start
+log "git diff --name-only --diff-filter=AM"
+ALL_CHANGED_FILES="$(
+  git diff --name-only --diff-filter=AM 2>/dev/null \
+  | grep -E '\.(ts|tsx|jsx|vue)$' \
+  | grep -Ev '\.(test|spec)\.(ts|tsx|jsx)$' \
+  | grep -Ev '\.d\.ts$' \
+  || true
+)"
+
+CHANGED_FILES=""
+if [[ -n "$ALL_CHANGED_FILES" ]]; then
+  while IFS= read -r file; do
+    [[ -z "$file" ]] && continue
+    [[ -f "$file" ]] || continue
+    FILE_MTIME="$(file_mtime_epoch "$file")"
+    log "  $file mtime=$FILE_MTIME vs $CONVERSATION_START_TIME"
+    if [[ "$FILE_MTIME" =~ ^[0-9]+$ ]] && [[ $FILE_MTIME -ge $CONVERSATION_START_TIME ]]; then
+      CHANGED_FILES+="$file"$'\n'
+    fi
+  done <<< "$ALL_CHANGED_FILES"
+fi
+
+CHANGED_FILES="$(echo "$CHANGED_FILES" | sed '/^$/d')"
+
+if [[ -n "$CHANGED_FILES" ]]; then
+  FILE_COUNT="$(echo "$CHANGED_FILES" | wc -l | tr -d ' ')"
+  log "✅ $FILE_COUNT changed file(s):"
+  log "$(echo "$CHANGED_FILES" | sed 's/^/  • /')"
+
+  # Save current time as last stop time BEFORE blocking
+  CURRENT_TIME="$(date +%s)"
+  echo "$CURRENT_TIME" > "$LAST_STOP_FILE" 2>/dev/null || log "⚠️ Could not save last stop time"
+  log "💾 Saved stop time: $CURRENT_TIME (before blocking)"
+
+  # Return structured JSON here if you want to block & trigger follow-up.
+  JSON_RESPONSE=$(cat << EOF
+{
+  "decision": "block",
+  "reason": "$FILE_COUNT application files have changed. If these changes will likely be committed please use the \"CodeYam Verify\" skill to simulate these changes. If you are just debugging, then there is no need to.",
+}
+EOF
+)
+
+  log "📤 Returning JSON (to stderr): $JSON_RESPONSE"
+  echo "$JSON_RESPONSE" >&2
+
+  log "✅ Hook completed successfully"
+  log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  exit 2
+else
+  log "ℹ️ No changed files since start"
+  # Save current time as last stop time for next continuation
+  CURRENT_TIME="$(date +%s)"
+  echo "$CURRENT_TIME" > "$LAST_STOP_FILE" 2>/dev/null || log "⚠️ Could not save last stop time"
+  log "💾 Saved stop time: $CURRENT_TIME"
+fi
+
+# Always allow the stop to proceed
+exit 0

package/codeyam-cli/templates/codeyam-test-skill.md

@@ -0,0 +1,178 @@
+---
+name: CodeYam Testing
+autoApprove: true
+description: |
+  Use this skill to write comprehensive unit and integration tests using CodeYam's mock generation.
+  Use when: User asks to write tests, generate mocks, understand function dependencies, or improve test coverage.
+  This skill uses the `codeyam generate-data-structure` command to create realistic test mocks based on actual code analysis.
+---
+
+# CodeYam Testing Assistant
+
+Use this skill to help users write comprehensive unit and integration tests for their code using CodeYam's dependency analysis and mock generation.
+
+## When to Use This Skill
+
+- User asks to write unit or integration tests
+- User wants to generate Jest mocks for a function
+- User needs help understanding function dependencies for testing
+- User requests mock data for testing
+- You see an opportunity to improve test coverage
+- Testing complex functions with many dependencies
+
+## Important: Permissions Already Configured
+
+The `codeyam init` command has already auto-approved:
+
+- ✅ All CodeYam CLI commands (including `codeyam generate-data-structure`)
+- ✅ All CodeYam skills
+- ✅ All file operations in the `.codeyam/` directory
+
+You can freely use Read, Write, and Bash tools for CodeYam operations without asking for permission.
+
+## Workflow: Writing Tests with CodeYam
+
+### Step 1: Generate Mock Template
+
+Use `codeyam generate-data-structure` to analyze the function and generate a mock template:
+
+```bash
+codeyam generate-data-structure --entity FunctionName path/to/file.ts
+```
+
+**What this does:**
+
+1. Runs partial analysis (data structure only, no scenarios)
+2. Discovers all function dependencies
+3. Generates Jest mock template with proper types
+4. Caches results for instant subsequent runs
+
+**Optional flags:**
+
+- `--json` - Output raw data structure for advanced use cases
+- `--output path/to/output.ts` - Write to file instead of stdout
+
+**Example:**
+
+```bash
+codeyam generate-data-structure --entity computeBranchEntityDiff codeyam-cli/src/webserver/app/lib/branchEntityComparison.ts
+```
+
+### Step 2: Understand the Analysis Output
+
+The mock template shows:
+
+- **Dependencies by module** - All external functions/imports
+- **Mock declarations** - `jest.mock()` calls for each module
+- **Return value templates** - Sample data for `mockReturnValue()`
+
+**With `--json` flag, you get:**
+
+```json
+{
+  "dataForMocks": {
+    "getProjectRoot()": "/project/root",
+    "getBranchDiffForProject(baseBranch, compareBranch)": [...]
+  },
+  "dependencySchemas": {
+    "module/path": {
+      "functionName": { "type": "object", "properties": {...} }
+    }
+  }
+}
+```
+
+### Step 3: Write the Test
+
+Use the generated template as a starting point:
+
+**Key principles learned from experience:**
+
+1. **Mock external dependencies only** - Let internal functions run
+2. **Use realistic mock data** - Based on CodeYam's analysis
+3. **Test behavior, not implementation** - Focus on what the function does
+4. **Consider edge cases** - Added files, deleted files, empty results, etc.
+
+**Example pattern:**
+
+```typescript
+// Mock external dependencies
+jest.mock('path/to/module', () => ({
+  externalFunction: jest.fn(),
+}));
+
+describe('FunctionName', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Setup default mocks
+  });
+
+  it('should handle normal case', () => {
+    // Arrange: Setup mocks
+    // Act: Call function
+    // Assert: Verify behavior
+  });
+
+  it('should handle edge case', () => {
+    // Test edge cases
+  });
+});
+```
+
+### Step 4: Run the Test
+
+```bash
+npx jest path/to/test.test.ts --verbose
+```
+
+### Step 5: Iterate
+
+If tests fail:
+
+1. Check mock data matches actual usage
+2. Verify mock call counts (added files call extract once, modified call twice)
+3. Ensure edge cases are handled
+4. Use `jest.clearAllMocks()` between tests for isolation
+
+## Common Testing Patterns
+
+### Integration Tests
+
+- Mock external dependencies (fs, child_process, imports)
+- Let internal logic run naturally
+- Test complete workflows
+
+### Unit Tests
+
+- Mock all dependencies
+- Test single function in isolation
+- Focus on edge cases and error handling
+
+### Cache Testing
+
+- Test both cache hit and miss scenarios
+- Verify cache writes happen correctly
+- Ensure cache reads prevent unnecessary work
+
+## Tips from Experience
+
+1. **Call counts matter** - Different file statuses call dependencies differently:
+   - Modified files: extract entities from old AND new content (2 calls)
+   - Added files: extract only from new content (1 call)
+   - Deleted files: extract only from old content (1 call)
+
+2. **Mock isolation** - Use `jest.clearAllMocks()` between tests to prevent interference
+
+3. **Realistic data** - Use CodeYam's analysis to ensure mock data matches real usage patterns
+
+4. **Test structure** - Organize by scenarios (cache hit, cache miss, edge cases)
+
+## When NOT to Use This Skill
+
+- User wants to simulate a component in the browser → Use **CodeYam Simulation** skill instead
+- User wants to see visual screenshots of scenarios → Use **CodeYam Simulation** skill instead
+- User asks to "analyze" or "simulate" an entity → Use **CodeYam Simulation** skill instead
+
+---
+
+**Remember**: This skill is for writing traditional unit/integration tests with Jest. For running CodeYam simulations with screenshots and scenarios, use the CodeYam Simulation skill.

package/codeyam-cli/templates/codeyam-verify-skill.md

@@ -0,0 +1,179 @@
+---
+name: CodeYam Verify
+autoApprove: true
+description: |
+  Use this skill after making code changes that impact application functionality.
+  Automatically run simulations to verify your changes and present results to the user.
+  Use when: You've completed making changes to visual components or library functions and are ready to present your work.
+
+  NOTE: A Stop hook is installed that will remind you to use this skill if you made changes to .ts/.tsx/.jsx/.vue files during the session.
+---
+
+# CodeYam Verify Assistant
+
+Use this skill to automatically verify code changes by running simulations and presenting results to the user.
+
+## When to Use This Skill
+
+**IMPORTANT: Use this skill automatically after making code changes that affect:**
+
+- Visual components (React components, Vue components, UI elements)
+- Library functions (exported functions, utility methods, business logic)
+- Any other code that impacts application functionality
+
+**You should invoke this skill:**
+
+- After completing a set of code changes
+- Before presenting your work to the user
+- When you want to demonstrate the impact of your changes
+
+**DO NOT use this skill for:**
+
+- Documentation-only changes
+- Type definition changes that don't affect runtime behavior
+- Configuration file updates (unless they affect component behavior)
+
+## Important: Permissions Already Configured
+
+The `codeyam init` command has already auto-approved:
+
+- ✅ All CodeYam CLI commands (including `codeyam verify`)
+- ✅ All CodeYam skills
+- ✅ All file operations in the `.codeyam/` directory
+
+You can freely use the verify command without asking for permission.
+
+## Workflow: Verifying Your Changes
+
+When you're ready to present your changes to the user, follow this workflow:
+
+### Step 1: Run the Verify Command
+
+Execute the verify command to detect changed entities and launch the dashboard:
+
+```bash
+codeyam verify
+```
+
+**Optional: Provide Business Logic Context**
+
+If you made business logic changes that require specific data to demonstrate, use the `--context` and `--scenario-count` flags:
+
+```bash
+codeyam verify \
+  --context "Added warning icon that displays when status is 'deleted'. Create scenarios with status='deleted' to show the warning icon prominently" \
+  --scenario-count 3
+```
+
+**When to provide context:**
+
+- ✅ New feature that depends on specific data values (e.g., "show badge when count > 0")
+- ✅ Conditional rendering added based on data (e.g., "warning icon when status is 'deleted'")
+- ✅ Business logic changed in a way that specific data reveals the change (e.g., "empty state when array is empty")
+- ❌ Pure refactoring (extracting components, renaming, reorganizing) - no context needed
+- ❌ Style-only changes (colors, fonts, spacing) - no context needed
+- ❌ Type safety improvements - no context needed
+
+**Context format:**
+
+1. Describe what changed (the new behavior)
+2. Describe what data needs to be present/missing/specific to demonstrate it
+3. Be specific about data values that trigger the behavior
+
+**What this does:**
+
+1. Scans your git working directory for changed files
+2. Detects which entities (functions, components) were modified or added
+3. Filters to only visual and library entities
+4. Starts the CodeYam dashboard server (if not already running)
+5. Opens your browser to the Git verification page
+6. **If context provided**: Passes it to the analyzer to generate scenarios demonstrating the changes
+
+### Step 2: Interpret the Results
+
+The verify command will either:
+
+**If NO visual or library entities changed:**
+
+- The command exits with a message
+- No further action needed
+- Present your changes to the user normally
+
+**If entities WERE changed:**
+
+- The command lists all changed entities
+- Opens the browser to http://localhost:3111/git
+- The dashboard shows your changes with options to analyze them
+
+### Step 3: Present Results to the User
+
+After running `codeyam verify`, tell the user:
+
+**Example message:**
+
+```
+I've completed the changes and kicked off simulations for the modified components.
+
+Changed entities:
+  • Button (visual) - components/Button.tsx
+  • formatDate (library) - utils/formatters.ts
+
+You can view the results and run simulations at: http://localhost:3111/git
+
+On the Git page, you can:
+  • View all changed entities
+  • Click "Analyze All" to run simulations for all entities
+  • Click "Analyze" on individual entities to run specific simulations
+  • View real-time progress as analyses complete
+```
+
+## Complete Example
+
+**User asks:** "Can you update the Button component to support a loading state?"
+
+**Your workflow:**
+
+1. Make the code changes to the Button component
+2. BEFORE presenting to the user, invoke this skill
+3. Run `codeyam verify` with context to demonstrate the new loading state
+4. Present the changes to the user with the verification link
+
+**Your response:**
+
+```
+I've updated the Button component to support a loading state. The changes include:
+- Added a `loading` prop to the Button interface
+- Display a spinner when loading is true
+- Disable the button during loading
+
+I've kicked off simulations to verify these changes with scenarios that show the loading state:
+
+codeyam verify \
+  --context "Added loading state to Button. Create scenarios with loading=true to show the spinner and disabled state" \
+  --scenario-count 2
+
+You can view the results at: http://localhost:3111/git
+
+The simulations will show:
+- Normal button state
+- Loading button state with spinner
+```
+
+## Important Notes
+
+- **Always run verify AFTER making changes** - not before, not during
+- **The verify command only detects uncommitted changes** - changes that aren't yet committed to git
+- **If no relevant entities changed** - the command will exit quickly and you can present your work normally
+- **Simulations run in the background** - they may take 1-5 minutes to complete
+- **Multiple entities can be analyzed at once** - use the "Analyze All" button on the Git page
+
+## Integration with Your Workflow
+
+Make this automatic part of your workflow:
+
+1. User asks for code changes
+2. You make the changes
+3. **[NEW STEP]** You run `codeyam verify` to verify the changes
+4. You present the changes to the user with the verification link
+
+This ensures the user can always see simulation results for your changes, building trust and providing visual confirmation that the changes work as expected.