bashdeps.bash File Reference

Materializes exact SHA-256-pinned external artifacts for a project. More...

Functions
int	__bashdeps_usage ()
	Writes the supported command forms to standard output.
int	__bashdeps_diag (String message)
	Writes one bashdeps-prefixed diagnostic to standard error.
int	__bashdeps_reset_record ()
	Clears scratch fields used while parsing one dependency declaration.
int	__bashdeps_validate_path_text (String path)
	Validates the canonical textual form required for project-relative paths.
int	__bashdeps_validate_dest_text (String dest)
	Applies the canonical project-relative path grammar to a destination.
int	__bashdeps_set_dest_root (String root)
	Validates and stores an explicit destination containment root.
int	__bashdeps_dest_within_root (String dest)
	Tests whether a complete destination is strictly beneath the selected root.
int	__bashdeps_validate_record ()
	Validates the complete dependency record held in scratch globals.
int	__bashdeps_parse_tokens (String fields)
	Parses and validates one dependency declaration from named field tokens.
int	__bashdeps_array_contains (String needle, String values)
	Tests whether a value appears exactly in a supplied positional collection.
int	__bashdeps_append_record ()
	Appends the validated scratch record to the loaded dependency arrays.
int	__bashdeps_load_manifest (String manifest)
	Loads and validates an entire dependency manifest into parallel arrays.
int	__bashdeps_select_hash_backend ()
	Selects and caches one supported SHA-256 command implementation.
int	__bashdeps_hash_file (String path)
	Calculates the lowercase SHA-256 digest of one local file.
int	__bashdeps_parse_checksum_file (String path, String identity)
	Extracts one SHA-256 value from a narrowly formatted checksum resource.
int	__bashdeps_wget_has_required_controls ()
	Tests whether the local Wget help surface advertises required controls.
int	__bashdeps_select_download_backend ()
	Selects and caches one supported HTTPS downloader adapter.
int	__bashdeps_download_once (String url, String candidate)
	Performs one transfer attempt into a caller-provided staging candidate.
int	__bashdeps_download (String url, String candidate)
	Acquires one URL with bounded bashdeps-managed transfer attempts.
int	__bashdeps_project_root ()
	Reports the physical current working directory used as the project root.
int	__bashdeps_check_existing_path (String root, String dest)
	Rejects unsafe existing components along a complete destination path.
int	__bashdeps_check_parent_path (String root, String dest)
	Rejects unsafe existing parent components without inspecting the final path.
int	__bashdeps_destination_state (String root, String dest, String expected)
	Determines whether one destination already contains the approved bytes.
int	__bashdeps_make_stage (String root)
	Creates a private bashdeps-owned staging directory beneath the project root.
int	__bashdeps_cleanup_stage ()
	Removes the specifically recorded staging directory on a best-effort basis.
int	__bashdeps_ensure_parent (String root, String dest)
	Creates missing destination parent directories after validating their path.
int	__bashdeps_publish_candidate (String root, String dest, String candidate)
	Publishes one already-verified candidate conservatively at its destination.
int	__bashdeps_verify_loaded (String root)
	Verifies every loaded dependency destination without network or mutation.
int	__bashdeps_sync_loaded (String root)
	Converges every loaded dependency to its approved byte identity.
int	__bashdeps_cmd_install (String dest_root, String fields)
	Implements the public single-artifact install command.
int	__bashdeps_cmd_sync (String dest_root, String manifest)
	Implements manifest-wide dependency convergence for the public sync command.
int	__bashdeps_cmd_verify (String dest_root, String manifest)
	Implements network-free manifest verification for the public verify command.
int	__bashdeps_cmd_version ()
	Writes embedded version and source-build metadata to standard output.
int	__bashdeps_main (String command, String arguments)
	Dispatches the supported public CLI commands and aliases.

Variables
String	__bashdeps_version
	Semantic version reported by the version command.
String	__bashdeps_build_date
	Source revision timestamp or build date reported by the version command.
String	__bashdeps_build_commit
	Source commit identifier reported by the version command.
String	__bashdeps_record_id
	Scratch identity for the dependency record currently being parsed.
String	__bashdeps_record_url
	Scratch HTTPS URL for the dependency record currently being parsed.
String	__bashdeps_record_dest
	Scratch project-relative destination for the record currently being parsed.
String	__bashdeps_record_digest
	Scratch sha256: declaration for the record currently being parsed.
String	__bashdeps_record_digest_url
	Scratch optional HTTPS checksum URL for the record currently being parsed.
IndexedArray	__bashdeps_ids
	Loaded dependency identities in manifest order.
IndexedArray	__bashdeps_urls
	Loaded dependency acquisition URLs in manifest order.
IndexedArray	__bashdeps_dests
	Loaded project-relative dependency destinations in manifest order.
IndexedArray	__bashdeps_digests
	Loaded lowercase SHA-256 hexadecimal digests in manifest order.
IndexedArray	__bashdeps_digest_urls
	Loaded optional upstream checksum URLs in manifest order.
String	__bashdeps_stage_dir
	Active bashdeps-owned candidate staging directory for the current process.
String	__bashdeps_hash_backend
	Cached name of the selected SHA-256 command adapter.
String	__bashdeps_download_backend
	Cached name of the selected HTTPS download command adapter.
String	__bashdeps_dest_root
	Project-relative containment root permitted for dependency destinations.

Detailed Description

Materializes exact SHA-256-pinned external artifacts for a project.

bashdeps.bash provides the maintained implementation of the bashdeps command-line interface. The tool reads explicit dependency declarations, verifies local or acquired bytes against committed SHA-256 digests, and materializes only verified candidates beneath an invocation-selected project-relative destination root.

