awesome-slash 2.4.4 → 2.5.1

package/plugins/ship/lib/utils/deprecation.js

@@ -0,0 +1,37 @@
+/**
+ * Deprecation Warning Utility
+ * Centralized utility for handling deprecation warnings across the codebase
+ *
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+// Track which functions have already shown deprecation warnings (once per function)
+const _deprecationWarned = new Set();
+
+/**
+ * Show deprecation warning for sync functions (once per function name)
+ * @param {string} funcName - Name of the deprecated sync function
+ * @param {string} asyncAlt - Name of the async alternative
+ */
+function warnDeprecation(funcName, asyncAlt) {
+  if (_deprecationWarned.has(funcName)) return;
+  _deprecationWarned.add(funcName);
+  console.warn(
+    `DEPRECATED: ${funcName}() is synchronous and blocks the event loop. ` +
+    `Use ${asyncAlt}() instead. Will be removed in v3.0.0.`
+  );
+}
+
+/**
+ * Reset deprecation warnings (for testing only)
+ * @private
+ */
+function _resetDeprecationWarnings() {
+  _deprecationWarned.clear();
+}
+
+module.exports = {
+  warnDeprecation,
+  _resetDeprecationWarnings
+};

package/plugins/ship/lib/utils/shell-escape.js

@@ -0,0 +1,88 @@
+/**
+ * Shell Escaping Utilities
+ * Centralized string escaping functions for safe shell command construction
+ *
+ * @module lib/utils/shell-escape
+ * @author Avi Fenesh
+ * @license MIT
+ */
+
+/**
+ * Escape shell special characters for safe command interpolation
+ * Handles all dangerous shell metacharacters including command injection vectors
+ * Optimized: uses single regex test instead of multiple .includes() calls
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for shell use
+ * @throws {Error} If string contains null bytes or newlines
+ */
+function escapeShell(str) {
+  if (typeof str !== 'string') return '';
+
+  // Reject null bytes and newlines which could be used for injection
+  // Optimized: single regex test instead of 3 separate .includes() scans
+  // Use \x00 instead of \0 for better portability across JS engines
+  if (/[\x00\n\r]/.test(str)) {
+    throw new Error('Input contains invalid characters (null bytes or newlines)');
+  }
+
+  // Escape all shell metacharacters: " $ ` \ ! ; | & > < ( ) { } [ ] * ? ~ # ' space tab
+  return str.replace(/["\$`\\!;|&><(){}[\]*?~#'\s]/g, '\\$&');
+}
+
+/**
+ * Escape single quotes for shell (replace ' with '\''
+ * Use this for strings that will be wrapped in single quotes
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for single-quoted shell use
+ */
+function escapeSingleQuotes(str) {
+  if (typeof str !== 'string') return '';
+  return str.replace(/'/g, "'\\''");
+}
+
+/**
+ * Validate and sanitize file extension
+ * Removes all non-alphanumeric characters
+ * @param {string} ext - Extension to validate
+ * @returns {string} Safe extension (alphanumeric only), defaults to 'ts' if empty
+ */
+function sanitizeExtension(ext) {
+  if (typeof ext !== 'string') return 'ts';
+  const safe = ext.replace(/[^a-zA-Z0-9]/g, '');
+  return safe || 'ts';
+}
+
+/**
+ * Escape a string for use in a double-quoted shell context
+ * More permissive than escapeShell but still safe
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for double-quoted shell use
+ */
+function escapeDoubleQuotes(str) {
+  if (typeof str !== 'string') return '';
+
+  // In double quotes, we need to escape: $ ` " \ and newlines
+  return str.replace(/[$`"\\\n]/g, '\\$&');
+}
+
+/**
+ * Quote a string for safe shell use
+ * Wraps in single quotes and escapes any embedded single quotes
+ * This is often safer than escapeShell for complex strings
+ * @param {string} str - String to quote
+ * @returns {string} Safely quoted string
+ */
+function quoteShell(str) {
+  if (typeof str !== 'string') return "''";
+
+  // Wrap in single quotes and escape any embedded single quotes
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
+module.exports = {
+  escapeShell,
+  escapeSingleQuotes,
+  sanitizeExtension,
+  escapeDoubleQuotes,
+  quoteShell
+};

package/scripts/install/codex.sh

@@ -4,8 +4,18 @@
 
 set -e
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# Detect plugin root - works whether run directly or via bash -c
+if [ -n "${BASH_SOURCE[0]}" ] && [ -f "${BASH_SOURCE[0]}" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+elif [ -f "scripts/install/codex.sh" ]; then
+  PLUGIN_ROOT="$(pwd)"
+elif [ -f "package.json" ] && grep -q "awesome-slash" package.json 2>/dev/null; then
+  PLUGIN_ROOT="$(pwd)"
+else
+  echo "Error: Cannot detect plugin root. Run from the awesome-slash directory."
+  exit 1
+fi
 
 echo "Installing awesome-slash for Codex CLI..."
 echo "Plugin root: $PLUGIN_ROOT"
@@ -22,22 +32,56 @@ echo "Installing MCP server dependencies..."
 cd "$PLUGIN_ROOT/mcp-server"
 npm install --production
 
-# Add MCP server using codex mcp add command
+# Configure MCP server in config.toml
 echo "Configuring MCP server..."
 
-# Remove existing awesome-slash MCP server if present
-codex mcp remove awesome-slash 2>/dev/null || true
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+CONFIG_FILE="$CODEX_HOME/config.toml"
+
+# Ensure config directory exists
+mkdir -p "$CODEX_HOME"
+
+# Create config file if it doesn't exist
+if [ ! -f "$CONFIG_FILE" ]; then
+  touch "$CONFIG_FILE"
+fi
+
+# Backup existing config
+cp "$CONFIG_FILE" "$CONFIG_FILE.backup"
 
-# Add the MCP server with environment variable
-codex mcp add awesome-slash \
-  --env "PLUGIN_ROOT=$PLUGIN_ROOT" \
-  -- node "$PLUGIN_ROOT/mcp-server/index.js"
+# Remove existing awesome-slash MCP server section if present
+if grep -q "\[mcp_servers.awesome-slash\]" "$CONFIG_FILE" 2>/dev/null; then
+  # Use sed to remove the section (from [mcp_servers.awesome-slash] to next section or EOF)
+  sed -i '/\[mcp_servers\.awesome-slash\]/,/^\[/{/^\[mcp_servers\.awesome-slash\]/d;/^\[/!d}' "$CONFIG_FILE"
+  # Clean up any trailing empty lines
+  sed -i '/^$/N;/^\n$/d' "$CONFIG_FILE"
+fi
+
+# Convert Git Bash path to Windows path for TOML
+# /c/Users/... -> C:/Users/...
+if [[ "$PLUGIN_ROOT" == /[a-z]/* ]]; then
+  DRIVE_LETTER=$(echo "$PLUGIN_ROOT" | cut -c2 | tr '[:lower:]' '[:upper:]')
+  PLUGIN_ROOT_WIN="${DRIVE_LETTER}:${PLUGIN_ROOT:2}"
+else
+  PLUGIN_ROOT_WIN="$PLUGIN_ROOT"
+fi
+MCP_SERVER_PATH="$PLUGIN_ROOT_WIN/mcp-server/index.js"
+
+# Append MCP server configuration
+cat >> "$CONFIG_FILE" << EOF
+
+[mcp_servers.awesome-slash]
+command = "node"
+args = ["$MCP_SERVER_PATH"]
+env = { PLUGIN_ROOT = "$PLUGIN_ROOT_WIN", AI_STATE_DIR = ".codex" }
+enabled = true
+EOF
 
-echo "MCP server configured."
+echo "MCP server configured in $CONFIG_FILE"
 
 # Create skills directory
-CODEX_CONFIG="${CODEX_CONFIG:-$HOME/.codex}"
-SKILLS_DIR="$CODEX_CONFIG/skills"
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+SKILLS_DIR="$CODEX_HOME/skills"
 
 echo "Installing Codex skills..."
 
@@ -46,35 +90,48 @@ mkdir -p "$SKILLS_DIR/next-task"
 cat > "$SKILLS_DIR/next-task/SKILL.md" << 'EOF'
 ---
 name: next-task
-description: Master workflow orchestrator for task-to-production automation. Use when users want to find their next task, prioritize work, start a new workflow, or ask "what should I work on". Integrates with GitHub Issues, Linear, and PLAN.md for task discovery.
+description: Master workflow orchestrator for task-to-production automation. Use this skill when users want to find their next task, prioritize work, start a new workflow, resume an interrupted workflow, or ask "what should I work on next". Integrates with GitHub Issues, Linear, and local task files for task discovery.
 ---
 
 # Next Task Workflow
 
 Find and implement the next priority task with full workflow automation.
 
-## Capabilities
+## CRITICAL: Always Ask User First
+
+**DO NOT auto-select options.** You MUST ask the user:
+
+1. First call `workflow_status` MCP tool to check for existing workflow
+2. If resumable, ASK: "Resume existing workflow or start fresh?"
+3. For new workflows, ASK user to choose:
+   - **Task Source**: GitHub Issues, GitLab, Local files, or Custom?
+   - **Priority Filter**: Bugs, Security, Features, or All?
+   - **Stopping Point**: PR created, Merged, or Deployed?
+
+## MCP Tools
 
-Use the awesome-slash MCP tools:
 - `workflow_status` - Check current workflow state
-- `workflow_start` - Start a new workflow
+- `workflow_start` - Start workflow (params: taskSource, priorityFilter, stoppingPoint)
 - `workflow_resume` - Resume from checkpoint
 - `workflow_abort` - Cancel and cleanup
-- `task_discover` - Find and prioritize tasks
+- `task_discover` - Find tasks (params: source, filter, limit)
 
-## Workflow
+## Task Sources (ask user)
 
-1. Check `workflow_status` for existing workflow
-2. If none exists, use `workflow_start` to begin
-3. Use `task_discover` to find priority tasks from configured source
-4. Guide through task selection and implementation
-5. Use `workflow_resume` if interrupted
+- `gh-issues` - GitHub Issues
+- `glab-issues` - GitLab Issues
+- `tasks-md` - Local TASKS.md/PLAN.md/TODO.md
+- `custom` - Custom file path
 
-## Task Sources
+## Stopping Points (ask user)
 
-- GitHub Issues (default)
-- Linear issues
-- PLAN.md file
+- `pr-created` - Stop after PR
+- `merged` - Stop after merge
+- `deployed` - Stop after deployment
+
+## State Directory
+
+State stored in `.codex/` (flow.json, tasks.json)
 EOF
 
 # Create ship skill
@@ -82,31 +139,44 @@ mkdir -p "$SKILLS_DIR/ship"
 cat > "$SKILLS_DIR/ship/SKILL.md" << 'EOF'
 ---
 name: ship
-description: Complete PR workflow from commit to production with validation. Use when users want to ship code, create a PR, merge changes, or deploy. Handles commit, PR creation, CI monitoring, review, merge, and deployment.
+description: Complete PR workflow from commit to production with validation. Use this skill when users want to ship code, create a pull request, merge changes, deploy to production, or finish their current work. Handles commit creation, PR creation, CI monitoring, code review, merge, and deployment validation.
 ---
 
 # Ship Workflow
 
 Complete PR workflow from commit to production.
 
-## Capabilities
+## MCP Tools Available
 
-Use the awesome-slash MCP tools:
 - `workflow_status` - Check current state
-- `review_code` - Run multi-agent review
-
-## Workflow
-
-1. Stage and commit changes with AI-generated message
-2. Create PR with context
-3. Run `review_code` for multi-agent review
-4. Monitor CI status
-5. Merge when approved
-6. Deploy if configured
-
-## Platforms
-
-Supports: GitHub Actions, GitLab CI, CircleCI, Railway, Vercel, Netlify, Fly.io
+- `review_code` - Run multi-agent code review
+
+## Workflow Instructions
+
+1. Check `workflow_status` for current state
+2. Stage and commit changes with a clear, descriptive message
+3. Create PR using `gh pr create` with context
+4. Run `review_code` MCP tool for multi-agent review
+5. Monitor CI status and fix any failures
+6. Merge when approved
+7. Validate deployment if configured
+
+## Supported Platforms
+
+**CI Platforms:**
+- GitHub Actions
+- GitLab CI
+- CircleCI
+- Jenkins
+- Travis CI
+
+**Deployment Platforms:**
+- Railway
+- Vercel
+- Netlify
+- Fly.io
+- Platform.sh
+- Render
 EOF
 
 # Create review skill
@@ -114,30 +184,43 @@ mkdir -p "$SKILLS_DIR/review"
 cat > "$SKILLS_DIR/review/SKILL.md" << 'EOF'
 ---
 name: review
-description: Run multi-agent code review on changes. Use when users want to review code, check code quality, or run code analysis before committing or creating a PR.
+description: Run multi-agent code review on changes. Use this skill when users want to review code, check code quality, run code analysis, find bugs, check for security issues, or validate changes before committing or creating a pull request.
 ---
 
 # Code Review
 
 Run multi-agent code review on changes.
 
-## Capabilities
+## How To Run
 
-Use the awesome-slash MCP tools:
-- `review_code` - Run multi-agent review
+**Step 1: Get files to review**
 
-## Review Agents
+If user provided files, use those. Otherwise get changed files:
+```bash
+git diff --name-only HEAD
+```
 
-- Code quality analysis
-- Silent failure detection
-- Test coverage analysis
-- Security review
+**Step 2: Call review_code MCP tool**
+```
+review_code({ files: ["src/file1.ts", "src/file2.ts"] })
+```
 
-## Usage
+## Review Checks
 
-Run `review_code` tool with the files to review.
-Auto-fixes critical and high severity issues.
-Reports medium and low severity for manual review.
+- Console debugging statements (console.log, print, dbg!)
+- TODO/FIXME comments
+- Commented-out code
+- Debugger statements
+- Empty catch blocks
+- TypeScript `any` types
+- Hardcoded secrets
+
+## Default Behavior
+
+If no files specified:
+1. Get changed files via `git diff --name-only HEAD`
+2. If no changes, ASK user: "Which files should I review?"
+3. Never review 0 files silently
 EOF
 
 # Create deslop skill
@@ -145,37 +228,98 @@ mkdir -p "$SKILLS_DIR/deslop"
 cat > "$SKILLS_DIR/deslop/SKILL.md" << 'EOF'
 ---
 name: deslop
-description: Clean AI slop from codebase - console.log statements, TODO comments, placeholder text, empty catch blocks, and other debugging artifacts. Use when users want to clean up code, remove debugging statements, or prepare code for production.
+description: Clean AI slop from codebase. Use this skill when users want to clean up code, remove debugging statements, delete console.log calls, remove TODO comments, clean placeholder text, remove empty catch blocks, or prepare code for production by removing development artifacts.
 ---
 
 # Deslop - AI Slop Cleanup
 
-Remove debugging code, old TODOs, and AI-generated slop from codebase.
+Remove debugging code, old TODOs, and AI-generated slop from the codebase.
+
+## How To Run
+
+**Step 1: Get files to analyze**
+
+If user provided a path, use that. Otherwise:
+```bash
+# Get changed files (staged + unstaged)
+git diff --name-only HEAD
+# Or get all source files in a directory
+find src -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" \)
+```
+
+**Step 2: Call review_code MCP tool with files**
+```
+review_code({ files: ["src/file1.ts", "src/file2.ts"] })
+```
+
+**Step 3: Fix issues found**
+
+Review findings by severity and apply fixes.
 
 ## Detection Patterns
 
-- Console debugging (console.log, print, dbg!)
+- Console debugging (console.log, print(), dbg!())
 - Placeholder text (TODO, FIXME, lorem ipsum)
 - Empty catch blocks
-- Commented-out code
-- Magic numbers
-- Disabled linters
+- Commented-out code blocks
+- Disabled linters (eslint-disable, @ts-ignore)
+
+## Default Behavior
+
+If no path specified:
+1. First check `git diff --name-only` for changed files
+2. If no changes, ASK user: "Which directory should I scan?"
+3. Never scan 0 files silently
+EOF
+
+# Create workflow-status skill for quick status checks
+mkdir -p "$SKILLS_DIR/workflow-status"
+cat > "$SKILLS_DIR/workflow-status/SKILL.md" << 'EOF'
+---
+name: workflow-status
+description: Check the current workflow status. Use this skill when users ask about current task status, workflow progress, what phase they're in, or want to see the state of their work.
+---
+
+# Workflow Status
+
+Quick check of the current workflow state.
 
-## Usage
+## MCP Tools Available
 
-1. Analyze codebase or specific files
-2. Report issues found with severity
-3. Apply fixes with verification when requested
+- `workflow_status` - Get current workflow state
+
+## Instructions
+
+Simply call the `workflow_status` MCP tool to retrieve:
+- Current task being worked on
+- Current workflow phase
+- Resume capability
+- PR status if applicable
+- Last update timestamp
+
+## Status Information
+
+The status includes:
+- **task** - Current task title and ID
+- **phase** - Current workflow phase (exploration, planning, implementation, etc.)
+- **status** - Current status (in_progress, completed, failed)
+- **pr** - Pull request number and URL if created
+- **canResume** - Whether the workflow can be resumed
 EOF
 
 echo ""
 echo "✓ Installation complete!"
 echo ""
+echo "Installed:"
+echo "  - MCP server: awesome-slash"
+echo "  - Skills: next-task, ship, review, deslop, workflow-status"
+echo ""
 echo "Usage:"
-echo "  1. Start Codex: codex --enable skills"
-echo "  2. Skills available: \$next-task, \$ship, \$review, \$deslop"
-echo "  3. MCP tools: workflow_status, workflow_start, task_discover, review_code"
+echo "  1. Start Codex: codex"
+echo "  2. Skills are automatically selected based on your request"
+echo "  3. Or invoke directly: \$next-task, \$ship, \$review, \$deslop"
+echo "  4. MCP tools: workflow_status, workflow_start, task_discover, review_code"
 echo ""
 echo "To verify installation:"
-echo "  codex mcp list"
-echo "  ls ~/.codex/skills/"
+echo "  cat ~/.codex/config.toml  # Check MCP server config"
+echo "  ls ~/.codex/skills/       # Check installed skills"