#![cfg_attr(not(feature = "tui"), allow(dead_code, unused_imports))]
mod cli;
mod collection;
mod env_panel;
mod environment;
mod generators;
mod git_remote;
#[cfg(feature = "gui")]
mod gui;
mod http;
mod hurl;
mod i18n;
mod persistence;
mod postman;
mod postman_api;
mod postman_cli;
mod postman_flow;
mod postman_import;
mod probe;
mod remote_flow;
mod report;
mod report_cli;
#[cfg(any(feature = "tui", feature = "gui"))]
mod report_highlight;
mod request;
mod save_flow;
mod session;
mod shared_utils;
mod theme;
mod tree;
#[cfg(feature = "tui")]
mod tui;
mod vars_view;
mod workspace;
use clap::Parser;
#[cfg(feature = "tui")]
const DEFAULT_MODE: &str = "\x20 TUI (default) a terminal user interface\n";
#[cfg(all(not(feature = "tui"), feature = "gui"))]
const DEFAULT_MODE: &str =
"\x20 GUI (-g/--gui) a native graphical interface (this build has no TUI)\n";
#[cfg(all(not(feature = "tui"), not(feature = "gui")))]
const DEFAULT_MODE: &str = "";
#[cfg(feature = "tui")]
const DEFAULT_EXAMPLE: &str =
"\x20 paperboy Launch the terminal UI (default)\n";
#[cfg(all(not(feature = "tui"), feature = "gui"))]
const DEFAULT_EXAMPLE: &str = "\x20 paperboy --gui Launch the graphical UI\n";
#[cfg(all(not(feature = "tui"), not(feature = "gui")))]
const DEFAULT_EXAMPLE: &str = "";
static LONG_ABOUT: std::sync::LazyLock<String> = std::sync::LazyLock::new(|| {
format!(
"PaperBoy — a Rust-native API client (a Postman alternative).\n\n\
Runs in one of these modes:\n\
{DEFAULT_MODE}\
\x20 CLI (-c/--collection) run a Hurl or Postman collection headlessly, then exit\n\
\x20 Report (-r/--report) run a PaperTrail report against a collection, then exit\n\
\x20 Import (--postman-import) download a Postman workspace over the API, then exit"
)
});
static AFTER_HELP: std::sync::LazyLock<String> = std::sync::LazyLock::new(|| {
format!(
"Examples:\n\
{DEFAULT_EXAMPLE}\
\x20 paperboy -c collection.hurl Run a collection headlessly\n\
\x20 paperboy -c collection.hurl -e environment.vars Run a collection with an environment\n\
\x20 paperboy -c collection.hurl --batch Run as one batch (preserves cookies across requests)\n\
\x20 paperboy -c collection.hurl -e environment.vars -r report.trail Run a report\n\
\x20 paperboy -r report.trail Run a report, taking its collection/environment from the report's own headers\n\
\x20 paperboy -c collection.hurl -e prod.vars -e staging.vars -r report.trail Run a baseline/comparison report\n\
\x20 paperboy -c collection.hurl -r report.trail --dry-run Preview a report without sending anything\n\
\x20 paperboy -c collection.hurl -r report.trail -o out.csv Write the report to a file (- = stdout)\n\
\x20 paperboy -r report.trail -o out.html -o out.json One run, several formats\n\
\x20 paperboy -r report.trail --param CASES_DIR=./batch-07 Run a report, setting a PARAM it declares\n\
\x20 paperboy -r report.trail -o out.json --progress-json Run a report, streaming JSON progress events to stderr\n\
\x20 paperboy --postman-import List the Postman workspaces your API key can see\n\
\x20 paperboy --postman-import --postman-workspace ID -o ./API Download a whole Postman workspace\n\
\x20 paperboy --postman-import --postman-all -o ./API Download every workspace the key can see\n\n\
Environment (.vars) entries are KEY=value, where the value is a literal or a\n\
{{ ... }} provider reference resolved when the environment is loaded:\n\
\x20 Literal value USERNAME=demo\n\
\x20 Process env var BASE_URL={{ env:DEMO_BASE_URL }}\n\
\x20 1Password (op CLI) API_TOKEN={{ op://Vault/Item/field }}\n\
\x20 AWS SSM parameter DB_PASSWORD={{ ssm:/path/to/param }}\n\n\
Collections are Hurl files (.hurl) or Postman collection exports (.json);\n\
Postman JSON is imported automatically."
)
});
#[derive(Parser)]
#[command(
name = "paperboy",
version,
about = "PaperBoy — a Rust-native API client (a Postman alternative).",
long_about = LONG_ABOUT.as_str(),
after_help = AFTER_HELP.as_str()
)]
struct Cli {
#[command(flatten)]
saved: report::saved::Options,
#[arg(short = 'c', long, value_name = "FILE")]
collection: Option<String>,
#[arg(short = 'e', long, value_name = "FILE")]
env: Vec<String>,
#[arg(short = 'b', long)]
batch: bool,
#[arg(short = 'r', long, value_name = "FILE")]
report: Option<String>,
#[arg(long, requires = "report")]
dry_run: bool,
#[arg(
long,
value_name = "PERCENT",
requires = "report",
// `requires` is not exclusion: `--postman-import -r x.trail
// --fail-under 95` satisfied it and then took the import path, where
// nothing is ever scored — so the gate was silently ignored and the
// command exited 0. A gate that can be quietly skipped is worse than
// one that refuses the command line.
conflicts_with_all = ["dry_run", "postman_import"],
value_parser = percentage
)]
fail_under: Option<f64>,
#[arg(
long,
value_name = "ROWS",
requires = "report",
// Same reasoning as `--fail-under`: a gate that can be quietly skipped
// is worse than one that refuses the command line.
conflicts_with_all = ["dry_run", "postman_import"],
allow_negative_numbers = true
)]
require_net_gain: Option<i64>,
#[arg(long, value_name = "STEPS", value_delimiter = ',', requires = "report")]
targets: Vec<String>,
#[arg(long, value_name = "SEED", num_args = 0..=1, requires = "report")]
shuffle: Option<Option<u64>>,
#[arg(short = 'o', long = "output", value_name = "FILE")]
outputs: Vec<String>,
#[arg(
long = "param",
value_name = "NAME=VALUE",
value_parser = report::params::parse_assignment,
requires = "report"
)]
params: Vec<(String, String)>,
#[arg(long)]
progress_json: bool,
#[arg(long, requires = "report")]
stop_on_stdin: bool,
#[arg(long, value_name = "SECONDS", requires = "report")]
grace: Option<u64>,
#[arg(short = 'g', long)]
gui: bool,
#[arg(long)]
postman_import: bool,
#[arg(long, value_name = "ID|URL")]
postman_workspace: Option<String>,
#[arg(long, conflicts_with = "postman_workspace")]
postman_all: bool,
#[arg(long, value_name = "KEY")]
postman_key: Option<String>,
#[arg(long, value_name = "WHAT")]
postman_what: Option<String>,
#[arg(long, value_name = "URL")]
postman_base_url: Option<String>,
#[arg(long, value_name = "FORMAT")]
postman_format: Option<String>,
#[arg(long)]
overwrite: bool,
}
fn percentage(raw: &str) -> Result<f64, String> {
let trimmed = raw.trim();
let digits = trimmed.strip_suffix('%').unwrap_or(trimmed);
let v: f64 = digits
.parse()
.map_err(|_| format!("'{raw}' is not a number"))?;
if !(0.0..=100.0).contains(&v) {
return Err(format!("'{raw}' is not a percentage between 0 and 100"));
}
Ok(v)
}
fn main() {
let cli = Cli::parse();
if cli.saved.run_state.is_some() {
use report::saved::Action;
let offline = matches!(cli.saved.state_action, Action::Inspect | Action::Render);
if cli.postman_import
|| cli.batch
|| cli.gui
|| cli.dry_run
|| (offline
&& (cli.report.is_some() || cli.collection.is_some() || !cli.env.is_empty()))
|| (!offline && cli.report.is_none())
{
eprintln!(
"error: saved execution requires -r; inspect/render require only --run-state, without other run modes"
);
std::process::exit(2);
}
if offline {
std::process::exit(report_cli::read_saved(
&cli.saved,
&cli.outputs,
cli.progress_json,
));
}
} else if cli.progress_json && cli.report.is_none() {
eprintln!("error: --progress-json requires --report or --run-state");
std::process::exit(2);
}
if !cli.outputs.is_empty() && cli.report.is_none() && !cli.postman_import {
eprintln!("error: -o/--output requires -r/--report or --postman-import");
std::process::exit(2);
}
if cli.postman_import {
if cli.outputs.len() > 1 {
eprintln!(
"error: --postman-import downloads into one directory, but -o was given {} times",
cli.outputs.len()
);
std::process::exit(2);
}
std::process::exit(postman_cli::run(postman_cli::Args {
key: cli.postman_key,
workspace: cli.postman_workspace,
all: cli.postman_all,
out: cli.outputs.into_iter().next(),
what: cli.postman_what,
base_url: cli.postman_base_url,
format: cli.postman_format,
overwrite: cli.overwrite,
}));
}
if let Some(report) = cli.report {
std::process::exit(report_cli::run_with_state(
cli.collection,
cli.env,
report,
cli.outputs,
cli.dry_run,
cli.targets,
cli.shuffle,
cli.params.into_iter().collect(),
report_cli::Gates {
fail_under: cli.fail_under,
net_gain: cli.require_net_gain,
},
cli.progress_json,
cli.grace,
cli.stop_on_stdin,
cli.saved,
));
}
if let Some(collection) = cli.collection {
if cli.env.len() > 1 {
eprintln!(
"warning: multiple -e environments are only used by reports (-r); running the collection with the first one"
);
}
std::process::exit(cli::run(collection, cli.env.into_iter().next(), cli.batch));
}
if cli.gui {
std::process::exit(run_gui());
}
std::process::exit(run_tui());
}
#[cfg(feature = "tui")]
fn run_tui() -> i32 {
if let Err(e) = tui::run() {
eprintln!("tui error: {e}");
return 1;
}
0
}
#[cfg(all(not(feature = "tui"), feature = "gui"))]
fn run_tui() -> i32 {
eprintln!(
"This build of PaperBoy has no terminal UI.\n\
Pass `-g/--gui` for the graphical one, or `-c <collection.hurl>` or \
`-r <report.trail>` to run headlessly."
);
1
}
#[cfg(all(not(feature = "tui"), not(feature = "gui")))]
fn run_tui() -> i32 {
eprintln!(
"This build of PaperBoy is headless: it runs collections and reports, \
but has no user interface.\n\
Pass `-c <collection.hurl>` or `-r <report.trail>`, or reinstall with \
the terminal UI:\n\
\x20 cargo install paperboy --locked"
);
1
}
#[cfg(feature = "gui")]
fn run_gui() -> i32 {
if let Err(e) = gui::run() {
eprintln!("gui error: {e}");
return 1;
}
0
}
#[cfg(not(feature = "gui"))]
fn run_gui() -> i32 {
eprintln!(
"This build of PaperBoy has no GUI. Reinstall it with the `gui` feature:\n\
\x20 cargo install paperboy --locked --features gui"
);
1
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_threshold_is_a_percentage_with_at_most_one_sign() {
assert_eq!(percentage("95"), Ok(95.0));
assert_eq!(percentage("95%"), Ok(95.0));
assert_eq!(percentage(" 99.5 "), Ok(99.5));
assert_eq!(percentage("0"), Ok(0.0));
assert_eq!(percentage("100"), Ok(100.0));
assert!(percentage("95%%").is_err());
assert!(percentage("%95").is_err());
assert!(percentage("").is_err());
assert!(percentage("high").is_err());
assert!(percentage("101").is_err());
assert!(percentage("-1").is_err());
assert!(percentage("nan").is_err());
assert!(percentage("inf").is_err());
}
}