AGENTS.md — working in the flua repository

Guidance for AI agents (any framework — Claude Code, Codex, Copilot, DeepSeek, or plain LLM tooling) working on flua. Humans: see CONTRIBUTING.md and USAGE.md.

What this repo is

flua is a Lua engine for Fibaro HC3 QuickApps: lupa (bundled Lua) hosted in Python with an asyncio pump, a virtual clock, a message-passing bridge, and a simulated HC3 REST API. The same QA file runs offline in the sim, online against a real HC3, or in proxy mode (a mirror QA on the HC3).

• Runtime: src/flua/ — Python engine + the HC3 runtime in src/flua/lua/.
• Docs: USAGE.md (user guide), ARCHITECTURE.md (internals), docs/concurrency.md (threading/execution model, blocking rules, graceful exit), docs/walkthroughs.md (guided traces of key flows), docs/invariants.md (behavioral contracts with their pinning tests), docs/rest-endpoints.md (real vs shape-only-stub REST routes), docs/mcp.md (the flua-mcp server: protocol, tools, host setup), docs/decisions/ (ADR-lite — update when a decision changes). README.md (overview).
• Examples: examples/ — runnable QuickApps; the test suite treats them as living fixtures, so keep them terminating unless their purpose is to run forever.
• Specs/references: docs/specs/ — including hc3-api.json, the checked-in structural reference of the HC3 REST API (endpoints, parameters, response codes, schema fields) distilled from the official swagger.

Commands

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"   # first time
.venv/bin/pytest tests/ -q                  # full suite (live-HC3 skipped)
.venv/bin/pytest tests/ -q --serial         # one process (debugging; -n 0 also works)
.venv/bin/pytest tests/ -q -m "not slow"    # fast gate: skips wall-clock-bound tests
.venv/bin/pytest tests/test_qa.py -q        # one file
.venv/bin/ruff check src/ tests/            # lint (must pass)
.venv/bin/ruff format src/ tests/           # format (line length 100)
.venv/bin/flua --check file.lua             # static check a QA

Python 3.11+. lupa is the only runtime dependency.

Repository map

Compatibility

• Python 3.11 or newer is supported.
• lupa is the only runtime dependency; avoid adding dependencies without discussing the trade-off in the change.
• Preserve HC3 behavior where practical. If flua intentionally differs, make the difference explicit in tests and document it in USAGE.md or ARCHITECTURE.md.
• Treat CLI flags, --%% directives, public Python APIs, and Lua runtime APIs as compatibility-sensitive. Do not change them silently.

How the tests work

• Almost everything runs offline: QAs against the simulated HC3, and online/proxy tests against local mock HC3 servers (threaded HTTP servers defined in the test files themselves). Never hit a real controller.
• Tests run in parallel by default (-n auto in addopts; ~20s on 8 cores). --serial (or -n 0) runs one process for debugging; -m "not slow" skips the tests that deliberately spend wall-clock time (real sleeps, protocol settles, socket timeouts) — they carry the slow marker.
• tests/test_hc3_live.py / tests/test_hc3_compat.py are opt-in live-HC3 suites (set HC3_TEST=1 and configure credentials).
• Many tests bind localhost sockets (mock servers, emulator callback servers). A sandbox that denies socket binds will fail them — run with local socket access.
• Tests assert on QA stdout (capsys) and on mock-server request records — follow that pattern for new behavior: deterministic, no sleeps where a wait_until/wait_for_output helper exists.

Architecture map (read before changing)

• src/flua/engine.py — LuaEngine: the lupa VM, message queues, pump. Single-entry discipline: Lua is entered only from _PY.dispatch(batch).
• src/flua/messages.py — the wire format; everything crossing the bridge is a JSON-compatible dict. Never cross a Lua function reference.
• src/flua/api/ — the HC3 REST API. state.py is the sim world; routes/*.py are pure (SimState, ApiRequest) -> (data, status) handlers; Api.dispatch does hybrid routing (sim first, real HC3 as fallback, offline-pinned QAs never reach the HC3).
• src/flua/lua/ — the HC3 runtime in Lua: init.lua (pump handlers, timers, per-QA environments), quickapp.lua, fibaro.lua, net.lua, mqtt.lua.
• src/flua/cli.py — the flua command.
• src/flua/tools/ — the --tool commands (downloadQA/uploadQA/updateQA): one module per tool, auto-discovered by the package registry; shared helpers live in tools/common.py.
• src/flua/config.py — --%% directive parsing, --%%include defaults, .flua-directives overrides, mode normalization (--%%mode:online|offline|proxy).
• src/flua/proxy.py — proxy mode: proxy QA deployment on the HC3, state mirroring, callback server.

Conventions and invariants

• Run ruff check and the relevant tests before and after any change; add a test for new behavior (the suite is the contract).
• API handlers stay pure; side effects go through req.emit / req.remote / forward_to_proxy.
• QA ids: engine-assigned from 5000; proxy QAs run under their HC3 id; the sim shadow and the HC3 device are the same id.
• A QA's api.* calls with a remote backend (online/proxy mode) suspend only the calling QA — the pump and other QAs keep running (per-QA coroutines + the shared deferral machinery, init.lua). Engine-side remote calls and the debugger still block the pump — keep those LAN-local and rare.
• Keep _PY (the Lua↔Python bridge surface) minimal; convenience lives in Lua.
• dev/ is scratch. Do not commit probes.
• Docs: behavior changes belong in USAGE.md (user-facing) and/or ARCHITECTURE.md (internals); new contracts, event shapes, or identity rules belong in docs/invariants.md with a pinning test; concurrency changes belong in docs/concurrency.md. Directive changes belong in the directive table.

Workflow for AI agents

Use this workflow regardless of the agent framework (Copilot, Codex, Claude Code, Cursor, or another tool):

1. Read this file and CONTRIBUTING.md, then inspect the relevant source and existing tests before proposing a change.
2. Make the smallest focused change; do not refactor unrelated code.
3. Add or update a deterministic test for behavior changes. Do not use a live HC3 unless the user explicitly requests it.
4. Update the appropriate documentation when behavior, directives, CLI flags, or compatibility contracts change.
5. Run the narrowest relevant test first, then ruff check src/ tests/ and pytest tests/ -q when practical.
6. Review the diff for secrets, accidental probes, live-controller access, and generated files.
7. Report changed files, tests run, and any validation that could not run.

Working with the user

• The project owner is the author and main developer; changes are reviewed commit-by-commit. Prefer small, focused, verifiable changes.
• When a behavior is intentional-but-surprising (e.g. a proxy QA sharing its HC3 device id with the sim shadow), document it rather than silently changing it.
• Do not touch the live HC3 from tests or scripts unless explicitly asked.

Repo-specific agent files

• .github/copilot-instructions.md — GitHub Copilot workspace instructions.
• .github/instructions/quickapp-dev.instructions.md — auto-applied to all *.lua files in Copilot.
• .github/skills/ — Copilot slash-command skills (flua-setup, flua-troubleshooting, quickapp-*, hc3-rest-api, ...).
• .github/prompts/install-qa-skills.prompt.md — installs the above into another workspace.