1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
//! Output sanitization helpers for `nb-api` consumers.
//!
//! Strips the trailing usage/help hint block from raw `nb`
//! CLI output when an empty result is detected. Requires
//! **structural evidence of a native hint block** (signal
//! line + blank separator + at least one recognized hint
//! marker) before truncating; otherwise returns input
//! unchanged. False negatives preferred over destructive
//! output loss.
//!
//! # Background
//!
//! `nb` CLI emits a trailing usage/help hint block after
//! some empty-result signals. For example, `nb ls` on an
//! empty notebook produces:
//!
//! ```text
//! 0 items.
//!
//! Add a note:
//! nb add scratch:
//! Add a bookmark:
//! nb scratch: <url>
//! ...
//! ```
//!
//! Consumers integrating against `nb-api` should not see
//! the hint block; only the empty-result signal is part of
//! the API contract. The hint block is widely recognized as
//! an `nb` CLI quirk, not a stable surface.
//!
//! # Why structural evidence, not just signal matching
//!
//! An empty-result signal like `0 items.` is also a
//! legitimate prefix for user-authored content (a note
//! whose first line is `0 items.`). If the helper matched
//! on signal alone, it could corrupt user content. The
//! structural-evidence requirement — signal + blank
//! separator + recognized hint markers — ensures the
//! helper only acts when the trailing block is unambiguously
//! the native `nb` hint block.
//!
//! # Why wrapper post-processing, not a native `nb` flag
//!
//! The design note `add-0-2-0-foundation/designs/2` D2 notes
//! "investigate whether `nb` exposes a flag to suppress the
//! hint. If yes, prefer the flag over wrapper
//! post-processing." As of `nb 7.24.0` (the version pinned by
//! `qa`), `nb ls` / `nb ls --type folder` / `nb bookmark`
//! have NO flag to suppress the hint block. The wrapper
//! approach is therefore the canonical implementation. The
//! spec scenario "Hint block is preserved if nb CLI exposes
//! a flag to suppress it natively" leaves room for switching
//! to a native flag in a future `nb` release.
//!
//! # Method coverage
//!
//! The helper is applied ONLY to list-style methods that
//! empirically emit the hint block:
//! - `NbClient::list_notes` (handles `0 items.`)
//! - `NbClient::list_folders` (handles `0 folders.`)
//!
//! The helper is NOT applied to:
//! - User-content methods (`show_note`, `add_note`,
//! `edit_note`, `delete_note`, `move_note`, `import_note`,
//! etc.) — these return user content, not list output, and a
//! note whose first line is `0 items.` would be wrongly
//! truncated.
//! - `NbClient::list_tasks` (returns the normalized empty signal,
//! e.g. `0 open tasks.` plus its terminator, for empty scopes)
//! - `NbClient::search_notes` no-match — `! Not found in
//! <notebook>: <query>` propagates as `CommandFailed`,
//! preserved as a distinct contract (not a helper
//! pass-through).
//!
//! # Server-side duplication
//!
//! The `output-behavior` specification scenario "Server-side
//! and API-side sanitization are independent" recommends
//! that `nb-mcp-server` MAY apply its own sanitization for
//! error-presentation quality (showing users clean output),
//! but should not duplicate the parser logic verbatim to
//! avoid drift from `nb-api`. If `nb-mcp-server` chooses
//! to apply server-side sanitization, it should be a thin
//! error-presentation wrapper (e.g., a server-side
//! fallback when `nb-api`'s output is wrong), not a
//! duplicate parser.
// Strip the trailing usage/help hint block from `nb` output
// when there is **structural evidence** of a native hint block:
// signal line, blank separator, at least one recognized hint
// marker. Otherwise returns input unchanged.
//
// **Detection rule:**
// 1. First line is a `0 <kind>.` signal (starts with `0 `,
// ends with `.`).
// 2. The line following the signal is blank (a blank
// separator, per `nb`'s hint-block convention).
// 3. At least one line in the trailing block is a recognized
// hint marker: starts with `Add a `, `Add an `,
// `Import a `, or `Help information:`.
//
// All three must hold. Any failure returns input unchanged.
//
// **Terminator preservation:** the helper preserves the
// signal's exact terminator (LF, CRLF, or none). When
// truncating, the result includes the signal line up to and
// including its terminator, with no characters appended.
pub
// NOTE: AGENTS.md requires inline `#[cfg(test)]` modules to
// satisfy ALL of: (1) tested item is crate-private by design,
// (2) no existing public interface exercises the same code
// path, (3) at most ONE `#[test]` function. Condition (2)
// fails for this helper because `NbClient::list_notes` and
// `NbClient::list_folders` invoke it publicly. Per the AGENTS.md
// guidance ("Do not default to inline to avoid that
// conversation; the friction is intentional"), all helper
// coverage is exercised via the public list-notes/list-folders
// behavior in `tests/integration/empty_result_hints.rs`, using a
// deterministic `nb` shim in PATH (see
// `tests/integration/common/mod.rs::with_shim_nb_env`) to
// emit crafted list output for the LF / CRLF / no-terminator
// / no-recognized-marker cases that real `nb` does not
// produce.