Skip to content

Commit d34e1f0

Browse files
darkzOGxdarkzOGx
committed
Initial commit with publishing workflow
0 parents  commit d34e1f0

61 files changed

Lines changed: 16893 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/publish.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
pypi-publish:
12+
name: Upload release to PyPI
13+
runs-on: ubuntu-latest
14+
environment:
15+
name: pypi
16+
url: https://pypi.org/p/darkzloop
17+
permissions:
18+
id-token: write
19+
steps:
20+
- uses: actions/checkout@v4
21+
- name: Set up Python
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: "3.x"
25+
- name: Install build dependencies
26+
run: pip install build
27+
- name: Build package
28+
run: python -m build
29+
- name: Publish package distributions to PyPI
30+
uses: pypa/gh-action-pypi-publish@release/v1

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
2+
# Valid .gitignore for Windows/Python
3+
nul
4+
__pycache__/
5+
*.pyc
6+
.env
7+
.venv
8+
.pytest_cache/
9+
dist/
10+
build/
11+
*.egg-info/

‎CHANGELOG.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Changelog
2+
3+
All notable changes to Darkzloop will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.6.0] - 2026-01-13
9+
10+
### 🎉 Initial Public Release
11+
12+
**Darkzloop is now model-agnostic!** Use your existing Claude, Copilot, or Ollama subscriptions.
13+
14+
### Added
15+
16+
#### Core Engine
17+
- **Finite State Machine (FSM)** - 7-state machine with strict transitions
18+
- States: IDLE → PLANNING → EXECUTING → TESTING → REMEDIATING → BLOCKED → DONE
19+
- Per-task retry tracking (circuit breaker per task)
20+
- Global consecutive failure tracking
21+
- Max iterations limit (default: 100)
22+
23+
- **Manifest Protocol** - Read-before-write enforcement
24+
- Files must be read before they can be modified
25+
- Context window tracking (re-read required if file pruned)
26+
- Sensitive file prompts (config/secrets protection)
27+
- Full access audit trail
28+
29+
- **Tiered Quality Gates**
30+
- Tier 1: Must-pass (cargo check, cargo test)
31+
- Tier 2: Should-pass with auto-fix (cargo clippy → cargo fmt)
32+
- Tier 3: Optional (cargo audit)
33+
34+
- **Semantic Expansion**
35+
- 50+ built-in synonym clusters
36+
- Project-specific learning glossary
37+
- Codebase term scanning
38+
- No external API calls (100% local)
39+
40+
#### CLI Interface
41+
- `darkzloop init` - Auto-detect stack (Rust/Python/Node/Go)
42+
- `darkzloop plan` - Generate execution plan with semantic expansion
43+
- `darkzloop run` - Execute with FSM control and safety checks
44+
- `darkzloop fix "..."` - One-shot fixes without manual spec
45+
- `darkzloop status` - Show current loop state
46+
- `darkzloop graph` - Visualize task DAG (ASCII/HTML/Mermaid)
47+
- `darkzloop config native <tool>` - Configure BYOA mode
48+
- `darkzloop config api <provider>` - Configure direct API
49+
- `darkzloop doctor` - Environment diagnostics
50+
51+
#### BYOA (Bring Your Own Auth)
52+
- **Shell Executor** - Pipe prompts to native CLI tools
53+
- Claude CLI (`claude --print`)
54+
- GitHub Copilot (`gh copilot suggest`)
55+
- Ollama (`ollama run llama3.1`)
56+
- llm CLI (`llm -m claude-3-sonnet`)
57+
- Aider (`aider --message`)
58+
- Any custom command
59+
60+
- **12 Native Tool Presets**
61+
- `claude`, `claude-json`
62+
- `gh-copilot`
63+
- `ollama`, `ollama-codellama`, `ollama-deepseek`
64+
- `llm`, `llm-gpt4`, `llm-gemini`
65+
- `aider`
66+
- `openai`, `anthropic`
67+
68+
- **4-Strategy JSON Extraction** - Handle chatty CLI output
69+
- Markdown JSON blocks
70+
- Generic code blocks
71+
- Balanced brace matching
72+
- Greedy extraction (last resort)
73+
74+
#### Safety Features
75+
- Git clean check before execution
76+
- Automatic backup branches (`darkzloop-backup-YYYYMMDD-HHMMSS`)
77+
- Dry run mode (`--dry-run`)
78+
- Attended mode (approval at each step)
79+
80+
### Technical Details
81+
- Python 3.10+ required
82+
- ~4,500 lines across 22 modules
83+
- Zero required API keys (BYOA mode)
84+
- MIT licensed
85+
86+
---
87+
88+
## Philosophy
89+
90+
> *"The goal is not to build a smarter agent. It's to build a more disciplined one."*
91+
92+
Darkzloop implements the **Ralph Loop** methodology:
93+
1. **Spec** - Define what you want (the "Pin")
94+
2. **Plan** - Break into tasks with dependencies (DAG)
95+
3. **Execute** - Agent works within strict boundaries
96+
4. **Verify** - Tests must pass before accepting changes
97+
5. **Learn** - Build project-specific vocabulary over time
98+
99+
The agent is powerful. The **system** keeps it honest.

