From c4437a2c3bd0e9bfa6bd1adbf9cfe14898b26e0b Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 19 Oct 2026 18:49:53 +0200 Subject: Initial commit: sb-builder build VM GUI Desktop PyQt6 GUI plus a stdlib Python helper on the build VM, to drive slackrepo, mkhint and the overlay sync tools from one interface, with detachable jobs. This commit carries the repo docs and the approved phase 1 (core) design spec. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 AGENTS.md (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..282bcd6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# 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 sbb-remote [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 `/jobs//`. The GUI can disconnect + and reattach with `job-follow `. +- 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 + +No test suite yet. Planned (phase 1 spec): `python3 -m unittest discover +tests`, with the GUI smoke test under `QT_QPA_PLATFORM=offscreen`. + +## Repo facts + +- License: GPLv2 only (`LICENSE`, header in each source file). +- Work directly on master. +- `.superpowers/` is brainstorming scratch, ignored. -- cgit v1.2.3