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 nb_program;
26mod output;
27pub mod parser;
28pub(crate) mod tokenizer;
29mod transaction;
30mod types;
31mod validate;
32
33#[cfg(feature = "testing")]
34pub mod testing;
35
36#[cfg(feature = "testing")]
37pub use gate::registry_len;
38
39pub use error::{IoError, IoErrorKind, NbError, ParseErrorKind};
40pub use fingerprint::{Fingerprint, fingerprint as compute_fingerprint};
41pub use git::{derive_git_notebook_name, git_rev_parse};
42pub use git_env::{leaked_git_names, scrub_git_env, scrub_git_env_std};
43pub use parser::{
44    BodyFragments, DocumentKind, NoteDocument, ParseContext,
45    SUPPORTED_DOCUMENT_EXTENSIONS, TagsIter, TagsStrIter, TodoState, parse,
46};
47pub use transaction::Transaction;
48pub use types::{
49    BodyFragment, BoundaryAt, CommitOutcome, LineAnchor, LineEdit, LineEol,
50    LinePosition, LineRef, NoteLine, NoteLineHit, NoteTarget, Occurrence,
51    OpOutcome, SearchNoteLines, ShowNote, ShowNoteLines,
52};
53
54use serde::Deserialize;
55use std::time::Duration;
56
57/// Configuration for constructing an [`NbClient`].
58///
59/// Contains only nb-relevant fields. MCP-specific fields
60/// (e.g., `show_paths`) remain in the server's config.
61#[derive(Clone, Debug)]
62pub struct Config {
63    /// Default notebook name (overrides Git-derived fallback).
64    pub notebook: Option<String>,
65    /// Automatically create missing notebooks.
66    pub create_notebook: bool,
67    /// Allow new notes to be created at notebook root.
68    pub allow_top_level_notes: bool,
69    /// Disable Git commit and tag signing for `nb` subprocesses.
70    pub disable_git_signing: bool,
71    /// Maximum time to wait on the process-shared gate queue.
72    pub gate_timeout: Duration,
73}
74
75impl Default for Config {
76    fn default() -> Self {
77        Self {
78            notebook: None,
79            create_notebook: true,
80            allow_top_level_notes: false,
81            disable_git_signing: false,
82            gate_timeout: gate::DEFAULT_GATE_TIMEOUT,
83        }
84    }
85}
86
87/// Client for invoking nb commands.
88#[derive(Clone)]
89pub struct NbClient {
90    /// Default notebook to use if not specified per-command.
91    default_notebook: Option<String>,
92    /// Automatically create missing notebooks.
93    create_notebook: bool,
94    /// Disable Git commit and tag signing for `nb` subprocesses.
95    disable_git_signing: bool,
96    /// Allow new notes to be created at notebook root.
97    allow_top_level_notes: bool,
98    /// Gate queue timeout.
99    gate_timeout: Duration,
100}
101
102/// Matching mode for `nb search` query terms.
103#[derive(Debug, Clone, Copy, Default, Deserialize, PartialEq, Eq)]
104#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
105#[serde(rename_all = "lowercase")]
106pub enum SearchMode {
107    /// Match any query term (`OR` semantics).
108    #[default]
109    Any,
110    /// Require all query terms (`AND` semantics).
111    All,
112}
113
114/// Status filter for `nb tasks`.
115#[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)]
116#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
117#[serde(rename_all = "lowercase")]
118pub enum TaskStatus {
119    /// Return open tasks.
120    Open,
121    /// Return closed tasks.
122    Closed,
123}