@git.zone/tsrust

A CLI build tool for Rust projects that follows the same conventions as @git.zone/tsbuild. It detects your rust/ source directory, parses Cargo.toml (including workspaces), runs cargo build --release with a managed target cache, and copies the resulting binaries into a clean dist_rust/ directory at the project root.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

Install globally with pnpm:

pnpm add -g @git.zone/tsrust

Or as a project-level dev dependency:

pnpm add --save-dev @git.zone/tsrust

⚡ No Rust required! If cargo isn't found on your system, tsrust automatically downloads and installs a minimal Rust toolchain to /tmp/tsrust_toolchain/. This gives a zero-setup experience. If you already have Rust installed, tsrust uses your system toolchain.

The Convention

tsrust mirrors the directory convention established by tsbuild:

| Tool | Source Directory | Output Directory | |------|-----------------|-----------------| | tsbuild | ts/ | dist_ts/ | | tsrust | rust/ | dist_rust/ |

Your Rust code lives in rust/ (or ts_rust/ as fallback), and compiled binaries land in dist_rust/ — ready for packaging, deployment, or further tooling.

Usage

🔨 Build (Default Command)

Simply run tsrust from your project root:

tsrust

This will:

1. Detect the Rust toolchain (system cargo, or auto-install to /tmp/tsrust_toolchain/)
2. Locate your rust/ directory (containing Cargo.toml)
3. Parse the workspace to discover all [[bin]] targets
4. With native notices configured: install the build's missing rustup targets, run the notices check's own cargo metadata --format-version 1 --locked --filter-platform <triple> online once per notices target so Cargo downloads exactly the packages the check reads, and verify the committed notices offline
5. Run cargo build --release with full streaming output
6. Store Cargo intermediates in .nogit/tsrust-target by default
7. Copy each binary to dist_rust/ with executable permissions (chmod 755)
8. Write a SHA-256-bound provenance sidecar without changing the binary bytes
9. Report file sizes and total build time

Example output:

Using cargo 1.90.0 (840b83a10 2025-07-30)
Found Rust project at: rust
Detected Cargo workspace
Binary targets: rustproxy
Running: CARGO_TARGET_DIR="/path/to/project/.nogit/tsrust-target" cargo build --release
   Compiling rustproxy v0.1.0
    Finished `release` profile [optimized] target(s) in 29.01s
Copied rustproxy (13.4 MB) -> dist_rust/rustproxy
Wrote provenance: @example/[email protected] abc123def456 (native)
Done in 29.2s

Automatic Rust Toolchain

tsrust provides a zero-setup experience through automatic toolchain management:

1. System toolchain detected → uses it as-is (no download, no overhead)
2. No system toolchain → checks /tmp/tsrust_toolchain/ for a previously installed bundled toolchain
3. No ready bundled toolchain → installs a minimal host-qualified stable toolchain with rustup-init, or cleanly reinstalls a secure but incomplete managed toolchain

The bundled toolchain is stored in /tmp/, so it's cleaned up on reboot. Subsequent runs reuse the existing installation. Before executing it, tsrust requires the root to be a current-user-owned, non-symlink directory, restricts it to mode 0700, verifies that cargo and rustup resolve to current-user-owned executables inside that root that are not group- or world-writable, and binds cargo, rustc, and target-manifest checks to the exact managed stable toolchain for the execution host. A securely resolved installation that fails readiness is removed and freshly installed through rustup under the installation lock. An atomically published current-user-owned installation lock serializes validation and bootstrap. A dead installer fails closed with the exact lock path for operator inspection instead of risking concurrent stale-lock deletion.

Supported platforms for automatic install: Linux (x64, arm64) and macOS (x64, arm64).

🐛 Debug Build

Build with the debug profile instead of release:

tsrust --debug

Binaries are taken from .nogit/tsrust-target/debug/ instead of .nogit/tsrust-target/release/.

🧹 Clean Before Building

Run cargo clean before building to force a full rebuild:

tsrust --clean

Cross-Compilation

Cross-compile for different OS/architecture combinations using the --target flag:

# Cross-compile for a single target
tsrust --target linux_arm64

# Cross-compile for multiple targets
tsrust --target linux_arm64 --target linux_amd64

# Full Rust triples are also accepted
tsrust --target aarch64-unknown-linux-gnu

Supported friendly target names:

| Friendly name | Rust target triple | |---|---| | linux_amd64 | x86_64-unknown-linux-gnu | | linux_arm64 | aarch64-unknown-linux-gnu | | linux_amd64_musl | x86_64-unknown-linux-musl | | linux_arm64_musl | aarch64-unknown-linux-musl | | macos_amd64 | x86_64-apple-darwin | | macos_arm64 | aarch64-apple-darwin |

