@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/scripts/lib/workflow-state.js

@@ -0,0 +1,249 @@
+/**
+ * Workflow State - Tracks Workflow Phases and Suggests Next Steps
+ *
+ * Manages the state of multi-phase workflows (feature, bugfix, refactor, zoho)
+ * and provides guidance on skipped phases and next steps.
+ *
+ * @module workflow-state
+ */
+
+/**
+ * Workflow phase definitions
+ *
+ * Each workflow type has an ordered list of phases that should be followed.
+ * Critical phases are marked and require confirmation to skip.
+ */
+const WORKFLOW_PHASES = {
+  feature: ['plan', 'tdd', 'implement', 'review', 'verify', 'pr'],
+  bugfix: ['investigate', 'tdd', 'fix', 'review', 'verify'],
+  refactor: ['plan', 'review-existing', 'refactor', 'verify'],
+  zoho: ['architect', 'deluge-review', 'deploy', 'verify'],
+};
+
+/**
+ * Critical phases that require confirmation to skip
+ */
+const CRITICAL_PHASES = {
+  feature: ['plan', 'tdd', 'review'],
+  bugfix: ['investigate', 'review'],
+  refactor: ['plan', 'review-existing'],
+  zoho: ['architect', 'deluge-review'],
+};
+
+/**
+ * In-memory workflow state
+ * In production, this would be persisted to session-memory.js
+ */
+let currentWorkflow = null;
+
+/**
+ * Get the current workflow state
+ *
+ * @returns {object|null} Current workflow state or null if no workflow active
+ */
+function getWorkflowState() {
+  return currentWorkflow;
+}
+
+/**
+ * Start a new workflow
+ *
+ * @param {string} type - Workflow type (feature, bugfix, refactor, zoho)
+ * @param {string} description - Description of what this workflow is for
+ * @returns {boolean} True if workflow started successfully
+ */
+function startWorkflow(type, description = '') {
+  // Validate workflow type
+  if (!WORKFLOW_PHASES[type]) {
+    return false;
+  }
+
+  currentWorkflow = {
+    type,
+    description,
+    currentPhase: null,
+    completedPhases: [],
+    startedAt: new Date().toISOString(),
+    lastUpdated: new Date().toISOString(),
+  };
+
+  return true;
+}
+
+/**
+ * Advance to a specific phase
+ *
+ * @param {string} phase - The phase to advance to
+ * @returns {boolean} True if phase was advanced successfully
+ */
+function advancePhase(phase) {
+  if (!currentWorkflow) {
+    return false;
+  }
+
+  // Add to completed phases if not already there
+  if (!currentWorkflow.completedPhases.includes(phase)) {
+    currentWorkflow.completedPhases.push(phase);
+  }
+
+  currentWorkflow.currentPhase = phase;
+  currentWorkflow.lastUpdated = new Date().toISOString();
+
+  return true;
+}
+
+/**
+ * Check which phases were skipped to reach a target phase
+ *
+ * @param {string} targetPhase - The phase we're trying to reach
+ * @returns {string[]} Array of skipped phase names
+ */
+function checkSkippedPhases(targetPhase) {
+  if (!currentWorkflow) {
+    return [];
+  }
+
+  const phases = WORKFLOW_PHASES[currentWorkflow.type];
+  if (!phases) {
+    return [];
+  }
+
+  const targetIndex = phases.indexOf(targetPhase);
+  if (targetIndex === -1) {
+    return [];
+  }
+
+  const skipped = [];
+
+  // Check all phases before the target
+  for (let i = 0; i < targetIndex; i++) {
+    const phase = phases[i];
+    if (!currentWorkflow.completedPhases.includes(phase)) {
+      skipped.push(phase);
+    }
+  }
+
+  return skipped;
+}
+
+/**
+ * Get the next recommended phase
+ *
+ * @returns {string|null} Next phase name or null if workflow complete
+ */
+function getNextPhase() {
+  if (!currentWorkflow) {
+    return null;
+  }
+
+  const phases = WORKFLOW_PHASES[currentWorkflow.type];
+  if (!phases) {
+    return null;
+  }
+
+  // Find the current phase index
+  const currentIndex = currentWorkflow.currentPhase
+    ? phases.indexOf(currentWorkflow.currentPhase)
+    : -1;
+
+  // Return the next phase
+  const nextIndex = currentIndex + 1;
+  if (nextIndex >= phases.length) {
+    return null; // Workflow complete
+  }
+
+  return phases[nextIndex];
+}
+
+/**
+ * Check if a phase is critical for a workflow type
+ *
+ * @param {string} phase - Phase name
+ * @param {string} workflowType - Workflow type
+ * @returns {boolean} True if phase is critical
+ */
+function isCriticalPhase(phase, workflowType) {
+  const criticalPhases = CRITICAL_PHASES[workflowType];
+  if (!criticalPhases) {
+    return false;
+  }
+  return criticalPhases.includes(phase);
+}
+
+/**
+ * Reset the workflow state
+ */
+function resetWorkflow() {
+  currentWorkflow = null;
+}
+
+/**
+ * Check if a workflow is currently active
+ *
+ * @returns {boolean} True if workflow is active
+ */
+function hasActiveWorkflow() {
+  return currentWorkflow !== null;
+}
+
+/**
+ * Get workflow progress as a percentage
+ *
+ * @returns {number} Progress percentage (0-100)
+ */
+function getProgress() {
+  if (!currentWorkflow) {
+    return 0;
+  }
+
+  const phases = WORKFLOW_PHASES[currentWorkflow.type];
+  if (!phases || phases.length === 0) {
+    return 0;
+  }
+
+  return Math.round((currentWorkflow.completedPhases.length / phases.length) * 100);
+}
+
+/**
+ * Detect workflow type from an intent
+ *
+ * @param {string} intent - The detected intent
+ * @returns {string|null} Suggested workflow type or null
+ */
+function detectWorkflowType(intent) {
+  const intentToWorkflow = {
+    PLANNING: 'feature',
+    TESTING: 'feature', // Testing typically part of feature workflow
+    REVIEW: null, // Review could be any workflow
+    SECURITY: null,
+    COMPLIANCE: null,
+    ZOHO: 'zoho',
+    DEPLOY: null, // Deploy is usually end of workflow
+    REFACTOR: 'refactor',
+    DEBUG: 'bugfix',
+  };
+
+  return intentToWorkflow[intent] || null;
+}
+
+module.exports = {
+  // State management
+  getWorkflowState,
+  startWorkflow,
+  advancePhase,
+  resetWorkflow,
+  hasActiveWorkflow,
+
+  // Phase checking
+  checkSkippedPhases,
+  getNextPhase,
+  isCriticalPhase,
+  getProgress,
+
+  // Workflow detection
+  detectWorkflowType,
+
+  // Constants
+  WORKFLOW_PHASES,
+  CRITICAL_PHASES,
+};