An optional explicit digest_url adds supplemental upstream SHA-256 corroboration when artifact acquisition is required. It never replaces the committed digest, is never inferred from the artifact URL, and is not fetched for already-correct local destinations or by network-free verify.

The implementation deliberately separates declaration parsing, runtime capability selection, acquisition, hashing, filesystem safety, staging, publication, and command dispatch. That separation keeps security-sensitive policy visible and allows each operation to fail conservatively without treating filenames, network success, or metadata as proof of artifact identity.

The supported consumer interface is the executable CLI. Functions and variables whose names begin with __bashdeps_ are private implementation details even though they are documented here for maintainers and reference generation. Sourcing this file leaves those private definitions available but does not create a supported sourced-function API.

verify is intentionally network-free and non-mutating. install and sync acquire bytes only when local destinations do not already match their approved digests. Acquired bytes are staged and verified before publication, and final destinations are hashed again before mutating operations report success.

Note

The physical current working directory is the project root for one command invocation. The manifest location does not redefine that root.

Warning

Version 1 does not coordinate concurrent mutating invocations. Path checks reduce ordinary symlink and traversal risk but do not claim openat-style race resistance against a hostile process changing the filesystem concurrently.

See also

doc/bashdeps-spec.md

doc/adr/ADR-014-documentation-first-source-code-commenting-standard.md

doc/adr/ADR-023-add-supplemental-upstream-sha256-verification.md

Examples

bash src/bashdeps.bash --help
bash src/bashdeps.bash verify dependencies.txt
bash src/bashdeps.bash sync --dest-root vendor dependencies.txt

Function Documentation

__bashdeps_append_record()

int __bashdeps_append_record

(

)

Appends the validated scratch record to the loaded dependency arrays.

Identity and destination uniqueness are set-wide manifest invariants. This helper checks both before mutating the parallel arrays, then appends the record fields at the same index. The stored digest has its sha256: prefix removed so later comparisons can use the raw digest produced by the hash adapter. Missing optional digest_url values are stored as aligned empty strings.

The function assumes __bashdeps_validate_record has already accepted the scratch record; it does not repeat field-level syntax checks.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic identifies a duplicate dependency identity or destination.

Returns

Nothing is written to STDOUT.

Return values

0	The record was appended to every loaded array.
2	The identity or destination duplicates a previously loaded record.

Examples

source src/bashdeps.bash
__bashdeps_ids=() __bashdeps_dests=() __bashdeps_urls=() __bashdeps_digests=() __bashdeps_digest_urls=()
__bashdeps_parse_tokens 'id=a@1' 'url=https://example.test/a' 'dest=vendor/a' 'digest=sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
__bashdeps_append_record

__bashdeps_array_contains()

int __bashdeps_array_contains	(	String	needle,
		String	values
	)

Tests whether a value appears exactly in a supplied positional collection.

The helper performs literal Bash string comparisons and does not interpret patterns, regular expressions, or package semantics. Manifest loading uses it to detect duplicate identities and destinations before appending a record.

Parameters

needle	Exact value to locate.
values	Values to search in order.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Nothing is written to STDERR.

Returns

Nothing is written to STDOUT.

Return values

0	At least one value exactly equals the needle.
1	No supplied value exactly equals the needle.

Examples

source src/bashdeps.bash
__bashdeps_array_contains 'vendor/a' 'vendor/a' 'vendor/b'

__bashdeps_check_existing_path()

int __bashdeps_check_existing_path	(	String	root,
		String	dest
	)

Rejects unsafe existing components along a complete destination path.

Starting from the physical project root, the helper examines each destination component that currently exists. Any symbolic link is rejected, including a final symlink. Existing parent components must be directories, and an existing final destination must be a regular file.

Missing components are allowed because synchronization may create parent directories later, after candidate preflight. This function therefore answers whether the existing filesystem state is safe to inspect or publish through; it does not require the destination to exist.

Parameters

root	Physical project root for the invocation.
dest	Canonical project-relative destination to inspect.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic identifies symbolic-link traversal or an incompatible file type.

Returns

Nothing is written to STDOUT.

Return values

0	Existing components satisfy the version 1 path-safety policy.
6	A symlink, non-directory parent, or non-regular final destination is present.

Examples

source src/bashdeps.bash
root=$(__bashdeps_project_root)
__bashdeps_check_existing_path "${root}" 'vendor/tool.bash'

__bashdeps_check_parent_path()

int __bashdeps_check_parent_path	(	String	root,
		String	dest
	)

Rejects unsafe existing parent components without inspecting the final path.

Parent creation needs to validate the path leading to a destination before and after mkdir -p. This helper walks every component except the final filename, rejecting symbolic links and existing non-directory parents while allowing components that do not yet exist.

The final destination is deliberately excluded because publication performs a separate complete-path check before replacement.

Parameters

root	Physical project root for the invocation.
dest	Canonical project-relative destination whose parents should be checked.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic identifies a symlink or non-directory parent component.

Returns

Nothing is written to STDOUT.

Return values

0	Existing parent components are acceptable or absent.
6	A parent component is a symlink or an existing non-directory.

Examples

source src/bashdeps.bash
root=$(__bashdeps_project_root)
__bashdeps_check_parent_path "${root}" 'vendor/deep/tool.bash'

__bashdeps_cleanup_stage()

int __bashdeps_cleanup_stage

(

)

Removes the specifically recorded staging directory on a best-effort basis.

Cleanup acts only on the exact path stored by __bashdeps_make_stage; it does not scan the project with broad filename patterns. Removal errors are intentionally ignored during cleanup so they do not replace the command's more meaningful acquisition, integrity, or publication status. The in-memory path is cleared after the attempt.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Cleanup errors are intentionally suppressed.

