1use std::collections::{HashMap, HashSet};
4use std::fs::OpenOptions;
5use std::io::Write;
6use std::path::{Path, PathBuf};
7use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
8
9use crate::NbClient;
10use crate::error::NbError;
11use crate::fingerprint::{self, Fingerprint};
12use crate::gate;
13use crate::git;
14use crate::lines::{
15 apply_line_edits, apply_substring, require_contiguous_body, splice_body, splice_title,
16};
17use crate::parser::{DocumentKind, NoteDocument, ParseContext, parse};
18use crate::types::{CommitOutcome, LineEdit, NoteTarget, Occurrence, OpOutcome};
19
20pub struct Transaction {
22 client: NbClient,
23 notebook: String,
24 plan: Vec<PlanOp>,
25 gate_timeout: Duration,
26}
27
28#[derive(Debug, Clone)]
29enum PlanOp {
30 AddNote {
31 path: String,
32 title: Option<String>,
33 content: String,
34 tags: Vec<String>,
35 },
36 AddTodo {
37 path: String,
38 title: String,
39 description: Option<String>,
40 tasks: Vec<String>,
41 tags: Vec<String>,
42 },
43 AddBookmark {
44 path: String,
45 url: String,
46 title: Option<String>,
47 tags: Vec<String>,
48 comment: Option<String>,
49 },
50 AddFolder {
51 path: String,
52 },
53 DeleteNote {
54 target: NoteTarget,
55 },
56 MoveNote {
57 target: NoteTarget,
58 destination: String,
59 },
60 MarkTaskDone {
61 target: NoteTarget,
62 task_number: Option<u32>,
63 },
64 UnmarkTaskDone {
65 target: NoteTarget,
66 task_number: Option<u32>,
67 },
68 ReplaceNoteBody {
69 target: NoteTarget,
70 new_body: String,
71 fingerprint: Fingerprint,
72 },
73 EditNoteSubstring {
74 target: NoteTarget,
75 pattern: String,
76 replacement: String,
77 occurrence: Occurrence,
78 expected_count: u32,
79 fingerprint: Option<Fingerprint>,
80 },
81 EditNoteLines {
82 target: NoteTarget,
83 edits: Vec<LineEdit>,
84 },
85 RetitleNote {
86 target: NoteTarget,
87 title: String,
88 },
89 EditNoteTags {
90 target: NoteTarget,
91 add: Vec<String>,
92 remove: Vec<String>,
93 },
94}
95
96#[derive(Debug, Clone)]
97enum VirtualNode {
98 File(Vec<u8>),
99 Folder,
100}
101
102struct VirtualTree {
103 nodes: HashMap<String, VirtualNode>,
105}
106
107impl VirtualTree {
108 fn from_disk(root: &Path) -> Result<Self, NbError> {
109 let mut nodes = HashMap::new();
110 let paths = git::list_notebook_paths(root)?;
111 for rel in paths {
112 let key = normalize_rel(&rel);
113 let abs = root.join(&rel);
114 let meta = std::fs::symlink_metadata(&abs).map_err(|e| NbError::Io {
115 path: abs.clone(),
116 source: e.into(),
117 })?;
118 if meta.file_type().is_symlink() {
119 return Err(NbError::UnsupportedStructure {
120 reason: format!(
121 "notebook path `{key}` is a symlink; transactions refuse symlink snapshot/materialization"
122 ),
123 });
124 }
125 if meta.is_dir() {
126 nodes.insert(key, VirtualNode::Folder);
127 } else if meta.is_file() {
128 let bytes = std::fs::read(&abs).map_err(|e| NbError::Io {
129 path: abs,
130 source: e.into(),
131 })?;
132 if let Some(parent) = parent_path(&key) {
137 let mut acc = String::new();
138 for part in parent.split('/').filter(|p| !p.is_empty()) {
139 if !acc.is_empty() {
140 acc.push('/');
141 }
142 acc.push_str(part);
143 nodes.entry(acc.clone()).or_insert(VirtualNode::Folder);
144 }
145 }
146 nodes.insert(key, VirtualNode::File(bytes));
147 }
148 }
149 Ok(Self { nodes })
150 }
151
152 fn exists(&self, path: &str) -> bool {
153 self.nodes.contains_key(path)
154 }
155
156 fn get_file(&self, path: &str) -> Option<&[u8]> {
157 match self.nodes.get(path) {
158 Some(VirtualNode::File(b)) => Some(b),
159 _ => None,
160 }
161 }
162
163 fn insert_file(&mut self, path: String, bytes: Vec<u8>) {
164 if let Some(parent) = parent_path(&path) {
166 self.ensure_folder_chain(&parent);
167 }
168 self.nodes.insert(path, VirtualNode::File(bytes));
169 }
170
171 fn insert_folder(&mut self, path: String) {
172 self.ensure_folder_chain(&path);
173 self.nodes.insert(path, VirtualNode::Folder);
174 }
175
176 fn ensure_folder_chain(&mut self, path: &str) {
177 let mut acc = String::new();
178 for part in path.split('/').filter(|p| !p.is_empty()) {
179 if !acc.is_empty() {
180 acc.push('/');
181 }
182 acc.push_str(part);
183 self.nodes.entry(acc.clone()).or_insert(VirtualNode::Folder);
184 }
185 }
186
187 fn remove(&mut self, path: &str) {
188 self.nodes.remove(path);
189 }
190
191 fn rename(&mut self, from: &str, to: &str) -> Result<(), NbError> {
192 let node = self.nodes.remove(from).ok_or_else(|| NbError::NotFound {
193 selector: from.to_string(),
194 })?;
195 if let Some(parent) = parent_path(to) {
196 self.ensure_folder_chain(&parent);
197 }
198 self.nodes.insert(to.to_string(), node);
199 Ok(())
200 }
201}
202
203impl Transaction {
204 pub(crate) fn new(client: NbClient, notebook: String, gate_timeout: Duration) -> Self {
205 Self {
206 client,
207 notebook,
208 plan: Vec::new(),
209 gate_timeout,
210 }
211 }
212
213 pub fn add_note(
214 &mut self,
215 path: &str,
216 title: Option<&str>,
217 content: &str,
218 tags: &[String],
219 ) -> Result<(), NbError> {
220 let path = validate_create_path(path, true)?;
221 if let Some(t) = title
222 && let Some(heading) = crate::validate::detect_duplicate_title_heading(t, content)
223 {
224 return Err(NbError::DuplicateTitleHeading {
225 title: t.to_string(),
226 heading,
227 });
228 }
229 self.plan.push(PlanOp::AddNote {
230 path,
231 title: title.map(str::to_string),
232 content: content.to_string(),
233 tags: tags.to_vec(),
234 });
235 Ok(())
236 }
237
238 pub fn add_todo(
239 &mut self,
240 path: &str,
241 title: &str,
242 description: Option<&str>,
243 tasks: &[String],
244 tags: &[String],
245 ) -> Result<(), NbError> {
246 let path = validate_create_path(path, true)?;
247 if title.trim().is_empty() {
248 return Err(NbError::ValidationError {
249 reason: "todo title must not be empty".into(),
250 location: None,
251 });
252 }
253 self.plan.push(PlanOp::AddTodo {
254 path,
255 title: title.to_string(),
256 description: description.map(str::to_string),
257 tasks: tasks.to_vec(),
258 tags: tags.to_vec(),
259 });
260 Ok(())
261 }
262
263 pub fn add_bookmark(
264 &mut self,
265 path: &str,
266 url: &str,
267 title: Option<&str>,
268 tags: &[String],
269 comment: Option<&str>,
270 ) -> Result<(), NbError> {
271 let path = validate_create_path(path, true)?;
272 if url.trim().is_empty() {
273 return Err(NbError::ValidationError {
274 reason: "bookmark url must not be empty".into(),
275 location: None,
276 });
277 }
278 self.plan.push(PlanOp::AddBookmark {
279 path,
280 url: url.to_string(),
281 title: title.map(str::to_string),
282 tags: tags.to_vec(),
283 comment: comment.map(str::to_string),
284 });
285 Ok(())
286 }
287
288 pub fn add_folder(&mut self, path: &str) -> Result<(), NbError> {
289 let path = validate_create_path(path, false)?;
290 self.plan.push(PlanOp::AddFolder { path });
291 Ok(())
292 }
293
294 pub fn delete_note(&mut self, target: NoteTarget) -> Result<(), NbError> {
295 validate_target(&target)?;
296 self.plan.push(PlanOp::DeleteNote { target });
297 Ok(())
298 }
299
300 pub fn move_note(&mut self, target: NoteTarget, destination: &str) -> Result<(), NbError> {
301 validate_target(&target)?;
302 crate::validate::validate_destination(destination)?;
303 let into_folder = destination.trim_end().ends_with('/');
307 let mut destination = normalize_rel(destination);
308 if destination.is_empty() || destination.contains("..") {
309 return Err(NbError::ValidationError {
310 reason: "invalid move destination".into(),
311 location: None,
312 });
313 }
314 if into_folder {
315 destination.push('/');
316 }
317 self.plan.push(PlanOp::MoveNote {
318 target,
319 destination,
320 });
321 Ok(())
322 }
323
324 pub fn mark_task_done(
325 &mut self,
326 target: NoteTarget,
327 task_number: Option<u32>,
328 ) -> Result<(), NbError> {
329 validate_target(&target)?;
330 self.plan.push(PlanOp::MarkTaskDone {
331 target,
332 task_number,
333 });
334 Ok(())
335 }
336
337 pub fn unmark_task_done(
338 &mut self,
339 target: NoteTarget,
340 task_number: Option<u32>,
341 ) -> Result<(), NbError> {
342 validate_target(&target)?;
343 self.plan.push(PlanOp::UnmarkTaskDone {
344 target,
345 task_number,
346 });
347 Ok(())
348 }
349
350 pub fn replace_note_body(
351 &mut self,
352 target: NoteTarget,
353 new_body: &str,
354 fingerprint: Fingerprint,
355 ) -> Result<(), NbError> {
356 validate_target(&target)?;
357 self.plan.push(PlanOp::ReplaceNoteBody {
358 target,
359 new_body: new_body.to_string(),
360 fingerprint,
361 });
362 Ok(())
363 }
364
365 pub fn edit_note_substring(
366 &mut self,
367 target: NoteTarget,
368 pattern: &str,
369 replacement: &str,
370 occurrence: Occurrence,
371 expected_count: u32,
372 fingerprint: Option<Fingerprint>,
373 ) -> Result<(), NbError> {
374 validate_target(&target)?;
375 if pattern.is_empty() {
376 return Err(NbError::EmptySubstringPattern);
377 }
378 self.plan.push(PlanOp::EditNoteSubstring {
379 target,
380 pattern: pattern.to_string(),
381 replacement: replacement.to_string(),
382 occurrence,
383 expected_count,
384 fingerprint,
385 });
386 Ok(())
387 }
388
389 pub fn edit_note_lines(
390 &mut self,
391 target: NoteTarget,
392 edits: Vec<LineEdit>,
393 ) -> Result<(), NbError> {
394 validate_target(&target)?;
395 if edits.is_empty() {
396 return Err(NbError::ValidationError {
397 reason: "edit_note_lines requires a non-empty edits batch".into(),
398 location: None,
399 });
400 }
401 self.plan.push(PlanOp::EditNoteLines { target, edits });
402 Ok(())
403 }
404
405 pub fn retitle_note(&mut self, target: NoteTarget, title: &str) -> Result<(), NbError> {
406 validate_target(&target)?;
407 self.plan.push(PlanOp::RetitleNote {
408 target,
409 title: title.to_string(),
410 });
411 Ok(())
412 }
413
414 pub fn edit_note_tags(
415 &mut self,
416 target: NoteTarget,
417 add: &[String],
418 remove: &[String],
419 ) -> Result<(), NbError> {
420 validate_target(&target)?;
421 let add_set: HashSet<&str> = add.iter().map(|s| s.trim_start_matches('#')).collect();
422 for r in remove {
423 let key = r.trim_start_matches('#');
424 if add_set.contains(key) {
425 return Err(NbError::ValidationError {
426 reason: format!("contradictory tag add/remove for `{key}`"),
427 location: None,
428 });
429 }
430 }
431 self.plan.push(PlanOp::EditNoteTags {
432 target,
433 add: add.to_vec(),
434 remove: remove.to_vec(),
435 });
436 Ok(())
437 }
438
439 pub async fn commit(self) -> Result<CommitOutcome, NbError> {
441 let notebook_root = self
444 .client
445 .show_notebook_path_unguarded(Some(&self.notebook))
446 .await?;
447 let gate_key = gate::git_common_dir_realpath(¬ebook_root)?;
448 let _hold = gate::acquire_notebook(gate_key, self.gate_timeout, false).await?;
449
450 reap_stale_index_lock(¬ebook_root, self.gate_timeout);
453
454 if git::notebook_is_dirty(¬ebook_root)? {
455 return Err(NbError::DirtyBaseline {
456 guidance: "commit or clean the notebook worktree/index before Transaction::commit"
457 .into(),
458 });
459 }
460
461 let pre_revision = git::notebook_head(¬ebook_root)?;
462 if self.plan.is_empty() {
463 return Ok(CommitOutcome {
464 commit_created: false,
465 revision_id: None,
466 pre_revision,
467 ops: Vec::new(),
468 });
469 }
470
471 let ignored_existing: HashSet<String> = git::list_ignored_paths(¬ebook_root)?
472 .into_iter()
473 .map(|p| normalize_rel(&p))
474 .collect();
475 let mut tree = VirtualTree::from_disk(¬ebook_root)?;
476 let mut op_meta: Vec<OpMeta> = Vec::with_capacity(self.plan.len());
477 let mut effects = PlanEffects::default();
478 let snapshot_keys: HashSet<String> = tree.nodes.keys().cloned().collect();
481
482 for (index, op) in self.plan.iter().enumerate() {
483 match validate_and_apply_virtual(
484 &self.notebook,
485 ¬ebook_root,
486 &mut tree,
487 &ignored_existing,
488 op,
489 index,
490 &mut effects,
491 ) {
492 Ok(meta) => op_meta.push(meta),
493 Err(err) => {
494 return Err(annotate_plan_index(err, index as u32));
495 }
496 }
497 }
498
499 #[cfg(feature = "testing")]
500 if std::env::var_os("NB_API_SIMULATE_EXTERNAL_WRITER").is_some() {
501 simulate_external_writer(¬ebook_root)?;
505 }
506
507 let baseline_on_disk: HashSet<String> = {
510 let mut s: HashSet<String> = git::list_notebook_paths(¬ebook_root)?
511 .into_iter()
512 .map(|p| normalize_rel(&p))
513 .collect();
514 s.extend(ignored_existing.iter().cloned());
515 s
516 };
517
518 let mut force_paths: Vec<String> = tree
523 .nodes
524 .iter()
525 .filter_map(|(p, n)| match n {
526 VirtualNode::File(_) => Some(p.clone()),
527 VirtualNode::Folder => None,
528 })
529 .collect();
530 for meta in &op_meta {
531 for edit in &meta.index_edits {
532 if !force_paths.iter().any(|p| p == &edit.file_rel) {
533 force_paths.push(edit.file_rel.clone());
534 }
535 }
536 }
537
538 let baseline_dirs = existing_dirs_under(¬ebook_root);
541
542 let apply_result = async {
548 materialize_tree(¬ebook_root, &tree, &effects, &snapshot_keys)?;
549 let mut pending: Vec<(u32, PendingIndexEdit)> = Vec::new();
550 for (i, meta) in op_meta.iter().enumerate() {
551 for edit in &meta.index_edits {
552 pending.push((i as u32, edit.clone()));
553 }
554 }
555 let placements = if pending.is_empty() {
556 Vec::new()
557 } else {
558 let _lock = acquire_index_lock(¬ebook_root, self.gate_timeout).await?;
559 let placements = apply_index_edits(¬ebook_root, &pending, self.gate_timeout)?;
560 drop(_lock);
561 placements
562 };
563 let created = git::notebook_commit_all(
564 ¬ebook_root,
565 &format!("nb-api transaction ({} ops)", self.plan.len()),
566 &force_paths,
567 )?;
568 Ok::<_, NbError>((created, placements))
569 }
570 .await;
571
572 match apply_result {
573 Ok((created, placements)) => {
574 let revision_id = if created {
575 match git::notebook_head(¬ebook_root) {
576 Ok(head) => Some(head),
577 Err(_) => {
578 return Err(NbError::IndeterminateCommit {
579 pre_revision,
580 post_revision_observed: None,
581 guidance: "git commit may have succeeded but HEAD could not be re-read; do not retry blindly".into(),
582 });
583 }
584 }
585 } else {
586 None
587 };
588 let ops = op_meta
589 .into_iter()
590 .enumerate()
591 .map(|(i, meta)| {
592 let (selector, numeric_id) =
600 match placements.iter().rev().find(|p| p.op_index == i as u32) {
601 Some(p) => (
602 Some(numeric_selector(&self.notebook, &p.folder, p.id)),
603 Some(p.id),
604 ),
605 None => (
606 meta.selector,
607 meta.path
608 .as_deref()
609 .and_then(|p| index_id_on_disk(¬ebook_root, p)),
610 ),
611 };
612 OpOutcome {
613 index: i as u32,
614 path: meta.path,
615 selector,
616 numeric_id,
617 noop: meta.noop,
618 fingerprint: meta.fingerprint,
619 }
620 })
621 .collect();
622 Ok(CommitOutcome {
623 commit_created: created,
624 revision_id,
625 pre_revision,
626 ops,
627 })
628 }
629 Err(err) => {
630 let post = git::notebook_head(¬ebook_root).ok();
631 if post.as_deref().is_some_and(|h| h != pre_revision.as_str()) {
632 return Err(NbError::IndeterminateCommit {
633 pre_revision,
634 post_revision_observed: post,
635 guidance: "checkpoint may have completed; re-read HEAD/status and do not retry the same plan blindly".into(),
636 });
637 }
638 let owned_new: Vec<String> = force_paths
643 .into_iter()
644 .filter(|p| !baseline_on_disk.contains(p))
645 .filter(|p| !baseline_dirs.contains(p))
646 .collect();
647 match try_restore(¬ebook_root, &pre_revision, &owned_new, &baseline_dirs) {
648 Ok(()) => Err(err),
649 Err(recovery) => Err(recovery),
650 }
651 }
652 }
653 }
654}
655
656fn existing_dirs_under(notebook_root: &Path) -> HashSet<String> {
659 let mut dirs = HashSet::new();
660 fn walk(base: &Path, rel: &Path, out: &mut HashSet<String>) {
661 let entries = match std::fs::read_dir(base) {
662 Ok(e) => e,
663 Err(_) => return,
664 };
665 for entry in entries.flatten() {
666 let name = entry.file_name();
667 if name == ".git" {
668 continue;
669 }
670 let Ok(ft) = entry.file_type() else {
671 continue;
672 };
673 if ft.is_symlink() || !ft.is_dir() {
675 continue;
676 }
677 let child_rel = if rel.as_os_str().is_empty() {
678 PathBuf::from(&name)
679 } else {
680 rel.join(&name)
681 };
682 let key = child_rel.to_string_lossy().replace('\\', "/");
683 out.insert(key);
684 walk(&entry.path(), &child_rel, out);
685 }
686 }
687 walk(notebook_root, Path::new(""), &mut dirs);
688 dirs
689}
690
691fn try_restore(
692 notebook_root: &Path,
693 pre_revision: &str,
694 remove_new_owned: &[String],
695 baseline_dirs: &HashSet<String>,
696) -> Result<(), NbError> {
697 if let Err(e) = git::notebook_reset_clean(notebook_root, pre_revision) {
698 let post = git::notebook_head(notebook_root).ok();
699 let status = git::notebook_status_porcelain(notebook_root).ok();
700 return Err(NbError::RecoveryRequired {
701 pre_revision: pre_revision.to_string(),
702 post_revision_observed: post,
703 status_observed: status,
704 preserved_paths: Some(remove_new_owned.to_vec()),
705 guidance: format!(
706 "cleanup after failed commit could not be verified; inspect HEAD/status before retry. underlying: {e}"
707 ),
708 });
709 }
710 for d in baseline_dirs {
714 let abs = notebook_root.join(d);
715 if !abs.exists()
716 && let Err(e) = std::fs::create_dir_all(&abs)
717 {
718 return Err(NbError::RecoveryRequired {
719 pre_revision: pre_revision.to_string(),
720 post_revision_observed: git::notebook_head(notebook_root).ok(),
721 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
722 preserved_paths: Some(vec![d.clone()]),
723 guidance: format!(
724 "failed to restore baseline directory `{d}` after cleanup; do not retry blindly. underlying: {e}"
725 ),
726 });
727 }
728 }
729 let mut remaining = Vec::new();
732 for rel in remove_new_owned {
733 let abs = notebook_root.join(rel);
734 match std::fs::symlink_metadata(&abs) {
735 Ok(meta) if meta.file_type().is_symlink() || meta.is_file() => {
736 if let Err(e) = std::fs::remove_file(&abs) {
737 remaining.push(format!("{rel} ({e})"));
738 }
739 }
740 Ok(meta) if meta.is_dir() => {
741 if let Err(e) = std::fs::remove_dir_all(&abs) {
742 remaining.push(format!("{rel} ({e})"));
743 }
744 }
745 Ok(_) => {}
746 Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
747 Err(e) => remaining.push(format!("{rel} ({e})")),
748 }
749 if let Some(parent) = parent_path(rel) {
752 let mut cur = parent;
753 loop {
754 if baseline_dirs.contains(&cur) {
755 break;
756 }
757 let p = notebook_root.join(&cur);
758 match std::fs::remove_dir(&p) {
759 Ok(()) => {}
760 Err(_) => break,
761 }
762 match parent_path(&cur) {
763 Some(next) => cur = next,
764 None => break,
765 }
766 }
767 }
768 }
769 if !remaining.is_empty() {
770 return Err(NbError::RecoveryRequired {
771 pre_revision: pre_revision.to_string(),
772 post_revision_observed: git::notebook_head(notebook_root).ok(),
773 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
774 preserved_paths: Some(remaining),
775 guidance: "failed to remove transaction-owned outputs after aborted commit; do not retry blindly".into(),
776 });
777 }
778 let mut still_present = Vec::new();
780 for rel in remove_new_owned {
781 if notebook_root.join(rel).exists() {
782 still_present.push(rel.clone());
783 }
784 }
785 let head = match restore_verify_head(notebook_root) {
786 Ok(h) => h,
787 Err(e) => {
788 return Err(NbError::RecoveryRequired {
789 pre_revision: pre_revision.to_string(),
790 post_revision_observed: None,
791 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
792 preserved_paths: if still_present.is_empty() {
793 None
794 } else {
795 Some(still_present)
796 },
797 guidance: format!(
798 "cleanup ran but HEAD re-read failed during verification; do not retry blindly. underlying: {e}"
799 ),
800 });
801 }
802 };
803 let dirty = match restore_verify_dirty(notebook_root) {
804 Ok(d) => d,
805 Err(e) => {
806 return Err(NbError::RecoveryRequired {
807 pre_revision: pre_revision.to_string(),
808 post_revision_observed: Some(head),
809 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
810 preserved_paths: if still_present.is_empty() {
811 None
812 } else {
813 Some(still_present)
814 },
815 guidance: format!(
816 "cleanup ran but dirty-status check failed during verification; do not retry blindly. underlying: {e}"
817 ),
818 });
819 }
820 };
821 if head != pre_revision || dirty || !still_present.is_empty() {
822 return Err(NbError::RecoveryRequired {
823 pre_revision: pre_revision.to_string(),
824 post_revision_observed: Some(head),
825 status_observed: git::notebook_status_porcelain(notebook_root).ok(),
826 preserved_paths: if still_present.is_empty() {
827 None
828 } else {
829 Some(still_present)
830 },
831 guidance:
832 "cleanup ran but HEAD/status/owned-path verification failed; do not retry blindly"
833 .into(),
834 });
835 }
836 Ok(())
837}
838
839fn restore_verify_head(notebook_root: &Path) -> Result<String, NbError> {
841 #[cfg(feature = "testing")]
842 if std::env::var_os("NB_API_FAIL_RESTORE_HEAD").is_some() {
843 return Err(NbError::CommandFailed {
844 command: "nb-api://fail-restore-head".into(),
845 stderr: "injected HEAD verify failure for rollback tests".into(),
846 exit_code: Some(1),
847 });
848 }
849 git::notebook_head(notebook_root)
850}
851
852fn restore_verify_dirty(notebook_root: &Path) -> Result<bool, NbError> {
854 #[cfg(feature = "testing")]
855 if std::env::var_os("NB_API_FAIL_RESTORE_DIRTY").is_some() {
856 return Err(NbError::CommandFailed {
857 command: "nb-api://fail-restore-dirty".into(),
858 stderr: "injected dirty-status verify failure for rollback tests".into(),
859 exit_code: Some(1),
860 });
861 }
862 git::notebook_is_dirty(notebook_root)
863}
864
865#[cfg(feature = "testing")]
874fn simulate_external_writer(notebook_root: &Path) -> Result<(), NbError> {
875 use std::io::Write as _;
876 let (folder, name) = match std::env::var("NB_API_SIMULATE_EXTERNAL_SAME_PATH") {
877 Ok(rel) => {
878 let (folder, basename) = split_folder_basename(&normalize_rel(&rel));
879 (folder, basename)
880 }
881 Err(_) => (String::new(), format!("external-{}.md", std::process::id())),
882 };
883 let rel = if folder.is_empty() {
884 name.clone()
885 } else {
886 format!("{folder}/{name}")
887 };
888 if !folder.is_empty() {
889 std::fs::create_dir_all(notebook_root.join(&folder)).map_err(|e| NbError::Io {
890 path: notebook_root.join(&folder),
891 source: e.into(),
892 })?;
893 }
894 std::fs::write(notebook_root.join(&rel), b"# External\n\nexternal body\n").map_err(|e| {
895 NbError::Io {
896 path: notebook_root.join(&rel),
897 source: e.into(),
898 }
899 })?;
900 let index_abs = notebook_root.join(index_rel_for_folder(&folder));
901 let mut f = OpenOptions::new()
902 .create(true)
903 .append(true)
904 .open(&index_abs)
905 .map_err(|e| NbError::Io {
906 path: index_abs.clone(),
907 source: e.into(),
908 })?;
909 writeln!(f, "{name}").map_err(|e| NbError::Io {
910 path: index_abs.clone(),
911 source: e.into(),
912 })?;
913 drop(f);
914 git::notebook_commit_all(
915 notebook_root,
916 "external writer",
917 &[rel, index_rel_for_folder(&folder)],
918 )?;
919 Ok(())
920}
921
922fn materialize_tree(
935 root: &Path,
936 tree: &VirtualTree,
937 effects: &PlanEffects,
938 snapshot_keys: &HashSet<String>,
939) -> Result<(), NbError> {
940 for rel in tree.nodes.keys() {
943 refuse_symlink_ancestors(root, rel)?;
944 }
945
946 let mut removed: Vec<&String> = effects.removed.iter().collect();
948 removed.sort();
949 removed.dedup();
950 for rel in removed {
951 let key = normalize_rel(rel);
952 let abs = root.join(&key);
953 let meta = match std::fs::symlink_metadata(&abs) {
954 Ok(m) => m,
955 Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
956 Err(e) => {
957 return Err(NbError::Io {
958 path: abs,
959 source: e.into(),
960 });
961 }
962 };
963 if meta.file_type().is_symlink() {
964 return Err(NbError::UnsupportedStructure {
965 reason: format!("refusing to materialize through symlink `{key}`"),
966 });
967 }
968 if meta.is_file() && !matches!(tree.nodes.get(&key), Some(VirtualNode::File(_))) {
969 std::fs::remove_file(&abs).map_err(|e| NbError::Io {
970 path: abs,
971 source: e.into(),
972 })?;
973 }
974 }
975 let mut mkdirs: Vec<&String> = effects.mkdirs.iter().collect();
977 mkdirs.sort();
978 mkdirs.dedup();
979 for rel in mkdirs {
980 let key = normalize_rel(rel);
981 let abs = root.join(&key);
982 refuse_symlink_ancestors(root, &key)?;
983 std::fs::create_dir_all(&abs).map_err(|e| NbError::Io {
984 path: abs.clone(),
985 source: e.into(),
986 })?;
987 }
988 let mut written: Vec<&String> = effects
990 .written
991 .iter()
992 .filter(|rel| !is_index_rel(rel))
993 .collect();
994 written.sort();
995 written.dedup();
996 let created: HashSet<&String> = effects.created.iter().collect();
997 for rel in written {
998 let key = normalize_rel(rel);
999 let created_contains = created.contains(rel);
1000 let Some(VirtualNode::File(bytes)) = tree.nodes.get(&key) else {
1001 return Err(NbError::ValidationError {
1002 reason: format!("plan effect `{key}` has no file content"),
1003 location: None,
1004 });
1005 };
1006 let abs = root.join(&key);
1007 refuse_symlink_ancestors(root, &key)?;
1009 if let Ok(meta) = std::fs::symlink_metadata(&abs) {
1010 if meta.file_type().is_symlink() {
1011 return Err(NbError::UnsupportedStructure {
1012 reason: format!("refusing to write through symlink `{key}`"),
1013 });
1014 }
1015 if created_contains && !snapshot_keys.contains(&key) {
1019 return Err(NbError::PathCollision {
1020 path: key,
1021 plan_index: None,
1022 });
1023 }
1024 }
1025 if let Some(parent) = abs.parent() {
1026 std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
1027 path: parent.to_path_buf(),
1028 source: e.into(),
1029 })?;
1030 }
1031 std::fs::write(&abs, bytes).map_err(|e| NbError::Io {
1032 path: abs,
1033 source: e.into(),
1034 })?;
1035 }
1036 Ok(())
1037}
1038
1039fn refuse_symlink_ancestors(root: &Path, rel: &str) -> Result<(), NbError> {
1045 let mut acc = PathBuf::new();
1046 for part in rel.split('/').filter(|p| !p.is_empty()) {
1047 acc.push(part);
1048 let abs = root.join(&acc);
1049 match std::fs::symlink_metadata(&abs) {
1050 Ok(meta) if meta.file_type().is_symlink() => {
1051 let key = acc.to_string_lossy().replace('\\', "/");
1052 return Err(NbError::UnsupportedStructure {
1053 reason: format!(
1054 "refusing path through symlink `{key}`; transactions do not follow symlinks"
1055 ),
1056 });
1057 }
1058 Ok(_) => {}
1059 Err(e) if e.kind() == std::io::ErrorKind::NotFound => break,
1060 Err(e) => {
1061 return Err(NbError::Io {
1062 path: abs,
1063 source: e.into(),
1064 });
1065 }
1066 }
1067 }
1068 Ok(())
1069}
1070
1071fn outcome_selector(notebook: &str, target: &NoteTarget, resolved_path: &str) -> String {
1072 match target {
1073 NoteTarget::Selector { value } => {
1074 if value.contains(':') {
1075 value.clone()
1076 } else {
1077 format!("{notebook}:{value}")
1078 }
1079 }
1080 NoteTarget::Path { .. } => format!("{notebook}:{resolved_path}"),
1081 }
1082}
1083
1084struct OpMeta {
1085 path: Option<String>,
1086 selector: Option<String>,
1087 noop: bool,
1088 fingerprint: Option<Fingerprint>,
1089 index_edits: Vec<PendingIndexEdit>,
1090}
1091
1092#[derive(Debug, Default)]
1096struct PlanEffects {
1097 removed: Vec<String>,
1099 written: Vec<String>,
1102 created: Vec<String>,
1107 mkdirs: Vec<String>,
1109}
1110
1111#[derive(Debug, Clone)]
1117struct PendingIndexEdit {
1118 file_rel: String,
1119 kind: PendingIndexKind,
1120}
1121
1122#[derive(Debug, Clone)]
1123enum PendingIndexKind {
1124 Append {
1125 basename: String,
1126 },
1127 Blank {
1128 basename: String,
1129 },
1130 Rename {
1131 old_basename: String,
1132 new_basename: String,
1133 },
1134}
1135
1136fn validate_and_apply_virtual(
1137 notebook: &str,
1138 notebook_root: &Path,
1139 tree: &mut VirtualTree,
1140 ignored_existing: &HashSet<String>,
1141 op: &PlanOp,
1142 _index: usize,
1143 effects: &mut PlanEffects,
1144) -> Result<OpMeta, NbError> {
1145 match op {
1146 PlanOp::AddNote {
1147 path,
1148 title,
1149 content,
1150 tags,
1151 } => {
1152 refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1153 let bytes = build_note_bytes(title.as_deref(), content, tags);
1154 let fp = fingerprint_bytes(&bytes, path)?;
1155 tree.insert_file(path.clone(), bytes);
1156 effects.written.push(path.clone());
1157 effects.created.push(path.clone());
1158 Ok(OpMeta {
1159 path: Some(path.clone()),
1160 selector: Some(format!("{notebook}:{path}")),
1161 noop: false,
1162 fingerprint: Some(fp),
1163 index_edits: vec![append_index_edit(path)],
1164 })
1165 }
1166 PlanOp::AddTodo {
1167 path,
1168 title,
1169 description,
1170 tasks,
1171 tags,
1172 } => {
1173 refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1174 let bytes = build_todo_bytes(title, description.as_deref(), tasks, tags);
1175 let fp = fingerprint_bytes(&bytes, path)?;
1176 tree.insert_file(path.clone(), bytes);
1177 effects.written.push(path.clone());
1178 effects.created.push(path.clone());
1179 Ok(OpMeta {
1180 path: Some(path.clone()),
1181 selector: Some(format!("{notebook}:{path}")),
1182 noop: false,
1183 fingerprint: Some(fp),
1184 index_edits: vec![append_index_edit(path)],
1185 })
1186 }
1187 PlanOp::AddBookmark {
1188 path,
1189 url,
1190 title,
1191 tags,
1192 comment,
1193 } => {
1194 refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1195 let bytes = build_bookmark_bytes(url, title.as_deref(), tags, comment.as_deref());
1196 let fp = fingerprint_bytes(&bytes, path)?;
1197 tree.insert_file(path.clone(), bytes);
1198 effects.written.push(path.clone());
1199 effects.created.push(path.clone());
1200 Ok(OpMeta {
1201 path: Some(path.clone()),
1202 selector: Some(format!("{notebook}:{path}")),
1203 noop: false,
1204 fingerprint: Some(fp),
1205 index_edits: vec![append_index_edit(path)],
1206 })
1207 }
1208 PlanOp::AddFolder { path } => {
1209 refuse_create_collision(notebook_root, tree, ignored_existing, path)?;
1210 let keep = format!("{path}/.gitkeep");
1211 refuse_create_collision(notebook_root, tree, ignored_existing, &keep)?;
1212 tree.insert_folder(path.clone());
1213 effects.mkdirs.push(path.clone());
1214 if !tree.exists(&keep) {
1217 tree.insert_file(keep.clone(), Vec::new());
1218 }
1219 effects.written.push(keep.clone());
1220 effects.created.push(keep);
1221 Ok(OpMeta {
1222 path: Some(path.clone()),
1223 selector: None,
1224 noop: false,
1225 fingerprint: None,
1226 index_edits: Vec::new(),
1227 })
1228 }
1229 PlanOp::DeleteNote { target } => {
1230 let path = resolve_target_path(tree, ignored_existing, target)?;
1231 if !tree.exists(&path) {
1232 return Err(NbError::NotFound {
1233 selector: target.value().to_string(),
1234 });
1235 }
1236 tree.remove(&path);
1237 effects.removed.push(path.clone());
1238 Ok(OpMeta {
1239 path: Some(path.clone()),
1240 selector: Some(outcome_selector(notebook, target, &path)),
1241 noop: false,
1242 fingerprint: None,
1243 index_edits: vec![blank_index_edit(&path)],
1244 })
1245 }
1246 PlanOp::MoveNote {
1247 target,
1248 destination,
1249 } => {
1250 let from = resolve_target_path(tree, ignored_existing, target)?;
1251 let to = resolve_move_destination(&from, destination);
1252 refuse_create_collision(notebook_root, tree, ignored_existing, &to)?;
1253 let (from_folder, from_base) = split_folder_basename(&from);
1260 let (to_folder, to_base) = split_folder_basename(&to);
1261 if from_folder == to_folder && to_base.len() > from_base.len() {
1262 return Err(NbError::ValidationError {
1263 reason: format!(
1264 "in-folder rename to a longer name (`{from_base}` -> `{to_base}`) would risk concurrent .index appends; delete and recreate the note instead"
1265 ),
1266 location: None,
1267 });
1268 }
1269 tree.rename(&from, &to)?;
1270 effects.removed.push(from.clone());
1271 effects.written.push(to.clone());
1272 effects.created.push(to.clone());
1273 Ok(OpMeta {
1274 path: Some(to.clone()),
1275 selector: Some(format!("{notebook}:{to}")),
1276 noop: false,
1277 fingerprint: None,
1278 index_edits: move_index_edits(&from, &to),
1279 })
1280 }
1281 PlanOp::MarkTaskDone {
1282 target,
1283 task_number,
1284 } => {
1285 let path = resolve_target_path(tree, ignored_existing, target)?;
1286 let bytes = tree
1287 .get_file(&path)
1288 .ok_or_else(|| NbError::NotFound {
1289 selector: target.value().to_string(),
1290 })?
1291 .to_vec();
1292 let new_bytes = set_todo_state(&bytes, &path, true, *task_number)?;
1293 let noop = new_bytes == bytes;
1294 let fp = fingerprint_bytes(&new_bytes, &path)?;
1295 tree.insert_file(path.clone(), new_bytes);
1296 effects.written.push(path.clone());
1297 Ok(OpMeta {
1298 path: Some(path.clone()),
1299 selector: Some(outcome_selector(notebook, target, &path)),
1300 noop,
1301 fingerprint: Some(fp),
1302 index_edits: Vec::new(),
1303 })
1304 }
1305 PlanOp::UnmarkTaskDone {
1306 target,
1307 task_number,
1308 } => {
1309 let path = resolve_target_path(tree, ignored_existing, target)?;
1310 let bytes = tree
1311 .get_file(&path)
1312 .ok_or_else(|| NbError::NotFound {
1313 selector: target.value().to_string(),
1314 })?
1315 .to_vec();
1316 let new_bytes = set_todo_state(&bytes, &path, false, *task_number)?;
1317 let noop = new_bytes == bytes;
1318 let fp = fingerprint_bytes(&new_bytes, &path)?;
1319 tree.insert_file(path.clone(), new_bytes);
1320 effects.written.push(path.clone());
1321 Ok(OpMeta {
1322 path: Some(path.clone()),
1323 selector: Some(outcome_selector(notebook, target, &path)),
1324 noop,
1325 fingerprint: Some(fp),
1326 index_edits: Vec::new(),
1327 })
1328 }
1329 PlanOp::ReplaceNoteBody {
1330 target,
1331 new_body,
1332 fingerprint: expected,
1333 } => {
1334 let path = resolve_target_path(tree, ignored_existing, target)?;
1335 let bytes = tree
1336 .get_file(&path)
1337 .ok_or_else(|| NbError::NotFound {
1338 selector: target.value().to_string(),
1339 })?
1340 .to_vec();
1341 let doc = parse_doc(&bytes, &path)?;
1342 require_contiguous_body(&doc)?;
1345 let current = fingerprint::fingerprint(&doc);
1346 if ¤t != expected {
1347 return Err(NbError::FingerprintMismatch {
1348 target: target.clone(),
1349 guidance: "body fingerprint does not match; re-read and retry".into(),
1350 });
1351 }
1352 let new_bytes = splice_body(&doc, new_body.as_bytes())?;
1353 let fp = fingerprint_bytes(&new_bytes, &path)?;
1354 let noop = new_bytes == bytes;
1355 tree.insert_file(path.clone(), new_bytes);
1356 effects.written.push(path.clone());
1357 Ok(OpMeta {
1358 path: Some(path.clone()),
1359 selector: Some(outcome_selector(notebook, target, &path)),
1360 noop,
1361 fingerprint: Some(fp),
1362 index_edits: Vec::new(),
1363 })
1364 }
1365 PlanOp::EditNoteSubstring {
1366 target,
1367 pattern,
1368 replacement,
1369 occurrence,
1370 expected_count,
1371 fingerprint: expected,
1372 } => {
1373 let path = resolve_target_path(tree, ignored_existing, target)?;
1374 let bytes = tree
1375 .get_file(&path)
1376 .ok_or_else(|| NbError::NotFound {
1377 selector: target.value().to_string(),
1378 })?
1379 .to_vec();
1380 let doc = parse_doc(&bytes, &path)?;
1381 let body = require_contiguous_body(&doc)?;
1382 if let Some(exp) = expected {
1383 let current = fingerprint::fingerprint(&doc);
1384 if ¤t != exp {
1385 return Err(NbError::FingerprintMismatch {
1386 target: target.clone(),
1387 guidance: "body fingerprint does not match; re-read and retry".into(),
1388 });
1389 }
1390 }
1391 let new_body = apply_substring(
1392 &body,
1393 pattern.as_bytes(),
1394 replacement.as_bytes(),
1395 occurrence,
1396 *expected_count,
1397 )?;
1398 let new_bytes = splice_body(&doc, &new_body)?;
1399 let fp = fingerprint_bytes(&new_bytes, &path)?;
1400 let noop = new_bytes == bytes;
1401 tree.insert_file(path.clone(), new_bytes);
1402 effects.written.push(path.clone());
1403 Ok(OpMeta {
1404 path: Some(path.clone()),
1405 selector: Some(outcome_selector(notebook, target, &path)),
1406 noop,
1407 fingerprint: Some(fp),
1408 index_edits: Vec::new(),
1409 })
1410 }
1411 PlanOp::EditNoteLines { target, edits } => {
1412 let path = resolve_target_path(tree, ignored_existing, target)?;
1413 let bytes = tree
1414 .get_file(&path)
1415 .ok_or_else(|| NbError::NotFound {
1416 selector: target.value().to_string(),
1417 })?
1418 .to_vec();
1419 let doc = parse_doc(&bytes, &path)?;
1420 let body = require_contiguous_body(&doc)?;
1421 let new_body = apply_line_edits(&body, edits)?;
1422 let new_bytes = splice_body(&doc, &new_body)?;
1423 let fp = fingerprint_bytes(&new_bytes, &path)?;
1424 let noop = new_bytes == bytes;
1425 tree.insert_file(path.clone(), new_bytes);
1426 effects.written.push(path.clone());
1427 Ok(OpMeta {
1428 path: Some(path.clone()),
1429 selector: Some(outcome_selector(notebook, target, &path)),
1430 noop,
1431 fingerprint: Some(fp),
1432 index_edits: Vec::new(),
1433 })
1434 }
1435 PlanOp::RetitleNote { target, title } => {
1436 let path = resolve_target_path(tree, ignored_existing, target)?;
1437 let bytes = tree
1438 .get_file(&path)
1439 .ok_or_else(|| NbError::NotFound {
1440 selector: target.value().to_string(),
1441 })?
1442 .to_vec();
1443 let doc = parse_doc(&bytes, &path)?;
1444 let mut title_line = title.clone();
1445 if !title_line.starts_with('#') {
1446 title_line = format!("# {title_line}");
1447 }
1448 let new_bytes = splice_title(&doc, title_line.as_bytes())?;
1449 let fp = fingerprint_bytes(&new_bytes, &path)?;
1450 let noop = new_bytes == bytes;
1451 tree.insert_file(path.clone(), new_bytes);
1452 effects.written.push(path.clone());
1453 Ok(OpMeta {
1454 path: Some(path.clone()),
1455 selector: Some(outcome_selector(notebook, target, &path)),
1456 noop,
1457 fingerprint: Some(fp),
1458 index_edits: Vec::new(),
1459 })
1460 }
1461 PlanOp::EditNoteTags {
1462 target,
1463 add,
1464 remove,
1465 } => {
1466 let path = resolve_target_path(tree, ignored_existing, target)?;
1467 let bytes = tree
1468 .get_file(&path)
1469 .ok_or_else(|| NbError::NotFound {
1470 selector: target.value().to_string(),
1471 })?
1472 .to_vec();
1473 let doc = parse_doc(&bytes, &path)?;
1474 let new_bytes = apply_tag_edit(&doc, &path, add, remove)?;
1475 let fp = fingerprint_bytes(&new_bytes, &path)?;
1476 let noop = new_bytes == bytes;
1477 tree.insert_file(path.clone(), new_bytes);
1478 effects.written.push(path.clone());
1479 Ok(OpMeta {
1480 path: Some(path.clone()),
1481 selector: Some(outcome_selector(notebook, target, &path)),
1482 noop,
1483 fingerprint: Some(fp),
1484 index_edits: Vec::new(),
1485 })
1486 }
1487 }
1488}
1489
1490fn refuse_create_collision(
1491 notebook_root: &Path,
1492 tree: &VirtualTree,
1493 ignored_existing: &HashSet<String>,
1494 path: &str,
1495) -> Result<(), NbError> {
1496 if ignored_existing.contains(path) {
1497 return Err(NbError::PathIgnored {
1498 path: path.to_string(),
1499 guidance: "path exists as a Git-ignored file; un-ignore or remove it outside the transaction before creating here".into(),
1500 plan_index: None,
1501 });
1502 }
1503 refuse_symlink_ancestors(notebook_root, path)?;
1506 for ig in ignored_existing {
1507 if path == ig || path.starts_with(&format!("{ig}/")) {
1508 let abs = notebook_root.join(ig);
1509 if let Ok(meta) = std::fs::symlink_metadata(&abs)
1510 && meta.file_type().is_symlink()
1511 {
1512 return Err(NbError::UnsupportedStructure {
1513 reason: format!(
1514 "refusing path through symlink `{ig}`; transactions do not follow symlinks"
1515 ),
1516 });
1517 }
1518 }
1519 }
1520 if tree.exists(path) {
1521 return Err(NbError::PathCollision {
1522 path: path.to_string(),
1523 plan_index: None,
1524 });
1525 }
1526 Ok(())
1527}
1528
1529fn refuse_existing_ignored(ignored_existing: &HashSet<String>, path: &str) -> Result<(), NbError> {
1530 if ignored_existing.contains(path) {
1531 return Err(NbError::PathIgnored {
1532 path: path.to_string(),
1533 guidance:
1534 "cannot edit, delete, or move an existing Git-ignored path inside a transaction"
1535 .into(),
1536 plan_index: None,
1537 });
1538 }
1539 Ok(())
1540}
1541
1542fn resolve_target_path(
1543 tree: &VirtualTree,
1544 ignored_existing: &HashSet<String>,
1545 target: &NoteTarget,
1546) -> Result<String, NbError> {
1547 match target {
1548 NoteTarget::Path { value } => {
1549 let path = normalize_rel(value);
1550 refuse_existing_ignored(ignored_existing, &path)?;
1551 if tree.exists(&path) {
1552 return Ok(path);
1553 }
1554 Err(NbError::NotFound {
1556 selector: value.clone(),
1557 })
1558 }
1559 NoteTarget::Selector { value } => {
1560 let stripped = value
1562 .rsplit_once(':')
1563 .map(|(_, rest)| rest)
1564 .unwrap_or(value.as_str());
1565 let candidate = normalize_rel(stripped);
1566 refuse_existing_ignored(ignored_existing, &candidate)?;
1567 if tree.exists(&candidate) {
1568 return Ok(candidate);
1569 }
1570 if let Some(resolved) = resolve_numeric_in_tree(tree, &candidate) {
1573 return resolved;
1574 }
1575 let matches: Vec<_> = tree
1577 .nodes
1578 .iter()
1579 .filter_map(|(p, n)| match n {
1580 VirtualNode::File(_)
1581 if p == &candidate
1582 || p.ends_with(&format!("/{candidate}"))
1583 || Path::new(p).file_stem().and_then(|s| s.to_str())
1584 == Some(stripped)
1585 || p.ends_with(stripped) =>
1586 {
1587 Some(p.clone())
1588 }
1589 _ => None,
1590 })
1591 .collect();
1592 match matches.as_slice() {
1593 [one] => Ok(one.clone()),
1594 [] => {
1595 if ignored_existing.contains(&candidate) {
1597 return Err(NbError::PathIgnored {
1598 path: candidate,
1599 guidance: "cannot edit, delete, or move an existing Git-ignored path inside a transaction".into(),
1600 plan_index: None,
1601 });
1602 }
1603 for ig in ignored_existing {
1604 if ig.ends_with(&format!("/{candidate}")) || ig.ends_with(stripped) {
1605 return Err(NbError::PathIgnored {
1606 path: ig.clone(),
1607 guidance: "cannot edit, delete, or move an existing Git-ignored path inside a transaction".into(),
1608 plan_index: None,
1609 });
1610 }
1611 }
1612 Err(NbError::NotFound {
1613 selector: value.clone(),
1614 })
1615 }
1616 _ => Err(NbError::ValidationError {
1617 reason: format!("selector `{value}` is ambiguous across multiple paths"),
1618 location: None,
1619 }),
1620 }
1621 }
1622 }
1623}
1624
1625fn resolve_numeric_in_tree(tree: &VirtualTree, candidate: &str) -> Option<Result<String, NbError>> {
1632 let (folder, id_str) = match candidate.rfind('/') {
1633 Some(i) => (candidate[..i].to_string(), candidate[i + 1..].to_string()),
1634 None => (String::new(), candidate.to_string()),
1635 };
1636 let id: usize = match id_str.parse() {
1637 Ok(n) => n,
1638 Err(_) => return None,
1639 };
1640 if id == 0 {
1641 return Some(Err(NbError::NotFound {
1642 selector: candidate.to_string(),
1643 }));
1644 }
1645 let rel = index_rel_for_folder(&folder);
1646 let bytes = match tree.nodes.get(&rel) {
1647 Some(VirtualNode::File(b)) => b.clone(),
1648 _ => return None,
1649 };
1650 let lines = parse_index_lines(&bytes);
1651 match lines.get(id - 1) {
1652 Some(name) if !name.trim().is_empty() => {
1653 let path = if folder.is_empty() {
1654 name.clone()
1655 } else {
1656 format!("{folder}/{name}")
1657 };
1658 Some(Ok(path))
1659 }
1660 _ => Some(Err(NbError::NotFound {
1661 selector: candidate.to_string(),
1662 })),
1663 }
1664}
1665
1666fn resolve_move_destination(from: &str, destination: &str) -> String {
1667 let into_folder = destination.trim_end().ends_with('/');
1671 let dest = normalize_rel(destination);
1672 if into_folder {
1673 let base = Path::new(from)
1674 .file_name()
1675 .and_then(|s| s.to_str())
1676 .unwrap_or(from);
1677 return normalize_rel(&format!("{dest}/{base}"));
1678 }
1679 dest
1682}
1683
1684fn parse_doc(bytes: &[u8], path: &str) -> Result<NoteDocument, NbError> {
1685 parse(bytes, ParseContext::FromPath(PathBuf::from(path)))
1686}
1687
1688fn fingerprint_bytes(bytes: &[u8], path: &str) -> Result<Fingerprint, NbError> {
1689 let doc = parse_doc(bytes, path)?;
1690 Ok(fingerprint::fingerprint(&doc))
1691}
1692
1693fn build_note_bytes(title: Option<&str>, content: &str, tags: &[String]) -> Vec<u8> {
1694 let mut out = Vec::new();
1695 if let Some(t) = title {
1696 out.extend_from_slice(format!("# {t}\n\n").as_bytes());
1697 }
1698 if !tags.is_empty() {
1699 let mut first = true;
1700 for tag in tags {
1701 if !first {
1702 out.push(b' ');
1703 }
1704 first = false;
1705 if tag.starts_with('#') {
1706 out.extend_from_slice(tag.as_bytes());
1707 } else {
1708 out.push(b'#');
1709 out.extend_from_slice(tag.as_bytes());
1710 }
1711 }
1712 out.extend_from_slice(b"\n\n");
1713 }
1714 out.extend_from_slice(content.as_bytes());
1715 out
1716}
1717
1718fn build_todo_bytes(
1719 title: &str,
1720 description: Option<&str>,
1721 tasks: &[String],
1722 tags: &[String],
1723) -> Vec<u8> {
1724 let mut out = Vec::new();
1725 let title_line = if title.contains('[') {
1726 format!("# {title}\n\n")
1727 } else {
1728 format!("# [ ] {title}\n\n")
1729 };
1730 out.extend_from_slice(title_line.as_bytes());
1731 if !tasks.is_empty() {
1732 out.extend_from_slice(b"## Tasks\n\n");
1733 for task in tasks {
1734 out.extend_from_slice(format!("- [ ] {task}\n").as_bytes());
1735 }
1736 out.push(b'\n');
1737 }
1738 if let Some(desc) = description {
1739 out.extend_from_slice(b"## Description\n\n");
1740 out.extend_from_slice(desc.as_bytes());
1741 if !desc.ends_with('\n') {
1742 out.push(b'\n');
1743 }
1744 out.push(b'\n');
1745 }
1746 if !tags.is_empty() {
1747 out.extend_from_slice(b"## Tags\n\n");
1748 let mut first = true;
1749 for tag in tags {
1750 if !first {
1751 out.push(b' ');
1752 }
1753 first = false;
1754 if tag.starts_with('#') {
1755 out.extend_from_slice(tag.as_bytes());
1756 } else {
1757 out.push(b'#');
1758 out.extend_from_slice(tag.as_bytes());
1759 }
1760 }
1761 out.push(b'\n');
1762 }
1763 out
1764}
1765
1766fn build_bookmark_bytes(
1767 url: &str,
1768 title: Option<&str>,
1769 tags: &[String],
1770 comment: Option<&str>,
1771) -> Vec<u8> {
1772 let mut out = Vec::new();
1773 if let Some(t) = title {
1774 out.extend_from_slice(format!("# {t}\n\n").as_bytes());
1775 }
1776 out.extend_from_slice(format!("<{url}>\n\n").as_bytes());
1777 if let Some(c) = comment {
1778 out.extend_from_slice(b"## Content\n\n");
1779 out.extend_from_slice(c.as_bytes());
1780 if !c.ends_with('\n') {
1781 out.push(b'\n');
1782 }
1783 out.push(b'\n');
1784 }
1785 if !tags.is_empty() {
1786 out.extend_from_slice(b"## Tags\n\n");
1787 let mut first = true;
1788 for tag in tags {
1789 if !first {
1790 out.push(b' ');
1791 }
1792 first = false;
1793 if tag.starts_with('#') {
1794 out.extend_from_slice(tag.as_bytes());
1795 } else {
1796 out.push(b'#');
1797 out.extend_from_slice(tag.as_bytes());
1798 }
1799 }
1800 out.push(b'\n');
1801 }
1802 out
1803}
1804
1805fn set_todo_state(
1806 bytes: &[u8],
1807 path: &str,
1808 done: bool,
1809 task_number: Option<u32>,
1810) -> Result<Vec<u8>, NbError> {
1811 let doc = parse_doc(bytes, path)?;
1812 if doc.kind() != DocumentKind::Todo {
1813 return Err(NbError::UnsupportedStructure {
1814 reason: "mark_task_done/unmark_task_done require a Todo document".into(),
1815 });
1816 }
1817 let mut out = bytes.to_vec();
1818 if let Some(n) = task_number {
1819 let mut count = 0u32;
1821 let mut i = 0usize;
1822 while i + 5 < out.len() {
1823 if out[i] == b'-' && out[i + 1] == b' ' && out[i + 2] == b'[' {
1824 let close = out[i + 4];
1825 if close == b']' {
1826 count += 1;
1827 if count == n {
1828 let mark = if done { b'x' } else { b' ' };
1829 out[i + 3] = mark;
1830 return Ok(out);
1831 }
1832 }
1833 }
1834 i += 1;
1835 }
1836 return Err(NbError::ValidationError {
1837 reason: format!("task_number {n} not found"),
1838 location: None,
1839 });
1840 }
1841 if let Some(range) = doc.title_byte_range() {
1843 let title = &out[range.clone()];
1844 let replaced = if done {
1845 replace_checkbox(title, true)
1846 } else {
1847 replace_checkbox(title, false)
1848 };
1849 out.splice(range, replaced);
1850 }
1851 Ok(out)
1852}
1853
1854fn replace_checkbox(title: &[u8], done: bool) -> Vec<u8> {
1855 let s = String::from_utf8_lossy(title);
1856 let mark = if done { "[x]" } else { "[ ]" };
1857 let new = if s.contains("[x]") || s.contains("[X]") {
1858 s.replacen("[x]", mark, 1).replacen("[X]", mark, 1)
1859 } else if s.contains("[ ]") {
1860 s.replacen("[ ]", mark, 1)
1861 } else {
1862 if let Some(rest) = s.strip_prefix("# ") {
1864 format!("# {mark} {rest}")
1865 } else {
1866 s.into_owned()
1867 }
1868 };
1869 new.into_bytes()
1870}
1871
1872fn apply_tag_edit(
1873 doc: &NoteDocument,
1874 path: &str,
1875 add: &[String],
1876 remove: &[String],
1877) -> Result<Vec<u8>, NbError> {
1878 let mut tags: Vec<String> = doc
1879 .tags_str()
1880 .filter_map(|t| t.ok().map(|s| s.trim_start_matches('#').to_string()))
1881 .collect();
1882 for r in remove {
1883 let key = r.trim_start_matches('#');
1884 tags.retain(|t| t != key);
1885 }
1886 for a in add {
1887 let key = a.trim_start_matches('#').to_string();
1888 if !tags.iter().any(|t| t == &key) {
1889 tags.push(key);
1890 }
1891 }
1892 let source = doc.source();
1893 let result = match doc.kind() {
1894 DocumentKind::Note => {
1895 let tag_line = if tags.is_empty() {
1896 None
1897 } else {
1898 Some(
1899 tags.iter()
1900 .map(|t| format!("#{t}"))
1901 .collect::<Vec<_>>()
1902 .join(" ")
1903 + "\n",
1904 )
1905 };
1906 if let Some(range) = doc.tags_byte_range() {
1907 let mut out = source.to_vec();
1908 match tag_line {
1909 Some(line) => {
1910 out.splice(range, line.into_bytes());
1911 }
1912 None => {
1913 out.splice(range, std::iter::empty::<u8>());
1914 }
1915 }
1916 Ok(out)
1917 } else if let Some(line) = tag_line {
1918 let insert_at = doc.title_byte_range().map(|r| r.end).unwrap_or(0);
1920 let mut block = Vec::new();
1921 if insert_at > 0 {
1922 block.push(b'\n');
1923 }
1924 block.extend_from_slice(line.as_bytes());
1925 block.push(b'\n');
1926 let mut out = source.to_vec();
1927 out.splice(insert_at..insert_at, block);
1928 Ok(out)
1929 } else {
1930 Ok(source.to_vec())
1931 }
1932 }
1933 DocumentKind::Todo | DocumentKind::Bookmark => {
1934 let section = if tags.is_empty() {
1935 None
1936 } else {
1937 Some(format!(
1938 "## Tags\n\n{}\n",
1939 tags.iter()
1940 .map(|t| format!("#{t}"))
1941 .collect::<Vec<_>>()
1942 .join(" ")
1943 ))
1944 };
1945 if let Some(range) = doc.tags_byte_range() {
1946 let mut out = source.to_vec();
1947 let replacement = section.map(|s| s.into_bytes()).unwrap_or_default();
1948 out.splice(range, replacement);
1949 Ok(out)
1950 } else if let Some(s) = section {
1951 let mut out = source.to_vec();
1952 if !out.ends_with(b"\n") {
1953 out.push(b'\n');
1954 }
1955 out.push(b'\n');
1956 out.extend_from_slice(s.as_bytes());
1957 Ok(out)
1958 } else {
1959 Ok(source.to_vec())
1960 }
1961 }
1962 };
1963 let _ = path;
1964 result
1965}
1966
1967fn annotate_plan_index(err: NbError, index: u32) -> NbError {
1968 match err {
1969 NbError::PathCollision { path, .. } => NbError::PathCollision {
1970 path,
1971 plan_index: Some(index),
1972 },
1973 NbError::PathIgnored { path, guidance, .. } => NbError::PathIgnored {
1974 path,
1975 guidance,
1976 plan_index: Some(index),
1977 },
1978 NbError::FingerprintMismatch { .. }
1979 | NbError::AnchorMismatch { .. }
1980 | NbError::OccurrenceMismatch { .. }
1981 | NbError::OverlappingEdits { .. }
1982 | NbError::FragmentedBody { .. }
1983 | NbError::EmptySubstringPattern
1984 | NbError::NotFound { .. }
1985 | NbError::UnsupportedStructure { .. } => err,
1986 NbError::PlanValidation {
1987 kind,
1988 message,
1989 plan_index: _,
1990 } => NbError::PlanValidation {
1991 kind,
1992 message,
1993 plan_index: Some(index),
1994 },
1995 other => NbError::PlanValidation {
1996 kind: "op_failed".into(),
1997 message: other.to_string(),
1998 plan_index: Some(index),
1999 },
2000 }
2001}
2002
2003fn validate_target(target: &NoteTarget) -> Result<(), NbError> {
2004 if target.value().trim().is_empty() {
2005 return Err(NbError::ValidationError {
2006 reason: "note target must not be empty".into(),
2007 location: None,
2008 });
2009 }
2010 Ok(())
2011}
2012
2013fn validate_create_path(path: &str, file: bool) -> Result<String, NbError> {
2014 let raw = path.trim();
2017 if raw.is_empty() {
2018 return Err(NbError::ValidationError {
2019 reason: "path must not be empty".into(),
2020 location: None,
2021 });
2022 }
2023 if raw.starts_with('/') || raw.starts_with('\\') || Path::new(raw).is_absolute() {
2024 return Err(NbError::ValidationError {
2025 reason: "path must be notebook-relative (absolute paths refused)".into(),
2026 location: None,
2027 });
2028 }
2029 if raw.contains('\\') {
2030 return Err(NbError::ValidationError {
2031 reason: "path must not contain backslash separators".into(),
2032 location: None,
2033 });
2034 }
2035 if raw.contains('\0') {
2036 return Err(NbError::ValidationError {
2037 reason: "path must not contain NUL".into(),
2038 location: None,
2039 });
2040 }
2041 let path = normalize_rel(raw);
2042 if path.is_empty() {
2043 return Err(NbError::ValidationError {
2044 reason: "path must not be empty".into(),
2045 location: None,
2046 });
2047 }
2048 if path
2049 .split('/')
2050 .any(|p| p.is_empty() || p == "." || p == "..")
2051 {
2052 return Err(NbError::ValidationError {
2053 reason: "path must not contain empty, `.`, or `..` segments".into(),
2054 location: None,
2055 });
2056 }
2057 if file {
2058 let name = Path::new(&path)
2059 .file_name()
2060 .and_then(|s| s.to_str())
2061 .unwrap_or("");
2062 if name.is_empty() {
2063 return Err(NbError::ValidationError {
2064 reason: "create path must include a filename".into(),
2065 location: None,
2066 });
2067 }
2068 }
2069 Ok(path)
2070}
2071
2072fn normalize_rel(path: &str) -> String {
2073 path.trim()
2074 .trim_start_matches("./")
2075 .trim_matches('/')
2076 .replace('\\', "/")
2077}
2078
2079fn parent_path(path: &str) -> Option<String> {
2080 let p = Path::new(path).parent()?;
2081 let s = p.to_string_lossy().replace('\\', "/");
2082 if s.is_empty() || s == "." {
2083 None
2084 } else {
2085 Some(s)
2086 }
2087}
2088
2089pub(crate) fn mangle_stem(title: &str) -> String {
2093 let mut out = String::with_capacity(title.len());
2094 let mut prev_underscore = false;
2095 for c in title.chars() {
2096 if c.is_ascii_alphanumeric() {
2097 out.push(c.to_ascii_lowercase());
2098 prev_underscore = false;
2099 } else if c.is_ascii() {
2100 if !prev_underscore {
2101 out.push('_');
2102 prev_underscore = true;
2103 }
2104 } else {
2105 out.push(c);
2106 prev_underscore = false;
2107 }
2108 }
2109 out.trim_matches('_').to_string()
2110}
2111
2112pub(crate) fn titleless_stem() -> String {
2116 if let Ok(out) = std::process::Command::new("date")
2117 .arg("+%Y%m%d%H%M%S")
2118 .output()
2119 && out.status.success()
2120 {
2121 let s = String::from_utf8_lossy(&out.stdout).trim().to_string();
2122 if s.len() == 14 && s.bytes().all(|b| b.is_ascii_digit()) {
2123 return s;
2124 }
2125 }
2126 static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
2128 let secs = SystemTime::now()
2129 .duration_since(UNIX_EPOCH)
2130 .map(|d| d.as_secs())
2131 .unwrap_or(0);
2132 let n = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2133 format!("{secs:014}-{n}")
2134}
2135
2136pub(crate) fn filename_for_title(title: Option<&str>, extension: &str) -> String {
2143 let stem = title
2144 .map(|t| mangle_stem(t.trim()))
2145 .filter(|s| !s.is_empty());
2146 match stem {
2147 Some(s) => format!("{s}.{extension}"),
2148 None => format!("{}.{extension}", titleless_stem()),
2149 }
2150}
2151
2152pub(crate) fn suffixed_filename(filename: &str, n: u32) -> String {
2154 match filename.find('.') {
2155 Some(i) => format!("{}-{n}{}", &filename[..i], &filename[i..]),
2156 None => format!("{filename}-{n}"),
2157 }
2158}
2159
2160pub(crate) fn join_folder_file(folder: Option<&str>, filename: &str) -> String {
2161 match folder {
2162 Some(f) if !f.trim().is_empty() => {
2163 format!("{}/{}", normalize_rel(f), filename.trim_start_matches('/'))
2164 }
2165 _ => filename.to_string(),
2166 }
2167}
2168
2169fn split_folder_basename(path: &str) -> (String, String) {
2171 match path.rfind('/') {
2172 Some(i) => (path[..i].to_string(), path[i + 1..].to_string()),
2173 None => (String::new(), path.to_string()),
2174 }
2175}
2176
2177fn index_rel_for_folder(folder: &str) -> String {
2179 if folder.is_empty() {
2180 ".index".to_string()
2181 } else {
2182 format!("{folder}/.index")
2183 }
2184}
2185
2186fn append_index_edit(path: &str) -> PendingIndexEdit {
2187 let (folder, basename) = split_folder_basename(path);
2188 PendingIndexEdit {
2189 file_rel: index_rel_for_folder(&folder),
2190 kind: PendingIndexKind::Append { basename },
2191 }
2192}
2193
2194fn blank_index_edit(path: &str) -> PendingIndexEdit {
2195 let (folder, basename) = split_folder_basename(path);
2196 PendingIndexEdit {
2197 file_rel: index_rel_for_folder(&folder),
2198 kind: PendingIndexKind::Blank { basename },
2199 }
2200}
2201
2202fn move_index_edits(from: &str, to: &str) -> Vec<PendingIndexEdit> {
2203 let (from_folder, from_base) = split_folder_basename(from);
2204 let (to_folder, to_base) = split_folder_basename(to);
2205 if from_folder == to_folder {
2206 vec![PendingIndexEdit {
2207 file_rel: index_rel_for_folder(&from_folder),
2208 kind: PendingIndexKind::Rename {
2209 old_basename: from_base,
2210 new_basename: to_base,
2211 },
2212 }]
2213 } else {
2214 vec![
2215 PendingIndexEdit {
2216 file_rel: index_rel_for_folder(&from_folder),
2217 kind: PendingIndexKind::Blank {
2218 basename: from_base,
2219 },
2220 },
2221 PendingIndexEdit {
2222 file_rel: index_rel_for_folder(&to_folder),
2223 kind: PendingIndexKind::Append { basename: to_base },
2224 },
2225 ]
2226 }
2227}
2228
2229fn parse_index_lines(bytes: &[u8]) -> Vec<String> {
2234 if bytes.is_empty() {
2235 return Vec::new();
2236 }
2237 let text = String::from_utf8_lossy(bytes);
2238 let mut lines: Vec<String> = text.split('\n').map(str::to_string).collect();
2239 if text.ends_with('\n') {
2240 lines.pop();
2241 }
2242 lines
2243}
2244
2245fn render_index_lines(lines: &[String]) -> Vec<u8> {
2246 if lines.is_empty() {
2247 return Vec::new();
2248 }
2249 let mut out = lines.join("\n").into_bytes();
2250 out.push(b'\n');
2251 out
2252}
2253
2254fn numeric_selector(notebook: &str, folder: &str, id: u32) -> String {
2256 if folder.is_empty() {
2257 format!("{notebook}:{id}")
2258 } else {
2259 format!("{notebook}:{folder}/{id}")
2260 }
2261}
2262
2263fn is_index_rel(rel: &str) -> bool {
2267 rel == ".index" || rel.ends_with("/.index")
2268}
2269
2270struct IndexLockGuard {
2289 path: PathBuf,
2290 nonce: String,
2291 heartbeat: Option<tokio::task::JoinHandle<()>>,
2292}
2293
2294impl Drop for IndexLockGuard {
2295 fn drop(&mut self) {
2296 if let Some(handle) = self.heartbeat.take() {
2297 handle.abort();
2298 }
2299 if std::fs::read_to_string(&self.path)
2300 .map(|content| content.trim_end() == self.nonce)
2301 .unwrap_or(false)
2302 {
2303 let _ = std::fs::remove_file(&self.path);
2304 }
2305 }
2306}
2307
2308fn index_lock_path(notebook_root: &Path) -> PathBuf {
2309 notebook_root.join(".nb-api-index.lock")
2310}
2311
2312fn new_lock_nonce() -> String {
2313 static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
2314 let n = COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
2315 let nanos = SystemTime::now()
2316 .duration_since(UNIX_EPOCH)
2317 .map(|d| d.as_nanos())
2318 .unwrap_or(0);
2319 format!("pid={} nonce={n} ns={nanos}", std::process::id())
2320}
2321
2322fn try_remove_lock_if_stale(path: &Path, timeout: Duration) -> bool {
2328 let content_before = std::fs::read_to_string(path).ok();
2329 let stale = std::fs::metadata(path)
2330 .and_then(|m| m.modified())
2331 .map(|t| t.elapsed().unwrap_or(Duration::ZERO) > timeout)
2332 .unwrap_or(false);
2333 if !stale {
2334 return content_before.is_none();
2335 }
2336 let content_after = std::fs::read_to_string(path).ok();
2339 if content_after != content_before {
2340 return false;
2341 }
2342 let still_stale = std::fs::metadata(path)
2343 .and_then(|m| m.modified())
2344 .map(|t| t.elapsed().unwrap_or(Duration::ZERO) > timeout)
2345 .unwrap_or(true);
2346 if content_before.is_none() || !still_stale {
2347 return content_before.is_none();
2348 }
2349 std::fs::remove_file(path).is_ok()
2350}
2351
2352fn reap_stale_index_lock(notebook_root: &Path, timeout: Duration) {
2358 let path = index_lock_path(notebook_root);
2359 if path.exists() {
2360 try_remove_lock_if_stale(&path, timeout);
2361 }
2362}
2363
2364async fn acquire_index_lock(
2365 notebook_root: &Path,
2366 timeout: Duration,
2367) -> Result<IndexLockGuard, NbError> {
2368 let path = index_lock_path(notebook_root);
2372 let start = Instant::now();
2373 loop {
2374 match OpenOptions::new().write(true).create_new(true).open(&path) {
2375 Ok(mut f) => {
2376 let nonce = new_lock_nonce();
2377 let _ = writeln!(f, "{nonce}");
2378 drop(f);
2379 let beat = (timeout / 3).clamp(Duration::from_millis(5), Duration::from_secs(30));
2383 let heartbeat_path = path.clone();
2384 let heartbeat_nonce = nonce.clone();
2385 let heartbeat = tokio::spawn(async move {
2386 loop {
2387 tokio::time::sleep(beat).await;
2388 let owned = std::fs::read_to_string(&heartbeat_path)
2389 .map(|content| content.trim_end() == heartbeat_nonce)
2390 .unwrap_or(false);
2391 if !owned {
2392 break;
2393 }
2394 if std::fs::File::options()
2395 .write(true)
2396 .open(&heartbeat_path)
2397 .and_then(|f| f.set_modified(SystemTime::now()))
2398 .is_err()
2399 {
2400 break;
2401 }
2402 }
2403 });
2404 return Ok(IndexLockGuard {
2405 path,
2406 nonce,
2407 heartbeat: Some(heartbeat),
2408 });
2409 }
2410 Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
2411 if try_remove_lock_if_stale(&path, timeout) {
2412 continue;
2413 }
2414 if start.elapsed() >= timeout {
2415 return Err(NbError::IndexLockTimeout {
2416 path: path.to_string_lossy().into_owned(),
2417 timeout_ms: timeout.as_millis() as u64,
2418 });
2419 }
2420 tokio::time::sleep(Duration::from_millis(10)).await;
2421 }
2422 Err(e) => {
2423 return Err(NbError::Io {
2424 path: path.clone(),
2425 source: e.into(),
2426 });
2427 }
2428 }
2429 }
2430}
2431
2432#[derive(Debug, Clone)]
2434struct IndexPlacement {
2435 op_index: u32,
2436 folder: String,
2437 id: u32,
2438}
2439
2440fn apply_index_edits(
2451 notebook_root: &Path,
2452 pending: &[(u32, PendingIndexEdit)],
2453 contention_timeout: Duration,
2454) -> Result<Vec<IndexPlacement>, NbError> {
2455 let mut order: Vec<String> = Vec::new();
2457 let mut grouped: HashMap<String, Vec<(u32, &PendingIndexEdit)>> = HashMap::new();
2458 for (op_index, edit) in pending {
2459 grouped
2460 .entry(edit.file_rel.clone())
2461 .or_insert_with(|| {
2462 order.push(edit.file_rel.clone());
2463 Vec::new()
2464 })
2465 .push((*op_index, edit));
2466 }
2467 let mut placements: Vec<IndexPlacement> = Vec::new();
2468 for file_rel in &order {
2469 let edits = &grouped[file_rel];
2470 let abs = notebook_root.join(file_rel);
2471 let append_only = edits
2472 .iter()
2473 .all(|(_, e)| matches!(e.kind, PendingIndexKind::Append { .. }));
2474 if append_only {
2475 if let Some(parent) = abs.parent() {
2477 std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
2478 path: parent.to_path_buf(),
2479 source: e.into(),
2480 })?;
2481 }
2482 let mut f = OpenOptions::new()
2483 .create(true)
2484 .append(true)
2485 .open(&abs)
2486 .map_err(|e| NbError::Io {
2487 path: abs.clone(),
2488 source: e.into(),
2489 })?;
2490 for (op_index, edit) in edits {
2491 let PendingIndexKind::Append { basename } = &edit.kind else {
2492 unreachable!()
2493 };
2494 writeln!(f, "{basename}").map_err(|e| NbError::Io {
2495 path: abs.clone(),
2496 source: e.into(),
2497 })?;
2498 let _ = op_index;
2499 }
2500 } else {
2501 if let Some(parent) = abs.parent() {
2504 std::fs::create_dir_all(parent).map_err(|e| NbError::Io {
2505 path: parent.to_path_buf(),
2506 source: e.into(),
2507 })?;
2508 }
2509 let appends: Vec<&String> = edits
2510 .iter()
2511 .filter_map(|(_, e)| match &e.kind {
2512 PendingIndexKind::Append { basename } => Some(basename),
2513 _ => None,
2514 })
2515 .collect();
2516 let mutations: Vec<&PendingIndexEdit> = edits
2517 .iter()
2518 .map(|(_, e)| *e)
2519 .filter(|e| !matches!(e.kind, PendingIndexKind::Append { .. }))
2520 .collect();
2521 merge_index_rewrite(&abs, &appends, &mutations, contention_timeout)?;
2522 }
2523 let fresh = std::fs::read(&abs).map_err(|e| NbError::Io {
2525 path: abs.clone(),
2526 source: e.into(),
2527 })?;
2528 let lines = parse_index_lines(&fresh);
2529 for (op_index, edit) in edits {
2530 let (folder, basename) = match &edit.kind {
2531 PendingIndexKind::Append { basename } => {
2532 let (folder, _) =
2533 split_folder_basename(&pending_basename_path(file_rel, basename));
2534 (folder, basename.clone())
2535 }
2536 PendingIndexKind::Blank { basename } => {
2537 let (folder, _) =
2538 split_folder_basename(&pending_basename_path(file_rel, basename));
2539 (folder, basename.clone())
2540 }
2541 PendingIndexKind::Rename { new_basename, .. } => {
2542 let (folder, _) =
2543 split_folder_basename(&pending_basename_path(file_rel, new_basename));
2544 (folder, new_basename.clone())
2545 }
2546 };
2547 if let Some(pos) = lines.iter().rposition(|l| l == &basename) {
2548 placements.push(IndexPlacement {
2549 op_index: *op_index,
2550 folder,
2551 id: pos as u32 + 1,
2552 });
2553 } else if let PendingIndexKind::Blank { .. } = &edit.kind {
2554 let _ = folder;
2558 }
2559 }
2560 }
2561 Ok(placements)
2562}
2563
2564fn merge_index_rewrite(
2593 abs: &Path,
2594 appends: &[&String],
2595 mutations: &[&PendingIndexEdit],
2596 contention_timeout: Duration,
2597) -> Result<(), NbError> {
2598 use std::io::{Read as _, Seek as _, Write as _};
2599 let io_err = |e: std::io::Error| NbError::Io {
2600 path: abs.to_path_buf(),
2601 source: e.into(),
2602 };
2603 let mut fd = OpenOptions::new()
2604 .read(true)
2605 .write(true)
2606 .create(true)
2607 .truncate(false)
2608 .open(abs)
2609 .map_err(io_err)?;
2610 for _ in 0..25 {
2611 let s0 = fd.metadata().map_err(io_err)?.len();
2612 fd.seek(std::io::SeekFrom::Start(0)).map_err(io_err)?;
2613 let mut base = Vec::new();
2614 fd.read_to_end(&mut base).map_err(io_err)?;
2615 if fd.metadata().map_err(io_err)?.len() != s0 {
2616 continue; }
2618 #[cfg(feature = "testing")]
2619 if let Ok(ms) = std::env::var("NB_API_INDEX_SPLICE_PAUSE_MS")
2620 && let Ok(ms) = ms.parse::<u64>()
2621 {
2622 std::thread::sleep(Duration::from_millis(ms));
2626 }
2627 let mut lines = parse_index_lines(&base);
2628 for edit in mutations {
2629 match &edit.kind {
2630 PendingIndexKind::Append { .. } => {}
2631 PendingIndexKind::Blank { basename } => {
2632 if let Some(pos) = lines.iter().position(|l| l == basename) {
2633 lines[pos] = String::new();
2634 }
2635 }
2636 PendingIndexKind::Rename {
2637 old_basename,
2638 new_basename,
2639 } => {
2640 if let Some(pos) = lines.iter().position(|l| l == old_basename) {
2641 lines[pos] = new_basename.clone();
2642 }
2643 }
2644 }
2645 }
2646 for basename in appends {
2647 if !lines.iter().any(|l| l == *basename) {
2648 lines.push((*basename).clone());
2649 }
2650 }
2651 let rendered = render_index_lines(&lines);
2652 if rendered.as_slice() == base.as_slice() {
2653 return Ok(()); }
2655 if rendered.len() as u64 > s0 {
2656 fd.seek(std::io::SeekFrom::Start(0)).map_err(io_err)?;
2661 fd.write_all(&rendered).map_err(io_err)?;
2662 fd.set_len(rendered.len() as u64).map_err(io_err)?;
2663 if fd.metadata().map_err(io_err)?.len() == rendered.len() as u64 {
2664 return Ok(());
2665 }
2666 continue;
2667 }
2668 let prefix_len = rendered.len() as u64;
2671 fd.seek(std::io::SeekFrom::Start(0)).map_err(io_err)?;
2672 fd.write_all(&rendered).map_err(io_err)?;
2673 if fd.metadata().map_err(io_err)?.len() != s0 {
2674 continue; }
2676 let s1 = fd.metadata().map_err(io_err)?.len();
2678 fd.seek(std::io::SeekFrom::Start(s0)).map_err(io_err)?;
2679 if fd.metadata().map_err(io_err)?.len() != s1 {
2680 continue;
2681 }
2682 let mut tail = Vec::new();
2683 let mut take = (s1 - s0) as usize;
2684 while take > 0 {
2685 let mut chunk = vec![0u8; take.min(8192)];
2686 let n = fd.read(&mut chunk).map_err(io_err)?;
2687 if n == 0 {
2688 break;
2689 }
2690 tail.extend_from_slice(&chunk[..n]);
2691 take -= n;
2692 }
2693 if fd.metadata().map_err(io_err)?.len() != s1 {
2694 continue;
2695 }
2696 #[cfg(feature = "testing")]
2697 if let Ok(ms) = std::env::var("NB_API_INDEX_SPLICE_PAUSE_MS")
2698 && let Ok(ms) = ms.parse::<u64>()
2699 {
2700 std::thread::sleep(Duration::from_millis(ms));
2704 }
2705 fd.seek(std::io::SeekFrom::Start(prefix_len))
2706 .map_err(io_err)?;
2707 fd.write_all(&tail).map_err(io_err)?;
2708 let tail_len = tail.len() as u64;
2715 let stale_len = s0.saturating_sub(prefix_len + tail_len);
2716 let expected = prefix_len + (s1 - s0);
2717 let collapsed = collapse_stale_range(&fd, prefix_len + tail_len, stale_len);
2718 if !collapsed {
2719 fd.set_len(prefix_len + tail_len).map_err(io_err)?;
2723 }
2724 if fd.metadata().map_err(io_err)?.len() == expected {
2725 return Ok(());
2726 }
2727 }
2729 Err(NbError::IndexLockTimeout {
2730 path: abs.to_string_lossy().into_owned(),
2731 timeout_ms: contention_timeout.as_millis() as u64,
2732 })
2733}
2734
2735#[cfg(target_os = "linux")]
2748fn collapse_stale_range(fd: &std::fs::File, offset: u64, len: u64) -> bool {
2749 use std::os::fd::AsRawFd;
2750 if len == 0 {
2751 return true;
2752 }
2753 const FALLOC_FL_COLLAPSE_RANGE: libc::c_int = 0x08;
2754 let r = unsafe {
2755 libc::fallocate(
2756 fd.as_raw_fd(),
2757 FALLOC_FL_COLLAPSE_RANGE,
2758 offset as libc::off_t,
2759 len as libc::off_t,
2760 )
2761 };
2762 r == 0
2763}
2764
2765#[cfg(not(target_os = "linux"))]
2768fn collapse_stale_range(_fd: &std::fs::File, _offset: u64, _len: u64) -> bool {
2769 false
2770}
2771
2772fn pending_basename_path(file_rel: &str, basename: &str) -> String {
2774 if file_rel == ".index" {
2775 basename.to_string()
2776 } else if let Some(folder) = file_rel.strip_suffix("/.index") {
2777 format!("{folder}/{basename}")
2778 } else {
2779 basename.to_string()
2780 }
2781}
2782
2783fn index_id_on_disk(notebook_root: &Path, rel_path: &str) -> Option<u32> {
2786 let (folder, basename) = split_folder_basename(rel_path);
2787 index_id_in_folder(notebook_root, &folder, &basename)
2788}
2789
2790pub(crate) fn index_id_in_folder(
2792 notebook_root: &Path,
2793 folder: &str,
2794 basename: &str,
2795) -> Option<u32> {
2796 let abs = notebook_root.join(index_rel_for_folder(folder));
2797 let bytes = std::fs::read(abs).ok()?;
2798 parse_index_lines(&bytes)
2799 .iter()
2800 .position(|l| l == basename)
2801 .map(|p| p as u32 + 1)
2802}