@agentic15.com/agentic15-claude-zen 1.0.1 → 1.1.0

package/src/core/GitHubConfig.js

@@ -0,0 +1,192 @@
+/**
+ * Copyright 2024-2025 agentic15.com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * GitHubConfig - Manages GitHub integration configuration
+ *
+ * Single Responsibility: Load and validate GitHub settings
+ *
+ * Configuration sources (in order of priority):
+ * 1. Environment variables (highest)
+ * 2. .claude/settings.local.json (user-specific, gitignored)
+ * 3. .claude/settings.json (defaults)
+ * 4. Auto-detection from git remote (fallback for owner/repo)
+ */
+export class GitHubConfig {
+  /**
+   * Initialize configuration loader
+   *
+   * @param {string} projectRoot - Project root directory
+   */
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.config = this.loadConfig();
+  }
+
+  /**
+   * Load configuration from all sources
+   *
+   * @returns {Object} Merged configuration object
+   */
+  loadConfig() {
+    const config = {
+      enabled: true,
+      token: null,
+      owner: null,
+      repo: null,
+      autoCreate: true,
+      autoUpdate: true,
+      autoClose: true
+    };
+
+    // Load from settings.json (defaults)
+    const settingsPath = path.join(this.projectRoot, '.claude', 'settings.json');
+    if (fs.existsSync(settingsPath)) {
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        if (settings.github) {
+          Object.assign(config, settings.github);
+        }
+      } catch (error) {
+        console.warn('⚠ Failed to load .claude/settings.json:', error.message);
+      }
+    }
+
+    // Load from settings.local.json (user overrides)
+    const localSettingsPath = path.join(this.projectRoot, '.claude', 'settings.local.json');
+    if (fs.existsSync(localSettingsPath)) {
+      try {
+        const localSettings = JSON.parse(fs.readFileSync(localSettingsPath, 'utf8'));
+        if (localSettings.github) {
+          Object.assign(config, localSettings.github);
+        }
+      } catch (error) {
+        console.warn('⚠ Failed to load .claude/settings.local.json:', error.message);
+      }
+    }
+
+    // Override with environment variables (highest priority)
+    if (process.env.GITHUB_TOKEN) {
+      config.token = process.env.GITHUB_TOKEN;
+    }
+    if (process.env.GITHUB_OWNER) {
+      config.owner = process.env.GITHUB_OWNER;
+    }
+    if (process.env.GITHUB_REPO) {
+      config.repo = process.env.GITHUB_REPO;
+    }
+    if (process.env.GITHUB_ENABLED !== undefined) {
+      config.enabled = process.env.GITHUB_ENABLED === 'true';
+    }
+    if (process.env.GITHUB_AUTO_CREATE !== undefined) {
+      config.autoCreate = process.env.GITHUB_AUTO_CREATE === 'true';
+    }
+    if (process.env.GITHUB_AUTO_UPDATE !== undefined) {
+      config.autoUpdate = process.env.GITHUB_AUTO_UPDATE === 'true';
+    }
+    if (process.env.GITHUB_AUTO_CLOSE !== undefined) {
+      config.autoClose = process.env.GITHUB_AUTO_CLOSE === 'true';
+    }
+
+    // Auto-detect owner/repo from git remote if not configured
+    if (!config.owner || !config.repo) {
+      try {
+        const remote = execSync('git remote get-url origin', {
+          cwd: this.projectRoot,
+          encoding: 'utf8'
+        }).trim();
+
+        // Parse GitHub URL formats:
+        // - https://github.com/owner/repo.git
+        // - git@github.com:owner/repo.git
+        const match = remote.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+        if (match) {
+          config.owner = config.owner || match[1];
+          config.repo = config.repo || match[2];
+        }
+      } catch (error) {
+        // Git remote not configured or not a git repository
+        // This is okay - GitHub integration will be disabled
+      }
+    }
+
+    return config;
+  }
+
+  /**
+   * Get GitHub Personal Access Token
+   *
+   * @returns {string|null} Token or null if not configured
+   */
+  getToken() {
+    return this.config.token;
+  }
+
+  /**
+   * Get repository owner and name
+   *
+   * @returns {Object} { owner: string|null, repo: string|null }
+   */
+  getRepoInfo() {
+    return {
+      owner: this.config.owner,
+      repo: this.config.repo
+    };
+  }
+
+  /**
+   * Check if GitHub integration is fully enabled and configured
+   *
+   * @returns {boolean} True if ready to use, false otherwise
+   */
+  isEnabled() {
+    return this.config.enabled &&
+           this.config.token !== null &&
+           this.config.owner !== null &&
+           this.config.repo !== null;
+  }
+
+  /**
+   * Check if auto-create issues feature is enabled
+   *
+   * @returns {boolean} True if enabled, false otherwise
+   */
+  isAutoCreateEnabled() {
+    return this.isEnabled() && this.config.autoCreate;
+  }
+
+  /**
+   * Check if auto-update issues feature is enabled
+   *
+   * @returns {boolean} True if enabled, false otherwise
+   */
+  isAutoUpdateEnabled() {
+    return this.isEnabled() && this.config.autoUpdate;
+  }
+
+  /**
+   * Check if auto-close issues feature is enabled
+   *
+   * @returns {boolean} True if enabled, false otherwise
+   */
+  isAutoCloseEnabled() {
+    return this.isEnabled() && this.config.autoClose;
+  }
+}