Returns

Nothing is written to STDOUT.

Return values

0	Cleanup completes or no active staging directory is recorded.

Examples

source src/bashdeps.bash
__bashdeps_stage_dir='/tmp/example-stage'
__bashdeps_cleanup_stage

__bashdeps_cmd_install()

int __bashdeps_cmd_install	(	String	dest_root,
		String	fields
	)

Implements the public single-artifact install command.

Each invocation begins with the default vendor containment policy. An optional leading --dest-root PATH replaces that policy only after validation. The remaining arguments must form one complete named-field dependency declaration, which is parsed using the same grammar and trust rules as a manifest record.

The validated scratch record is converted into a one-element loaded dependency set and passed to the common convergence engine. Existing correct bytes avoid network access, while missing or mismatched bytes follow the same staged, integrity-checked publication path as manifest synchronization.

Parameters

dest_root	Optional project-relative containment root supplied before fields.
fields	Four required dependency fields plus optional digest_url=.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT on successful installation.

STDERR

Usage, declaration, capability, acquisition, integrity, and filesystem failures are diagnosed here or by shared helpers.

Returns

Nothing is written to STDOUT on success.

Return values

0	The declared destination contains the approved bytes.
2	CLI policy or dependency declaration is invalid.
3	A required runtime capability is unavailable.
4	Artifact or checksum-resource network acquisition fails.
5	Acquired integrity verification fails.
6	Project-root resolution, filesystem safety, staging, publication, or final verification fails.

Examples

source src/bashdeps.bash
__bashdeps_cmd_install \
  'id=tool@1' \
  'url=https://example.test/tool' \
  'dest=vendor/tool' \
  'digest=sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' \
  'digest_url=https://example.test/tool.sha256'

__bashdeps_cmd_sync()

int __bashdeps_cmd_sync	(	String	dest_root,
		String	manifest
	)

Implements manifest-wide dependency convergence for the public sync command.

The command resets destination containment to vendor, optionally validates a leading alternate root, accepts at most one manifest pathname, and defaults to dependencies.txt. Manifest parsing and duplicate detection complete before the physical project root is resolved and the shared synchronization engine is entered.

The loaded engine performs whole-set candidate preflight, including any explicitly declared upstream checksum corroboration, before publication and never implements synchronization as a shell loop that re-evaluates manifest records as install commands.

Parameters

dest_root	Optional project-relative containment root supplied before the manifest.
manifest	Optional manifest path; defaults to dependencies.txt.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT on successful synchronization.

STDERR

CLI, manifest, capability, acquisition, integrity, and filesystem failures are diagnosed here or by shared helpers.

Returns

Nothing is written to STDOUT on success.

Return values

0	Every declared destination contains its approved bytes.
2	CLI policy or manifest content is invalid.
3	A required runtime capability is unavailable.
4	Artifact or checksum-resource network acquisition fails.
5	Acquired integrity verification fails.
6	Project-root resolution, filesystem safety, staging, publication, or final verification fails.

Examples

source src/bashdeps.bash
__bashdeps_cmd_sync dependencies.txt
__bashdeps_cmd_sync --dest-root third_party dependencies.txt

__bashdeps_cmd_verify()

int __bashdeps_cmd_verify	(	String	dest_root,
		String	manifest
	)

Implements network-free manifest verification for the public verify command.

The command resets destination containment to vendor, optionally validates a leading alternate root, accepts at most one manifest pathname, and defaults to dependencies.txt. After loading the complete manifest it resolves the physical project root and inspects current destination bytes through the shared verification engine.

No downloader is selected and no digest_url is fetched. The optional field is validated as declaration syntax during manifest loading, then ignored for local verification. No destination directory, file, mode, staging area, or other managed state is intentionally changed.

Parameters

dest_root	Optional project-relative containment root supplied before the manifest.
manifest	Optional manifest path; defaults to dependencies.txt.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT on successful verification.

STDERR

CLI, manifest, hash-capability, and filesystem-safety failures are diagnosed here or by shared helpers.

Returns

Nothing is written to STDOUT on success.

Return values

0	Every declared destination exists safely and matches its approved digest.
1	At least one declared destination is absent or mismatched.
2	CLI policy or manifest content is invalid.
3	SHA-256 capability is unavailable or hashing fails.
6	Project-root resolution or filesystem safety fails.

Examples

source src/bashdeps.bash
__bashdeps_cmd_verify dependencies.txt
__bashdeps_cmd_verify --dest-root third_party dependencies.txt

__bashdeps_cmd_version()

int __bashdeps_cmd_version

(

)

Writes embedded version and source-build metadata to standard output.

Version output intentionally identifies the distributed program as bashdeps.bash and reports the semantic version, source revision timestamp or build date, and source commit identifier on separate lines. Generated release artifacts inject these values during make build; direct maintained-source use may report development placeholders.

STDIN

Nothing is read from STDIN.

STDOUT

Three newline-terminated version/build metadata lines are written.

STDERR

Nothing is intentionally written to STDERR.

Returns

Three newline-terminated metadata lines: version, build date, and commit.

Return values

0	Version information was written successfully.

Examples

source src/bashdeps.bash
__bashdeps_cmd_version

__bashdeps_dest_within_root()

int __bashdeps_dest_within_root

(

String

dest

)

Tests whether a complete destination is strictly beneath the selected root.

Containment uses a path-component boundary by requiring the destination to begin with the selected root followed by /. This permits vendor/tool while rejecting both the root itself and look-alike prefixes such as vendor-old/tool.

Parameters

dest	Complete project-relative destination to test.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Nothing is written to STDERR.

Returns

Nothing is written to STDOUT.

Return values

