specweave 0.12.0 → 0.12.1

package/plugins/specweave-github/commands/specweave-github-sync-from.md

@@ -0,0 +1,147 @@
+---
+name: specweave-github:sync-from
+description: Sync state from GitHub to SpecWeave (bidirectional sync). Fetches issue state, comments, and detects conflicts.
+---
+
+# Sync from GitHub to SpecWeave
+
+Bidirectional sync - pull changes from GitHub issue back to SpecWeave increment.
+
+## Usage
+
+```bash
+/specweave-github:sync-from <incrementId>
+```
+
+## What It Does
+
+1. **Fetches GitHub Issue State**:
+   - Issue status (open/closed)
+   - Comments
+   - Labels, assignees, milestones
+   - Last updated timestamp
+
+2. **Detects Conflicts**:
+   - GitHub closed but SpecWeave active
+   - SpecWeave completed but GitHub open
+   - GitHub abandoned but issue open
+
+3. **Syncs Comments**:
+   - Saves GitHub comments to `.specweave/increments/<id>/logs/github-comments.md`
+   - Only syncs new comments (tracks IDs)
+
+4. **Updates Metadata**:
+   - Updates `metadata.json` with latest GitHub state
+   - Tracks last sync timestamp
+
+## Examples
+
+### Basic Sync
+
+```bash
+/specweave-github:sync-from 0015-hierarchical-sync
+```
+
+**Output**:
+```
+🔄 Syncing from GitHub for increment: 0015-hierarchical-sync
+   Syncing from anton-abyzov/specweave#29
+✅ No conflicts - GitHub and SpecWeave in sync
+📝 Syncing 3 new comment(s)
+✅ Comments saved to: logs/github-comments.md
+✅ Metadata updated
+✅ Bidirectional sync complete
+```
+
+### Conflict Detection
+
+```bash
+/specweave-github:sync-from 0015-hierarchical-sync
+```
+
+**Output**:
+```
+🔄 Syncing from GitHub for increment: 0015-hierarchical-sync
+   Syncing from anton-abyzov/specweave#29
+⚠️  Detected 1 conflict(s)
+
+⚠️  Conflict detected: status
+   GitHub: closed
+   SpecWeave: active
+
+⚠️  **CONFLICT**: GitHub issue closed but SpecWeave increment still active!
+   Recommendation: Run /specweave:done 0015-hierarchical-sync to close increment
+   Or reopen issue on GitHub if work is not complete
+
+✅ Bidirectional sync complete
+```
+
+## When to Use
+
+Use this command when:
+- ✅ Someone closed/reopened the GitHub issue
+- ✅ Comments were added on GitHub (want to import them)
+- ✅ Want to check if GitHub and SpecWeave are in sync
+- ✅ Resolving conflicts between GitHub and SpecWeave state
+
+## Requirements
+
+- GitHub CLI (`gh`) installed and authenticated
+- GitHub issue linked in metadata.json
+- Repository has GitHub remote configured
+
+## Conflict Resolution
+
+### GitHub Closed, SpecWeave Active
+
+**Resolution**: Close SpecWeave increment
+```bash
+/specweave:done 0015-hierarchical-sync
+```
+
+**Or**: Reopen GitHub issue if work not complete
+```bash
+gh issue reopen 29
+```
+
+### SpecWeave Completed, GitHub Open
+
+**Resolution**: Close GitHub issue
+```bash
+gh issue close 29 --comment "Increment completed in SpecWeave"
+```
+
+### SpecWeave Abandoned, GitHub Open
+
+**Resolution**: Close GitHub issue with reason
+```bash
+gh issue close 29 --comment "Increment abandoned: Requirements changed"
+```
+
+## Files Modified
+
+- `.specweave/increments/<id>/logs/github-comments.md` - GitHub comments
+- `.specweave/increments/<id>/metadata.json` - Sync metadata
+
+## Related Commands
+
+- `/specweave-github:sync` - One-way sync (SpecWeave → GitHub)
+- `/specweave-github:create-issue` - Create GitHub issue
+- `/specweave-github:close-issue` - Close GitHub issue
+- `/specweave-github:status` - Check sync status
+
+## Automation
+
+For automatic bidirectional sync, add to cron or CI/CD:
+
+```bash
+# Sync all active increments hourly
+0 * * * * cd /path/to/project && \
+  for inc in $(ls .specweave/increments/ | grep -v _backlog); do \
+    /specweave-github:sync-from $inc; \
+  done
+```
+
+## Implementation
+
+Invokes `github-sync-bidirectional` agent with conflict detection and resolution logic.