When using --target, output binaries are named <binname>_<os>_<arch>:

dist_rust/
├── rustproxy_linux_arm64
├── rustproxy_linux_arm64.tsrust-build.json
├── rustproxy_linux_amd64
└── rustproxy_linux_amd64.tsrust-build.json

tsrust automatically installs missing rustup targets via rustup target add when needed. With native notices configured, the build does this for its targets before the notices check. The check reads the rust-src component and every configured musl target, including ones this host does not build, and installs neither: declare them in rust-toolchain.toml (see Native Notices), or it refuses and names the rustup component add rust-src or rustup target add <triple> command to run.

Configuration via .smartconfig.json

You can set default cross-compilation targets in your project's .smartconfig.json file so you don't need to pass --target flags every time:

{
  "@git.zone/tsrust": {
    "targets": ["linux_arm64", "linux_amd64"],
    "locked": true,
    "targetDir": ".nogit/tsrust-target",
    "pruneAfterBuild": false
  }
}

When targets are configured in .smartconfig.json, simply running tsrust will cross-compile for all listed targets. CLI --target flags determine the selected targets when provided. The complete configuration is still validated first, so malformed legacy or host-specific entries are always rejected.

For builds split across Linux and macOS hosts, select targets by build host:

{
  "@git.zone/tsrust": {
    "targetsByHost": {
      "linux": ["linux_amd64", "linux_arm64"],
      "macos": ["macos_amd64", "macos_arm64"]
    },
    "locked": true
  }
}

Host selection uses this precedence: CLI --target, exact host key, OS-family key, legacy targets, then a native build. Exact host keys are linux_amd64, linux_arm64, macos_amd64, and macos_arm64; OS-family keys are linux and macos. The selected entries are not merged, so an exact host entry completely replaces its family entry for that host.

locked: true runs Cargo builds with --locked for deterministic dependency resolution. This requires Cargo.lock to exist and remain consistent with the manifests; Cargo fails instead of updating an inconsistent lockfile.

targetDir is optional. It must point to a tsrust-owned path under .nogit/, such as .nogit/tsrust-target or .nogit/tsrust-custom-target. You can also set TSRUST_TARGET_DIR for one-off runs. pruneAfterBuild: true or TSRUST_PRUNE_AFTER_BUILD=true removes the marked managed target cache after binaries have been copied to dist_rust/.

Build Provenance

Every new build writes <binary>.tsrust-build.json beside the binary. In a Git checkout, the sidecar records the consuming package name and version, exact commit and dirty state, target, build time, and tsrust version. Non-Git builds record gitCommit: "unknown" and omit gitDirty. The sidecar also contains the binary's SHA-256 digest, so provenance reads fail if either file no longer belongs to the pair. The binary itself remains byte-identical to the postprocessed Cargo target-cache binary, preserving Mach-O signatures and other binary-format integrity checks. On Darwin targets, tsrust preserves an existing valid signature and applies an ad-hoc signature only when codesign explicitly identifies the Cargo output as unsigned. Invalid or ambiguous signature states fail the build. Signing happens before the binary is copied and before its provenance digest is written.

Inspect a built artifact with:

tsrust inspect dist_rust/rustproxy_linux_amd64

inspect verifies and reads the sidecar. It retains read compatibility with provenance trailers produced by tsrust 1.7 and 1.8, but new builds no longer append those trailers.

tsrust snapshots the Git commit and complete worktree status before each Cargo build and verifies that neither changed before copying artifacts. Dirty builds remain possible for development and are marked as dirty; strict multi-host assembly rejects them.

Multi-Host Assembly

Each host build owns and cleans its own dist_rust/. Copy those host outputs into separate artifact directories, then assemble the complete matrix from the same clean Git checkout and package version:

tsrust assemble .nogit/artifacts/linux .nogit/artifacts/macos

The union of targets and targetsByHost defines the required target matrix. Repeated --target options can define an explicit matrix instead. Assembly always publishes to the tsrust-owned dist_rust/ directory.

Assembly requires every Cargo binary for every expected target. It rejects missing, duplicate, unexpected, non-executable, symlinked, hash-mismatched, dirty, wrong-commit, wrong-package, and wrong-tsrust-version inputs. Validation and copying happen in a same-filesystem transaction under .nogit/tsrust-assembly/, guarded by the atomically published .nogit/tsrust-assembly.lock. The Git commit, clean worktree, and package identity are checked again immediately before publication. The previous output is retained until the complete staged matrix is ready, and successful publication removes files left by older matrices.

