hungry-ghost-hive 0.44.0 → 0.46.0

package/src/utils/instance.ts

@@ -0,0 +1,95 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { nanoid } from 'nanoid';
+import { join } from 'path';
+
+const INSTANCE_ID_FILE = 'instance.id';
+
+/**
+ * Get or create the instance ID for a hive workspace.
+ * The ID is stored in .hive/instance.id.
+ * Returns null if the hive directory does not exist.
+ * Only creates the file if the .hive directory already exists
+ * (i.e., this is a real workspace, not a test environment).
+ */
+export function getInstanceId(hiveDir: string): string | null {
+  if (!existsSync(hiveDir)) {
+    return null;
+  }
+
+  const instancePath = join(hiveDir, INSTANCE_ID_FILE);
+
+  if (existsSync(instancePath)) {
+    const id = readFileSync(instancePath, 'utf-8').trim();
+    if (id) return id;
+  }
+
+  // Generate a short unique ID for this workspace instance
+  const id = nanoid(6);
+  try {
+    writeFileSync(instancePath, id, 'utf-8');
+  } catch {
+    // If write fails (e.g., read-only filesystem), use in-memory ID
+  }
+  return id;
+}
+
+/**
+ * Get the instance-scoped tmux session prefix.
+ * Falls back to 'hive' if no instance ID is available.
+ */
+export function getInstancePrefix(hiveDir: string): string {
+  const instanceId = getInstanceId(hiveDir);
+  if (instanceId) {
+    return `hive-${instanceId}`;
+  }
+  return 'hive';
+}
+
+/**
+ * Build an instance-scoped session name.
+ * Pattern: hive-<instanceId>-<agentType>[-<teamName>][-<index>]
+ * Falls back to hive-<agentType>[-<teamName>][-<index>] if no instance ID.
+ */
+export function buildInstanceSessionName(
+  hiveDir: string,
+  agentType: string,
+  teamName?: string,
+  index?: number
+): string {
+  const prefix = getInstancePrefix(hiveDir);
+  let name = `${prefix}-${agentType}`;
+  if (teamName) {
+    name += `-${teamName}`;
+  }
+  if (index !== undefined && index > 1) {
+    name += `-${index}`;
+  }
+  return name;
+}
+
+/**
+ * Build the instance-scoped tech lead session name.
+ */
+export function getTechLeadSessionName(hiveDir: string): string {
+  return buildInstanceSessionName(hiveDir, 'tech-lead');
+}
+
+/**
+ * Build the instance-scoped manager session name.
+ */
+export function getManagerSessionName(hiveDir: string): string {
+  return buildInstanceSessionName(hiveDir, 'manager');
+}
+
+/**
+ * Build the instance-scoped manager lock path.
+ */
+export function getManagerLockPath(hiveDir: string): string {
+  const instanceId = getInstanceId(hiveDir);
+  if (instanceId) {
+    return join(hiveDir, `manager-${instanceId}.lock`);
+  }
+  return join(hiveDir, 'manager.lock');
+}

package/src/utils/paths.test.ts

@@ -102,6 +102,7 @@ describe('paths utility', () => {
         agentsDir: join(rootDir, '.hive', 'agents'),
         logsDir: join(rootDir, '.hive', 'logs'),
         reposDir: join(rootDir, 'repos'),
+        storiesDir: join(rootDir, '.hive', 'stories'),
       });
     });
 
@@ -128,6 +129,7 @@ describe('paths utility', () => {
       expect(result.configPath).toContain(result.hiveDir);
       expect(result.agentsDir).toContain(result.hiveDir);
       expect(result.logsDir).toContain(result.hiveDir);
+      expect(result.storiesDir).toContain(result.hiveDir);
       expect(result.reposDir).not.toContain(result.hiveDir);
     });
 
@@ -154,6 +156,12 @@ describe('paths utility', () => {
 
       expect(result.logsDir).toContain(paths.LOGS_DIR_NAME);
     });
