From 333281049149dadc1c6bec7ac68c2633073436d3 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 21 Sep 2026 00:20:36 +0200 Subject: [PATCH] feat: expose lock inspection and recovery --- bin_efo/src/commands.rs | 1 + bin_efo/src/commands/safety.rs | 67 ++++++++++++++++++++++++++++++++++ bin_efo/src/error.rs | 5 +++ bin_efo/src/main.rs | 17 ++++++++- bin_efo/tests/cli_workflows.rs | 6 +++ docs/commands.md | 4 ++ 6 files changed, 98 insertions(+), 2 deletions(-) create mode 100644 bin_efo/src/commands/safety.rs diff --git a/bin_efo/src/commands.rs b/bin_efo/src/commands.rs index 26c1c20..0148382 100644 --- a/bin_efo/src/commands.rs +++ b/bin_efo/src/commands.rs @@ -13,6 +13,7 @@ pub mod epoch; pub mod generate; pub mod init; pub mod migrate; +pub mod safety; // pub mod roll; pub mod show; pub mod status; diff --git a/bin_efo/src/commands/safety.rs b/bin_efo/src/commands/safety.rs new file mode 100644 index 0000000..5ddec28 --- /dev/null +++ b/bin_efo/src/commands/safety.rs @@ -0,0 +1,67 @@ +//! Recovery and writer-lock inspection commands. + +use std::path::Path; + +use clap::{Args, Subcommand}; +use lib_efo::transaction::{RecoveryOutcome, break_lock, inspect_lock, recover}; + +use crate::error::AppError; + +/// Arguments for deterministic transaction recovery. +#[derive(Args, Debug)] +pub struct RecoverCmd {} + +/// Writer-lock administration. +#[derive(Subcommand, Debug)] +pub enum LockCmd { + /// Show which process owns the writer lock. + Inspect, + /// Remove a lock after independently confirming its owner is gone. + Break(BreakLockCmd), +} + +/// Explicit confirmation required to remove a writer lock. +#[derive(Args, Debug)] +pub struct BreakLockCmd { + /// Confirm that the recorded writer is no longer operating. + #[arg(long, required = true)] + yes: bool, +} + +/// Recover or clean an interrupted repository transaction. +pub fn handle_recover(_command: &RecoverCmd) -> Result<(), AppError> { + match recover(Path::new("."))? { + RecoveryOutcome::Clean => println!("Repository is clean — no recovery is needed."), + RecoveryOutcome::RolledBack => { + println!("✓ Rolled back an uncommitted replacement; prior data is unchanged.") + } + RecoveryOutcome::Completed => { + println!("✓ Verified the committed replacement and completed recovery.") + } + } + Ok(()) +} + +/// Inspect or explicitly remove the repository writer lock. +pub fn handle_lock(command: &LockCmd) -> Result<(), AppError> { + match command { + LockCmd::Inspect => { + let owner = inspect_lock(Path::new("."))?; + println!("Writer lock"); + println!("├─ PID {}", owner.pid); + println!("├─ Host {}", owner.hostname); + println!("├─ Command {}", owner.command); + println!("└─ Created {} (Unix time)", owner.created_at); + } + LockCmd::Break(arguments) => { + debug_assert!(arguments.yes); + let owner = break_lock(Path::new("."))?; + println!( + "✓ Removed lock for PID {} on {} (`{}`).", + owner.pid, owner.hostname, owner.command + ); + println!(" Run `efo recover` before the next mutation."); + } + } + Ok(()) +} diff --git a/bin_efo/src/error.rs b/bin_efo/src/error.rs index 7168d0d..82b447e 100644 --- a/bin_efo/src/error.rs +++ b/bin_efo/src/error.rs @@ -8,6 +8,7 @@ use lib_efo::{ error::{EpochError, StorageError}, migration::MigrationError, + transaction::TransactionError, }; use miette::Diagnostic; use thiserror::Error; @@ -38,6 +39,10 @@ pub enum AppError { /// Repository-format migration failed safely. #[error("Migration stopped: {0}")] Migration(#[from] MigrationError), + + /// Exclusive locking or interrupted-write recovery failed safely. + #[error("Repository safety check stopped: {0}")] + Transaction(#[from] TransactionError), // /// Anything else we didn't anticipate. // #[error("Unknown error: {0}")] // Other(String), diff --git a/bin_efo/src/main.rs b/bin_efo/src/main.rs index 083358d..6c33091 100644 --- a/bin_efo/src/main.rs +++ b/bin_efo/src/main.rs @@ -29,8 +29,14 @@ use clap::{Parser, Subcommand}; use crate::{ commands::{ - entity_generic::EntitySubCommands, epoch::cli_epoch::EpochCmd, generate::GenCmd, - init::InitCmd, migrate::MigrateCmd, show::ShowCmd, status::StatusCmd, + entity_generic::EntitySubCommands, + epoch::cli_epoch::EpochCmd, + generate::GenCmd, + init::InitCmd, + migrate::MigrateCmd, + safety::{LockCmd, RecoverCmd}, + show::ShowCmd, + status::StatusCmd, }, error::AppError, }; @@ -68,6 +74,11 @@ enum TopLevelCmd { Init(InitCmd), /// Preview or apply a repository-format migration. Migrate(MigrateCmd), + /// Recover an interrupted repository write. + Recover(RecoverCmd), + /// Inspect or explicitly break the repository writer lock. + #[command(subcommand)] + Lock(LockCmd), /// Gives a very simple status. Status(StatusCmd), /// Advance or query the current epoch. @@ -148,6 +159,8 @@ fn exec_dispatch(cli: Cli) -> Result<(), AppError> { match cli.command { TopLevelCmd::Init(cmd) => commands::init::init(&cmd), TopLevelCmd::Migrate(cmd) => commands::migrate::migrate(&cmd), + TopLevelCmd::Recover(cmd) => commands::safety::handle_recover(&cmd), + TopLevelCmd::Lock(cmd) => commands::safety::handle_lock(&cmd), TopLevelCmd::Epoch(cmd) => commands::epoch::handle_cmd(&cmd), TopLevelCmd::Show(cmd) => commands::show::handle_show_cmd(&cmd), TopLevelCmd::Gen(cmd) => commands::generate::gen_handler(&cmd), diff --git a/bin_efo/tests/cli_workflows.rs b/bin_efo/tests/cli_workflows.rs index 10b4262..faaca10 100644 --- a/bin_efo/tests/cli_workflows.rs +++ b/bin_efo/tests/cli_workflows.rs @@ -79,6 +79,8 @@ fn help_version_and_invalid_invocations_follow_cli_conventions() { &["chr", "add", "--help"][..], &["show", "--help"][..], &["migrate", "--help"][..], + &["recover", "--help"][..], + &["lock", "--help"][..], &["gen", "event", "--help"][..], ] { let output = efo(&repo, args); @@ -189,6 +191,10 @@ fn migration_is_dry_run_by_default_and_backs_up_before_commit() { let protected = efo(&repo, &["status"]); assert!(!protected.status.success()); assert!(stderr(&protected).contains("does not yet support repository format 2")); + + let recovery = efo(&repo, &["recover"]); + assert_success(&recovery); + assert!(stdout(&recovery).contains("no recovery is needed")); } #[test] diff --git a/docs/commands.md b/docs/commands.md index 5f8d18f..a16452f 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -12,6 +12,10 @@ parent directories. `efo --help` is the authoritative syntax. Add `--yes` to create a byte-for-byte manifest backup and initialise the version-2 index/worktree. This is an opt-in Phase 4 transition: ordinary commands deliberately refuse format 2 until the staging checkpoint lands. +- `efo recover` deterministically rolls back a prepared replacement or verifies + a committed one. It is safe to repeat. +- `efo lock inspect` reports writer ownership. `efo lock break --yes` removes + an abandoned lock only after explicit confirmation; run `efo recover` next. - `efo status [EPOCH_ID]` shows an epoch summary, tags, and entity counts. - `efo epoch log [-c N]` shows epochs around the current epoch. - `efo epoch next` creates and checks out the next snapshot. It refuses while