The transaction records a boot-scoped host identity, process, owner token, publication phase, and exact digest manifest for staged binaries and sidecars. A separate atomic recovery claim serializes dead-owner recovery. When the owner lock and state are readable and consistent, a later invocation on the owning host rejects a live process, rolls back an interrupted pre-commit publication after that process exits, and completes publication or cleanup after durable commit intent only after revalidating the manifest. Legacy committed v1 transactions from tsrust 1.9 are validated against the current exact assembly request, upgraded with a manifest, and then completed; incompatible legacy staging fails closed. A confirmed missing state file is safe to clean because the owner-lock protocol forbids output mutation before initial state persistence; malformed, non-regular, unreadable, owner-inconsistent, or manifest-inconsistent state fails closed. A transaction owned by another host is never taken over automatically because portable filesystem operations cannot fence a paused remote writer. If committed cleanup cannot finish immediately, the programmatic result reports cleanupPending: true and the CLI prints a warning; the owning process can retry it immediately.

Native Build Matrix

tsrust matrix automates host-partitioned builds and strict assembly. Committed configuration identifies expected worker architectures and names the environment variables that contain operator-local SSH details:

{
  "@git.zone/tsrust": {
    "targetsByHost": {
      "linux": ["linux_amd64", "linux_arm64"],
      "macos": ["macos_amd64", "macos_arm64"]
    },
    "locked": true,
    "matrix": {
      "builders": {
        "linux_amd64": {
          "transport": "local"
        },
        "macos_arm64": {
          "transport": "ssh",
          "destinationEnv": "TSRUST_MACOS_SSH",
          "temporaryRootEnv": "TSRUST_MACOS_TEMP_ROOT"
        }
      },
      "smokeTestArgs": ["--version"],
      "verificationCommand": ["cargo", "test", "--manifest-path", "rust/Cargo.toml", "--workspace", "--locked"],
      "forwardEnvironment": ["NPM_TOKEN"]
    }
  }
}

matrix.verificationCommand is optional. It is an executable followed by literal arguments, with no shell expansion. It runs once per configured worker in that worker's exact-commit checkout, after frozen dependency installation and before the artifact build. Use ['pnpm', 'run', 'verify-native'] for a reviewed project script that combines Rust and public API qualification. A test failure, timeout, interruption or tracked-source mutation prevents artifact assembly and preserves the prior output. Verification inherits the restricted worker environment, pnpm age policy, shared one-hour worker deadline and owned process-group cleanup; SSH workers also retain the disconnect watchdog. Arguments are limited to 256 entries and 64 KiB total, with no NUL or line breaks. Keep credentials out of committed commands and test output.

Successful NativeMatrixBuilder.build() results include verifiedWorkers, the host keys on which verification completed; it is empty when no command was configured. matrix check checks capabilities only and does not run verification.

Set the referenced values outside the repository. The SSH destination may be an OpenSSH alias or user@host; the temporary root must be a dedicated absolute path owned by the remote account:

export TSRUST_MACOS_SSH="[email protected]"
export TSRUST_MACOS_TEMP_ROOT="/Users/release-user/.git.zone/tsrust/my-project"
export TSRUST_MATRIX_ALLOWED_ENVIRONMENT="NPM_TOKEN"

Builder keys are limited to linux_amd64, linux_arm64, macos_amd64, and macos_arm64. At most one worker may use transport: "local". Worker target partitions must be non-empty, disjoint, complete, and from the worker's OS family. Matrix execution probes support the six predefined targets linux_amd64, linux_arm64, linux_amd64_musl, linux_arm64_musl, macos_amd64, and macos_arm64. Native GNU targets require cc; non-native GNU probes use their predefined *-linux-gnu-gcc command. Musl probes always use their predefined *-linux-musl-gcc command. Non-native architectures also require executable emulation.

Environment-variable names must match [A-Za-z_][A-Za-z0-9_]*. Committed forwardEnvironment entries are requests, not grants: every requested name must also appear in the operator-owned comma-separated TSRUST_MATRIX_ALLOWED_ENVIRONMENT value or matrix construction fails. Built-in worker and transport names cannot be requested, including PATH, HOME, CI, RUSTUP_HOME, CARGO_HOME, SSH agent variables, and the grant variable itself. Worker lifecycle commands receive only a small execution baseline, synthetic per-run HOME and CARGO_HOME directories, and operator-granted names; unrelated coordinator credentials are omitted. For SSH workers, granted values are made available to the SSH client and admitted into project commands only when the remote login environment supplies them, such as through deliberate OpenSSH SendEnv/AcceptEnv configuration. Values are never placed in the remote command line. SSH destinations are ASCII single aliases or user@host values without embedded options, ports, whitespace, or IPv6 syntax. Put ports, identity files, proxy jumps, host-key policy, credentials, and agent selection in OpenSSH configuration or an SSH agent. Temporary roots use an ASCII path whitelist and must be normalized, space-free, multi-component absolute paths whose physical resolution contains no symlink traversal. When present, smokeTestArgs must be a non-empty array of single-line, NUL-free strings and must not contain secrets.

