Skip to main content

nb_api/
lib.rs

1//! Typed Rust interface to the `nb` note-taking CLI.
2//!
3//! Handles notebook qualification, escaping, and output parsing.
4//! Wraps the `nb` CLI as a subprocess, providing async methods for
5//! all note-taking operations.
6//!
7//! # Concurrency (0.3.0)
8//!
9//! Notebook-scoped reads and [`Transaction::commit`] are serialized by a
10//! **process-shared**, **in-process** gate registry keyed by the realpath of
11//! the notebook Git common directory. Independently constructed [`NbClient`]
12//! values that resolve to the same repository share one gate. Cross-process
13//! `index.lock` wait is deferred.
14
15mod argv;
16mod client;
17mod diagnostics;
18mod error;
19pub mod fingerprint;
20mod gate;
21mod git;
22mod git_env;
23mod git_signing;
24mod lines;
25mod native;
26mod nb_program;
27mod output;
28pub mod parser;
29pub(crate) mod scope;
30pub(crate) mod tokenizer;
31mod transaction;
32mod types;
33mod validate;
34
35#[cfg(feature = "testing")]
36pub mod testing;
37
38#[cfg(feature = "testing")]
39pub use gate::registry_len;
40
41pub use error::{IoError, IoErrorKind, NbError, ParseErrorKind};
42pub use fingerprint::{Fingerprint, fingerprint as compute_fingerprint};
43pub use git::{derive_git_notebook_name, git_rev_parse};
44pub use git_env::{leaked_git_names, scrub_git_env, scrub_git_env_std};
45pub use parser::{
46    BodyFragments, DocumentKind, NoteDocument, ParseContext,
47    SUPPORTED_DOCUMENT_EXTENSIONS, TagsIter, TagsStrIter, TodoState, parse,
48};
49pub use transaction::Transaction;
50pub use types::{
51    BodyFragment, BoundaryAt, Classify, CommitOutcome, EntityKind, KindSet,
52    LineAnchor, LineEdit, LineEol, LinePosition, LineRef, ListEntry, NoteLine,
53    NoteLineHit, NoteTarget, Occurrence, OpOutcome, SearchNoteLines, ShowNote,
54    ShowNoteLines, TodoSummary,
55};
56
57use serde::Deserialize;
58use std::time::Duration;
59
60/// Configuration for constructing an [`NbClient`].
61///
62/// Contains only nb-relevant fields. MCP-specific fields
63/// (e.g., `show_paths`) remain in the server's config.
64#[derive(Clone, Debug)]
65pub struct Config {
66    /// Default notebook name (overrides Git-derived fallback).
67    pub notebook: Option<String>,
68    /// Automatically create missing notebooks.
69    pub create_notebook: bool,
70    /// Allow new notes to be created at notebook root.
71    pub allow_top_level_notes: bool,
72    /// Disable Git commit and tag signing for `nb` subprocesses.
73    pub disable_git_signing: bool,
74    /// Maximum time to wait on the process-shared gate queue.
75    pub gate_timeout: Duration,
76}
77
78impl Default for Config {
79    fn default() -> Self {
80        Self {
81            notebook: None,
82            create_notebook: true,
83            allow_top_level_notes: false,
84            disable_git_signing: false,
85            gate_timeout: gate::DEFAULT_GATE_TIMEOUT,
86        }
87    }
88}
89
90/// Client for invoking nb commands.
91#[derive(Clone)]
92pub struct NbClient {
93    /// Default notebook to use if not specified per-command.
94    default_notebook: Option<String>,
95    /// Automatically create missing notebooks.
96    create_notebook: bool,
97    /// Disable Git commit and tag signing for `nb` subprocesses.
98    disable_git_signing: bool,
99    /// Allow new notes to be created at notebook root.
100    allow_top_level_notes: bool,
101    /// Gate queue timeout.
102    gate_timeout: Duration,
103}
104
105/// Matching mode for `nb search` query terms.
106#[derive(Debug, Clone, Copy, Default, Deserialize, PartialEq, Eq)]
107#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
108#[serde(rename_all = "lowercase")]
109pub enum SearchMode {
110    /// Match any query term (`OR` semantics).
111    #[default]
112    Any,
113    /// Require all query terms (`AND` semantics).
114    All,
115}
116
117/// Status filter for `nb tasks`.
118#[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
119#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
120#[serde(rename_all = "lowercase")]
121pub enum TaskStatus {
122    /// Return open tasks.
123    Open,
124    /// Return closed tasks.
125    Closed,
126}