jettypod 3.0.1

package/lib/decisions-generator.test.js

@@ -0,0 +1,457 @@
+const { generateDecisionsFile } = require('./decisions-generator');
+const { createTestEnvironment } = require('./test-helpers');
+const { getDb, closeDb, resetDb } = require('./database');
+const config = require('./config');
+const fs = require('fs');
+const path = require('path');
+
+describe('Decisions Generator', () => {
+  let testEnv;
+  let db;
+
+  beforeEach(() => {
+    resetDb();
+    testEnv = createTestEnvironment();
+    process.chdir(testEnv.testDir);
+    db = getDb();
+  });
+
+  afterEach(async () => {
+    
+    
+    await closeDb();
+    testEnv.cleanup();
+    resetDb();
+  });
+
+  describe('generateDecisionsFile', () => {
+    test('creates docs directory if it does not exist', async () => {
+      // Ensure db is ready
+      await new Promise((resolve) => {
+        db.get('SELECT 1', [], resolve);
+      });
+
+      const docsDir = path.join(process.cwd(), 'docs');
+      expect(fs.existsSync(docsDir)).toBe(false);
+
+      await generateDecisionsFile();
+
+      expect(fs.existsSync(docsDir)).toBe(true);
+    });
+
+    test('creates DECISIONS.md in docs directory', async () => {
+      await new Promise((resolve) => {
+        db.get('SELECT 1', [], resolve);
+      });
+
+      const decisionsPath = path.join(process.cwd(), 'docs', 'DECISIONS.md');
+
+      await generateDecisionsFile();
+
+      expect(fs.existsSync(decisionsPath)).toBe(true);
+    });
+
+    test('generates file with header when no decisions exist', async () => {
+      await new Promise((resolve) => {
+        db.get('SELECT 1', [], resolve);
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('# Architectural and Technical Decisions');
+      expect(content).toContain('This document records key decisions made during project discovery and epic planning');
+    });
+
+    test('includes project-level decision when it exists', async () => {
+      await new Promise((resolve) => {
+        db.get('SELECT 1', [], resolve);
+      });
+
+      // Mock config with decision
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/rest-api',
+          rationale: 'Simple and widely understood',
+          started_date: '2025-10-31T00:00:00.000Z'
+        }
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('## Project-Level Decisions');
+      expect(content).toContain('prototypes/rest-api');
+      expect(content).toContain('Simple and widely understood');
+
+      config.read = originalRead;
+    });
+
+    test('formats project decision date correctly', async () => {
+      await new Promise((resolve) => { db.get("SELECT 1", [], resolve); });
+
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/test',
+          rationale: 'Testing',
+          started_date: '2025-10-31T00:00:00.000Z'
+        }
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      const date = new Date('2025-10-31T00:00:00.000Z');
+      expect(content).toContain(date.toLocaleDateString());
+
+      config.read = originalRead;
+    });
+
+    test('handles missing project rationale gracefully', async () => {
+      await new Promise((resolve) => { db.get("SELECT 1", [], resolve); });
+
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/test'
+        }
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('prototypes/test');
+      expect(content).not.toContain('**Rationale:**');
+
+      config.read = originalRead;
+    });
+
+    test('handles missing project date gracefully', async () => {
+      await new Promise((resolve) => { db.get("SELECT 1", [], resolve); });
+
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/test',
+          rationale: 'Testing'
+        }
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('prototypes/test');
+      expect(content).not.toContain('**Date:**');
+
+      config.read = originalRead;
+    });
+
+    test('includes epic decisions when they exist', async () => {
+      // Create epic with decision
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple and widely understood'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('## Epic-Level Decisions');
+      expect(content).toContain('Epic #1: Test Epic');
+      expect(content).toContain('**Architecture:** REST API');
+      expect(content).toContain('*Rationale:* Simple and widely understood');
+    });
+
+    test('formats epic decision dates correctly', async () => {
+      // Create epic with decision
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale, created_at) VALUES (?, ?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple', '2025-10-31 12:00:00'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('*Date:*');
+    });
+
+    test('groups multiple decisions by epic', async () => {
+      // Create epic with multiple decisions
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Database', 'PostgreSQL', 'Robust'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      // Should have one epic section with two decisions
+      const epicSections = content.match(/### Epic #1:/g);
+      expect(epicSections).toHaveLength(1);
+      expect(content).toContain('**Architecture:** REST API');
+      expect(content).toContain('**Database:** PostgreSQL');
+    });
+
+    test('separates decisions from different epics', async () => {
+      // Create two epics with decisions
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Epic 1'], resolve);
+      });
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Epic 2'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [2, 'Architecture', 'GraphQL', 'Flexible'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('### Epic #1: Epic 1');
+      expect(content).toContain('### Epic #2: Epic 2');
+      expect(content).toContain('REST API');
+      expect(content).toContain('GraphQL');
+    });
+
+    test('includes both project and epic decisions in single file', async () => {
+      // Mock project decision
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/web-app',
+          rationale: 'Web-first approach'
+        }
+      });
+
+      // Create epic with decision
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('## Project-Level Decisions');
+      expect(content).toContain('prototypes/web-app');
+      expect(content).toContain('## Epic-Level Decisions');
+      expect(content).toContain('REST API');
+
+      config.read = originalRead;
+    });
+
+    test('overwrites existing DECISIONS.md file', async () => {
+      // Ensure db is ready
+      await new Promise((resolve) => {
+        db.get('SELECT 1', [], resolve);
+      });
+
+      const decisionsPath = path.join(process.cwd(), 'docs', 'DECISIONS.md');
+
+      // Create initial file
+      await generateDecisionsFile();
+      const initialContent = fs.readFileSync(decisionsPath, 'utf8');
+
+      // Add a decision
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'New Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      // Regenerate
+      await generateDecisionsFile();
+      const updatedContent = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(updatedContent).not.toBe(initialContent);
+      expect(updatedContent).toContain('New Epic');
+    });
+
+    test('returns path to generated file', async () => {
+      // Ensure db is ready
+      await new Promise((resolve) => {
+        db.get('SELECT 1', [], resolve);
+      });
+
+      const returnedPath = await generateDecisionsFile();
+      const expectedPath = path.join(process.cwd(), 'docs', 'DECISIONS.md');
+
+      expect(returnedPath).toBe(expectedPath);
+    });
+
+    test('generates valid markdown structure', async () => {
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/test',
+          rationale: 'Testing'
+        }
+      });
+
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', 'Simple'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      // Check markdown structure
+      expect(content).toContain('# Architectural and Technical Decisions');
+      expect(content).toContain('## Project-Level Decisions');
+      expect(content).toContain('### UX Approach & Tech Stack');
+      expect(content).toContain('## Epic-Level Decisions');
+      expect(content).toContain('### Epic #1');
+      expect(content).toContain('---'); // Section separators
+
+      config.read = originalRead;
+    });
+
+    test('orders epic decisions by created_at ASC', async () => {
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      // Add decisions with specific timestamps
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale, created_at) VALUES (?, ?, ?, ?, ?)',
+          [1, 'Second', 'Decision 2', 'Later', '2025-10-31 12:00:00'],
+          resolve
+        );
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale, created_at) VALUES (?, ?, ?, ?, ?)',
+          [1, 'First', 'Decision 1', 'Earlier', '2025-10-31 11:00:00'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      const firstIndex = content.indexOf('**First:**');
+      const secondIndex = content.indexOf('**Second:**');
+
+      expect(firstIndex).toBeLessThan(secondIndex);
+    });
+
+    test('handles empty rationale field', async () => {
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test Epic'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Architecture', 'REST API', ''],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      // Should still include the decision even with empty rationale
+      expect(content).toContain('**Architecture:** REST API');
+    });
+
+    test('handles special characters in decisions', async () => {
+      const originalRead = config.read;
+      config.read = () => ({
+        project_discovery: {
+          winner: 'prototypes/api-v2.0',
+          rationale: 'RESTful API with OAuth 2.0 & JWT tokens'
+        }
+      });
+
+      await new Promise((resolve) => {
+        db.run('INSERT INTO work_items (type, title) VALUES (?, ?)', ['epic', 'Test & Production'], resolve);
+      });
+
+      await new Promise((resolve) => {
+        db.run(
+          'INSERT INTO discovery_decisions (work_item_id, aspect, decision, rationale) VALUES (?, ?, ?, ?)',
+          [1, 'Auth & Security', 'OAuth 2.0', 'Industry standard (RFC 6749)'],
+          resolve
+        );
+      });
+
+      const decisionsPath = await generateDecisionsFile();
+      const content = fs.readFileSync(decisionsPath, 'utf8');
+
+      expect(content).toContain('api-v2.0');
+      expect(content).toContain('OAuth 2.0 & JWT');
+      expect(content).toContain('Test & Production');
+      expect(content).toContain('RFC 6749');
+
+      config.read = originalRead;
+    });
+  });
+});