+
+    it('should use STORIES_DIR_NAME constant for stories directory', () => {
+      const result = paths.getHivePaths(rootDir);
+
+      expect(result.storiesDir).toBe(join(rootDir, '.hive', paths.STORIES_DIR_NAME));
+    });
   });
 
   describe('isHiveWorkspace', () => {

package/src/utils/paths.ts

@@ -7,6 +7,7 @@ export const HIVE_DIR_NAME = '.hive';
 export const REPOS_DIR_NAME = 'repos';
 export const AGENTS_DIR_NAME = 'agents';
 export const LOGS_DIR_NAME = 'logs';
+export const STORIES_DIR_NAME = 'stories';
 
 export interface HivePaths {
   root: string;
@@ -16,6 +17,7 @@ export interface HivePaths {
   agentsDir: string;
   logsDir: string;
   reposDir: string;
+  storiesDir: string;
 }
 
 export function findHiveRoot(startDir: string = process.cwd()): string | null {
@@ -43,6 +45,7 @@ export function getHivePaths(rootDir: string): HivePaths {
     agentsDir: join(hiveDir, AGENTS_DIR_NAME),
     logsDir: join(hiveDir, LOGS_DIR_NAME),
     reposDir: join(rootDir, REPOS_DIR_NAME),
+    storiesDir: join(hiveDir, STORIES_DIR_NAME),
   };
 }
 

package/src/utils/story-markdown.test.ts

@@ -0,0 +1,176 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { StoryRow } from '../db/client.js';
+import {
+  deleteStoryMarkdown,
+  generateStoryMarkdown,
+  writeStoryMarkdown,
+} from './story-markdown.js';
+
+const TEST_DIR = join('/tmp', `story-markdown-test-${Date.now()}`);
+
+function makeStory(overrides: Partial<StoryRow> = {}): StoryRow {
+  return {
+    id: 'STORY-TEST01',
+    requirement_id: null,
+    team_id: null,
+    title: 'Test Story',
+    description: 'A test story description.',
+    acceptance_criteria: null,
+    complexity_score: null,
+    story_points: null,
+    status: 'draft',
+    assigned_agent_id: null,
+    branch_name: null,
+    pr_url: null,
+    jira_issue_key: null,
+    jira_issue_id: null,
+    jira_project_key: null,
+    jira_subtask_key: null,
+    jira_subtask_id: null,
+    external_issue_key: null,
+    external_issue_id: null,
+    external_project_key: null,
+    external_subtask_key: null,
+    external_subtask_id: null,
+    external_provider: null,
+    in_sprint: 0,
+    markdown_path: null,
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+describe('generateStoryMarkdown', () => {
+  it('should generate a markdown document with title and description', () => {
+    const story = makeStory();
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('# Test Story');
+    expect(md).toContain('**Story ID:** STORY-TEST01');
+    expect(md).toContain('**Status:** draft');
+    expect(md).toContain('A test story description.');
+  });
+
+  it('should include acceptance criteria as a checklist', () => {
+    const story = makeStory({
+      acceptance_criteria: JSON.stringify(['Criterion A', 'Criterion B']),
+    });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('## Acceptance Criteria');
+    expect(md).toContain('- [ ] Criterion A');
+    expect(md).toContain('- [ ] Criterion B');
+  });
+
+  it('should include optional fields when present', () => {
+    const story = makeStory({
+      team_id: 'TEAM-1',
+      requirement_id: 'REQ-1',
+      assigned_agent_id: 'agent-123',
+      complexity_score: 5,
+      story_points: 5,
+      branch_name: 'feature/STORY-TEST01-test-story',
+      pr_url: 'https://github.com/test/repo/pull/42',
+    });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('**Team:** TEAM-1');
+    expect(md).toContain('**Requirement:** REQ-1');
+    expect(md).toContain('**Assigned Agent:** agent-123');
+    expect(md).toContain('**Complexity:** 5');
+    expect(md).toContain('**Story Points:** 5');
+    expect(md).toContain('**Branch:** feature/STORY-TEST01-test-story');
+    expect(md).toContain('**PR:** https://github.com/test/repo/pull/42');
+  });
+
+  it('should include created and updated timestamps', () => {
+    const story = makeStory();
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('*Created: 2026-01-01T00:00:00.000Z*');
+    expect(md).toContain('*Updated: 2026-01-01T00:00:00.000Z*');
+  });
+
+  it('should handle malformed acceptance_criteria gracefully', () => {
+    const story = makeStory({ acceptance_criteria: 'not-json' });
+    const md = generateStoryMarkdown(story);
+
+    expect(md).toContain('not-json');
+  });
+});
+
+describe('writeStoryMarkdown', () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it('should write a markdown file in storiesDir', () => {
+    const story = makeStory();
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+
+    expect(existsSync(filePath)).toBe(true);
+    expect(filePath).toBe(join(TEST_DIR, 'STORY-TEST01.md'));
+  });
+
+  it('should create the directory if it does not exist', () => {
+    const nestedDir = join(TEST_DIR, 'nested', 'stories');
+    const story = makeStory();
+    writeStoryMarkdown(nestedDir, story);
+
+    expect(existsSync(nestedDir)).toBe(true);
+    expect(existsSync(join(nestedDir, 'STORY-TEST01.md'))).toBe(true);
+  });
+
+  it('should write valid markdown content', () => {
+    const story = makeStory({ description: 'My description.' });
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+    const content = readFileSync(filePath, 'utf-8');
+
+    expect(content).toContain('# Test Story');
+    expect(content).toContain('My description.');
+  });
+
+  it('should overwrite existing file on update', () => {
+    const story = makeStory({ title: 'Old Title' });
+    writeStoryMarkdown(TEST_DIR, story);
+
+    const updatedStory = makeStory({ title: 'New Title' });
+    const filePath = writeStoryMarkdown(TEST_DIR, updatedStory);
+    const content = readFileSync(filePath, 'utf-8');
+
+    expect(content).toContain('# New Title');
+    expect(content).not.toContain('# Old Title');
+  });
+});
+
+describe('deleteStoryMarkdown', () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it('should delete the markdown file', () => {
+    const story = makeStory();
+    const filePath = writeStoryMarkdown(TEST_DIR, story);
+    expect(existsSync(filePath)).toBe(true);
+
+    deleteStoryMarkdown(TEST_DIR, story.id);
+    expect(existsSync(filePath)).toBe(false);
+  });
+
+  it('should not throw if file does not exist', () => {
+    expect(() => deleteStoryMarkdown(TEST_DIR, 'STORY-NONEXISTENT')).not.toThrow();
+  });
+});

package/src/utils/story-markdown.ts

@@ -0,0 +1,94 @@
+// Licensed under the Hungry Ghost Hive License. See LICENSE.
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import type { StoryRow } from '../db/client.js';
+
+/**
+ * Generate markdown content for a story.
+ */
+export function generateStoryMarkdown(story: StoryRow): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${story.title}`);
+  lines.push('');
+  lines.push(`**Story ID:** ${story.id}`);
+  lines.push(`**Status:** ${story.status}`);
+
+  if (story.team_id) {
+    lines.push(`**Team:** ${story.team_id}`);
+  }
+  if (story.requirement_id) {
+    lines.push(`**Requirement:** ${story.requirement_id}`);
+  }
+  if (story.assigned_agent_id) {
+    lines.push(`**Assigned Agent:** ${story.assigned_agent_id}`);
+  }
+  if (story.complexity_score !== null) {
+    lines.push(`**Complexity:** ${story.complexity_score}`);
+  }
+  if (story.story_points !== null) {
+    lines.push(`**Story Points:** ${story.story_points}`);
+  }
+  if (story.branch_name) {
+    lines.push(`**Branch:** ${story.branch_name}`);
+  }
+  if (story.pr_url) {
+    lines.push(`**PR:** ${story.pr_url}`);
+  }
+
+  lines.push('');
+  lines.push('## Description');
+  lines.push('');
+  lines.push(story.description);
+
+  if (story.acceptance_criteria) {
+    lines.push('');
+    lines.push('## Acceptance Criteria');
+    lines.push('');
+    try {
+      const criteria = JSON.parse(story.acceptance_criteria) as string[];
+      for (const criterion of criteria) {
+        lines.push(`- [ ] ${criterion}`);
+      }
+    } catch {
+      lines.push(story.acceptance_criteria);
+    }
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push(`*Created: ${story.created_at}*`);
+  lines.push(`*Updated: ${story.updated_at}*`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Write a story as a markdown file in the storiesDir.
+ * Creates the directory if it does not exist.
+ * Returns the path to the written file.
+ */
+export function writeStoryMarkdown(storiesDir: string, story: StoryRow): string {
+  mkdirSync(storiesDir, { recursive: true });
+
+  const fileName = `${story.id}.md`;
+  const filePath = join(storiesDir, fileName);
+  const content = generateStoryMarkdown(story);
+
+  writeFileSync(filePath, content, 'utf-8');
+
+  return filePath;
+}
+
+/**
+ * Delete a story's markdown file if it exists.
+ */
+export function deleteStoryMarkdown(storiesDir: string, storyId: string): void {
+  const filePath = join(storiesDir, `${storyId}.md`);
+  if (existsSync(filePath)) {
+    rmSync(filePath);
+  }
+}