pub struct NbClient { /* private fields */ }Expand description
Client for invoking nb commands.
Implementations§
Source§impl NbClient
impl NbClient
Sourcepub fn new(config: &Config) -> Result<Self>
pub fn new(config: &Config) -> Result<Self>
Creates a new nb client.
Uses the notebook from config if set, otherwise falls back to a
Git-derived notebook name. Does NOT read NB_MCP_NOTEBOOK —
that is an MCP-server-specific env var resolved by the server.
Sourcepub async fn transaction(
&self,
notebook: Option<&str>,
) -> Result<Transaction, NbError>
pub async fn transaction( &self, notebook: Option<&str>, ) -> Result<Transaction, NbError>
Begin a collect-then-commit Transaction for notebook.
Construction performs no durable I/O and does not acquire the gate.
Sourcepub fn gate_timeout(&self) -> Duration
pub fn gate_timeout(&self) -> Duration
Process-shared gate queue timeout configured on this client.
Source§impl NbClient
impl NbClient
Sourcepub async fn show_notebook_status(
&self,
notebook: Option<&str>,
) -> Result<String, NbError>
pub async fn show_notebook_status( &self, notebook: Option<&str>, ) -> Result<String, NbError>
Notebook status from git state, without spawning nb:
porcelain output for the notebook worktree, plus the
index-only reconciliation note when no note content is
affected. A missing notebook is terminal NotFound, never
created. (Pre-1.0 break: replaces the verbatim nb status
rendering.)
Sourcepub async fn list_notebooks(&self) -> Result<String, NbError>
pub async fn list_notebooks(&self) -> Result<String, NbError>
Lists available notebooks.
Sourcepub async fn show_notebook_path(
&self,
notebook: Option<&str>,
) -> Result<PathBuf, NbError>
pub async fn show_notebook_path( &self, notebook: Option<&str>, ) -> Result<PathBuf, NbError>
Returns the path for a notebook.
Sourcepub async fn show_note(
&self,
id: &str,
notebook: Option<&str>,
) -> Result<ShowNote, NbError>
pub async fn show_note( &self, id: &str, notebook: Option<&str>, ) -> Result<ShowNote, NbError>
Shows a note as a structured ShowNote (gate-held).
Reads resolve via the notebook filesystem plus .index
under one no-ensure gate hold, spawning zero nb
subprocesses. Plain string ids always carry selector
semantics.
Sourcepub async fn classify(
&self,
id: &str,
notebook: Option<&str>,
) -> Result<Classify, NbError>
pub async fn classify( &self, id: &str, notebook: Option<&str>, ) -> Result<Classify, NbError>
Classify one id without reading content beyond
classification: kind, notebook-relative path, shadow-aware
canonical selector, and numeric id when listed. Plain ids
carry selector semantics; notebook qualification resolves
upstream. Side-effect-free: filesystem plus .index under
the gate, zero spawns.
Sourcepub async fn read_note_source_bytes(
&self,
target: NoteTarget,
notebook: Option<&str>,
) -> Result<Vec<u8>, NbError>
pub async fn read_note_source_bytes( &self, target: NoteTarget, notebook: Option<&str>, ) -> Result<Vec<u8>, NbError>
Raw-bytes escape hatch: full file bytes without UTF-8 validation.
This is the only public read that returns Vec<u8>; every other
structured read is text-only and returns NonUtf8 on invalid UTF-8.
Sourcepub async fn show_note_lines(
&self,
target: NoteTarget,
offset: Option<u32>,
limit: Option<u32>,
notebook: Option<&str>,
) -> Result<ShowNoteLines, NbError>
pub async fn show_note_lines( &self, target: NoteTarget, offset: Option<u32>, limit: Option<u32>, notebook: Option<&str>, ) -> Result<ShowNoteLines, NbError>
Enumerate body lines for a contiguous-body note.
Sourcepub async fn search_note_lines(
&self,
target: NoteTarget,
pattern: &str,
notebook: Option<&str>,
) -> Result<SearchNoteLines, NbError>
pub async fn search_note_lines( &self, target: NoteTarget, pattern: &str, notebook: Option<&str>, ) -> Result<SearchNoteLines, NbError>
Search body line texts for a pattern (contiguous body only).
Sourcepub async fn list_notes(
&self,
folder: Option<&str>,
tags: &[String],
limit: Option<u32>,
notebook: Option<&str>,
) -> Result<String, NbError>
pub async fn list_notes( &self, folder: Option<&str>, tags: &[String], limit: Option<u32>, notebook: Option<&str>, ) -> Result<String, NbError>
Lists notes in a notebook or folder.
Sourcepub async fn search_notes(
&self,
queries: &[String],
mode: SearchMode,
tags: &[String],
folder: Option<&str>,
notebook: Option<&str>,
) -> Result<String, NbError>
pub async fn search_notes( &self, queries: &[String], mode: SearchMode, tags: &[String], folder: Option<&str>, notebook: Option<&str>, ) -> Result<String, NbError>
Searches notes.
Sourcepub async fn search_notes_typed(
&self,
queries: &[String],
mode: SearchMode,
tags: &[String],
folder: Option<&str>,
notebook: Option<&str>,
) -> Result<Vec<ListEntry>, NbError>
pub async fn search_notes_typed( &self, queries: &[String], mode: SearchMode, tags: &[String], folder: Option<&str>, notebook: Option<&str>, ) -> Result<Vec<ListEntry>, NbError>
Searches notes natively: recursive text-file walk under the
scope, case-insensitive substring match of the queries
against title plus body text (Any/All across queries),
tag-filtered like the typed list. Returns lexical
crate::ListEntry values. Empty queries are
ValidationError. Zero nb spawns.
Sourcepub async fn list_notes_typed(
&self,
folder: Option<&str>,
tags: &[String],
limit: Option<u32>,
notebook: Option<&str>,
) -> Result<Vec<ListEntry>, NbError>
pub async fn list_notes_typed( &self, folder: Option<&str>, tags: &[String], limit: Option<u32>, notebook: Option<&str>, ) -> Result<Vec<ListEntry>, NbError>
Lists notes in a notebook or folder as typed entries:
one crate::ListEntry per file directly under the scope
(non-recursive), excluding dotfiles and symlinks, ordered
lexically by relative path. Tags filter by parsed document
tags (all must match); limit takes the first N. A missing
scope is terminal NotFound. Zero nb spawns.
Source§impl NbClient
impl NbClient
Sourcepub async fn add_note(
&self,
title: Option<&str>,
content: &str,
tags: &[String],
folder: Option<&str>,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn add_note( &self, title: Option<&str>, content: &str, tags: &[String], folder: Option<&str>, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Creates a new note (one-shot transaction; nb-mangled filename).
Sourcepub async fn delete_note(
&self,
id: &str,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn delete_note( &self, id: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Deletes a note (one-shot transaction).
Sourcepub async fn delete_folder(
&self,
id: &str,
recursive: bool,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn delete_folder( &self, id: &str, recursive: bool, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Deletes a folder (one-shot transaction).
recursive = false refuses non-empty folders, listing their
contents; recursive = true removes the whole subtree. There
is no force flag: deletion is explicit by call.
Sourcepub async fn move_note(
&self,
id: &str,
destination: &str,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn move_note( &self, id: &str, destination: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Moves or renames a note (one-shot transaction).
Sourcepub async fn add_todo(
&self,
title: &str,
description: Option<&str>,
tasks: &[String],
tags: &[String],
folder: Option<&str>,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn add_todo( &self, title: &str, description: Option<&str>, tasks: &[String], tags: &[String], folder: Option<&str>, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Creates a todo item (one-shot transaction; nb-mangled filename).
Sourcepub async fn mark_task_done(
&self,
id: &str,
task_number: Option<u32>,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn mark_task_done( &self, id: &str, task_number: Option<u32>, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Marks a todo as done (one-shot transaction).
Sourcepub async fn unmark_task_done(
&self,
id: &str,
task_number: Option<u32>,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn unmark_task_done( &self, id: &str, task_number: Option<u32>, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Marks a todo as not done (one-shot transaction).
Sourcepub async fn replace_note_body(
&self,
target: NoteTarget,
new_body: &str,
fingerprint: Fingerprint,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn replace_note_body( &self, target: NoteTarget, new_body: &str, fingerprint: Fingerprint, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Replace contiguous body text (one-shot).
Sourcepub async fn edit_note_substring(
&self,
target: NoteTarget,
pattern: &str,
replacement: &str,
occurrence: Occurrence,
expected_count: u32,
fingerprint: Option<Fingerprint>,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn edit_note_substring( &self, target: NoteTarget, pattern: &str, replacement: &str, occurrence: Occurrence, expected_count: u32, fingerprint: Option<Fingerprint>, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Substring edit on contiguous body (one-shot).
Sourcepub async fn edit_note_lines(
&self,
target: NoteTarget,
edits: Vec<LineEdit>,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn edit_note_lines( &self, target: NoteTarget, edits: Vec<LineEdit>, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Line-oriented body edit batch (one-shot).
Sourcepub async fn retitle_note(
&self,
target: NoteTarget,
title: &str,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn retitle_note( &self, target: NoteTarget, title: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Retitle a note without changing path (one-shot).
Add/remove tags (one-shot).
Sourcepub async fn list_tasks(
&self,
folder: Option<&str>,
status: Option<TaskStatus>,
recursive: bool,
notebook: Option<&str>,
) -> Result<String, NbError>
pub async fn list_tasks( &self, folder: Option<&str>, status: Option<TaskStatus>, recursive: bool, notebook: Option<&str>, ) -> Result<String, NbError>
Lists checklist items within todos.
Invokes nb todos tasks per scope. The method enumerates
the checklist items within todos (and recursively into
subfolders when recursive = true), filtered by
status if provided. An empty scope returns the empty
signal (0 open tasks.) rather than an error. A future
list_todos method for the todo container listing
(invoking nb todos) is tracked at
nb-api:todos/api/5 (deferred to 0.5.0).
Sourcepub async fn list_tasks_typed(
&self,
folder: Option<&str>,
status: Option<TaskStatus>,
recursive: bool,
notebook: Option<&str>,
) -> Result<Vec<ListEntry>, NbError>
pub async fn list_tasks_typed( &self, folder: Option<&str>, status: Option<TaskStatus>, recursive: bool, notebook: Option<&str>, ) -> Result<Vec<ListEntry>, NbError>
Lists todo checklist items natively: one crate::ListEntry
per - [ ] / - [x] / - [X] item in .todo.md files
under the scope (recursive iff set), in file order with
1-based task positions. Selectors append #task-<n> to the
shadow-aware canonical file selector; kind is Todo and
numeric_id rides along from the file. status filters by
item state (None keeps all). Scopes skip dotfiles and
symlinks; a missing scope is terminal NotFound. Zero nb
spawns.
Sourcepub async fn list_todos(
&self,
folder: Option<&str>,
state: Option<TodoState>,
recursive: bool,
notebook: Option<&str>,
) -> Result<Vec<TodoSummary>, NbError>
pub async fn list_todos( &self, folder: Option<&str>, state: Option<TodoState>, recursive: bool, notebook: Option<&str>, ) -> Result<Vec<TodoSummary>, NbError>
Lists todo files as summaries: one crate::TodoSummary per
.todo.md file under the scope (recursive iff set) with task
counts and derived state (Done iff at least one item exists
and all are completed, else Open). state filters files
(None keeps all). Titles are checkbox-stripped and trimmed,
falling back to the filename. Zero nb spawns.
Sourcepub async fn add_bookmark(
&self,
url: &str,
title: Option<&str>,
tags: &[String],
comment: Option<&str>,
folder: Option<&str>,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn add_bookmark( &self, url: &str, title: Option<&str>, tags: &[String], comment: Option<&str>, folder: Option<&str>, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Creates a bookmark (one-shot transaction; nb-mangled filename).
Sourcepub async fn list_folders(
&self,
parent: Option<&str>,
notebook: Option<&str>,
) -> Result<String, NbError>
pub async fn list_folders( &self, parent: Option<&str>, notebook: Option<&str>, ) -> Result<String, NbError>
Lists folders in a notebook.
Sourcepub async fn list_folders_typed(
&self,
parent: Option<&str>,
notebook: Option<&str>,
) -> Result<Vec<ListEntry>, NbError>
pub async fn list_folders_typed( &self, parent: Option<&str>, notebook: Option<&str>, ) -> Result<Vec<ListEntry>, NbError>
Lists folders in a notebook as typed entries: one
crate::ListEntry per direct child directory of the
scope (non-recursive), excluding dot-directories, ordered
lexically by relative path. Each entry is kind Folder
with the exact-path selector and no numeric id. A missing
scope is terminal NotFound. Zero nb spawns.
Sourcepub async fn add_folder(
&self,
path: &str,
notebook: Option<&str>,
) -> Result<CommitOutcome, NbError>
pub async fn add_folder( &self, path: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>
Creates a folder (one-shot transaction).
Sourcepub async fn import_note(
&self,
source: &str,
folder: Option<&str>,
filename: Option<&str>,
convert: bool,
notebook: Option<&str>,
) -> Result<String, NbError>
pub async fn import_note( &self, source: &str, folder: Option<&str>, filename: Option<&str>, convert: bool, notebook: Option<&str>, ) -> Result<String, NbError>
Imports a file or URL into the notebook as a note.
One-shot only under the process-shared notebook gate. Not a
Transaction plan op in 0.3.0.
NOTE (0.4.3, evaluated): nb import accepts no --wait
flag — an unknown flag would be misparsed as an import
path — and a standalone nb git checkpoint --wait cannot
join the import’s already-backgrounded checkpoint job, so
there is no --wait containment for the import race window.
Containment waits on 0.5.0 (native import with proper
locking); meanwhile the commit guard absorbs index-only
droppings and note-content leftovers still refuse loudly.