‎CONTRIBUTING.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Contributing to darkzloop
2+
3+
Thanks for your interest in contributing! This project benefits from community input on patterns, integrations, and tooling.
4+
5+
## Ways to Contribute
6+
7+
### 1. Language/Stack Configurations
8+
9+
Add detection and default commands for new languages in `bin/darkzloop`:
10+
11+
```python
12+
# In detect_project_type()
13+
elif (project_dir / "build.gradle").exists():
14+
config.update({
15+
"language": "kotlin",
16+
"test": "./gradlew test",
17+
"format_check": "./gradlew ktlintCheck",
18+
"lint": "./gradlew detekt",
19+
})
20+
```
21+
22+
### 2. Integration Guides
23+
24+
Add guides for new coding agents in `integrations/`:
25+
26+
- Follow the existing format (setup, running iterations, tips)
27+
- Include both attended and unattended examples
28+
- Add troubleshooting section
29+
30+
### 3. Example Specs and Plans
31+
32+
Add examples in `examples/` showing:
33+
34+
- Different languages/frameworks
35+
- Various feature types (API, UI, CLI, library)
36+
- Real-world complexity with strong linkage
37+
38+
### 4. Documentation Improvements
39+
40+
Improve docs in `docs/`:
41+
42+
- Clarify confusing sections
43+
- Add diagrams or flowcharts
44+
- More examples of patterns and anti-patterns
45+
46+
### 5. CLI Improvements
47+
48+
Enhance `bin/darkzloop`:
49+
50+
- Better error messages
51+
- New validation checks
52+
- Integration with specific agents
53+
54+
## Development Setup
55+
56+
```bash
57+
git clone https://github.com/yourusername/darkzloop.git
58+
cd darkzloop
59+
60+
# Make CLI executable
61+
chmod +x bin/darkzloop
62+
63+
# Add to PATH for testing
64+
export PATH="$PATH:$(pwd)/bin"
65+
66+
# Test it works
67+
darkzloop --help
68+
```
69+
70+
## Pull Request Process
71+
72+
1. **Fork and branch**: Create a feature branch from `main`
73+
74+
2. **Make changes**: Keep commits focused and atomic
75+
76+
3. **Test**: Verify `darkzloop` commands work
77+
```bash
78+
cd /tmp && mkdir test-project && cd test-project
79+
darkzloop init
80+
darkzloop validate
81+
```
82+
83+
4. **Document**: Update relevant docs/README if needed
84+
85+
5. **Submit PR**: Describe what you changed and why
86+
87+
## Code Style
88+
89+
- Python: Follow PEP 8, use type hints
90+
- Markdown: Use ATX headers (`#`), include blank lines around lists
91+
- Shell: Use `shellcheck` to validate scripts
92+
93+
## Commit Messages
94+
95+
Follow conventional commits:
96+
97+
```
98+
feat(cli): add Java/Gradle detection
99+
fix(docs): correct line numbers in Rust example
100+
docs(integration): add Continue.dev guide
101+
```
102+
103+
## Questions?
104+
105+
Open an issue for:
106+
107+
- Feature proposals
108+
- Questions about the methodology
109+
- Help with integration
110+
111+
## License
112+
113+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 darkzloop contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# ============================================================================
2+
# Darkzloop Makefile
3+
# ============================================================================
4+
5+
.PHONY: install dev test lint format build publish clean demo help
6+
7+
# Default Python
8+
PYTHON := python3
9+
10+
# ============================================================================
11+
# Development
12+
# ============================================================================
13+
14+
install: ## Install package in editable mode
15+
$(PYTHON) -m pip install -e .
16+
17+
dev: ## Install with dev dependencies
18+
$(PYTHON) -m pip install -e ".[dev]"
19+
20+
all: ## Install with all optional dependencies
21+
$(PYTHON) -m pip install -e ".[all,dev]"
22+
23+
# ============================================================================
24+
# Quality
25+
# ============================================================================
26+
27+
test: ## Run tests
28+
pytest tests/ -v
29+
30+
lint: ## Run linters
31+
ruff check darkzloop/
32+
mypy darkzloop/
33+
34+
format: ## Format code
35+
black darkzloop/
36+
ruff check darkzloop/ --fix
37+
38+
# ============================================================================
39+
# Build & Publish
40+
# ============================================================================
41+
42+
build: clean ## Build distribution packages
43+
$(PYTHON) -m pip install build
44+
$(PYTHON) -m build
45+
46+
publish: build ## Publish to PyPI
47+
$(PYTHON) -m pip install twine
48+
twine upload dist/*
49+
50+
publish-test: build ## Publish to TestPyPI
51+
$(PYTHON) -m pip install twine
52+
twine upload --repository testpypi dist/*
53+
54+
# ============================================================================
55+
# Verification
56+
# ============================================================================
57+
58+
verify: ## Run install verification script
59+
./test_install.sh
60+
61+
doctor: ## Run darkzloop doctor
62+
darkzloop doctor
63+
64+
# ============================================================================
65+
# Demo
66+
# ============================================================================
67+
68+
demo: ## Generate demo GIF (requires vhs)
69+
@command -v vhs >/dev/null 2>&1 || { echo "Install vhs: https://github.com/charmbracelet/vhs"; exit 1; }
70+
vhs demo.tape
71+
72+
# ============================================================================
73+
# Cleanup
74+
# ============================================================================
75+
76+
clean: ## Clean build artifacts
77+
rm -rf build/
78+
rm -rf dist/
79+
rm -rf *.egg-info/
80+
rm -rf .pytest_cache/
81+
rm -rf .mypy_cache/
82+
rm -rf .ruff_cache/
83+
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
84+
find . -type f -name "*.pyc" -delete 2>/dev/null || true
85+
86+
# ============================================================================
87+
# Help
88+
# ============================================================================
89+
90+
help: ## Show this help
91+
@echo "Darkzloop Development Commands"
92+
@echo ""
93+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'

0 commit comments

Comments
 (0)