package/lib/decisions-helpers.js

@@ -0,0 +1,119 @@
+// Decision query helpers for Claude to use programmatically
+const { getDb } = require('./database');
+const config = require('./config');
+
+/**
+ * Get project-level decision (UX approach & tech stack)
+ * @returns {Object|null} Project decision with winner, rationale, started_date
+ */
+function getProjectDecision() {
+  try {
+    const projectConfig = config.read();
+    if (projectConfig.project_discovery && projectConfig.project_discovery.winner) {
+      return {
+        winner: projectConfig.project_discovery.winner,
+        rationale: projectConfig.project_discovery.rationale || null,
+        started_date: projectConfig.project_discovery.started_date || null
+      };
+    }
+    return null;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Get all decisions for a specific epic
+ * @param {number} epicId - The epic ID
+ * @returns {Promise<Array>} Array of decision objects with aspect, decision, rationale, created_at
+ */
+function getDecisionsForEpic(epicId) {
+  const db = getDb();
+
+  return new Promise((resolve, reject) => {
+    db.all(`
+      SELECT dd.*, w.title as epic_title, w.id as epic_id
+      FROM discovery_decisions dd
+      JOIN work_items w ON dd.work_item_id = w.id
+      WHERE dd.work_item_id = ?
+      ORDER BY dd.created_at ASC
+    `, [epicId], (err, rows) => {
+      if (err) {
+        return reject(err);
+      }
+      resolve(rows || []);
+    });
+  });
+}
+
+/**
+ * Get all epic-level decisions across all epics
+ * @returns {Promise<Array>} Array of decision objects with epic info
+ */
+function getAllEpicDecisions() {
+  const db = getDb();
+
+  return new Promise((resolve, reject) => {
+    db.all(`
+      SELECT dd.*, w.title as epic_title, w.id as epic_id
+      FROM discovery_decisions dd
+      JOIN work_items w ON dd.work_item_id = w.id
+      ORDER BY dd.created_at ASC
+    `, [], (err, rows) => {
+      if (err) {
+        return reject(err);
+      }
+      resolve(rows || []);
+    });
+  });
+}
+
+/**
+ * Get all decisions (project + epic) in a structured format
+ * @returns {Promise<Object>} Object with project and epics keys
+ */
+async function getAllDecisions() {
+  const project = getProjectDecision();
+  const epicDecisions = await getAllEpicDecisions();
+
+  // Group epic decisions by epic ID
+  const epicGroups = {};
+  epicDecisions.forEach(decision => {
+    if (!epicGroups[decision.epic_id]) {
+      epicGroups[decision.epic_id] = {
+        id: decision.epic_id,
+        title: decision.epic_title,
+        decisions: []
+      };
+    }
+    epicGroups[decision.epic_id].decisions.push({
+      aspect: decision.aspect,
+      decision: decision.decision,
+      rationale: decision.rationale,
+      created_at: decision.created_at
+    });
+  });
+
+  return {
+    project,
+    epics: Object.values(epicGroups)
+  };
+}
+
+/**
+ * Check if an epic has any decisions recorded
+ * @param {number} epicId - The epic ID
+ * @returns {Promise<boolean>} True if epic has decisions
+ */
+async function hasDecisions(epicId) {
+  const decisions = await getDecisionsForEpic(epicId);
+  return decisions.length > 0;
+}
+
+module.exports = {
+  getProjectDecision,
+  getDecisionsForEpic,
+  getAllEpicDecisions,
+  getAllDecisions,
+  hasDecisions
+};