package/src/core/HookInstaller.js

@@ -1,54 +1,71 @@
-/**
- * Copyright 2024-2025 agentic15.com
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { writeFileSync } from 'fs';
-import { join } from 'path';
-
-/**
- * HookInstaller - Installs git hooks
- *
- * Single Responsibility: Setup git hooks in project
- */
-export class HookInstaller {
-  /**
-   * Install git hooks
-   *
-   * @param {string} targetDir - Target directory path
-   */
-  async install(targetDir) {
-    console.log('\n🔗 Setting up Git hooks...');
-    try {
-      const gitHooksDir = join(targetDir, '.git', 'hooks');
-
-      // Create pre-commit hook (reminder that hooks run via Claude Code)
-      const preCommitHook = `#!/bin/sh
-# agentic15-claude-zen pre-commit hook
-# This hook is CRITICAL for enforcement
-
-echo "⚠️  agentic15-claude-zen git hooks are NOT yet active"
-echo "   Hooks run via Claude Code settings.json, not git hooks"
-echo "   This is just a reminder"
-exit 0
-`;
-
-      writeFileSync(join(gitHooksDir, 'pre-commit'), preCommitHook, { mode: 0o755 });
-      console.log('✅ Git hooks configured');
-    } catch (error) {
-      console.log('⚠️  Warning: Git hooks setup failed');
-      console.log(`   Error: ${error.message}`);
-    }
-  }
-}
+/**
+ * Copyright 2024-2025 agentic15.com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { writeFileSync, readFileSync, existsSync, chmodSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * HookInstaller - Installs git hooks
+ *
+ * Single Responsibility: Setup git hooks in project
+ */
+export class HookInstaller {
+  /**
+   * Install git hooks
+   *
+   * @param {string} targetDir - Target directory path
+   */
+  async install(targetDir) {
+    console.log('\n🔗 Setting up Git hooks...');
+    try {
+      const gitHooksDir = join(targetDir, '.git', 'hooks');
+      const claudeHooksDir = join(targetDir, '.claude', 'hooks');
+
+      // Create pre-commit hook (reminder that hooks run via Claude Code)
+      const preCommitHook = `#!/bin/sh
+# agentic15-claude-zen pre-commit hook
+# This hook is CRITICAL for enforcement
+
+echo "⚠️  agentic15-claude-zen git hooks are NOT yet active"
+echo "   Hooks run via Claude Code settings.json, not git hooks"
+echo "   This is just a reminder"
+exit 0
+`;
+
+      writeFileSync(join(gitHooksDir, 'pre-commit'), preCommitHook, { mode: 0o755 });
+
+      // Install post-merge hook for GitHub issue auto-close
+      const postMergeSource = join(claudeHooksDir, 'post-merge.js');
+      if (existsSync(postMergeSource)) {
+        const postMergeContent = readFileSync(postMergeSource, 'utf8');
+        const postMergeHook = join(gitHooksDir, 'post-merge');
+        writeFileSync(postMergeHook, postMergeContent, { mode: 0o755 });
+        try {
+          chmodSync(postMergeHook, 0o755);
+        } catch (chmodError) {
+          // chmod might fail on some systems, but file should still be executable
+        }
+        console.log('✅ Git hooks configured (including post-merge for GitHub integration)');
+      } else {
+        console.log('✅ Git hooks configured');
+      }
+    } catch (error) {
+      console.log('⚠️  Warning: Git hooks setup failed');
+      console.log(`   Error: ${error.message}`);
+    }
+  }
+}

package/src/core/TaskIssueMapper.js

