dhurandhar 1.0.0

package/docs/TEST_FIRST_AGILE.md

@@ -0,0 +1,359 @@
+# Test-First Agile Decomposition
+
+## Overview
+
+Dhurandhar v2.1 integrates a **Test-First Agile Decomposition** layer that bridges natural language requirements with engineering-first implementation through contract-driven testing.
+
+## Philosophy
+
+### Traditional Agile (Anti-Pattern)
+
+```
+Requirements → User Stories → Discussion → Planning → Implementation → Tests
+[Weeks of overhead before any code]
+```
+
+### Dhurandhar Test-First Agile
+
+```
+Epic → Story → API Contract → Tests → Implementation
+[Tests written in minutes, define the contract]
+```
+
+**Key Principle**: Tests are technical specifications, not afterthoughts.
+
+## Architecture
+
+### Epic-Story-Task Hierarchy
+
+```
+EPIC (System Capability)
+  └── STORY (User Journey)
+      ├── Interaction Boundary (API Contract)
+      │   ├── Service
+      │   ├── Endpoint
+      │   ├── Request/Response Schema
+      │   └── Error States
+      ├── Technical Acceptance Criteria
+      └── TASKS
+          ├── Test Task (contract tests)
+          └── Implementation Tasks
+```
+
+### Integration with SDM
+
+All Epic/Story/Task data lives in `SYSTEM_DESIGN_MAP.yaml`:
+
+```yaml
+agile_blueprint:
+  epics:
+    - id: EPIC-001
+      name: "User Authentication & Authorization"
+      stories:
+        - id: STORY-001
+          name: "OAuth2 Social Login Flow"
+          interaction_boundary:
+            service: auth-service
+            api_endpoint: /api/v1/auth/oauth/callback
+            method: POST
+            request_contract:
+              provider: string
+              code: string
+              state: string
+            response_contract:
+              access_token: string
+              refresh_token: string
+            error_states: [400, 401, 500]
+          tasks:
+            - id: TASK-001-001
+              description: "Write contract tests"
+              type: test
+              status: not_started
+            - id: TASK-001-002
+              description: "Implement OAuth callback"
+              type: implementation
+              status: not_started
+  
+  test_suite_status:
+    total_stories: 1
+    tested_stories: 0
+    coverage_percentage: 0
+```
+
+## Specialized Agent Personas
+
+### 1. Test Architect
+
+**Role**: Translate Stories into executable test specifications
+
+**Process**:
+1. User provides Story name
+2. Test Architect asks **max 3 technical questions**:
+   - Which service?
+   - API endpoint?
+   - HTTP method?
+3. Generates:
+   - Interaction boundary definition
+   - Contract test suite (standard flows, errors, edge cases)
+   - Technical acceptance criteria
+   - Linked tasks
+
+**Output**: Executable tests that define the contract
+
+### 2. Edge Case Hunter
+
+**Role**: Systematically identify boundary conditions and failure modes
+
+**Checklist** (6 categories):
+1. **Input Boundaries**: Empty, null, size limits, type boundaries
+2. **Auth/Security**: Missing auth, invalid tokens, permission bypasses
+3. **Concurrency**: Race conditions, resource contention, idempotency
+4. **Data Integrity**: Injection attacks, XSS, path traversal, SSRF
+5. **Resource Exhaustion**: Memory bombs, CPU exhaustion, rate limits
+6. **Network**: Timeouts, partial failures, network splits
+
+**Output**: Additional edge case tests for each Story
+
+## Workflow
+
+### Complete Test-First Cycle
+
+```bash
+# 1. Define capability
+dhurandhar epic add "User Authentication & Authorization"
+
+# 2. Define user journey
+dhurandhar story add "OAuth2 Social Login" --epic EPIC-001
+
+# Test Architect asks 3 questions:
+#   - Service? auth-service
+#   - Endpoint? /api/v1/auth/oauth/callback
+#   - Method? POST
+
+# 3. Generate contract tests
+dhurandhar test --generate
+
+# Output:
+#   ✓ tests/contracts/story-001-standard.test.js
+#   ✓ tests/contracts/story-001-errors.test.js
+#   ✓ tests/edge-cases/story-001-edge.test.js
+
+# 4. Run tests (they will fail - no implementation yet)
+npm test
+
+# Expected: All tests fail (this is correct!)
+
+# 5. Implement service to pass the tests
+# (Implementation guided by test contracts)
+
+# 6. Run tests again
+npm test
+
+# Expected: All tests pass
+
+# 7. Validate coverage
+dhurandhar test --validate
+
+# Output:
+#   Total Stories: 1
+#   Test Coverage: 100%
+#   Implementation: 100%
+```
+
+## Test Generation
+
+### Generated Test Structure
+
+For each Story, 3 test files are generated:
+
+#### 1. Standard Flow Tests
+**File**: `tests/contracts/story-001-standard.test.js`
+
+```javascript
+describe('OAuth2 Social Login - Standard Flows', () => {
+  it('should exchange valid OAuth code for tokens', async () => {
+    const response = await apiClient.post('/api/v1/auth/oauth/callback', {
+      provider: 'google',
+      code: 'valid_code',
+      state: 'valid_state',
+    });
+    
+    expect(response.status).toBe(200);
+    expect(response.data).toHaveProperty('access_token');
+    expect(response.data).toHaveProperty('refresh_token');
+  });
+});
+```
+
+#### 2. Error State Tests
+**File**: `tests/contracts/story-001-errors.test.js`
+
+```javascript
+describe('OAuth2 Social Login - Error States', () => {
+  it('should return 400 for invalid OAuth code', async () => {
+    try {
+      await apiClient.post('/api/v1/auth/oauth/callback', {
+        provider: 'google',
+        code: 'invalid_code',
+        state: 'valid_state',
+      });
+      fail('Should have thrown');
+    } catch (error) {
+      expect(error.response.status).toBe(400);
+    }
+  });
+  
+  it('should return 401 for CSRF mismatch', async () => {
+    // Test state parameter validation
+  });
+});
+```
+
+#### 3. Edge Case Tests
+**File**: `tests/edge-cases/story-001-edge.test.js`
+
+```javascript
+describe('OAuth2 Social Login - Edge Cases', () => {
+  it('should prevent OAuth code reuse', async () => {
+    // Replay attack test
+  });
+  
+  it('should handle concurrent callbacks', async () => {
+    // Race condition test
+  });
+  
+  it('should handle provider timeout', async () => {
+    // Network failure test
+  });
+});
+```
+
+## CLI Commands
+
+### Epic Management
+
+```bash
+# List epics
+dhurandhar epic --list
+
+# Add epic
+dhurandhar epic add "User Authentication & Authorization"
+```
+
+### Story Management
+
+```bash
+# List stories
+dhurandhar story --list
+
+# Add story
+dhurandhar story add "OAuth2 Login" --epic EPIC-001
+
+# Add story interactively
+dhurandhar story add
+```
+
+### Test Operations
+
+```bash
+# Initialize test infrastructure
+dhurandhar test --init
+
+# Generate all tests from Agile Blueprint
+dhurandhar test --generate
+
+# Validate coverage
+dhurandhar test --validate
+
+# Generate edge cases for specific story
+dhurandhar test --edge-cases STORY-001
+```
+
+## Engineering-First Approach
+
+### What We Ask (Technical)
+
+✅ **Good Questions**:
+- "Which service handles this?"
+- "API endpoint path?"
+- "Request/response schema?"
+- "Expected error codes?"
+
+### What We Don't Ask (Business)
+
+❌ **Bad Questions**:
+- "What's the business value?"
+- "Why do you need this feature?"
+- "Have you considered alternatives?"
+- "Who are the stakeholders?"
+
+## Benefits
+
+### 1. Contract-First Development
+
+Tests define the API contract before implementation:
+- Clear expectations
+- No ambiguity
+- Implementation guided by tests
+
+### 2. Zero Cognitive Fatigue
+
+- Max 3 questions per Story
+- No justification loops
+- Direct action
+
+### 3. Complete Coverage Tracking
+
+```bash
+$ dhurandhar test --validate
+
+Coverage Report:
+  Total Stories: 10
+  Test Coverage: 100% (10/10)
+  Implementation: 70% (7/10)
+
+Uncovered Stories:
+  🔴 STORY-008: Password Reset Flow
+    Pending tasks: 2
+  🔴 STORY-009: Email Verification
+    Pending tasks: 3
+```
+
+### 4. Cross-Session Persistence
+
+All Epic/Story/Task data in SDM:
+- Instant context rehydration
+- Definition of Done tracked
+- No rediscovery needed
+
+## Definition of Done
+
+A Story is "Done" when:
+
+1. ✅ Contract tests generated
+2. ✅ Edge case tests generated
+3. ✅ All tests passing
+4. ✅ All tasks marked `complete` in SDM
+
+Check status:
+```bash
+dhurandhar test --validate
+```
+
+## Integration with Engineering-First
+
+Test-First Agile **complements** (not replaces) the engineering-first approach:
+
+| Layer | Focus | Artifacts |
+|-------|-------|-----------|
+| Engineering-First | Services, Entities, Tech Stack | SDM: services, entities |
+| Test-First Agile | User Journeys, API Contracts | SDM: epics, stories, tasks |
+| Both | Implementation | Code that passes tests |
+
+## Example: Complete Flow
+
+See `docs/test-first-example.md` for a complete walkthrough.
+
+---
+
+**Dhurandhar: Engineering-First + Test-First = Zero Cognitive Overhead**

