claude-cli-advanced-starter-pack 1.0.0

package/templates/hooks/context-guardian.template.js

@@ -0,0 +1,173 @@
+/**
+ * Context Guardian Hook
+ *
+ * Monitors token usage and triggers appropriate actions at configured thresholds.
+ * Configured via tech-stack.json tokenManagement settings.
+ *
+ * Event: PostToolUse (monitors after each tool execution)
+ * Priority: {{hooks.priorities.lifecycle}}
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration from tech-stack.json
+const CONFIG = {
+  enabled: {{tokenManagement.enabled}},
+  dailyBudget: {{tokenManagement.dailyBudget}},
+  thresholds: {
+    compact: {{tokenManagement.thresholds.compact}},
+    archive: {{tokenManagement.thresholds.archive}},
+    respawn: {{tokenManagement.thresholds.respawn}},
+  },
+  trackingFile: '{{tokenManagement.trackingFile}}',
+};
+
+/**
+ * Load current token usage data
+ */
+function loadUsageData() {
+  const trackingPath = path.join(process.cwd(), CONFIG.trackingFile);
+
+  if (fs.existsSync(trackingPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(trackingPath, 'utf8'));
+    } catch (error) {
+      console.warn('[context-guardian] Could not parse tracking file:', error.message);
+    }
+  }
+
+  // Return default usage data
+  return {
+    date: new Date().toISOString().split('T')[0],
+    sessions: [],
+    totalTokens: 0,
+    currentSession: {
+      id: generateSessionId(),
+      startTime: new Date().toISOString(),
+      tokens: 0,
+      toolCalls: 0,
+    },
+  };
+}
+
+/**
+ * Save usage data
+ */
+function saveUsageData(data) {
+  const trackingPath = path.join(process.cwd(), CONFIG.trackingFile);
+  const trackingDir = path.dirname(trackingPath);
+
+  if (!fs.existsSync(trackingDir)) {
+    fs.mkdirSync(trackingDir, { recursive: true });
+  }
+
+  fs.writeFileSync(trackingPath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+/**
+ * Generate a simple session ID
+ */
+function generateSessionId() {
+  return `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Estimate tokens from tool output
+ * Rough estimation: ~4 chars per token
+ */
+function estimateTokens(text) {
+  if (!text) return 0;
+  const str = typeof text === 'string' ? text : JSON.stringify(text);
+  return Math.ceil(str.length / 4);
+}
+
+/**
+ * Get usage percentage
+ */
+function getUsagePercentage(usedTokens) {
+  return usedTokens / CONFIG.dailyBudget;
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function contextGuardian(context) {
+  // Skip if disabled
+  if (!CONFIG.enabled) {
+    return { continue: true };
+  }
+
+  const { tool, output, error } = context;
+
+  // Load current usage
+  const usage = loadUsageData();
+
+  // Check if we need to reset for a new day
+  const today = new Date().toISOString().split('T')[0];
+  if (usage.date !== today) {
+    // Archive previous day
+    usage.sessions.push(usage.currentSession);
+    usage.date = today;
+    usage.totalTokens = 0;
+    usage.currentSession = {
+      id: generateSessionId(),
+      startTime: new Date().toISOString(),
+      tokens: 0,
+      toolCalls: 0,
+    };
+  }
+
+  // Estimate tokens from this tool call
+  const outputTokens = estimateTokens(output);
+  const errorTokens = estimateTokens(error);
+  const callTokens = outputTokens + errorTokens;
+
+  // Update usage
+  usage.currentSession.tokens += callTokens;
+  usage.currentSession.toolCalls += 1;
+  usage.totalTokens += callTokens;
+
+  // Save updated usage
+  saveUsageData(usage);
+
+  // Calculate usage percentage
+  const usagePercent = getUsagePercentage(usage.totalTokens);
+
+  // Check thresholds and add warnings
+  let message = null;
+
+  if (usagePercent >= CONFIG.thresholds.respawn) {
+    message = `⚠️ CRITICAL: Token usage at ${(usagePercent * 100).toFixed(1)}% of daily budget!
+    Consider respawning session to preserve budget.
+    Run /context-audit for details.`;
+  } else if (usagePercent >= CONFIG.thresholds.archive) {
+    message = `⚠️ WARNING: Token usage at ${(usagePercent * 100).toFixed(1)}% of daily budget.
+    Consider archiving this session.
+    Run /context-audit for recommendations.`;
+  } else if (usagePercent >= CONFIG.thresholds.compact) {
+    message = `ℹ️ Token usage at ${(usagePercent * 100).toFixed(1)}% of daily budget.
+    Consider compacting context soon.`;
+  }
+
+  return {
+    continue: true,
+    message: message,
+    // Add metadata for other hooks/tools to use
+    metadata: {
+      tokenUsage: {
+        session: usage.currentSession.tokens,
+        daily: usage.totalTokens,
+        budget: CONFIG.dailyBudget,
+        percentUsed: usagePercent,
+        status: usagePercent >= CONFIG.thresholds.respawn
+          ? 'critical'
+          : usagePercent >= CONFIG.thresholds.archive
+          ? 'warning'
+          : usagePercent >= CONFIG.thresholds.compact
+          ? 'attention'
+          : 'ok',
+      },
+    },
+  };
+};

package/templates/hooks/deployment-orchestrator.template.js

@@ -0,0 +1,219 @@
+/**
+ * Deployment Orchestrator Hook
+ *
+ * Monitors deployment-related commands and provides coordination.
+ * Prevents conflicting deployments and tracks deployment state.
+ *
+ * Event: PreToolUse
+ * Priority: {{hooks.priorities.tools}}
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Configuration from tech-stack.json
+const CONFIG = {
+  backend: {
+    platform: '{{deployment.backend.platform}}',
+    projectId: '{{deployment.backend.projectId}}',
+    serviceId: '{{deployment.backend.serviceId}}',
+  },
+  frontend: {
+    platform: '{{deployment.frontend.platform}}',
+    projectName: '{{deployment.frontend.projectName}}',
+  },
+};
+
+const DEPLOYMENT_STATE_FILE = '.claude/hooks/cache/deployment-state.json';
+
+/**
+ * Load deployment state
+ */
+function loadDeploymentState() {
+  const statePath = path.join(process.cwd(), DEPLOYMENT_STATE_FILE);
+
+  if (fs.existsSync(statePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    } catch (error) {
+      // Ignore parse errors
+    }
+  }
+
+  return {
+    backend: { status: 'idle', lastDeployment: null },
+    frontend: { status: 'idle', lastDeployment: null },
+    inProgress: false,
+  };
+}
+
+/**
+ * Save deployment state
+ */
+function saveDeploymentState(state) {
+  const statePath = path.join(process.cwd(), DEPLOYMENT_STATE_FILE);
+  const stateDir = path.dirname(statePath);
+
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+  }
+
+  state.lastUpdated = new Date().toISOString();
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+}
+
+/**
+ * Check if a deployment is in progress
+ */
+function checkDeploymentInProgress(state) {
+  // Check if state indicates deployment in progress
+  if (state.inProgress) {
+    // Check if it's been more than 10 minutes (likely stale)
+    if (state.lastUpdated) {
+      const lastUpdate = new Date(state.lastUpdated);
+      const now = new Date();
+      const minutes = (now - lastUpdate) / 1000 / 60;
+
+      if (minutes > 10) {
+        // Stale state, reset
+        state.inProgress = false;
+        state.backend.status = 'idle';
+        state.frontend.status = 'idle';
+        saveDeploymentState(state);
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Detect deployment-related commands
+ */
+function isDeploymentCommand(tool, input) {
+  // MCP Railway deployment
+  if (tool.includes('railway') && tool.includes('deployment')) {
+    return { type: 'backend', platform: 'railway' };
+  }
+
+  // Bash commands
+  if (tool === 'Bash' && input && input.command) {
+    const cmd = input.command.toLowerCase();
+
+    // Cloudflare/Vercel/Netlify deploys
+    if (cmd.includes('wrangler pages deploy') || cmd.includes('wrangler deploy')) {
+      return { type: 'frontend', platform: 'cloudflare' };
+    }
+    if (cmd.includes('vercel') && (cmd.includes('--prod') || cmd.includes('deploy'))) {
+      return { type: 'frontend', platform: 'vercel' };
+    }
+    if (cmd.includes('netlify deploy')) {
+      return { type: 'frontend', platform: 'netlify' };
+    }
+
+    // Heroku
+    if (cmd.includes('git push heroku')) {
+      return { type: 'backend', platform: 'heroku' };
+    }
+
+    // Fly.io
+    if (cmd.includes('fly deploy')) {
+      return { type: 'backend', platform: 'fly' };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function deploymentOrchestrator(context) {
+  const { tool, input } = context;
+
+  // Check if this is a deployment command
+  const deployment = isDeploymentCommand(tool, input);
+
+  if (!deployment) {
+    return { continue: true };
+  }
+
+  // Load current deployment state
+  const state = loadDeploymentState();
+
+  // Check if another deployment is in progress
+  if (checkDeploymentInProgress(state)) {
+    const inProgressType = state.backend.status === 'deploying' ? 'backend' : 'frontend';
+
+    return {
+      continue: false, // Block the deployment
+      message: `⚠️ Deployment blocked: ${inProgressType} deployment already in progress.
+
+Current state:
+- Backend: ${state.backend.status}
+- Frontend: ${state.frontend.status}
+
+Wait for the current deployment to complete, or clear the state if it's stuck:
+- Check deployment status in your platform dashboard
+- Clear state by deleting ${DEPLOYMENT_STATE_FILE}`,
+    };
+  }
+
+  // Mark deployment as in progress
+  state.inProgress = true;
+  state[deployment.type].status = 'deploying';
+  state[deployment.type].startTime = new Date().toISOString();
+  state[deployment.type].platform = deployment.platform;
+  saveDeploymentState(state);
+
+  // Allow the deployment to proceed
+  return {
+    continue: true,
+    message: `🚀 Starting ${deployment.type} deployment to ${deployment.platform}...
+
+Pre-flight checks:
+${CONFIG[deployment.type].platform === deployment.platform ? '✅' : '⚠️'} Platform matches config
+✅ No conflicting deployments
+
+Deployment state saved. Run /deploy-full to see full deployment status.`,
+  };
+};
+
+/**
+ * Post-deployment cleanup (called as PostToolUse)
+ */
+module.exports.postDeployment = async function postDeploymentOrchestrator(context) {
+  const { tool, input, output, error } = context;
+
+  // Check if this was a deployment command
+  const deployment = isDeploymentCommand(tool, input);
+
+  if (!deployment) {
+    return { continue: true };
+  }
+
+  // Load and update state
+  const state = loadDeploymentState();
+
+  state.inProgress = false;
+  state[deployment.type].status = error ? 'failed' : 'completed';
+  state[deployment.type].lastDeployment = new Date().toISOString();
+  state[deployment.type].duration = state[deployment.type].startTime
+    ? Math.round((Date.now() - new Date(state[deployment.type].startTime)) / 1000)
+    : null;
+
+  if (error) {
+    state[deployment.type].lastError = error.message || String(error);
+  }
+
+  saveDeploymentState(state);
+
+  return {
+    continue: true,
+    message: error
+      ? `❌ ${deployment.type} deployment failed after ${state[deployment.type].duration}s`
+      : `✅ ${deployment.type} deployment completed in ${state[deployment.type].duration}s`,
+  };
+};

package/templates/hooks/github-progress-hook.template.js

@@ -0,0 +1,197 @@
+/**
+ * GitHub Progress Hook
+ *
+ * Automatically updates GitHub issues as tasks are completed.
+ * Monitors TodoWrite/TaskUpdate calls and syncs progress to linked GitHub issues.
+ *
+ * Event: PostToolUse
+ * Priority: {{hooks.priorities.automation}}
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+// Configuration from tech-stack.json
+const CONFIG = {
+  owner: '{{versionControl.owner}}',
+  repo: '{{versionControl.repo}}',
+  projectNumber: {{versionControl.projectBoard.number}},
+  enabled: '{{versionControl.projectBoard.type}}' === 'github-projects',
+};
+
+const PROGRESS_FILE = '.claude/hooks/cache/github-progress.json';
+
+/**
+ * Load progress tracking data
+ */
+function loadProgress() {
+  const progressPath = path.join(process.cwd(), PROGRESS_FILE);
+
+  if (fs.existsSync(progressPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(progressPath, 'utf8'));
+    } catch (error) {
+      console.warn('[github-progress] Could not parse progress file');
+    }
+  }
+
+  return {
+    linkedIssue: null,
+    tasks: [],
+    completedTasks: [],
+    lastUpdate: null,
+  };
+}
+
+/**
+ * Save progress tracking data
+ */
+function saveProgress(progress) {
+  const progressPath = path.join(process.cwd(), PROGRESS_FILE);
+  const progressDir = path.dirname(progressPath);
+
+  if (!fs.existsSync(progressDir)) {
+    fs.mkdirSync(progressDir, { recursive: true });
+  }
+
+  progress.lastUpdate = new Date().toISOString();
+  fs.writeFileSync(progressPath, JSON.stringify(progress, null, 2), 'utf8');
+}
+
+/**
+ * Check if gh CLI is available
+ */
+function hasGhCli() {
+  try {
+    execSync('gh --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Update GitHub issue with progress
+ */
+function updateGitHubIssue(issueNumber, completedTasks, totalTasks, latestTask) {
+  if (!hasGhCli()) {
+    console.warn('[github-progress] gh CLI not available');
+    return false;
+  }
+
+  try {
+    // Create progress comment
+    const percentage = Math.round((completedTasks / totalTasks) * 100);
+    const progressBar = '█'.repeat(Math.floor(percentage / 10)) + '░'.repeat(10 - Math.floor(percentage / 10));
+
+    const comment = `### Progress Update
+
+${progressBar} ${percentage}% (${completedTasks}/${totalTasks} tasks)
+
+**Latest completed:** ${latestTask || 'N/A'}
+
+---
+*Auto-updated by Claude Code github-progress-hook*`;
+
+    // Add comment to issue
+    execSync(
+      `gh issue comment ${issueNumber} --repo ${CONFIG.owner}/${CONFIG.repo} --body "${comment.replace(/"/g, '\\"')}"`,
+      { stdio: 'ignore' }
+    );
+
+    return true;
+  } catch (error) {
+    console.warn('[github-progress] Failed to update GitHub:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Extract linked issue from task metadata or context
+ */
+function findLinkedIssue(input, progress) {
+  // Check if issue is already linked
+  if (progress.linkedIssue) {
+    return progress.linkedIssue;
+  }
+
+  // Try to extract from task description
+  if (input && input.description) {
+    const issueMatch = input.description.match(/#(\d+)/);
+    if (issueMatch) {
+      return parseInt(issueMatch[1], 10);
+    }
+  }
+
+  // Try to extract from subject
+  if (input && input.subject) {
+    const issueMatch = input.subject.match(/#(\d+)/);
+    if (issueMatch) {
+      return parseInt(issueMatch[1], 10);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Main hook handler
+ */
+module.exports = async function githubProgressHook(context) {
+  // Skip if not configured
+  if (!CONFIG.enabled || !CONFIG.owner || !CONFIG.repo) {
+    return { continue: true };
+  }
+
+  const { tool, input } = context;
+
+  // Only process task-related tools
+  if (!['TodoWrite', 'TaskUpdate', 'TaskCreate'].includes(tool)) {
+    return { continue: true };
+  }
+
+  // Load progress tracking
+  const progress = loadProgress();
+
+  // Check for linked issue
+  const issueNumber = findLinkedIssue(input, progress);
+
+  if (issueNumber && !progress.linkedIssue) {
+    progress.linkedIssue = issueNumber;
+    console.log(`[github-progress] Linked to issue #${issueNumber}`);
+  }
+
+  // Track task completion
+  if (tool === 'TaskUpdate' && input && input.status === 'completed') {
+    const taskId = input.taskId;
+    if (taskId && !progress.completedTasks.includes(taskId)) {
+      progress.completedTasks.push(taskId);
+
+      // Update GitHub if we have a linked issue
+      if (progress.linkedIssue) {
+        const totalTasks = progress.tasks.length || progress.completedTasks.length;
+        updateGitHubIssue(
+          progress.linkedIssue,
+          progress.completedTasks.length,
+          totalTasks,
+          input.subject || `Task ${taskId}`
+        );
+      }
+    }
+  }
+
+  // Track new tasks
+  if (tool === 'TaskCreate' && input && input.subject) {
+    progress.tasks.push({
+      id: Date.now().toString(),
+      subject: input.subject,
+      created: new Date().toISOString(),
+    });
+  }
+
+  // Save updated progress
+  saveProgress(progress);
+
+  return { continue: true };
+};