xtrm-tools 2.0.0

package/project-skills/main-guard/.claude/hooks/main-guard.cjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Main Guard - Git branch protection hook for Claude Code.
+ * Blocks direct edits to main/master branches and enforces feature branch workflow.
+ * 
+ * Exit codes:
+ *   0 - Allowed (not on protected branch, or operation allowed)
+ *   1 - Fatal error
+ *   2 - Blocked (attempted edit on protected branch)
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Colors
+const colors = {
+  red: '\x1b[0;31m',
+  green: '\x1b[0;32m',
+  yellow: '\x1b[0;33m',
+  blue: '\x1b[0;34m',
+  cyan: '\x1b[0;36m',
+  reset: '\x1b[0m',
+};
+
+function log(msg, color = '') {
+  console.error(`${color}${msg}${colors.reset}`);
+}
+
+function logInfo(msg) { log(`[INFO] ${msg}`, colors.blue); }
+function logError(msg) { log(`[ERROR] ${msg}`, colors.red); }
+function logSuccess(msg) { log(`[OK] ${msg}`, colors.green); }
+function logWarning(msg) { log(`[WARN] ${msg}`, colors.yellow); }
+
+/**
+ * Get current git branch name
+ */
+function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
+  } catch (e) {
+    logWarning('Could not determine git branch');
+    return null;
+  }
+}
+
+/**
+ * Check if branch is protected
+ */
+function isProtectedBranch(branch) {
+  if (!branch) return false;
+  
+  // Get protected branches from config or use defaults
+  const protectedPatterns = process.env.MAIN_GUARD_PROTECTED_BRANCHES 
+    ? process.env.MAIN_GUARD_PROTECTED_BRANCHES.split(',') 
+    : ['main', 'master', 'develop'];
+  
+  return protectedPatterns.some(pattern => {
+    const regex = new RegExp(`^${pattern.replace('*', '.*')}$`);
+    return regex.test(branch);
+  });
+}
+
+/**
+ * Get feature branch name suggestion based on task
+ */
+function suggestBranchName(input) {
+  const toolName = input.tool_name || '';
+  const prompt = input.user_prompt || '';
+  
+  // Extract potential task identifier
+  const match = prompt.match(/(?:issue|ticket|task|bug|feat)[#:-]?\s*(\d+|[a-z-]+)/i) ||
+                prompt.match(/^([a-z-]+)/i);
+  
+  if (match) {
+    const prefix = toolName.includes('Edit') || toolName.includes('Write') ? 'fix' : 'feat';
+    return `${prefix}/${match[1].toLowerCase().replace(/\s+/g, '-')}`;
+  }
+  
+  return 'feature/task';
+}
+
+/**
+ * Parse JSON input from stdin
+ */
+function parseInput() {
+  let inputData = '';
+  
+  try {
+    inputData = fs.readFileSync(0, 'utf8');
+  } catch (e) {
+    return null;
+  }
+  
+  if (!inputData.trim()) {
+    return null;
+  }
+  
+  try {
+    return JSON.parse(inputData);
+  } catch (e) {
+    logWarning('Invalid JSON input');
+    return null;
+  }
+}
+
+/**
+ * Print blocked message with instructions
+ */
+function printBlocked(branch, suggestedBranch) {
+  log('', colors.red);
+  log('═══════════════════════════════════════════════════════════', colors.red);
+  log('  🛑 BLOCKED: Direct edits to protected branches', colors.red);
+  log('═══════════════════════════════════════════════════════════', colors.red);
+  log('', colors.reset);
+  log(`  Current branch: ${colors.yellow}${branch}${colors.reset}`, colors.reset);
+  log('', colors.reset);
+  log('  You cannot edit files directly on a protected branch.', colors.reset);
+  log('  This prevents accidental commits and enforces code review.', colors.reset);
+  log('', colors.reset);
+  log('  📋 To proceed:', colors.cyan);
+  log(`     1. Create a feature branch: ${colors.green}git checkout -b ${suggestedBranch}${colors.reset}`, colors.reset);
+  log(`     2. Make your changes on that branch`, colors.reset);
+  log(`     3. Push and create a pull request`, colors.reset);
+  log('', colors.reset);
+  log('═══════════════════════════════════════════════════════════', colors.red);
+  log('', colors.reset);
+}
+
+/**
+ * Print success message
+ */
+function printSuccess(branch) {
+  log('', colors.green);
+  log(`✅ Git workflow check passed`, colors.green);
+  log(`   Branch: ${branch}`, colors.green);
+  log('', colors.reset);
+}
+
+/**
+ * Main entry point
+ */
+function main() {
+  log('');
+  log('🔒 Main Guard - Branch Protection Check', colors.blue);
+  log('─────────────────────────────────────────', colors.blue);
+  
+  // Parse input
+  const input = parseInput();
+  
+  // Get current branch
+  const branch = getCurrentBranch();
+  
+  if (!branch) {
+    logWarning('Not in a git repository - skipping branch protection');
+    log('', colors.yellow);
+    log('👉 Not a git repository - continuing without branch protection', colors.yellow);
+    log('', colors.reset);
+    process.exit(0);
+  }
+  
+  logInfo(`Current branch: ${branch}`);
+  
+  // Check if protected
+  if (isProtectedBranch(branch)) {
+    const suggestedBranch = suggestBranchName(input || {});
+    printBlocked(branch, suggestedBranch);
+    process.exit(2);
+  }
+  
+  // Not a protected branch - allow
+  printSuccess(branch);
+  process.exit(0);
+}
+
+// Handle errors
+process.on('unhandledRejection', (error) => {
+  logError(`Unhandled error: ${error.message}`);
+  process.exit(1);
+});
+
+// Run
+try {
+  main();
+} catch (error) {
+  logError(`Fatal error: ${error.message}`);
+  process.exit(1);
+}

package/project-skills/main-guard/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/main-guard.cjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/project-skills/main-guard/.claude/skills/using-main-guard/SKILL.md

@@ -0,0 +1,135 @@
+# Using Main Guard
+
+**Main Guard** enforces Git branch protection by blocking direct edits to protected branches (main, master, develop).
+
+## What It Does
+
+- **Blocks direct edits** to protected branches
+- **Enforces feature branch workflow**
+- **Suggests branch names** based on your task
+- **Prevents accidental commits** to main/master
+
+## How It Works
+
+When you attempt to write or edit files:
+
+1. PreToolUse hook fires before Write/Edit
+2. Runs `main-guard.js` to check current branch
+3. If on protected branch: **blocks the action**
+4. If on feature branch: **allows the action**
+
+## Protected Branches
+
+By default, these branches are protected:
+- `main`
+- `master`
+- `develop`
+
+Customize via environment variable:
+```bash
+export MAIN_GUARD_PROTECTED_BRANCHES="main,master,develop,production"
+```
+
+## Installation
+
+```bash
+# Install project skill
+xtrm install project main-guard
+```
+
+## Usage
+
+### When Blocked
+
+If you try to edit files on a protected branch, you'll see:
+
+```
+🛑 BLOCKED: Direct edits to protected branches
+
+  Current branch: main
+
+  You cannot edit files directly on a protected branch.
+
+  📋 To proceed:
+     1. Create a feature branch: git checkout -b feat/task-name
+     2. Make your changes on that branch
+     3. Push and create a pull request
+```
+
+### Branch Name Suggestions
+
+The hook suggests branch names based on your task:
+- `feat/issue-123` - For feature requests
+- `fix/bug-456` - For bug fixes
+- `feat/description` - For general features
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Custom protected branches
+export MAIN_GUARD_PROTECTED_BRANCHES="main,master,develop,staging"
+
+# Support wildcards
+export MAIN_GUARD_PROTECTED_BRANCHES="main,master,release/*,hotfix/*"
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Allowed (not on protected branch) |
+| 1 | Fatal error |
+| 2 | Blocked (on protected branch) |
+
+## Workflow
+
+### Recommended Git Flow
+
+```bash
+# Start new feature
+git checkout main
+git pull origin main
+git checkout -b feat/my-feature
+
+# Make changes (main-guard allows this)
+# ... edit files ...
+
+# Commit and push
+git add .
+git commit -m "feat: add my feature"
+git push -u origin feat/my-feature
+
+# Create PR on GitHub/GitLab
+```
+
+### Hotfix Flow
+
+```bash
+# Emergency fix
+git checkout main
+git checkout -b hotfix/urgent-fix
+
+# Make changes, commit, push
+# Create PR with expedited review
+```
+
+## Troubleshooting
+
+**"Not in a git repository"**
+- Hook skips gracefully when not in git repo
+- No protection applied outside git projects
+
+**"Could not determine git branch"**
+- Ensure git is installed and working
+- Check if `.git` folder exists
+
+**Hook not running**
+- Verify PreToolUse hook in `.claude/settings.json`
+- Check Node.js is installed
+
+## See Also
+
+- Full documentation: `.claude/docs/main-guard-readme.md`
+- Git flow: https://nvie.com/posts/a-successful-git-branching-model/

package/project-skills/main-guard/README.md

@@ -0,0 +1,163 @@
+# Main Guard
+
+**Git branch protection** for Claude Code. Blocks direct edits to main/master branches and enforces feature branch workflow.
+
+## What It Does
+
+Main Guard prevents accidental commits to protected branches:
+
+| Feature | Description |
+|---------|-------------|
+| **Branch blocking** | Prevents Write/Edit on protected branches |
+| **Branch suggestions** | Suggests feature branch names |
+| **Custom patterns** | Configure which branches are protected |
+| **Git flow enforcement** | Encourages PR-based workflow |
+
+## Installation
+
+```bash
+# Install project skill
+xtrm install project main-guard
+```
+
+## How It Works
+
+The guard runs as a `PreToolUse` hook:
+
+1. You attempt to write/edit a file
+2. Before the edit, the hook checks current branch
+3. If on protected branch: **blocks with instructions**
+4. If on feature branch: **allows the edit**
+
+## Protected Branches
+
+**Default:**
+- `main`
+- `master`
+- `develop`
+
+**Customize:**
+```bash
+export MAIN_GUARD_PROTECTED_BRANCHES="main,master,develop,production"
+```
+
+**Supports wildcards:**
+```bash
+export MAIN_GUARD_PROTECTED_BRANCHES="main,master,release/*,hotfix/*"
+```
+
+## Usage
+
+### Blocked Message
+
+When you try to edit on a protected branch:
+
+```
+🛑 BLOCKED: Direct edits to protected branches
+
+  Current branch: main
+
+  📋 To proceed:
+     1. Create a feature branch: git checkout -b feat/task
+     2. Make your changes on that branch
+     3. Push and create a pull request
+```
+
+### Allowed
+
+When on a feature branch:
+```
+✅ Git workflow check passed
+   Branch: feat/my-feature
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MAIN_GUARD_PROTECTED_BRANCHES` | `main,master,develop` | Comma-separated list of protected branches |
+
+### Setup
+
+Add to your shell profile (`~/.bashrc`, `~/.zshrc`):
+```bash
+export MAIN_GUARD_PROTECTED_BRANCHES="main,master"
+```
+
+Or create `.env` in your project:
+```bash
+MAIN_GUARD_PROTECTED_BRANCHES=main,master,develop
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Allowed (not on protected branch) |
+| 1 | Fatal error |
+| 2 | Blocked (on protected branch) |
+
+## Git Flow
+
+### Standard Feature Development
+
+```bash
+# Start from main
+git checkout main
+git pull origin main
+
+# Create feature branch
+git checkout -b feat/user-authentication
+
+# Make changes (main-guard allows this)
+# Edit files, commit, push
+git add .
+git commit -m "feat: add user authentication"
+git push -u origin feat/user-authentication
+
+# Create PR on GitHub
+```
+
+### Hotfix
+
+```bash
+# Emergency fix from main
+git checkout main
+git checkout -b hotfix/login-bug
+
+# Fix, commit, push, PR
+```
+
+### Release Branch
+
+```bash
+# Prepare release
+git checkout -b release/v1.2.0
+
+# Final testing, version bump
+# Merge to main and develop
+```
+
+## Benefits
+
+- ✅ Prevents accidental direct commits to main
+- ✅ Enforces code review via PRs
+- ✅ Maintains clean main branch history
+- ✅ Encourages proper Git workflow
+
+## Troubleshooting
+
+**"Not in a git repository"**
+- Hook skips when not in git project
+- No protection outside git repos
+
+**Node.js not found**
+- Install Node.js: `node --version`
+- Hook requires Node.js to run
+
+## See Also
+
+- Git Flow: https://nvie.com/posts/a-successful-git-branching-model/
+- GitHub Flow: https://docs.github.com/en/get-started/using-github/github-flow