@silverassist/agents-toolkit 2.2.0 → 2.3.0

package/README.md

@@ -14,6 +14,7 @@ Reusable AI agent prompts for development workflows — supports **GitHub Copilo
 - ✅ **Global Install**: Install once for all projects with `--global`
 - ✅ **Modular Partials**: Reusable prompt fragments
 - ✅ **Customizable**: Easy to extend and modify
+- ✅ **PostToolUse Hooks**: Automated validation and formatting after Copilot edits
 - ✅ **CLI Tool**: Quick installation in any project
 
 ## Installation
@@ -257,6 +258,7 @@ npx @silverassist/agents-toolkit@latest install [options]
 | `--instructions-only` | Only install instructions and instructions file |
 | `--partials-only` | Only install partials |
 | `--skills-only` | Only install skills |
+| `--hooks-only` | Only install hooks (PostToolUse validation scripts) |
 | `--dry-run` | Show what would be installed without making changes |
 
 **Examples:**
@@ -384,6 +386,39 @@ Specialized knowledge guides for domain-specific patterns:
 
 **Codex** — skills are stored in `.github/skills/` and can be referenced from `AGENTS.md` and task context.
 
+## Hooks
+
+PostToolUse hooks run automatically after GitHub Copilot edits files. They provide real-time validation and formatting without manual intervention.
+
+| Hook | Trigger | Description |
+|------|---------|-------------|
+| `validate-tsx` | `*.tsx` in `components/` | Validates kebab-case folders, `index.tsx` naming, default export, and Props interface |
+| `lint-format` | `*.ts, *.tsx, *.js, *.jsx, *.css` | Runs ESLint `--fix` and Prettier `--write` on the modified file |
+
+Hooks are installed to:
+
+- **Project** (default): `.github/hooks/`
+- **Global** (`--global`): `~/.copilot/hooks/`
+
+```
+.github/hooks/              # or ~/.copilot/hooks/ for global
+├── validate-tsx.json       # Hook config (PostToolUse trigger)
+├── lint-format.json        # Hook config (PostToolUse trigger)
+└── scripts/
+    ├── validate-tsx.sh     # Validation logic (exit 1 = warning)
+    └── lint-format.sh      # Auto-fix logic (always exit 0)
+```
+
+Install only hooks:
+
+```bash
+# Project-level (hooks apply to this project only)
+npx @silverassist/agents-toolkit@latest install --hooks-only
+
+# Global (hooks apply to all Copilot sessions)
+npx @silverassist/agents-toolkit@latest install --hooks-only --global
+```
+
 ## Agent Instructions Files
 
 ### AGENTS.md (Copilot/Codex Agent)

package/bin/cli.js

@@ -286,14 +286,16 @@ function getInstallScope(options = {}) {
     partialsOnly = false,
     skillsOnly = false,
     instructionsOnly = false,
+    hooksOnly = false,
   } = options;
 
-  const hasSpecificFlag = promptsOnly || partialsOnly || skillsOnly || instructionsOnly;
+  const hasSpecificFlag = promptsOnly || partialsOnly || skillsOnly || instructionsOnly || hooksOnly;
 
   return {
     shouldInstallPrompts: !hasSpecificFlag || promptsOnly || partialsOnly,
     shouldInstallInstructions: !hasSpecificFlag || instructionsOnly,
     shouldInstallSkills: !hasSpecificFlag || skillsOnly,
+    shouldInstallHooks: !hasSpecificFlag || hooksOnly,
   };
 }
 
@@ -301,6 +303,37 @@ function getChangeCount(result, dryRun) {
   return dryRun ? result.planned : result.written;
 }
 
+function installHooks({ targetDir, force = false, dryRun = false }) {
+  const hooksSrc = path.join(TEMPLATES_DIR, 'shared', 'hooks');
+  const hooksDest = path.join(targetDir, 'hooks');
+
+  if (!fs.existsSync(hooksSrc)) {
+    warn('No hooks templates found — skipping');
+    return { written: 0, skipped: 0, planned: 0 };
+  }
+
+  // Copy hook JSON configs and scripts
+  const result = copyDir(hooksSrc, hooksDest, { force, dryRun });
+
+  // Make scripts executable (non-dry-run only)
+  if (!dryRun) {
+    const scriptsDir = path.join(hooksDest, 'scripts');
+    if (fs.existsSync(scriptsDir)) {
+      const scripts = fs.readdirSync(scriptsDir).filter(f => f.endsWith('.sh'));
+      for (const script of scripts) {
+        const scriptPath = path.join(scriptsDir, script);
+        fs.chmodSync(scriptPath, 0o755);
+      }
+    }
+  }
+
+  if (!dryRun && result.written > 0) {
+    success(`Installed ${result.written} hook files`);
+  }
+
+  return result;
+}
+
 function ensureConfigFile({ dryRun = false, global = false } = {}) {
   const configDir = global ? getHomeDir() : process.cwd();
   const configPath = path.join(configDir, '.agents-toolkit.json');
@@ -495,6 +528,12 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
     }
   }
 
