Skip to main content

NbClient

Struct NbClient 

Source
pub struct NbClient { /* private fields */ }
Expand description

Client for invoking nb commands.

Implementations§

Source§

impl NbClient

Source

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.

Source

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.

Source

pub fn gate_timeout(&self) -> Duration

Process-shared gate queue timeout configured on this client.

Source§

impl NbClient

Source

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.)

Source

pub async fn list_notebooks(&self) -> Result<String, NbError>

Lists available notebooks.

Source

pub async fn show_notebook_path( &self, notebook: Option<&str>, ) -> Result<PathBuf, NbError>

Returns the path for a notebook.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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).

Source

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.

Source

pub async fn search_notes( &self, queries: &[String], mode: SearchMode, tags: &[String], folder: Option<&str>, notebook: Option<&str>, ) -> Result<String, NbError>

Searches notes.

Source

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.

Source

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

Source

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).

Source

pub async fn delete_note( &self, id: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>

Deletes a note (one-shot transaction).

Source

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.

Source

pub async fn move_note( &self, id: &str, destination: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>

Moves or renames a note (one-shot transaction).

Source

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).

Source

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).

Source

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).

Source

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).

Source

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).

Source

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).

Source

pub async fn retitle_note( &self, target: NoteTarget, title: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>

Retitle a note without changing path (one-shot).

Source

pub async fn edit_note_tags( &self, target: NoteTarget, add: &[String], remove: &[String], notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>

Add/remove tags (one-shot).

Source

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).

Source

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.

Source

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.

Source

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).

Source

pub async fn list_folders( &self, parent: Option<&str>, notebook: Option<&str>, ) -> Result<String, NbError>

Lists folders in a notebook.

Source

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.

Source

pub async fn add_folder( &self, path: &str, notebook: Option<&str>, ) -> Result<CommitOutcome, NbError>

Creates a folder (one-shot transaction).

Source

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.

Trait Implementations§

Source§

impl Clone for NbClient

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more