Creepso/agent-desktop
1
0
Fork 0
mirror of https://github.com/lahfir/agent-desktop.git synced 2026-07-27 01:22:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

docs: add community health files for GitHub community standards

Browse source 
Completes the recommended community profile (opensource.guide best practices):
- CODE_OF_CONDUCT.md — Contributor Covenant v2.1
- CONTRIBUTING.md — repo-accurate dev workflow, quality gates, coding standards,
  conventional-commit and command-extensibility guidance
- SUPPORT.md — where to get help / report issues
- .github/ISSUE_TEMPLATE/ — bug + feature issue forms and config (security and
  docs contact links; blank issues disabled)
- .github/PULL_REQUEST_TEMPLATE.md — summary, type, gate checklist
This commit is contained in:
Lahfir 2026-06-28 18:35:20 -07:00
parent 5cb71051f6
commit f2553b19cc
7 changed files with 554 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
.github/ISSUE_TEMPLATE/bug_report.yml vendored Normal file
View file

@ -0,0 +1,109 @@
name: Bug Report
description: Report a reproducible defect in agent-desktop
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to file a bug report.
Before submitting, please **search existing issues** to avoid duplicates.
Fill in every required field — incomplete reports will be closed without investigation.
- type: input
id: version
attributes:
label: agent-desktop version
description: Paste the output of `agent-desktop --version`
placeholder: "agent-desktop 0.1.8"
validations:
required: true
- type: dropdown
id: os
attributes:
label: Operating system
options:
- macOS
- Windows
- Linux
- Other
validations:
required: true
- type: input
id: os_version
attributes:
label: OS version
description: "e.g. macOS 15.2 Sequoia, Windows 11 24H2, Ubuntu 24.04"
placeholder: macOS 15.2 Sequoia
validations:
required: true
- type: input
id: install_method
attributes:
label: Installation method
description: How did you install agent-desktop?
placeholder: "npm / GitHub release / built from source"
validations:
required: true
- type: textarea
id: command_and_output
attributes:
label: Command run and full JSON output
description: Paste the exact command you ran and the complete JSON response.
render: shell
placeholder: |
$ agent-desktop snapshot --app Finder
{"version":"2.0","ok":false,"command":"snapshot","error":{"code":"APP_NOT_FOUND",...}}
validations:
required: true
- type: textarea
id: steps_to_reproduce
attributes:
label: Steps to reproduce
description: Numbered steps that reliably trigger the bug.
placeholder: |
1. Open Finder
2. Run `agent-desktop snapshot --app Finder`
3. Observe error
validations:
required: true
- type: textarea
id: expected_behavior
attributes:
label: Expected behavior
description: What should have happened?
validations:
required: true
- type: textarea
id: actual_behavior
attributes:
label: Actual behavior
description: What actually happened?
validations:
required: true
- type: checkboxes
id: macos_permission
attributes:
label: macOS Accessibility permission (macOS only)
description: Skip if you are not on macOS.
options:
- label: I have granted Accessibility permission in **System Settings > Privacy & Security > Accessibility**
required: false
- type: textarea
id: logs
attributes:
label: Logs / additional context
description: |
Paste verbose logs if available. Re-run with `RUST_LOG=debug agent-desktop <your-command>` to capture them.
Include any other context that might help (target app, screenshot, etc.).
validations:
required: false

8
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View file

@ -0,0 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Security vulnerabilities
url: https://github.com/lahfir/agent-desktop/security/advisories/new
about: Report security issues privately (do not open a public issue).
- name: Documentation & usage
url: https://github.com/lahfir/agent-desktop#readme
about: Read the README and skill docs before filing.

66
.github/ISSUE_TEMPLATE/feature_request.yml vendored Normal file
View file