+  if (scope.shouldInstallHooks) {
+    info('Installing hooks...');
+    const hooksResult = installHooks({ targetDir, force, dryRun });
+    totalChanges += getChangeCount(hooksResult, dryRun);
+  }
+
   const configResult = ensureConfigFile({ dryRun, global: isGlobal });
   totalChanges += getChangeCount(configResult, dryRun);
 
@@ -715,6 +754,17 @@ function list() {
       console.log(`  • ${s}`);
     });
   }
+
+  console.log('');
+  log('Hooks:', 'cyan');
+  const hooksDir = path.join(TEMPLATES_DIR, 'shared', 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const hooks = fs.readdirSync(hooksDir)
+      .filter(f => f.endsWith('.json'));
+    hooks.forEach(h => {
+      console.log(`  • ${h.replace('.json', '')}`);
+    });
+  }
   console.log('');
 }
 
@@ -745,6 +795,7 @@ function showHelp() {
   console.log('  --instructions-only Only install instructions');
   console.log('  --partials-only     Only install partials');
   console.log('  --skills-only       Only install skills');
+  console.log('  --hooks-only        Only install hooks (PostToolUse validation scripts)');
   console.log('  --dry-run           Show what would be installed');
 
   console.log('');
@@ -821,6 +872,7 @@ function parseArgs() {
     partialsOnly: flags.includes('--partials-only'),
     skillsOnly: flags.includes('--skills-only'),
     instructionsOnly: flags.includes('--instructions-only'),
+    hooksOnly: flags.includes('--hooks-only'),
     dryRun: flags.includes('--dry-run'),
     claude: flags.includes('--claude'),
     codex: flags.includes('--codex'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silverassist/agents-toolkit",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Reusable AI agent prompts for development workflows with Jira integration — supports GitHub Copilot, Claude Code, and Codex",
   "author": "Santiago Ramirez",
   "license": "PolyForm-Noncommercial-1.0.0",

package/src/index.js

@@ -3,7 +3,7 @@
  * @module @silverassist/agents-toolkit
  */
 
-export const VERSION = "2.2.0";
+export const VERSION = "2.3.0";
 
 export const PROMPTS = {
   workflow: [
@@ -40,6 +40,8 @@ export const SKILLS = [
   "ai-seo-optimization",
 ];
 
+export const HOOKS = ["validate-tsx", "lint-format"];
+
 // Claude Code equivalents
 export const CLAUDE_COMMANDS = [
   "analyze-ticket",

package/templates/shared/hooks/lint-format.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "scripts/lint-format.sh",
+        "timeout": 30
+      }
+    ]
+  }
+}

package/templates/shared/hooks/scripts/lint-format.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# lint-format.sh — PostToolUse hook for VS Code Copilot
+# Runs eslint --fix and prettier --write on files modified by the agent.
+# This ensures agent-generated code follows project formatting standards.
+# Exit 0 = pass (always), diagnostics printed to stderr.
+
+set -uo pipefail
+
+FILE="${COPILOT_FILE:-}"
+
+if [[ -z "$FILE" ]]; then
+  exit 0
+fi
+
+# Only process TypeScript, JavaScript, and CSS files
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx|*.css) ;;
+  *) exit 0 ;;
+esac
+
+# Resolve to absolute path to prevent infinite loop in directory walk
+if [[ "$FILE" != /* ]]; then
+  FILE="$(cd "$(dirname "$FILE")" && pwd)/$(basename "$FILE")"
+fi
+
+# File must exist
+if [[ ! -f "$FILE" ]]; then
+  exit 0
+fi
+
+# Find project root (look for package.json)
+DIR="$(dirname "$FILE")"
+PROJECT_ROOT=""
+while [[ "$DIR" != "/" ]]; do
+  if [[ -f "$DIR/package.json" ]]; then
+    PROJECT_ROOT="$DIR"
+    break
+  fi
+  DIR="$(dirname "$DIR")"
+done
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+  exit 0
+fi
+
+# Resolve tool paths
+ESLINT="$PROJECT_ROOT/node_modules/.bin/eslint"
+PRETTIER="$PROJECT_ROOT/node_modules/.bin/prettier"
+
+# Run ESLint --fix (only on TS/JS files)
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx)
+    if [[ -x "$ESLINT" ]]; then
+      "$ESLINT" --fix "$FILE" || true
+    fi
+    ;;
+esac
+
+# Run Prettier --write
+if [[ -x "$PRETTIER" ]]; then
+  "$PRETTIER" --write "$FILE" || true
+fi
+
+exit 0

package/templates/shared/hooks/scripts/validate-tsx.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# validate-tsx.sh — PostToolUse hook for VS Code Copilot
+# Validates that TSX component files follow project conventions.
+# Exit 0 = pass, Exit 1 = fail (shown as warning to Copilot).
+
+set -euo pipefail
+
+# Only run when a .tsx file was modified
+FILE="${COPILOT_FILE:-}"
+
+if [[ -z "$FILE" ]]; then
+  exit 0
+fi
+
+if [[ "$FILE" != *.tsx ]]; then
+  exit 0
+fi
+
+# Only validate files inside components/ directories
+if [[ "$FILE" != *"/components/"* ]]; then
+  exit 0
+fi
+
+ERRORS=()
+
+# --- Rule 1: Component must be inside a folder with index.tsx ---
+BASENAME=$(basename "$FILE")
+DIRNAME=$(basename "$(dirname "$FILE")")
+
+if [[ "$BASENAME" != "index.tsx" && "$DIRNAME" != "__tests__" ]]; then
+  ERRORS+=("Component files must be named index.tsx inside a kebab-case folder (found: $BASENAME)")
+fi
+
+# --- Rule 2: Parent folder must be kebab-case ---
+if [[ "$BASENAME" == "index.tsx" ]]; then
+  if [[ ! "$DIRNAME" =~ ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ ]]; then
+    ERRORS+=("Component folder must be kebab-case (found: $DIRNAME)")
+  fi
+fi
+
+# --- Rule 3: Must have a default export function (PascalCase) ---
+if [[ "$BASENAME" == "index.tsx" ]] && [[ -f "$FILE" ]]; then
+  if ! grep -qE "^export default function [A-Z]" "$FILE"; then
+    ERRORS+=("Component must use 'export default function PascalName' pattern")
+  fi
+fi
+
+# --- Rule 4: Props interface should exist for non-trivial components ---
+if [[ "$BASENAME" == "index.tsx" ]] && [[ -f "$FILE" ]]; then
+  # Check if there are props being destructured
+  if grep -qE "^export default function [A-Z][a-zA-Z]+\(" "$FILE"; then
+    # If it has props (not empty parens), check for interface
+    if grep -qE "^export default function [A-Z][a-zA-Z]+\(\{" "$FILE"; then
+      if ! grep -qE "^(export )?(interface|type) [A-Z][a-zA-Z]+Props" "$FILE"; then
+        ERRORS+=("Components with props should define a Props interface (e.g., interface ComponentNameProps)")
+      fi
+    fi
+  fi
+fi
+
+# --- Rule 5: No relative imports (must use @/ prefix) ---
+if [[ -f "$FILE" ]]; then
+  if grep -qE "^import .+ from ['\"]\.\.?/" "$FILE" || grep -qE "^import ['\"]\.\.?/" "$FILE"; then
+    ERRORS+=("Relative imports found. Use absolute imports with @/ prefix instead of ./ or ../")
+  fi
+fi
+
+# --- Report ---
+if [[ ${#ERRORS[@]} -gt 0 ]]; then
+  echo "⚠️  TSX validation issues in: $FILE"
+  for err in "${ERRORS[@]}"; do
+    echo "  • $err"
+  done
+  exit 1
+fi
+
+exit 0

package/templates/shared/hooks/validate-tsx.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "scripts/validate-tsx.sh",
+        "timeout": 30
+      }
+    ]
+  }
+}