package/docs/architecture.md

@@ -0,0 +1,279 @@
+# Dhurandhar Architecture
+
+This document describes the internal architecture of the Dhurandhar framework.
+
+## Overview
+
+Dhurandhar is built as a modular, YAML-driven framework for system design. It consists of:
+
+1. **CLI Layer**: Command-line interface for user interaction
+2. **Core Libraries**: Business logic and utilities
+3. **Module System**: Pluggable design modules
+4. **Configuration Engine**: YAML-based configuration management
+5. **Validation System**: Schema and rule validation
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    CLI Layer                        │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐         │
+│  │ install  │  │  config  │  │  module  │  ...    │
+│  └──────────┘  └──────────┘  └──────────┘         │
+└─────────────────────┬───────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│                Core Libraries                        │
+│  ┌─────────────────┐  ┌─────────────────┐          │
+│  │ ConfigManager   │  │ ModuleManager   │          │
+│  └─────────────────┘  └─────────────────┘          │
+│  ┌─────────────────┐  ┌─────────────────┐          │
+│  │ FileSystem      │  │ Validators      │          │
+│  └─────────────────┘  └─────────────────┘          │
+└─────────────────────┬───────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│              Module System                           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
+│  │   Core   │  │ Example  │  │  Custom  │          │
+│  └──────────┘  └──────────┘  └──────────┘          │
+└──────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### CLI Layer (`tools/cli/`)
+
+**Purpose**: User interface and command routing
+
+**Components**:
+- `dhurandhar.js`: Main CLI entry point
+- `commands/install.js`: Framework installation
+- `commands/config.js`: Configuration management
+- `commands/module.js`: Module operations
+- `commands/validate.js`: Validation operations
+
+**Technologies**:
+- `commander`: CLI framework
+- `@clack/prompts`: Interactive prompts
+- `chalk`: Terminal styling
+
+### Core Libraries (`tools/lib/`)
+
+#### ConfigManager
+
+**Purpose**: Manages YAML-based configuration
+
+**Key Features**:
+- Load/save configuration files
+- Variable substitution (`{variable}` syntax)
+- Nested value access (dot notation)
+- Configuration validation
+
+**File**: `tools/lib/config-manager.js`
+
+#### ModuleManager
+
+**Purpose**: Module discovery and lifecycle management
+
+**Key Features**:
+- List available modules
+- Install/uninstall modules
+- Dependency resolution
+- Module metadata parsing
+
+**File**: `tools/lib/module-manager.js`
+
+#### FileSystem
+
+**Purpose**: File system operations abstraction
+
+**Key Features**:
+- Directory management
+- File copying
+- Pattern matching (glob)
+- JSON/YAML helpers
+
+**File**: `tools/lib/filesystem.js`
+
+#### Validators
+
+**Purpose**: Configuration and module validation
+
+**Components**:
+- `ConfigValidator`: Validates configuration structure
+- `ModuleValidator`: Validates module definitions
+
+**Files**: `tools/lib/validators/`
+
+### Module System (`src/`)
+
+#### Core Module (`src/core/`)
+
+**Purpose**: Essential framework components
+
+**Contents**:
+- Base templates for design modules
+- Schema definitions
+- Core utilities
+
+#### Design Modules (`src/modules/`)
+
+**Purpose**: Pluggable system designs
+
+**Structure**:
+```
+module-name/
+├── module.yaml       # Module definition
+├── README.md         # Documentation
+├── templates/        # Design templates
+└── utilities/        # Helper scripts
+```
+
+## Data Flow
+
+### Installation Flow
+
+```
+User runs: dhurandhar install
+    ↓
+CLI prompts for configuration
+    ↓
+ConfigManager creates .dhurandhar/config.yaml
+    ↓
+FileSystem creates directory structure
+    ↓
+ModuleInstaller copies selected modules
+    ↓
+Installation complete
+```
+
+### Module Installation Flow
+
+```
+User runs: dhurandhar module --add example
+    ↓
+ModuleManager finds module in src/modules/
+    ↓
+Checks dependencies
+    ↓
+Installs dependencies first (recursive)
+    ↓
+FileSystem copies module to .dhurandhar/modules/
+    ↓
+ConfigManager updates config.yaml
+    ↓
+Module installed
+```
+
+### Validation Flow
+
+```
+User runs: dhurandhar validate
+    ↓
+ConfigValidator checks .dhurandhar/config.yaml
+    ↓
+ModuleValidator checks each installed module
+    ↓
+Returns errors and warnings
+    ↓
+Exit with appropriate status code
+```
+
+## Configuration System
+
+### Configuration File Structure
+
+```yaml
+version: "0.1.0"
+projectName: my-project
+userName: User
+outputFolder: _dhurandhar-output
+modules: [core, example]
+settings:
+  created: "2024-01-01T00:00:00Z"
+  lastModified: "2024-01-01T00:00:00Z"
+variables:
+  projectRoot: /path/to/project
+  configDir: /path/to/project/.dhurandhar
+```
+
+### Variable Substitution
+
+Variables use `{key}` syntax:
+
+```yaml
+output: "{projectRoot}/{outputFolder}/designs"
+# Resolves to: "/path/to/project/_dhurandhar-output/designs"
+```
+
+## Module System
+
+### Module Definition Schema
+
+See `src/core/schemas/design-module-schema.yaml` for complete schema.
+
+Key fields:
+- **code**: Unique identifier
+- **name**: Display name
+- **version**: Semantic version
+- **dependencies**: Required modules
+- **design_components**: System components
+- **relationships**: Component connections
+- **build_processes**: Workflows
+
+### Dependency Resolution
+
+Modules can depend on other modules. Dependencies are:
+1. Declared in `module.yaml`
+2. Automatically installed when parent is installed
+3. Validated before uninstallation
+4. Recursively resolved
+
+## Extension Points
+
+Dhurandhar is designed to be extended:
+
+1. **Custom Modules**: Create new design modules
+2. **Custom Validators**: Add validation rules
+3. **Custom Commands**: Extend CLI
+4. **Custom Templates**: Add design templates
+5. **Custom Utilities**: Add helper scripts
+
+## File Structure
+
+```
+.dhurandhar/              # Framework installation
+├── config.yaml           # Project configuration
+├── modules/              # Installed modules
+│   ├── core/
+│   └── example/
+└── cache/                # Cache directory
+
+_dhurandhar-output/       # Generated outputs
+└── designs/              # Design artifacts
+```
+
+## Design Philosophy
+
+Inspired by Bmad-Method, Dhurandhar adopts:
+
+1. **Skills-based Architecture** → Module System
+2. **YAML Configuration** → Design Definitions
+3. **CLI Installer** → Framework Setup
+4. **Validation Framework** → Quality Assurance
+5. **Modular Structure** → Extensibility
+
+## Technology Stack
+
+- **Runtime**: Node.js 20+
+- **CLI**: Commander, Clack
+- **Configuration**: js-yaml, yaml
+- **File System**: fs-extra, glob
+- **Utilities**: chalk, picocolors
+
+## Next Steps
+
+- [Getting Started](getting-started.md)
+- [Module Development](module-development.md)
+- [CLI Reference](cli-reference.md)