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.
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.
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.
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.
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.
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.
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.