package/plugins/specweave-github/lib/cli-sync-increment-changes.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+/**
+ * CLI wrapper for syncing increment changes to GitHub
+ *
+ * Usage:
+ *   node dist/plugins/specweave-github/lib/cli-sync-increment-changes.js <incrementId> <changedFile>
+ *
+ * Example:
+ *   node dist/plugins/specweave-github/lib/cli-sync-increment-changes.js 0015-hierarchical-sync spec.md
+ */
+
+import { syncIncrementChanges } from './github-sync-increment-changes.js';
+
+const incrementId = process.argv[2];
+const changedFile = process.argv[3] as 'spec.md' | 'plan.md' | 'tasks.md';
+
+if (!incrementId || !changedFile) {
+  console.error('❌ Usage: cli-sync-increment-changes <incrementId> <changedFile>');
+  console.error('   Example: cli-sync-increment-changes 0015-hierarchical-sync spec.md');
+  process.exit(1);
+}
+
+if (!['spec.md', 'plan.md', 'tasks.md'].includes(changedFile)) {
+  console.error(`❌ Invalid file: ${changedFile}`);
+  console.error('   Must be one of: spec.md, plan.md, tasks.md');
+  process.exit(1);
+}
+
+syncIncrementChanges(incrementId, changedFile).catch((error) => {
+  console.error('❌ Fatal error:', error);
+  // Don't exit with error code - best-effort sync
+});

package/plugins/specweave-github/lib/github-issue-updater.ts

