@canivel/ralph 0.2.0

package/diagram.svg

@@ -0,0 +1,55 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 520" role="img" aria-label="Ralph architecture diagram">
+  <style>
+    .bg { fill: #0f1218; }
+    .box { fill: #141a23; stroke: #e6e6e6; stroke-width: 1.5; }
+    .line { stroke: #e6e6e6; stroke-width: 1.5; }
+    .text { fill: #f3f3f3; font-family: Menlo, Consolas, Monaco, monospace; font-size: 16px; }
+    .small { font-size: 13px; opacity: 0.9; }
+    .muted { opacity: 0.7; }
+  </style>
+
+  <rect class="bg" x="0" y="0" width="1000" height="520" rx="0" />
+
+  <!-- Top boxes -->
+  <rect class="box" x="390" y="30" width="220" height="44" rx="0" />
+  <text class="text" x="500" y="58" text-anchor="middle">ralph CLI</text>
+
+  <rect class="box" x="240" y="114" width="520" height="48" rx="0" />
+  <text class="text small muted" x="500" y="144" text-anchor="middle">agent CLI: codex | claude | droid</text>
+
+  <!-- Arrow from top to agent (gap matches lower arrows) -->
+  <line class="line" x1="500" y1="74" x2="500" y2="96" />
+  <polygon points="496,96 500,104 504,96" fill="#e6e6e6" />
+
+  <!-- Branch lines (gap for heads) -->
+  <line class="line" x1="500" y1="162" x2="500" y2="200" />
+  <line class="line" x1="500" y1="200" x2="280" y2="200" />
+  <line class="line" x1="500" y1="200" x2="720" y2="200" />
+  <line class="line" x1="280" y1="200" x2="280" y2="214" />
+  <line class="line" x1="720" y1="200" x2="720" y2="214" />
+  <polygon points="276,214 280,222 284,214" fill="#e6e6e6" />
+  <polygon points="716,214 720,222 724,214" fill="#e6e6e6" />
+
+  <!-- Bottom boxes -->
+  <rect class="box" x="90" y="226" width="380" height="230" rx="0" />
+  <text class="text" x="110" y="256">.agents/ralph/</text>
+  <text class="text small muted" x="110" y="278">local overrides (optional)</text>
+  <text class="text small" x="110" y="306">loop.sh</text>
+  <text class="text small" x="110" y="328">PROMPT_build.md</text>
+  <text class="text small" x="110" y="350">references/</text>
+  <text class="text small" x="110" y="372">log-activity.sh</text>
+  <text class="text small" x="110" y="394">config.sh (optional)</text>
+
+  <rect class="box" x="530" y="226" width="380" height="230" rx="0" />
+  <text class="text" x="550" y="256">.ralph/</text>
+  <text class="text small muted" x="550" y="278">state + logs</text>
+  <text class="text small" x="550" y="306">errors.log</text>
+  <text class="text small" x="550" y="328">progress.md</text>
+  <text class="text small" x="550" y="350">guardrails.md</text>
+  <text class="text small" x="550" y="372">activity.log</text>
+  <text class="text small" x="550" y="394">runs/</text>
+
+  <text class="text small muted" x="500" y="500" text-anchor="middle">
+    Local templates override bundled defaults. State persists between runs.
+  </text>
+</svg>

package/examples/commands.md

@@ -0,0 +1,46 @@
+# Ralph CLI Examples
+
+Basic usage:
+
+```bash
+ralph prd "A lightweight uptime monitor (Hono app), deployed on Cloudflare, with email alerts via AWS SES"
+ralph build 1 # one Ralph run
+ralph build 1 --no-commit # one Ralph run
+ralph overview
+```
+
+Agent override:
+
+```bash
+ralph ping --agent=codex # check agent is installed + responsive
+ralph build 1 --agent=codex # one Ralph run
+ralph build 1 --agent=claude # one Ralph run
+ralph build 1 --agent=droid # one Ralph run
+```
+
+PRD overrides:
+
+```bash
+ralph prd "..." --out .agents/tasks/prd-api.json
+ralph build 1 --prd .agents/tasks/prd-api.json # one Ralph run
+ralph overview --prd .agents/tasks/prd-api.json
+```
+
+Progress override:
+
+```bash
+ralph build 1 --progress .ralph/progress-api.md # one Ralph run
+```
+
+Install templates:
+
+```bash
+ralph install
+ralph install --force
+```
+
+Install skills:
+
+```bash
+ralph install --skills
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@canivel/ralph",
+  "version": "0.2.0",
+  "description": "Minimal, file-based agent loop for autonomous coding. Fork with improved Claude support and first-run configuration.",
+  "bin": {
+    "ralph": "bin/ralph"
+  },
+  "scripts": {
+    "test": "node tests/cli-smoke.mjs && node tests/agent-loops.mjs",
+    "test:real": "node tests/real-agents.mjs",
+    "test:ping": "node tests/agent-ping.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/canivel/ralph.git"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "coding",
+    "autonomous",
+    "claude",
+    "codex",
+    "prd",
+    "cli"
+  ],
+  "author": "Danilo Canivel",
+  "bugs": {
+    "url": "https://github.com/canivel/ralph/issues"
+  },
+  "homepage": "https://github.com/canivel/ralph#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/commit/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: commit
+description: Write conventional commit messages with type, scope, and subject when the user wants to commit changes or save work.
+---
+
+# Git Commit
+
+Creates git commits following Conventional Commits format with proper type, scope, and subject.
+
+## Quick Start
+
+```bash
+# 1. Stage changes
+git add <files>  # or: git add -A
+
+# 2. Create commit (branch commit format)
+git commit -m "type(scope): subject
+
+Body explaining HOW and WHY.
+Reference: Task X.Y, Req N"
+```
+
+## Commit Types
+
+### Regular Branch Commits (During Development)
+
+**Format**: `type(scope): subject`
+
+| Type | Purpose |
+|------|---------|
+| `feat` | New feature or functionality |
+| `fix` | Bug fix or issue resolution |
+| `refactor` | Code refactoring without behavior change |
+| `perf` | Performance improvements |
+| `test` | Test additions or modifications |
+| `ci` | CI/CD configuration changes |
+| `docs` | Documentation updates |
+| `chore` | Maintenance, dependencies, tooling |
+| `style` | Code formatting, linting (non-functional) |
+| `security` | Security vulnerability fixes or hardening |
+
+### Scope (Required, kebab-case)
+
+Examples: `validation`, `auth`, `cookie-service`, `template`, `config`, `tests`, `api`
+
+### Subject Line Rules
+
+- Max 50 characters after colon
+- Present tense imperative: add, implement, fix, improve, enhance, refactor, remove, prevent
+- NO period at the end
+- Specific and descriptive - state WHAT, not WHY
+
+## Core Workflow
+
+### 1. Review Changes
+
+```bash
+git status
+git diff --staged  # if already staged
+git diff           # if not staged
+```
+
+### 2. Stage Files
+
+```bash
+git add <specific-files>  # preferred
+# or
+git add -A  # all changes
+```
+
+**NEVER commit**:
+- `.env`, `credentials.json`, secrets
+- `node_modules/`, `__pycache__/`, `.venv/`
+- Large binary files without explicit approval
+
+### 3. Create Commit
+
+**Simple change**:
+```bash
+git commit -m "fix(auth): use hmac.compare_digest for secure comparison"
+```
+
+**Complex change (with body)**:
+```bash
+git commit -m "$(cat <<'EOF'
+feat(validation): add URLValidator with domain whitelist
+
+Implement URLValidator class supporting:
+- Domain whitelist enforcement (youtube.com, youtu.be)
+- Dangerous scheme blocking (javascript, data, file)
+- URL parsing with embedded credentials handling
+
+Addresses Requirement 31: Input validation
+Part of Task 5.1: Input Validation Utilities
+EOF
+)"
+```
+
+### 4. Verify Commit
+
+```bash
+git log -1 --format="%h %s"
+git show --stat HEAD
+```
+
+## Body Format (Recommended for Complex Changes)
+
+```
+<blank line>
+Explain HOW and WHY the change was made.
+- Use bullet points for multiple items
+- Wrap at 72 characters
+
+Reference: Task X.Y
+Addresses: Req N
+```
+
+## Git Trailers
+
+| Trailer | Purpose |
+|---------|---------|
+| `Fixes #N` | Links and closes issue on merge |
+| `Closes #N` | Same as Fixes |
+| `Co-authored-by: Name <email>` | Credit co-contributors |
+
+Place trailers at end of body after blank line. See `references/commit_examples.md` for examples.
+
+## Breaking Changes
+
+For incompatible API/behavior changes, use `!` after scope OR `BREAKING CHANGE:` footer:
+
+```
+feat(api)!: change response format to JSON:API
+
+BREAKING CHANGE: Response envelope changed from `{ data }` to `{ data: { type, id, attributes } }`.
+```
+
+Triggers major version bump in semantic-release.
+
+## Merge Commits (PR Closure)
+
+For PRs, use extended description with sections:
+
+```bash
+gh pr create --title "feat(security): implement input validation (Task 5)" --body "$(cat <<'EOF'
+## Summary
+- Input validation utilities (URLValidator, FormatValidator)
+- Secure template processor with path traversal prevention
+- API key authentication middleware
+
+## Task Breakdown
+Task 5.1: Input Validation - URLValidator, FormatValidator
+Task 5.2: Template Processing - Path traversal prevention
+Task 5.3: API Key Auth - Multi-key support, excluded paths
+Task 5.4: Security Tests - 102 path traversal tests
+
+## Requirements Covered
+Req 7, Req 9, Req 31, Req 33
+
+## Test Coverage
+- All 473 tests passing
+- Coverage: 93%
+- Pre-commit checks: passing
+EOF
+)"
+```
+
+## Integration with Other Skills
+
+### From github-pr-review
+
+When fixing review comments, use this format:
+
+```bash
+git commit -m "fix(scope): address review comment #ID
+
+Brief explanation of what was wrong and how it's fixed.
+Addresses review comment #123456789."
+```
+
+### From github-pr-creation
+
+Before creating PR, ensure all commits follow this format. The PR skill will:
+1. Analyze commits for proper format
+2. Extract types for PR labels
+3. Build PR description from commit bodies
+
+## Important Rules
+
+- **ALWAYS** include scope in parentheses
+- **ALWAYS** use present tense imperative verb
+- **NEVER** end subject with period
+- **NEVER** commit secrets or credentials
+- **NEVER** use generic messages ("update code", "fix bug", "changes")
+- **NEVER** exceed 50 chars in subject line
+- Group related changes -> single focused commit
+
+## Examples
+
+**Good**:
+```
+feat(validation): add URLValidator with domain whitelist
+fix(auth): use hmac.compare_digest for secure key comparison
+refactor(template): consolidate filename sanitization logic
+test(security): add 102 path traversal prevention tests
+```
+
+**Bad**:
+```
+update validation code           # no type, no scope, vague
+feat: add stuff                  # missing scope, too vague
+fix(auth): fix bug               # circular, not specific
+chore: make changes              # missing scope, vague
+feat(security): improve things.  # has period, vague
+```
+
+## References
+
+- `references/commit_examples.md` - Extended examples by type

package/skills/commit/references/commit_examples.md

@@ -0,0 +1,292 @@
+# Commit Examples by Type
+
+Extended examples for each commit type with body content.
+
+## feat - New Features
+
+```
+feat(validation): add URLValidator with domain whitelist
+
+Implement URLValidator class supporting:
+- Domain whitelist enforcement (youtube.com, youtu.be, m.youtube.com)
+- Dangerous scheme blocking (javascript, data, file)
+- URL parsing with embedded credentials handling
+- Port number validation (1-65535)
+
+Addresses Requirement 31: Input validation
+Part of Task 5.1: Input Validation Utilities
+```
+
+```
+feat(api): add video metadata endpoint
+
+New GET /api/v1/videos/{id}/metadata endpoint:
+- Returns title, duration, formats, thumbnails
+- Supports format filtering via query params
+- Implements caching with 5-minute TTL
+
+Part of Task 6.2: API Endpoints
+```
+
+## fix - Bug Fixes
+
+```
+fix(auth): use hmac.compare_digest for secure key comparison
+
+Replace direct string equality with hmac.compare_digest to prevent
+timing attacks on API key validation. Ensures constant-time comparison
+regardless of key length or content.
+
+Addresses security best practice for sensitive data comparison
+```
+
+```
+fix(download): handle network timeout during video fetch
+
+Add retry logic with exponential backoff for network failures:
+- Max 3 attempts with delays [2, 4, 8] seconds
+- Classify retriable errors (5xx, timeout, connection)
+- Log each retry attempt with remaining count
+
+Fixes issue where downloads would fail silently on flaky connections
+```
+
+## refactor - Code Improvements
+
+```
+refactor(template): consolidate filename sanitization logic
+
+Extract common sanitization patterns into helper methods:
+- Path traversal prevention (.., /, absolute paths)
+- Special character removal (control chars, null bytes)
+- Windows reserved name handling (CON, PRN, LPT1-9, etc)
+
+Improves code maintainability and reduces duplication
+```
+
+```
+refactor(providers): extract common yt-dlp options builder
+
+Move duplicated option building from get_info/download to
+_build_base_options helper. Reduces code duplication and ensures
+consistent option handling across all provider methods.
+
+No behavior change, pure refactoring
+```
+
+## test - Test Changes
+
+```
+test(security): add 102 path traversal prevention tests
+
+Comprehensive test coverage for TemplateProcessor including:
+- Basic path traversal attempts (.., /)
+- URL-encoded variants (%2e%2e, %2f)
+- Unicode/UTF-8 bypass attempts
+- Windows edge cases (backslashes, drive letters)
+
+Part of Task 5.4: Security Test Suite
+```
+
+```
+test(validation): add parametrized URL validation tests
+
+Add 25 test cases covering:
+- Valid YouTube URL formats (watch, shorts, embed, youtu.be)
+- Invalid domains (vimeo, dailymotion)
+- Malformed URLs (no scheme, wrong port)
+- Edge cases (trailing slashes, query params)
+
+Coverage for URLValidator: 98%
+```
+
+## perf - Performance
+
+```
+perf(cache): implement LRU eviction for metadata cache
+
+Replace dict-based cache with LRU implementation:
+- Max 1000 entries with automatic eviction
+- 40% memory reduction under high load
+- Sub-millisecond lookup times maintained
+
+Addresses memory growth issue in long-running instances
+```
+
+## security - Security Fixes
+
+```
+security(cookie): validate cookie file integrity before use
+
+Add SHA256 checksum verification for cookie files:
+- Compute hash on first load, store in memory
+- Verify hash before each use
+- Reject modified files with clear error message
+
+Prevents use of tampered cookie files
+Addresses Requirement 33: Security validation
+```
+
+## ci - CI/CD Changes
+
+```
+ci(github): add security scanning to PR workflow
+
+Enable Bandit security scanner in GitHub Actions:
+- Run on all Python files
+- Fail on HIGH/CRITICAL findings
+- Cache virtualenv for faster runs
+
+Part of Task 15.3: Basic security validation
+```
+
+## docs - Documentation
+
+```
+docs(api): add OpenAPI description for download endpoint
+
+Document /api/v1/download endpoint:
+- Request body schema with format options
+- Response codes (200, 400, 401, 404, 500)
+- Example requests and responses
+
+Improves API documentation for consumers
+```
+
+## chore - Maintenance
+
+```
+chore(deps): update yt-dlp to 2024.12.06
+
+Update yt-dlp from 2024.11.15 to 2024.12.06:
+- Fixes YouTube throttling detection
+- Adds support for new Instagram format
+- Improves error messages for geo-blocked content
+
+No breaking changes expected
+```
+
+## style - Formatting
+
+```
+style(providers): apply black formatting to youtube.py
+
+Apply black formatter with 88 char line length.
+No functional changes, formatting only.
+```
+
+## Merge Commit Examples
+
+### Feature Branch to Develop
+
+```
+Merge pull request #5 from fvadicamo/feature/input-validation-security
+
+feat(security): implement input validation and security (Task 5)
+
+Merges comprehensive security implementation (Task 5) into develop:
+- Input validation utilities (URLValidator, FormatValidator, ParameterValidator)
+- Secure template processor with path traversal prevention
+- API key authentication middleware with multi-key support
+- 473 tests with 93% coverage
+
+Task 5.1: Input Validation Utilities
+- URLValidator: Domain whitelist (youtube.com, youtu.be), dangerous scheme blocking
+- FormatValidator: yt-dlp format ID validation with regex and selectors
+- ParameterValidator: Audio quality/format and language code validation
+
+Task 5.2: Template Processor
+- Path traversal prevention (.., /, absolute paths, URL encoding)
+- Filename sanitization (illegal chars, control chars, null bytes)
+- Windows reserved names handling (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
+- Collision handling with numeric suffix, max length 200 chars
+
+Task 5.3: API Key Authentication
+- APIKeyAuth class with multi-key support
+- Excluded paths for health/doc endpoints
+- Secure hashing for logging (SHA256 first 8 chars)
+- FastAPI dependency injection integration
+
+Task 5.4: Security Tests
+- 102 path traversal prevention tests with edge cases
+- URL validation tests with malicious inputs
+- API key authentication and credential tests
+- Sensitive data redaction verification
+
+Requirements Covered:
+- Req 7: Output template processing with security
+- Req 9: API key authentication
+- Req 31: Input validation
+- Req 33: Security (secure comparison, log redaction)
+
+Test Coverage:
+- All 473 tests passing
+- Coverage: 93% (exceeds 80% minimum)
+- Pre-commit checks: all passing
+```
+
+### Develop to Main (Release)
+
+```
+Merge pull request #10 from fvadicamo/develop
+
+release: v0.1.0 - MVP with YouTube provider
+
+First stable release with core functionality:
+- YouTube video info, formats, download, audio extraction
+- Cookie-based authentication for age-restricted content
+- API key authentication
+- Input validation and security hardening
+- 500+ tests with 92% coverage
+
+Breaking Changes: None (initial release)
+
+Features:
+- GET /api/v1/info - Video metadata
+- GET /api/v1/formats - Available formats
+- POST /api/v1/download - Video/audio download
+- Cookie file support for authenticated requests
+
+Documentation:
+- API documentation at /docs (Swagger UI)
+- OpenAPI spec at /openapi.json
+```
+
+## Commits with Trailers
+
+### Single Issue
+```
+fix(validation): prevent XSS in user input
+
+Escape HTML entities before rendering.
+
+Fixes #78
+```
+
+### Multiple Issues + Co-author
+```
+fix(auth): resolve session and token issues
+
+- Fix session expiry not triggering logout
+- Fix token refresh race condition
+
+Fixes #101
+Fixes #103
+Co-authored-by: Bob <bob@example.com>
+```
+
+## Breaking Changes
+
+### With ! Notation
+```
+feat(api)!: migrate to v2 endpoints
+
+BREAKING CHANGE: /api/v1/* endpoints removed. Update base URL to /api/v2/.
+```
+
+### Config Breaking Change
+```
+chore(config)!: rename environment variables
+
+BREAKING CHANGE: DATABASE_URL -> APP_DATABASE_URL, API_KEY -> APP_API_KEY
+```