cadr-cli 0.0.1 → 1.9.2

package/dist/version.test.js

@@ -0,0 +1,25 @@
+"use strict";
+// Test version constants in CLI
+const CORE_VERSION = '0.0.1';
+const CLI_VERSION = '0.0.1';
+describe('CLI Version Constants', () => {
+    test('exports CORE_VERSION constant', () => {
+        expect(CORE_VERSION).toBe('0.0.1');
+    });
+    test('CORE_VERSION is a string', () => {
+        expect(typeof CORE_VERSION).toBe('string');
+    });
+    test('CORE_VERSION matches semantic version pattern', () => {
+        expect(CORE_VERSION).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+    test('exports CLI_VERSION constant', () => {
+        expect(CLI_VERSION).toBe('0.0.1');
+    });
+    test('CLI_VERSION is a string', () => {
+        expect(typeof CLI_VERSION).toBe('string');
+    });
+    test('CLI_VERSION matches semantic version pattern', () => {
+        expect(CLI_VERSION).toMatch(/^\d+\.\d+\.\d+$/);
+    });
+});
+//# sourceMappingURL=version.test.js.map

package/dist/version.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.test.js","sourceRoot":"","sources":["../src/version.test.ts"],"names":[],"mappings":";AAAA,gCAAgC;AAChC,MAAM,YAAY,GAAG,OAAO,CAAC;AAC7B,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,IAAI,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACpC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "cadr-cli",
-  "version": "0.0.1",
+  "version": "1.9.2",
   "description": "Continuous Architectural Decision Records - Automatically capture ADRs as you code",
   "main": "dist/index.js",
   "bin": {
-    "cadr": "./bin/cadr.js"
+    "cadr": "./dist/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run postbuild",
+    "postbuild": "if [ -f dist/index.js ]; then if ! head -1 dist/index.js | grep -q '^#!/usr/bin/env node$'; then echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js; fi; chmod +x dist/index.js; fi",
     "test": "jest"
   },
   "keywords": [
@@ -17,7 +18,7 @@
     "decision-records",
     "documentation"
   ],
-  "author": "",
+  "author": "Yotpo Ltd.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +27,15 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "pino": "^8.17.2"
+    "pino": "^8.17.2",
+    "openai": "^4.0.0",
+    "@google/generative-ai": "^0.21.0",
+    "js-yaml": "^4.1.0",
+    "yup": "^1.0.0",
+    "commander": "^11.0.0"
   }
 }

package/src/adr.test.ts