Matrix builds capture the coordinator repository's effective minimumReleaseAge, minimumReleaseAgeStrict, and minimumReleaseAgeExclude values using individual pnpm config get <key> --json calls. These three nonsecret policy values travel to every local and SSH worker through tSRust-owned PNPM_CONFIG_MINIMUM_RELEASE_AGE, PNPM_CONFIG_MINIMUM_RELEASE_AGE_STRICT, and PNPM_CONFIG_MINIMUM_RELEASE_AGE_EXCLUDE environment variables. These names cannot be requested through forwardEnvironment. Global scope exclusions and repository overrides therefore survive the synthetic worker home. SSH transport shell-quotes the policy values; unlike granted credentials, these nonsecret values are included in the remote command. Registry and authentication configuration is never enumerated or copied, and the coordinator process environment remains unchanged. Values must be valid JSON with a nonnegative integer age, boolean strictness, and a string-array exclusion list; unset values remain unset. The policy is limited to 32 KiB, at most 512 exclusions, and 1,024 characters per exclusion. Each worker reads all three values back before installation and fails if they differ from the captured policy. There is no age-gate bypass or fallback policy.

matrix check validates the coordinator's package-age policy and verifies the exact project-local tsrust package version without executing its binary, the native linker, system Cargo plus rustup with an active default toolchain and readable target manifest or the complete securely resolved bundled pair with cargo, rustc, and target-manifest readiness bound to that worker's exact managed stable toolchain, worker identity, emulation or cross-execution, and remote-root ownership and permissions. It is a capability-only command: it does not require a clean worktree or compare the working configuration with the committed plan. If usable system Cargo is unavailable and the bundled executables are either absent or securely resolved but not ready, it verifies only that curl is available for tsrust bootstrap or clean reinstall; it does not prove network access, install targets, or compile the project. The check creates the dedicated remote root with restrictive permissions when it is absent. Capability and cleanup commands have a five-minute limit. Dependency installation, configured verification, compilation, per-binary smoke execution, bundle upload, and bounded artifact retrieval share each worker's one-hour build limit.

Before a configured verification command runs, the worker selects usable system Cargo or prepares the bundled toolchain through the exact installed tsrust package. Bundled verification receives its host-specific Rustup selection and executable path while retaining the worker's private HOME and CARGO_HOME. This supports direct cargo, rustc and rustup calls inside verification scripts. Preparation failure prevents verification and artifact assembly; bootstrap and verification remain within the same worker deadline and process cleanup boundary.

Run the capability-only check before release metadata is created:

tsrust matrix check

Build and atomically publish the complete matrix from a clean exact Git commit:

tsrust matrix build

Every worker receives the same exact commit through a streamed Git bundle, installs with pnpm install --frozen-lockfile, revalidates the installed tsrust package version, invokes the project-local tsrust with explicit targets, and optionally executes every binary with smokeTestArgs. Local and remote project commands run with the restricted worker environment. Local and remote workers build in isolated clones, so an incomplete matrix never replaces an existing dist_rust. SSH workers use /bin/bash on Linux or /bin/zsh on macOS in login mode for builds, normal OpenSSH host verification, architecture and random-owner-marker validation on every lifecycle and transfer connection, locally and remotely byte-bounded non-login SSH streams for artifact retrieval, a heartbeat-bound process-group watchdog, and a unique mode-0700 child below the configured root. Remote owner-validated cleanup is a pre-publication gate: failure preserves the prior dist_rust and reports retained diagnostics. After successful assembly, failure to remove local staging emits a warning but does not reverse the committed publication.