@ -0,0 +1,66 @@
name: Feature Request
description: Propose a new command, flag, or behavior for agent-desktop
title: "[Feature]: "
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Thanks for proposing an improvement to agent-desktop.
agent-desktop is a **machine-facing tool** — features are evaluated by how they help AI agents observe and control desktop applications more effectively.
Please be as specific as possible about the use case.
- type: textarea
id: problem_use_case
attributes:
label: Problem / use case
description: |
Describe the agent workflow that is blocked or degraded today.
Frame it from the agent's perspective: "As an agent I want to…"
placeholder: |
As an agent I want to read the selected text in any app so that I can
operate on clipboard contents without issuing a separate `clipboard get` command.
validations:
required: true
- type: textarea
id: proposed_solution
attributes:
label: Proposed solution
description: |
Describe the new command, flag, or behavior you have in mind.
Include example CLI invocations and the JSON output you would expect.
placeholder: |
Add a `--selection` flag to `snapshot` that appends a `selected_text` field
to the response envelope when the focused element has a non-empty selection.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: What workarounds or alternative designs did you explore, and why do they fall short?
validations:
required: false
- type: dropdown
id: platform
attributes:
label: Target platform(s)
description: Which platform(s) should this feature cover?
options:
- macOS
- Windows
- Linux
- All platforms
validations:
required: false
- type: checkboxes
id: prior_search
attributes:
label: Prior search
options:
- label: I have searched existing issues and discussions and did not find a duplicate
required: true

41
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View file

@ -0,0 +1,41 @@
## Summary
<!-- What changed and why — 1–3 lines. -->
## Related issues
Closes #
## Type of change
- [ ] `feat:` — new feature
- [ ] `fix:` — bug fix
- [ ] `docs:` — documentation only
- [ ] `refactor:` — no behavior change
- [ ] `perf:` — performance improvement
- [ ] `test:` — adding or fixing tests
- [ ] `chore:` — maintenance / dependencies
- [ ] `ci:` — CI/CD changes
- [ ] `BREAKING CHANGE` — incompatible ABI or CLI change
## How tested
<!-- Check every gate you ran. -->
- [ ] `cargo fmt --all -- --check`
- [ ] `cargo clippy --all-targets -- -D warnings`
- [ ] `cargo test --lib --workspace`
- [ ] `cargo test -p agent-desktop`
- [ ] `cargo test -p agent-desktop-ffi --tests`
- [ ] `bash tests/e2e/run.sh` (requires `--release` build + AX permission; run when behavior changes)
## Checklist
- [ ] PR title uses a conventional-commit prefix (`type: description`, lowercase, no capital after colon)
- [ ] `cargo fmt` and `cargo clippy -D warnings` are clean
- [ ] All tests pass
- [ ] No `unwrap()` added in non-test code
- [ ] No inline comments added (only `///` doc-comments on public items)
- [ ] All modified files are within the 400 LOC limit
- [ ] Skill docs updated if a command, flag, or JSON output changed (`skills/agent-desktop/` or platform skill)
- [ ] README / other docs updated if the public interface changed

132
CODE_OF_CONDUCT.md Normal file
View file

