Crate helixforge_engine

Expand description

Turns entries into explicit plans, runs them, and records what happened.

Every interface uses this crate the same way: plan an entry (or several) into a Plan of ordered Steps with what they need, whether they are privileged and how risky they are; show it; then run it through a Runner. The steps become one POSIX shell program that stops at the first failure. The shell only ever sees quoted literals from the validated catalog, never free text. Native operations run back inside HelixForge itself, so even they go through the same program and the same terminal.

A package step lists its sources in order (the distribution’s package, the AUR on Arch, Flathub); the program tries the next one only when the one before it fails or leaves the package missing. After a run, verify checks that each package step left its package installed, or removed.

Modules§

backups: Configuration backups in one place: the copies HelixForge’s scripts leave beside a file before changing it (<file>.commander-backup-<time>, <file>.helixforge-backup-<time>), found in the user’s configuration and in the system places those scripts change, and restored in a way that can itself be undone. Snapshots (Snapper, Timeshift) are taken before system changes where the machine supports them; HelixForge does not roll snapshots or packages back itself.
bundle: Offline installation bundles: a folder holding HelixForge itself (with its catalog inside), the packages chosen entries need for this machine’s distribution and architecture, and a manifest of every file’s checksum. On a machine of the same distribution without reliable internet, the bundle is checked, then its packages are installed by the package manager from the files, without downloading. What needs the network (Flatpaks, AUR builds, scripts) is named, never pretended to be offline.
desktop: The desktop environment manager: which desktop, session and display manager this is, its appearance settings (read with the desktop’s own tools), saved looks to put back, and who else sets those settings: Home Manager, its Plasma and dconf modules, Stylix. Reading changes nothing; applying a look is a plan of the desktop’s own commands, confirmed first.
doctor: HELIX Doctor: read-only health checks that say what is wrong, show the evidence, and offer a repair where a safe one exists. A repair is a plan of its own, confirmed and run like any other; nothing here changes the system.
drift: HELIX Drift: how a machine has moved away from a saved baseline or a workstation profile. A baseline records what was installed, the configuration files catalog entries write (by checksum, never their contents), a few machine settings and the entries HelixForge ran there. Comparing names what is missing, changed or new, and which entry would put a missing part back; nothing here changes the machine.
hardware: The hardware and firmware center: read-only facts about the machine’s firmware (through fwupd), disks, temperature sensors, batteries and PCI and USB devices, from /sys and tools that answer without root. A SMART check, which needs root, and a firmware update are plans of their own, each run only after it is confirmed.
history: An append-only record of runs in $XDG_STATE_HOME/helixforge/history.jsonl, with saved terminal output beside it under logs/.
inventory: What is installed, where from, at which version, and whether an update is waiting: one snapshot from a few read-only queries (no root, no network: updates come from the repository metadata already on the machine), so a list of entries is answered by lookups.
preflight: Checks made before a plan runs: what it needs that is missing, entries in it that conflict with each other or with what is installed, repositories it needs, the graphics hardware it is for, and whether the disk has room. A blocker stops the run; a warning is shown with the confirmation.
preview: The system change preview: what a plan is expected to change on this machine, step by step: files (side by side where the new contents can be worked out without writing anything), packages, services and when it takes effect. Every change says how it is known: worked out here, declared by the entry, or impossible to tell before the step runs. It only reads files and asks package managers read-only questions.
profiles: Workstation profiles of the user’s own: a name, a description and the entries to run, kept as TOML in $XDG_CONFIG_HOME/helixforge/profiles/, exported and imported as the same files. Each becomes a profile entry in the catalog’s Profiles area, under “Your profiles”, so it is planned, queued and run like the built-in ones.
pty: A shell program running in a pseudo-terminal, with its output collected for an interface to draw and its input forwarded from the keyboard.
reliability: How far each entry has been tested: real installs in distribution containers (recorded by the Distributions workflow and carried by release builds), installer tests with stand-in commands, and reports from virtual and real machines (catalog/validation.toml), with this machine’s own runs beside them. Nothing here claims more than its record shows.
setup: The setup wizard: what this machine is (distribution, desktop, graphics, package tools), the workstations it offers (catalog/setup.toml), and which of their entries this machine can run. The wizard only queues entries for an ordinary Install Plan; it runs nothing itself.
trust: The trust inspector: where an entry’s installer comes from, what checks the integrity of what it installs, what it downloads unchecked, what privileges it uses and how far it has been tested. It reads files and asks package managers read-only questions; it changes nothing.
updates: One overview of pending updates across the tools that keep this machine: the distribution’s package manager, an AUR helper, Flatpak and Nix. It reads what each tool already knows; an online check asks the network only through read-only commands. Updating is delegated to the tools themselves.