package/scripts/onboard.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+
+/**
+ * Onboard Script for Everything Claude Code
+ * Interactive setup wizard for new users
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getClaudeDir,
+  commandExists,
+  runCommand,
+  readFile,
+  ensureDir,
+  log,
+} = require('./lib/utils');
+
+// Status indicators
+const CHECK = '\u2713'; // ✓
+const CROSS = '\u2717'; // ✗
+const ARROW = '\u2192'; // →
+
+let stepNumber = 0;
+const totalSteps = 6;
+const issues = [];
+
+function step(title) {
+  stepNumber++;
+  log('');
+  log(`[${stepNumber}/${totalSteps}] ${title}`);
+}
+
+function success(msg) {
+  log(`  ${CHECK} ${msg}`);
+}
+
+function fail(msg) {
+  log(`  ${CROSS} ${msg}`);
+  issues.push(msg);
+}
+
+function info(msg) {
+  log(`  ${ARROW} ${msg}`);
+}
+
+function divider() {
+  log('');
+  log('-'.repeat(50));
+}
+
+// Step 1: Prerequisites
+function checkPrerequisites() {
+  step('Checking prerequisites...');
+
+  // Node.js
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (nodeMajor >= 18) {
+    success(`Node.js ${nodeVersion}`);
+  } else {
+    fail(`Node.js ${nodeVersion} (requires 18+)`);
+    info('Install Node.js 18+ from https://nodejs.org/');
+  }
+
+  // Git
+  const gitResult = runCommand('git --version');
+  if (gitResult.success) {
+    success('Git installed');
+
+    // Check git config
+    const emailResult = runCommand('git config --get user.email');
+    if (emailResult.success && emailResult.output) {
+      success(`Git configured (${emailResult.output})`);
+    } else {
+      fail('Git email not configured');
+      info('Run: git config --global user.email "your@email.com"');
+    }
+  } else {
+    fail('Git not installed');
+    info('Install Git from https://git-scm.com/');
+  }
+
+  // Package manager
+  if (commandExists('npm')) {
+    success('npm available');
+  } else if (commandExists('yarn')) {
+    success('yarn available');
+  } else if (commandExists('pnpm')) {
+    success('pnpm available');
+  } else {
+    fail('No package manager found');
+    info('npm comes with Node.js - try reinstalling Node.js');
+  }
+}
+
+// Step 2: Repository
+function checkRepository() {
+  step('Checking repository setup...');
+
+  const gitDirResult = runCommand('git rev-parse --git-dir');
+  if (!gitDirResult.success) {
+    fail('Not in a git repository');
+    info('Clone your fork first: git clone https://github.com/YOUR-USERNAME/css_claude_code.git');
+    return;
+  }
+  success('In a git repository');
+
+  // Check remotes
+  const remotesResult = runCommand('git remote -v');
+  if (remotesResult.success) {
+    const remotes = remotesResult.output;
+
+    if (remotes.includes('origin')) {
+      success('Origin remote configured');
+    } else {
+      fail('No origin remote');
+    }
+
+    if (remotes.includes('upstream')) {
+      success('Upstream remote configured');
+    } else {
+      fail('No upstream remote');
+      info(
+        'Add upstream: git remote add upstream https://github.com/CloudStreamSoftware/css_claude_code.git'
+      );
+    }
+  }
+
+  // Check if we're in the right repo
+  const packagePath = path.join(process.cwd(), 'package.json');
+  if (fs.existsSync(packagePath)) {
+    const pkg = JSON.parse(readFile(packagePath));
+    if (pkg.name && pkg.name.includes('claude')) {
+      success('Appears to be correct repository');
+    }
+  }
+}
+
+// Step 3: Dependencies
+function checkDependencies() {
+  step('Checking dependencies...');
+
+  const nodeModules = path.join(process.cwd(), 'node_modules');
+  if (fs.existsSync(nodeModules)) {
+    success('node_modules exists');
+
+    // Quick check for a key dependency
+    const utilsPath = path.join(nodeModules, '.package-lock.json');
+    if (fs.existsSync(utilsPath) || fs.readdirSync(nodeModules).length > 10) {
+      success('Dependencies appear installed');
+    }
+  } else {
+    fail('node_modules not found');
+    info('Run: npm install');
+  }
+
+  // Check for package-lock.json
+  const lockFile = path.join(process.cwd(), 'package-lock.json');
+  if (fs.existsSync(lockFile)) {
+    success('package-lock.json exists');
+  }
+}
+
+// Step 4: Credentials
+function checkCredentials() {
+  step('Checking credentials...');
+
+  const claudeDir = getClaudeDir();
+  ensureDir(claudeDir);
+
+  const envFile = path.join(claudeDir, '.env');
+  if (fs.existsSync(envFile)) {
+    const content = readFile(envFile);
+    if (content && content.trim().length > 0) {
+      success('~/.claude/.env exists with content');
+
+      // Check for GITHUB_TOKEN
+      if (content.includes('GITHUB_TOKEN')) {
+        success('GITHUB_TOKEN configured');
+      } else {
+        fail('GITHUB_TOKEN not found in .env');
+        info('Add GITHUB_TOKEN=your_token to ~/.claude/.env');
+      }
+    } else {
+      fail('~/.claude/.env is empty');
+      info('Add your credentials to ~/.claude/.env');
+    }
+  } else {
+    fail('~/.claude/.env not found');
+    log('');
+    log('  Create ~/.claude/.env with:');
+    log('    GITHUB_TOKEN=your_github_token');
+    log('');
+    log('  Ask your team lead for additional credentials.');
+  }
+}
+
+// Step 5: Health Check
+function runHealthCheck() {
+  step('Running health check...');
+
+  // Run a simplified health check
+  const claudeDir = getClaudeDir();
+
+  // Check claude dir
+  if (fs.existsSync(claudeDir)) {
+    try {
+      const testFile = path.join(claudeDir, '.onboard-test');
+      fs.writeFileSync(testFile, 'test');
+      fs.unlinkSync(testFile);
+      success('~/.claude/ is writable');
+    } catch {
+      fail('~/.claude/ is not writable');
+    }
+  } else {
+    ensureDir(claudeDir);
+    success('Created ~/.claude/ directory');
+  }
+
+  // Check hooks
+  const hooksFile = path.join(process.cwd(), 'hooks', 'hooks.json');
+  if (fs.existsSync(hooksFile)) {
+    try {
+      JSON.parse(readFile(hooksFile));
+      success('hooks.json is valid');
+    } catch {
+      fail('hooks.json has invalid JSON');
+    }
+  } else {
+    fail('hooks.json not found');
+  }
+
+  // Check commands directory
+  const commandsDir = path.join(process.cwd(), 'commands');
+  if (fs.existsSync(commandsDir)) {
+    const commands = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md'));
+    success(`${commands.length} commands available`);
+  }
+}
+
+// Step 6: Next Steps
+function showNextSteps() {
+  step('Setup complete!');
+
+  divider();
+
+  if (issues.length === 0) {
+    log('');
+    log('Your system is ready!');
+    log('');
+    log('Next steps:');
+    log('');
+    log('  1. Start the tutorial:');
+    log('     /tutorial');
+    log('');
+    log('  2. Review documentation:');
+    log('     - README.md (overview)');
+    log('     - GETTING-STARTED.md (detailed setup)');
+    log('     - docs/DAY-ONE-CHECKLIST.md (first day guide)');
+    log('');
+    log('  3. When ready for client work:');
+    log('     /client-switch [client-name]');
+    log('');
+    log('Questions? Ask your team buddy or check docs/FAQ.md');
+  } else {
+    log('');
+    log(`Setup incomplete - ${issues.length} issue(s) to resolve:`);
+    log('');
+    issues.forEach((issue, i) => {
+      log(`  ${i + 1}. ${issue}`);
+    });
+    log('');
+    log('Fix these issues, then run /onboard again.');
+  }
+
+  log('');
+}
+
+// Status only mode
+function showStatus() {
+  log('');
+  log('Everything Claude Code - Setup Status');
+  log('');
+
+  const checks = [];
+
+  // Node
+  const nodeMajor = parseInt(process.version.slice(1).split('.')[0], 10);
+  checks.push({ name: 'Node.js 18+', ok: nodeMajor >= 18 });
+
+  // Git
+  checks.push({ name: 'Git', ok: runCommand('git --version').success });
+
+  // In repo
+  checks.push({ name: 'Git repository', ok: runCommand('git rev-parse --git-dir').success });
+
+  // Dependencies
+  checks.push({
+    name: 'Dependencies',
+    ok: fs.existsSync(path.join(process.cwd(), 'node_modules')),
+  });
+
+  // Credentials
+  checks.push({ name: 'Credentials', ok: fs.existsSync(path.join(getClaudeDir(), '.env')) });
+
+  // Hooks
+  checks.push({
+    name: 'Hooks config',
+    ok: fs.existsSync(path.join(process.cwd(), 'hooks', 'hooks.json')),
+  });
+
+  checks.forEach((check) => {
+    const status = check.ok ? CHECK : CROSS;
+    log(`  ${status} ${check.name}`);
+  });
+
+  const passed = checks.filter((c) => c.ok).length;
+  log('');
+  log(`${passed}/${checks.length} checks passed`);
+
+  if (passed < checks.length) {
+    log('');
+    log('Run /onboard for guided setup.');
+  }
+
+  log('');
+}
+
+function runOnboard(options = {}) {
+  const { skipChecks = false, status = false } = options;
+
+  if (status) {
+    showStatus();
+    return;
+  }
+
+  log('');
+  log('Welcome to CloudStream Claude Code!');
+  log('');
+  log("Let's get you set up. This takes about 15 minutes.");
+
+  if (!skipChecks) {
+    checkPrerequisites();
+  }
+  checkRepository();
+  checkDependencies();
+  checkCredentials();
+  runHealthCheck();
+  showNextSteps();
+
+  // Exit with appropriate code for CI/CD
+  process.exit(issues.length > 0 ? 1 : 0);
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+const options = {
+  skipChecks: args.includes('--skip-checks'),
+  status: args.includes('--status'),
+};
+
+runOnboard(options);