matrix build additionally requires the normalized resolved matrix policy to match committed .smartconfig.json at the captured commit, a clean Git worktree without skip-worktree or assume-unchanged flags, package name and version, a frozen pnpm lockfile, and at least one Cargo binary. Matrix transport rejects Git submodules, tracked symbolic links, checkout filters, and external-content pointer records because those inputs are not self-contained regular files in a plain exact-commit bundle. Source compatibility, index flags, and the clean Git snapshot are revalidated around bundle creation and after project-controlled build and smoke commands. Binaries are limited to 2 GiB each, provenance sidecars to 1 MiB each, and an assembly to 8 GiB total. Worker keys are expected host identities, not network addresses. Keep only the SSH destination and temporary root in the referenced variables; keys and credentials remain in OpenSSH configuration or an agent. Failed workspaces are intentionally retained and are not pruned automatically; each local and remote root admits at most three retained failed runs and then requires the operator to inspect and remove the exact reported paths before retrying.

Matrix workers are trusted execution principals, not sandboxes. A release therefore trusts the reviewed exact source commit, its lockfile-selected dependencies and lifecycle/build scripts, the selected local and SSH hosts, their toolchains and login configuration, and the registries they contact. Environment filtering, owner markers, source checks, bounded transfers, provenance digests, and transactional publication prevent accidental credential inheritance, stale or incomplete inputs, endpoint mix-ups, and partial publication; they do not contain deliberately malicious code already running as the same operating-system user. Use a separately isolated worker account or container when that trust assumption does not hold.

Static Linking

For static Linux binaries, build the musl targets. They are statically linked by default, run on glibc distros (Debian/Ubuntu) and musl distros (Alpine) alike, and contain musl libc, which is MIT-licensed:

{
  "@git.zone/tsrust": {
    "targets": ["linux_amd64_musl", "linux_arm64_musl"],
    "static": true
  }
}

static: true (or --static per invocation) makes tsrust verify after the build that every Linux binary in dist_rust/ is statically linked (no PT_INTERP ELF program header — the check is architecture-independent, so cross-compiled binaries are verified too) and fail the build otherwise.

Behavior per target:

• *-linux-musl: statically linked by default; no flags are injected.
• *-linux-gnu: tsrust injects RUSTFLAGS="-C target-feature=+crt-static" and links glibc statically.
• *-apple-darwin: full static linking is not applicable on macOS; the target builds with default linkage.

Prefer musl over static glibc. glibc is licensed under the LGPL-2.1-or-later. A binary that links it statically must be distributed with the means to relink it that LGPL-2.1 section 6 requires: the application's object files or source, so users can relink it against a modified glibc, and the glibc source or a written offer for it. tsrust does not produce that material, and native notices refuse static glibc targets. Use the musl targets for static binaries, or leave GNU targets dynamically linked (without static): a dynamic binary loads the host's glibc at run time and redistributes none of it.

Why tsrust injects the crt-static flag for GNU targets instead of the project setting rustflags in rust/.cargo/config.toml:

• tsrust always builds with an explicit --target, so the flag never applies to host artifacts. A repo-wide rustflags entry also applies to proc-macros and build scripts whenever cargo runs without --target (plain cargo test, cargo check, rust-analyzer) — and rustc cannot build proc-macros with +crt-static on linux-gnu, breaking those commands.
• Keep rust/.cargo/config.toml free of rustflags when using static — the injected RUSTFLAGS environment variable replaces any config-file rustflags (cargo does not merge them). linker entries (e.g. for aarch64 cross-compilation) are unaffected and should stay.

Deterministic Path Remapping

Release binaries can embed absolute source paths in panic locations. Enable local path remapping to avoid publishing machine-specific paths:

{
  "@git.zone/tsrust": {
    "targets": ["linux_amd64_musl", "linux_arm64_musl"],
    "static": true,
    "remapLocalPaths": true
  }
}

remapLocalPaths adds Rust --remap-path-prefix flags for the project root, Rust source directory, Cargo home, and rustup home. Additional flags can be supplied explicitly through rustflags; these flags are combined with automatic flags such as -C target-feature=+crt-static for Linux GNU static builds:

{
  "@git.zone/tsrust": {
    "rustflags": ["--cfg=my_feature"]
  }
}

Native Notices

A package that ships native binaries must carry the license notices of everything those binaries contain: the Rust crates from Cargo.lock, C libraries that crates compile in, the Rust standard library, and the C runtime. tsrust notices generates them into a committed directory next to your sources, and every build verifies it:

{
  "@git.zone/tsrust": {
    "targets": ["linux_amd64_musl", "linux_arm64_musl"],
    "static": true,
    "locked": true,
    "notices": {}
  }
}

tsrust notices          # write native-notices/
tsrust notices --check  # verify without writing

Ship the directory with the package by listing it in package.json:

{
  "files": ["dist_rust/**/*", "native-notices/**/*"]
}

