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