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}