What the bundle holds (manifest.json records each package's license expression, the texts that cover it, each target's packages and runtime, and the SHA-256 digest of every file):

| Path | Contents | | --- | --- | | crates/<name>-<version>/ | Every license, copyright and notice file each third-party package publishes, copied verbatim. | | crates/<name>-<version>/extra/ | Reviewed extra texts the project declares for a package in notices.packages.<key>.extraTexts. | | native/<crate>-<version>/<library>-<version>/ | License files of C/C++ libraries a crate compiles in, as declared in notices.packages. | | rust/ | The toolchain's standard-library copyright inventory and license texts, compiler-builtins' license, and (rust/crates/) the license files of standard-library dependencies the inventory omits. | | runtime/ | musl's copyright (static musl targets), the glibc LGPL-2.1 text (dynamic GNU targets, glibc itself is not redistributed), and GCC's GPL-3.0 with the Runtime Library Exception (Linux targets). macOS targets link Apple's system libraries, which are not redistributed. | | readme.md | A summary of the targets, their linkage, and the obligations above. |

Packages are resolved per configured target with cargo metadata --locked --filter-platform <triple>: the normal and build dependencies of the workspace's binary packages, transitively, including procedural macros. Development dependencies and the workspace's own crates are excluded. The Rust runtime comes from the toolchain rust-toolchain.toml selects.

Generation fails instead of guessing when:

