agileflow 3.4.2 → 4.0.0-alpha.1

package/lib/worktree-operations.js

@@ -1,201 +0,0 @@
-/**
- * worktree-operations.js - Git worktree creation and management
- *
- * Provides worktree creation with timeout, cleanup, and thread type detection.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync, spawn } = require('child_process');
-
-const { getProjectRoot } = require('./paths');
-
-const ROOT = getProjectRoot();
-
-// Thread type enum values
-const THREAD_TYPES = ['base', 'parallel', 'chained', 'fusion', 'big', 'long'];
-
-// Default worktree timeout (2 minutes)
-const DEFAULT_WORKTREE_TIMEOUT_MS = 120000;
-
-/**
- * Check if a directory is a git worktree (not the main repo).
- * In a worktree, .git is a file pointing to the main repo's .git/worktrees/<name>
- * In the main repo, .git is a directory.
- *
- * @param {string} dir - Directory to check
- * @returns {boolean} True if dir is a git worktree
- */
-function isGitWorktree(dir) {
-  const gitPath = path.join(dir, '.git');
-  try {
-    const stat = fs.lstatSync(gitPath);
-    // In a worktree, .git is a file containing "gitdir: /path/to/main/.git/worktrees/<name>"
-    // In the main repo, .git is a directory
-    return stat.isFile();
-  } catch (e) {
-    // .git doesn't exist - not a git repo at all
-    return false;
-  }
-}
-
-/**
- * Auto-detect thread type from context
- * @param {Object} session - Session object
- * @param {boolean} [isWorktree=false] - Whether this is a worktree
- * @returns {string} Thread type
- */
-function detectThreadType(session, isWorktree = false) {
-  // Worktree sessions are parallel threads
-  if (isWorktree || (session && !session.is_main)) {
-    return 'parallel';
-  }
-  // Default to base
-  return 'base';
-}
-
-/**
- * Display progress feedback during long operations.
- * Returns a function to stop the progress indicator.
- * Uses stderr to avoid corrupting stdout JSON output from callers.
- *
- * @param {string} message - Progress message
- * @returns {function} Stop function
- */
-function progressIndicator(message) {
-  const { FeedbackSpinner } = require('./feedback');
-  const spinner = new FeedbackSpinner(message, { stream: process.stderr });
-  spinner.start();
-  return () => spinner.succeed();
-}
-
-/**
- * Create a git worktree with timeout and progress feedback.
- * Uses async spawn instead of spawnSync for timeout support.
- *
- * @param {string} worktreePath - Path for the new worktree
- * @param {string} branchName - Branch name for the worktree
- * @param {number} timeoutMs - Timeout in milliseconds
- * @returns {Promise<{stdout: string, stderr: string}>}
- */
-function createWorktreeWithTimeout(
-  worktreePath,
-  branchName,
-  timeoutMs = DEFAULT_WORKTREE_TIMEOUT_MS
-) {
-  return new Promise((resolve, reject) => {
-    let stdout = '';
-    let stderr = '';
-    let timedOut = false;
-
-    const proc = spawn('git', ['worktree', 'add', worktreePath, branchName], {
-      cwd: ROOT,
-    });
-
-    const timer = setTimeout(() => {
-      timedOut = true;
-      proc.kill('SIGTERM');
-      // Give it a moment to terminate gracefully, then SIGKILL
-      setTimeout(() => {
-        try {
-          proc.kill('SIGKILL');
-        } catch (e) {
-          // Process may have already exited
-        }
-      }, 1000);
-    }, timeoutMs);
-
-    proc.stdout.on('data', data => {
-      stdout += data.toString();
-    });
-
-    proc.stderr.on('data', data => {
-      stderr += data.toString();
-    });
-
-    proc.on('error', err => {
-      clearTimeout(timer);
-      reject(new Error(`Failed to spawn git: ${err.message}`));
-    });
-
-    proc.on('close', (code, signal) => {
-      clearTimeout(timer);
-
-      if (timedOut) {
-        reject(
-          new Error(
-            `Worktree creation timed out after ${timeoutMs / 1000}s. Try increasing timeout or check disk space.`
-          )
-        );
-        return;
-      }
-
-      if (signal) {
-        reject(new Error(`Worktree creation was terminated by signal: ${signal}`));
-        return;
-      }
-
-      if (code === 0) {
-        resolve({ stdout, stderr });
-      } else {
-        reject(new Error(`Failed to create worktree: ${stderr || 'unknown error'}`));
-      }
-    });
-  });
-}
-
-/**
- * Clean up partial state after failed worktree creation.
- * Removes partial directory and prunes git worktree registry.
- *
- * @param {string} worktreePath - Path of the failed worktree
- * @param {string} branchName - Branch name that was being used
- * @param {boolean} branchCreatedByUs - Whether we created the branch
- */
-function cleanupFailedWorktree(worktreePath, branchName, branchCreatedByUs = false) {
-  // Remove partial worktree directory if it exists
-  if (fs.existsSync(worktreePath)) {
-    try {
-      fs.rmSync(worktreePath, { recursive: true, force: true });
-      process.stderr.write(`🧹 Cleaned up partial worktree directory\n`);
-    } catch (e) {
-      process.stderr.write(`⚠️  Could not remove partial directory: ${e.message}\n`);
-    }
-  }
-
-  // Prune git worktree registry to clean up any references
-  try {
-    spawnSync('git', ['worktree', 'prune'], { cwd: ROOT, encoding: 'utf8' });
-  } catch (e) {
-    // Non-fatal
-  }
-
-  // If we created the branch and the worktree failed, optionally clean up the branch too
-  if (branchCreatedByUs) {
-    try {
-      const result = spawnSync('git', ['branch', '-d', branchName], {
-        cwd: ROOT,
-        encoding: 'utf8',
-      });
-      if (result.status === 0) {
-        process.stderr.write(`🧹 Cleaned up unused branch: ${branchName}\n`);
-      }
-    } catch (e) {
-      // Non-fatal - branch may have commits or not exist
-    }
-  }
-}
-
-module.exports = {
-  // Constants
-  THREAD_TYPES,
-  DEFAULT_WORKTREE_TIMEOUT_MS,
-  // Detection
-  isGitWorktree,
-  detectThreadType,
-  // Progress indicator
-  progressIndicator,
-  // Worktree management
-  createWorktreeWithTimeout,
-  cleanupFailedWorktree,
-};