0	The destination is strictly beneath the selected root.
1	The destination is outside the root or names the root itself.

Examples

source src/bashdeps.bash
__bashdeps_dest_root='vendor'
__bashdeps_dest_within_root 'vendor/tool.bash'
! __bashdeps_dest_within_root 'vendor-old/tool.bash'

__bashdeps_destination_state()

int __bashdeps_destination_state	(	String	root,
		String	dest,
		String	expected
	)

Determines whether one destination already contains the approved bytes.

The helper first applies existing-path safety checks. A missing destination is an ordinary unsatisfied state rather than a filesystem error. Existing regular files are hashed through the selected SHA-256 adapter and compared literally with the expected 64-character digest.

This is the central cache-validity rule: filename presence, timestamps, embedded versions, and file mode do not establish satisfaction. Only the bytes at a safe destination and their approved committed digest do. digest_url deliberately does not participate in this local-state check.

Parameters

root	Physical project root for the invocation.
dest	Canonical project-relative destination to inspect.
expected	Approved 64-character lowercase SHA-256 digest without a prefix.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Filesystem-safety diagnostics may be written.

Returns

Nothing is written to STDOUT.

Return values

0	The destination exists safely and its bytes match the approved digest.
1	The destination is absent or its bytes do not match.
3	SHA-256 capability is unavailable or hashing fails.
6	Existing filesystem state violates destination safety policy.

Examples

source src/bashdeps.bash
root=$(__bashdeps_project_root)
__bashdeps_destination_state "${root}" 'vendor/tool' '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'

__bashdeps_diag()

int __bashdeps_diag

(

String

message

)

Writes one bashdeps-prefixed diagnostic to standard error.

All arguments are joined using the shell's normal $* semantics and emitted as one diagnostic line. Centralizing the prefix makes operational errors easy to identify without requiring each caller to repeat program-name formatting.

Parameters

message

Words that form the diagnostic message.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

One line beginning with bashdeps.bash: followed by the supplied message.

Returns

Nothing is written to STDOUT.

Return values

0	The diagnostic was written successfully.

Examples

source src/bashdeps.bash
__bashdeps_diag "manifest is not readable: dependencies.txt"

__bashdeps_download()

int __bashdeps_download	(	String	url,
		String	candidate
	)

Acquires one URL with bounded bashdeps-managed transfer attempts.

The acquisition layer first requires a supported downloader, then makes at most three transfer attempts. Before each attempt it removes any prior candidate so partial bytes from an earlier failure cannot be mistaken for the current result. A successful transfer returns immediately; ordinary transport failures consume the remaining attempts.

Status 3 is treated specially because it represents the runtime-capability category used by backend selection. After all attempts fail, the helper maps the outcome to the public network-acquisition failure category. Integrity verification is intentionally not handled here because transport does not decide byte trust.

Parameters

url	Declared HTTPS URL to retrieve.
candidate	Private staging path used for each attempt.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is intentionally written to STDOUT.

STDERR

A final network-acquisition diagnostic is written after all attempts fail.

Returns

Nothing is intentionally written to STDOUT.

Return values

0	A transfer attempt succeeded.
3	A required downloader capability is unavailable or status 3 is propagated.
4	All permitted transfer attempts failed.
6	A stale candidate could not be removed before an attempt.

Examples

source src/bashdeps.bash
__bashdeps_download 'https://example.test/tool' '.bashdeps-stage/tool'

__bashdeps_download_once()

int __bashdeps_download_once	(	String	url,
		String	candidate
	)

Performs one transfer attempt into a caller-provided staging candidate.

The function delegates to the selected private transport adapter and never targets a declared dependency destination directly. Curl follows redirects while restricting both initial and redirected protocols to HTTPS, limiting redirects to ten, using a 10-second connection timeout, and bounding an attempt to 120 seconds. Wget uses quiet mode, a 120-second timeout, and exactly one backend-managed try.

A successful transfer establishes only that bytes were retrieved. Digest acceptance happens later and remains independent of transport success.

Parameters

url	Declared HTTPS URL to retrieve.
candidate	Private staging path that should receive transferred bytes.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is intentionally written to STDOUT.

STDERR

Downloader diagnostics may be written by the selected backend.

Returns

Nothing is intentionally written to STDOUT.

Return values

0	The selected downloader reported a successful transfer.
3	No supported downloader is selected or the invoked downloader itself returns status 3.

Note

Other nonzero downloader exit statuses are propagated to the caller unchanged.

Examples

source src/bashdeps.bash
__bashdeps_download_once 'https://example.test/tool' '.bashdeps-stage/example'

__bashdeps_ensure_parent()

int __bashdeps_ensure_parent	(	String	root,
		String	dest
	)

Creates missing destination parent directories after validating their path.

Publication is allowed to create required parent directories only after the calling convergence operation has completed declaration and candidate preflight. When a destination contains parent components, this helper checks all existing parents for symlinks and incompatible file types, runs mkdir -p, then checks them again before the caller writes a destination-adjacent temporary file.

Destinations with no slash have no project-relative parent to create and return successfully without filesystem mutation.

Parameters

root	Physical project root for the invocation.
dest	Canonical project-relative destination whose parents may be needed.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic identifies unsafe parents or an inability to create the directory tree.

Returns

Nothing is written to STDOUT.

Return values

0	Parent directories are present and pass the safety checks.
6	Parent validation or directory creation fails.

Examples

source src/bashdeps.bash
root=$(__bashdeps_project_root)
__bashdeps_ensure_parent "${root}" 'vendor/deep/tool.bash'

__bashdeps_hash_file()

int __bashdeps_hash_file

(

String

path

)

Calculates the lowercase SHA-256 digest of one local file.

