agileflow 2.91.0 → 2.92.0

package/scripts/pre-push-check.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Pre-push validation script
+# Run before pushing to catch CI failures locally
+# Usage: npm run check        (quick: lint + tests only, ~30s)
+#        npm run check:full   (full: lint + tests + docs build, ~5m)
+
+set -e
+
+echo "🔍 Running pre-push checks..."
+echo ""
+
+# Track start time
+START_TIME=$(date +%s)
+
+# 1. Lint check (fastest, catches most issues)
+echo "📋 Step 1/2: Linting..."
+cd packages/cli
+npm run lint 2>&1 | tail -30 || {
+    echo "❌ Lint failed! Fix errors before pushing."
+    exit 1
+}
+cd ../..
+echo "✅ Lint passed"
+echo ""
+
+# 2. Run tests (catches logic errors)
+echo "🧪 Step 2/2: Running tests..."
+cd packages/cli
+npm test 2>&1 | tail -20 || {
+    echo "❌ Tests failed! Fix errors before pushing."
+    exit 1
+}
+cd ../..
+echo "✅ Tests passed"
+echo ""
+
+# Calculate elapsed time
+END_TIME=$(date +%s)
+ELAPSED=$((END_TIME - START_TIME))
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ Pre-push checks passed! (${ELAPSED}s)"
+echo "   Safe to push."
+echo ""
+echo "💡 Tip: Run 'npm run check:full' to include docs build"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

package/scripts/precompact-context.sh

@@ -74,16 +74,29 @@ if [ -f "docs/09-agents/session-state.json" ]; then
     fi
 
     if [ ! -z "$COMMAND_FILE" ]; then
