hungry-ghost-hive 0.43.0 → 0.43.2

package/src/integrations/jira/sync.ts

@@ -18,66 +18,13 @@ import { createLog } from '../../db/queries/logs.js';
 import { getStoryById, updateStory, type StoryStatus } from '../../db/queries/stories.js';
 import * as logger from '../../utils/logger.js';
 import { getHivePaths } from '../../utils/paths.js';
+import { isForwardTransition, isStatusRegression } from '../../utils/story-status.js';
 import { JiraClient } from './client.js';
 import { createSubtask, postComment } from './comments.js';
 import { getIssue } from './issues.js';
 import { syncRequirementToJira, tryMoveToActiveSprint } from './stories.js';
 import { syncStoryStatusToJira, transitionJiraIssue } from './transitions.js';
-
-/**
- * Ordered lifecycle stages for Hive stories.
- * Used to prevent bidirectional sync from regressing story status.
- */
-const STATUS_LIFECYCLE_ORDER: string[] = [
-  'draft',
-  'estimated',
-  'planned',
-  'in_progress',
-  'review',
-  'qa',
-  'qa_failed',
-  'pr_submitted',
-  'merged',
-];
-
-/**
- * Check if transitioning from currentStatus to newStatus would be a regression.
- * Returns true if the new status is earlier in the lifecycle than the current one.
- */
-function isStatusRegression(currentStatus: string, newStatus: string): boolean {
-  const currentIdx = STATUS_LIFECYCLE_ORDER.indexOf(currentStatus);
-  const newIdx = STATUS_LIFECYCLE_ORDER.indexOf(newStatus);
-  // If either status is unknown, allow the transition
-  if (currentIdx === -1 || newIdx === -1) return false;
-  return newIdx < currentIdx;
-}
-
-/**
- * Status progression order for the Hive pipeline.
- * Higher numbers represent further progress. Used to prevent
- * Jira sync from regressing stories backward.
- */
-const STATUS_ORDER: Record<string, number> = {
-  draft: 0,
-  estimated: 1,
-  planned: 2,
-  in_progress: 3,
-  review: 4,
-  pr_submitted: 5,
-  qa: 6,
-  qa_failed: 4, // allowed as a backward step from qa
-  merged: 7,
-};
-
-/**
- * Check whether transitioning from currentStatus to newStatus is a
- * forward (or lateral) move in the pipeline.
- */
-export function isForwardTransition(currentStatus: string, newStatus: string): boolean {
-  const currentOrder = STATUS_ORDER[currentStatus] ?? -1;
-  const newOrder = STATUS_ORDER[newStatus] ?? -1;
-  return newOrder >= currentOrder;
-}
+export { isForwardTransition };
 
 /**
  * Convert a Jira status name to a Hive status using the configured status mapping.
@@ -101,6 +48,81 @@ export function jiraStatusToHiveStatus(
   return null;
 }
 
+/**
+ * Create a JiraClient from environment variables.
+ * Shared by all sync functions in this module.
+ */
+function createJiraClient(tokenStore: TokenStore): JiraClient {
+  loadEnvIntoProcess();
+  return new JiraClient({
+    tokenStore,
+    clientId: process.env.JIRA_CLIENT_ID || '',
+    clientSecret: process.env.JIRA_CLIENT_SECRET || '',
+  });
+}
+
+/**
+ * Shared loop used by both bidirectional sync functions.
+ *
+ * For each story, fetches the current Jira status, converts it to a Hive status
+ * via the configured mapping, skips if unmapped, then delegates to `onMappedStatus`
+ * for the direction-specific action. Catches and logs per-story errors so one
+ * failing story does not abort the entire batch.
+ *
+ * @param db - Database instance (used for error logging)
+ * @param client - Authenticated JiraClient
+ * @param config - Jira configuration with status_mapping
+ * @param stories - Stories to process
+ * @param getIssueKey - Returns the Jira issue key for a given story row
+ * @param onMappedStatus - Called when a Jira status is successfully mapped;
+ *   returns true if the story was acted upon (counted toward the return value)
+ * @returns Number of stories acted upon
+ */
+async function processBidirectionalStatusSync(
+  db: Database,
+  client: JiraClient,
+  config: JiraConfig,
+  stories: StoryRow[],
+  getIssueKey: (story: StoryRow) => string,
+  onMappedStatus: (
+    story: StoryRow,
+    issueKey: string,
+    jiraStatusName: string,
+    mappedHiveStatus: string
+  ) => Promise<boolean>
+): Promise<number> {
+  let count = 0;
+  for (const story of stories) {
+    const issueKey = getIssueKey(story);
+    try {
+      const jiraIssue = await getIssue(client, issueKey, ['status']);
+      const jiraStatusName = jiraIssue.fields.status.name;
+      const mappedHiveStatus = jiraStatusToHiveStatus(jiraStatusName, config.status_mapping);
+      if (!mappedHiveStatus) {
+        logger.debug(
+          `No Hive status mapping for Jira status "${jiraStatusName}" (${issueKey}), skipping`
+        );
+        continue;
+      }
+      if (await onMappedStatus(story, issueKey, jiraStatusName, mappedHiveStatus)) {
+        count++;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.warn(`Failed to sync Jira status for story ${story.id} (${issueKey}): ${message}`);
+      createLog(db, {
+        agentId: 'manager',
+        storyId: story.id,
+        eventType: 'JIRA_SYNC_WARNING',
+        status: 'warn',
+        message: `Failed to sync status: ${message}`,
+        metadata: { jiraKey: issueKey, error: message },
+      });
+    }
+  }
+  return count;
+}
+
 /**
  * Sync Jira issue statuses back to the Hive database.
  * This detects manual status changes in Jira (e.g., dragging cards on the board)
@@ -132,93 +154,59 @@ export async function syncJiraStatusesToHive(
     return 0;
   }
 
-  loadEnvIntoProcess();
-
-  const client = new JiraClient({
-    tokenStore,
-    clientId: process.env.JIRA_CLIENT_ID || '',
-    clientSecret: process.env.JIRA_CLIENT_SECRET || '',
-  });
-
-  let updatedCount = 0;
-
-  for (const story of storiesWithJira) {
-    try {
-      // Fetch current Jira issue status
-      const jiraIssue = await getIssue(client, story.external_issue_key!, ['status']);
-      const jiraStatusName = jiraIssue.fields.status.name;
-
-      // Convert Jira status to Hive status
-      const mappedHiveStatus = jiraStatusToHiveStatus(jiraStatusName, config.status_mapping);
-
-      if (!mappedHiveStatus) {
-        logger.debug(
-          `No Hive status mapping for Jira status "${jiraStatusName}" (${story.external_issue_key}), skipping`
-        );
-        continue;
-      }
+  const client = createJiraClient(tokenStore);
 
-      // Check if status differs from current Hive status
+  return processBidirectionalStatusSync(
+    db,
+    client,
+    config,
+    storiesWithJira,
+    story => story.external_issue_key!,
+    async (story, issueKey, jiraStatusName, mappedHiveStatus) => {
       // Guard: never regress status backward in the lifecycle
       if (isStatusRegression(story.status, mappedHiveStatus)) {
         logger.debug(
           `Skipping Jira sync for ${story.id}: would regress ${story.status} → ${mappedHiveStatus}`
         );
-        continue;
+        return false;
       }
 
-      if (mappedHiveStatus !== story.status) {
-        // Only allow forward transitions — never regress stories backward
-        if (!isForwardTransition(story.status, mappedHiveStatus)) {
-          logger.debug(
-            `Skipping backward Jira sync for story ${story.id} (${story.external_issue_key}): ` +
-              `would regress ${story.status} → ${mappedHiveStatus} (Jira: "${jiraStatusName}")`
-          );
-          continue;
-        }
-
-        // Update the story status in Hive
-        await withTransaction(db, () => {
-          updateStory(db, story.id, { status: mappedHiveStatus as StoryStatus });
-
-          createLog(db, {
-            agentId: 'manager',
-            storyId: story.id,
-            eventType: 'JIRA_SYNC_COMPLETED',
-            message: `Synced status from Jira: ${story.status} → ${mappedHiveStatus} (Jira: "${jiraStatusName}")`,
-            metadata: {
-              jiraKey: story.external_issue_key,
-              oldHiveStatus: story.status,
-              newHiveStatus: mappedHiveStatus,
-              jiraStatus: jiraStatusName,
-            },
-          });
-        });
+      if (mappedHiveStatus === story.status) return false;
 
+      // Only allow forward transitions — never regress stories backward
+      if (!isForwardTransition(story.status, mappedHiveStatus)) {
         logger.debug(
-          `Synced Jira status for story ${story.id} (${story.external_issue_key}): ${story.status} → ${mappedHiveStatus}`
+          `Skipping backward Jira sync for story ${story.id} (${issueKey}): ` +
+            `would regress ${story.status} → ${mappedHiveStatus} (Jira: "${jiraStatusName}")`
         );
-
-        updatedCount++;
+        return false;
       }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      logger.warn(
-        `Failed to sync Jira status for story ${story.id} (${story.external_issue_key}): ${message}`
-      );
 
-      createLog(db, {
-        agentId: 'manager',
-        storyId: story.id,
-        eventType: 'JIRA_SYNC_WARNING',
-        status: 'warn',
-        message: `Failed to sync status from Jira: ${message}`,
-        metadata: { jiraKey: story.external_issue_key, error: message },
+      // Update the story status in Hive
+      await withTransaction(db, () => {
+        updateStory(db, story.id, { status: mappedHiveStatus as StoryStatus });
+
+        createLog(db, {
+          agentId: 'manager',
+          storyId: story.id,
+          eventType: 'JIRA_SYNC_COMPLETED',
+          message: `Synced status from Jira: ${story.status} → ${mappedHiveStatus} (Jira: "${jiraStatusName}")`,
+          metadata: {
+            jiraKey: issueKey,
+            oldHiveStatus: story.status,
+            newHiveStatus: mappedHiveStatus,
+            jiraStatus: jiraStatusName,
+          },
+        });
       });
-    }
-  }
 
-  return updatedCount;
+      logger.debug(
+        `Synced Jira status for story ${story.id} (${issueKey}): ${story.status} → ${mappedHiveStatus}`
+      );
+
+      return true;
+    }
+  );
 }
 
 /**
@@ -374,13 +362,7 @@ export async function repairMissedAssignmentHooks(
     `Found ${storiesMissingSubtasks.length} assigned story(ies) missing Jira subtasks — repairing`
   );
 
-  loadEnvIntoProcess();
-
-  const client = new JiraClient({
-    tokenStore,
-    clientId: process.env.JIRA_CLIENT_ID || '',
-    clientSecret: process.env.JIRA_CLIENT_SECRET || '',
-  });
+  const client = createJiraClient(tokenStore);
 
   let repairedCount = 0;
 
@@ -482,13 +464,7 @@ export async function retrySprintAssignment(
 
   logger.info(`Found ${storiesNotInSprint.length} story(ies) not in sprint — retrying assignment`);
 
-  loadEnvIntoProcess();
-
-  const client = new JiraClient({
-    tokenStore,
-    clientId: process.env.JIRA_CLIENT_ID || '',
-    clientSecret: process.env.JIRA_CLIENT_SECRET || '',
-  });
+  const client = createJiraClient(tokenStore);
 
   const issueKeys = storiesNotInSprint.map(s => s.jira_issue_key!).filter(Boolean);
 
@@ -534,90 +510,56 @@ export async function syncHiveStatusesToJira(
     return 0;
   }
 
-  loadEnvIntoProcess();
+  const client = createJiraClient(tokenStore);
 
-  const client = new JiraClient({
-    tokenStore,
-    clientId: process.env.JIRA_CLIENT_ID || '',
-    clientSecret: process.env.JIRA_CLIENT_SECRET || '',
-  });
-
-  let pushedCount = 0;
-
-  for (const story of storiesWithJira) {
-    try {
-      // Fetch current Jira issue status
-      const jiraIssue = await getIssue(client, story.jira_issue_key!, ['status']);
-      const jiraStatusName = jiraIssue.fields.status.name;
-
-      // Convert Jira status to Hive status to compare
-      const jiraStatusAsHiveStatus = jiraStatusToHiveStatus(jiraStatusName, config.status_mapping);
-
-      if (!jiraStatusAsHiveStatus) {
+  return processBidirectionalStatusSync(
+    db,
+    client,
+    config,
+    storiesWithJira,
+    story => story.jira_issue_key!,
+    async (story, issueKey, jiraStatusName, jiraStatusAsHiveStatus) => {
+      if (story.status === jiraStatusAsHiveStatus) return false;
+
+      // Only push forward transitions — never regress Jira backward
+      if (!isForwardTransition(jiraStatusAsHiveStatus, story.status)) {
         logger.debug(
-          `No Hive status mapping for Jira status "${jiraStatusName}" (${story.jira_issue_key}), skipping`
+          `Skipping Hive-to-Jira push for story ${story.id} (${issueKey}): ` +
+            `would regress Jira from ${jiraStatusAsHiveStatus} → ${story.status} (Jira: "${jiraStatusName}")`
         );
-        continue;
+        return false;
       }
 
-      // Check if Hive status is ahead of Jira status
-      if (story.status !== jiraStatusAsHiveStatus) {
-        // Only push forward transitions — never regress Jira backward
-        if (!isForwardTransition(jiraStatusAsHiveStatus, story.status)) {
-          logger.debug(
-            `Skipping Hive-to-Jira push for story ${story.id} (${story.jira_issue_key}): ` +
-              `would regress Jira from ${jiraStatusAsHiveStatus} → ${story.status} (Jira: "${jiraStatusName}")`
-          );
-          continue;
-        }
+      // Push the Hive status to Jira
+      const transitioned = await transitionJiraIssue(
+        client,
+        issueKey,
+        story.status,
+        config.status_mapping
+      );
 
-        // Push the Hive status to Jira
-        const transitioned = await transitionJiraIssue(
-          client,
-          story.jira_issue_key!,
-          story.status,
-          config.status_mapping
-        );
+      if (transitioned) {
+        createLog(db, {
+          agentId: 'manager',
+          storyId: story.id,
+          eventType: 'JIRA_SYNC_COMPLETED',
+          message: `Pushed status to Jira: ${jiraStatusAsHiveStatus} → ${story.status} (was Jira: "${jiraStatusName}")`,
+          metadata: {
+            jiraKey: issueKey,
+            oldJiraStatus: jiraStatusName,
+            oldHiveStatus: jiraStatusAsHiveStatus,
+            newHiveStatus: story.status,
+          },
+        });
 
-        if (transitioned) {
-          createLog(db, {
-            agentId: 'manager',
-            storyId: story.id,
-            eventType: 'JIRA_SYNC_COMPLETED',
-            message: `Pushed status to Jira: ${jiraStatusAsHiveStatus} → ${story.status} (was Jira: "${jiraStatusName}")`,
-            metadata: {
-              jiraKey: story.jira_issue_key,
-              oldJiraStatus: jiraStatusName,
-              oldHiveStatus: jiraStatusAsHiveStatus,
-              newHiveStatus: story.status,
-            },
-          });
-
-          logger.debug(
-            `Pushed Hive status to Jira for story ${story.id} (${story.jira_issue_key}): ${jiraStatusAsHiveStatus} → ${story.status}`
-          );
-
-          pushedCount++;
-        }
+        logger.debug(
+          `Pushed Hive status to Jira for story ${story.id} (${issueKey}): ${jiraStatusAsHiveStatus} → ${story.status}`
+        );
       }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      logger.warn(
-        `Failed to push Hive status to Jira for story ${story.id} (${story.jira_issue_key}): ${message}`
-      );
 
-      createLog(db, {
-        agentId: 'manager',
-        storyId: story.id,
-        eventType: 'JIRA_SYNC_WARNING',
-        status: 'warn',
-        message: `Failed to push status to Jira: ${message}`,
-        metadata: { jiraKey: story.jira_issue_key, error: message },
-      });
+      return transitioned;
     }
-  }
-
-  return pushedCount;
+  );
 }
 
 /**

package/src/utils/cli-helpers.test.ts

@@ -0,0 +1,138 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../db/client.js', () => ({
+  queryOne: vi.fn(),
+}));
+
+vi.mock('../db/queries/agents.js', () => ({
+  getAgentById: vi.fn(),
+}));
+
+vi.mock('../db/queries/pull-requests.js', () => ({
+  getPullRequestById: vi.fn(),
+}));
+
+vi.mock('../db/queries/stories.js', () => ({
+  getStoryById: vi.fn(),
+}));
+
+import { queryOne } from '../db/client.js';
+import { getAgentById } from '../db/queries/agents.js';
+import { getPullRequestById } from '../db/queries/pull-requests.js';
+import { getStoryById } from '../db/queries/stories.js';
+import {
+  requireAgent,
+  requireAgentBySession,
+  requirePullRequest,
+  requireStory,
+} from './cli-helpers.js';
+
+const mockDb = {} as any;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('requireStory', () => {
+  it('returns the story when found', () => {
+    const story = { id: 'STORY-1', title: 'Test' };
+    vi.mocked(getStoryById).mockReturnValue(story as any);
+
+    const result = requireStory(mockDb, 'STORY-1');
+
+    expect(result).toBe(story);
+    expect(getStoryById).toHaveBeenCalledWith(mockDb, 'STORY-1');
+  });
+
+  it('exits with error when story not found', () => {
+    vi.mocked(getStoryById).mockReturnValue(undefined);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit called');
+    }) as any);
+
+    expect(() => requireStory(mockDb, 'STORY-99')).toThrow('process.exit called');
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Story not found: STORY-99'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('requireAgent', () => {
+  it('returns the agent when found', () => {
+    const agent = { id: 'agent-1', type: 'senior' };
+    vi.mocked(getAgentById).mockReturnValue(agent as any);
+
+    const result = requireAgent(mockDb, 'agent-1');
+
+    expect(result).toBe(agent);
+    expect(getAgentById).toHaveBeenCalledWith(mockDb, 'agent-1');
+  });
+
+  it('exits with error when agent not found', () => {
+    vi.mocked(getAgentById).mockReturnValue(undefined);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit called');
+    }) as any);
+
+    expect(() => requireAgent(mockDb, 'agent-99')).toThrow('process.exit called');
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Agent not found: agent-99'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('requireAgentBySession', () => {
+  it('returns the agent when session matches', () => {
+    const agent = { id: 'agent-1', tmux_session: 'hive-senior-team' };
+    vi.mocked(queryOne).mockReturnValue(agent as any);
+
+    const result = requireAgentBySession(mockDb, 'hive-senior-team');
+
+    expect(result).toBe(agent);
+    expect(queryOne).toHaveBeenCalledWith(
+      mockDb,
+      expect.stringContaining("status != 'terminated'"),
+      ['hive-senior-team']
+    );
+  });
+
+  it('exits with error when session not found', () => {
+    vi.mocked(queryOne).mockReturnValue(undefined);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit called');
+    }) as any);
+
+    expect(() => requireAgentBySession(mockDb, 'unknown-session')).toThrow('process.exit called');
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('No agent found with session: unknown-session')
+    );
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('requirePullRequest', () => {
+  it('returns the PR when found', () => {
+    const pr = { id: 'pr-1', branch_name: 'feature/test' };
+    vi.mocked(getPullRequestById).mockReturnValue(pr as any);
+
+    const result = requirePullRequest(mockDb, 'pr-1');
+
+    expect(result).toBe(pr);
+    expect(getPullRequestById).toHaveBeenCalledWith(mockDb, 'pr-1');
+  });
+
+  it('exits with error when PR not found', () => {
+    vi.mocked(getPullRequestById).mockReturnValue(undefined);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {
+      throw new Error('process.exit called');
+    }) as any);
+
+    expect(() => requirePullRequest(mockDb, 'pr-99')).toThrow('process.exit called');
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('PR not found: pr-99'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});

package/src/utils/cli-helpers.ts

@@ -0,0 +1,61 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import chalk from 'chalk';
+import type { Database } from 'sql.js';
+import type { AgentRow, PullRequestRow, StoryRow } from '../db/client.js';
+import { queryOne } from '../db/client.js';
+import { getAgentById } from '../db/queries/agents.js';
+import { getPullRequestById } from '../db/queries/pull-requests.js';
+import { getStoryById } from '../db/queries/stories.js';
+
+/**
+ * Require a story by ID, exit with error if not found.
+ */
+export function requireStory(db: Database, storyId: string): StoryRow {
+  const story = getStoryById(db, storyId);
+  if (!story) {
+    console.error(chalk.red(`Story not found: ${storyId}`));
+    process.exit(1);
+  }
+  return story;
+}
+
+/**
+ * Require an agent by ID, exit with error if not found.
+ */
+export function requireAgent(db: Database, agentId: string): AgentRow {
+  const agent = getAgentById(db, agentId);
+  if (!agent) {
+    console.error(chalk.red(`Agent not found: ${agentId}`));
+    process.exit(1);
+  }
+  return agent;
+}
+
+/**
+ * Require an active agent by tmux session name, exit with error if not found or terminated.
+ */
+export function requireAgentBySession(db: Database, session: string): AgentRow {
+  const agent = queryOne<AgentRow>(
+    db,
+    "SELECT * FROM agents WHERE tmux_session = ? AND status != 'terminated'",
+    [session]
+  );
+  if (!agent) {
+    console.error(chalk.red(`No agent found with session: ${session}`));
+    process.exit(1);
+  }
+  return agent;
+}
+
+/**
+ * Require a pull request by ID, exit with error if not found.
+ */
+export function requirePullRequest(db: Database, prId: string): PullRequestRow {
+  const pr = getPullRequestById(db, prId);
+  if (!pr) {
+    console.error(chalk.red(`PR not found: ${prId}`));
+    process.exit(1);
+  }
+  return pr;
+}

package/src/utils/github-cli.ts

@@ -0,0 +1,4 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+/** Default timeout in ms for GitHub CLI operations */
+export const GH_CLI_TIMEOUT_MS = 30000;

package/src/utils/pr-sync.ts

@@ -8,13 +8,11 @@ import { createLog } from '../db/queries/logs.js';
 import { createPullRequest } from '../db/queries/pull-requests.js';
 import { updateStory } from '../db/queries/stories.js';
 import { getAllTeams } from '../db/queries/teams.js';
+import { GH_CLI_TIMEOUT_MS } from './github-cli.js';
 import { extractStoryIdFromBranch } from './story-id.js';
 
 const GITHUB_PR_LIST_LIMIT = 20;
 
-/** Default timeout in ms for GitHub CLI operations */
-const GH_CLI_TIMEOUT_MS = 30000;
-
 /**
  * Extract 'owner/repo' slug from a GitHub URL for use with `gh -R`.
  * Handles https://github.com/owner/repo.git and similar variants.