@@ -0,0 +1,278 @@
+/**
+ * ADR File Management Module Tests
+ * 
+ * Tests for ADR file creation, numbering, and management.
+ * Following TDD: These tests are written BEFORE implementation.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  titleToSlug,
+  getNextADRNumber,
+  generateADRFilename,
+  ensureADRDirectory,
+  saveADR,
+  DEFAULT_ADR_DIR,
+} from './adr';
+
+describe('ADR Module', () => {
+  const testDir = path.join(__dirname, '../test-adrs');
+
+  beforeEach(() => {
+    // Clean up test directory before each test
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  afterEach(() => {
+    // Clean up test directory after each test
+    if (fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('titleToSlug', () => {
+    it('converts title to lowercase slug', () => {
+      expect(titleToSlug('Use PostgreSQL for Storage')).toBe('use-postgresql-for-storage');
+    });
+
+    it('replaces spaces with hyphens', () => {
+      expect(titleToSlug('My Great Decision')).toBe('my-great-decision');
+    });
+
+    it('handles special characters', () => {
+      expect(titleToSlug('API v2.0: New Endpoints!')).toBe('api-v2-0-new-endpoints');
+    });
+
+    it('removes leading and trailing hyphens', () => {
+      expect(titleToSlug('---Test Title---')).toBe('test-title');
+    });
+
+    it('handles multiple consecutive spaces', () => {
+      expect(titleToSlug('Too    Many    Spaces')).toBe('too-many-spaces');
+    });
+
+    it('handles empty string', () => {
+      expect(titleToSlug('')).toBe('');
+    });
+
+    it('handles only special characters', () => {
+      expect(titleToSlug('!!!')).toBe('');
+    });
+  });
+
+  describe('generateADRFilename', () => {
+    it('generates properly formatted filename', () => {
+      expect(generateADRFilename(1, 'Use PostgreSQL')).toBe('0001-use-postgresql.md');
+    });
+
+    it('pads numbers with zeros to 4 digits', () => {
+      expect(generateADRFilename(42, 'Test Decision')).toBe('0042-test-decision.md');
+    });
+
+    it('handles three-digit numbers', () => {
+      expect(generateADRFilename(123, 'Another Decision')).toBe('0123-another-decision.md');
+    });
+
+    it('handles four-digit numbers', () => {
+      expect(generateADRFilename(9999, 'Max Decision')).toBe('9999-max-decision.md');
+    });
+
+    it('handles titles with special characters', () => {
+      expect(generateADRFilename(5, 'Switch to React v18!')).toBe('0005-switch-to-react-v18.md');
+    });
+  });
+
+  describe('getNextADRNumber', () => {
+    it('returns 1 for non-existent directory', () => {
+      expect(getNextADRNumber(testDir)).toBe(1);
+    });
+
+    it('returns 1 for empty directory', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      expect(getNextADRNumber(testDir)).toBe(1);
+    });
+
+    it('returns next number after existing ADRs', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, '0001-first.md'), '# First');
+      fs.writeFileSync(path.join(testDir, '0002-second.md'), '# Second');
+      expect(getNextADRNumber(testDir)).toBe(3);
+    });
+
+    it('handles non-sequential numbers correctly', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, '0001-first.md'), '# First');
+      fs.writeFileSync(path.join(testDir, '0005-fifth.md'), '# Fifth');
+      expect(getNextADRNumber(testDir)).toBe(6);
+    });
+
+    it('ignores files without number prefix', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, '0001-first.md'), '# First');
+      fs.writeFileSync(path.join(testDir, 'README.md'), '# README');
+      fs.writeFileSync(path.join(testDir, 'template.md'), '# Template');
+      expect(getNextADRNumber(testDir)).toBe(2);
+    });
+
+    it('ignores files with incorrect number format', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, '0001-first.md'), '# First');
+      fs.writeFileSync(path.join(testDir, '1-wrong.md'), '# Wrong');
+      fs.writeFileSync(path.join(testDir, '00002-also-wrong.md'), '# Also Wrong');
+      expect(getNextADRNumber(testDir)).toBe(2);
+    });
+
+    it('handles directory with only non-ADR files', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      fs.writeFileSync(path.join(testDir, 'README.md'), '# README');
+      expect(getNextADRNumber(testDir)).toBe(1);
+    });
+  });
+
+  describe('ensureADRDirectory', () => {
+    it('creates directory if it does not exist', () => {
+      ensureADRDirectory(testDir);
+      expect(fs.existsSync(testDir)).toBe(true);
+      expect(fs.statSync(testDir).isDirectory()).toBe(true);
+    });
+
+    it('creates nested directories recursively', () => {
+      const nestedDir = path.join(testDir, 'nested', 'path');
+      ensureADRDirectory(nestedDir);
+      expect(fs.existsSync(nestedDir)).toBe(true);
+      expect(fs.statSync(nestedDir).isDirectory()).toBe(true);
+    });
+
+    it('does not error if directory already exists', () => {
+      fs.mkdirSync(testDir, { recursive: true });
+      expect(() => ensureADRDirectory(testDir)).not.toThrow();
+      expect(fs.existsSync(testDir)).toBe(true);
+    });
+
+    it('can be called multiple times safely', () => {
+      ensureADRDirectory(testDir);
+      ensureADRDirectory(testDir);
+      ensureADRDirectory(testDir);
+      expect(fs.existsSync(testDir)).toBe(true);
+    });
+  });
+
+  describe('saveADR', () => {
+    it('saves ADR with correct filename in specified directory', () => {
+      const content = '# Use PostgreSQL\n\n* Status: accepted\n\nContent here';
+      const result = saveADR(content, 'Use PostgreSQL', testDir);
+
+      expect(result.success).toBe(true);
+      expect(result.filePath).toBe(path.join(testDir, '0001-use-postgresql.md'));
+      expect(result.error).toBeUndefined();
+      expect(fs.existsSync(result.filePath!)).toBe(true);
+    });
+
+    it('creates directory automatically if it does not exist', () => {
+      const content = '# Test ADR\n\nContent';
+      const result = saveADR(content, 'Test ADR', testDir);
+
+      expect(fs.existsSync(testDir)).toBe(true);
+      expect(result.success).toBe(true);
+    });
+
+    it('increments number for multiple ADRs', () => {
+      const result1 = saveADR('# First\n\nFirst ADR', 'First', testDir);
+      const result2 = saveADR('# Second\n\nSecond ADR', 'Second', testDir);
+      const result3 = saveADR('# Third\n\nThird ADR', 'Third', testDir);
+
+      expect(result1.filePath).toContain('0001-first.md');
+      expect(result2.filePath).toContain('0002-second.md');
+      expect(result3.filePath).toContain('0003-third.md');
+      
+      expect(fs.existsSync(result1.filePath!)).toBe(true);
+      expect(fs.existsSync(result2.filePath!)).toBe(true);
+      expect(fs.existsSync(result3.filePath!)).toBe(true);
+    });
+
+    it('saves correct content to file', () => {
+      const content = '# My Decision\n\n* Status: accepted\n* Date: 2025-10-21\n\n## Context\n\nSome context here.';
+      const result = saveADR(content, 'My Decision', testDir);
+
+      const savedContent = fs.readFileSync(result.filePath!, 'utf-8');
+      expect(savedContent).toBe(content);
+    });
+
+    it('uses default directory when not specified', () => {
+      // Clean up default directory
+      const defaultPath = path.join(process.cwd(), DEFAULT_ADR_DIR);
+      if (fs.existsSync(defaultPath)) {
+        fs.rmSync(defaultPath, { recursive: true, force: true });
+      }
+
+      const content = '# Default Location\n\nContent';
+      const result = saveADR(content, 'Default Location');
+
+      expect(result.success).toBe(true);
+      expect(result.filePath).toContain(DEFAULT_ADR_DIR);
+      
+      // Cleanup
+      if (fs.existsSync(defaultPath)) {
+        fs.rmSync(defaultPath, { recursive: true, force: true });
+      }
+    });
+
+    it('handles file write errors gracefully', () => {
+      // Create a read-only directory to trigger write error
+      fs.mkdirSync(testDir, { recursive: true });
+      
+      // Make directory read-only (if not Windows)
+      if (process.platform !== 'win32') {
+        fs.chmodSync(testDir, 0o444);
+        
+        const content = '# Test\n\nContent';
+        const result = saveADR(content, 'Test', testDir);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.filePath).toBeUndefined();
+        
+        // Restore permissions for cleanup
+        fs.chmodSync(testDir, 0o755);
+      } else {
+        // On Windows, just verify error handling structure exists
+        // Skip actual permission test as Windows permissions work differently
+        const content = '# Test\n\nContent';
+        const result = saveADR(content, 'Test', testDir);
+        
+        // Should succeed on Windows since we can't easily simulate permission errors
+        expect(result).toHaveProperty('success');
+        expect(typeof result.success).toBe('boolean');
+      }
+    });
+
+    it('handles long titles correctly', () => {
+      const longTitle = 'This is a very long title that should still work correctly when converted to a filename slug';
+      const content = `# ${longTitle}\n\nContent`;
+      const result = saveADR(content, longTitle, testDir);
+
+      expect(result.success).toBe(true);
+      expect(result.filePath).toContain('0001-this-is-a-very-long-title');
+    });
+
+    it('handles titles with unicode characters', () => {
+      const content = '# Decision with émojis 🚀\n\nContent';
+      const result = saveADR(content, 'Decision with émojis 🚀', testDir);
+
+      expect(result.success).toBe(true);
+      // Should strip unicode to safe characters
+      expect(result.filePath).toMatch(/0001-.+\.md$/);
+    });
+  });
+
+  describe('DEFAULT_ADR_DIR constant', () => {
+    it('is defined and has expected value', () => {
+      expect(DEFAULT_ADR_DIR).toBeDefined();
+      expect(DEFAULT_ADR_DIR).toBe('docs/adr');
+    });
+  });
+});
+

package/src/adr.ts

@@ -0,0 +1,136 @@
+/**
+ * ADR File Management Module
+ * 
+ * Handles creation and management of Architectural Decision Record files.
+ * Follows MADR (Markdown Architectural Decision Records) format.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { loggerInstance as logger } from './logger';
+
+/**
+ * Default ADR directory relative to project root
+ */
+export const DEFAULT_ADR_DIR = 'docs/adr';
+
+/**
+ * Convert a title to a filename-safe slug
+ * Example: "Use PostgreSQL for Storage" -> "use-postgresql-for-storage"
+ */
+export function titleToSlug(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphens
+    .replace(/^-+|-+$/g, ''); // Remove leading/trailing hyphens
+}
+
+/**
+ * Get the next ADR number by scanning existing ADR files
+ * 
+ * @param adrDir - Directory containing ADR files
+ * @returns Next available ADR number (e.g., 1, 2, 3...)
+ */
+export function getNextADRNumber(adrDir: string): number {
+  try {
+    if (!fs.existsSync(adrDir)) {
+      return 1; // First ADR
+    }
+
+    const files = fs.readdirSync(adrDir);
+    const adrNumbers: number[] = [];
+
+    // Extract numbers from existing ADR files (format: 0001-title.md)
+    for (const file of files) {
+      const match = file.match(/^(\d{4})-/);
+      if (match) {
+        adrNumbers.push(parseInt(match[1], 10));
+      }
+    }
+
+    if (adrNumbers.length === 0) {
+      return 1;
+    }
+
+    // Return next number after the highest existing number
+    return Math.max(...adrNumbers) + 1;
+  } catch (error) {
+    logger.warn('Failed to scan existing ADRs, defaulting to 1', { error, adrDir });
+    return 1;
+  }
+}
+
+/**
+ * Ensure ADR directory exists, create if it doesn't
+ * 
+ * @param adrDir - Directory path to ensure exists
+ */
+export function ensureADRDirectory(adrDir: string): void {
+  if (!fs.existsSync(adrDir)) {
+    logger.info('Creating ADR directory', { adrDir });
+    fs.mkdirSync(adrDir, { recursive: true });
+  }
+}
+
+/**
+ * Generate ADR filename from number and title
+ * 
+ * @param number - ADR number (will be zero-padded to 4 digits)
+ * @param title - ADR title (will be converted to slug)
+ * @returns Filename like "0001-use-postgresql-for-storage.md"
+ */
+export function generateADRFilename(number: number, title: string): string {
+  const paddedNumber = String(number).padStart(4, '0');
+  const slug = titleToSlug(title);
+  return `${paddedNumber}-${slug}.md`;
+}
+
+/**
+ * Save ADR content to file
+ * 
+ * @param content - Full markdown content of the ADR
+ * @param title - Title extracted from ADR content
+ * @param adrDir - Directory to save ADR in (defaults to docs/adr)
+ * @returns Object with success status, file path, and any error
+ */
+export function saveADR(
+  content: string,
+  title: string,
+  adrDir: string = DEFAULT_ADR_DIR
+): { success: boolean; filePath?: string; error?: string } {
+  try {
+    // Ensure directory exists
+    ensureADRDirectory(adrDir);
+
+    // Get next ADR number
+    const adrNumber = getNextADRNumber(adrDir);
+
+    // Generate filename
+    const filename = generateADRFilename(adrNumber, title);
+    const filePath = path.join(adrDir, filename);
+
+    // Check if file already exists (shouldn't happen, but safety check)
+    if (fs.existsSync(filePath)) {
+      logger.warn('ADR file already exists, using alternative name', { filePath });
+      const alternativeFilename = generateADRFilename(adrNumber + 1, title);
+      const alternativeFilePath = path.join(adrDir, alternativeFilename);
+      
+      fs.writeFileSync(alternativeFilePath, content, 'utf-8');
+      logger.info('ADR saved successfully', { filePath: alternativeFilePath });
+      
+      return { success: true, filePath: alternativeFilePath };
+    }
+
+    // Write ADR content to file
+    fs.writeFileSync(filePath, content, 'utf-8');
+
+    logger.info('ADR saved successfully', { filePath, adrNumber });
+
+    return { success: true, filePath };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    logger.error('Failed to save ADR', { error, adrDir });
+    return { success: false, error: errorMessage };
+  }
+}
+