-      SUMMARY=$(node -e "
-        const fs = require('fs');
-        const content = fs.readFileSync('$COMMAND_FILE', 'utf8');
-        const match = content.match(/<!-- COMPACT_SUMMARY_START[\\s\\S]*?-->([\\s\\S]*?)<!-- COMPACT_SUMMARY_END -->/);
-        if (match) {
-          console.log('## ACTIVE COMMAND: /agileflow:${ACTIVE_COMMAND}');
-          console.log('');
-          console.log(match[1].trim());
-        }
-      " 2>/dev/null || echo "")
+      # Security: Validate COMMAND_FILE contains only safe characters (alphanumeric, /, -, _, .)
+      # and doesn't contain path traversal sequences
+      if [[ "$COMMAND_FILE" =~ ^[a-zA-Z0-9/_.-]+$ ]] && [[ ! "$COMMAND_FILE" =~ \.\. ]]; then
+        SUMMARY=$(COMMAND_FILE_PATH="$COMMAND_FILE" ACTIVE_CMD="$ACTIVE_COMMAND" node -e "
+          const fs = require('fs');
+          const filePath = process.env.COMMAND_FILE_PATH;
+          const activeCmd = process.env.ACTIVE_CMD;
+          // Double-check: only allow paths within expected directories
+          const allowedPrefixes = ['packages/cli/src/core/commands/', '.agileflow/commands/', '.claude/commands/agileflow/'];
+          if (!allowedPrefixes.some(p => filePath.startsWith(p))) {
+            process.exit(1);
+          }
+          try {
+            const content = fs.readFileSync(filePath, 'utf8');
+            const match = content.match(/<!-- COMPACT_SUMMARY_START[\\s\\S]*?-->([\\s\\S]*?)<!-- COMPACT_SUMMARY_END -->/);
+            if (match) {
+              console.log('## ACTIVE COMMAND: /agileflow:' + activeCmd);
+              console.log('');
+              console.log(match[1].trim());
+            }
+          } catch (e) {}
+        " 2>/dev/null || echo "")
+      fi
 
       if [ ! -z "$SUMMARY" ]; then
         COMMAND_SUMMARIES="${COMMAND_SUMMARIES}

package/scripts/query-codebase.js

@@ -21,6 +21,7 @@
  *   --budget=<chars>   Token budget for output (default: 15000)
  *   --json             Output as JSON
  *   --verbose          Show debug info
+ *   --explain          Show equivalent bash workflow (ls/find/grep/cat)
  *
  * Exit codes:
  *   0 = Success
@@ -56,6 +57,7 @@ function parseArgs(argv) {
     budget: DEFAULT_BUDGET,
     json: false,
     verbose: false,
+    explain: false, // Show equivalent bash workflow
   };
 
   for (const arg of argv.slice(2)) {
@@ -65,6 +67,8 @@ function parseArgs(argv) {
       args.json = true;
     } else if (arg === '--verbose') {
       args.verbose = true;
+    } else if (arg === '--explain') {
+      args.explain = true;
     } else if (arg.startsWith('--query=')) {
       args.query = arg.slice(8);
     } else if (arg.startsWith('--deps=')) {
@@ -85,6 +89,73 @@ function parseArgs(argv) {
   return args;
 }
 
+// Generate bash workflow explanation (research: ls → find → grep → cat pattern)
+function explainWorkflow(queryType, queryValue, projectRoot) {
+  const lines = ['', '📖 Equivalent Bash Workflow:', ''];
+
+  switch (queryType) {
+    case 'query':
+      lines.push('# Step 1: List available directories (ls)');
+      lines.push(`ls -la ${projectRoot}/src/`);
+      lines.push('');
+      lines.push('# Step 2: Find files matching pattern (find)');
+      lines.push(`find ${projectRoot} -name "*${queryValue}*" -type f`);
+      lines.push('');
+      lines.push('# Step 3: Search content within files (grep)');
+      lines.push(`grep -rl "${queryValue}" ${projectRoot}/src/`);
+      lines.push('');
+      lines.push('# This tool combines all three with indexing for speed.');
+      break;
+
+    case 'content':
+      lines.push('# Equivalent to grep with context:');
+      lines.push(`grep -rn "${queryValue}" ${projectRoot}/src/ --include="*.{js,ts,tsx}"`);
+      lines.push('');
+      lines.push('# This tool adds: index awareness, budget truncation, structured output.');
+      break;
+
+    case 'tag':
+      const tagPatterns = {
+        api: '/api/|/routes/|/controllers/',
+        ui: '/components/|/views/|/pages/',
+        auth: '/auth/|/login/|/jwt/',
+        database: '/db/|/models/|/migrations/',
+        test: '/test/|/__tests__/|/spec/',
+      };
+      lines.push('# Equivalent to find with path patterns:');
+      lines.push(`find ${projectRoot} -type f | grep -E "${tagPatterns[queryValue] || queryValue}"`);
+      lines.push('');
+      lines.push('# This tool uses pre-indexed tags for instant lookup.');
+      break;
+
+    case 'export':
+      lines.push('# Equivalent to grep for export statements:');
+      lines.push(`grep -rn "export.*${queryValue}" ${projectRoot}/src/ --include="*.{js,ts,tsx}"`);
+      lines.push('');
+      lines.push('# This tool tracks exports in index for instant symbol lookup.');
+      break;
+
+    case 'deps':
+      lines.push('# Equivalent to grep for imports:');
+      lines.push(`grep -n "import.*from" ${queryValue}`);
+      lines.push('');
+      lines.push('# Plus reverse search for files importing this one:');
+      lines.push(`grep -rl "${path.basename(queryValue, path.extname(queryValue))}" ${projectRoot}/src/`);
+      lines.push('');
+      lines.push('# This tool tracks bidirectional dependencies in index.');
+      break;
+
+    default:
+      lines.push('# Generic file system exploration:');
+      lines.push(`ls -la ${projectRoot}/`);
+      lines.push(`find ${projectRoot} -type f -name "*.ts" | head -20`);
+  }
+
+  lines.push('');
+  lines.push('─'.repeat(50));
+  return lines.join('\n');
+}
+
 // Search file content using grep-style regex
 function queryContent(projectRoot, pattern, budget) {
   const results = [];
@@ -135,7 +206,14 @@ function queryContent(projectRoot, pattern, budget) {
         if (totalChars + resultChars > budget) {
           results.push({
             file: '...',
-            matches: [{ line: 0, context: [{ lineNumber: 0, content: `[Truncated: budget exceeded]`, isMatch: false }] }],
+            matches: [
+              {
+                line: 0,
+                context: [
+                  { lineNumber: 0, content: `[Truncated: budget exceeded]`, isMatch: false },
+                ],
+              },
+            ],
           });
           break;
         }
@@ -258,14 +336,21 @@ async function main() {
 
     // Handle --query (glob pattern search)
     if (args.query) {
-      if (args.verbose) console.error(`Querying: ${args.query}`);
+      if (args.verbose) {
+        console.error(`\n🔍 Step 1: Querying for "${args.query}"`);
+        console.error(`   Project: ${args.project}`);
+      }
 
       // First try to get/update index
+      if (args.verbose) console.error(`📂 Step 2: Checking/updating index...`);
       const indexResult = updateIndex(args.project);
       if (!indexResult.ok) {
         console.error(`Error: ${indexResult.error}`);
         process.exit(1);
       }
+      if (args.verbose) {
+        console.error(`   Index has ${Object.keys(indexResult.data.files).length} files`);
+      }
 
       // Interpret query
       const query = args.query.toLowerCase();
@@ -273,29 +358,41 @@ async function main() {
 
       // If query looks like a glob, use it directly
       if (query.includes('*') || query.includes('/')) {
+        if (args.verbose) console.error(`🔎 Step 3: Glob pattern search: ${args.query}`);
         files = queryFiles(indexResult.data, args.query);
       } else {
         // Otherwise, search multiple ways:
+        if (args.verbose) console.error(`🔎 Step 3: Multi-strategy search...`);
+
         // 1. Files containing query in name
+        if (args.verbose) console.error(`   3a. Filename match: **/*${args.query}*`);
         files = queryFiles(indexResult.data, `**/*${args.query}*`);
+        if (args.verbose) console.error(`       Found ${files.length} files by name`);
 
         // 2. Files with matching tag
+        if (args.verbose) console.error(`   3b. Tag search: ${query}`);
         const tagFiles = queryByTag(indexResult.data, query);
+        if (args.verbose) console.error(`       Found ${tagFiles.length} files by tag`);
         files = [...new Set([...files, ...tagFiles])];
 
         // 3. Files exporting symbol
+        if (args.verbose) console.error(`   3c. Export search: ${args.query}`);
         const exportFiles = queryByExport(indexResult.data, args.query);
+        if (args.verbose) console.error(`       Found ${exportFiles.length} files by export`);
         files = [...new Set([...files, ...exportFiles])];
       }
+      if (args.verbose) console.error(`✅ Step 4: Total unique results: ${files.length}\n`);
 
       if (files.length === 0) {
         console.error(`No files found matching: ${args.query}`);
         process.exit(2);
       }
 
-      const output = args.json
-        ? JSON.stringify(files, null, 2)
-        : formatResults(files, 'files');
+      if (args.explain) {
+        console.log(explainWorkflow('query', args.query, args.project));
+      }
+
+      const output = args.json ? JSON.stringify(files, null, 2) : formatResults(files, 'files');
       console.log(truncateOutput(output, args.budget));
       process.exit(0);
     }
@@ -316,6 +413,10 @@ async function main() {
         process.exit(2);
       }
 
+      if (args.explain) {
+        console.log(explainWorkflow('content', args.content, args.project));
+      }
+
       const output = args.json
         ? JSON.stringify(result.data, null, 2)
         : formatResults(result.data, 'content');
@@ -340,9 +441,11 @@ async function main() {
         process.exit(2);
       }
 
-      const output = args.json
-        ? JSON.stringify(files, null, 2)
-        : formatResults(files, 'files');
+      if (args.explain) {
+        console.log(explainWorkflow('tag', args.tag, args.project));
+      }
+
+      const output = args.json ? JSON.stringify(files, null, 2) : formatResults(files, 'files');
       console.log(truncateOutput(output, args.budget));
       process.exit(0);
     }
@@ -364,9 +467,11 @@ async function main() {
         process.exit(2);
       }
 
-      const output = args.json
-        ? JSON.stringify(files, null, 2)
-        : formatResults(files, 'files');
+      if (args.explain) {
+        console.log(explainWorkflow('export', args.export, args.project));
+      }
+
+      const output = args.json ? JSON.stringify(files, null, 2) : formatResults(files, 'files');
       console.log(truncateOutput(output, args.budget));
       process.exit(0);
     }
@@ -388,9 +493,11 @@ async function main() {
         process.exit(2);
       }
 
-      const output = args.json
-        ? JSON.stringify(deps, null, 2)
-        : formatResults(deps, 'deps');
+      if (args.explain) {
+        console.log(explainWorkflow('deps', args.deps, args.project));
+      }
+
+      const output = args.json ? JSON.stringify(deps, null, 2) : formatResults(deps, 'deps');
       console.log(truncateOutput(output, args.budget));
       process.exit(0);
     }
@@ -411,6 +518,7 @@ Options:
   --budget=<chars>      Output budget in characters (default: 15000)
   --json                Output as JSON
   --verbose             Show debug info
+  --explain             Show equivalent bash workflow (ls/find/grep/cat)
 
 Exit codes:
   0 = Success

package/scripts/ralph-loop.js

@@ -34,33 +34,33 @@ const { execSync, spawnSync } = require('child_process');
 
 // Shared utilities
 const { c } = require('../lib/colors');
-const { getProjectRoot } = require('../lib/paths');
+const { getProjectRoot, getStatusPath, getSessionStatePath } = require('../lib/paths');
 const { safeReadJSON, safeWriteJSON } = require('../lib/errors');
 const { isValidEpicId, parseIntBounded } = require('../lib/validate');
 
 // Read session state
 function getSessionState(rootDir) {
-  const statePath = path.join(rootDir, 'docs/09-agents/session-state.json');
+  const statePath = getSessionStatePath(rootDir);
   const result = safeReadJSON(statePath, { defaultValue: {} });
   return result.ok ? result.data : {};
 }
 
 // Write session state
 function saveSessionState(rootDir, state) {
-  const statePath = path.join(rootDir, 'docs/09-agents/session-state.json');
+  const statePath = getSessionStatePath(rootDir);
   safeWriteJSON(statePath, state, { createDir: true });
 }
 
 // Read status.json for stories
 function getStatus(rootDir) {
-  const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
+  const statusPath = getStatusPath(rootDir);
   const result = safeReadJSON(statusPath, { defaultValue: { stories: {}, epics: {} } });
   return result.ok ? result.data : { stories: {}, epics: {} };
 }
 
 // Save status.json
 function saveStatus(rootDir, status) {
-  const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
+  const statusPath = getStatusPath(rootDir);
   safeWriteJSON(statusPath, status);
 }