The selected hash adapter is kept behind this helper so dependency-state logic does not depend on command-specific output. sha256sum is invoked directly; shasum is invoked with -a 256. In either case the first whitespace-delimited output field must be exactly 64 lowercase hexadecimal characters before it is accepted as a usable digest.

Parameters

path	Local file whose bytes should be hashed.

STDIN

Nothing is read from STDIN.

STDOUT

The 64-character lowercase SHA-256 digest is written on success.

STDERR

Nothing is intentionally written to STDERR by this helper.

Returns

The 64-character lowercase SHA-256 digest followed by a newline.

Return values

0	A valid SHA-256 digest was calculated and written.
3	The hash backend is unavailable, hashing fails, or output is not a valid digest.

Examples

source src/bashdeps.bash
digest=$(__bashdeps_hash_file vendor/tool.bash)
printf '%s\n' "${digest}"

__bashdeps_load_manifest()

int __bashdeps_load_manifest

(

String

manifest

)

Loads and validates an entire dependency manifest into parallel arrays.

Loading begins by clearing previously loaded records, then requires the manifest to be a readable regular file. Blank lines and lines whose first non-horizontal whitespace character is # are ignored. Every other line is split on spaces and tabs into named-field tokens and parsed using the same record logic as the explicit install command.

The complete manifest is validated before synchronization begins acquisition or publication. Duplicate identities and destinations therefore fail before any dependency candidate is downloaded for that command invocation.

Parameters

manifest

Path to the dependency manifest to read.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic identifies an unreadable manifest or the line containing an invalid record.

Returns

Nothing is written to STDOUT.

Return values

0	Every non-comment record was loaded and validated successfully.
2	The manifest is unreadable or contains an invalid or duplicate record.

Examples

source src/bashdeps.bash
__bashdeps_load_manifest dependencies.txt
printf '%s\n' "${#__bashdeps_ids[@]} dependencies loaded"

__bashdeps_main()

int __bashdeps_main	(	String	command,
		String	arguments
	)

Dispatches the supported public CLI commands and aliases.

The dispatcher requires a command, removes that token, and delegates dependency operations to their command handlers. help, -h, and --help are equivalent and accept no additional arguments. version and --version are likewise equivalent and argument-free. Unknown or missing commands are usage errors and write concise usage guidance to standard error.

The dispatcher returns command-handler statuses unchanged, preserving the public categories documented in ADR-007 and refined by ADR-023. The direct-execution guard invokes it only when the file is executed as a process.

Parameters

command	Public command or supported help/version alias.
arguments	Remaining arguments for the selected command.

STDIN

Nothing is read directly by the dispatcher.

STDOUT

Help or version text is written only for the corresponding informational commands.

STDERR

Missing and unknown commands include a diagnostic plus usage; operational diagnostics come from command handlers.

Returns

Help or version text when those informational commands are selected.

Return values

0	The selected operation succeeds or help/version output is produced.
1	Verification completes with one or more absent or mismatched destinations.
2	CLI usage, manifest syntax, declaration, or destination-root policy is invalid.
3	A required runtime capability is unavailable or unusable.
4	Artifact or checksum-resource network acquisition fails.
5	Acquired integrity verification fails.
6	Filesystem safety, staging, publication, or related operational handling fails.

Examples

source src/bashdeps.bash
__bashdeps_main --help
__bashdeps_main verify dependencies.txt

__bashdeps_make_stage()

int __bashdeps_make_stage

(

String

root

)

Creates a private bashdeps-owned staging directory beneath the project root.

Network candidates are kept away from final destinations so failed or unverified transfers cannot overwrite useful local bytes. The helper tries up to five process-and-random-derived names and creates the first available directory with mode 0700, then records that exact path for later cleanup.

Parameters

root	Physical project root under which staging should be created.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic is written when staging cannot be allocated.

Returns

Nothing is written to STDOUT.

Return values

0	A private staging directory was created and recorded.
6	No staging directory could be allocated after the bounded attempts.

Examples

source src/bashdeps.bash
root=$(__bashdeps_project_root)
__bashdeps_make_stage "${root}"
printf '%s\n' "${__bashdeps_stage_dir}"

__bashdeps_parse_checksum_file()

int __bashdeps_parse_checksum_file	(	String	path,
		String	identity
	)

Extracts one SHA-256 value from a narrowly formatted checksum resource.

ADR-023 permits exactly one non-blank checksum entry. The digest token may be bare or prefixed with sha256:; an omitted algorithm defaults to SHA-256. Conventional text or binary-marker filename suffixes are accepted but ignored as trust input. Other explicit algorithms, multiple entries, comments, and malformed syntax fail closed. Hexadecimal digest text is normalized to lowercase before comparison.

Parameters

path	Downloaded checksum-resource path in private staging.
identity	Dependency identity used only for diagnostics.

STDIN

Nothing is read from STDIN.

STDOUT

The normalized 64-character lowercase SHA-256 digest is written on success.

STDERR

A diagnostic identifies empty, multi-entry, or malformed checksum content.

Returns

The normalized SHA-256 digest followed by a newline on success.

Return values

0	Exactly one supported checksum entry was parsed.
5	The checksum resource was unreadable or syntactically unusable.

Examples

digest=$(__bashdeps_parse_checksum_file '.bashdeps-stage/checksum' 'tool@1')

__bashdeps_parse_tokens()

int __bashdeps_parse_tokens

(

String

fields

)

Parses and validates one dependency declaration from named field tokens.

The parser resets prior scratch state, requires each token to contain =, and splits only at the first equals sign so additional equals characters remain data inside values such as URL query strings. Field order is irrelevant. The four historical fields remain mandatory, digest_url is optional, and duplicate or unknown field names fail closed.