• a package declares no license, or an expression that is not valid SPDX (Cargo's legacy MIT/Apache-2.0 form is accepted);
• no license file of a package covers its expression: every AND term of at least one alternative needs a recognised license text;
• a package has a links key and does not declare the native libraries it compiles;
• a Linux GNU target is linked statically (see Static Linking);
• an override names no compiled package, or is no longer needed;
• an extra text is missing or its SHA-256 digest differs from its pin;
• the musl version in the toolchain has no reviewed copyright text in tsrust;
• package.json files does not ship the notices directory.

Overrides are keyed by the exact name@version, so a dependency upgrade retires them:

{
  "@git.zone/tsrust": {
    "notices": {
      "directory": "native-notices",
      "packages": {
        "[email protected]+zstd.1.5.7": {
          "native": [
            {
              "name": "zstd",
              "version": "1.5.7",
              "license": "BSD-3-Clause OR GPL-2.0-only",
              "files": ["zstd/LICENSE", "zstd/COPYING"]
            }
          ]
        },
        "[email protected]": {
          "files": [{ "from": "project", "path": "legal/crc32c-license-mit", "licenses": ["MIT"] }]
        },
        "[email protected]": {
          "extraTexts": [
            {
              "path": "legal/ring-0.17.14-once-cell-license-mit.txt",
              "sha256": "6ee2ed6c77710de911761acd5fc1ad1da00f476beb1a7ef27e78c2d1858deafc",
              "kind": "component-license",
              "component": "once_cell"
            },
            {
              "path": "legal/ring-0.17.14-source-attributions.txt",
              "sha256": "675df5a11ef946e519a267eba5f54ce8125eee0d0d443e614302706db4819459",
              "kind": "source-attribution"
            }
          ]
        }
      },
      "runtime": {
        "linux_amd64_musl": [
          { "name": "musl-cross", "version": "20260823", "license": "MIT", "files": ["legal/musl-cross-copyright"] }
        ]
      }
    }
  }
}

• packages.<key>.native: C/C++ libraries the crate compiles, with license files relative to the crate root. [] declares that a links crate bundles no third-party library.
• packages.<key>.files: reviewed texts for a package whose own files do not cover its license, either kept in the project ("from": "project") or a crate file whose wording tsrust does not recognise ("from": "crate"), with the SPDX identifiers each text satisfies.
• packages.<key>.extraTexts: reviewed project texts to ship with a package in addition to the texts that cover its license, for example the license of a component the crate vendors or a supplement reproducing the copyright comments of its sources. Each entry names the project-relative path, the file's lowercase hex sha256 digest, its kind ("component-license" or "source-attribution") and, optionally, the vendored component it applies to. The texts are copied to crates/<name>-<version>/extra/ (rust/crates/…/extra/ for standard-library dependencies) and listed with their kind under the package's extraTexts in manifest.json. They never count towards covering the package's license, so a package whose own files do not cover it still needs files, and files that are no longer needed still fail. Generation and every check refuse a missing text or one whose digest differs from its pin; after reviewing a changed text, update the pin.
• packages.<key>.license: only for a package that declares no license or one that is not valid SPDX.
• runtime.<target>: runtime material a custom linker adds, for example the startup files of a musl cross toolchain.

The build (tsrust) checks the notices before compiling when notices is configured, and refuses targets the notices do not cover. It first installs the rustup targets it builds and then, in the Rust directory and with the same toolchain, runs the check's own metadata command online, cargo metadata --format-version 1 --locked --filter-platform <triple> without --offline, once for every notices target, one after another, so a fresh CI container or developer machine with an empty Cargo cache builds without a manual step; the first failing run fails the build with its command, exit code, Rust directory and Cargo's error. Each run downloads exactly what the offline check then reads for that target: the packages the lockfile activates with default features for that target and for the host, where build scripts and procedural macros run. It does not use cargo fetch, which downloads the optional dependencies of every feature of every workspace member and, for several targets at once, the dependencies a package has on one target when another target uses it, none of which the check reads. Packages only other platforms use, such as cfg(windows) dependencies of a Linux build, and optional dependencies of features that nothing in the default-feature build enables are not downloaded, so a Cargo cache that tsrust notices or an earlier build filled on the same host is enough during a registry outage or offline. Git dependencies are cloned whole whatever the platform, because Cargo needs them to resolve the lockfile. If cargo metadata --offline still fails after the same command succeeded online, the error says so instead of the standalone advice. tsrust matrix check and tsrust matrix build check them once on the coordinator, before any worker starts; tsrust matrix build first runs the same online metadata on the coordinator, once per notices target, and stops before any worker when it fails. tsrust notices --check and tsrust matrix check still download nothing. Workers then build with --no-notices-check, which skips only that comparison. After a dependency, toolchain, or target change, run tsrust notices, review the diff, and commit it.

Apart from that build preparation, only tsrust notices uses the network and installs anything: it lets Cargo download missing packages, fetches the standard-library dependencies the toolchain inventory omits (verified against the checksums in the toolchain's library/Cargo.lock), and installs the rust-src component and missing musl targets. tsrust notices --check, tsrust matrix check and the check itself in tsrust and tsrust matrix build work offline and install nothing: they run cargo metadata --offline against the local Cargo cache, verify the committed rust/crates/ notices against the toolchain's checksums and the digests in manifest.json and the project's extra texts against their pins, and refuse with the command to run when something is missing (cargo fetch --locked for an empty Cargo cache, rustup component add rust-src, rustup target add <triple>).

The notices read the standard-library sources of the rust-src component and the C runtime of every configured musl target. No check installs them, and the build installs only the targets it builds, never rust-src. Declare them in the project's rust-toolchain.toml, so rustup installs them with the toolchain on every machine:

[toolchain]
channel = "1.95.0"
components = ["rust-src"]
targets = ["x86_64-unknown-linux-musl", "aarch64-unknown-linux-musl"]

Without the declaration, run rustup component add rust-src and rustup target add <triple> once per machine, or tsrust notices, which installs them.

With notices configured, every build refuses static glibc, including builds with --no-notices-check: static/--static on a GNU target, and +crt-static in the tsrust rustflags, RUSTFLAGS, CARGO_ENCODED_RUSTFLAGS, CARGO_BUILD_RUSTFLAGS or CARGO_TARGET_<TRIPLE>_RUSTFLAGS. Static linking configured elsewhere, such as rustflags in .cargo/config.toml, is caught after compiling: a GNU binary without an ELF interpreter is removed from dist_rust/ and the build fails.

🗑️ Clean Only

Remove all build artifacts without rebuilding:

tsrust clean

This runs cargo clean in the Rust directory and deletes the dist_rust/ output directory.

🧹 Prune Rust Target Caches

Report Rust target caches without deleting anything:

tsrust prune

Apply cleanup to marked tsrust-managed target caches:

tsrust prune --apply --days 14 --max-size 5GiB

Prune plans retain their thresholds and cache identity. Apply checks the marker, identity, complete scan, and current age/size again before removal. Symlinks, filesystem boundaries, unreadable entries, and incomplete scans are report-only. Active Rust tools or processes using the cache block removal. Linux builds and prune operations share a kernel-owned socket guard with a 30-second acquisition timeout; process inspection requires a readable /proc. Apply (including pruneAfterBuild) fails closed on other platforms. Dry-run reporting remains available. Direct Cargo commands do not participate in the tsrust guard: stop other Rust tools before applying a prune. Unmarked and conventional target directories remain report-only.

| Option | Description | | --- | --- | | --apply | Remove marked managed target caches that match the filters | | --days <n> | Prune marked caches whose newest file is at least n days old; default 14 | | --max-size <size> | Prune marked caches at or above a size such as 5GiB | | --workspace <path> | Inspect another workspace path |

Conventional rust/target and ts_rust/target directories are report-only, even if they carry a marker. Only managed .nogit/tsrust* target directories are eligible for --apply; arbitrary app data is never marked or removed.

Project Structure

tsrust expects your project to follow this layout:

my-project/
├── rust/                   # 🦀 Your Rust source code
│   ├── Cargo.toml          #    Root manifest (workspace or single crate)
│   ├── src/
│   │   └── main.rs         #    (for single-crate projects)
│   └── crates/             #    (for workspace projects)
│       ├── my-binary/
│       │   ├── Cargo.toml  #    Contains [[bin]] targets
│       │   └── src/
│       └── my-lib/
│           ├── Cargo.toml
│           └── src/
├── native-notices/         # ⚖️ Third-party notices (tsrust notices, committed)
├── dist_rust/              # 📦 Output: compiled binaries go here
│   ├── my-binary
│   └── my-binary.tsrust-build.json
├── .nogit/
│   └── tsrust-target/      # 🧹 Managed Cargo target cache
├── ts/                     #    (your TypeScript code, built by tsbuild)
├── dist_ts/                #    (TypeScript output)
└── package.json

Workspace Support

tsrust fully supports Cargo workspaces. It reads the [workspace] section from your root Cargo.toml, iterates through all members, and discovers binary targets from each member crate's Cargo.toml.

Binary target discovery follows Cargo's own rules:

• Explicit [[bin]] entries → uses the name field from each entry
• Implicit binary → if no [[bin]] is declared but src/main.rs exists, uses the [package] name
• Library-only crates → skipped (no binary output expected)

Fallback Directory

If no rust/ directory is found, tsrust checks for ts_rust/ as a fallback. This supports projects that use the ts_ prefix convention for all source directories.

Programmatic API

tsrust exports its internals for use in other Node.js/TypeScript tools:

import {
  ArtifactAssembler,
  CargoConfig,
  CargoRunner,
  FsHelpers,
  ProvenanceStore,
  NativeMatrixBuilder,
  TsRustCli,
  configuredAssemblyTargets,
  normalizeTargets,
  resolveBuildTargets,
  resolveManagedTargetDir,
} from '@git.zone/tsrust';

// Parse a Cargo workspace
const config = new CargoConfig('/path/to/rust');
const info = await config.parse();
console.log(info.isWorkspace);   // true
console.log(info.binTargets);    // ['rustproxy']

// Run cargo build
const runner = new CargoRunner('/path/to/rust');
const targetDir = resolveManagedTargetDir('/path/to/project');
const result = await runner.build({ debug: false, clean: false, targetDir });
console.log(result.success);     // true
console.log(result.exitCode);    // 0

// File helpers
await FsHelpers.ensureEmptyDir('/path/to/dist_rust');
await FsHelpers.copyFile(src, dest);
await FsHelpers.makeExecutable(dest);
const size = await FsHelpers.getFileSize(dest);
console.log(FsHelpers.formatFileSize(size));  // "13.4 MB"

Important exported build and artifact APIs:

| API | Purpose | | --- | --- | | resolveBuildTargets() | Apply CLI, exact-host, OS-family, legacy, and native target precedence. | | configuredAssemblyTargets() | Normalize and deduplicate the union required for multi-host assembly. | | normalizeTargets() | Resolve friendly aliases and reject invalid or colliding target names. | | ProvenanceStore | Write, hash-verify, and read byte-preserving provenance sidecars. | | ArtifactAssembler | Validate and transactionally publish a complete exact-commit artifact matrix to dist_rust/. | | NativeMatrixBuilder | Check and build an isolated local/SSH native matrix, then delegate publication to ArtifactAssembler. | | resolveMatrixPlan() / matrixHostKeys | Validate matrix configuration and inspect its complete disjoint worker schedule. | | MatrixCommandRunner | Execute bounded matrix subprocesses with process-group, signal, timeout, input, and heartbeat ownership. | | Matrix configuration and result types | Type NativeMatrixBuilder, worker transports, resolved plans, and check/build results. | | captureGitSnapshot() / assertGitSnapshotUnchanged() | Capture and compare Git commit and worktree state around a build. | | ProvenanceStamper | Read legacy tsrust 1.7/1.8 embedded trailers; new builds use ProvenanceStore. | | NativeNoticesGenerator / createProjectNoticesGenerator() | Generate, write, or check the native notices bundle of a project. | | parseSpdxExpression() / classifyLicenseText() | Expand SPDX expressions into alternatives and recognise license texts. |

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.