package/lib/yaml-utils.js

@@ -1,164 +0,0 @@
-/**
- * Centralized YAML parsing utilities with security guarantees.
- *
- * Security Note (js-yaml v4.x):
- * - yaml.load() is SAFE by default in v4+ (unlike v3.x)
- * - Dangerous JavaScript types (functions, regexps) are NOT supported
- * - Only JSON-compatible types are parsed
- * - See: https://github.com/nodeca/js-yaml/blob/master/migrate_v3_to_v4.md
- *
- * This wrapper provides:
- * - Explicit security documentation
- * - Input validation
- * - Consistent error handling
- * - Future-proofing for library changes
- * - Lazy loading: js-yaml is only loaded when YAML parsing is actually needed,
- *   so scripts that import paths.js but never parse YAML won't crash if
- *   js-yaml isn't installed in the user's project.
- */
-
-const path = require('path');
-
-// Lazy-loaded js-yaml instance (resolved on first use)
-let _yaml = null;
-
-/**
- * Resolve and load js-yaml from multiple locations.
- * Called lazily on first actual YAML operation.
- * @returns {Object} The js-yaml module
- * @throws {Error} If js-yaml cannot be found anywhere
- */
-function getYaml() {
-  if (_yaml) return _yaml;
-
-  // Resolve js-yaml from multiple locations:
-  // 1. User's project node_modules (may not exist)
-  // 2. AgileFlow npm package node_modules (always available when run via npx)
-  // 3. Parent of .agileflow directory
-  const tryPaths = [
-    'js-yaml', // Standard require (user's node_modules or global)
-    path.join(__dirname, '..', 'node_modules', 'js-yaml'), // AgileFlow package
-    path.join(__dirname, '..', '..', 'node_modules', 'js-yaml'), // .agileflow/../node_modules
-  ];
-
-  for (const tryPath of tryPaths) {
-    try {
-      _yaml = require(tryPath);
-      return _yaml;
-    } catch (_e) {
-      // Continue to next path
-    }
-  }
-
-  throw new Error(
-    'js-yaml not found. Please run: npm install js-yaml\n' +
-      'Or reinstall AgileFlow: npx agileflow setup --force'
-  );
-}
-
-/**
- * Safely parse YAML content. Uses js-yaml's DEFAULT_SCHEMA which is
- * safe by default in v4+ (does not execute arbitrary JavaScript).
- *
- * @param {string} content - YAML string to parse
- * @param {Object} options - Optional yaml.load options
- * @returns {any} Parsed YAML content (object, array, or primitive)
- * @throws {yaml.YAMLException} If YAML is malformed
- */
-function safeLoad(content, options = {}) {
-  if (typeof content !== 'string') {
-    throw new TypeError('YAML content must be a string');
-  }
-
-  const yaml = getYaml();
-  // In js-yaml v4+, load() uses DEFAULT_SCHEMA which is safe.
-  // Explicitly pass schema to make the security guarantee clear
-  // and protect against future library changes.
-  return yaml.load(content, {
-    schema: yaml.DEFAULT_SCHEMA,
-    ...options,
-  });
-}
-
-/**
- * Safely parse all YAML documents in a multi-document file.
- *
- * @param {string} content - YAML string containing one or more documents
- * @param {Object} options - Optional yaml.loadAll options
- * @returns {any[]} Array of parsed YAML documents
- * @throws {yaml.YAMLException} If YAML is malformed
- */
-function safeLoadAll(content, options = {}) {
-  if (typeof content !== 'string') {
-    throw new TypeError('YAML content must be a string');
-  }
-
-  const yaml = getYaml();
-  const documents = [];
-  yaml.loadAll(content, doc => documents.push(doc), { schema: yaml.DEFAULT_SCHEMA, ...options });
-  return documents;
-}
-
-/**
- * Safely serialize data to YAML string.
- *
- * @param {any} data - Data to serialize
- * @param {Object} options - Optional yaml.dump options
- * @returns {string} YAML string representation
- */
-function safeDump(data, options = {}) {
-  const yaml = getYaml();
-  return yaml.dump(data, {
-    schema: yaml.DEFAULT_SCHEMA,
-    ...options,
-  });
-}
-
-/**
- * Test if js-yaml is configured securely (no JavaScript type support).
- * This function is used in security tests to verify the library version
- * and configuration.
- *
- * @returns {boolean} True if the configuration is secure
- */
-function isSecureConfiguration() {
-  // Attempt to parse YAML with JavaScript function syntax
-  // This should NOT execute any code in v4+
-  const maliciousYaml = `
-test: !!js/function 'function() { return "pwned"; }'
-regex: !!js/regexp /test/i
-undef: !!js/undefined ''
-`;
-
-  try {
-    const result = safeLoad(maliciousYaml);
-    // If we get here without executing code, and the values are
-    // either strings or undefined (not actual functions), we're safe
-    if (typeof result.test === 'function') {
-      return false; // Unsafe: function was instantiated
-    }
-    if (result.regex instanceof RegExp) {
-      return false; // Unsafe: regex was instantiated
-    }
-    // Values should be undefined or error out due to unknown tags
-    return true;
-  } catch (e) {
-    // YAMLException for unknown tags is the expected safe behavior
-    if (e.name === 'YAMLException') {
-      return true;
-    }
-    throw e;
-  }
-}
-
-// Use a getter for the yaml export so tests can access the raw module
-// without triggering eager loading at require() time
-Object.defineProperty(module.exports, 'yaml', {
-  get: () => getYaml(),
-  enumerable: true,
-});
-
-module.exports.safeLoad = safeLoad;
-module.exports.safeLoadAll = safeLoadAll;
-module.exports.safeDump = safeDump;
-module.exports.isSecureConfiguration = isSecureConfiguration;

