diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..bedfe398d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,88 @@ +name: Bug Report +description: Report a bug in CLI-Anything +title: "[Bug]: " +labels: ["type: bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug! Please fill out the information below to help us reproduce and fix it. + + - type: input + id: software + attributes: + label: Affected Software/Harness + description: Which CLI harness is affected? (e.g., gimp, blender, inkscape, or "plugin" for the framework) + placeholder: e.g., gimp + validations: + required: true + + - type: input + id: version + attributes: + label: Version / Commit + description: The version or commit hash you are using. + placeholder: e.g., v1.0.0 or commit abc1234 + validations: + required: true + + - type: dropdown + id: os + attributes: + label: Operating System + options: + - Linux + - macOS + - Windows + - Other + validations: + required: true + + - type: input + id: python-version + attributes: + label: Python Version + placeholder: e.g., 3.10.12 + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: Provide clear steps to reproduce the bug. + placeholder: | + 1. Install the harness with `pip install -e .` + 2. Run `cli-anything-gimp project create test.xcf` + 3. See error... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? Include error messages or tracebacks if applicable. + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant Logs / Tracebacks + description: Paste any relevant output here. This will be auto-formatted as code. + render: shell + + - type: textarea + id: context + attributes: + label: Additional Context + description: Any other context, screenshots, or information that might help. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..06a34646b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Questions & Discussions + url: https://github.com/HKUDS/CLI-Anything/discussions + about: Please ask questions and discuss ideas here instead of opening an issue. + - name: CLI Generation Help + url: https://github.com/HKUDS/CLI-Anything/discussions/categories/q-a + about: Need help generating a CLI for a new software? Ask in Discussions first. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..0aa8ebdb2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,52 @@ +name: Feature Request +description: Suggest a new feature or enhancement +title: "[Feature]: " +labels: ["type: enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! Please describe your idea clearly so we can evaluate it. + + - type: dropdown + id: category + attributes: + label: Category + description: What type of feature is this? + options: + - New Software CLI + - Enhancement to Existing Harness + - Plugin / Framework Improvement + - Documentation + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this feature solve? What pain point are you experiencing? + placeholder: I'm always frustrated when... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Have you considered any alternative solutions or workarounds? + + - type: textarea + id: context + attributes: + label: Additional Context + description: Any other context, mockups, or references that might help. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..2910d82bc --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,51 @@ +## Description + + + +Fixes # + +## Type of Change + + + +- [ ] **New Software CLI** — adds a CLI harness for a new application +- [ ] **New Feature** — adds new functionality to an existing harness or the plugin +- [ ] **Bug Fix** — fixes incorrect behavior +- [ ] **Documentation** — updates docs only +- [ ] **Other** — please describe: + +--- + +### For New Software CLIs + + + +- [ ] `.md` SOP document exists at `/agent-harness/.md` +- [ ] `SKILL.md` exists inside the Python package (`cli_anything//SKILL.md`) +- [ ] Unit tests at `cli_anything//tests/test_core.py` are present and pass without backend +- [ ] E2E tests at `cli_anything//tests/test_full_e2e.py` are present +- [ ] `README.md` includes the new software (with link to harness directory) +- [ ] `repl_skin.py` in `utils/` is an unmodified copy from the plugin + +### For Existing CLI Modifications + + + +- [ ] All unit tests pass: `python3 -m pytest cli_anything//tests/test_core.py -v` +- [ ] All E2E tests pass: `python3 -m pytest cli_anything//tests/test_full_e2e.py -v` +- [ ] No test regressions — no previously passing tests were removed or weakened + +### General Checklist + +- [ ] Code follows existing patterns and conventions +- [ ] `--json` flag is supported on any new commands +- [ ] Commit messages follow the conventional format (`feat:`, `fix:`, `docs:`, `test:`) +- [ ] I have tested my changes locally + +## Test Results + + + +``` + +``` diff --git a/.gitignore b/.gitignore index 8a8e23618..6b44fe45b 100644 --- a/.gitignore +++ b/.gitignore @@ -13,8 +13,10 @@ # Step 2: Allow .gitignore, README, assets, and marketplace !.gitignore !/README.md +!/CONTRIBUTING.md !/assets/ !/.claude-plugin/ +!/.github/ # Step 3: Allow cli-anything-plugin, codex-skill, and skill_generation tests !/cli-anything-plugin/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..e3eb8cb1f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,98 @@ +# Contributing to CLI-Anything + +Thank you for your interest in contributing to CLI-Anything! This guide will help you get started. + +## Types of Contributions + +We welcome three main categories of contributions: + +### A) CLIs for New Software + +Adding a new CLI harness is the most impactful contribution. Before submitting a PR, ensure the following are in place: + +1. **`.md`** — the SOP document exists at `/agent-harness/.md` describing the harness architecture. +2. **`SKILL.md`** — the AI-discoverable skill definition exists inside the Python package at `cli_anything//SKILL.md`. +3. **Tests** — unit tests (`test_core.py`, passable without backend) and E2E tests (`test_full_e2e.py`) are present and passing. +4. **`README.md`** — the project README includes the new software with a link to its harness directory. +5. **`repl_skin.py`** — an unmodified copy from the plugin exists in `utils/`. + +### B) New Features + +Feature contributions improve existing harnesses or the plugin framework. Examples include new CLI commands, output formats, backend improvements, or cross-platform fixes. + +- Open an issue first to discuss the feature before starting work. +- Follow existing code patterns and conventions in the target harness. +- Include tests for any new functionality. + +### C) Bug Fixes + +Bug fixes resolve incorrect behavior in existing harnesses or the plugin. + +- Reference the related issue in your PR (e.g., `Fixes #123`). +- Include a test that reproduces the bug and verifies the fix. +- Ensure all existing tests for the affected harness still pass. + +## Development Setup + +Each generated CLI lives in `/agent-harness/` and is an independent Python package: + +```bash +# Clone the repo +git clone https://github.com/HKUDS/CLI-Anything.git +cd CLI-Anything + +# Install a harness in editable mode +cd /agent-harness +pip install -e . + +# Run tests +python3 -m pytest cli_anything//tests/ -v +``` + +### Requirements + +- Python 3.10+ +- Click 8.0+ +- pytest 7.0+ + +## Code Style + +- Follow PEP 8 conventions. +- Use type hints where practical. +- All CLI commands must support the `--json` flag for machine-readable output. + +## Commit Messages + +Use clear, descriptive commit messages following the conventional format: + +``` +feat: add Krita CLI harness +fix: resolve Blender backend path on macOS +docs: update README with new software entry +test: add unit tests for Inkscape layer commands +``` + +## Running Tests + +```bash +# Unit tests (no backend software needed) +python3 -m pytest cli_anything//tests/test_core.py -v + +# E2E tests (requires real backend installed) +python3 -m pytest cli_anything//tests/test_full_e2e.py -v + +# All tests for a harness +python3 -m pytest cli_anything//tests/ -v +``` + +## Submitting a Pull Request + +1. Fork the repository and create a feature branch from `main`. +2. Make your changes following the guidelines above. +3. Ensure all tests pass for any harnesses you modified. +4. Push your branch and open a Pull Request against `main`. +5. Fill out the PR template completely. + +## Questions? + +If you have questions, feel free to open a [Discussion](https://github.com/HKUDS/CLI-Anything/discussions) or an issue tagged with `type: question`.