Successful parsing leaves scratch globals populated and delegates field-specific policy checks to __bashdeps_validate_record. Manifest text is never sourced, evaluated, or sent back through a shell parser.

Parameters

fields

Required id=, url=, dest=, and digest= tokens plus optional digest_url=.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic describes malformed, duplicate, unknown, or invalid fields.

Returns

Nothing is written to STDOUT.

Return values

0	The declaration was parsed and validated successfully.
2	The declaration is malformed, incomplete, duplicated, unknown, or invalid.

Examples

source src/bashdeps.bash
__bashdeps_parse_tokens \
  'id=tool@1' \
  'url=https://example.test/tool?x=1&y=2' \
  'dest=vendor/tool' \
  'digest=sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' \
  'digest_url=https://example.test/tool.sha256'

__bashdeps_project_root()

int __bashdeps_project_root

(

)

Reports the physical current working directory used as the project root.

bashdeps deliberately avoids Git-root discovery and does not anchor destinations to the manifest's directory. pwd -P resolves the invocation's current working directory physically so subsequent relative destination checks share one stable root string for the duration of the command.

STDIN

Nothing is read from STDIN.

STDOUT

The physical current working directory is written.

STDERR

Nothing is intentionally written to STDERR.

Returns

The physical current working directory followed by a newline.

Return values

0	The physical working directory was written successfully.

Examples

source src/bashdeps.bash
root=$(__bashdeps_project_root)
printf '%s\n' "${root}"

__bashdeps_publish_candidate()

int __bashdeps_publish_candidate	(	String	root,
		String	dest,
		String	candidate
	)

Publishes one already-verified candidate conservatively at its destination.

This helper is intentionally downstream of all applicable candidate integrity verification. It ensures the parent path exists safely, rechecks the current destination, and allocates a destination-adjacent temporary name so the final replacement can use same-directory rename behavior. Candidate bytes are copied into that temporary file, assigned mode 0644, and the destination path is checked again immediately before mv -f replaces the final file.

Publication does not itself decide whether candidate bytes are trusted and does not hash them. Callers must provide a verified staging candidate and perform final destination verification after publication. Failure cleanup targets only the exact temporary path allocated by this invocation.

Parameters

root	Physical project root for the invocation.
dest	Canonical project-relative final destination.
candidate	Staged candidate whose bytes have already passed integrity verification.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic identifies parent, allocation, copy, mode, path-safety, or rename failure.

Returns

Nothing is written to STDOUT.

Return values

0	The candidate was replaced into the final destination.
6	Filesystem safety, staging beside the destination, mode setting, or publication fails.

Examples

source src/bashdeps.bash
root=$(__bashdeps_project_root)
__bashdeps_publish_candidate "${root}" 'vendor/tool' '.bashdeps-stage/0'

__bashdeps_reset_record()

int __bashdeps_reset_record

(

)

Clears scratch fields used while parsing one dependency declaration.

Parsing is intentionally stateful inside one shell process so manifest records and explicit install arguments can share validation logic. Resetting every scratch field before a new parse prevents omitted fields from inheriting values from a previous record.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Nothing is written to STDERR.

Returns

Nothing is written to STDOUT.

Return values

0	The scratch record fields were cleared.

Examples

source src/bashdeps.bash
__bashdeps_record_id='old@1'
__bashdeps_reset_record

__bashdeps_select_download_backend()

int __bashdeps_select_download_backend

(

)

Selects and caches one supported HTTPS downloader adapter.

An existing selection is reused. Otherwise curl is preferred whenever the command is present. Wget is considered only when curl is unavailable and the local help surface exposes the required timeout and retry-count controls. This keeps transport-specific capabilities behind one adapter boundary while avoiding operating-system assumptions.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic is written when neither supported downloader is usable.

Returns

Nothing is written to STDOUT.

Return values

0	A downloader is selected in __bashdeps_download_backend.
3	No supported HTTPS downloader is available.

Examples

source src/bashdeps.bash
__bashdeps_download_backend=''
__bashdeps_select_download_backend
printf '%s\n' "${__bashdeps_download_backend}"

__bashdeps_select_hash_backend()

int __bashdeps_select_hash_backend

(

)

Selects and caches one supported SHA-256 command implementation.

Selection is capability-based rather than operating-system-based. An existing cached selection is reused. Otherwise sha256sum is preferred and shasum is the fallback. No other command is chosen opportunistically because each supported adapter has explicit output and invocation semantics.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic is written when neither supported SHA-256 command is available.

Returns

Nothing is written to STDOUT.

Return values

0	A supported hash backend is selected in __bashdeps_hash_backend.
3	No supported SHA-256 implementation is available.

Examples

source src/bashdeps.bash
__bashdeps_hash_backend=''
__bashdeps_select_hash_backend
printf '%s\n' "${__bashdeps_hash_backend}"

__bashdeps_set_dest_root()

int __bashdeps_set_dest_root

(

String

root

)

Validates and stores an explicit destination containment root.

One or more trailing slashes are removed before validation so common directory spellings such as vendor/ and vendor select the same policy. The normalized value must still satisfy the canonical relative-path grammar. Invalid input is rejected before the global policy changes.

Parameters

root	Project-relative root supplied by --dest-root.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A diagnostic names the invalid root when validation fails.

Returns

Nothing is written to STDOUT.

Return values

0	The normalized destination root was stored.
2	The supplied root is invalid CLI policy.

Examples

source src/bashdeps.bash
__bashdeps_set_dest_root 'third_party/'
printf '%s\n' "${__bashdeps_dest_root}"

__bashdeps_sync_loaded()

int __bashdeps_sync_loaded

(

String

root

)

Converges every loaded dependency to its approved byte identity.

Synchronization first inspects every loaded destination and records only missing or mismatched entries as needing acquisition. If all destinations already match, it returns without requiring a downloader or fetching an optional checksum URL. Otherwise it selects hashing and download capabilities, creates private staging, and installs an EXIT trap for narrowly scoped cleanup.

Every required artifact candidate is downloaded and compared with the committed SHA-256 digest. When a record declares digest_url, the explicit checksum resource is then downloaded through the same adapter, parsed under ADR-023's narrow grammar, and required to yield the same artifact SHA-256. All applicable checks for every candidate complete before intentional publication begins.

Verified candidates are published in manifest order, after which all loaded destinations are hashed again against committed digests. Whole-set preflight reduces predictable partial updates but does not make multi-file publication globally atomic.

Parameters

root	Physical project root for the invocation.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT on successful convergence.

STDERR

Diagnostics identify capability, acquisition, integrity, filesystem, or final-verification failures.

Returns

Nothing is written to STDOUT on success.

Return values

0	Every loaded destination contains its approved bytes after the operation.
3	A required runtime hash or downloader capability is unavailable.
4	Artifact or checksum-resource acquisition exhausts its permitted attempts.
5	Acquired integrity verification fails against committed or upstream checksum data.
6	Filesystem safety, staging, publication, cleanup prerequisite, or final verification fails.

Examples

source src/bashdeps.bash
__bashdeps_load_manifest dependencies.txt
root=$(__bashdeps_project_root)
__bashdeps_sync_loaded "${root}"

__bashdeps_usage()

int __bashdeps_usage

(

)

Writes the supported command forms to standard output.

The helper centralizes usage wording so explicit help and usage-error paths show the same command surface. Callers that need usage on standard error redirect this helper rather than maintaining a second copy of the text.

STDIN

Nothing is read from STDIN.

STDOUT

Human-readable CLI usage text is written.

STDERR

Nothing is intentionally written to STDERR.

Returns

Human-readable CLI usage text.

Return values

0	Usage text was written successfully.

Examples

source src/bashdeps.bash
__bashdeps_usage

__bashdeps_validate_dest_text()

int __bashdeps_validate_dest_text

(

String

dest

)

Applies the canonical project-relative path grammar to a destination.

Destination text currently has the same lexical requirements as destination-root text. This wrapper preserves a destination-specific call boundary so future destination validation can evolve without spreading generic path checks through the parser.

Parameters

dest	Project-relative dependency destination to validate.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Nothing is written to STDERR.

Returns

Nothing is written to STDOUT.

Return values

0	The destination uses the accepted canonical relative form.
1	The destination violates the canonical relative-path grammar.

Examples

source src/bashdeps.bash
__bashdeps_validate_dest_text 'vendor/mktext.bash'

__bashdeps_validate_path_text()

int __bashdeps_validate_path_text

(

String

path

)

Validates the canonical textual form required for project-relative paths.

The check rejects empty paths, absolute paths, trailing separators, repeated separators, whitespace, and components equal to . or ... This lexical normalization rule prevents multiple textual aliases from bypassing containment or duplicate-destination checks without introducing a realpath dependency.

This helper validates text only. Symlink and file-type checks are performed separately against the filesystem before inspection or publication.

Parameters

path	Project-relative path text to validate.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Nothing is written to STDERR.

Returns

Nothing is written to STDOUT.

Return values

0	The path uses the accepted canonical relative form.
1	The path is empty, absolute, aliased, traversal-bearing, or contains whitespace.

Examples

source src/bashdeps.bash
__bashdeps_validate_path_text 'vendor/tool.bash'
! __bashdeps_validate_path_text '../outside/tool.bash'

__bashdeps_validate_record()

int __bashdeps_validate_record

(

)

Validates the complete dependency record held in scratch globals.

A valid record has non-empty identity, URL, destination, and digest fields. The artifact URL must use HTTPS, the destination must use canonical relative text and remain strictly beneath the selected destination root, and the digest must be sha256: followed by exactly 64 lowercase hexadecimal characters. An optional digest_url must also use HTTPS when present.

Identity text remains opaque after non-emptiness is established. This function therefore validates declaration syntax and write policy without pretending that labels or URLs prove artifact identity; the committed digest remains authoritative.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

A field-specific diagnostic explains the first validation failure.

Returns

Nothing is written to STDOUT.

Return values

0	The scratch record is valid for the selected destination policy.
2	The record is incomplete or contains an invalid URL, destination, or digest.

Examples

source src/bashdeps.bash
__bashdeps_record_id='tool@1'
__bashdeps_record_url='https://example.test/tool'
__bashdeps_record_dest='vendor/tool'
__bashdeps_record_digest='sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
__bashdeps_record_digest_url='https://example.test/tool.sha256'
__bashdeps_validate_record

__bashdeps_verify_loaded()

int __bashdeps_verify_loaded

(

String

root

)

Verifies every loaded dependency destination without network or mutation.

The loaded arrays are expected to be index-aligned and already validated. Each destination is inspected through the common byte-satisfaction helper. Missing or mismatched bytes are accumulated as an ordinary unsatisfied verification result so the loop can inspect the complete declaration set; capability and filesystem-safety failures stop immediately because continuing cannot produce a trustworthy verification result.

This function performs no downloader selection, checksum-resource acquisition, directory creation, chmod, or publication. A declared digest_url is ignored after manifest syntax validation because ADR-023 defines it as acquisition-time corroboration rather than a live verification source.

Parameters

root	Physical project root for the invocation.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Filesystem and hash-capability diagnostics may be written.

Returns

Nothing is written to STDOUT.

Return values

0	Every loaded destination exists safely and matches its approved digest.
1	At least one loaded destination is absent or mismatched.
3	SHA-256 capability is unavailable or hashing fails.
6	Filesystem safety fails or an unexpected internal state is encountered.

Examples

source src/bashdeps.bash
__bashdeps_load_manifest dependencies.txt
root=$(__bashdeps_project_root)
__bashdeps_verify_loaded "${root}"

__bashdeps_wget_has_required_controls()

int __bashdeps_wget_has_required_controls

(

)

Tests whether the local Wget help surface advertises required controls.

A command named wget is not automatically considered a usable fallback. Version 1 requires -T timeout control and -t tries control so the acquisition layer can keep each backend invocation bounded and own the overall attempt count. The probe is local and performs no network request. A nonzero wget --help status is ignored because the advertised text, when present, is the capability evidence this helper examines.

STDIN

Nothing is read from STDIN.

STDOUT

Nothing is written to STDOUT.

STDERR

Nothing is intentionally written to STDERR.

Returns

Nothing is written to STDOUT.

Return values

0	Both -T and -t appear in recognized help forms.
1	At least one required control is not advertised.

Examples

source src/bashdeps.bash
if __bashdeps_wget_has_required_controls; then printf '%s\n' 'wget usable'; fi

Variable Documentation

__bashdeps_build_commit

__bashdeps_build_commit

Source commit identifier reported by the version command.

The build system supplies this metadata for generated artifacts. Runtime behavior does not otherwise depend on Git or on this value.

Bash variable: read-write string

__bashdeps_build_date

__bashdeps_build_date

Source revision timestamp or build date reported by the version command.

Generated artifacts inject release metadata. Maintained source uses unknown when no build layer has supplied a value.

Bash variable: read-write string

__bashdeps_dest_root

__bashdeps_dest_root

Project-relative containment root permitted for dependency destinations.

Command handlers reset this policy to vendor for every operation and replace it only after validating an explicit --dest-root value. The root constrains complete dest= values; it is never prepended to or used to relocate them.

Bash variable: read-write string

__bashdeps_dests

__bashdeps_dests

Loaded project-relative dependency destinations in manifest order.

Duplicate destinations are rejected so one synchronization set cannot contain two declarations competing to manage the same path.

Bash variable: read-write indexed_array

__bashdeps_digest_urls

__bashdeps_digest_urls

Loaded optional upstream checksum URLs in manifest order.

The array is index-aligned with all other loaded record arrays. Four-field declarations contribute an empty string, preserving their existing acquisition behavior without any checksum-resource request.

Bash variable: read-write indexed_array

__bashdeps_digests

__bashdeps_digests

Loaded lowercase SHA-256 hexadecimal digests in manifest order.

Values omit the manifest's sha256: prefix because the selected hash adapters already produce bare hexadecimal digests for comparison.

Bash variable: read-write indexed_array

__bashdeps_download_backend

__bashdeps_download_backend

Cached name of the selected HTTPS download command adapter.

Selection prefers curl. wget is eligible only when curl is absent and the local Wget help surface advertises the timeout and tries controls required by the version 1 acquisition policy.

Bash variable: read-write string

__bashdeps_hash_backend

__bashdeps_hash_backend

Cached name of the selected SHA-256 command adapter.

Selection prefers sha256sum, falls back to shasum, and fails when neither supported capability is available. An already selected value avoids repeated command discovery within one process.

Bash variable: read-write string

__bashdeps_ids

__bashdeps_ids

Loaded dependency identities in manifest order.

This array is kept index-aligned with the URL, destination, digest, and optional checksum-URL arrays. Duplicate identities are rejected before a record is appended.

Bash variable: read-write indexed_array

__bashdeps_record_dest

__bashdeps_record_dest

Scratch project-relative destination for the record currently being parsed.

Validation requires canonical relative path text and containment beneath the invocation's selected destination root before this value can enter loaded state.

Bash variable: read-write string

__bashdeps_record_digest

__bashdeps_record_digest

Scratch sha256: declaration for the record currently being parsed.

A valid value contains exactly 64 lowercase hexadecimal characters after the sha256: prefix. Loaded state stores only that hexadecimal portion.

Bash variable: read-write string

__bashdeps_record_digest_url

__bashdeps_record_digest_url

Scratch optional HTTPS checksum URL for the record currently being parsed.

An empty value means the declaration uses the historical four-field contract. When non-empty, the URL is explicit source and is never derived from url=.

Bash variable: read-write string

__bashdeps_record_id

__bashdeps_record_id

Scratch identity for the dependency record currently being parsed.

Record parsing resets this value before reading a new declaration. The value is opaque metadata after validation and is not used as proof of artifact identity.

Bash variable: read-write string

__bashdeps_record_url

__bashdeps_record_url

Scratch HTTPS URL for the dependency record currently being parsed.

The parser preserves the field value literally after the first = delimiter. Validation later requires the value to begin with https://.

Bash variable: read-write string

__bashdeps_stage_dir

__bashdeps_stage_dir

Active bashdeps-owned candidate staging directory for the current process.

The value is empty until staging is required. A successful staging allocation uses a private directory beneath the project root with mode 0700; cleanup removes that known path on ordinary shell exit after synchronization begins.

Bash variable: read-write string

__bashdeps_urls

__bashdeps_urls

Loaded dependency acquisition URLs in manifest order.

Element indexes correspond directly to the other loaded dependency arrays.

Bash variable: read-write indexed_array

__bashdeps_version

__bashdeps_version

Semantic version reported by the version command.

Release builds inject this value before the maintained source is appended to a generated artifact. Direct execution of maintained source uses 0.0.0-dev unless a caller intentionally defines the variable first.

Bash variable: read-write string