Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ with a custom scheme:

### Fixed

- **A failed `draft`, `substitute` or `update` rolls back what it already installed (closes #59)**
All three install a plan as separate persisted steps — extract, link, record — and none undid them on a failure: `draft`'s `session_packages` was "for rollback" but only fed the `--json` `installed` list, `substitute`'s `new_installed` was honoured only when removing the old package's roster row failed (and then only for the root), and `update` tracked nothing and deleted the old release's extract dir before the new one was linked. A failure partway through — a download, a missing binary, a vetoing pre-hook — left the earlier packages linked and on the roster. The new `src/commands/rollback.rs` adds a `Session` each command notes every step in (`begin` before a package's first change, then `downloaded`/`linked`/`recorded`); on an error the command unwinds it newest first, then returns the original error. A package new to the run is unlinked, removed from the roster and purged from the cache (`Downloader::purge_download`). A package the run found already installed is restored rather than removed: `begin` snapshots its roster row and `package_dependencies` rows, and rollback writes them back (via `InstalledPackage::to_package` and `insert_package`, so only `installed_at` is reset) and points its link at its old binary again — without that, a failed `draft --force`, a failed `substitute` (which re-fetches dependencies the user already has, since `resolve_deps_with_root` returns them) and a failed `update` would each have uninstalled working packages. `draft`'s and `substitute`'s loops move into `install_plan` and `install_replacement`, and `update`'s steps from the first new dependency to recording the new release into `install_update`. `update` now prunes the old extract dir only after the new release is linked and recorded, so rolling back never needs files it deleted. `substitute` also rolls back when the old package cannot be unlinked or removed, and puts the old package's link back if its roster row could not be deleted, which the old partial rollback left removed. Behaviour changes: a failed run prints `Rolled back undid this run's changes to <names>` as a warning (hidden by `-q`/`--json`; details at `--verbose`); `draft --json`'s `installed` lists the packages recorded this run, as before. Not undone: what a system package manager, `cargo install` or a hook did — a warning says when a system or cargo package stays installed with only its roster entry removed. Post-hooks still never fail a command, so they cannot trigger a rollback; Referee Phase A still runs before every install loop. Unit tests in `rollback.rs` cover removal, restore (row, `user_installed`, dependency rows), the same-version reinstall that keeps its tree, and ordering; new `tests/rollback.rs` drives the binary against a mock registry for each command's failure paths and both success paths. The six failure cases fail against the previous code. `tests/rollback.rs` reads which version a package is exposed as from the binary itself, so it covers Windows' copied `<name>.exe` the same way as a Unix symlink, and honours `BALLER_TEST_BIN` like `json_output.rs`. Verified on Windows 11 (PowerShell 5.1, execution policy `Restricted`): all 8 end-to-end cases, the 5 unit tests and the full lib, bin and `json_output` suites pass. Under Wine the 6 non-hook cases pass and the 2 hook-veto cases fail only because Wine's `powershell` is a stub that exits 0. Documented in `docs/commands.md`, `docs/error-handling.md` and `docs/architecture.md`, which already described rollback for `draft` and `substitute` that did not exist.

- **The build scripts run cargo in the repository, wherever they are called from**
`build.sh` and `build.ps1` ran a bare `cargo` in the caller's working directory, and cargo finds its project by walking up from there, not from the script. Called from outside the repo, every command failed with ``could not find `Cargo.toml` ``; called from inside *another* Cargo project, they built, tested and linted that project instead — and `clean` deleted that project's `target/` and reported success, leaving baller's own untouched. Every cargo invocation now runs from the repository root (`run_cargo` in `build.sh`, `Invoke-Cargo` in `build.ps1`), so the scripts behave the same from any directory. `build.sh`'s `run_build` no longer assembles its command as a string for `eval`; it passes `CARGO_FLAGS` to cargo as an array. Documented in `CONTRIBUTING.md` (Development Setup).

Expand Down
17 changes: 14 additions & 3 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ baller/
│ │ ├── freeze.rs # Pin/unpin packages
│ │ ├── substitute.rs # Swap packages
│ │ ├── update.rs # Update non-frozen packages
│ │ ├── rollback.rs # Undo a failed draft/substitute/update
│ │ ├── sweep.rs # Clean cache
│ │ ├── referee/ # referee group: audit, check, scan, cache, config, sbom
│ │ └── build.rs # Assemble a package from a local manifest
Expand Down Expand Up @@ -298,9 +299,19 @@ The modules live in `src/security/` and are mapped in
## Error Handling and Rollback

### Partial Failure Rollback
Commands that install multiple packages (`draft`, `substitute`) track packages
installed during the current session. If any package fails to install, all
packages from the session are rolled back (symlink removed, DB entry deleted).
`draft`, `substitute` and `update` install a plan as separate persisted steps
(extract, link, record) with no transaction around them, so each notes every
step in a `commands::rollback::Session` as it goes. On a failure the session is
unwound newest package first, then the original error is returned. A package
new to the run is unlinked, taken off the roster and purged from the cache
(extract dir and archive). A package the run found already installed — a
`draft --force` reinstall, a dependency `substitute` re-fetched, `update`'s
root — gets its snapshotted roster row and dependency rows written back and
its link pointed at its old binary again. `update` prunes the old release's
extract dir only after the new one is linked and recorded, so that binary is
always still there to go back to. Rollback is best-effort (a step that cannot
be undone is logged at `--verbose`) and runs no hooks; what a system package
manager or `cargo install` did is not undone.

### Orphan Dependency Cleanup
When ejecting a package, BALLER checks for orphaned dependencies — packages
Expand Down
18 changes: 17 additions & 1 deletion docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,12 @@ instead of reporting a plan that cannot work — see
[error-handling.md](error-handling.md#github-source-asset-errors). `-v` logs
the chosen asset's file name alongside the URL.

If any step of the install fails partway through the plan — a download, a
missing binary, a `pre_install` hook vetoing a later package — the packages
this run already installed are rolled back before the error is reported, and a
package `--force` reinstalled goes back to the version it was at. See
[error-handling.md](error-handling.md#rollback-on-partial-failure).

### Installation Modes

The `draft` command follows one of four code paths depending on the package
Expand Down Expand Up @@ -338,6 +344,12 @@ If the replacement extracts without an executable, the substitution fails with
`NoBinaryFound` **before** the old package is ejected, so a broken replacement
cannot cost you a working package.

Any failure before the old package is off the roster rolls the whole
replacement back: packages it installed fresh are removed, and dependencies you
already had (which `substitute` re-fetches) go back to the version they were
at. If the old package's roster entry cannot be removed, its link is put back
too, so it comes out of a failed substitution exactly as it went in.

**Example:**
```
$ baller substitute ripgrep hound
Expand Down Expand Up @@ -420,7 +432,11 @@ not just strict semver. Falls back to string comparison when both versions
cannot be parsed.

New dependencies introduced by the updated version are automatically installed.
Old extracted cache directories are cleaned before the new version is installed.
The old version's extracted cache directory is pruned only once the new version
is linked and recorded. If anything fails before that — a new dependency, the
`pre_update` hook, the new download — the new dependencies are rolled back and
the old version keeps its link, roster entry and files, and `update` stops with
the error.

Both `BALLER_OLD_VERSION` and `BALLER_NEW_VERSION` environment variables are
available in pre-update and post-update hooks.
Expand Down
24 changes: 17 additions & 7 deletions docs/error-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,13 +288,23 @@ See [referee.md](referee.md).

## Rollback on Partial Failure

When `draft` or `substitute` installs multiple packages and one fails mid-way,
all packages installed during the current session are cleaned up:
- Symlinks are removed
- Database entries are deleted
- The original error is returned after cleanup

This ensures the system is never left in a partially-installed state.
When `draft`, `substitute` or `update` fails partway through its plan, every
package the run already changed is put back, newest first, before the original
error is returned:
- A package the run installed fresh is unlinked, removed from the roster, and
its extract dir and cached archive are deleted.
- A package that was already installed (a `draft --force` reinstall, a
dependency `substitute` re-fetched, the package `update` was upgrading) gets
its previous roster row, dependency rows and link back. Its `installed_at`
is the one thing reset, to the time of the rollback.

A warning names the packages rolled back (`Rolled back undid this run's changes
to …`). Cleanup is best-effort: a step that cannot be undone is logged at
`--verbose` and never replaces the original error. Rollback does not run hooks,
and does not uninstall what a system package manager or `cargo install` put on
the system — a warning says when such a package stays installed with only its
roster entry removed. Post-hooks still never fail a command, so a failing
`post_install` or `post_update` hook does not trigger a rollback.

## Confirmation Prompts

Expand Down
96 changes: 68 additions & 28 deletions src/commands/draft.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
use colored::Colorize;
use serde_json::json;
use std::collections::HashMap;
use std::path::Path;

use crate::commands::rollback::Session;
use crate::context::{effective_source_order, AppContext};
use crate::core::dep_solver::{get_installed_map, resolve_deps_with_root};
use crate::core::downloader::DownloadedPackage;
Expand Down Expand Up @@ -81,8 +83,9 @@ pub fn execute_draft(

// Every package this draft would install — the root and each dependency
// the chain resolved — must be able to run on this host. Gated before the
// dry-run report and before the install loop, which has no rollback, so a
// mismatch deep in the graph cannot leave earlier packages installed.
// dry-run report and before the install loop, so a mismatch deep in the
// graph is reported as a plan that cannot work rather than as a failure
// the loop has to roll back.
for candidate in &result_packages {
if !installed.contains_key(&candidate.name) || opts.force {
ensure_installable(candidate)?;
Expand All @@ -99,10 +102,11 @@ pub fn execute_draft(
}

// Referee Phase A: the whole plan is checked before any of it is
// installed. The loop below has no rollback — `session_packages` is
// tracked for reporting, not for undoing — so blocking here is the only
// place a block can be atomic. It also runs before the PreInstall hook, so
// a package Referee rejected never gets to run code of its own.
// installed. The loop below rolls back its own links and roster rows on a
// failure, but not what a system package manager, cargo or a hook already
// did, so blocking here is the only place a block is fully atomic. It also
// runs before the PreInstall hook, so a package Referee rejected never
// gets to run code of its own.
let gate = ctx.referee.gate(&ctx.db, &result_packages)?;
gate.report(quiet);

Expand All @@ -114,11 +118,56 @@ pub fn execute_draft(
return Err(blocked);
}

// D1: Track packages installed in this session for rollback
let mut session_packages: Vec<String> = Vec::new();
// Every step the loop takes is noted in `session`, so a failure partway
// through the plan unwinds the packages already installed instead of
// leaving a partial set behind (#59).
let mut session = Session::default();
let mut skipped: Vec<String> = Vec::new();

for pkg_to_install in &result_packages {
if let Err(e) = install_plan(
ctx,
&pkg,
&result_packages,
opts,
&mut installed,
&mut session,
&mut skipped,
) {
session.rollback(ctx);
return Err(e);
}

if ctx.flags.json {
return print_json(&json!({
"command": "draft",
"package": pkg.name,
"version": pkg.version,
"source": source_label(&pkg.source),
"installed": session.installed(),
"skipped": skipped,
"referee": gate.to_json(),
}));
}

Ok(())
}

/// Install each package of the plan in order, noting every step in `session`.
///
/// Returns at the first failure without undoing anything; the caller rolls
/// the session back.
fn install_plan(
ctx: &AppContext,
root: &Package,
plan: &[Package],
opts: &DraftOptions,
installed: &mut HashMap<String, String>,
session: &mut Session,
skipped: &mut Vec<String>,
) -> Result<(), BallError> {
let quiet = ctx.flags.is_quiet();

for pkg_to_install in plan {
if installed.contains_key(&pkg_to_install.name) && !opts.force {
tracing::info!(
"{} {} already installed",
Expand All @@ -139,16 +188,18 @@ pub fn execute_draft(
&[],
)?;

session.begin(&ctx.db, pkg_to_install)?;

// System packages are installed via the native package manager,
// not downloaded/archived. Record them in the DB and continue.
if let PackageSource::System { manager } = &pkg_to_install.source {
tracing::info!("{} installing via {}...", "System".green(), manager.cyan());
install_system_package(manager, &pkg_to_install.name)?;

let is_root = pkg_to_install.name == pkg.name;
let is_root = pkg_to_install.name == root.name;
ctx.db
.insert_package(pkg_to_install, "", None, None, is_root)?;
session_packages.push(pkg_to_install.name.clone());
session.recorded();
installed.insert(pkg_to_install.name.clone(), pkg_to_install.version.clone());

run_hook(
Expand Down Expand Up @@ -180,10 +231,10 @@ pub fn execute_draft(
);
install_cargo_package(crate_name)?;

let is_root = pkg_to_install.name == pkg.name;
let is_root = pkg_to_install.name == root.name;
ctx.db
.insert_package(pkg_to_install, "", None, None, is_root)?;
session_packages.push(pkg_to_install.name.clone());
session.recorded();
installed.insert(pkg_to_install.name.clone(), pkg_to_install.version.clone());

run_hook(
Expand Down Expand Up @@ -218,6 +269,7 @@ pub fn execute_draft(
let downloaded = ctx
.downloader
.download_and_extract(pkg_to_install, !quiet)?;
session.downloaded(&downloaded);

tracing::debug!(
"{}: extracted to {} (binary: {})",
Expand Down Expand Up @@ -246,23 +298,23 @@ pub fn execute_draft(
let bin_path_str = Some(binary_path.to_string_lossy().to_string());

ActiveManager::create_symlink(&binary_path, &pkg_to_install.name)?;
session.linked();
tracing::info!(
"{} symlinked to {}",
"Linked".green(),
binary_path.display().to_string().cyan()
);

// Pass user_installed=true for root packages, false for deps
let is_root = pkg_to_install.name == pkg.name;
let is_root = pkg_to_install.name == root.name;
ctx.db.insert_package(
pkg_to_install,
&install_path,
bin_path_str.as_deref(),
None,
is_root,
)?;

session_packages.push(pkg_to_install.name.clone());
session.recorded();

// D3: Update the installed map so subsequent packages see this one
installed.insert(pkg_to_install.name.clone(), pkg_to_install.version.clone());
Expand All @@ -289,18 +341,6 @@ pub fn execute_draft(
);
}

if ctx.flags.json {
return print_json(&json!({
"command": "draft",
"package": pkg.name,
"version": pkg.version,
"source": source_label(&pkg.source),
"installed": session_packages,
"skipped": skipped,
"referee": gate.to_json(),
}));
}

Ok(())
}

Expand Down
1 change: 1 addition & 0 deletions src/commands/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ pub mod external;
pub mod freeze;
pub mod inject;
pub mod referee;
pub(crate) mod rollback;
pub mod roster;
pub mod substitute;
pub mod sweep;
Expand Down
Loading
Loading