vpackage

new_manifest(name, version)

Builds a fresh, empty package manifest as a plain map: a name, a version, and a dependencies map with no entries yet.

new_manifest("my-app", "0.1.0")

add_dependency_path(manifest, name, location)

Records one dependency in manifest as coming from a local directory: a spec map with "kind" set to "path" and "location" set to location (interpreted later, by resolve_relative, as relative to the manifest's own directory unless it starts with "/").

add_dependency_path(new_manifest("my-app", "0.1.0"), "utils", "../shared/utils")

add_dependency_archive(manifest, name, location)

Records one dependency in manifest as coming from a local archive file: a spec map with "kind" set to "archive" and "location" set to location (a .zip or .tar/.tar.gz path, distinguished later by install_from_archive purely on its file extension).

add_dependency_archive(new_manifest("my-app", "0.1.0"), "utils", "vendor/utils.zip")

dependency_names(manifest)

dependency_names(add_dependency_path(new_manifest("my-app", "0.1.0"), "utils", "../utils"))

save_manifest(path, manifest)

Writes manifest to path as pretty-printed JSON (the second, yes argument to json_encode is the indent flag), the on-disk form of a project's venutian.json.

save_manifest("venutian.json", new_manifest("my-app", "0.1.0"))

load_manifest(path)

Reads path and decodes it as a manifest map: the exact inverse of save_manifest.

load_manifest("venutian.json")

manifest_path_in(directory)

The conventional manifest path inside directory: always <directory>/venutian.json, joined with path_join rather than plain concatenation so it comes out right whether or not directory already ends in a slash.

manifest_path_in("venutian_packages/utils")

has_own_manifest(package_dir)

Whether package_dir has its own venutian.json, which is what makes it a package with its own dependencies rather than a plain bundle of source files.

has_own_manifest("venutian_packages/utils")

resolve_relative(base_dir, location)

Resolves a dependency's location against the directory its OWN manifest lives in, matching uses own relative-to-the-importing-file convention rather than the process's current working directory.

resolve_relative("/projects/my-app", "../shared/utils")

ensure_directory(directory)

ensure_directory("venutian_packages")

copy_directory_contents(source_dir, dest_dir)

Recursively copies every file and subdirectory from source_dir into dest_dir, creating dest_dir first if needed.

copy_directory_contents("../shared/utils", "venutian_packages/utils")

destination_for(packages_dir, name)

The conventional installed location for a package named name inside packages_dir: always <packages_dir>/<name>.

destination_for("venutian_packages", "utils")

clear_existing(dest)

Removes dest and everything under it, if it exists, so a fresh install never mixes leftover files from a previous version of the same package with the new one.

clear_existing("venutian_packages/utils")

install_from_path(name, source_dir, packages_dir)

Installs a package from a local directory: ensures packages_dir exists, clears out any previous install at the same destination, then copies source_dirs contents in whole.

install_from_path("utils", "../shared/utils", "venutian_packages")

install_from_archive(name, archive_path, packages_dir)

Installs a package from a local archive file: ensures packages_dir exists, clears out any previous install at the same destination, then extracts archive_path into it, using zip_extract_all for a .zip and tar_extract_all for anything else (in practice, a .tar or .tar.gz).

install_from_archive("utils", "vendor/utils.zip", "venutian_packages")

install_dependency(name, spec, manifest_dir, packages_dir)

Installs a single dependency according to its own spec's "kind": resolves specs "location" against manifest_dir first, then dispatches to install_from_path for kind "path" or install_from_archive for kind "archive".

manifest = add_dependency_path(new_manifest("a", "0.1.0"), "utils", "../utils")
spec = map_get(map_get(manifest, "dependencies"), "utils")
install_dependency("utils", spec, ".", "venutian_packages")

install_all(manifest, manifest_dir, packages_dir)

install_all(load_manifest("venutian.json"), ".", "venutian_packages")

is_installed(name, packages_dir)

Whether a package named name is currently installed: true exactly when its conventional destination directory exists.

is_installed("utils", "venutian_packages")

list_installed(packages_dir)

Lists every currently installed package: each subdirectory directly under packages_dir.

list_installed("venutian_packages")

uninstall(name, packages_dir)

Removes an installed package's whole destination directory.

uninstall("utils", "venutian_packages")

resolve_transitive(manifest, manifest_dir, packages_dir)

Installs every dependency manifest declares AND every dependency those dependencies declare in their own venutian.json, recursively, each installed exactly once even if named by more than one package along the way.

resolve_transitive(load_manifest("venutian.json"), ".", "venutian_packages")

resolve_one(name, spec, manifest_dir, packages_dir, resolved, resolving)

Installs one dependency and recurses into its own dependencies, if it has any (per has_own_manifest), used internally by resolve_transitive to walk the whole dependency graph.

deps = map_get(load_manifest("venutian.json"), "dependencies")
resolve_one("utils", map_get(deps, "utils"), ".", "venutian_packages", new_set(), new_set())

content_hash_of_directory(directory)

content_hash_of_directory("venutian_packages/utils")

generate_lockfile(package_names, packages_dir)

Builds a lockfile map recording each named package's current content hash, computed with content_hash_of_directory.

generate_lockfile(list_installed("venutian_packages"), "venutian_packages")

save_lockfile(path, lockfile)

Writes lockfile to path as pretty-printed JSON, the on-disk form of a project's venutian.lock.json.

save_lockfile("venutian.lock.json", generate_lockfile(["utils"], "venutian_packages"))

load_lockfile(path)

Reads path and decodes it as a lockfile map: the exact inverse of save_lockfile.

load_lockfile("venutian.lock.json")

verify_lockfile(lockfile, packages_dir)

Checks every package named in lockfile against what is actually installed in packages_dir: "not installed" when its destination directory is missing entirely, "content hash does not match lockfile" when it is installed but content_hash_of_directory gives a different hash than what was recorded, and "matches lockfile" otherwise.

verify_lockfile(load_lockfile("venutian.lock.json"), "venutian_packages")

all_verified(results)

Whether every result in results passed verification: true exactly when no result has "ok" set to no.

all_verified(verify_lockfile(load_lockfile("venutian.lock.json"), "venutian_packages"))

format_install_summary(results)

Renders install_alls (or a hand-built equivalent's) result List as plain, human-readable Text, one " + name -> destination" line per entry, or a literal "(nothing to install)" when results is empty.

format_install_summary(install_all(load_manifest("venutian.json"), ".", "venutian_packages"))

format_verify_summary(results)

Renders verify_lockfiles result List as plain, human-readable Text, one "OK name, reason" or "FAIL name, reason" line per entry, or a literal "(nothing to verify)" when results is empty.

format_verify_summary(verify_lockfile(load_lockfile("venutian.lock.json"), "venutian_packages"))