@@ -0,0 +1,449 @@
+/**
+ * GitHub Issue Updater for Living Docs Sync
+ *
+ * Handles updating GitHub issues with living documentation links and content.
+ * Used by post-task-completion hook to keep GitHub issues in sync with SpecWeave docs.
+ *
+ * @module github-issue-updater
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+
+export interface LivingDocsSection {
+  specs: string[];
+  architecture: string[];
+  diagrams: string[];
+}
+
+export interface IncrementMetadata {
+  id: string;
+  status: string;
+  type: string;
+  github?: {
+    issue: number;
+    url: string;
+    synced?: string;
+  };
+}
+
+/**
+ * Update GitHub issue with living docs section
+ */
+export async function updateIssueLivingDocs(
+  issueNumber: number,
+  livingDocs: LivingDocsSection,
+  owner: string,
+  repo: string
+): Promise<void> {
+  console.log(`📝 Updating GitHub issue #${issueNumber} with living docs...`);
+
+  // 1. Get current issue body
+  const currentBody = await getIssueBody(issueNumber, owner, repo);
+
+  // 2. Build living docs section
+  const livingDocsSection = buildLivingDocsSection(livingDocs, owner, repo);
+
+  // 3. Update or append living docs section
+  const updatedBody = updateBodyWithLivingDocs(currentBody, livingDocsSection);
+
+  // 4. Update issue
+  await updateIssueBody(issueNumber, updatedBody, owner, repo);
+
+  console.log(`✅ Living docs section updated in issue #${issueNumber}`);
+}
+
+/**
+ * Post comment about ADR/HLD/diagram creation
+ */
+export async function postArchitectureComment(
+  issueNumber: number,
+  docPath: string,
+  owner: string,
+  repo: string
+): Promise<void> {
+  const docType = getDocType(docPath);
+  const docName = path.basename(docPath, '.md');
+  const docUrl = `https://github.com/${owner}/${repo}/blob/develop/${docPath}`;
+
+  const comment = `
+🏗️ **${docType} Created**
+
+**Document**: [${docName}](${docUrl})
+
+**Path**: \`${docPath}\`
+
+---
+🤖 Auto-updated by SpecWeave
+`.trim();
+
+  await postComment(issueNumber, comment, owner, repo);
+  console.log(`✅ Posted ${docType} comment to issue #${issueNumber}`);
+}
+
+/**
+ * Post scope change comment
+ */
+export async function postScopeChangeComment(
+  issueNumber: number,
+  changes: {
+    added?: string[];
+    removed?: string[];
+    modified?: string[];
+    reason?: string;
+    impact?: string;
+  },
+  owner: string,
+  repo: string
+): Promise<void> {
+  const parts: string[] = ['**Scope Change Detected**', ''];
+
+  if (changes.added && changes.added.length > 0) {
+    parts.push('**Added**:');
+    changes.added.forEach(item => parts.push(`- ✅ ${item}`));
+    parts.push('');
+  }
+
+  if (changes.removed && changes.removed.length > 0) {
+    parts.push('**Removed**:');
+    changes.removed.forEach(item => parts.push(`- ❌ ${item}`));
+    parts.push('');
+  }
+
+  if (changes.modified && changes.modified.length > 0) {
+    parts.push('**Modified**:');
+    changes.modified.forEach(item => parts.push(`- 🔄 ${item}`));
+    parts.push('');
+  }
+
+  if (changes.reason) {
+    parts.push(`**Reason**: ${changes.reason}`);
+    parts.push('');
+  }
+
+  if (changes.impact) {
+    parts.push(`**Impact**: ${changes.impact}`);
+    parts.push('');
+  }
+
+  parts.push('---');
+  parts.push('🤖 Auto-updated by SpecWeave');
+
+  await postComment(issueNumber, parts.join('\n'), owner, repo);
+  console.log(`✅ Posted scope change comment to issue #${issueNumber}`);
+}
+
+/**
+ * Post status change comment (pause/resume/abandon)
+ */
+export async function postStatusChangeComment(
+  issueNumber: number,
+  status: 'paused' | 'resumed' | 'abandoned',
+  reason: string,
+  owner: string,
+  repo: string
+): Promise<void> {
+  const emoji = {
+    paused: '⏸️',
+    resumed: '▶️',
+    abandoned: '🗑️'
+  }[status];
+
+  const title = {
+    paused: 'Increment Paused',
+    resumed: 'Increment Resumed',
+    abandoned: 'Increment Abandoned'
+  }[status];
+
+  const comment = `
+${emoji} **${title}**
+
+**Reason**: ${reason}
+
+**Timestamp**: ${new Date().toISOString()}
+
+---
+🤖 Auto-updated by SpecWeave
+`.trim();
+
+  await postComment(issueNumber, comment, owner, repo);
+  console.log(`✅ Posted ${status} comment to issue #${issueNumber}`);
+}
+
+/**
+ * Collect living docs for an increment
+ */
+export async function collectLivingDocs(incrementId: string): Promise<LivingDocsSection> {
+  const livingDocs: LivingDocsSection = {
+    specs: [],
+    architecture: [],
+    diagrams: []
+  };
+
+  // 1. Find specs
+  const specsDir = path.join(process.cwd(), '.specweave/docs/internal/specs');
+  if (await fs.pathExists(specsDir)) {
+    const specFiles = await fs.readdir(specsDir);
+    for (const file of specFiles) {
+      if (file.endsWith('.md') && !file.startsWith('README')) {
+        livingDocs.specs.push(path.join('.specweave/docs/internal/specs', file));
+      }
+    }
+  }
+
+  // 2. Find architecture docs (ADRs, HLDs)
+  const archDir = path.join(process.cwd(), '.specweave/docs/internal/architecture');
+  if (await fs.pathExists(archDir)) {
+    // ADRs
+    const adrDir = path.join(archDir, 'adr');
+    if (await fs.pathExists(adrDir)) {
+      const adrFiles = await fs.readdir(adrDir);
+      for (const file of adrFiles) {
+        if (file.endsWith('.md')) {
+          livingDocs.architecture.push(path.join('.specweave/docs/internal/architecture/adr', file));
+        }
+      }
+    }
+
+    // HLDs
+    const hldFiles = await fs.readdir(archDir);
+    for (const file of hldFiles) {
+      if (file.startsWith('hld-') && file.endsWith('.md')) {
+        livingDocs.architecture.push(path.join('.specweave/docs/internal/architecture', file));
+      }
+    }
+  }
+
+  // 3. Find diagrams
+  const diagramsDir = path.join(process.cwd(), '.specweave/docs/internal/architecture/diagrams');
+  if (await fs.pathExists(diagramsDir)) {
+    const diagramFiles = await fs.readdir(diagramsDir);
+    for (const file of diagramFiles) {
+      if (file.endsWith('.mmd') || file.endsWith('.svg')) {
+        livingDocs.diagrams.push(path.join('.specweave/docs/internal/architecture/diagrams', file));
+      }
+    }
+  }
+
+  return livingDocs;
+}
+
+/**
+ * Load increment metadata
+ */
+export async function loadIncrementMetadata(incrementId: string): Promise<IncrementMetadata | null> {
+  const metadataPath = path.join(
+    process.cwd(),
+    '.specweave/increments',
+    incrementId,
+    'metadata.json'
+  );
+
+  if (!await fs.pathExists(metadataPath)) {
+    return null;
+  }
+
+  return await fs.readJson(metadataPath);
+}
+
+/**
+ * Detect repository owner and name from git remote
+ */
+export async function detectRepo(): Promise<{ owner: string; repo: string } | null> {
+  try {
+    const result = await execFileNoThrow('git', ['remote', 'get-url', 'origin']);
+
+    if (result.status !== 0) {
+      return null;
+    }
+
+    const remote = result.stdout.trim();
+    const match = remote.match(/github\.com[:/](.+)\/(.+?)(?:\.git)?$/);
+
+    if (!match) {
+      return null;
+    }
+
+    return {
+      owner: match[1],
+      repo: match[2]
+    };
+  } catch (error) {
+    return null;
+  }
+}
+
+// =============================================================================
+// PRIVATE HELPERS
+// =============================================================================
+
+/**
+ * Get current issue body
+ */
+async function getIssueBody(
+  issueNumber: number,
+  owner: string,
+  repo: string
+): Promise<string> {
+  const result = await execFileNoThrow('gh', [
+    'issue',
+    'view',
+    String(issueNumber),
+    '--repo',
+    `${owner}/${repo}`,
+    '--json',
+    'body',
+    '-q',
+    '.body'
+  ]);
+
+  if (result.status !== 0) {
+    throw new Error(`Failed to get issue body: ${result.stderr}`);
+  }
+
+  return result.stdout.trim();
+}
+
+/**
+ * Update issue body
+ */
+async function updateIssueBody(
+  issueNumber: number,
+  body: string,
+  owner: string,
+  repo: string
+): Promise<void> {
+  const result = await execFileNoThrow('gh', [
+    'issue',
+    'edit',
+    String(issueNumber),
+    '--repo',
+    `${owner}/${repo}`,
+    '--body',
+    body
+  ]);
+
+  if (result.status !== 0) {
+    throw new Error(`Failed to update issue body: ${result.stderr}`);
+  }
+}
+
+/**
+ * Post comment to issue
+ */
+async function postComment(
+  issueNumber: number,
+  comment: string,
+  owner: string,
+  repo: string
+): Promise<void> {
+  const result = await execFileNoThrow('gh', [
+    'issue',
+    'comment',
+    String(issueNumber),
+    '--repo',
+    `${owner}/${repo}`,
+    '--body',
+    comment
+  ]);
+
+  if (result.status !== 0) {
+    throw new Error(`Failed to post comment: ${result.stderr}`);
+  }
+}
+
+/**
+ * Build living docs section for issue body
+ */
+function buildLivingDocsSection(
+  livingDocs: LivingDocsSection,
+  owner: string,
+  repo: string
+): string {
+  const parts: string[] = ['## 📚 Living Documentation', ''];
+
+  // Specs
+  if (livingDocs.specs.length > 0) {
+    parts.push('**Specifications**:');
+    livingDocs.specs.forEach(spec => {
+      const name = path.basename(spec, '.md');
+      const url = `https://github.com/${owner}/${repo}/blob/develop/${spec}`;
+      parts.push(`- [${name}](${url})`);
+    });
+    parts.push('');
+  }
+
+  // Architecture
+  if (livingDocs.architecture.length > 0) {
+    parts.push('**Architecture**:');
+    livingDocs.architecture.forEach(doc => {
+      const name = path.basename(doc, '.md');
+      const url = `https://github.com/${owner}/${repo}/blob/develop/${doc}`;
+      parts.push(`- [${name}](${url})`);
+    });
+    parts.push('');
+  }
+
+  // Diagrams
+  if (livingDocs.diagrams.length > 0) {
+    parts.push('**Diagrams**:');
+    livingDocs.diagrams.forEach(diagram => {
+      const name = path.basename(diagram);
+      const url = `https://github.com/${owner}/${repo}/blob/develop/${diagram}`;
+      parts.push(`- [${name}](${url})`);
+    });
+    parts.push('');
+  }
+
+  parts.push('---');
+
+  return parts.join('\n');
+}
+
+/**
+ * Update body with living docs section
+ */
+function updateBodyWithLivingDocs(
+  currentBody: string,
+  livingDocsSection: string
+): string {
+  // Check if living docs section already exists
+  const marker = '## 📚 Living Documentation';
+
+  if (currentBody.includes(marker)) {
+    // Replace existing section
+    const beforeMarker = currentBody.substring(0, currentBody.indexOf(marker));
+    const afterMarker = currentBody.substring(currentBody.indexOf(marker));
+
+    // Find end of section (next ## header or end of body)
+    const nextSection = afterMarker.indexOf('\n## ', 1);
+    const replacement = nextSection > 0
+      ? afterMarker.substring(0, nextSection)
+      : afterMarker;
+
+    return beforeMarker + livingDocsSection + (nextSection > 0 ? afterMarker.substring(nextSection) : '');
+  } else {
+    // Append at end
+    return currentBody + '\n\n' + livingDocsSection;
+  }
+}
+
+/**
+ * Determine document type from path
+ */
+function getDocType(docPath: string): string {
+  if (docPath.includes('/adr/')) {
+    return 'Architecture Decision Record (ADR)';
+  }
+  if (docPath.includes('/diagrams/')) {
+    return 'Architecture Diagram';
+  }
+  if (docPath.startsWith('hld-')) {
+    return 'High-Level Design (HLD)';
+  }
+  if (docPath.includes('/specs/')) {
+    return 'Specification';
+  }
+  return 'Documentation';
+}