@@ -0,0 +1,137 @@
+/**
+ * Copyright 2024-2025 agentic15.com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * TaskIssueMapper - Maps task data to GitHub issue format
+ *
+ * Single Responsibility: Convert between task and issue representations
+ *
+ * This class provides static methods for mapping task JSON structure
+ * to GitHub issue format (title, body, labels).
+ */
+export class TaskIssueMapper {
+  /**
+   * Generate GitHub issue title from task
+   *
+   * @param {Object} task - Task object
+   * @returns {string} Issue title
+   */
+  static taskToIssueTitle(task) {
+    return `[${task.id}] ${task.title}`;
+  }
+
+  /**
+   * Generate GitHub issue body from task
+   *
+   * @param {Object} task - Task object
+   * @returns {string} Issue body in markdown format
+   */
+  static taskToIssueBody(task) {
+    let body = `## Task: ${task.title}\n\n`;
+
+    if (task.description) {
+      body += `${task.description}\n\n`;
+    }
+
+    if (task.phase) {
+      body += `**Phase:** ${task.phase}\n`;
+    }
+
+    if (task.estimatedHours) {
+      body += `**Estimated Hours:** ${task.estimatedHours}h\n`;
+    }
+
+    if (task.completionCriteria && task.completionCriteria.length > 0) {
+      body += `\n### Completion Criteria\n\n`;
+      task.completionCriteria.forEach(criteria => {
+        body += `- [ ] ${criteria}\n`;
+      });
+    }
+
+    if (task.dependencies && task.dependencies.length > 0) {
+      body += `\n### Dependencies\n\n`;
+      task.dependencies.forEach(dep => {
+        body += `- ${dep}\n`;
+      });
+    }
+
+    if (task.testCases && task.testCases.length > 0) {
+      body += `\n### Test Cases\n\n`;
+      task.testCases.forEach(test => {
+        body += `- ${test}\n`;
+      });
+    }
+
+    body += `\n---\n*Auto-created by Agentic15 Claude Zen*`;
+
+    return body;
+  }
+
+  /**
+   * Map task status and phase to GitHub labels
+   *
+   * @param {string} status - Task status (pending, in_progress, completed, blocked)
+   * @param {string|null} phase - Task phase (design, implementation, testing, etc.)
+   * @returns {string[]} Array of label names
+   */
+  static taskStatusToLabels(status, phase = null) {
+    const labels = [];
+
+    // Status labels
+    switch (status) {
+      case 'pending':
+        labels.push('status: pending');
+        break;
+      case 'in_progress':
+        labels.push('status: in-progress');
+        break;
+      case 'completed':
+        labels.push('status: completed');
+        break;
+      case 'blocked':
+        labels.push('status: blocked');
+        break;
+    }
+
+    // Phase labels
+    if (phase) {
+      const phaseLabel = this.phaseToLabel(phase);
+      if (phaseLabel) {
+        labels.push(phaseLabel);
+      }
+    }
+
+    return labels;
+  }
+
+  /**
+   * Convert phase name to GitHub label
+   *
+   * @param {string} phase - Phase name
+   * @returns {string} Label name
+   */
+  static phaseToLabel(phase) {
+    const phaseLabels = {
+      'design': 'phase: design',
+      'implementation': 'phase: implementation',
+      'testing': 'phase: testing',
+      'deployment': 'phase: deployment',
+      'documentation': 'phase: documentation'
+    };
+
+    return phaseLabels[phase] || `phase: ${phase}`;
+  }
+}

package/src/utils/updateTaskGitHubStatus.js

@@ -0,0 +1,81 @@
+/**
+ * Copyright 2024-2025 agentic15.com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { GitHubConfig } from '../core/GitHubConfig.js';
+import { GitHubClient } from '../core/GitHubClient.js';
+import { TaskIssueMapper } from '../core/TaskIssueMapper.js';
+
+/**
+ * Update GitHub issue status when task state changes
+ *
+ * This utility function is used by various hooks to keep GitHub issues
+ * in sync with local task status changes.
+ *
+ * @param {Object} taskData - Task JSON object
+ * @param {string} projectRoot - Path to project root directory
+ * @param {string} newStatus - New task status (pending, in_progress, completed, blocked)
+ * @param {Object} options - Optional parameters
+ * @param {string} options.comment - Optional comment to add to the issue
+ * @returns {Promise<boolean>} - Success status
+ */
+export async function updateTaskGitHubStatus(taskData, projectRoot, newStatus, options = {}) {
+  try {
+    // Load GitHub configuration
+    const githubConfig = new GitHubConfig(projectRoot);
+
+    // Check if auto-update is enabled
+    if (!githubConfig.isAutoUpdateEnabled()) {
+      return false;
+    }
+
+    // Check if task has associated GitHub issue
+    if (!taskData.githubIssue) {
+      return false;
+    }
+
+    // Initialize GitHub client
+    const { owner, repo } = githubConfig.getRepoInfo();
+    const githubClient = new GitHubClient(
+      githubConfig.getToken(),
+      owner,
+      repo
+    );
+
+    // Update issue labels based on new status
+    const labels = TaskIssueMapper.taskStatusToLabels(newStatus, taskData.phase);
+    const labelsUpdated = await githubClient.updateIssueLabels(taskData.githubIssue, labels);
+
+    if (!labelsUpdated) {
+      console.warn(`⚠ Failed to update GitHub issue #${taskData.githubIssue} labels`);
+      return false;
+    }
+
+    // Add comment if provided
+    if (options.comment) {
+      const commentAdded = await githubClient.addIssueComment(taskData.githubIssue, options.comment);
+      if (!commentAdded) {
+        console.warn(`⚠ Failed to add comment to GitHub issue #${taskData.githubIssue}`);
+      }
+    }
+
+    console.log(`✓ Updated GitHub issue #${taskData.githubIssue} to ${newStatus}`);
+    return true;
+
+  } catch (error) {
+    console.warn('⚠ Failed to update GitHub issue status:', error.message);
+    return false;
+  }
+}