specweave 2.3.0 → 3.0.1

package/plugins/specweave/lib/integrations/github/github-feature-sync-cli.ts

@@ -1,243 +0,0 @@
-#!/usr/bin/env node
-/**
- * GitHub Feature Sync CLI
- *
- * CLI wrapper for GitHubFeatureSync.syncFeatureToGitHub()
- * Called by post-increment-planning.sh hook to create GitHub issues
- * after increment creation.
- *
- * Usage:
- *   node github-feature-sync-cli.js <feature-id>
- *   node github-feature-sync-cli.js FS-062
- *
- * Environment:
- *   GITHUB_TOKEN - Required
- *   GITHUB_OWNER - Optional (detected from config.json or git remote)
- *   GITHUB_REPO  - Optional (detected from config.json or git remote)
- *
- * @see ADR-0139 (Unified Post-Increment Sync)
- */
-
-import { existsSync, readFileSync } from 'fs';
-import * as path from 'path';
-import { GitHubFeatureSync } from './github-feature-sync.js';
-import { GitHubClientV2 } from './github-client-v2.js';
-
-interface GitHubConfig {
-  owner: string;
-  repo: string;
-  token: string;
-}
-
-/**
- * Resolve GitHub config (owner/repo) with a single canonical precedence order.
- *
- * Resolution order (documented for both CLI and hooks):
- * 1. CLI flags / env vars: GITHUB_OWNER, GITHUB_REPO
- * 2. .specweave/config.json — sync.github.owner/repo
- * 3. .specweave/config.json — multiProject.projects[active].externalTools.github
- * 4. .specweave/config.json — sync.profiles[defaultProfile].config
- * 5. .specweave/config.json — first GitHub profile (fallback)
- * 6. Git remote detection (git remote get-url origin)
- *
- * This is the SINGLE source of truth for owner/repo config.
- * Shell hooks should read the same config.json paths in the same order.
- */
-export async function resolveGitHubConfig(options?: {
-  cliOwner?: string;
-  cliRepo?: string;
-  cliToken?: string;
-  projectRoot?: string;
-}): Promise<{ owner: string; repo: string; token: string } | null> {
-  const projectRoot = options?.projectRoot || process.cwd();
-  const configPath = path.join(projectRoot, '.specweave/config.json');
-
-  // Step 1: CLI flags / env vars (highest precedence)
-  let owner = options?.cliOwner || process.env.GITHUB_OWNER || '';
-  let repo = options?.cliRepo || process.env.GITHUB_REPO || '';
-  const token = options?.cliToken || process.env.GITHUB_TOKEN || '';
-
-  // Step 2-5: config.json methods (only if not already resolved)
-  if ((!owner || !repo) && existsSync(configPath)) {
-    try {
-      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-
-      // Method 2: sync.github
-      if (!owner && !repo && config.sync?.github?.owner && config.sync?.github?.repo) {
-        owner = config.sync.github.owner;
-        repo = config.sync.github.repo;
-      }
-      // Method 3: multiProject.projects[activeProject].externalTools.github
-      if (!owner && !repo && config.multiProject?.enabled && config.multiProject?.activeProject) {
-        const activeProject = config.multiProject.activeProject;
-        const projectConfig = config.multiProject.projects?.[activeProject];
-        if (projectConfig?.externalTools?.github?.repository) {
-          const parts = projectConfig.externalTools.github.repository.split('/');
-          if (parts.length === 2) {
-            owner = parts[0];
-            repo = parts[1];
-          }
-        }
-      }
-      // Method 4: sync.profiles[defaultProfile]
-      if (!owner && !repo && config.sync?.defaultProfile && config.sync?.profiles) {
-        const profile = config.sync.profiles[config.sync.defaultProfile];
-        if (profile?.config?.owner && profile?.config?.repo) {
-          owner = profile.config.owner;
-          repo = profile.config.repo;
-        }
-      }
-      // Method 5: First GitHub profile if no defaultProfile is set
-      if (!owner && !repo && config.sync?.profiles) {
-        const profileNames = Object.keys(config.sync.profiles);
-        for (const name of profileNames) {
-          const profile = config.sync.profiles[name];
-          if (profile?.provider === 'github' && profile?.config?.owner && profile?.config?.repo) {
-            owner = profile.config.owner;
-            repo = profile.config.repo;
-            console.log(`ℹ️  Using first GitHub profile: ${name}`);
-            break;
-          }
-        }
-      }
-    } catch (error) {
-      console.error('⚠️  Failed to parse config.json:', error);
-    }
-  }
-
-  // Step 6: Git remote detection (lowest precedence)
-  if (!owner || !repo) {
-    try {
-      const { execSync } = await import('child_process');
-      const remoteUrl = execSync('git remote get-url origin 2>/dev/null', {
-        encoding: 'utf-8',
-        cwd: projectRoot
-      }).trim();
-
-      const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
-      if (match) {
-        owner = owner || match[1];
-        repo = repo || match[2];
-      }
-    } catch {
-      // Git detection failed
-    }
-  }
-
-  if (!token) {
-    console.error('❌ GITHUB_TOKEN not set');
-    console.error('   Set it in .env file or export GITHUB_TOKEN=ghp_xxx');
-    return null;
-  }
-
-  if (!owner || !repo) {
-    console.error('❌ Could not detect GitHub owner/repo');
-    console.error('   Set sync.github.owner and sync.github.repo in .specweave/config.json');
-    return null;
-  }
-
-  return { owner, repo, token };
-}
-
-async function loadGitHubConfig(): Promise<GitHubConfig | null> {
-  return resolveGitHubConfig();
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log('Usage: node github-feature-sync-cli.js <feature-id>');
-    console.log('');
-    console.log('Arguments:');
-    console.log('  feature-id   Feature ID (e.g., FS-062)');
-    console.log('');
-    console.log('Environment:');
-    console.log('  GITHUB_TOKEN  Required - GitHub PAT with repo scope');
-    console.log('');
-    console.log('Example:');
-    console.log('  GITHUB_TOKEN=ghp_xxx node github-feature-sync-cli.js FS-062');
-    process.exit(args.length === 0 ? 1 : 0);
-  }
-
-  const featureId = args[0];
-
-  // Validate feature ID format
-  if (!featureId.match(/^FS-\d+$/i)) {
-    console.error(`❌ Invalid feature ID: ${featureId}`);
-    console.error('   Expected format: FS-XXX (e.g., FS-062)');
-    process.exit(1);
-  }
-
-  console.log(`\n🐙 GitHub Feature Sync CLI`);
-  console.log(`   Feature: ${featureId}`);
-
-  // Load config
-  const config = await loadGitHubConfig();
-  if (!config) {
-    process.exit(1);
-  }
-
-  console.log(`   Repository: ${config.owner}/${config.repo}`);
-
-  // Create client and sync
-  const projectRoot = process.cwd();
-  const specsDir = path.join(projectRoot, '.specweave/docs/internal/specs');
-
-  const profile = {
-    provider: 'github' as const,
-    displayName: 'GitHub',
-    config: {
-      owner: config.owner,
-      repo: config.repo,
-      token: config.token
-    },
-    timeRange: {
-      default: '1M' as const,
-      max: '3M' as const
-    }
-  };
-
-  const client = new GitHubClientV2(profile);
-  const sync = new GitHubFeatureSync(client, specsDir, projectRoot);
-
-  try {
-    console.log(`\n🔄 Syncing ${featureId} to GitHub...`);
-
-    const result = await sync.syncFeatureToGitHub(featureId);
-
-    // FS-609: Surface rate limit skip instead of misleading "Sync complete!"
-    if (result.rateLimitSkipped) {
-      console.log(`\n⚠️  Sync skipped — GitHub API rate limit too low`);
-      console.log(`   💡 Run 'specweave sync push' to retry when the rate limit resets`);
-      process.exit(2); // Non-zero exit signals skip (not failure)
-    }
-
-    console.log(`\n✅ Sync complete!`);
-    console.log(`   🎯 Milestone: #${result.milestoneNumber}`);
-    console.log(`   📝 Issues created: ${result.issuesCreated}`);
-    console.log(`   🔄 Issues updated: ${result.issuesUpdated}`);
-    console.log(`   📚 User stories processed: ${result.userStoriesProcessed}`);
-
-    if (result.milestoneUrl) {
-      console.log(`   🔗 ${result.milestoneUrl}`);
-    }
-
-    process.exit(0);
-  } catch (error: unknown) {
-    // FIXED (v1.0.302): Write errors to stdout too, since stderr may be suppressed
-    // by run_with_timeout() in shell handlers. This ensures errors appear in throttle.log.
-    const msg = error instanceof Error ? error.message : String(error);
-    console.log(`\n[ERROR] Sync failed for ${featureId}: ${msg}`);
-    console.error(`\n❌ Sync failed:`, error);
-    process.exit(1);
-  }
-}
-
-// Run CLI
-main().catch(error => {
-  const msg = error instanceof Error ? error.message : String(error);
-  console.log(`[FATAL] ${msg}`);
-  console.error('Fatal error:', error);
-  process.exit(1);
-});

