Skip to content

AGENTS.md

Latest commit

 

History

History
101 lines (69 loc) · 3.55 KB

AGENTS.md

File metadata and controls

101 lines (69 loc) · 3.55 KB
Raw

AGENTS

This repository is a GTK4/libadwaita desktop application for Salesforce Composite and Serial API flows. The canonical workflow is documented in CONTRIBUTING.md and README.md, and the repo uses uv as the primary launcher for local commands.

Goal

Help future agents work with this repository consistently and safely.

Primary commands

Run from the repository root.

Setup

  • uv sync
    • Installs dependencies and configures the local environment.

Local run

  • uv run salesforce-object-flow
    • Starts the desktop application.

Checks and tests

The repository expects these four checks before a pull request:

  • uv run ruff check salesforce_object_flow/ tests/
  • uv run ruff format --check salesforce_object_flow/ tests/
  • uv run pyright salesforce_object_flow/ tests/
  • uv run pytest tests/ -v

Fixing formatting and lint issues

  • uv run ruff format salesforce_object_flow/ tests/
  • uv run ruff check --fix salesforce_object_flow/ tests/

Environment

  • Python >=3.12
  • The repo uses a virtual environment under .venv when available.
  • Primary dependencies are in pyproject.toml.
  • Dev dependencies include ruff, pytest, pyright, and babel.

Repository structure

  • salesforce_object_flow/: main package
  • tests/: test suite
  • pyproject.toml: project metadata and tooling configuration
  • CONTRIBUTING.md: development workflow and checks
  • README.md: product description, status, and higher-level documentation
  • po/: translation source files (.po)
  • locale/: compiled translation artifacts (.mo), expected to be generated locally and ignored by git

Formatting and linting conventions

  • Use ruff for formatting and linting.
  • Project config is in pyproject.toml:
    • target-version = "py312"
    • line-length = 100
    • select = ["E", "F", "W", "I"]
  • Do not rely on formatting tools outside the documented uv commands unless necessary.

Type checking

  • Use pyright in strict mode for the package.
  • Only salesforce_object_flow is strict, while tests are included for analysis.
  • Avoid assert for runtime type narrowing; prefer isinstance, early returns, or explicit cast.

Translation workflow

  • Source translations live under po/<lang>.po.
  • Compiled catalogs live under locale/<lang>/LC_MESSAGES/.
  • Do not commit locale/ artifacts if they are generated locally.
  • Translation commands use uv run python scripts/i18n.py ....

Important code conventions

  • Logging: one logger per module with import logging; log = logging.getLogger(__name__).
  • Avoid asyncio and manual threads in v1; use GLib.idle_add and the Timer helper for deferred work instead.
  • Follow existing package and module structure; keep app logic in salesforce_object_flow/ and tests in tests/.

What agents should do first

  1. Read CONTRIBUTING.md and README.md.
  2. Use uv sync if the workspace needs dependencies.
  3. Verify formatting with uv run ruff format --check salesforce_object_flow/ tests/.
  4. Run the full check suite if changes are non-trivial.

When editing code

  • Preserve the existing architecture and naming patterns.
  • Prefer small, focused changes.
  • Run the relevant tests for changed modules.
  • Avoid changing translation workflows unless the feature is translation-specific.

Notes

  • salesforce-object-flow is installed as an entry point from pyproject.toml.
  • The repository is currently at alpha status, so maintainers may expect careful review for new features and bugfixes.
  • Use LANGUAGE=es uv run salesforce-object-flow to validate Spanish locale behavior.