DOCSEARCHbyAlgolia
Submit Docs

aube

repository·main·Indexed 23 days ago

https://github.com/jdx/aube

A high-performance, secure Node.js package manager featuring a global content-addressable store and a lifecycle-script jail. It drops into existing projects by reading and writing lockfiles (pnpm, npm, yarn, bun) in place and automatically installs dependencies when running scripts via aubr. The project provides the @jdxcode/aube-node embedder for JavaScript environments and @jdxcode/aube-ffi for C ABI access.

Tokens
128.3K
Snippets
291
Records
777
Agent score
81%

What's inside aube

  1. Overview of the aube package manager

    main

    aube is a package manager for Node.js projects designed for speed and disk efficiency. It utilizes a pnpm-style isolated node_modules layout and a content-addressable global store.

    Key Features:

    • Lockfile Compatibility: aube can read and write existing lockfiles in place, including pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json, yarn.lock, and bun.lock.
    • New Projects: Projects without a supported lockfile will use aube-lock.yaml.
    • Storage Model:
      • Virtual store: node_modules/.aube/
      • Global store: $XDG_DATA_HOME/aube/store/ (defaults to ~/.local/share/aube/store/)
    • Dependency Specifiers: Supports workspace:, link:, file:, git, tarball URL, npm alias, and catalogs.

  2. Understand the purpose of the aube publish smoke package

    main
    The publish-smoke package is a minimal, utility-only package used to verify the aube publish workflow. It is not intended for production use. When aube publish is executed, this package is used to simulate a real registry publication by copying the package, renaming it to a throwaway name, applying a unique prerelease version, and publishing it to ensure the registry interaction logic is functioning correctly.

  3. Run dependency scripts in a build jail

    main

    Enable jailBuilds to run approved dependency lifecycle scripts in a restricted environment. On macOS, aube uses a native Seatbelt profile; on Linux, it uses Landlock and seccomp. The jail denies network access and limits filesystem writes to the package directory and temporary directories. Root lifecycle scripts are not jailed.

    jail-builds=true

  4. Coexistence with pnpm

    main
    aube is designed to coexist with pnpm. It does not attempt to reuse the .pnpm/ directory or the ~/.pnpm-store/. If a project already has a node_modules tree built by pnpm, aube will install its own dependencies into node_modules/.aube/ alongside the existing pnpm structure.

  5. Use JSR packages with `aube add`

    main

    Aube supports JSR packages using the jsr:@scope/name syntax. These specifiers resolve against JSR's npm-compat endpoint at https://npm.jsr.io.

    Aube automatically registers the @jsr scope, so no .npmrc configuration is required. The installation process fetches the package under its compatibility name (@jsr/<scope>__<name>) and writes the original jsr:<range> specifier back to your package.json.

    aube add jsr:@std/collections@^1.0.0

  6. Understand aube benchmark scenarios

    main

    Benchmarks are measured end-to-end using a medium-sized real-world fixture (~1400 packages) via hyperfine. The scenarios are defined by the state of the tool's cache/store and the presence of node_modules:

    • Fresh install (warm cache): Uses a frozen lockfile with node_modules wiped, but the tool's store and packument cache remain populated. This measures local linking and materialization.
    • Fresh install (cold cache): Uses a frozen lockfile with the store, packument cache, and node_modules all wiped. This measures registry fetching, store importing, and linking from scratch.
    • npm install && npm run test (already installed): Models the developer loop. It measures how quickly a tool can skip install work (short-circuiting) and dispatch a script when dependencies are already present. aube can skip install work when its install-state file is fresh.

  7. Use Catalogs to manage shared dependencies

    main

    Aube supports catalogs to manage dependency versions centrally in a workspace.

    • --save-catalog: Saves the dependency into the workspace's default catalog. It writes catalog: into package.json and updates the workspace yaml.
    • --save-catalog-name <NAME>: Saves the dependency into a specific named catalog (e.g., catalogs.my-catalog in the workspace yaml and catalog:my-catalog in package.json).

    Exclusions: Workspace and aliased specs (like workspace:*, npm:, or jsr:) are never catalogized.

    Conflict: --save-catalog conflicts with --no-save because catalog mutations write to the workspace yaml, which --no-save does not snapshot.

  8. Protect against typosquatting and impersonation

    main

    Aube includes several reputation gates to prevent installing malicious or lookalike packages. These checks run during aube add, aube update, or when the resolver picks a new version not pinned in the lockfile.

    Reputation Gates

    • Known-malicious advisories: Queries OSV for MAL-* advisories. A hit results in ERR_AUBE_MALICIOUS_PACKAGE.
    • Similar package name: Compares requested names against a snapshot of the 100,000 most-downloaded npm packages. Non-interactive sessions fail with ERR_AUBE_SIMILAR_PACKAGE_NAME if a lookalike is detected.
    • Low download count: If a package falls below the lowDownloadThreshold, a confirmation is required. In non-interactive contexts, this fails with ERR_AUBE_LOW_DOWNLOAD_PACKAGE unless --allow-low-downloads is passed.
    • New package name: Checks if a package was registered within the minimumPackageAge (default 30 days). Non-interactive sessions fail with ERR_AUBE_NEW_PACKAGE_NAME.

    Bypassing Gates

    • Private packages: Any package from a non-registry.npmjs.org registry (e.g., via scoped overrides) automatically skips all four gates.
    • Internal packages: Use allowedUnpopularPackages in your config to skip reputation gates for known internal packages that might have low download counts.
    • Manual override: Use the --allow-low-downloads flag to bypass all three reputation challenges (low downloads, similar name, and new package age) for a specific command.
    # Example configuration for internal packages
