dhurandhar 1.0.0

package/docs/test-first-example.md

@@ -0,0 +1,392 @@
+# Test-First Agile - Complete Example
+
+## Scenario: Building Authentication System
+
+Let's build a complete authentication system using Dhurandhar's test-first approach.
+
+## Step 1: Initialize Framework
+
+```bash
+$ dhurandhar install
+
+🔧 Dhurandhar - Engineering-First System Design
+
+? Project identifier: my-auth-system
+? Architecture type: microservices
+? Primary language: go
+
+✓ Framework installed!
+
+System initialized:
+  SYSTEM_DESIGN_MAP.yaml - Persistent architecture state
+```
+
+## Step 2: Define Services (Engineering-First)
+
+```bash
+$ dhurandhar service add "auth: JWT authentication and session management"
+
+? Framework: Echo
+? Database: PostgreSQL
+
+✓ auth-service added: Go/Echo/PostgreSQL on port 8080
+✓ Updated SYSTEM_DESIGN_MAP.yaml
+```
+
+## Step 3: Define Entities (Engineering-First)
+
+```bash
+$ dhurandhar entity add User
+
+? Add custom attributes now? Yes
+? Attribute name: email
+? Type: varchar
+? Add another? Yes
+? Attribute name: password_hash
+? Type: varchar
+? Add another? No
+
+✓ User entity added to data model
+```
+
+```bash
+$ dhurandhar entity add Session
+
+? Add custom attributes now? Yes
+? Attribute name: token
+? Type: varchar
+? Add another? Yes
+? Attribute name: expires_at
+? Type: timestamp
+? Add another? No
+
+✓ Session entity added
+```
+
+```bash
+$ dhurandhar entity --relate
+
+? From entity: Session
+? To entity: User
+? Relationship type: many_to_one
+
+✓ Relationship added: Session → User
+```
+
+## Step 4: Define Epic (Test-First Agile)
+
+```bash
+$ dhurandhar epic add "User Authentication & Authorization"
+
+? Technical description: JWT-based auth with email/password and OAuth2
+
+✓ Epic EPIC-001 added
+
+Next: Add Stories
+  dhurandhar story add --epic EPIC-001
+```
+
+## Step 5: Define Stories (Test-First Agile)
+
+### Story 1: Email/Password Login
+
+```bash
+$ dhurandhar story add "Email/Password Login" --epic EPIC-001
+
+Technical specification (max 3 questions):
+
+? 1. Target service: auth-service
+? 2. API endpoint: /api/v1/auth/login
+? 3. HTTP method: POST
+
+✓ Story STORY-001 added with 2 tasks
+
+Next: Generate contract tests
+  dhurandhar test --generate
+```
+
+### Story 2: Token Refresh
+
+```bash
+$ dhurandhar story add "JWT Token Refresh" --epic EPIC-001
+
+? 1. Target service: auth-service
+? 2. API endpoint: /api/v1/auth/refresh
+? 3. HTTP method: POST
+
+✓ Story STORY-002 added with 2 tasks
+```
+
+### Story 3: Logout
+
+```bash
+$ dhurandhar story add "User Logout" --epic EPIC-001
+
+? 1. Target service: auth-service
+? 2. API endpoint: /api/v1/auth/logout
+? 3. HTTP method: POST
+
+✓ Story STORY-003 added with 2 tasks
+```
+
+## Step 6: Generate Contract Tests
+
+```bash
+$ dhurandhar test --init
+
+🔧 Initialize Test Infrastructure
+
+✓ Test infrastructure ready
+```
+
+```bash
+$ dhurandhar test --generate
+
+📋 Generate Contract-First Test Suite
+
+✓ Generated 9 test suites
+
+Generated files:
+  tests/contracts/story-001-standard.test.js
+  tests/contracts/story-001-errors.test.js
+  tests/edge-cases/story-001-edge.test.js
+  tests/contracts/story-002-standard.test.js
+  tests/contracts/story-002-errors.test.js
+  tests/edge-cases/story-002-edge.test.js
+  tests/contracts/story-003-standard.test.js
+  tests/contracts/story-003-errors.test.js
+  tests/edge-cases/story-003-edge.test.js
+
+Next steps:
+  1. Install test dependencies: npm install -D vitest
+  2. Review generated tests in tests/ directory
+  3. Run tests: npm test
+  4. Implement services to pass the tests
+```
+
+## Step 7: Review Generated Tests
+
+### Example: tests/contracts/story-001-standard.test.js
+
+```javascript
+/**
+ * Contract Test: Email/Password Login
+ * Story: STORY-001
+ * Service: auth-service
+ * Endpoint: POST /api/v1/auth/login
+ */
+
+import { describe, it, expect } from 'vitest';
+import { apiClient } from '../utils/api-client';
+
+describe('Email/Password Login - Standard Flows', () => {
+  it('should login successfully with valid credentials', async () => {
+    const response = await apiClient.post('/api/v1/auth/login', {
+      email: 'user@example.com',
+      password: 'ValidPass123!',
+    });
+    
+    expect(response.status).toBe(200);
+    expect(response.data).toHaveProperty('access_token');
+    expect(response.data).toHaveProperty('refresh_token');
+    expect(response.data).toHaveProperty('expires_in');
+  });
+  
+  it('should return user information', async () => {
+    const response = await apiClient.post('/api/v1/auth/login', {
+      email: 'user@example.com',
+      password: 'ValidPass123!',
+    });
+    
+    expect(response.data).toHaveProperty('user');
+    expect(response.data.user).toHaveProperty('id');
+    expect(response.data.user).toHaveProperty('email');
+    expect(response.data.user.email).toBe('user@example.com');
+  });
+});
+```
+
+## Step 8: Run Tests (Before Implementation)
+
+```bash
+$ npm install -D vitest
+$ npm test
+
+ FAIL  tests/contracts/story-001-standard.test.js
+  ✕ Email/Password Login - Standard Flows
+    ✕ should login successfully with valid credentials (0 ms)
+      NetworkError: connect ECONNREFUSED localhost:8080
+
+ FAIL  tests/contracts/story-001-errors.test.js
+  ✕ Email/Password Login - Error States
+    ✕ should return 400 for missing email (0 ms)
+    ✕ should return 401 for invalid password (0 ms)
+
+Test Suites: 9 failed, 9 total
+Tests:       27 failed, 27 total
+```
+
+**This is correct!** Tests fail because we haven't implemented the service yet.
+
+## Step 9: Implement Service (Guided by Tests)
+
+Now implement `auth-service` to pass the contract tests:
+
+1. Create Go service with Echo framework
+2. Implement `/api/v1/auth/login` endpoint
+3. Follow the contract defined in tests:
+   - Accept `email` and `password` in request body
+   - Return `access_token`, `refresh_token`, `expires_in`, `user`
+   - Return 400 for missing fields
+   - Return 401 for invalid credentials
+
+## Step 10: Run Tests (After Implementation)
+
+```bash
+$ npm test
+
+ PASS  tests/contracts/story-001-standard.test.js
+  ✓ Email/Password Login - Standard Flows
+    ✓ should login successfully with valid credentials (45 ms)
+    ✓ should return user information (12 ms)
+
+ PASS  tests/contracts/story-001-errors.test.js
+  ✓ Email/Password Login - Error States
+    ✓ should return 400 for missing email (8 ms)
+    ✓ should return 401 for invalid password (15 ms)
+
+Test Suites: 9 passed, 9 total
+Tests:       27 passed, 27 total
+```
+
+**Success!** Implementation passes all contract tests.
+
+## Step 11: Validate Coverage
+
+```bash
+$ dhurandhar test --validate
+
+✅ Validate Story Coverage
+
+Coverage Report:
+  Total Stories: 3
+  Test Coverage: 100% (3/3)
+  Implementation: 100% (3/3)
+
+✓ Full coverage!
+```
+
+## Step 12: View Complete Architecture
+
+```bash
+$ dhurandhar context --full
+
+🏗️  System Architecture Context
+
+Project Metadata
+Name: my-auth-system
+Version: 1.0.0
+Architecture: microservices
+
+Tech Stack
+Languages: Go
+Frameworks: Echo
+Databases: PostgreSQL
+
+Entities (2)
+  User (5 attributes)
+  Session (4 attributes)
+    many_to_one → User
+
+Services (1)
+  auth-service
+    JWT authentication and session management
+    Stack: Go/Echo/PostgreSQL
+    API: rest /api/v1/auth :8080
+
+Agile Blueprint
+  Epics: 1
+  Stories: 3
+  Test Coverage: 100%
+
+This context is persisted in SYSTEM_DESIGN_MAP.yaml
+```
+
+## Benefits Demonstrated
+
+### 1. Speed
+
+- **Traditional**: 2-3 days of requirements gathering, planning, design
+- **Dhurandhar**: 15 minutes from concept to complete test suite
+
+### 2. Clarity
+
+- Tests define exact API contract
+- No ambiguity about what to implement
+- Implementation guided by failing tests
+
+### 3. Coverage
+
+- 100% test coverage before implementation
+- All error states tested
+- Edge cases identified by Edge Case Hunter
+
+### 4. Persistence
+
+- All decisions in SYSTEM_DESIGN_MAP.yaml
+- Next session: instant context rehydration
+- No rediscovery needed
+
+## Complete SYSTEM_DESIGN_MAP.yaml
+
+```yaml
+metadata:
+  project_name: my-auth-system
+  architecture_type: microservices
+  
+services:
+  - name: auth-service
+    scope: "JWT authentication and session management"
+    tech_stack:
+      language: Go
+      framework: Echo
+      database: PostgreSQL
+
+entities:
+  - name: User
+    attributes:
+      - name: email
+        type: varchar
+  - name: Session
+    relationships:
+      - type: many_to_one
+        target: User
+
+agile_blueprint:
+  epics:
+    - id: EPIC-001
+      name: "User Authentication & Authorization"
+      stories:
+        - id: STORY-001
+          name: "Email/Password Login"
+          interaction_boundary:
+            service: auth-service
+            api_endpoint: /api/v1/auth/login
+            method: POST
+          tasks:
+            - id: TASK-001-001
+              type: test
+              status: complete
+            - id: TASK-001-002
+              type: implementation
+              status: complete
+  
+  test_suite_status:
+    total_stories: 3
+    tested_stories: 3
+    coverage_percentage: 100
+```
+
+---
+
+**Result**: Complete authentication system with 100% test coverage, defined and implemented in under 30 minutes.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "dhurandhar",
+  "version": "1.0.0",
+  "description": "Engineering-First + Test-First + Strategy-Driven + Decision-Stocked Framework - Bmad-level maturity with zero cognitive fatigue",
+  "keywords": [
+    "system-design",
+    "architecture",
+    "framework",
+    "engineering-first",
+    "test-first",
+    "strategy-driven",
+    "decision-registry",
+    "drift-detection",
+    "bmad-method",
+    "system-design-map",
+    "sdm",
+    "architectural-patterns",
+    "code-generation",
+    "technical-decisions"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rweb22/dhurandhar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rweb22/dhurandhar/issues"
+  },
+  "homepage": "https://github.com/rweb22/dhurandhar#readme",
+  "license": "MIT",
+  "author": "Dhurandhar Contributors",
+  "private": false,
+  "type": "module",
+  "main": "tools/cli/dhurandhar.js",
+  "bin": {
+    "dhurandhar": "tools/cli/dhurandhar.js"
+  },
+  "files": [
+    "tools/",
+    "src/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    ".dhurandhar-session-start.md"
+  ],
+  "scripts": {
+    "cli": "node tools/cli/dhurandhar.js",
+    "install:framework": "node tools/cli/dhurandhar.js install",
+    "config": "node tools/cli/dhurandhar.js config",
+    "test": "node --test test/unit/**/*.test.js",
+    "test:integration": "node --test test/integration/**/*.test.js",
+    "test:all": "npm run test && npm run test:integration",
+    "lint": "eslint . --ext .js,.mjs --max-warnings=0",
+    "lint:fix": "eslint . --ext .js,.mjs --fix",
+    "format:check": "prettier --check \"**/*.{js,mjs,json,yaml,yml,md}\"",
+    "format:fix": "prettier --write \"**/*.{js,mjs,json,yaml,yml,md}\"",
+    "validate:config": "node tools/lib/validators/config-validator.js",
+    "validate:modules": "node tools/lib/validators/module-validator.js"
+  },
+  "dependencies": {
+    "@clack/core": "^1.0.0",
+    "@clack/prompts": "^1.0.0",
+    "chalk": "^5.3.0",
+    "commander": "^14.0.0",
+    "fs-extra": "^11.3.0",
+    "glob": "^11.0.3",
+    "js-yaml": "^4.1.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^10.1.0",
+    "prettier": "^3.4.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/core/README.md

@@ -0,0 +1,92 @@
+# Dhurandhar Core Module
+
+The Core Module provides essential components and utilities for the Dhurandhar framework.
+
+## Overview
+
+This module contains:
+
+- **Base Templates**: Foundational templates for creating design modules
+- **System Mapper**: Utilities for mapping and visualizing system architectures
+- **Schema Definitions**: Standard schemas for design components and configurations
+
+## Components
+
+### Base Design Template
+
+A standardized template for creating new design modules. Includes:
+
+- Module metadata structure
+- Configuration schema
+- Component organization patterns
+- Export definitions
+
+### System Mapper
+
+Utilities for working with system designs:
+
+- Component relationship mapping
+- Dependency analysis
+- Visualization helpers
+- Export/import functionality
+
+### Schema Definitions
+
+Standard schemas for:
+
+- Design modules
+- System components
+- Configuration files
+- Validation rules
+
+## Usage
+
+The core module is automatically installed with the Dhurandhar framework and provides the foundation for all other modules.
+
+### Creating a Design Module
+
+```yaml
+# Based on core templates
+code: my-design
+name: "My Design Module"
+extends: core/base-design
+
+components:
+  - name: frontend
+    type: application
+  - name: backend
+    type: service
+```
+
+### Using System Mapper
+
+```javascript
+import { SystemMapper } from '@dhurandhar/core';
+
+const mapper = new SystemMapper();
+const system = await mapper.load('my-design');
+const dependencies = mapper.analyzeDependencies(system);
+```
+
+## Configuration
+
+The core module can be configured in `.dhurandhar/config.yaml`:
+
+```yaml
+modules:
+  core:
+    enable_validation: true
+    cache_enabled: true
+```
+
+## Dependencies
+
+None - this is the foundational module.
+
+## Version
+
+0.1.0
+
+## License
+
+MIT