asm 0.5.0

asm 0.5.0

Version 0.5.0 adds inventory, upgrade, and uninstall commands for programs installed through Asm.
Published 0.4.0 artifacts remain unchanged and do not include these commands.

Host contract

Host	CLI artifact	Native project target
Linux x86-64	asm-0.5.0-x86_64-linux	x86_64-linux
Linux ARM64	asm-0.5.0-aarch64-linux	aarch64-linux
Apple Silicon, macOS 15 or later	asm-0.5.0-aarch64-macos	aarch64-macos

ISA means instruction set architecture. ABI means application binary interface.
The operating system, ABI, and CPU requirements are separate requirements.

CLI target	ISA	Operating system	ABI and executable format	CPU requirements
x86_64-linux	x86-64	Linux	Linux x86-64 system calls; little-endian ELF64	No optional CPU features declared.
aarch64-linux	AArch64	Linux	Linux AArch64 system calls; little-endian ELF64	ARMv8-A; no optional CPU features declared.
aarch64-macos	AArch64 (arm64)	macOS 15 or later	Apple arm64, Mach-O, and libSystem	Apple Silicon; no optional CPU features declared.

The Linux native CI runners use Ubuntu 24.04.
A minimum Linux kernel version has not been qualified separately.

Intel macOS, Windows x86-64, Windows ARM64, and a native Linux RISC-V64 CLI are not included.
The Linux RISC-V hello example does not establish native CLI support.
Project builds require GNU Binutils on Linux or Xcode Command Line Tools on macOS.

Manage installed programs

On Linux x86-64 or ARM64, install the hello executable:

asm install stubbi/hello@0.5.0

The default destination is $HOME/.local/bin/hello.
Use --output PATH to select another new destination.
Asm records both default and explicit destinations in $HOME/.local/state/asm/installed.tsv.
Each record contains the package, version, host target, digest, size, absolute path, and registry origin.
One package identity has at most one managed installation.

List recorded installations:

asm installed
asm installed --json

Listing reads the inventory without network access.
It does not verify that current executable files still match their records.
An empty JSON inventory is {"installed":[]}.

Upgrade a recorded program:

asm upgrade stubbi/hello

Upgrade selects the highest available numeric version for the host.
Use owner/name@version to select an exact version.
It retains the recorded destination and HTTPS registry origin.
Local-index installations require --index PATH again.
Upgrade rejects an older version, another registry origin, or changed bytes for an equal version.

Uninstall a recorded program:

asm uninstall stubbi/hello

Uninstall removes the recorded executable and its inventory entry.
It leaves the destination directory and other package data.
Install, upgrade, and uninstall do not execute the program.
They are quiet on success unless --json is supplied.

The commands update and remove continue to manage project source dependencies.
Use asm self update to update Asm itself.
The $HOME/.local/bin/asm destination and case variants remain reserved for that route.

File protection and recovery

Upgrade and uninstall check the recorded size and SHA-256 digest before changing a file.
They require a user-owned, single-link regular executable with protected permissions.
They refuse changed files, symlinks, malformed inventory records, and unmanaged destinations.

Programs installed before 0.5.0 have no inventory record.
Updating Asm does not adopt them, even when their names and bytes match a package.

Destination checks use the filesystem's filename rules, including case and Unicode aliases.
A temporary, empty destination with mode 000 protects recorded names during this check.
Cleanup removes it only when it still matches the owned probe.
Interruption or a cleanup failure can retain it for manual inspection.

Private staging and an advisory lock coordinate Asm operations.
Ordinary commit failures restore the prior executable and retain the prior inventory.
The lock does not constrain another process that runs under the same account.

The executable and inventory use separate filesystem entries.
Their updates are not one atomic transaction.
Process interruption or power failure can require manual recovery of staged files or mismatched records.
Retain those files for inspection; automatic crash recovery is not provided.
See the installed-program contract for the format, file boundaries, and recovery requirements.

Other changes

• Core commands return a nonzero exit status when their output cannot be written.
• Committed-source packaging and published-history checks ignore local Git object replacements.
• Source collectors check the aggregate byte limit before reading each file.
• Repository documentation clarifies the layout, reference manifest, host support, and retained performance measurements.

The source includes a disabled bundled-verifier profile for signed update authorization and release provenance.
Production activation still requires offline keys, metadata renewal, review, and recovery qualification.
This release retains the GitHub CLI 2.93.0-or-later installation and self-update contract.
See the migration gates and self-update contract.

Release evidence and limits

The release workflow requires native command tests and identical bytes from two clean builds for each CLI host.
It binds release artifacts to an exact source commit, sizes, digests, and GitHub release-provenance evidence.
Publication requires the workflow's validation of those final bytes.
This document does not record a completed release run.

Package integrity checks use the selected index's sizes and digests.
They do not establish publisher identity, registry freshness, or that a program is harmless.
The registry still has no separately signed expiry, rollback protection, or implemented emergency-revocation service.
Hosted public builds and formal verification remain planned.
See the security model for the full trust boundaries.