package/plugins/specweave/lib/integrations/github/github-field-sync.js

@@ -1,116 +0,0 @@
-const DEFAULT_STATUS_MAPPING = {
-  "planned": "Todo",
-  "in-progress": "In Progress",
-  "completed": "Done"
-};
-const DEFAULT_PRIORITY_MAPPING = {
-  "P1": "Urgent",
-  "P2": "High",
-  "P3": "Medium",
-  "P4": "Low"
-};
-class GitHubFieldSync {
-  constructor(client, config) {
-    this.fieldsLoaded = false;
-    this.client = client;
-    this.config = config;
-  }
-  /**
-   * Load project fields and cache field IDs and option IDs.
-   */
-  async loadFields() {
-    if (this.fieldsLoaded) return;
-    const fields = await this.client.getProjectFields(this.config.projectId);
-    for (const field of fields) {
-      if (field.name === "Status" && field.options) {
-        this.statusField = {
-          id: field.id,
-          name: field.name,
-          options: new Map(field.options.map((o) => [o.name, o.id]))
-        };
-      } else if (field.name === "Priority" && field.options) {
-        this.priorityField = {
-          id: field.id,
-          name: field.name,
-          options: new Map(field.options.map((o) => [o.name, o.id]))
-        };
-      }
-    }
-    this.fieldsLoaded = true;
-  }
-  /**
-   * Sync fields for one or more items.
-   * Auto-calls loadFields if not called yet.
-   */
-  async syncItemFields(items) {
-    if (!this.fieldsLoaded) {
-      await this.loadFields();
-    }
-    const result = { updated: [], warnings: [] };
-    for (const item of items) {
-      if (item.status !== void 0) {
-        await this.syncField(
-          item,
-          "Status",
-          item.status,
-          this.statusField,
-          this.config.statusFieldMapping ?? DEFAULT_STATUS_MAPPING,
-          result
-        );
-      }
-      if (item.priority !== void 0) {
-        await this.syncField(
-          item,
-          "Priority",
-          item.priority,
-          this.priorityField,
-          this.config.priorityFieldMapping ?? DEFAULT_PRIORITY_MAPPING,
-          result
-        );
-      }
-    }
-    return result;
-  }
-  async syncField(item, fieldName, value, cachedField, mapping, result) {
-    if (!cachedField) {
-      result.warnings.push({
-        itemId: item.itemId,
-        field: fieldName,
-        message: `${fieldName} field not found on project`
-      });
-      return;
-    }
-    const mappedValue = mapping[value];
-    if (!mappedValue) {
-      result.warnings.push({
-        itemId: item.itemId,
-        field: fieldName,
-        message: `No mapping found for ${fieldName} value "${value}"`
-      });
-      return;
-    }
-    const optionId = cachedField.options.get(mappedValue);
-    if (!optionId) {
-      result.warnings.push({
-        itemId: item.itemId,
-        field: fieldName,
-        message: `Option "${mappedValue}" not found on ${fieldName} field`
-      });
-      return;
-    }
-    await this.client.updateItemFieldValue(
-      this.config.projectId,
-      item.itemId,
-      cachedField.id,
-      { singleSelectOptionId: optionId }
-    );
-    result.updated.push({
-      itemId: item.itemId,
-      field: fieldName,
-      value: mappedValue
-    });
-  }
-}
-export {
-  GitHubFieldSync
-};

