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 nbrc;
28mod output;
29pub mod parser;
30pub(crate) mod scope;
31pub(crate) mod tokenizer;
32mod transaction;
33mod types;
34mod validate;
35
36#[cfg(feature = "testing")]
37pub mod testing;
38
39#[cfg(feature = "testing")]
40pub use gate::registry_len;
41
42pub use error::{IoError, IoErrorKind, NbError, ParseErrorKind};
43pub use fingerprint::{Fingerprint, fingerprint as compute_fingerprint};
44pub use git::{derive_git_notebook_name, git_rev_parse};
45pub use git_env::{leaked_git_names, scrub_git_env, scrub_git_env_std};
46pub use parser::{
47    BodyFragments, DocumentKind, NoteDocument, ParseContext,
48    SUPPORTED_DOCUMENT_EXTENSIONS, TagsIter, TagsStrIter, TodoState, parse,
49};
50pub use transaction::Transaction;
51pub use types::{
52    BodyFragment, BoundaryAt, Classify, CommitOutcome, EntityKind, KindSet,
53    LineAnchor, LineEdit, LineEol, LinePosition, LineRef, ListEntry, NoteLine,
54    NoteLineHit, NoteTarget, Occurrence, OpOutcome, SearchNoteLines, ShowNote,
55    ShowNoteLines, TodoSummary,
56};
57
58use serde::Deserialize;
59use std::time::Duration;
60
61/// Configuration for constructing an [`NbClient`].
62///
63/// Contains only nb-relevant fields. MCP-specific fields
64/// (e.g., `show_paths`) remain in the server's config.
65#[derive(Clone, Debug)]
66pub struct Config {
67    /// Default notebook name (overrides Git-derived fallback).
68    pub notebook: Option<String>,
69    /// Automatically create missing notebooks.
70    pub create_notebook: bool,
71    /// Refuse the file default when `NB_DIR` is unset: embedders
72    /// that assign the notebook store themselves set this to keep
73    /// resolution explicit and never read `~/.nbrc`.
74    ///
75    /// With the default `false`, an unset or empty `NB_DIR` falls
76    /// back to the parsed `~/.nbrc` (`$NBRC_PATH`) value, else
77    /// `~/.nb`. The rc is parsed, never executed: supported
78    /// forms are unconditional top-level `NB_DIR` assignments
79    /// (bare and `export`, last wins, with `$NB_DIR` self-default
80    /// tracking); anything undeterminable without execution warns
81    /// and falls back to `~/.nb` instead of resolving elsewhere.
82    /// Spawned `nb` subprocesses keep their existing routing
83    /// (they inherit the process environment and source the rc
84    /// themselves); this flag only governs native resolution.
85    pub require_explicit_nb_dir: bool,
86    /// Allow new notes to be created at notebook root.
87    pub allow_top_level_notes: bool,
88    /// Disable Git commit and tag signing for `nb` subprocesses.
89    pub disable_git_signing: bool,
90    /// Maximum time to wait on the process-shared gate queue.
91    pub gate_timeout: Duration,
92}
93
94impl Default for Config {
95    fn default() -> Self {
96        Self {
97            notebook: None,
98            create_notebook: true,
99            require_explicit_nb_dir: false,
100            allow_top_level_notes: false,
101            disable_git_signing: false,
102            gate_timeout: gate::DEFAULT_GATE_TIMEOUT,
103        }
104    }
105}
106
107/// Client for invoking nb commands.
108#[derive(Clone)]
109pub struct NbClient {
110    /// Default notebook to use if not specified per-command.
111    default_notebook: Option<String>,
112    /// Automatically create missing notebooks.
113    create_notebook: bool,
114    /// Refuse the file default when `NB_DIR` is unset.
115    require_explicit_nb_dir: bool,
116    /// Disable Git commit and tag signing for `nb` subprocesses.
117    disable_git_signing: bool,
118    /// Allow new notes to be created at notebook root.
119    allow_top_level_notes: bool,
120    /// Gate queue timeout.
121    gate_timeout: Duration,
122}
123
124/// Matching mode for `nb search` query terms.
125#[derive(Debug, Clone, Copy, Default, Deserialize, PartialEq, Eq)]
126#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
127#[serde(rename_all = "lowercase")]
128pub enum SearchMode {
129    /// Match any query term (`OR` semantics).
130    #[default]
131    Any,
132    /// Require all query terms (`AND` semantics).
133    All,
134}
135
136/// Status filter for `nb tasks`.
137#[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
138#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
139#[serde(rename_all = "lowercase")]
140pub enum TaskStatus {
141    /// Return open tasks.
142    Open,
143    /// Return closed tasks.
144    Closed,
145}