Skip to content

Development environment setup #431

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
abhimehro wants to merge 1 commit into from
Closed

Development environment setup #431

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# AGENTS.md

## Cursor Cloud specific instructions

### Overview

This is **ctrld-sync**, a single-file Python CLI tool (`main.py`) that syncs Control D DNS folders with remote block-lists via the Control D API. No external services (databases, caches, Docker) are needed.

### Prerequisites

- **Python 3.13+** (required by `pyproject.toml`). The VM update script installs `uv`, which manages the Python version automatically.
- **uv** is the preferred package manager (`uv.lock` present). Run `uv sync --all-extras` to install runtime + dev deps.

### Common commands

- **Install deps**: `uv sync --all-extras`
- **Run tests**: `uv run pytest tests/ -v`
- **Lint (ruff)**: `ruff check .` and `ruff format --check .` (ruff is installed as a uv tool, not a project dep)
Copy link

@gemini-code-assist gemini-code-assist bot Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The 'Trunk' section below states that the project uses Trunk for linting with ruff, bandit, black, and isort. However, the command listed here only runs ruff. To ensure all configured linters are executed for a comprehensive check, it would be better to use the trunk command. This also makes the documentation more consistent.

Suggested change
- **Lint (ruff)**: `ruff check .` and `ruff format --check .` (ruff is installed as a uv tool, not a project dep)
- **Lint (Trunk)**: `trunk check .` and `trunk fmt --check .`

- **Run app**: `uv run python main.py --help` / `uv run python main.py --dry-run`
- **Run benchmark**: `uv run python benchmark_retry_jitter.py`

### Known issues

- **Pre-existing syntax error in `main.py` line 1141**: `for j, rule in enumerate (rgi"rules"1):` is corrupted code. This exists on the `main` branch as well and prevents `import main` from working, which blocks most tests and the CLI itself. Only `tests/test_fix_env.py` (which imports `fix_env` instead) passes.

### Environment variables

For live runs (not `--dry-run`), set `TOKEN` and `PROFILE` in a `.env` file (see `.env.example`). These are Control D API credentials and are **not** needed for running tests or `--dry-run`.

### Trunk

The project uses Trunk for linting (`.trunk/trunk.yaml`) with ruff, bandit, black, isort, etc. Trunk actions (pre-commit/pre-push) are disabled in the config.
Loading