package/plugins/specweave/lib/integrations/github/github-field-sync.ts

@@ -1,165 +0,0 @@
-/**
- * GitHub Field Sync — Status and Priority field sync for Projects V2
- *
- * Syncs Status and Priority custom fields on Projects V2 items
- * using configurable field mappings.
- *
- * @module github-field-sync
- */
-
-import type { GitHubGraphQLClient } from './github-graphql-client.js';
-
-export interface FieldSyncConfig {
-  projectId: string;
-  statusFieldMapping?: Record<string, string>;
-  priorityFieldMapping?: Record<string, string>;
-}
-
-export interface FieldSyncItem {
-  itemId: string;
-  status?: string;
-  priority?: string;
-}
-
-export interface FieldSyncResult {
-  updated: Array<{ itemId: string; field: string; value: string }>;
-  warnings: Array<{ itemId: string; field: string; message: string }>;
-}
-
-interface CachedField {
-  id: string;
-  name: string;
-  options: Map<string, string>; // option name → option ID
-}
-
-const DEFAULT_STATUS_MAPPING: Record<string, string> = {
-  'planned': 'Todo',
-  'in-progress': 'In Progress',
-  'completed': 'Done',
-};
-
-const DEFAULT_PRIORITY_MAPPING: Record<string, string> = {
-  'P1': 'Urgent',
-  'P2': 'High',
-  'P3': 'Medium',
-  'P4': 'Low',
-};
-
-export class GitHubFieldSync {
-  private client: GitHubGraphQLClient;
-  private config: FieldSyncConfig;
-  private statusField?: CachedField;
-  private priorityField?: CachedField;
-  private fieldsLoaded = false;
-
-  constructor(client: GitHubGraphQLClient, config: FieldSyncConfig) {
-    this.client = client;
-    this.config = config;
-  }
-
-  /**
-   * Load project fields and cache field IDs and option IDs.
-   */
-  async loadFields(): Promise<void> {
-    if (this.fieldsLoaded) return;
-
-    const fields = await this.client.getProjectFields(this.config.projectId);
-
-    for (const field of fields) {
-      if (field.name === 'Status' && field.options) {
-        this.statusField = {
-          id: field.id,
-          name: field.name,
-          options: new Map(field.options.map(o => [o.name, o.id])),
-        };
-      } else if (field.name === 'Priority' && field.options) {
-        this.priorityField = {
-          id: field.id,
-          name: field.name,
-          options: new Map(field.options.map(o => [o.name, o.id])),
-        };
-      }
-    }
-
-    this.fieldsLoaded = true;
-  }
-
-  /**
-   * Sync fields for one or more items.
-   * Auto-calls loadFields if not called yet.
-   */
-  async syncItemFields(items: FieldSyncItem[]): Promise<FieldSyncResult> {
-    if (!this.fieldsLoaded) {
-      await this.loadFields();
-    }
-
-    const result: FieldSyncResult = { updated: [], warnings: [] };
-
-    for (const item of items) {
-      // Sync Status field
-      if (item.status !== undefined) {
-        await this.syncField(item, 'Status', item.status, this.statusField,
-          this.config.statusFieldMapping ?? DEFAULT_STATUS_MAPPING, result);
-      }
-
-      // Sync Priority field
-      if (item.priority !== undefined) {
-        await this.syncField(item, 'Priority', item.priority, this.priorityField,
-          this.config.priorityFieldMapping ?? DEFAULT_PRIORITY_MAPPING, result);
-      }
-    }
-
-    return result;
-  }
-
-  private async syncField(
-    item: FieldSyncItem,
-    fieldName: string,
-    value: string,
-    cachedField: CachedField | undefined,
-    mapping: Record<string, string>,
-    result: FieldSyncResult,
-  ): Promise<void> {
-    if (!cachedField) {
-      result.warnings.push({
-        itemId: item.itemId,
-        field: fieldName,
-        message: `${fieldName} field not found on project`,
-      });
-      return;
-    }
-
-    const mappedValue = mapping[value];
-    if (!mappedValue) {
-      result.warnings.push({
-        itemId: item.itemId,
-        field: fieldName,
-        message: `No mapping found for ${fieldName} value "${value}"`,
-      });
-      return;
-    }
-
-    const optionId = cachedField.options.get(mappedValue);
-    if (!optionId) {
-      result.warnings.push({
-        itemId: item.itemId,
-        field: fieldName,
-        message: `Option "${mappedValue}" not found on ${fieldName} field`,
-      });
-      return;
-    }
-
-    await this.client.updateItemFieldValue(
-      this.config.projectId,
-      item.itemId,
-      cachedField.id,
-      { singleSelectOptionId: optionId },
-    );
-
-    result.updated.push({
-      itemId: item.itemId,
-      field: fieldName,
-      value: mappedValue,
-    });
-  }
-}

