aube 1.41.0

Aube — a fast Node.js package manager
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

// Thin binary wrapper: the whole CLI lives in the `aube` library crate
// (src/lib.rs) so the command layer can also be embedded as a library.
// What belongs here is binary-level / aube-specific policy the library
// must not impose on embedders: the global-allocator choice, the `main`
// that forwards to `aube::cli_main`, and the aube-specific `usage`
// (usage.jdx.dev KDL) command, which is aube's own tooling rather than
// part of the embeddable command layer. The `aubr` / `aubx` multicall
// shims `include!` this file, so all three bins stay byte-identical in
// behavior.

// mimalloc as global allocator on release builds. Cuts linker-phase
// wall time and peak RSS on large installs. Per-thread heaps suit
// rayon work-stealing and tokio's blocking pool. Gated on
// `not(debug_assertions)` so `cargo run` and `cargo test` keep the
// system allocator, which keeps Valgrind, ASAN, and Miri happy.
// `secure` feature skipped. aube's hot path is tarball extraction
// with bounded input, not a sandbox boundary.
#[cfg(all(feature = "mimalloc", not(debug_assertions)))]
#[global_allocator]
static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;

fn main() {
    // The standalone `aube` binary runs with aube's own embedder profile.
    // Embedders call `aube::cli_main` with their own `&'static Embedder`
    // instead (and `cli_main_with_defaults` to also seed setting defaults).
    let embedder = &aube_util::identity::AUBE;

    // `aube usage` prints a usage.jdx.dev KDL spec for the CLI (consumed by
    // `mise render` and the CLI docs build). It's aube-specific tooling, not
    // part of the embeddable command layer — a downstream embedder ships its
    // own top-level usage/completions — so it's intercepted here in the binary
    // before `cli_main` rather than carried as a subcommand in the lib. Only
    // the standalone `aube` invocation reaches it: multicall shims rewrite
    // argv before clap, so their `usage` tokens belong to the wrapped tool.
    // The binary owns the single `std::process::exit`: `cli_main` returns the
    // code so the library stays embed-safe (a host driving it in-process is
    // never hard-killed), and the standalone binary terminates with it here.
    let code = if is_usage_invocation() {
        print_usage_spec(embedder)
    } else {
        aube::cli_main(embedder)
    };
    std::process::exit(code);
}

/// Print the usage.jdx.dev KDL spec for the CLI and return an exit code.
fn print_usage_spec(embedder: &'static aube_util::Embedder) -> i32 {
    let mut cmd = aube::command();
    let mut usage_spec = clap_usage::spec(&mut cmd, embedder.name);
    // Declare what each command does to the world; clap cannot express it.
    aube::command_effects::apply(&mut usage_spec);
    // 4.0 added `effect=`; older `usage` CLIs reject the spec outright with
    // "unsupported cmd prop effect".
    let mut spec = format!(
        "// @generated by usage-cli from clap metadata\nmin_usage_version \"4.0\"\n{usage_spec}\n"
    )
    .into_bytes();
    // `clap_usage` only sees the clap tree, which has no way to express a
    // dynamic completer, so the `complete` nodes come from a hand-written
    // fragment. usage merges top-level nodes, so appending the text is
    // enough (`mise usage` does the same). `{bin}` carries the embedder's
    // binary name into the shell snippet the completer runs.
    let extra = include_str!("../assets/extra.usage.kdl")
        .replace("{run}", &format!("{} run", embedder.name))
        .replace(
            "{completers}",
            &include_str!("../assets/completion.usage.kdl").replace("{bin}", embedder.name),
        );
    spec.extend_from_slice(extra.trim_end().as_bytes());
    spec.push(b'\n');

    // `mise render` redirects this into `aube.usage.kdl`, so a short write
    // must not pass for success — a truncated spec would become the
    // checked-in one, and the completions built from it. A reader that
    // hung up (`aube usage | head`) is not a failure.
    use std::io::Write;
    let mut out = std::io::stdout();
    match out.write_all(&spec).and_then(|()| out.flush()) {
        Ok(()) => 0,
        Err(e) if e.kind() == std::io::ErrorKind::BrokenPipe => 0,
        Err(e) => {
            // This path never reaches miette — the usage branch returns
            // before `cli_main` — so the stable code is printed here and
            // the exit status comes from the same `EXIT_TABLE` lookup the
            // diagnostic path uses.
            let code = aube_codes::errors::ERR_AUBE_USAGE_SPEC_WRITE_FAILED;
            eprintln!("{}: {code}: failed to write usage spec: {e}", embedder.name);
            aube_codes::exit::exit_code_for(code).unwrap_or(aube_codes::exit::EXIT_GENERIC)
        }
    }
}

/// True for a standalone `aube usage` invocation: argv[0] resolves to the
/// `aube` binary (not one of the multicall/tool shims) and the first
/// argument is `usage`.
fn is_usage_invocation() -> bool {
    let mut args = std::env::args_os();
    let invoked_as_aube = args
        .next()
        .as_deref()
        .map(std::path::Path::new)
        .and_then(|p| p.file_stem())
        .and_then(|s| s.to_str())
        .map(|stem| {
            !matches!(
                stem.to_ascii_lowercase().as_str(),
                "aubr" | "aubx" | "node" | "npm" | "npx" | "pnpm" | "pnpx" | "yarn" | "yarnpkg"
            )
        })
        .unwrap_or(true);
    invoked_as_aube && args.next().as_deref() == Some(std::ffi::OsStr::new("usage"))
}