@ -0,0 +1,132 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual
identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and graciously accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall
community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or advances of
any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
the project maintainer via [@lahfir](https://github.com/lahfir).
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series of
actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or permanent
ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within the
community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

178
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,178 @@
# Contributing to agent-desktop
agent-desktop is a native Rust CLI and FFI library that gives AI agents structured access to desktop applications through OS accessibility trees. Contributions that sharpen that core mission are welcome.
## Kinds of contributions that fit this project
- **Bug fixes** — wrong JSON output, incorrect ref resolution, `STALE_REF` on a stable target, etc.
- **New commands** — additions to the 54-command surface (follow the Extensibility Pattern below)
- **Platform adapters** — Windows (Phase 2) and Linux (Phase 3) adapters implementing `PlatformAdapter`
- **App-specific quirks** — documented edge cases for specific apps (Electron, game engines, etc.) under `skills/`
- **Docs and skill files** — keeping `skills/agent-desktop*/` accurate when behaviour changes
Out of scope: embedding LLMs, GUI/TUI interfaces, browser automation, macro recording.
## Code of Conduct
This project follows the guidelines in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). All contributors are expected to uphold them.
## Prerequisites
| Requirement | Notes |
|---|---|
| **Rust toolchain** | Pinned to `stable` via `rust-toolchain.toml` (`rust-version` 1.85). `rustup` picks the correct channel automatically. |
| **macOS 13.0+** | Required to build and run the macOS adapter (`crates/macos/`). The stub adapters for Windows and Linux compile on any platform. |
| **Accessibility permission** | Required for integration and E2E tests against real apps. Grant it in **System Settings > Privacy & Security > Accessibility** by adding the terminal you run tests from. |
| **Screen Recording permission** | Required only for `screenshot` tests. Same path in System Settings. |
## Getting started
```bash
git clone https://github.com/lahfir/agent-desktop
cd agent-desktop
# Wire up the pre-commit hook (one time per clone)
git config core.hooksPath .githooks
# Debug build
cargo build
# Release build (optimised, < 15 MB)
cargo build --release
# Run the binary
./target/release/agent-desktop snapshot --app Finder -i
```
## Dev workflow and quality gates
All of these must pass before a PR is merged. The pre-commit hook runs the first four automatically.
```bash
# Format check
cargo fmt --all -- --check
# Lint — zero warnings required
cargo clippy --all-targets -- -D warnings
# Unit tests (MockAdapter, golden fixtures)
cargo test --lib --workspace
# Binary-level command tests
cargo test -p agent-desktop
# FFI integration tests (C-ABI, enum fuzzing, out-param zeroing)
cargo test -p agent-desktop-ffi --tests
# Core isolation — output must contain no platform crate names
cargo tree -p agent-desktop-core
# E2E harness against the SwiftUI fixture app (requires --release build + AX permission)
cargo build --release
bash tests/e2e/run.sh
```
The E2E harness drives the release binary against a real SwiftUI/AppKit fixture and asserts every effect by independent observation — never by trusting `ok: true`. See `tests/e2e/README.md` for what it covers and how to add a scenario.
CI additionally checks that the release binary stays under 15 MB and that `crates/ffi/src/commands/generated.rs` is not out of sync with `build.rs`.
## Pre-commit hook
The repo ships a pre-commit hook at `.githooks/pre-commit`. After cloning, enable it once:
```bash
git config core.hooksPath .githooks
```
On every commit that touches `.rs` or `.toml` files, the hook runs:
1. **Inline comment ban** — rejects bare `//` comments in staged `.rs` files (only `///` and `//!` are permitted)
2. `cargo fmt --all -- --check`
3. `cargo clippy --all-targets -- -D warnings`
4. `cargo test --lib --workspace`
When changes touch `crates/ffi/`, the hook also runs the FFI codegen-drift check and the stub-adapter passthrough tests locally.
To bypass in a genuine emergency:
```bash
git commit --no-verify
# or
SKIP_PRECOMMIT=1 git commit -m "..."
```
## Coding standards
### Conventional Commits (required)
Every commit title must begin with one of these prefixes:
| Prefix | When to use |
|---|---|
| `feat:` | new capability |
| `fix:` | bug fix |
| `feat!:` / `BREAKING CHANGE:` footer | breaking API or CLI change |
| `refactor:` | restructures code without changing behaviour |
| `perf:` | measurable performance improvement |
| `test:` | adds or fixes tests |
| `docs:` | documentation only |
| `ci:` | CI/CD changes |
| `chore:` | maintenance, dependency bumps |
| `style:` | formatting only |
Format: `type: concise imperative description` — lowercase prefix, no capital after the colon, focus on the *why*.
Examples: `feat: add scroll-to command`, `fix: prevent stale ref on window resize`, `ci: add binary size check`
### File rules
- **400 LOC hard limit per file.** If a file approaches 400 lines, split by responsibility. Generated files marked `@generated` are exempt — fix the generator, not the output.
- **No inline comments.** Code must be self-documenting through naming. Use `///` doc-comments on public items when the name alone is insufficient. `//` and end-of-line `//` comments are rejected by the pre-commit hook.
- **One struct/enum per file** for domain types. `node.rs` defines `AccessibilityNode`. `action.rs` defines `Action`.
- **One command per file.** Each CLI command lives in its own file under `crates/core/src/commands/`. Filename matches the command name.
- **No God objects.** No struct with more than 7 fields; no function with more than 5 parameters. Use builder patterns or config structs.
- **Explicit `pub` boundaries.** Only `lib.rs` re-exports public items. Internal modules use `pub(crate)`. No wildcard re-exports.
### Error handling
- **Zero `unwrap()` in non-test code.** Propagate `Result`s with `?` or match explicitly. Panics are test-only.
- Every error carries an `ErrorCode` (machine-readable), `message` (human-readable), an optional `suggestion`, and an optional `platform_detail`.
### Core isolation (non-negotiable)
`agent-desktop-core` must never import a platform crate. Platform crates must never import each other. The only legitimate wiring points are the binary crate (`src/`) and the FFI crate (`crates/ffi/`). CI enforces this with `cargo tree -p agent-desktop-core`.
## Adding a new command
Follow the Extensibility Pattern exactly — no step may be skipped:
1. Create `crates/core/src/commands/{name}.rs` with a standalone `execute()` function.
2. Register it in `crates/core/src/commands/mod.rs`.
3. Add the CLI subcommand variant to `src/cli/mod.rs` and its argument struct under `src/cli_args/`.
4. Add a `match` arm in `dispatch()` in the binary crate.
5. If a new `Action` variant is needed, add it to `crates/core/src/action.rs`.
6. If a new adapter method is needed, add it to the `PlatformAdapter` trait with a default of `Err(AdapterError::not_supported())`.
No existing files are modified beyond these six registration points.
**Mandatory skill update:** every new command or changed CLI flag must be reflected in the corresponding file under `skills/agent-desktop/references/`. Skill files are source-of-truth documentation consumed by AI agents and must stay in sync with the implementation.
## Submitting a pull request
1. **Branch from `main`.**
2. **Keep PRs focused.** One logical change per PR; separate refactors from features.
3. **Ensure all quality gates pass** locally before pushing (see Dev workflow above).
4. **Use a Conventional Commit title** for the PR title — it becomes the squash-merge commit message.
5. **Link related issues** with `Fixes #N` or `Refs #N` in the PR description.
6. **Check that `cargo tree -p agent-desktop-core` is clean** if you touched any crate dependency.
7. CI runs automatically on every push. A red CI is a blocker.
## Reporting bugs and security issues
**Bugs and feature requests:** open an issue on [GitHub Issues](https://github.com/lahfir/agent-desktop/issues). Include the OS version, the `agent-desktop version` output, the exact command that failed, and the full JSON response.
**Security vulnerabilities:** do **not** open a public issue. Use [GitHub private vulnerability reporting](https://github.com/lahfir/agent-desktop/security/advisories/new) for this repository. Include the affected version or commit, reproduction steps, expected impact, and any proof-of-concept details. See [SECURITY.md](SECURITY.md) for the full scope and response policy.
## License
By contributing, you agree that your contributions are licensed under the [Apache-2.0 License](LICENSE) that covers this project.

20
SUPPORT.md Normal file
View file

@ -0,0 +1,20 @@
# Support
## Before asking
- Read the [README](README.md) and the skill docs in [`skills/`](skills/) — the per-command reference and platform-specific notes are there.
- Search [existing issues](../../issues) to see if your question has already been answered.
## Getting help
- **Bug or unexpected behavior** — open an issue via the [issue templates](../../issues/new/choose). Include the command you ran, the full JSON output, the OS and agent-desktop version, and reproduction steps.
- **Feature request** — use the feature-request template in the same link above.
- **AI-agent integration / skill usage** — refer to the README usage section and the `skills/agent-desktop/` reference docs.
## Security vulnerabilities
Do **not** open a public issue for suspected security issues. Report privately via [GitHub Security Advisories](../../security/advisories/new) or follow the process in [SECURITY.md](SECURITY.md).
## Response
This project is maintained by [@lahfir](https://github.com/lahfir) on a best-effort basis. There is no guaranteed response time or SLA.