package/scripts/README.md

@@ -1,267 +0,0 @@
-# AgileFlow Release Scripts
-
-Automated scripts to streamline the release process and reduce cognitive strain.
-
-## 📦 Release Script
-
-**Purpose**: Automate the entire release process from version bump to npm publish.
-
-**Usage**:
-```bash
-./scripts/release.sh <version> <release-title>
-```
-
-**Example**:
-```bash
-./scripts/release.sh 2.32.0 "Dynamic Content Injection System"
-```
-
-**What it does**:
-1. ✅ Bumps version in `packages/cli/package.json`
-2. ✅ Bumps version in root `package.json`
-3. ⏸️ Prompts you to update `CHANGELOG.md` manually (then press ENTER)
-4. ✅ Commits changes with conventional commit message
-5. ✅ Pushes to GitHub
-6. ✅ Creates and pushes git tag `vX.Y.Z`
-7. ✅ Extracts changelog notes for this version
-8. ✅ Creates GitHub release with extracted notes
-9. ✅ GitHub Actions automatically publishes to npm
-
-**Benefits**:
-- No manual steps to remember
-- Consistent release process every time
-- Automatic changelog extraction
-- Automatic tag creation
-- Zero chance of forgetting to push the tag
-
-## 🎯 Quick Release Flow
-
-For a typical release:
-
-```bash
-# 1. Make your changes
-git add -A
-git commit -m "feat: add new feature"
-git push origin main
-
-# 2. Update CHANGELOG.md with new [X.Y.Z] section
-
-# 3. Run release script
-./scripts/release.sh 2.32.0 "New Feature Name"
-
-# 4. Wait for GitHub Actions to publish to npm
-# (Check: https://github.com/projectquestorg/AgileFlow/actions)
-
-# 5. Verify publish
-npm view agileflow version
-```
-
-## 🔧 Troubleshooting
-
-**If GitHub Actions fails**:
-- Check that `NPM_TOKEN` secret is configured: https://github.com/projectquestorg/AgileFlow/settings/secrets/actions
-- Check workflow run logs: https://github.com/projectquestorg/AgileFlow/actions
-
-**If tag already exists**:
-```bash
-# Delete local and remote tag
-git tag -d v2.32.0
-git push origin :refs/tags/v2.32.0
-
-# Re-run release script
-./scripts/release.sh 2.32.0 "Feature Name"
-```
-
-**Manual publish** (if GitHub Actions fails):
-```bash
-cd packages/cli
-npm publish --access public
-```
-
-## 🔍 Environment Info Script
-
-**Purpose**: Output project environment information for hooks and automation.
-
-**File**: `scripts/get-env.js`
-
-**Usage**:
-```bash
-# Human-readable format
-node scripts/get-env.js
-
-# JSON format
-node scripts/get-env.js --json
-```
-
-**Output**:
-- Project name, version, description
-- Git branch and commit hash
-- Node.js version
-- Platform and architecture
-- Current user and hostname
-- Timestamp
-
-**Example output** (human-readable):
-```
-Project: agileflow v2.35.0
-Description: AI-driven agile development system for Claude Code, Cursor, Windsurf, and more
-Root Directory: /home/coder/AgileFlow
-Git Branch: main
-Git Commit: 45bb0da
-Node Version: v18.20.8
-Platform: linux (x64)
-User: coder@ProjectQuest
-Timestamp: 2025-12-15T20:31:44.742Z
-```
-
-**Example output** (JSON):
-```json
-{
-  "project": {
-    "name": "agileflow",
-    "version": "2.35.0",
-    "description": "AI-driven agile development system...",
-    "rootDir": "/home/coder/AgileFlow"
-  },
-  "git": {
-    "branch": "main",
-    "commit": "45bb0da"
-  },
-  "system": {
-    "node": "v18.20.8",
-    "platform": "linux",
-    "arch": "x64",
-    "hostname": "ProjectQuest",
-    "user": "coder"
-  },
-  "timestamp": "2025-12-15T20:31:44.742Z"
-}
-```
-
-**Use Cases**:
-- Session start hook (display project info)
-- CI/CD environment validation
-- Debugging environment issues
-- Logging and audit trails
-- Integration with external tools
-
-## 📁 Auto-Archival Scripts
-
-**Purpose**: Automatically manage `status.json` file size by archiving old completed stories.
-
-### Archive Completed Stories
-
-**File**: `scripts/archive-completed-stories.sh`
-
-**Usage**:
-```bash
-bash scripts/archive-completed-stories.sh
-```
-
-**What it does**:
-1. Reads `docs/09-agents/status.json`
-2. Identifies stories with `status: "completed"` older than threshold (default: 7 days)
-3. Moves them to `docs/09-agents/archive/YYYY-MM.json` (organized by completion month)
-4. Removes archived stories from `status.json`
-5. Logs what was archived
-
-**Configuration**:
-Edit `docs/00-meta/agileflow-metadata.json`:
-```json
-{
-  "archival": {
-    "threshold_days": 7,
-    "enabled": true
-  }
-}
-```
-
-**Automation**:
-- Runs automatically on each session start via `.claude/settings.json` hook
-- Runs in background (non-blocking)
-- Idempotent (safe to run multiple times)
-
-**Example output**:
-```
-Starting auto-archival (threshold: 7 days)...
-Cutoff date: 2025-12-08T20:41:15.000Z
-✓ Archived 3 stories to 2025-11.json
-✓ Removed 3 archived stories from status.json
-Stories remaining: 5
-Auto-archival complete!
-```
-
-### Compress Status
-
-**File**: `scripts/compress-status.sh`
-
-**Usage**:
-```bash
-bash scripts/compress-status.sh
-```
-
-**What it does**:
-1. Reads `docs/09-agents/status.json`
-2. Removes verbose fields from each story (descriptions, notes, acceptance criteria, etc.)
-3. Keeps only essential tracking metadata:
-   - `id`, `title`, `status`, `owner`
-   - `created_at`, `updated_at`, `completed_at`
-   - `epic`, `dependencies`, `blocked_by`, `blocks`
-   - `pr_url`, `test_status`, `priority`, `tags`
-4. Updates `status.json` with compressed version
-5. Reports size savings
-
-**When to use**:
-- When `status.json` grows too large
-- Before committing to git
-- As part of cleanup workflow
-- Manually when needed (not automated)
-
-**Example output**:
-```
-Compressing status.json...
-✓ Removed 15 verbose fields
-Stories processed: 8
-Compression complete!
-Original size: 12543 bytes
-New size: 4821 bytes
-Saved: 7722 bytes (61%)
-```
-
-### Archive Directory Structure
-
-```
-docs/09-agents/
-├── status.json              # Active stories only
-├── archive/
-│   ├── 2025-11.json        # Stories completed in Nov 2025
-│   ├── 2025-12.json        # Stories completed in Dec 2025
-│   └── ...
-└── bus/
-    └── log.jsonl
-```
-
-**Archive file format**:
-```json
-{
-  "month": "2025-11",
-  "archived_at": "2025-12-15T20:41:15.983Z",
-  "stories": {
-    "US-001": {
-      "id": "US-001",
-      "title": "Old completed story",
-      "status": "completed",
-      "completed_at": "2025-11-05T15:00:00.000Z",
-      ...
-    }
-  }
-}
-```
-
-**Benefits**:
-- Keeps `status.json` small and fast to process
-- Preserves historical data in organized archives
-- No manual intervention required
-- Easy to retrieve archived stories by month
-- Reduces git diff noise
-- Faster parsing for slash commands

package/scripts/af

@@ -1,34 +0,0 @@
-#!/bin/bash
-# af - Short alias for Claude Code with tmux integration
-#
-# This is a convenience wrapper that:
-# 1. Auto-starts Claude in a tmux session (for parallel sessions support)
-# 2. Attaches to existing session if one exists for this directory
-# 3. Falls back to regular claude if tmux isn't available
-#
-# Usage:
-#   af              # Start Claude in tmux
-#   af --no-tmux    # Start without tmux
-#   af -h           # Show help
-#
-# To install globally:
-#   sudo ln -s $(pwd)/.agileflow/scripts/af /usr/local/bin/af
-#   # Or add to your PATH
-
-set -e
-
-# Get the directory where this script is located
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Check if claude-tmux.sh exists in the same directory
-if [ -f "$SCRIPT_DIR/claude-tmux.sh" ]; then
-  exec "$SCRIPT_DIR/claude-tmux.sh" "$@"
-fi
-
-# Fallback: try to find claude-tmux.sh in .agileflow/scripts
-if [ -f ".agileflow/scripts/claude-tmux.sh" ]; then
-  exec ".agileflow/scripts/claude-tmux.sh" "$@"
-fi
-
-# Last resort: just run claude directly
-exec claude "$@"