package/plugins/specweave/lib/integrations/github/github-graphql-client.js

@@ -1,138 +0,0 @@
-import { execFile } from "child_process";
-class GitHubGraphQLClient {
-  constructor(token) {
-    this.token = token;
-  }
-  /**
-   * Resolve an owner login (user or org) to a node ID.
-   * Tries user first, falls back to organization.
-   */
-  async getOwnerNodeId(login) {
-    const userQuery = `query($login: String!) { user(login: $login) { id } }`;
-    const userResult = await this.executeGraphQL(userQuery, { login });
-    if (userResult.data?.user && userResult.data.user.id) {
-      return userResult.data.user.id;
-    }
-    const orgQuery = `query($login: String!) { organization(login: $login) { id } }`;
-    const orgResult = await this.executeGraphQL(orgQuery, { login });
-    if (orgResult.data?.organization && orgResult.data.organization.id) {
-      return orgResult.data.organization.id;
-    }
-    throw new Error(`Could not resolve to a User or Organization with the login of '${login}'.`);
-  }
-  /**
-   * Create a new GitHub Projects V2 board.
-   */
-  async createProjectV2(ownerId, title) {
-    const query = `mutation($ownerId: ID!, $title: String!) {
-      createProjectV2(input: { ownerId: $ownerId, title: $title }) {
-        projectV2 { id number }
-      }
-    }`;
-    const result = await this.executeGraphQL(query, { ownerId, title });
-    const project = result.data?.createProjectV2?.projectV2;
-    return { id: project.id, number: project.number };
-  }
-  /**
-   * Add an issue (by node ID) to a Projects V2 board.
-   * Returns the project item ID. Idempotent.
-   */
-  async addProjectV2Item(projectId, contentId) {
-    const query = `mutation($projectId: ID!, $contentId: ID!) {
-      addProjectV2ItemById(input: { projectId: $projectId, contentId: $contentId }) {
-        item { id }
-      }
-    }`;
-    const result = await this.executeGraphQL(query, { projectId, contentId });
-    const item = result.data?.addProjectV2ItemById?.item;
-    return item.id;
-  }
-  /**
-   * Update a field value on a Projects V2 item.
-   */
-  async updateItemFieldValue(projectId, itemId, fieldId, value) {
-    const query = `mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
-      updateProjectV2ItemFieldValue(input: {
-        projectId: $projectId,
-        itemId: $itemId,
-        fieldId: $fieldId,
-        value: { singleSelectOptionId: $optionId }
-      }) {
-        projectV2Item { id }
-      }
-    }`;
-    await this.executeGraphQL(query, {
-      projectId,
-      itemId,
-      fieldId,
-      optionId: value.singleSelectOptionId
-    });
-  }
-  /**
-   * Get field definitions for a Projects V2 board.
-   */
-  async getProjectFields(projectId) {
-    const query = `query($nodeId: ID!) {
-      node(id: $nodeId) {
-        ... on ProjectV2 {
-          fields(first: 50) {
-            nodes {
-              ... on ProjectV2Field { id name dataType }
-              ... on ProjectV2SingleSelectField {
-                id name dataType
-                options { id name }
-              }
-            }
-          }
-        }
-      }
-    }`;
-    const result = await this.executeGraphQL(query, { nodeId: projectId });
-    const fields = result.data?.node?.fields?.nodes || [];
-    return fields.map((f) => {
-      const field = { id: f.id, name: f.name };
-      if (f.options && f.options.length > 0) {
-        field.options = f.options;
-      }
-      return field;
-    });
-  }
-  /**
-   * Execute a GraphQL query via `gh api graphql`.
-   * All variables are passed via `-F` flags to prevent injection.
-   */
-  executeGraphQL(query, variables = {}) {
-    return new Promise((resolve, reject) => {
-      const args = ["api", "graphql", "-f", `query=${query}`];
-      for (const [key, value] of Object.entries(variables)) {
-        args.push("-F", `${key}=${value}`);
-      }
-      const opts = {};
-      if (this.token) {
-        opts.env = { ...process.env, GH_TOKEN: this.token };
-      }
-      execFile("gh", args, opts, (err, stdout, stderr) => {
-        if (err) {
-          reject(new Error(stderr || err.message));
-          return;
-        }
-        let parsed;
-        try {
-          parsed = JSON.parse(stdout);
-        } catch {
-          reject(new Error(`Failed to parse GraphQL response: ${stdout.slice(0, 200)}`));
-          return;
-        }
-        if (parsed.errors && parsed.errors.length > 0) {
-          const messages = parsed.errors.map((e) => e.message).join("; ");
-          reject(new Error(`GraphQL error: ${messages}`));
-          return;
-        }
-        resolve(parsed);
-      });
-    });
-  }
-}
-export {
-  GitHubGraphQLClient
-};