Structs§

Check: Whether one package step left its package as intended.
Finished: A finished run: how the program ended, how each step ended, and what the checks of the package steps that finished found.
InheritedRunner: Runs in the caller’s terminal, inheriting stdin and stdout.
Machine: The questions planning asks the machine, so tests can answer them.
MockRunner: Records the program instead of running it, for tests.
Plan: What running a set of entries means on this machine: the steps in order, plus what a reviewer needs to know before saying yes.
ShellChange: A file a HelixForge-made step changes.
Source: One way to install or remove a package.
StepResult: One step of a finished run.
UpdateTarget: A package an update step brings up to date.

Enums§

EngineError
Outcome: The outcome of a run, as the history records it.
PackageState: How a package entry stands on a machine.
Probe: A question about the system whose answer says a package is installed.
Step: One thing to run, with everything needed to run it.
StepState: How one step of a run ended.

Constants§

LIB_VARIABLE: The variable scripts use to find the shared helpers.

Traits§

Runner: Something that can run a shell program: the caller’s terminal, a pseudo-terminal, or a test double.

Functions§

aur_helper: The AUR helper to use, paru before yay.
check_requirements: Check that what the plan needs is installed before anything starts. A package step whose first source cannot run still starts when another of its sources can.
date: A day as YYYY-MM-DD in UTC, from Unix seconds, without a time library.
execute: Run a plan through a runner and record the outcome in the default history.
execute_in: Run a plan through a runner and record the outcome in history_dir.
flatpak_installed_in: Whether a Flatpak application is installed under any of the roots.
managed_path: The first of the entry’s paths that is a Home Manager symlink, or a child of one, with ~ expanded to the user’s home.
managed_path_in: managed_path with an explicit home directory. Dangling links count: the store path may be garbage-collected while the link stays.
missing_requirements: The plan’s requirements that are missing and that no other source of the steps needing them can do without.
package_state: How a package entry stands: its own packages first, then the packages it conflicts with, and its command only when neither is installed. None for an entry that is not a package.
plan: Plan one or more entries. Profiles expand into their members; a package that is already installed becomes a note instead of a step.
plan_removal: Plan removing package entries. An entry is removed the way it is found installed: its Flatpak, the family’s package or, on Arch, its AUR package with pacman. Entries that are not installed become notes, as do entries found only by their command, which HelixForge did not install.
plan_removal_with: plan_removal with the machine’s answers supplied.
plan_with: plan with the machine’s answers supplied.
quote: Quote a value for the POSIX shell.
requirement_present: Whether a requirement, a command or an absolute path, is on this machine.
run_native: Run a native action and return its text.
shell_program: The shell program that runs the steps in order and stops at the first failure. lib_dir is exported as HELIXFORGE_LIB for scripts; this is the HelixForge executable that native steps re-invoke.
shell_program_with: shell_program that also writes each step’s outcome to status, one index state exit line per step (done, failed, interrupted, skipped).
status_file: A fresh, empty file for a run’s step outcomes, only this user can write.
step_results: Read the step outcomes a run’s program wrote to status; a step with no line did not run, unless the whole program succeeded without a file.
verify: Check every package and update step of a finished plan against the system.
verify_updates_with: The checks of a plan’s update steps: each package’s version now against its version before. version and holds answer for the machine.
verify_with: verify with the questions it asks supplied, for tests.