feat: add atomic format 2 commits and log
This commit is contained in:
parent
d938e27288
commit
c6442bdeac
|
|
@ -100,8 +100,9 @@ portable release gates.
|
|||
- [x] Add durable single-file transaction journaling, exclusive writer locks,
|
||||
lock inspection/break primitives, and deterministic interrupted-write
|
||||
recovery.
|
||||
- [ ] Extend transactions across multi-file commits and add automatic
|
||||
pre-commit migration rollback.
|
||||
- [x] Extend transactions across ordered multi-file commits with rollback
|
||||
copies and a manifest-last commit point.
|
||||
- [ ] Add automatic pre-commit migration rollback.
|
||||
- [x] Implement worktree/index-aware `status`, `diff`, `stage`, and both restore
|
||||
directions without changing immutable epochs.
|
||||
- [ ] Implement committed epochs, `log`, conflict-safe `revert`, and backed-up
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@
|
|||
pub mod entity_generic;
|
||||
pub mod epoch;
|
||||
pub mod generate;
|
||||
pub mod history;
|
||||
pub mod init;
|
||||
pub mod migrate;
|
||||
pub mod safety;
|
||||
|
|
|
|||
|
|
@ -0,0 +1,63 @@
|
|||
//! Immutable format-2 commit and log commands.
|
||||
|
||||
use std::{fs, path::Path};
|
||||
|
||||
use clap::Args;
|
||||
use lib_efo::{epoch::EpochInfo, workspace::Workspace};
|
||||
|
||||
use crate::error::AppError;
|
||||
|
||||
/// Create an immutable epoch from the index.
|
||||
#[derive(Args, Debug)]
|
||||
pub struct CommitCmd {
|
||||
/// Required explanation stored with the new epoch.
|
||||
#[arg(short, long, required = true)]
|
||||
message: String,
|
||||
}
|
||||
|
||||
/// Options for displaying immutable history.
|
||||
#[derive(Args, Debug)]
|
||||
pub struct LogCmd {
|
||||
/// Maximum number of newest entries to display.
|
||||
#[arg(short, long, default_value_t = 20)]
|
||||
limit: usize,
|
||||
}
|
||||
|
||||
/// Commit staged state through a manifest-last transaction.
|
||||
pub fn commit(command: &CommitCmd) -> Result<(), AppError> {
|
||||
let mut workspace = Workspace::open(Path::new("."))?;
|
||||
let id = workspace.commit(command.message.clone())?;
|
||||
println!("✓ Committed epoch {id}: {}", command.message);
|
||||
println!(" HEAD, index, and worktree are now aligned.");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Display format-2 history newest first.
|
||||
pub fn log(command: &LogCmd) -> Result<(), AppError> {
|
||||
let workspace = Workspace::open(Path::new("."))?;
|
||||
let mut id = Some(workspace.manifest.epoch_id);
|
||||
let mut shown = 0;
|
||||
while let Some(current) = id.filter(|_| shown < command.limit) {
|
||||
let path = Path::new("epoch")
|
||||
.join(current.to_string())
|
||||
.join("epochinfo.json");
|
||||
let epoch: EpochInfo = serde_json::from_slice(&fs::read(&path)?)
|
||||
.map_err(lib_efo::error::StorageError::from)?;
|
||||
let message = if epoch.commit_message.is_empty() {
|
||||
"(legacy snapshot)"
|
||||
} else {
|
||||
&epoch.commit_message
|
||||
};
|
||||
println!(
|
||||
"{} epoch {} {}",
|
||||
if shown == 0 { "*" } else { " " },
|
||||
current,
|
||||
message
|
||||
);
|
||||
id = epoch
|
||||
.parent_epoch
|
||||
.or_else(|| (current.id > 0).then(|| lib_efo::epoch::EpochId::new(current.id - 1)));
|
||||
shown += 1;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
|
@ -32,6 +32,7 @@ use crate::{
|
|||
entity_generic::EntitySubCommands,
|
||||
epoch::cli_epoch::EpochCmd,
|
||||
generate::GenCmd,
|
||||
history::{CommitCmd, LogCmd},
|
||||
init::InitCmd,
|
||||
migrate::MigrateCmd,
|
||||
safety::{LockCmd, RecoverCmd},
|
||||
|
|
@ -86,6 +87,10 @@ enum TopLevelCmd {
|
|||
Stage(StageCmd),
|
||||
/// Restore index or worktree state from its prior layer.
|
||||
Restore(RestoreCmd),
|
||||
/// Create an immutable epoch from staged state.
|
||||
Commit(CommitCmd),
|
||||
/// Show immutable format-2 history newest first.
|
||||
Log(LogCmd),
|
||||
/// Gives a very simple status.
|
||||
Status(StatusCmd),
|
||||
/// Advance or query the current epoch.
|
||||
|
|
@ -171,6 +176,8 @@ fn exec_dispatch(cli: Cli) -> Result<(), AppError> {
|
|||
TopLevelCmd::Diff(cmd) => commands::state::diff(&cmd),
|
||||
TopLevelCmd::Stage(cmd) => commands::state::stage(&cmd),
|
||||
TopLevelCmd::Restore(cmd) => commands::state::restore(&cmd),
|
||||
TopLevelCmd::Commit(cmd) => commands::history::commit(&cmd),
|
||||
TopLevelCmd::Log(cmd) => commands::history::log(&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),
|
||||
|
|
|
|||
|
|
@ -202,11 +202,19 @@ fn migration_is_dry_run_by_default_and_backs_up_before_commit() {
|
|||
let status = stdout(&efo(&repo, &["status"]));
|
||||
assert!(status.contains("Staged changes"));
|
||||
assert!(status.contains("Worktree clean"));
|
||||
assert_success(&efo(&repo, &["commit", "-m", "Add Bryn"]));
|
||||
let log = efo(&repo, &["log"]);
|
||||
assert_success(&log);
|
||||
assert!(stdout(&log).contains("epoch 1 Add Bryn"));
|
||||
assert!(repo.path().join("epoch/1/epochinfo.json").is_file());
|
||||
|
||||
assert_success(&efo(&repo, &["chr", "add", "Cora"]));
|
||||
assert_success(&efo(&repo, &["restore", "--staged", "--all"]));
|
||||
assert_success(&efo(&repo, &["restore", "--worktree", "--all"]));
|
||||
let show = efo(&repo, &["show", "character"]);
|
||||
assert_success(&show);
|
||||
assert!(!stdout(&show).contains("Bryn"));
|
||||
assert!(stdout(&show).contains("Bryn"));
|
||||
assert!(!stdout(&show).contains("Cora"));
|
||||
|
||||
let recovery = efo(&repo, &["recover"]);
|
||||
assert_success(&recovery);
|
||||
|
|
|
|||
|
|
@ -55,6 +55,9 @@ worktree. Use `efo diff`, `efo stage --all` or `efo stage --kind KIND ID...`,
|
|||
and `efo diff --staged` to prepare history. `efo restore --staged ...` copies
|
||||
HEAD into the index; `efo restore --worktree ...` copies the index into the
|
||||
worktree. Both restore modes require either `--all` or an entity kind and IDs.
|
||||
`efo commit -m MESSAGE` refuses unstaged or empty commits, creates an immutable
|
||||
epoch using a manifest-last transaction, and realigns all three layers.
|
||||
`efo log` shows the resulting parent-linked history newest first.
|
||||
|
||||
`efo show all` lists every collection in the current epoch. `show character`,
|
||||
`show town`, `show event`, `show calamity`, and `show blocker` select one
|
||||
|
|
|
|||
|
|
@ -35,6 +35,16 @@ pub struct EpochInfo {
|
|||
#[table(title = "ID")]
|
||||
pub epoch_id: EpochId,
|
||||
|
||||
/// Immutable predecessor in format-2 history.
|
||||
#[serde(default)]
|
||||
#[table(skip)]
|
||||
pub parent_epoch: Option<EpochId>,
|
||||
|
||||
/// User-supplied history message for format-2 commits.
|
||||
#[serde(default)]
|
||||
#[table(skip)]
|
||||
pub commit_message: String,
|
||||
|
||||
/// RNG seed that was used to generate randomised data for
|
||||
/// this epoch. Keeping it in the file guarantees repeatable
|
||||
/// behaviour when replaying the same epoch.
|
||||
|
|
@ -80,6 +90,8 @@ impl Default for EpochInfo {
|
|||
fn default() -> Self {
|
||||
Self {
|
||||
epoch_id: EpochId::new(0),
|
||||
parent_epoch: None,
|
||||
commit_message: String::new(),
|
||||
rng_seed: 0,
|
||||
tags: TagList::new(),
|
||||
summary: String::new(),
|
||||
|
|
|
|||
|
|
@ -32,10 +32,19 @@ pub struct RepositoryLock {
|
|||
/// Durable record for an interrupted file replacement.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
struct TransactionJournal {
|
||||
/// Destination path relative to `.efo`'s parent.
|
||||
/// Ordered replacements; the manifest must be supplied last.
|
||||
entries: Vec<TransactionEntry>,
|
||||
}
|
||||
|
||||
/// One recoverable file replacement.
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
struct TransactionEntry {
|
||||
/// Destination path relative to repository root.
|
||||
destination: PathBuf,
|
||||
/// Prepared replacement path relative to `.efo`'s parent.
|
||||
/// Prepared replacement path relative to repository root.
|
||||
temporary: PathBuf,
|
||||
/// Optional prior content used for rollback.
|
||||
backup: Option<PathBuf>,
|
||||
/// Checksum of the complete replacement.
|
||||
new_checksum: String,
|
||||
}
|
||||
|
|
@ -152,36 +161,59 @@ pub fn replace_file(
|
|||
destination: &Path,
|
||||
bytes: &[u8],
|
||||
command: &str,
|
||||
) -> Result<(), TransactionError> {
|
||||
replace_files(
|
||||
root,
|
||||
&[(destination.to_path_buf(), bytes.to_vec())],
|
||||
command,
|
||||
)
|
||||
}
|
||||
|
||||
/// Replace several files under one lock and journal, in the supplied order.
|
||||
pub fn replace_files(
|
||||
root: &Path,
|
||||
replacements: &[(PathBuf, Vec<u8>)],
|
||||
command: &str,
|
||||
) -> Result<(), TransactionError> {
|
||||
let _lock = RepositoryLock::acquire(root, command)?;
|
||||
recover_unlocked(root)?;
|
||||
let workspace = root.join(".efo");
|
||||
let journal_path = workspace.join("transaction.json");
|
||||
let temporary = workspace.join(format!("transaction-{}.tmp", std::process::id()));
|
||||
let mut file =
|
||||
File::create(&temporary).map_err(|source| io_error(temporary.clone(), source))?;
|
||||
file.write_all(bytes)
|
||||
.and_then(|_| file.sync_all())
|
||||
.map_err(|source| io_error(temporary.clone(), source))?;
|
||||
let destination_relative = destination.strip_prefix(root).map_err(|_| {
|
||||
TransactionError::Ambiguous(format!(
|
||||
"destination `{}` is outside repository `{}`",
|
||||
destination.display(),
|
||||
root.display()
|
||||
))
|
||||
})?;
|
||||
let journal = TransactionJournal {
|
||||
destination: destination_relative.to_path_buf(),
|
||||
temporary: temporary
|
||||
.strip_prefix(root)
|
||||
.map_err(|_| TransactionError::Ambiguous("temporary path escaped repository".into()))?
|
||||
.to_path_buf(),
|
||||
new_checksum: checksum(bytes),
|
||||
};
|
||||
let mut entries = Vec::new();
|
||||
for (index, (destination, bytes)) in replacements.iter().enumerate() {
|
||||
let temporary = workspace.join(format!("transaction-{index}.tmp"));
|
||||
let backup_path = workspace.join(format!("transaction-{index}.bak"));
|
||||
write_bytes_synced(&temporary, bytes)?;
|
||||
let backup = if destination.exists() {
|
||||
write_bytes_synced(
|
||||
&backup_path,
|
||||
&fs::read(destination).map_err(|source| io_error(destination.clone(), source))?,
|
||||
)?;
|
||||
Some(
|
||||
backup_path
|
||||
.strip_prefix(root)
|
||||
.map_err(|_| TransactionError::Ambiguous("backup escaped repository".into()))?
|
||||
.to_path_buf(),
|
||||
)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
entries.push(TransactionEntry {
|
||||
destination: relative(root, destination)?,
|
||||
temporary: relative(root, &temporary)?,
|
||||
backup,
|
||||
new_checksum: checksum(bytes),
|
||||
});
|
||||
}
|
||||
let journal = TransactionJournal { entries };
|
||||
write_json_synced(&journal_path, &journal)?;
|
||||
fs::rename(&temporary, destination)
|
||||
.map_err(|source| io_error(destination.to_path_buf(), source))?;
|
||||
sync_directory(destination.parent().unwrap_or(root))?;
|
||||
for entry in &journal.entries {
|
||||
let destination = root.join(&entry.destination);
|
||||
fs::rename(root.join(&entry.temporary), &destination)
|
||||
.map_err(|source| io_error(destination.clone(), source))?;
|
||||
sync_directory(destination.parent().unwrap_or(root))?;
|
||||
}
|
||||
cleanup_transaction(root, &journal)?;
|
||||
fs::remove_file(&journal_path).map_err(|source| io_error(journal_path.clone(), source))?;
|
||||
sync_directory(&workspace)
|
||||
}
|
||||
|
|
@ -204,31 +236,59 @@ fn recover_unlocked(root: &Path) -> Result<RecoveryOutcome, TransactionError> {
|
|||
path: journal_path.clone(),
|
||||
source,
|
||||
})?;
|
||||
let destination = root.join(&journal.destination);
|
||||
let temporary = root.join(&journal.temporary);
|
||||
let outcome = if temporary.exists() {
|
||||
fs::remove_file(&temporary).map_err(|source| io_error(temporary, source))?;
|
||||
RecoveryOutcome::RolledBack
|
||||
} else if destination.exists() {
|
||||
let current =
|
||||
fs::read(&destination).map_err(|source| io_error(destination.clone(), source))?;
|
||||
if checksum(¤t) != journal.new_checksum {
|
||||
return Err(TransactionError::Ambiguous(format!(
|
||||
"`{}` matches neither prepared nor committed content",
|
||||
destination.display()
|
||||
)));
|
||||
}
|
||||
let committed = journal.entries.iter().all(|entry| {
|
||||
fs::read(root.join(&entry.destination))
|
||||
.ok()
|
||||
.is_some_and(|bytes| checksum(&bytes) == entry.new_checksum)
|
||||
});
|
||||
let outcome = if committed {
|
||||
RecoveryOutcome::Completed
|
||||
} else {
|
||||
return Err(TransactionError::Ambiguous(
|
||||
"both prepared and destination files are missing".to_owned(),
|
||||
));
|
||||
for entry in journal.entries.iter().rev() {
|
||||
let destination = root.join(&entry.destination);
|
||||
if let Some(backup) = &entry.backup {
|
||||
fs::rename(root.join(backup), &destination)
|
||||
.map_err(|source| io_error(destination, source))?;
|
||||
} else if destination.exists() {
|
||||
fs::remove_file(&destination).map_err(|source| io_error(destination, source))?;
|
||||
}
|
||||
}
|
||||
RecoveryOutcome::RolledBack
|
||||
};
|
||||
cleanup_transaction(root, &journal)?;
|
||||
fs::remove_file(&journal_path).map_err(|source| io_error(journal_path.clone(), source))?;
|
||||
sync_directory(journal_path.parent().unwrap_or(root))?;
|
||||
Ok(outcome)
|
||||
}
|
||||
|
||||
/// Remove prepared and backup files after commit or recovery.
|
||||
fn cleanup_transaction(root: &Path, journal: &TransactionJournal) -> Result<(), TransactionError> {
|
||||
for entry in &journal.entries {
|
||||
for relative in std::iter::once(&entry.temporary).chain(entry.backup.iter()) {
|
||||
let path = root.join(relative);
|
||||
if path.exists() {
|
||||
fs::remove_file(&path).map_err(|source| io_error(path, source))?;
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Convert an absolute repository path into a journal-safe relative path.
|
||||
fn relative(root: &Path, path: &Path) -> Result<PathBuf, TransactionError> {
|
||||
path.strip_prefix(root).map(Path::to_path_buf).map_err(|_| {
|
||||
TransactionError::Ambiguous(format!("path `{}` escaped repository", path.display()))
|
||||
})
|
||||
}
|
||||
|
||||
/// Write and flush raw transaction data.
|
||||
fn write_bytes_synced(path: &Path, bytes: &[u8]) -> Result<(), TransactionError> {
|
||||
let mut file = File::create(path).map_err(|source| io_error(path.to_path_buf(), source))?;
|
||||
file.write_all(bytes)
|
||||
.and_then(|_| file.sync_all())
|
||||
.map_err(|source| io_error(path.to_path_buf(), source))
|
||||
}
|
||||
|
||||
/// Write durable JSON metadata before a transaction commit point.
|
||||
fn write_json_synced<T: Serialize>(path: &Path, value: &T) -> Result<(), TransactionError> {
|
||||
let bytes = serde_json::to_vec_pretty(value).map_err(|source| TransactionError::Json {
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ use crate::{
|
|||
DetectedManifest, FormatError, RepositoryManifest, RepositorySnapshot, detect_manifest,
|
||||
},
|
||||
stats::EntityType,
|
||||
transaction::{TransactionError, replace_file},
|
||||
transaction::{TransactionError, replace_file, replace_files},
|
||||
};
|
||||
|
||||
/// A validated format-2 repository and its three state layers.
|
||||
|
|
@ -65,6 +65,12 @@ pub enum WorkspaceError {
|
|||
/// A requested entity selector did not resolve safely.
|
||||
#[error("entity selector `{0}` did not match exactly one entity")]
|
||||
Selector(String),
|
||||
/// A commit would discard unstaged edits.
|
||||
#[error("worktree has unstaged changes; stage them or restore the worktree before committing")]
|
||||
Unstaged,
|
||||
/// The index is identical to HEAD.
|
||||
#[error("index has no changes to commit")]
|
||||
EmptyCommit,
|
||||
/// Transaction safety rejected the write.
|
||||
#[error(transparent)]
|
||||
Transaction(#[from] TransactionError),
|
||||
|
|
@ -179,6 +185,53 @@ impl Workspace {
|
|||
pub fn save_index(&self, command: &str) -> Result<(), WorkspaceError> {
|
||||
save(&self.root, ".efo/index.json", &self.index, command)
|
||||
}
|
||||
|
||||
/// Create an immutable epoch and advance all state layers atomically.
|
||||
pub fn commit(&mut self, message: String) -> Result<crate::epoch::EpochId, WorkspaceError> {
|
||||
if self.has_unstaged_changes() {
|
||||
return Err(WorkspaceError::Unstaged);
|
||||
}
|
||||
if !self.has_staged_changes() {
|
||||
return Err(WorkspaceError::EmptyCommit);
|
||||
}
|
||||
let new_id = self.manifest.next_epoch_id;
|
||||
let mut world = self.index.world.clone();
|
||||
world.parent_epoch = Some(self.manifest.epoch_id);
|
||||
world.epoch_id = new_id;
|
||||
world.commit_message = message;
|
||||
let mut manifest = self.manifest.clone();
|
||||
manifest.epoch_id = new_id;
|
||||
manifest.next_epoch_id =
|
||||
crate::epoch::EpochId::new(new_id.id.checked_add(1).ok_or_else(|| {
|
||||
WorkspaceError::Inconsistent("epoch ID allocator is exhausted".into())
|
||||
})?);
|
||||
let snapshot = RepositorySnapshot::new(manifest.repository_id, new_id, world.clone());
|
||||
let epoch_path = self.root.join(format!("epoch/{new_id}/epochinfo.json"));
|
||||
fs::create_dir_all(
|
||||
epoch_path
|
||||
.parent()
|
||||
.ok_or_else(|| WorkspaceError::Inconsistent("epoch path has no parent".into()))?,
|
||||
)
|
||||
.map_err(|source| io(&epoch_path, source))?;
|
||||
let replacements = [
|
||||
(epoch_path, encode(&world, "epoch snapshot")?),
|
||||
(
|
||||
self.root.join(".efo/index.json"),
|
||||
encode(&snapshot, "index")?,
|
||||
),
|
||||
(
|
||||
self.root.join(".efo/worktree.json"),
|
||||
encode(&snapshot, "worktree")?,
|
||||
),
|
||||
(self.root.join(".epoch"), encode(&manifest, "manifest")?),
|
||||
];
|
||||
replace_files(&self.root, &replacements, "commit")?;
|
||||
self.manifest = manifest;
|
||||
self.head = world;
|
||||
self.index = snapshot.clone();
|
||||
self.worktree = snapshot;
|
||||
Ok(new_id)
|
||||
}
|
||||
}
|
||||
|
||||
/// Copy selected collection entries with delete semantics.
|
||||
|
|
@ -260,6 +313,14 @@ fn save<T: Serialize>(
|
|||
Ok(())
|
||||
}
|
||||
|
||||
/// Encode transaction content with a meaningful synthetic path.
|
||||
fn encode<T: Serialize>(value: &T, label: &str) -> Result<Vec<u8>, WorkspaceError> {
|
||||
serde_json::to_vec_pretty(value).map_err(|source| WorkspaceError::Json {
|
||||
path: PathBuf::from(label),
|
||||
source,
|
||||
})
|
||||
}
|
||||
|
||||
/// Attach the attempted path to an I/O error.
|
||||
fn io(path: &Path, source: std::io::Error) -> WorkspaceError {
|
||||
WorkspaceError::Io {
|
||||
|
|
|
|||
|
|
@ -71,3 +71,34 @@ fn entity_staging_and_both_restore_directions_are_isolated() {
|
|||
assert!(!workspace.has_unstaged_changes());
|
||||
assert!(workspace.worktree.world.characters.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn commit_creates_immutable_history_and_advances_all_layers() {
|
||||
let directory = migrated_repository();
|
||||
let mut workspace = Workspace::open(directory.path()).expect("workspace");
|
||||
let mut aria = Entity::default();
|
||||
aria.name = "Aria".into();
|
||||
aria.entity_type = EntityType::Character;
|
||||
workspace.worktree.world.characters.push(aria);
|
||||
workspace.save_worktree("test edit").expect("worktree");
|
||||
let mut workspace = Workspace::open(directory.path()).expect("changed workspace");
|
||||
workspace.stage_all().expect("stage");
|
||||
|
||||
let id = workspace.commit("Add Aria".into()).expect("commit");
|
||||
|
||||
assert_eq!(id, EpochId::new(1));
|
||||
assert_eq!(workspace.manifest.next_epoch_id, EpochId::new(2));
|
||||
assert!(!workspace.has_staged_changes());
|
||||
assert!(!workspace.has_unstaged_changes());
|
||||
let committed: EpochInfo = serde_json::from_slice(
|
||||
&fs::read(directory.path().join("epoch/1/epochinfo.json")).expect("epoch 1"),
|
||||
)
|
||||
.expect("committed epoch");
|
||||
assert_eq!(committed.parent_epoch, Some(EpochId::new(0)));
|
||||
assert_eq!(committed.commit_message, "Add Aria");
|
||||
let original: EpochInfo = serde_json::from_slice(
|
||||
&fs::read(directory.path().join("epoch/0/epochinfo.json")).expect("epoch 0"),
|
||||
)
|
||||
.expect("original epoch");
|
||||
assert!(original.characters.is_empty());
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue