doiget-cli 0.7.0

doiget CLI binary
Documentation 
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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302

//! End-to-end wiremock test for `doiget text` — full-text extraction from
//! ar5iv (the #281 "read" step; ADR-0032).
//!
//! ## What is exercised
//!
//! - `doiget_cli::commands::text::run` end-to-end: `build_resolve_context`
//!   → `paper_text::paper_text` → wiremock ar5iv → on-disk text cache.
//! - The ar5iv `/html/<id>` call path reached via the `DOIGET_AR5IV_BASE`
//!   override (no env-var capability gate — ADR-0032 D2: full-text
//!   extraction is Tier-1, always-on).
//! - The provenance contract: one `Fetch` row under `source = "ar5iv"`.
//! - The cache contract: a `<cache_root>/text/<safekey>.json` entry is
//!   written, and a second run is served from it (the wiremock mock is
//!   single-shot).
//!
//! ## Network purity
//!
//! No outbound calls: all HTTP terminates at a `wiremock::MockServer` on
//! `127.0.0.1:N`, reached via `DOIGET_AR5IV_BASE`.

#![allow(clippy::expect_used, clippy::unwrap_used, clippy::panic)]

use assert_cmd::Command;
use camino::Utf8PathBuf;
use predicates::str::contains;
use serial_test::serial;
use tempfile::TempDir;
use wiremock::matchers::{method, path};
use wiremock::{Mock, MockServer, ResponseTemplate};

use doiget_cli::commands::output::OutputMode;
use doiget_cli::commands::text::run;

mod common;
use common::env_guard::EnvGuard;

/// Env keys this test mutates (restored on `EnvGuard` drop).
const ENV_KEYS: &[&str] = &[
    "DOIGET_AR5IV_BASE",
    "DOIGET_CACHE_ROOT",
    "DOIGET_STORE_ROOT",
    "DOIGET_LOG_PATH",
    "DOIGET_MODE",
    "HOME",
    "USERPROFILE",
];

/// Minimal synthetic ar5iv XHTML (title + one headed section).
const SAMPLE_AR5IV: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title>Extracted Paper</title></head>
<body>
  <p>Lead matter.</p>
  <section><h2>1 Introduction</h2><p>Intro body.</p></section>
</body>
</html>"#;

fn utf8(dir: &TempDir) -> Utf8PathBuf {
    Utf8PathBuf::from_path_buf(dir.path().to_path_buf()).expect("temp dir path must be UTF-8")
}

#[tokio::test]
#[serial]
async fn text_extracts_logs_and_caches() {
    // Single-shot mock: a second network fetch would fail, so a second
    // `run` must be served from the on-disk cache.
    let server = MockServer::start().await;
    Mock::given(method("GET"))
        .and(path("/html/2401.12345"))
        .respond_with(ResponseTemplate::new(200).set_body_string(SAMPLE_AR5IV))
        .up_to_n_times(1)
        .mount(&server)
        .await;

    let dir = TempDir::new().expect("tempdir");
    let root = utf8(&dir);
    let cache_root = root.join("cache");
    let log_path = root.join("access.jsonl");

    let guard = EnvGuard::new(ENV_KEYS);
    guard.set("DOIGET_AR5IV_BASE", &server.uri());
    guard.set("DOIGET_CACHE_ROOT", cache_root.as_str());
    guard.set("DOIGET_STORE_ROOT", root.join("papers").as_str());
    guard.set("DOIGET_LOG_PATH", log_path.as_str());
    guard.set("DOIGET_MODE", "quiet");
    guard.set("HOME", root.as_str());
    guard.set("USERPROFILE", root.as_str());

    // First run: hits wiremock, writes the cache, logs one ar5iv fetch.
    let res = run(
        "arxiv:2401.12345".to_string(),
        None,
        false, // no_cache = false → cache enabled
        OutputMode::Quiet,
        true, // DOIGET_MODE=quiet → explicit Quiet, output suppressed
    )
    .await;
    assert!(res.is_ok(), "text run failed: {res:?}");

    // Provenance: one Fetch row under source "ar5iv".
    let log = std::fs::read_to_string(log_path.as_std_path()).expect("read provenance log");
    assert!(
        log.contains("\"event\":\"fetch\"") && log.contains("\"source\":\"ar5iv\""),
        "missing ar5iv fetch row in:\n{log}"
    );

    // Cache: a `<cache_root>/text/<safekey>.json` entry was written.
    let text_dir = cache_root.join("text");
    let entries: Vec<_> = std::fs::read_dir(text_dir.as_std_path())
        .expect("text cache dir exists")
        .filter_map(Result::ok)
        .filter(|e| {
            e.path()
                .extension()
                .and_then(|x| x.to_str())
                .map(|x| x == "json")
                .unwrap_or(false)
        })
        .collect();
    assert_eq!(entries.len(), 1, "exactly one cached text entry expected");

    // Second run: the single-shot mock is exhausted, so success here proves
    // the result was served from the cache.
    let res2 = run(
        "arxiv:2401.12345".to_string(),
        None,
        false,
        OutputMode::Quiet,
        true,
    )
    .await;
    assert!(res2.is_ok(), "second (cached) text run failed: {res2:?}");
}

#[tokio::test]
#[serial]
async fn text_for_doi_reports_no_oa_available() {
    // A bare DOI has no full-text source in PR4 (ADR-0032 D5): the command
    // must error with a NO_OA_AVAILABLE exit, not silently succeed. No
    // network is touched.
    let dir = TempDir::new().expect("tempdir");
    let root = utf8(&dir);

    let guard = EnvGuard::new(ENV_KEYS);
    guard.set("DOIGET_CACHE_ROOT", root.join("cache").as_str());
    guard.set("DOIGET_STORE_ROOT", root.join("papers").as_str());
    guard.set("DOIGET_LOG_PATH", root.join("access.jsonl").as_str());
    guard.set("DOIGET_MODE", "quiet");
    guard.set("HOME", root.as_str());
    guard.set("USERPROFILE", root.as_str());

    let err = run(
        "10.1234/example".to_string(),
        None,
        false,
        OutputMode::Quiet,
        true,
    )
    .await
    .expect_err("a DOI must error (no full-text source)");
    // The command exits via `CliExit` carrying the NO_OA_AVAILABLE code.
    let exit = err
        .downcast_ref::<doiget_cli::commands::fetch::CliExit>()
        .expect("DOI path must yield a CliExit");
    assert_ne!(exit.0, 0, "exit code must be non-zero for a DOI");
}

#[tokio::test]
#[serial]
async fn text_unconverted_render_exits_non_zero_never_silent() {
    // Issue #302: when ar5iv returns a 200 with no readable prose (the paper
    // was never converted to HTML), `text` MUST NOT exit 0 with empty output
    // — that is the silent-success that agents misread as a bad identifier.
    // It must surface as a non-zero `CliExit` (the `TEXT_UNAVAILABLE` code is
    // asserted at the core/MCP layers; here we pin the never-exit-0 contract).
    let server = MockServer::start().await;
    Mock::given(method("GET"))
        .and(path("/html/2012.03644"))
        .respond_with(
            ResponseTemplate::new(200).set_body_string("<html><head></head><body></body></html>"),
        )
        .mount(&server)
        .await;

    let dir = TempDir::new().expect("tempdir");
    let root = utf8(&dir);

    let guard = EnvGuard::new(ENV_KEYS);
    guard.set("DOIGET_AR5IV_BASE", &server.uri());
    guard.set("DOIGET_CACHE_ROOT", root.join("cache").as_str());
    guard.set("DOIGET_STORE_ROOT", root.join("papers").as_str());
    guard.set("DOIGET_LOG_PATH", root.join("access.jsonl").as_str());
    guard.set("DOIGET_MODE", "quiet");
    guard.set("HOME", root.as_str());
    guard.set("USERPROFILE", root.as_str());

    let err = run(
        "arxiv:2012.03644".to_string(),
        None,
        true, // no_cache: exercise the live render path, not a cache hit
        OutputMode::Quiet,
        true,
    )
    .await
    .expect_err("an unconverted render must error, never silently succeed");
    let exit = err
        .downcast_ref::<doiget_cli::commands::fetch::CliExit>()
        .expect("unavailable text must yield a CliExit");
    assert_ne!(
        exit.0, 0,
        "exit code must be non-zero when no text is produced"
    );
}