advisoryCheck: on            # default; fail open on network error
lowDownloadThreshold: 1000   # weekly downloads, 0 disables
allowedUnpopularPackages:    # glob patterns; OSV check still runs
  - "@mycompany/*"
  - "internal-*"

  9. Use workspace filters to scope commands

    main

    You can scope aube command execution to specific workspace packages using the --filter or --filter-prod flags. This is useful for running commands like run, test, install, or publish only on a subset of your project.

    Selector Grammar:

    • Exact names: my-pkg
    • Globs: @scope/*, *-plugin
    • Paths: ./packages/api
    • Graph selectors: pkg... (include dependencies), ...pkg (include dependents)
    • Git-ref selectors: [origin/main]
    • Exclusions: !pkg (use ! to exclude a package)

    Production-only filtering: Use --filter-prod to restrict graph walks (pkg..., ...pkg) to only follow dependencies, optionalDependencies, and peerDependencies. devDependencies and packages reachable only through them are skipped.

    Note: --filter is repeatable; multiple matches are OR-ed.

  10. Why aube is faster in benchmarks

    main

    aube's performance advantage in benchmarks stems from its default configuration of the global virtual store.

    While aube starts from pnpm's isolated symlink model (a global content-addressable store plus a per-project virtual store), it enables the global virtual store by default for local installs. In contrast, while pnpm supports a similar feature, it is left off by default, meaning benchmarks compare the tools as they are experienced 'out of the box'.

  11. Understand the Default Jailed Build Profile

    main

    When jailBuilds is enabled and a dependency is approved, it runs with a default native jail profile. The following table describes the default capabilities:

    CapabilityDefault
    Filesystem readsunrestricted today; package/toolchain-only reads are planned
    Filesystem writespackage directory and aube-owned temporary directories
    Networkdenied
    Environmentscrubbed allowlist only
    Home directorytemporary aube-owned jail home

    Approval via allowBuilds means the package is permitted to build itself, but it does not grant permission to modify unrelated workspace files, inherit registry tokens, or access the network.

  12. Manage dependency lifecycle scripts and security

    main

    By default, aube skips dependency lifecycle scripts for security, only allowing packages on its built-in trusted list.

    To manage these:

    • aube approve-builds: Explicitly allow packages to run build scripts.
    • aube ignored-builds: Inspect which packages had their scripts skipped.

    Build Jail: For approved packages, you can use jailBuilds: true (planned to be default) to run lifecycle scripts in a scrubbed environment with a temporary HOME. You can configure specific permissions or exclusions using jailBuildPermissions or jailBuildExclusions in your configuration.