specweave 1.0.235 → 1.0.239

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

@@ -0,0 +1,165 @@
+/**
+ * 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-github/lib/github-graphql-client.js

@@ -0,0 +1,129 @@
+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 { user(login: "${login}") { id } }`;
+    const userResult = await this.executeGraphQL(userQuery);
+    if (userResult.data?.user && userResult.data.user.id) {
+      return userResult.data.user.id;
+    }
+    const orgQuery = `query { organization(login: "${login}") { id } }`;
+    const orgResult = await this.executeGraphQL(orgQuery);
+    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 {
+      createProjectV2(input: { ownerId: "${ownerId}", title: "${title}" }) {
+        projectV2 { id number }
+      }
+    }`;
+    const result = await this.executeGraphQL(query);
+    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 {
+      addProjectV2ItemById(input: { projectId: "${projectId}", contentId: "${contentId}" }) {
+        item { id }
+      }
+    }`;
+    const result = await this.executeGraphQL(query);
+    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 {
+      updateProjectV2ItemFieldValue(input: {
+        projectId: "${projectId}",
+        itemId: "${itemId}",
+        fieldId: "${fieldId}",
+        value: { singleSelectOptionId: "${value.singleSelectOptionId}" }
+      }) {
+        projectV2Item { id }
+      }
+    }`;
+    await this.executeGraphQL(query);
+  }
+  /**
+   * Get field definitions for a Projects V2 board.
+   */
+  async getProjectFields(projectId) {
+    const query = `query {
+      node(id: "${projectId}") {
+        ... 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);
+    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`.
+   */
+  executeGraphQL(query) {
+    return new Promise((resolve, reject) => {
+      const args = ["api", "graphql", "-f", `query=${query}`];
+      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
+};

package/plugins/specweave-github/lib/github-graphql-client.ts

@@ -0,0 +1,181 @@
+/**
+ * GitHub GraphQL Client for Projects V2
+ *
+ * Wraps `gh api graphql` CLI calls for GitHub Projects V2 operations.
+ * All calls use child_process.execFile for security (no shell interpolation).
+ *
+ * @module github-graphql-client
+ */
+
+import { execFile } from 'child_process';
+
+interface ProjectField {
+  id: string;
+  name: string;
+  options?: Array<{ id: string; name: string }>;
+}
+
+interface GraphQLResponse {
+  data?: Record<string, unknown>;
+  errors?: Array<{ message: string; type?: string; path?: string[] }>;
+}
+
+export class GitHubGraphQLClient {
+  private token?: string;
+
+  constructor(token?: string) {
+    this.token = token;
+  }
+
+  /**
+   * Resolve an owner login (user or org) to a node ID.
+   * Tries user first, falls back to organization.
+   */
+  async getOwnerNodeId(login: string): Promise<string> {
+    // Try user query first
+    const userQuery = `query { user(login: "${login}") { id } }`;
+    const userResult = await this.executeGraphQL(userQuery);
+
+    if (userResult.data?.user && (userResult.data.user as { id?: string }).id) {
+      return (userResult.data.user as { id: string }).id;
+    }
+
+    // Fallback to organization
+    const orgQuery = `query { organization(login: "${login}") { id } }`;
+    const orgResult = await this.executeGraphQL(orgQuery);
+
+    if (orgResult.data?.organization && (orgResult.data.organization as { id?: string }).id) {
+      return (orgResult.data.organization as { id: string }).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: string, title: string): Promise<{ id: string; number: number }> {
+    const query = `mutation {
+      createProjectV2(input: { ownerId: "${ownerId}", title: "${title}" }) {
+        projectV2 { id number }
+      }
+    }`;
+
+    const result = await this.executeGraphQL(query);
+    const project = (result.data?.createProjectV2 as { projectV2: { id: string; number: number } })?.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: string, contentId: string): Promise<string> {
+    const query = `mutation {
+      addProjectV2ItemById(input: { projectId: "${projectId}", contentId: "${contentId}" }) {
+        item { id }
+      }
+    }`;
+
+    const result = await this.executeGraphQL(query);
+    const item = (result.data?.addProjectV2ItemById as { item: { id: string } })?.item;
+    return item.id;
+  }
+
+  /**
+   * Update a field value on a Projects V2 item.
+   */
+  async updateItemFieldValue(
+    projectId: string,
+    itemId: string,
+    fieldId: string,
+    value: { singleSelectOptionId: string },
+  ): Promise<void> {
+    const query = `mutation {
+      updateProjectV2ItemFieldValue(input: {
+        projectId: "${projectId}",
+        itemId: "${itemId}",
+        fieldId: "${fieldId}",
+        value: { singleSelectOptionId: "${value.singleSelectOptionId}" }
+      }) {
+        projectV2Item { id }
+      }
+    }`;
+
+    await this.executeGraphQL(query);
+  }
+
+  /**
+   * Get field definitions for a Projects V2 board.
+   */
+  async getProjectFields(projectId: string): Promise<ProjectField[]> {
+    const query = `query {
+      node(id: "${projectId}") {
+        ... 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);
+    const fields = (result.data?.node as { fields?: { nodes: Array<{
+      id: string;
+      name: string;
+      dataType: string;
+      options?: Array<{ id: string; name: string }>;
+    }> } })?.fields?.nodes || [];
+
+    return fields.map((f) => {
+      const field: ProjectField = { 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`.
+   */
+  private executeGraphQL(query: string): Promise<GraphQLResponse> {
+    return new Promise((resolve, reject) => {
+      const args = ['api', 'graphql', '-f', `query=${query}`];
+      const opts: { env?: NodeJS.ProcessEnv } = {};
+
+      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: GraphQLResponse;
+        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);
+      });
+    });
+  }
+}

package/plugins/specweave-github/lib/github-issue-body-generator.js

@@ -0,0 +1,30 @@
+function generateIssueBody(userStory) {
+  const lines = [];
+  lines.push("## Description");
+  lines.push("");
+  lines.push(userStory.description);
+  lines.push("");
+  lines.push(`**Priority**: ${userStory.priority}`);
+  lines.push("");
+  if (userStory.acceptanceCriteria.length > 0) {
+    lines.push("## Acceptance Criteria");
+    lines.push("");
+    lines.push("<!-- specweave:ac-start -->");
+    for (const ac of userStory.acceptanceCriteria) {
+      const checkbox = ac.completed ? "[x]" : "[ ]";
+      lines.push(`- ${checkbox} **${ac.id}**: ${ac.description}`);
+    }
+    lines.push("<!-- specweave:ac-end -->");
+    lines.push("");
+  }
+  const syncParts = [];
+  if (userStory.specId) {
+    syncParts.push(`spec=${userStory.specId}`);
+  }
+  syncParts.push(`us=${userStory.id}`);
+  lines.push(`<!-- specweave:sync ${syncParts.join(" ")} -->`);
+  return lines.join("\n");
+}
+export {
+  generateIssueBody
+};

package/plugins/specweave-github/lib/github-issue-body-generator.ts

@@ -0,0 +1,76 @@
+/**
+ * GitHub Issue Body Generator
+ *
+ * Generates GitHub issue body markdown from a User Story.
+ * Used by the spec-to-issue push sync to create rich issue content
+ * with AC checkboxes, priority badges, and sync markers.
+ *
+ * @module github-issue-body-generator
+ */
+
+export interface UserStoryInput {
+  /** User story ID, e.g., "US-001" */
+  id: string;
+  /** User story title */
+  title: string;
+  /** User story description */
+  description: string;
+  /** Priority, e.g., "P1" */
+  priority: string;
+  /** Acceptance criteria */
+  acceptanceCriteria: Array<{
+    id: string;
+    description: string;
+    completed: boolean;
+  }>;
+  /** Spec ID, e.g., "spec-001" */
+  specId?: string;
+  /** Local file path to the spec */
+  specPath?: string;
+}
+
+/**
+ * Generate a GitHub issue body from a User Story input.
+ *
+ * Output format:
+ * - Description section
+ * - AC checkboxes between specweave markers
+ * - Priority badge
+ * - Sync footer marker
+ */
+export function generateIssueBody(userStory: UserStoryInput): string {
+  const lines: string[] = [];
+
+  // Description
+  lines.push('## Description');
+  lines.push('');
+  lines.push(userStory.description);
+  lines.push('');
+
+  // Priority badge
+  lines.push(`**Priority**: ${userStory.priority}`);
+  lines.push('');
+
+  // Acceptance Criteria with markers
+  if (userStory.acceptanceCriteria.length > 0) {
+    lines.push('## Acceptance Criteria');
+    lines.push('');
+    lines.push('<!-- specweave:ac-start -->');
+    for (const ac of userStory.acceptanceCriteria) {
+      const checkbox = ac.completed ? '[x]' : '[ ]';
+      lines.push(`- ${checkbox} **${ac.id}**: ${ac.description}`);
+    }
+    lines.push('<!-- specweave:ac-end -->');
+    lines.push('');
+  }
+
+  // Sync footer marker
+  const syncParts: string[] = [];
+  if (userStory.specId) {
+    syncParts.push(`spec=${userStory.specId}`);
+  }
+  syncParts.push(`us=${userStory.id}`);
+  lines.push(`<!-- specweave:sync ${syncParts.join(' ')} -->`);
+
+  return lines.join('\n');
+}

package/plugins/specweave-github/lib/github-issue-body-parser.js

@@ -0,0 +1,55 @@
+const AC_CHECKBOX_RE = /^-\s+\[([ xX])\]\s+\*\*(?<acId>AC-[A-Z0-9]+-\d+)\*\*:\s*(?<desc>.+)$/;
+const SYNC_MARKER_RE = /<!--\s*specweave:sync\s+(?:spec=(?<specId>[^\s]+)\s+)?us=(?<usId>[^\s]+)\s*-->/;
+function parseIssueBody(body) {
+  const result = {
+    acceptanceCriteria: {}
+  };
+  if (!body || !body.trim()) {
+    return result;
+  }
+  const lines = body.split("\n");
+  let inAcSection = false;
+  let foundAcSection = false;
+  for (const line of lines) {
+    if (/^##\s+Acceptance Criteria/i.test(line)) {
+      inAcSection = true;
+      foundAcSection = true;
+      continue;
+    }
+    if (inAcSection && /^##\s+/.test(line)) {
+      inAcSection = false;
+      continue;
+    }
+    if (inAcSection) {
+      const match = line.match(AC_CHECKBOX_RE);
+      if (match?.groups) {
+        result.acceptanceCriteria[match.groups.acId] = {
+          checked: match[1] !== " ",
+          description: match.groups.desc.trim()
+        };
+      }
+    }
+  }
+  if (!foundAcSection) {
+    for (const line of lines) {
+      const match = line.match(AC_CHECKBOX_RE);
+      if (match?.groups) {
+        result.acceptanceCriteria[match.groups.acId] = {
+          checked: match[1] !== " ",
+          description: match.groups.desc.trim()
+        };
+      }
+    }
+  }
+  const syncMatch = body.match(SYNC_MARKER_RE);
+  if (syncMatch?.groups?.usId) {
+    result.syncMarker = {
+      specId: syncMatch.groups.specId || "",
+      userStoryId: syncMatch.groups.usId
+    };
+  }
+  return result;
+}
+export {
+  parseIssueBody
+};