# AGENTS.md

Guidance for AI coding agents working in this repository.

## What this is

`sb-builder`: a PyQt6 desktop GUI that drives the SlackBuild tooling on a
Slackware -current build VM (slackrepo, mkhint, sbpull, sbshadow) over ssh.
Two programs: the GUI (`sb_builder/`, PyQt6 incl. QtDBus, stdlib otherwise)
and `remote/sbb-remote`, a single-file stdlib-only Python helper deployed on
the VM. Do not add third-party dependencies to either.

Design and phasing: `docs/superpowers/specs/`. Phase 1 (core) is
`2026-10-19-sb-builder-phase1-design.md`.

## How it works

- Every GUI action is `ssh <target> sbb-remote <cmd> [args]`; the helper
  answers with JSON. `sb_builder/remote.py` is the only code that runs ssh
  (and local `virsh`).
- Trust boundary: the helper runs only a fixed table of job kinds and builds
  argv itself from validated args. Never pass shell strings or paths from the
  GUI to the helper.
- Jobs run detached on the VM (`setsid`, `stdin=/dev/null`), one at a time
  under a flock, logging to `<state_dir>/jobs/<id>/`. The GUI can disconnect
  and reattach with `job-follow <id> <offset>`.
- Jobs never get input. Any tool run as a job must be non-interactive
  (`--yes`/`--no` style flags). If a tool needs a flag it lacks, add it in
  that tool's own repo (e.g. `slackrepo_setup` for sbshadow, `mkhintfile`
  for mkhint) rather than working around it here.

## Conventions

- GUI config: `$XDG_CONFIG_HOME/sb-builder/config.toml`. Helper config:
  `/etc/sb-builder/config.toml` on the VM. Both read with `tomllib`, both
  have shipped `config.example.toml` files, defaults live in code.
- One file per GUI tab.
- Deploying to the VM is outward-facing: confirm before `install.sh --remote`.
- Placeholders only in code, docs, tests and commits.

## Testing

    python3 -m unittest discover -s tests

Headless (`test_gui.py` sets `QT_QPA_PLATFORM=offscreen`), no VM needed.
`test_remote.py` loads `remote/sbb-remote` with `SourceFileLoader` (no `.py`
extension) and points it at a temp state dir through `SBB_CONFIG`. Two
`ResourceWarning: subprocess ... is still running` lines are expected: the
detached `_run` is never waited for. To try the helper on the VM without
installing it, copy it to `/tmp` there and run it with `SBB_CONFIG` pointing
at a config whose `state_dir` is under `/tmp`.

## Repo facts

- License: GPLv2 only (`LICENSE`, header in each source file).
- Work directly on master.
- `.superpowers/` is brainstorming scratch, ignored.