From 4c23417b8f7baba8a1f9cfe8b720db09e846e193 Mon Sep 17 00:00:00 2001 From: Amanbig Date: Sat, 31 Oct 2026 15:46:07 +0530 Subject: [PATCH] docs: add open-source project files and drop the outdated screenshots Add CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, issue forms, a pull request template and a dependabot config. Remove the README screenshots section (they show the pre-redesign UI), point the Contributing section at the new guide, and tick the roadmap items that have shipped. --- .github/ISSUE_TEMPLATE/bug_report.yml | 60 ++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 25 +++++++ .github/PULL_REQUEST_TEMPLATE.md | 18 +++++ .github/dependabot.yml | 11 +++ CODE_OF_CONDUCT.md | 32 +++++++++ CONTRIBUTING.md | 80 ++++++++++++++++++++++ README.md | 40 +++-------- SECURITY.md | 34 +++++++++ 9 files changed, 275 insertions(+), 30 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/dependabot.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..27d95c8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,60 @@ +name: Bug report +description: Something is broken or behaves unexpectedly +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting! **Remove API keys and other secrets** from anything you paste. + For security problems, do not open an issue: see SECURITY.md. + - type: textarea + id: what-happened + attributes: + label: What happened? + description: What did you do, what did you expect, and what happened instead? + validations: + required: true + - type: textarea + id: repro + attributes: + label: Steps to reproduce + placeholder: | + 1. Run `devorch -p openai` + 2. Type ... + 3. See ... + validations: + required: true + - type: input + id: version + attributes: + label: DevOrch version + description: Output of `devorch --version` (or `pip show devorch`) + validations: + required: true + - type: input + id: provider + attributes: + label: Provider and model + placeholder: openai / gpt-4o + - type: dropdown + id: os + attributes: + label: Operating system + options: [Linux, macOS, Windows, Other] + validations: + required: true + - type: input + id: python + attributes: + label: Python version + placeholder: "3.12" + - type: input + id: terminal + attributes: + label: Terminal + description: For display or input problems (e.g. iTerm2, Windows Terminal, GNOME Terminal, tmux) + - type: textarea + id: logs + attributes: + label: Output / logs + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..4197dde --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Report a security vulnerability + url: https://github.com/Amanbig/DevOrch/security/advisories/new + about: Please report security issues privately, not as a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..17bd407 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,25 @@ +name: Feature request +description: Suggest an idea or improvement +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: What problem would this solve? + description: Describe the use case, not just the solution. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + - type: textarea + id: alternatives + attributes: + label: Alternatives you considered + - type: checkboxes + id: contribute + attributes: + label: Contribution + options: + - label: I'd be willing to open a pull request for this diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..16352e0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,18 @@ +## Summary + + + +## Changes + +- + +## How it was tested + + + +## Checklist + +- [ ] `ruff check .` and `ruff format --check .` pass +- [ ] `pytest` passes, with tests for new behaviour (a bug fix has a test that fails without it) +- [ ] README / `CHANGELOG.md` updated for user-facing changes +- [ ] No secrets, personal paths or API keys in code, tests, or logs diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..9fce184 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "monthly" + open-pull-requests-limit: 5 + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..85d0dae --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,32 @@ +# Code of Conduct + +We want DevOrch to be a friendly, welcoming project for everyone, whatever their background or experience. + +## Our standards + +Expected: + +- Be respectful and patient, especially with people who are new. +- Give and accept constructive feedback; critique the work, not the person. +- Assume good faith, and ask when something is unclear. +- Keep discussion on topic and credit other people's work. + +Not acceptable: + +- Harassment, insults, personal attacks, or discriminatory language or jokes. +- Trolling, deliberately derailing threads, or spamming. +- Publishing someone else's private information. +- Any other conduct that would reasonably be considered inappropriate in a professional setting. + +## Scope + +This applies in all project spaces (issues, pull requests, discussions, commits) and when someone is +representing the project in public. + +## Enforcement + +Maintainers may edit or remove comments, close or lock threads, and ban people who do not follow these +standards. To report a problem privately, contact the maintainer at the address listed in the `authors` +field of `pyproject.toml`. Reports are treated confidentially. + +This policy is inspired by the [Contributor Covenant](https://www.contributor-covenant.org). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9128058 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# Contributing to DevOrch + +Thanks for helping out! DevOrch is a multi-provider AI coding assistant CLI, and contributions of all sizes +are welcome: bug reports, docs, tests, new providers, tools and features. + +By participating you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). To report a security problem, +see [SECURITY.md](SECURITY.md) instead of opening a public issue. + +## Getting set up + +```bash +git clone https://github.com/Amanbig/DevOrch.git +cd DevOrch +python -m venv .venv && source .venv/bin/activate # or: uv venv && source .venv/bin/activate +pip install -e ".[dev]" # or: uv pip install -e ".[dev]" + +pytest # the whole suite; no network or API keys needed +ruff check . # lint +ruff format . # format (CI runs `ruff format --check .`) +devorch # run your working copy +``` + +Python 3.10+ is required; CI runs the tests on Linux, macOS and Windows for 3.10-3.13, so avoid +platform-specific assumptions (paths, shells, terminal behaviour) and keep type hints 3.10-compatible. + +## Workflow + +1. Open an issue first for anything large, so we can agree on the approach. +2. Create a branch per change (`feat/...`, `fix/...`, `docs/...`, `chore/...`). +3. Keep PRs focused: one feature or fix per PR. +4. Use clear, conventional-style commit messages (`feat(hooks): ...`, `fix(ui): ...`). +5. Open a PR against `main`. CI must pass (lint + tests on all platforms). + +A good PR includes: + +- **Tests** for new behaviour and for the bug it fixes. A regression test should fail without your fix. +- **Docs**: update the README for user-facing changes and add a line to `CHANGELOG.md`. +- An honest description: what changed, why, what you did **not** test. + +## Where things live + +See [`DEVORCH.md`](DEVORCH.md) and the project structure in the README. In short: `cli/` (commands, REPL, UI), +`core/` (agent loop, executor, hooks, memory, sessions), `providers/` (one file per LLM provider), `tools/` +(built-in tools), `config/` (settings, permissions, project settings), `tests/`. + +### Adding a provider + +Subclass `LLMProvider` in `providers/.py`, implement `generate()`, and register it in +`providers/__init__.py`. Set the capability flags honestly: `supports_images` and `supports_streaming` +(`generate()` then accepts `on_text` and streams deltas). OpenAI-compatible APIs can reuse `chat_create` / +`post_chat` and `openai_user_content` from `providers/base.py`. Add tests with a mocked client. + +### Adding a tool + +Subclass `Tool` in `tools/`, give it a pydantic `args_schema`, register it in `build_tools` / +`start_repl`, and describe what the user sees in `utils/tool_display.py`. If it changes files, make sure +checkpoints can snapshot it (`core/checkpoints.py`). Tools that can do damage need permission handling in +`config/permissions.py`. + +### Adding a slash command + +Add it to `SLASH_COMMANDS` in `cli/constants.py` (that feeds the dropdown and `/help`) and handle it in the +REPL in `cli/main.py`; put non-trivial logic in `cli/repl_commands.py` so it can be tested. A test fails if a +command appears in the dropdown without a handler. + +## Testing notes + +- Tests must not touch your real `~/.devorch`: monkeypatch `Path.home()` and the config paths (see + `tests/test_repl_commands.py` for a fixture). +- Do not assert on `--help` text; it is colourised and wrapped differently per terminal. Inspect the + registered options instead. +- Terminal UI behaviour (layout, colours, key bindings) is tested on a virtual terminal with + `tests/_screen.py` (uses `pyte`), so it can be verified without a real terminal. +- Mock the model: provider tests use fake clients, never live APIs. + +## Releasing (maintainers) + +1. Bump the version in `pyproject.toml` **and** `cli/constants.py`, and add the `CHANGELOG.md` entry. +2. Merge to `main`, then push a `vX.Y.Z` tag. The publish workflow builds, uploads to PyPI and creates the + GitHub release. Published versions cannot be reused, so double-check before tagging. diff --git a/README.md b/README.md index 69ddab7..96fe7a3 100644 --- a/README.md +++ b/README.md @@ -16,20 +16,6 @@ DevOrch gives you a coding assistant in your terminal that can execute shell commands, edit files, search your codebase, manage terminal sessions, and remember context across conversations — powered by any of 13+ AI providers or your own local models. -## Screenshots - -| Startup | Chat | -|---------|------| -| ![Startup](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/startup.png) | ![Chat](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/chat.png) | - -| Provider Selection | Model Selection | -|--------------------|-----------------| -| ![Providers](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/providers.png) | ![Models](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/models.png) | - -| Tool Execution | Terminal Session | -|----------------|-----------------| -| ![Tools](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/tools.png) | ![Terminal](https://raw.githubusercontent.com/Amanbig/DevOrch/main/assets/terminal.png) | - ## Why DevOrch? - **Provider freedom** — Switch between OpenAI, Anthropic, Gemini, Mistral, Groq, and 8 more providers (including local models) with a single command. No vendor lock-in. @@ -554,28 +540,21 @@ mcp_servers: ## Contributing -Contributions are welcome! Here's how to get started: +Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (setup, workflow, how to add a +provider, tool or slash command, testing notes). The short version: ```bash -# Clone and install in development mode git clone https://github.com/Amanbig/DevOrch.git cd DevOrch pip install -e ".[dev]" -# Run linting -ruff check . -ruff format . - -# Run tests -pytest +ruff check . && ruff format . # lint and format +pytest # tests (no network or API keys needed) ``` -### Guidelines - -- Run `ruff check .` and `ruff format .` before submitting -- Add tests for new features -- Keep PRs focused — one feature or fix per PR -- Update the README if adding user-facing features +- Keep PRs focused: one feature or fix per PR, with tests, and update the README/CHANGELOG for user-facing changes +- Please follow the [Code of Conduct](CODE_OF_CONDUCT.md) +- Security issues: report them privately, see [SECURITY.md](SECURITY.md) ### Project Structure @@ -600,8 +579,9 @@ DevOrch/ ## Roadmap -- [ ] Streaming responses -- [ ] Multi-file context awareness +- [x] Streaming responses +- [x] Image input +- [x] `@file` mentions (multi-file context) - [ ] Plugin marketplace - [ ] VS Code extension - [ ] Agent-to-agent delegation diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b830311 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,34 @@ +# Security Policy + +## Supported versions + +Security fixes are made against the latest released minor version. Please upgrade before reporting. + +## Reporting a vulnerability + +**Please do not open a public issue for security problems.** + +Use GitHub's private reporting: go to the repository's **Security** tab and choose **Report a vulnerability** +(). Include what you found, how to reproduce it, +and the impact you expect. I'll acknowledge reports on a best-effort basis and keep you updated until it is +fixed and released; credit is given if you want it. + +## What counts + +DevOrch is an agent that runs commands and edits files on your machine **by design**, so the interesting +problems are about the guard rails around that: + +- Bypassing the permission system (deny rules, the built-in dangerous-command blocks, ASK / PLAN modes). +- A cloned repository executing code, enabling MCP servers or widening permissions **without** the user running + `devorch trust` (project hooks, `.devorch/settings.yaml`). +- Leaking API keys (to logs, session storage, error messages, or another provider). +- Path or command injection through tool arguments (for example the `git` tool, `@file` mentions). + +Running a command because the model decided to is expected behaviour in AUTO mode and with +`--dangerously-skip-permissions`; that alone is not a vulnerability. + +## Handling your keys + +API keys are stored in the OS keychain (via `keyring`) or read from environment variables; they are not written +to `config.yaml` and are never read from project files. If you share logs or `devorch --output json` output in +an issue, check them for secrets first.