/// Build env for a subprocess `doiget` run against `server`, isolated to
/// `root`. Deliberately does NOT set `DOIGET_MODE`, so the piped (non-TTY)
/// child resolves to *implicit* Quiet — the exact condition the artifact
/// rule must override.
fn doiget_subprocess(root: &Utf8PathBuf, server_uri: &str) -> Command {
    let mut cmd = Command::cargo_bin("doiget").expect("locate doiget binary");
    let p = root.as_str();
    cmd.env("DOIGET_AR5IV_BASE", server_uri)
        .env("DOIGET_CACHE_ROOT", root.join("cache").as_str())
        .env("DOIGET_STORE_ROOT", root.join("papers").as_str())
        .env("DOIGET_LOG_PATH", root.join("access.jsonl").as_str())
        .env("HOME", p)
        .env("USERPROFILE", p);
    cmd
}

#[tokio::test]
#[serial]
async fn text_piped_non_tty_still_emits_prose() {
    // Review #318: extracted paper prose IS the artifact. Piped without an
    // explicit `--quiet`, the mode is *implicit* Quiet; the artifact rule
    // (ADR-0017 Amendment 2, extended to `text`) must still emit, or
    // `doiget text arxiv:… > paper.txt` would silently write an empty file.
    let server = MockServer::start().await;
    Mock::given(method("GET"))
        .and(path("/html/2401.12345"))
        .respond_with(ResponseTemplate::new(200).set_body_string(SAMPLE_AR5IV))
        .mount(&server)
        .await;

    let dir = TempDir::new().expect("tempdir");
    let root = utf8(&dir);
    doiget_subprocess(&root, &server.uri())
        .args(["text", "arxiv:2401.12345"])
        .assert()
        .success()
        // The rendered prose reaches stdout — not blanked by implicit Quiet.
        .stdout(contains("Extracted Paper"))
        .stdout(contains("Intro body."));
}

#[tokio::test]
#[serial]
async fn text_explicit_quiet_still_suppresses_prose() {
    // The flip side: an *explicit* `--quiet` DOES suppress the artifact
    // (exit 0, empty stdout) — the artifact rule only overrides the implicit
    // non-TTY fallback, not a deliberate quiet request.
    let server = MockServer::start().await;
    Mock::given(method("GET"))
        .and(path("/html/2401.12345"))
        .respond_with(ResponseTemplate::new(200).set_body_string(SAMPLE_AR5IV))
        .mount(&server)
        .await;

    let dir = TempDir::new().expect("tempdir");
    let root = utf8(&dir);
    doiget_subprocess(&root, &server.uri())
        .args(["text", "arxiv:2401.12345", "--quiet"])
        .assert()
        .success()
        .stdout(predicates::str::is_empty());
}

#[tokio::test]
#[serial]
async fn text_unavailable_prints_actionable_fetch_note() {
    // Review #318 / #302: an ar5iv 200 with no extractable prose must fail
    // with the ACTIONABLE `= note:` naming the exact fetch command, not just
    // a bare non-zero exit. Pins the note string a human / agent acts on.
    let server = MockServer::start().await;
    Mock::given(method("GET"))
        .and(path("/html/2012.03644"))
        .respond_with(
            ResponseTemplate::new(200).set_body_string("<html><head></head><body></body></html>"),
        )
        .mount(&server)
        .await;

    let dir = TempDir::new().expect("tempdir");
    let root = utf8(&dir);
    doiget_subprocess(&root, &server.uri())
        .args(["text", "arxiv:2012.03644"])
        .assert()
        .failure()
        .stderr(contains(
            "fetch the PDF instead: `doiget fetch arxiv:2012.03644`",
        ));
}