zuzu-js 0.1.0

package/stdlib/modules/std/zuzuzoo.zzm

@@ -0,0 +1,3960 @@
+=encoding utf8
+
+=head1 NAME
+
+std/zuzuzoo - Plan and install Zuzu distributions.
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and
+Electron. It is not supported by zuzu-js in the browser.
+
+=head1 DESCRIPTION
+
+C<std/zuzuzoo> provides the package-management engine used by the
+command-line C<zuzuzoo> tool. It supports installed distribution
+metadata queries, source archive inspection, dependency-aware install
+planning, distribution test execution, file installation, planned
+target-root removal execution, installed metadata writing, standalone
+safe removal planning and execution, installed-file verification,
+latest-version checks, upgrade checks, and canonical pretty JSON
+formatting.
+
+The command-line C<zuzuzoo> wrapper delegates package behaviour to this
+module and handles argument parsing, user prompts, output formatting,
+JSON output selection, and exit-code translation.
+
+=head1 EXPORTS
+
+=head2 Functions
+
+=over
+
+=item C<< compare_versions(left, right) >>
+
+Parameters: C<left> and C<right> are version strings. Returns:
+C<Number>. Compares two versions, returning a negative, zero, or
+positive value.
+
+=item C<< list_installed(options?) >>, C<< query(module_name, options?) >>, C<< query_distribution(distribution_name, options?) >>
+
+Parameters: names identify installed modules or distributions and
+C<options> controls roots and output. Returns: value. Reads installed
+distribution metadata.
+
+=item C<< is_installed(module_name, min_version?, options?) >>, C<< installed_version(module_name, options?) >>
+
+Parameters: C<module_name> identifies a module, C<min_version> is
+optional, and C<options> controls roots. Returns: C<Boolean> or
+C<String>/C<null>. Checks installed module state.
+
+=item C<< pretty_json(value, options?) >>, C<< format_json(value, options?) >>
+
+Parameters: C<value> is JSON-encodable data and C<options> controls
+formatting. Returns: C<String>. Formats canonical JSON output.
+
+=item C<< fetch_source(target, options?) >>, C<< load_distribution(target, options?) >>
+
+Parameters: C<target> identifies a source archive or distribution and
+C<options> controls fetch/load behaviour. Returns: value. Fetches or
+loads distribution metadata.
+
+=item C<< dependency_roots(options?) >>, C<< find_dependency(module_name, min_version?, options?) >>
+
+Parameters: C<options> controls search roots and C<module_name> names a
+dependency. Returns: value. Locates dependency sources.
+
+=item C<< plan_install(targets, options?) >>, C<< plan_remove(targets, options?) >>
+
+Parameters: C<targets> is an array of requested modules or
+distributions. Returns: C<Dict>. Builds an install or removal plan.
+
+=item C<< verify(targets, options?) >>, C<< latest(module_name, options?) >>, C<< can_upgrade(module_name, options?) >>
+
+Parameters: C<targets> or C<module_name> identify installed or remote
+items. Returns: value. Verifies installation state or checks available
+versions.
+
+=item C<< install(targets, options?) >>, C<< remove(targets, options?) >>
+
+Parameters: C<targets> is an array of modules or distributions. Returns:
+C<Dict>. Executes installation or removal.
+
+=item C<< run_distribution_tests(install_action, options?) >>, C<< execute_removal(removal_action, options?) >>
+
+Parameters: action dictionaries come from plans and C<options> controls
+execution. Returns: C<Dict>. Runs tests or executes one removal action.
+
+=item C<< format_install_plan(plan, options?) >>, C<< format_remove_plan(plan, options?) >>
+
+Parameters: C<plan> is a plan dictionary. Returns: C<String>. Formats a
+plan for display.
+
+=back
+
+=head2 Classes
+
+=over
+
+=item C<ZuzuzooLock>
+
+Filesystem lock object.
+
+=over
+
+=item C<< lock.release() >>
+
+Parameters: none. Returns: C<null>. Releases the lock.
+
+=back
+
+=item C<Zuzuzoo>
+
+Stateful package-management helper. Its methods correspond to the
+module-level functions and take the same parameters, without the final
+C<options> argument where object configuration already supplies defaults.
+
+=over
+
+=item C<< zoo.config() >>
+
+Parameters: none. Returns: C<Dict>. Returns the effective configuration.
+
+=item C<< zoo.acquire_lock(operation, options?) >>
+
+Parameters: C<operation> names the operation and C<options> controls
+locking. Returns: C<ZuzuzooLock>. Acquires an operation lock.
+
+=item C<< zoo.find_installed_module(module_name, options?) >>
+
+Parameters: C<module_name> identifies a module and C<options> controls
+roots. Returns: C<Dict> or C<null>. Finds installed metadata for a
+module.
+
+=item C<< zoo.find_installed_distribution(distribution_name, options?) >>
+
+Parameters: C<distribution_name> identifies a distribution and
+C<options> controls roots. Returns: C<Dict> or C<null>. Finds installed
+metadata for a distribution.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/zuzuzoo >> is copyright Toby Inkster.
+
+It is free software; you may redistribute it and/or modify it under
+the terms of either the Artistic License 1.0 or the GNU General Public
+License version 2.
+
+=cut
+
+from std/data/json import JSON;
+from std/archive import Archive;
+from std/digest/sha import sha256_hex;
+from std/io import Path, STDERR, STDOUT;
+from std/net/http import UserAgent;
+from std/proc import Env, Proc, sleep;
+from std/string import contains, ends_with, join, split, starts_with, substr;
+from std/time import Time;
+from test/parser import parse as parse_tap;
+
+
+function _opt ( options, key, fallback := null ) {
+	if ( options instanceof Dict and options.exists(key) ) {
+		return options.get(key);
+	}
+	return fallback;
+}
+
+function _progress ( options, message ) {
+	if ( _opt( options, "progress", false ) ) {
+		STDERR.say( "zuzuzoo: " _ message );
+	}
+	return true;
+}
+
+function _response_success ( response ) {
+	return response.success() if response can "success";
+	return true;
+}
+
+function _response_status_text ( response ) {
+	let status := ( response can "status" ) ? response.status() : "?";
+	let reason := ( response can "reason" ) ? response.reason() : "";
+	return "" _ status _ " " _ reason;
+}
+
+function _archive_url_from_latest ( latest_info ) {
+	let metadata := latest_info{remote_metadata};
+	if (
+		( metadata instanceof Dict or metadata instanceof PairList ) and
+		metadata.exists("archive_url")
+	) {
+		return metadata{archive_url};
+	}
+
+	let remote_url := latest_info{remote_url};
+	if ( ends_with( remote_url, ".json" ) ) {
+		return substr( remote_url, 0, length remote_url - 5 ) _ ".tar.gz";
+	}
+
+	die(
+		"Latest metadata URL does not identify a source archive " _
+		"(remote_url=" _ remote_url _ ")"
+	);
+}
+
+function _push_unique_string ( items, seen, value ) {
+	let key := "" _ value;
+	return false if key eq "";
+	return false if seen.exists(key);
+	seen.add( key, true );
+	items.push(key);
+	return true;
+}
+
+function _copy_options_with ( options, key, value ) {
+	let out := {};
+	if ( options instanceof Dict ) {
+		for ( let existing_key in options.keys() ) {
+			out.set( existing_key, options.get(existing_key) );
+		}
+	}
+	out.set( key, value );
+	return out;
+}
+
+function _is_windows_platform () {
+	if ( "platform" in __system__ ) {
+		let platform := lc( "" _ __system__.get("platform") );
+		return platform eq "windows" or platform eq "mswin32";
+	}
+	return false;
+}
+
+function _join_dir ( String base, String child, Boolean windows ) {
+	let sep := windows ? "\\": "/";
+	return base _ sep _ child;
+}
+
+function _require_text ( obj, String key, String where ) {
+	if ( not( obj instanceof Dict ) or not obj.exists(key) ) {
+		die `Invalid installed metadata ${where}: missing ${key}`;
+	}
+	let value := obj.get(key);
+	if ( not( value instanceof String ) or value eq "" ) {
+		die `Invalid metadata ${where}: ${key} must be a string`;
+	}
+	return value;
+}
+
+function _require_object ( obj, String key, String where ) {
+	if ( not( obj instanceof Dict ) or not obj.exists(key) ) {
+		die `Invalid installed metadata ${where}: missing ${key}`;
+	}
+	let value := obj.get(key);
+	if ( not( value instanceof Dict ) ) {
+		die `Invalid metadata ${where}: ${key} must be an object`;
+	}
+	return value;
+}
+
+function _require_array ( obj, String key, String where ) {
+	if ( not( obj instanceof Dict ) or not obj.exists(key) ) {
+		die `Invalid installed metadata ${where}: missing ${key}`;
+	}
+	let value := obj.get(key);
+	if ( not( value instanceof Array ) ) {
+		die `Invalid metadata ${where}: ${key} must be an array`;
+	}
+	return value;
+}
+
+function _source_require_text ( obj, String key, String where ) {
+	if ( not( obj instanceof Dict ) and not( obj instanceof PairList ) ) {
+		die `Invalid source metadata ${where}: root must be an object`;
+	}
+	if ( not obj.exists(key) ) {
+		die `Invalid source metadata ${where}: missing ${key}`;
+	}
+	let value := obj.get(key);
+	if ( not( value instanceof String ) or value eq "" ) {
+		die `Invalid source metadata ${where}: ${key} must be a string`;
+	}
+	return value;
+}
+
+function _validate_dependency_pair ( key, value, String where ) {
+	if ( not( key instanceof String ) or key eq "" ) {
+		die `Invalid source metadata ${where}: bad dependency name`;
+	}
+	if ( not( value instanceof String ) or value eq "" ) {
+		die `Invalid source metadata ${where}: bad dependency version`;
+	}
+	return true;
+}
+
+function _validate_dependencies ( meta, String where ) {
+	if ( not meta.exists("dependencies") ) {
+		return true;
+	}
+	let deps := meta.get("dependencies");
+	if ( not( deps instanceof Dict ) ) {
+		die `Invalid metadata ${where}: dependencies must be an object`;
+	}
+	for ( let key in deps.keys() ) {
+		if ( not( key instanceof String ) or key eq "" ) {
+			die `Invalid metadata ${where}: bad dependency name`;
+		}
+		let value := deps.get(key);
+		if ( not( value instanceof String ) or value eq "" ) {
+			die `Invalid metadata ${where}: bad dependency version`;
+		}
+	}
+	return true;
+}
+
+function _validate_source_dependencies ( meta, String where ) {
+	if ( not meta.exists("dependencies") ) {
+		return true;
+	}
+	let deps := meta.get("dependencies");
+	if ( deps instanceof Dict ) {
+		for ( let key in deps.keys() ) {
+			_validate_dependency_pair( key, deps.get(key), where );
+		}
+		return true;
+	}
+	if ( deps instanceof PairList ) {
+		let keys := deps.keys();
+		let values := deps.values();
+		let i := 0;
+		while ( i < keys.length() ) {
+			_validate_dependency_pair( keys[i], values[i], where );
+			i++;
+		}
+		return true;
+	}
+	die `Invalid source metadata ${where}: dependencies must be an object`;
+}
+
+function _validate_source_metadata ( meta, String metadata_file ) {
+	if ( not( meta instanceof Dict ) and not( meta instanceof PairList ) ) {
+		die `Invalid source metadata ${metadata_file}: root must be an object`;
+	}
+	if ( meta.exists("installed") ) {
+		die `Invalid source metadata ${metadata_file}: installed is not allowed`;
+	}
+	if ( meta.exists("modules") or meta.exists("scripts") ) {
+		die(
+			`Invalid source metadata ${metadata_file}: top-level ` _
+			"modules/scripts are not allowed"
+		);
+	}
+
+	_source_require_text( meta, "name", metadata_file );
+	_source_require_text( meta, "version", metadata_file );
+	_source_require_text( meta, "author", metadata_file );
+	_source_require_text( meta, "license", metadata_file );
+
+	if ( meta.exists("status") ) {
+		let status := _source_require_text( meta, "status", metadata_file );
+		if ( status ne "stable" and status ne "trial" ) {
+			die `Invalid source metadata ${metadata_file}: bad status ${status}`;
+		}
+	}
+	_validate_source_dependencies( meta, metadata_file );
+
+	if ( meta instanceof Dict ) {
+		meta.set( "metadata_file", metadata_file );
+	}
+	else {
+		meta.add( "metadata_file", metadata_file );
+	}
+	return meta;
+}
+
+function _validate_entry ( entry, String kind, String where ) {
+	if ( not( entry instanceof Dict ) ) {
+		die `Invalid metadata ${where}: bad ${kind} entry`;
+	}
+	_require_text( entry, "source", where );
+	_require_text( entry, "install_as", where );
+	_require_text( entry, "sha256", where );
+	if ( kind eq "script" and entry.exists("wrappers") ) {
+		let wrappers := entry.get("wrappers");
+		if ( not( wrappers instanceof Array ) ) {
+			die `Invalid metadata ${where}: bad script wrappers`;
+		}
+		for ( let wrapper in wrappers ) {
+			if ( not( wrapper instanceof String ) or wrapper eq "" ) {
+				die `Invalid metadata ${where}: bad wrapper`;
+			}
+		}
+	}
+	return true;
+}
+
+function _validate_installed_metadata ( meta, String metadata_file ) {
+	if ( not( meta instanceof Dict ) ) {
+		die `Invalid metadata ${metadata_file}: root must be an object`;
+	}
+	if ( meta.exists("modules") or meta.exists("scripts") ) {
+		die(
+			`Invalid metadata ${metadata_file}: top-level ` _
+			"modules/scripts are not allowed"
+		);
+	}
+
+	_require_text( meta, "name", metadata_file );
+	_require_text( meta, "version", metadata_file );
+	_require_text( meta, "author", metadata_file );
+	_require_text( meta, "license", metadata_file );
+	let status := _require_text( meta, "status", metadata_file );
+	if ( status ne "stable" and status ne "trial" ) {
+		die `Invalid metadata ${metadata_file}: bad status ${status}`;
+	}
+	_validate_dependencies( meta, metadata_file );
+
+	let installed := _require_object( meta, "installed", metadata_file );
+	let zdf := _require_text( installed, "zdf", metadata_file );
+	if ( zdf ne "ZDF-1" ) {
+		die `Invalid metadata ${metadata_file}: bad installed.zdf`;
+	}
+	_require_text( installed, "lib_dir", metadata_file );
+	_require_text( installed, "bin_dir", metadata_file );
+	_require_text( installed, "meta_dir", metadata_file );
+
+	let modules := _require_array( installed, "modules", metadata_file );
+	let scripts := _require_array( installed, "scripts", metadata_file );
+	if ( modules.length() + scripts.length() = 0 ) {
+		die `Invalid metadata ${metadata_file}: no installed files`;
+	}
+
+	for ( let module in modules ) {
+		_validate_entry( module, "module", metadata_file );
+	}
+	for ( let script in scripts ) {
+		_validate_entry( script, "script", metadata_file );
+	}
+
+	meta.set( "metadata_file", metadata_file );
+	return meta;
+}
+
+function _parse_version ( version ) {
+	let text := "" _ version;
+	let nums := [];
+	let i := 0;
+	let n := length text;
+
+	while ( i < n and substr( text, i, 1 ) ~ /^[0-9]$/ ) {
+		let start := i;
+		while ( i < n and substr( text, i, 1 ) ~ /^[0-9]$/ ) {
+			i++;
+		}
+		nums.push( int( substr( text, start, i - start ) ) );
+
+		if (
+			i < n - 1 and
+			substr( text, i, 1 ) eq "." and
+			substr( text, i + 1, 1 ) ~ /^[0-9]$/
+		) {
+			i++;
+			next;
+		}
+		last;
+	}
+
+	return {
+		nums: nums,
+		suffix: substr( text, i ),
+	};
+}
+
+function compare_versions ( left, right ) {
+	let a := _parse_version(left);
+	let b := _parse_version(right);
+	let max := a{nums}.length() > b{nums}.length()
+		? a{nums}.length()
+		: b{nums}.length();
+
+	let i := 0;
+	while ( i < max ) {
+		let av := i < a{nums}.length() ? a{nums}[i]: 0;
+		let bv := i < b{nums}.length() ? b{nums}[i]: 0;
+		return av <=> bv if av != bv;
+		i++;
+	}
+
+	if ( a{suffix} eq "" and b{suffix} ne "" ) {
+		return 1;
+	}
+	if ( a{suffix} ne "" and b{suffix} eq "" ) {
+		return -1;
+	}
+	return a{suffix} cmp b{suffix};
+}
+
+function _module_key ( module_name ) {
+	let text := "" _ module_name;
+	if ( ends_with( text, ".zzm" ) ) {
+		return substr( text, 0, length text - 4 );
+	}
+	return text;
+}
+
+function _is_url ( String target ) {
+	return (
+		starts_with( target, "http://" ) or
+		starts_with( target, "https://" )
+	);
+}
+
+function _trim_right_slash ( String text ) {
+	let out := text;
+	while ( length out > 0 and substr( out, length out - 1, 1 ) eq "/" ) {
+		out := substr( out, 0, length out - 1 );
+	}
+	return out;
+}
+
+function _safe_archive_root ( archive, String where ) {
+	if ( not( archive instanceof Dict ) or not( archive.get("entries") instanceof Array ) ) {
+		die `Invalid archive ${where}: entries must be an array`;
+	}
+
+	let seen := {};
+	let root := null;
+	for ( let entry in archive{entries} ) {
+		if ( not( entry instanceof Dict ) or not( entry.get("path") instanceof String ) ) {
+			die `Invalid archive ${where}: bad entry path`;
+		}
+		let path := entry{path};
+		if ( path eq "" ) {
+			die `Invalid archive ${where}: empty path`;
+		}
+		if ( starts_with( path, "/" ) or contains( path, "\\" ) ) {
+			die `Invalid archive ${where}: unsafe path ${path}`;
+		}
+		if ( seen.exists(path) ) {
+			die `Invalid archive ${where}: duplicate path ${path}`;
+		}
+		seen.add( path, true );
+
+		let parts := split( path, "/" );
+		if ( parts.length() == 0 or parts[0] eq "" ) {
+			die `Invalid archive ${where}: empty path component`;
+		}
+		for ( let part in parts ) {
+			if ( part eq "" or part eq "." or part eq ".." ) {
+				die `Invalid archive ${where}: unsafe path ${path}`;
+			}
+		}
+		if ( root instanceof Null ) {
+			root := parts[0];
+		}
+		else if ( root ne parts[0] ) {
+			die `Invalid archive ${where}: multiple top-level roots`;
+		}
+	}
+
+	die `Invalid archive ${where}: no entries` if root instanceof Null;
+	return root;
+}
+
+function _ensure_dir ( path ) {
+	return true if path.exists();
+	let parent := path.parent();
+	_ensure_dir(parent) if not parent.exists();
+	path.mkdir();
+	return true;
+}
+
+function _mkdir_parent ( path ) {
+	_ensure_dir( path.parent() );
+	return true;
+}
+
+function _extract_archive ( archive, String root_name, root_dir ) {
+	for ( let entry in archive{entries} ) {
+		let parts := split( entry{path}, "/" );
+		let out := root_dir;
+		let i := 1;
+		while ( i < parts.length() ) {
+			out := out.child(parts[i]);
+			i++;
+		}
+		_mkdir_parent(out);
+		out.spew(entry{data});
+	}
+	return true;
+}
+
+function _relative_path ( root, path ) {
+	let prefix := root.to_String() _ "/";
+	let text := path.to_String();
+	if ( starts_with( text, prefix ) ) {
+		return substr( text, length prefix );
+	}
+	return path.basename();
+}
+
+function _discover_files ( root, dir_name, extension ) {
+	let base := root.child(dir_name);
+	return [] if not base.exists();
+	return [] if not base.is_dir();
+
+	let found := [];
+	function walk ( path ) {
+		for ( let child in path.children() ) {
+			if ( child.is_dir() ) {
+				walk(child);
+			}
+			else if ( child.is_file() and ends_with( child.basename(), extension ) ) {
+				found.push( _relative_path( root, child ) );
+			}
+		}
+	}
+	walk(base);
+	return found.sort( fn ( a, b ) -> a cmp b );
+}
+
+function _has_extension ( String basename ) {
+	return contains( basename, "." );
+}
+
+function _has_zuzu_shebang ( path ) {
+	let text := "";
+	try {
+		text := path.slurp_utf8();
+	}
+	catch {
+		return false;
+	}
+
+	let lines := split( text, "\n" );
+	let first_line := lines.length() == 0 ? "" : lines[0];
+	return starts_with( first_line, "#!" ) and contains( first_line, "zuzu" );
+}
+
+function _discover_scripts ( root ) {
+	let base := root.child("scripts");
+	return [] if not base.exists();
+	return [] if not base.is_dir();
+
+	let found := [];
+	function walk ( path ) {
+		for ( let child in path.children() ) {
+			if ( child.is_dir() ) {
+				walk(child);
+			}
+			else if ( child.is_file() ) {
+				let basename := child.basename();
+				if (
+					ends_with( basename, ".zzs" ) or
+					(
+						not _has_extension(basename) and
+						_has_zuzu_shebang(child)
+					)
+				) {
+					found.push( _relative_path( root, child ) );
+				}
+			}
+		}
+	}
+	walk(base);
+	return found.sort( fn ( a, b ) -> a cmp b );
+}
+
+function _module_install_name ( String source ) {
+	return substr( source, length "modules/" );
+}
+
+function _script_install_name ( String source ) {
+	return substr( source, length "scripts/" );
+}
+
+function _target_list ( targets ) {
+	return targets instanceof Array ? targets : [ targets ];
+}
+
+function _root_key ( root ) {
+	return (
+		root{lib_dir} _ "\n" _
+		root{bin_dir} _ "\n" _
+		root{meta_dir}
+	);
+}
+
+function _root_from_config ( String name, String kind, cfg ) {
+	return {
+		name: name,
+		kind: kind,
+		lib_dir: cfg{lib_dir},
+		bin_dir: cfg{bin_dir},
+		meta_dir: cfg{meta_dir},
+		global: cfg{global},
+		windows: cfg{windows},
+	};
+}
+
+function _require_root_text ( root, String key, String where ) {
+	if ( not( root instanceof Dict ) or not root.exists(key) ) {
+		die `Invalid dependency root ${where}: missing ${key}`;
+	}
+	let value := root.get(key);
+	if ( not( value instanceof String ) or value eq "" ) {
+		die `Invalid dependency root ${where}: ${key} must be a string`;
+	}
+	return value;
+}
+
+function _custom_root ( root, String where ) {
+	return {
+		name: _require_root_text( root, "name", where ),
+		kind: "custom",
+		lib_dir: _require_root_text( root, "lib_dir", where ),
+		bin_dir: _require_root_text( root, "bin_dir", where ),
+		meta_dir: _require_root_text( root, "meta_dir", where ),
+		global: root.exists("global") ? root{global} : false,
+		windows: root.exists("windows") ? root{windows} : false,
+	};
+}
+
+function _root_override ( root, String name, String kind, String where ) {
+	return {
+		name: name,
+		kind: kind,
+		lib_dir: _require_root_text( root, "lib_dir", where ),
+		bin_dir: _require_root_text( root, "bin_dir", where ),
+		meta_dir: _require_root_text( root, "meta_dir", where ),
+		global: root.exists("global") ? root{global} : false,
+		windows: root.exists("windows") ? root{windows} : false,
+	};
+}
+
+function _add_root ( roots, seen, root ) {
+	let key := _root_key(root);
+	return false if seen.exists(key);
+	seen.add( key, true );
+	roots.push(root);
+	return true;
+}
+
+function _path_join ( String base, String child, Boolean windows ) {
+	let sep := windows ? "\\": "/";
+	return base _ sep _ child;
+}
+
+function _path_child ( String base, String relative ) {
+	let out := new Path(base);
+	for ( let part in split( relative, "/" ) ) {
+		out := out.child(part) if part ne "";
+	}
+	return out;
+}
+
+function _relative_basename ( String relative ) {
+	let parts := split( relative, "/" );
+	return parts[ parts.length() - 1 ];
+}
+
+function _replace_script_suffix ( String relative, String suffix ) {
+	if ( ends_with( relative, ".zzs" ) ) {
+		return substr( relative, 0, length relative - 4 ) _ suffix;
+	}
+	return relative _ suffix;
+}
+
+function _installed_at () {
+	return ( new Time() ).strftime("%Y-%m-%dT%H:%M:%SZ");
+}
+
+function _now_epoch () {
+	return ( new Time() ).epoch();
+}
+
+function _temp_parent ( options? ) {
+	let temp_root := _opt( options, "temp_root", null );
+	if ( temp_root instanceof Null ) {
+		return null;
+	}
+	let root := new Path(temp_root);
+	_ensure_dir(root);
+	return root;
+}
+
+function _unique_temp_path ( parent, String prefix, String suffix ) {
+	let base := prefix _ Proc.pid() _ "-" _ _now_epoch();
+	let i := 0;
+	while ( true ) {
+		let candidate := parent.child( base _ "-" _ i _ suffix );
+		return candidate if not candidate.exists();
+		i++;
+	}
+}
+
+function _new_temp_dir ( options?, String prefix := "zuzuzoo-" ) {
+	let parent := _temp_parent(options);
+	if ( parent instanceof Null ) {
+		return Path.tempdir();
+	}
+
+	let i := 0;
+	while ( true ) {
+		let candidate := _unique_temp_path(
+			parent,
+			prefix,
+			".d",
+		);
+		if ( candidate.mkdir_exclusive() ) {
+			return candidate;
+		}
+		i++;
+		die `Could not allocate temporary directory in ${parent}`
+			if i > 1000;
+	}
+}
+
+function _cleanup_path ( path ) {
+	return false if path instanceof Null;
+	try {
+		if ( path.exists() ) {
+			if ( path.is_dir() ) {
+				path.remove_tree();
+			}
+			else {
+				path.remove();
+			}
+			return true;
+		}
+	}
+	catch ( Exception e ) {
+		return false;
+	}
+	return false;
+}
+
+function _cleanup_source ( source, options? ) {
+	return false if source instanceof Null;
+	return false if _opt( options, "keep_work_dirs", false );
+	if ( source.exists("temp_dir") ) {
+		return _cleanup_path(source{temp_dir});
+	}
+	return false;
+}
+
+function _cleanup_install_action ( install_action, options? ) {
+	return false if _opt( options, "keep_work_dirs", false );
+	_cleanup_source( install_action{source}, options )
+		if install_action.exists("source");
+	_cleanup_path( install_action{work_dir_obj} )
+		if install_action.exists("work_dir_obj");
+	return true;
+}
+
+function _cleanup_plan_work_dirs ( plan, options? ) {
+	return false if plan instanceof Null;
+	return false if _opt( options, "keep_work_dirs", false );
+	for ( let install_action in plan.get( "installs", [] ) ) {
+		_cleanup_install_action( install_action, options );
+	}
+	return true;
+}
+
+function _cleanup_loaded_work_dirs ( loaded, options? ) {
+	return false if _opt( options, "keep_work_dirs", false );
+	for ( let item in loaded ) {
+		_cleanup_install_action( item, options );
+	}
+	return true;
+}
+
+function _atomic_temp_sibling ( path, String suffix := ".tmp" ) {
+	return _unique_temp_path(
+		path.parent(),
+		"." _ path.basename() _ ".",
+		suffix,
+	);
+}
+
+function _atomic_json_write ( path, value ) {
+	_mkdir_parent(path);
+	let temp := _atomic_temp_sibling(path);
+	let codec := new JSON( pretty: true, canonical: true );
+	try {
+		codec.dump( temp, value );
+		codec.load(temp);
+		temp.move(path);
+	}
+	catch ( Exception e ) {
+		_cleanup_path(temp);
+		throw e;
+	}
+	return path;
+}
+
+function _copy_file_atomic ( source, destination, chmod_mode? ) {
+	_mkdir_parent(destination);
+	let temp := _atomic_temp_sibling(destination);
+	try {
+		source.copy(temp);
+		let temp_sha := sha256_hex(temp.slurp());
+		temp.chmod(chmod_mode) if not( chmod_mode instanceof Null );
+		temp.move(destination);
+		let final_bytes := destination.slurp();
+		let final_sha := sha256_hex(final_bytes);
+		if ( final_sha ne temp_sha ) {
+			die(
+				`Atomic install verification failed for ${destination}: ` _
+				`expected ${temp_sha}, got ${final_sha}`
+			);
+		}
+		return {
+			sha256: final_sha,
+			size: destination.size(),
+		};
+	}
+	catch ( Exception e ) {
+		_cleanup_path(temp);
+		throw e;
+	}
+}
+
+function _spew_utf8_atomic ( destination, String text ) {
+	_mkdir_parent(destination);
+	let temp := _atomic_temp_sibling(destination);
+	try {
+		temp.spew_utf8(text);
+		temp.move(destination);
+	}
+	catch ( Exception e ) {
+		_cleanup_path(temp);
+		throw e;
+	}
+	return destination;
+}
+
+function _source_context ( source ) {
+	let parts := [
+		"target=" _ source{value},
+		"source_type=" _ source{type},
+	];
+	parts.push( "url=" _ source{url} ) if source.exists("url");
+	parts.push( "resolved_url=" _ source{resolved_url} )
+		if source.exists("resolved_url");
+	parts.push( "path=" _ source{path} ) if source.exists("path");
+	return join( ", ", parts );
+}
+
+function _corrupt_archive_error ( source, underlying ) {
+	return (
+		"Corrupt source archive (" _ _source_context(source) _
+		"): " _ underlying.to_String()
+	);
+}
+
+function _cache_key ( String url ) {
+	return sha256_hex(to_binary(url));
+}
+
+function _cache_paths ( String cache_dir, String url ) {
+	let dir := new Path(cache_dir);
+	_ensure_dir(dir);
+	let key := _cache_key(url);
+	return {
+		dir: dir,
+		key: key,
+		archive: dir.child(key _ ".archive"),
+		sidecar: dir.child(key _ ".json"),
+	};
+}
+
+function _delete_cache_entry ( paths ) {
+	_cleanup_path(paths{archive});
+	_cleanup_path(paths{sidecar});
+	return true;
+}
+
+function _validate_cache_entry ( paths ) {
+	return false if not paths{archive}.exists();
+	return false if not paths{sidecar}.exists();
+
+	let sidecar := null;
+	try {
+		sidecar := ( new JSON() ).load(paths{sidecar});
+	}
+	catch ( Exception e ) {
+		return false;
+	}
+
+	let bytes := paths{archive}.slurp();
+	let actual_sha := sha256_hex(bytes);
+	if ( sidecar.get( "archive_sha256", "" ) ne actual_sha ) {
+		return false;
+	}
+	if ( sidecar.get( "byte_size", -1 ) != paths{archive}.size() ) {
+		return false;
+	}
+	try {
+		Archive.decode(bytes);
+	}
+	catch ( Exception e ) {
+		return false;
+	}
+	return sidecar;
+}
+
+function _write_cache_entry ( paths, source, temp_path ) {
+	let bytes := temp_path.slurp();
+	let sidecar := {
+		original_url: source{url},
+		resolved_url: source{resolved_url},
+		downloaded_at: _installed_at(),
+		archive_sha256: sha256_hex(bytes),
+		byte_size: temp_path.size(),
+	};
+	Archive.decode(bytes);
+	let archive_temp := _atomic_temp_sibling(paths{archive});
+	let sidecar_temp := _atomic_temp_sibling(paths{sidecar});
+	try {
+		temp_path.copy(archive_temp);
+		archive_temp.move(paths{archive});
+		( new JSON( pretty: true, canonical: true ) ).dump(
+			sidecar_temp,
+			sidecar,
+		);
+		( new JSON() ).load(sidecar_temp);
+		sidecar_temp.move(paths{sidecar});
+	}
+	catch ( Exception e ) {
+		_cleanup_path(archive_temp);
+		_cleanup_path(sidecar_temp);
+		_delete_cache_entry(paths);
+		throw e;
+	}
+	return sidecar;
+}
+
+function _check_expected_source_sha ( source, expected_sha256 ) {
+	return true if expected_sha256 instanceof Null;
+	let actual := sha256_hex( ( new Path(source{path}) ).slurp() );
+	if ( actual ne expected_sha256 ) {
+		die(
+			"Source checksum mismatch (" _ _source_context(source) _
+			`): expected ${expected_sha256}, got ${actual}`
+		);
+	}
+	return true;
+}
+
+function _dependency_chain ( stack, dependency_of, module_name ) {
+	let chain := [];
+	for ( let item in stack ) {
+		chain.push(item);
+	}
+	if ( not( dependency_of instanceof Null ) ) {
+		chain.push(dependency_of{metadata}{name});
+	}
+	chain.push(module_name);
+	return join( " -> ", chain );
+}
+
+function _dependency_conflict_message (
+	dep,
+	dependency_of,
+	stack,
+	planned_action,
+	conflicting_dist
+) {
+	let requested_by := dependency_of instanceof Null
+		? "<requested target>"
+		: dependency_of{metadata}{name};
+	let planned_text := planned_action instanceof Null
+		? "none"
+		: planned_action{metadata}{name} _ " " _
+			planned_action{metadata}{version};
+	let conflicting_text := conflicting_dist{metadata}{name} _ " " _
+		conflicting_dist{metadata}{version};
+	return (
+		"Dependency conflict: requested dependency " _
+		dep{module_name} _ " >= " _ dep{min_version} _
+		"; requester chain " _
+		_dependency_chain(
+			stack,
+			dependency_of,
+			dep{module_name},
+		) _
+		"; requested by " _ requested_by _
+		"; planned/provided version " _ planned_text _
+		"; conflicting planned/provided version " _
+		conflicting_text
+	);
+}
+
+function _planned_version_conflict_message (
+	String dist_name,
+	existing,
+	dist,
+	String target_text
+) {
+	return (
+		`Conflicting planned versions for ${dist_name}: ` _
+		existing{metadata}{version} _ " and " _
+		dist{metadata}{version} _
+		"; existing target " _ existing{target} _
+		"; conflicting target " _ target_text _
+		"; existing metadata " _
+		existing{metadata}{metadata_file} _
+		"; conflicting metadata " _
+		dist{metadata}{metadata_file}
+	);
+}
+
+function _copy_dependencies ( metadata ) {
+	let out := {};
+	return out if not metadata.exists("dependencies");
+	let deps := metadata{dependencies};
+	if ( deps instanceof PairList ) {
+		let keys := deps.keys();
+		let values := deps.values();
+		let i := 0;
+		while ( i < keys.length() ) {
+			out.set( keys[i], values[i] );
+			i++;
+		}
+		return out;
+	}
+	for ( let key in deps.keys() ) {
+		out.set( key, deps.get(key) );
+	}
+	return out;
+}
+
+function _copy_source_record ( source ) {
+	let out := {
+		type: source{type},
+		value: source{value},
+	};
+	out{url} := source{url} if source.exists("url");
+	out{resolved_url} := source{resolved_url}
+		if source.exists("resolved_url");
+	out{path} := source{path} if source.exists("path");
+	return out;
+}
+
+function _copy_source_metadata ( metadata ) {
+	let out := {};
+	for ( let key in metadata.keys() ) {
+		next if key eq "metadata_file";
+		if ( key eq "dependencies" ) {
+			out.set( key, _copy_dependencies(metadata) );
+		}
+		else {
+			out.set( key, metadata.get(key) );
+		}
+	}
+	out.set( "status", "stable" ) if not out.exists("status");
+	out.set( "dependencies", {} ) if not out.exists("dependencies");
+	return out;
+}
+
+function _test_ok ( parsed, run_result ) {
+	return false if not Proc.is_success(run_result);
+	return false if parsed{planned} instanceof Null;
+	return false if parsed{assertions}{failed} > 0;
+	return true;
+}
+
+function _dependency_entries ( metadata ) {
+	let out := [];
+	return out if not metadata.exists("dependencies");
+
+	let deps := metadata{dependencies};
+	if ( deps instanceof PairList ) {
+		let keys := deps.keys();
+		let values := deps.values();
+		let i := 0;
+		while ( i < keys.length() ) {
+			out.push(
+				{
+					module_name: keys[i],
+					min_version: values[i],
+				},
+			);
+			i++;
+		}
+		return out;
+	}
+
+	let keys := deps.keys();
+	for ( let key in keys ) {
+		out.push(
+			{
+				module_name: key,
+				min_version: deps.get(key),
+			},
+		);
+	}
+	return out;
+}
+
+function _version_satisfies ( version, min_version ) {
+	return true if min_version instanceof Null;
+	return true if "" _ min_version eq "0";
+	return compare_versions( version, min_version ) >= 0;
+}
+
+function _provides_module ( dist, module_name, min_version ) {
+	return false if not _version_satisfies( dist{version}, min_version );
+	let wanted := _module_key(module_name);
+	for ( let module in dist{installed}{modules} ) {
+		return true if _module_key( module{install_as} ) eq wanted;
+	}
+	return false;
+}
+
+function _planned_provides_module ( install_action, module_name, min_version ) {
+	return false if not _version_satisfies(
+		install_action{metadata}{version},
+		min_version,
+	);
+	let wanted := _module_key(module_name);
+	for ( let module in install_action{modules} ) {
+		return true if _module_key( module{install_as} ) eq wanted;
+	}
+	return false;
+}
+
+function _loaded_distribution_provides ( dist, module_name, min_version ) {
+	return false if not _version_satisfies(
+		dist{metadata}{version},
+		min_version,
+	);
+	let wanted := _module_key(module_name);
+	for ( let module in dist{modules} ) {
+		return true if _module_key( module{install_as} ) eq wanted;
+	}
+	return false;
+}
+
+function _metadata_files_in_dir ( String meta_dir ) {
+	let dir := new Path(meta_dir);
+	return [] if not dir.exists();
+	die `Metadata path is not a directory: ${dir}`
+		if not dir.is_dir();
+
+	let files := [];
+	for ( let child in dir.children() ) {
+		if (
+			child.is_file() and
+			ends_with( child.basename(), ".json" )
+		) {
+			files.push(child);
+		}
+	}
+	return files.sort(
+		fn ( a, b ) -> a.to_String() cmp b.to_String()
+	);
+}
+
+function _list_installed_in_root ( root ) {
+	let codec := new JSON();
+	let installed := [];
+	for ( let file in _metadata_files_in_dir( root{meta_dir} ) ) {
+		let data := codec.load(file);
+		let valid := _validate_installed_metadata(
+			data,
+			file.to_String(),
+		);
+		installed.push(valid);
+	}
+
+	return installed.sort( function ( a, b ) {
+		let name_cmp := a{name} cmp b{name};
+		return name_cmp if name_cmp != 0;
+		return compare_versions( b{version}, a{version} );
+	} );
+}
+
+function _candidate_record (
+	String source,
+	module_name,
+	min_version,
+	version,
+	distribution,
+	root,
+	metadata_file,
+	install_action
+) {
+	let record := {
+		module_name: "" _ module_name,
+		min_version: min_version instanceof Null ? null : "" _ min_version,
+		version: "" _ version,
+		source: source,
+		distribution: distribution,
+		metadata_file: metadata_file,
+	};
+	record{root} := root if not( root instanceof Null );
+	record{install} := install_action if not( install_action instanceof Null );
+	return record;
+}
+
+function _better_dependency_candidate ( current, candidate, root_order ) {
+	return true if current instanceof Null;
+
+	let version_cmp := compare_versions(
+		candidate{version},
+		current{version},
+	);
+	return true if version_cmp > 0;
+	return false if version_cmp < 0;
+
+	let current_order := root_order.exists(current{root}{name})
+		? root_order.get(current{root}{name})
+		: 1000000;
+	let candidate_order := root_order.exists(candidate{root}{name})
+		? root_order.get(candidate{root}{name})
+		: 1000000;
+	return true if candidate_order < current_order;
+	return false if candidate_order > current_order;
+
+	return candidate{metadata_file} lt current{metadata_file};
+}
+
+function _find_dependency_in_roots ( roots, module_name, min_version ) {
+	let root_order := {};
+	let i := 0;
+	while ( i < roots.length() ) {
+		root_order.add( roots[i]{name}, i );
+		i++;
+	}
+
+	let best := null;
+	for ( let root in roots ) {
+		for ( let dist in _list_installed_in_root(root) ) {
+			if ( _provides_module( dist, module_name, min_version ) ) {
+				let candidate := _candidate_record(
+					"root",
+					module_name,
+					min_version,
+					dist{version},
+					dist{name},
+					root,
+					dist{metadata_file},
+					null,
+				);
+				candidate{installed} := dist;
+				if (
+					_better_dependency_candidate(
+						best,
+						candidate,
+						root_order,
+					)
+				) {
+					best := candidate;
+				}
+			}
+		}
+	}
+	return best;
+}
+
+function _find_dependency_in_planned ( planned, module_name, min_version ) {
+	let best := null;
+	for ( let install_action in planned ) {
+		if ( _planned_provides_module( install_action, module_name, min_version ) ) {
+			let candidate := _candidate_record(
+				"planned",
+				module_name,
+				min_version,
+				install_action{metadata}{version},
+				install_action{metadata}{name},
+				install_action{target_root},
+				install_action{metadata}{metadata_file},
+				install_action,
+			);
+			if (
+					best instanceof Null or
+				compare_versions(
+					candidate{version},
+					best{version},
+				) > 0 or
+				(
+					compare_versions(
+						candidate{version},
+						best{version},
+					) == 0 and
+					candidate{metadata_file} lt best{metadata_file}
+				)
+			) {
+				best := candidate;
+			}
+		}
+	}
+	return best;
+}
+
+function _runtime_module_path ( module_name ) {
+	return null if not starts_with( "" _ module_name, "std/" );
+
+	let inc := [];
+	if ( "inc" in __system__ ) {
+		inc := __system__.get("inc");
+	}
+	return null if inc ≡ null;
+	if ( not( inc instanceof Array ) ) {
+		let separator := _is_windows_platform() ? ";" : ":";
+		inc := split( "" _ inc, separator );
+	}
+
+	let relative := module_name _ ".zzm";
+	for ( let root in inc ) {
+		next if root eq "";
+		let path := ( new Path(root) ).child(relative);
+		return path if path.exists() and path.is_file();
+	}
+	return null;
+}
+
+function _runtime_include_dirs () {
+	let out := [];
+	let seen := {};
+	let inc := [];
+	if ( "inc" in __system__ ) {
+		inc := __system__.get("inc");
+	}
+	return out if inc ≡ null;
+	if ( not( inc instanceof Array ) ) {
+		let separator := _is_windows_platform() ? ";" : ":";
+		inc := split( "" _ inc, separator );
+	}
+
+	for ( let root in inc ) {
+		next if root eq "";
+		let path := ( new Path(root) ).absolute();
+		_push_unique_string( out, seen, path.to_String() )
+			if path.exists() and path.is_dir();
+	}
+	return out;
+}
+
+function _find_dependency_in_runtime ( module_name, min_version ) {
+	return null if not _version_satisfies( "0", min_version );
+
+	let module_path := _runtime_module_path(module_name);
+	return null if module_path instanceof Null;
+
+	let root := {
+		name: "runtime",
+		lib_dir: "",
+		bin_dir: "",
+		meta_dir: "",
+	};
+	let candidate := _candidate_record(
+		"runtime",
+		module_name,
+		min_version,
+		"0",
+		"zuzu-runtime",
+		root,
+		module_path.to_String(),
+		null,
+	);
+	candidate{module_file} := module_path.to_String();
+	return candidate;
+}
+
+function _find_dependency_for_plan (
+	planned,
+	roots,
+	module_name,
+	min_version
+) {
+	let found := _find_dependency_in_planned(
+		planned,
+		module_name,
+		min_version,
+	);
+	return found if not( found instanceof Null );
+	found := _find_dependency_in_roots( roots, module_name, min_version );
+	return found if not( found instanceof Null );
+	return _find_dependency_in_runtime( module_name, min_version );
+}
+
+function _cycle_path ( stack, module_name ) {
+	let path := [];
+	let started := false;
+	for ( let item in stack ) {
+		started := true if item eq module_name;
+		path.push(item) if started;
+	}
+	path.push(module_name);
+	return join( " -> ", path );
+}
+
+function _stack_contains ( stack, value ) {
+	for ( let item in stack ) {
+		return true if item eq value;
+	}
+	return false;
+}
+
+function _remove_file_kind_order ( String kind ) {
+	return kind eq "metadata" ? 1 : 0;
+}
+
+function _remove_file_cmp ( a, b ) {
+	let kind_cmp := _remove_file_kind_order(a{kind}) <=>
+		_remove_file_kind_order(b{kind});
+	return kind_cmp if kind_cmp != 0;
+	let path_cmp := a{path} cmp b{path};
+	return path_cmp if path_cmp != 0;
+	return a{kind} cmp b{kind};
+}
+
+function _removal_cmp ( a, b ) {
+	let name_cmp := a{name} cmp b{name};
+	return name_cmp if name_cmp != 0;
+	let version_cmp := compare_versions( b{version}, a{version} );
+	return version_cmp if version_cmp != 0;
+	return a{metadata_file} cmp b{metadata_file};
+}
+
+function _owner_record ( dist ) {
+	return {
+		name: dist{name},
+		version: dist{version},
+		metadata_file: dist{metadata_file},
+	};
+}
+
+function _same_owner ( left, right ) {
+	return left{metadata_file} eq right{metadata_file};
+}
+
+function _owner_list_contains ( owners, owner ) {
+	for ( let item in owners ) {
+		return true if _same_owner( item, owner );
+	}
+	return false;
+}
+
+function _add_owner_to_list ( owners, owner ) {
+	return false if _owner_list_contains( owners, owner );
+	owners.push(owner);
+	return true;
+}
+
+function _add_owner_for_path ( by_path, String path, owner ) {
+	if ( not by_path.exists(path) ) {
+		by_path.add( path, [] );
+	}
+	_add_owner_to_list( by_path.get(path), owner );
+	return true;
+}
+
+function _remove_target_record ( target, options? ) {
+	if ( target instanceof Dict ) {
+		let type := target.exists("type") ? "" _ target{type} : "";
+		let value := target.exists("value") ? "" _ target{value} : "";
+		return {
+			type: type,
+			value: value,
+			raw: target,
+		};
+	}
+	return {
+		type: _opt( options, "dist", false ) ? "distribution" : "module",
+		value: "" _ target,
+		raw: target,
+	};
+}
+
+function _latest_module_name ( module_name ) {
+	if ( not( module_name instanceof String ) ) {
+		die "latest target must be a module name";
+	}
+	if ( module_name eq "" or _is_url(module_name) ) {
+		die "latest target must be a module name";
+	}
+	let path := new Path(module_name);
+	if ( path.exists() ) {
+		die "latest target must be a module name";
+	}
+	return module_name;
+}
+
+function _latest_status ( installed_version, remote_version ) {
+	return "not-installed" if installed_version instanceof Null;
+	let comparison := compare_versions( installed_version, remote_version );
+	return "current" if comparison == 0;
+	return comparison < 0 ? "outdated" : "newer-local";
+}
+
+function _add_verify_target_error ( result, code, target, message ) {
+	result{errors}.push(
+		{
+			code: code,
+			target: target,
+			message: message,
+		},
+	);
+	return true;
+}
+
+class ZuzuzooLock {
+	let lock_path := null;
+	let owner_file := null;
+	let acquired := false;
+
+	method release () {
+		return false if not acquired;
+		_cleanup_path(owner_file);
+		_cleanup_path(lock_path);
+		acquired := false;
+		return true;
+	}
+}
+
+class Zuzuzoo {
+	let lib_dir := null;
+	let bin_dir := null;
+	let meta_dir := null;
+	let global := false;
+	let windows := null;
+	let home := null;
+	let userprofile := null;
+	let base_url := "https://zuzulang.org";
+	let user_agent := null;
+	let zuzu_command := "zuzu";
+	let dependency_roots := [];
+	let global_root := null;
+
+	method _user_agent () {
+		return not( user_agent instanceof Null ) ? user_agent : new UserAgent();
+	}
+
+	method config () {
+		let resolved_windows := windows instanceof Null
+			? _is_windows_platform()
+			: windows;
+		let resolved_global := global ? true: false;
+
+		if ( resolved_windows and resolved_global ) {
+			die "Global Windows installs are not supported";
+		}
+
+		let base_home := not( home instanceof Null ) ? home : Env.get( "HOME", "" );
+		let base_userprofile := not( userprofile instanceof Null )
+			? userprofile
+			: Env.get( "USERPROFILE", "" );
+
+		let resolved_lib := lib_dir;
+		let resolved_bin := bin_dir;
+		let resolved_meta := meta_dir;
+		let needs_default := (
+			resolved_lib instanceof Null or
+			resolved_bin instanceof Null or
+			resolved_meta instanceof Null
+		);
+
+		if ( resolved_windows ) {
+			if ( needs_default ) {
+				die "USERPROFILE required for Windows install"
+					if base_userprofile eq "";
+				let root := _join_dir(
+					base_userprofile,
+					".zuzu",
+					true,
+				);
+				resolved_lib := _join_dir(
+					root,
+					"modules",
+					true,
+				)
+					if resolved_lib instanceof Null;
+				resolved_bin := _join_dir( root, "bin", true )
+					if resolved_bin instanceof Null;
+				resolved_meta := _join_dir( root, "meta", true )
+					if resolved_meta instanceof Null;
+			}
+		}
+		else if ( resolved_global ) {
+			resolved_lib := "/var/lib/zuzu/modules"
+				if resolved_lib instanceof Null;
+			resolved_bin := "/usr/local/bin"
+				if resolved_bin instanceof Null;
+			resolved_meta := "/var/lib/zuzu/meta"
+				if resolved_meta instanceof Null;
+		}
+		else {
+			if ( needs_default ) {
+				die "HOME required for POSIX user install"
+					if base_home eq "";
+				let root := _join_dir(
+					base_home,
+					".zuzu",
+					false,
+				);
+				resolved_lib := _join_dir(
+					root,
+					"modules",
+					false,
+				)
+					if resolved_lib instanceof Null;
+				resolved_bin := _join_dir( root, "bin", false )
+					if resolved_bin instanceof Null;
+				resolved_meta := _join_dir(
+					root,
+					"meta",
+					false,
+				)
+					if resolved_meta instanceof Null;
+			}
+		}
+
+		return {
+			lib_dir: resolved_lib,
+			bin_dir: resolved_bin,
+			meta_dir: resolved_meta,
+			global: resolved_global,
+			windows: resolved_windows,
+		};
+	}
+
+	method acquire_lock ( operation, options? ) {
+		if ( not _opt( options, "lock", true ) ) {
+			return new ZuzuzooLock( acquired: false );
+		}
+
+		let cfg := self.config();
+		let meta_path := new Path(cfg{meta_dir});
+		_ensure_dir(meta_path);
+		let lock_path := meta_path.child(".zuzuzoo.lock");
+		let owner_file := lock_path.child("owner.json");
+		let timeout := _opt( options, "lock_timeout", 30 );
+		let poll := _opt( options, "lock_poll", 0.1 );
+		let started := _now_epoch();
+
+		while ( true ) {
+			if ( lock_path.mkdir_exclusive() ) {
+				let owner := {
+					pid: Proc.pid(),
+					created_at: _installed_at(),
+					meta_dir: cfg{meta_dir},
+					operation: "" _ operation,
+				};
+				try {
+					( new JSON( pretty: true, canonical: true ) ).dump(
+						owner_file,
+						owner,
+					);
+				}
+				catch ( Exception e ) {
+					_cleanup_path(lock_path);
+					throw e;
+				}
+				return new ZuzuzooLock(
+					lock_path: lock_path,
+					owner_file: owner_file,
+					acquired: true,
+				);
+			}
+
+			if ( _now_epoch() - started >= timeout ) {
+				let owner_text := "";
+				try {
+					owner_text := owner_file.slurp_utf8();
+				}
+				catch ( Exception e ) {
+					owner_text := "<unreadable>";
+				}
+				die(
+					`Timed out waiting for Zuzuzoo lock ${lock_path} ` _
+					`after ${timeout} seconds; owner=${owner_text}`
+				);
+			}
+			sleep(poll);
+		}
+	}
+
+	method _metadata_files () {
+		return _metadata_files_in_dir( self.config(){meta_dir} );
+	}
+
+	method list_installed ( options? ) {
+		let codec := new JSON();
+		let installed := [];
+		for ( let file in self._metadata_files() ) {
+			let data := codec.load(file);
+			let valid := _validate_installed_metadata(
+				data,
+				file.to_String(),
+			);
+			installed.push(valid);
+		}
+
+		return installed.sort( function ( a, b ) {
+			let name_cmp := a{name} cmp b{name};
+			return name_cmp if name_cmp != 0;
+			return compare_versions( b{version}, a{version} );
+		} );
+	}
+
+	method find_installed_module ( module_name, options? ) {
+		let wanted := _module_key(module_name);
+		for ( let dist in self.list_installed(options) ) {
+			for ( let module in dist{installed}{modules} ) {
+				let installed_as := _module_key(
+					module{install_as},
+				);
+				if ( installed_as eq wanted ) {
+					return dist;
+				}
+			}
+		}
+		return null;
+	}
+
+	method find_installed_distribution ( distribution_name, options? ) {
+		let wanted := "" _ distribution_name;
+		for ( let dist in self.list_installed(options) ) {
+			return dist if dist{name} eq wanted;
+		}
+		return null;
+	}
+
+	method query ( module_name, options? ) {
+		return self.find_installed_module( module_name, options );
+	}
+
+	method query_distribution ( distribution_name, options? ) {
+		return self.find_installed_distribution(
+			distribution_name,
+			options,
+		);
+	}
+
+	method is_installed ( module_name, min_version? ) {
+		let found := self.find_installed_module(module_name);
+		return false if found instanceof Null;
+		if ( not( min_version instanceof Null ) ) {
+			let comparison := compare_versions(
+				found{version},
+				min_version,
+			);
+			return comparison >= 0;
+		}
+		return true;
+	}
+
+	method installed_version ( module_name ) {
+		let found := self.find_installed_module(module_name);
+		return found instanceof Null ? null : found{version};
+	}
+
+	method pretty_json ( value ) {
+		let codec := new JSON( pretty: true, canonical: true );
+		return codec.encode(value);
+	}
+
+	method format_json ( value, options? ) {
+		return self.pretty_json(value);
+	}
+
+	method _verify_module_file ( result, dist, entry ) {
+		let path := _path_child(
+			dist{installed}{lib_dir},
+			entry{install_as},
+		);
+		let file := {
+			kind: "module",
+			distribution: dist{name},
+			version: dist{version},
+			install_as: entry{install_as},
+			path: path.to_String(),
+			exists: path.exists(),
+			expected_sha256: entry{sha256},
+			expected_size: entry.get( "size", null ),
+			actual_sha256: null,
+			actual_size: null,
+			hash_ok: false,
+			size_ok: null,
+		};
+		if ( path.exists() ) {
+			let bytes := path.slurp();
+			file{actual_sha256} := sha256_hex(bytes);
+			file{actual_size} := path.size();
+			file{hash_ok} := file{actual_sha256} eq entry{sha256};
+			if ( file{expected_size} != null ) {
+				file{size_ok} := file{actual_size} == file{expected_size};
+				if ( not file{size_ok} ) {
+					result{size_mismatches}.push(file);
+				}
+			}
+			if ( not file{hash_ok} ) {
+				result{hash_mismatches}.push(file);
+			}
+		}
+		else {
+			result{missing_files}.push(file);
+		}
+		result{files}.push(file);
+		result{checked_files}.push(file);
+		return file;
+	}
+
+	method _verify_script_file ( result, dist, entry ) {
+		let path := _path_child(
+			dist{installed}{bin_dir},
+			entry{install_as},
+		);
+		let file := {
+			kind: "script",
+			distribution: dist{name},
+			version: dist{version},
+			install_as: entry{install_as},
+			path: path.to_String(),
+			exists: path.exists(),
+			expected_sha256: entry{sha256},
+			expected_size: entry.get( "size", null ),
+			actual_sha256: null,
+			actual_size: null,
+			hash_ok: false,
+			size_ok: null,
+		};
+		if ( path.exists() ) {
+			let bytes := path.slurp();
+			file{actual_sha256} := sha256_hex(bytes);
+			file{actual_size} := path.size();
+			file{hash_ok} := file{actual_sha256} eq entry{sha256};
+			if ( file{expected_size} != null ) {
+				file{size_ok} := file{actual_size} == file{expected_size};
+				if ( not file{size_ok} ) {
+					result{size_mismatches}.push(file);
+				}
+			}
+			if ( not file{hash_ok} ) {
+				result{hash_mismatches}.push(file);
+			}
+		}
+		else {
+			result{missing_files}.push(file);
+		}
+		result{files}.push(file);
+		result{checked_files}.push(file);
+
+		for ( let wrapper in entry.get( "wrappers", [] ) ) {
+			let wrapper_path := _path_child(
+				dist{installed}{bin_dir},
+				wrapper,
+			);
+			let wrapper_file := {
+				kind: "wrapper",
+				distribution: dist{name},
+				version: dist{version},
+				install_as: wrapper,
+				path: wrapper_path.to_String(),
+				exists: wrapper_path.exists(),
+				expected_sha256: null,
+				actual_sha256: null,
+				hash_ok: null,
+			};
+			if ( not wrapper_file{exists} ) {
+				result{missing_files}.push(wrapper_file);
+			}
+			result{files}.push(wrapper_file);
+			result{wrapper_files}.push(wrapper_file);
+		}
+		return file;
+	}
+
+	method verify ( targets, options? ) {
+		let roots := self.dependency_roots(options);
+		let target_root := roots[0];
+		let installed := _list_installed_in_root(target_root);
+		let result := {
+			ok: true,
+			target_root: target_root,
+			targets: [],
+			distributions: [],
+			files: [],
+			checked_files: [],
+			wrapper_files: [],
+			missing_files: [],
+			hash_mismatches: [],
+			size_mismatches: [],
+			skipped_duplicates: [],
+			errors: [],
+		};
+
+		let seen := {};
+		for ( let target in _target_list(targets) ) {
+			let record := _remove_target_record( target, options );
+			if ( record{type} eq "dist" ) {
+				record{type} := "distribution";
+			}
+			record{matches} := [];
+			result{targets}.push(record);
+
+			if (
+				(
+					record{type} ne "module" and
+					record{type} ne "distribution"
+				) or
+				record{value} eq ""
+			) {
+				_add_verify_target_error(
+					result,
+					"invalid-target",
+					record,
+					"verify target must be a module or distribution",
+				);
+				next;
+			}
+
+			let matches := record{type} eq "module"
+				? self._module_remove_matches(
+					installed,
+					record{value},
+				)
+				: self._distribution_remove_matches(
+					installed,
+					record{value},
+				);
+			for ( let match in matches ) {
+				record{matches}.push(
+					{
+						name: match{name},
+						version: match{version},
+						metadata_file: match{metadata_file},
+					},
+				);
+			}
+
+			if ( matches.length() == 0 ) {
+				_add_verify_target_error(
+					result,
+					"missing-target",
+					record,
+					"verify target is not installed",
+				);
+				next;
+			}
+			if ( record{type} eq "module" and matches.length() > 1 ) {
+				_add_verify_target_error(
+					result,
+					"ambiguous-target",
+					record,
+					"module target has multiple owners",
+				);
+				result{errors}[ result{errors}.length() - 1 ]{matches} :=
+					record{matches};
+				next;
+			}
+
+			for ( let dist in matches ) {
+				let key := dist{metadata_file};
+				if ( seen.exists(key) ) {
+					result{skipped_duplicates}.push(
+						{
+							target: record,
+							name: dist{name},
+							version: dist{version},
+							metadata_file: dist{metadata_file},
+						},
+					);
+					next;
+				}
+				seen.add( key, true );
+				result{distributions}.push(
+					{
+						name: dist{name},
+						version: dist{version},
+						metadata_file: dist{metadata_file},
+					},
+				);
+				for ( let module in dist{installed}{modules} ) {
+					self._verify_module_file(
+						result,
+						dist,
+						module,
+					);
+				}
+				for ( let script in dist{installed}{scripts} ) {
+					self._verify_script_file(
+						result,
+						dist,
+						script,
+					);
+				}
+			}
+		}
+
+		result{ok} := (
+			result{errors}.length() == 0 and
+			result{missing_files}.length() == 0 and
+			result{hash_mismatches}.length() == 0 and
+			result{size_mismatches}.length() == 0
+		);
+		return result;
+	}
+
+	method latest ( module_name, options? ) {
+		let module := _latest_module_name(module_name);
+		let base := _trim_right_slash(
+			"" _ _opt( options, "base_url", base_url ),
+		);
+		let url := base _ "/module/" _ module _ ".json";
+		let ua := _opt( options, "user_agent", self._user_agent() );
+		let req := ua.build_request( "GET", url );
+		_progress( options, "downloading latest metadata " _ url );
+		let response := ua.send(req);
+		response.expect_success();
+		let remote_url := url;
+		if ( response can "url" ) {
+			remote_url := response.url();
+		}
+		_progress( options, "received latest metadata " _ remote_url );
+
+		let metadata := _validate_source_metadata(
+			response.json(),
+			remote_url,
+		);
+		if ( not metadata.exists("status") ) {
+			metadata{status} := "stable";
+		}
+		if (
+			metadata.exists("status") and
+			metadata{status} eq "trial"
+		) {
+			die(
+				"Trial distributions are not available through " _
+				"module-name latest endpoints"
+			);
+		}
+
+		let installed := self.find_installed_module( module, options );
+			let installed_version := installed instanceof Null
+			? null
+			: installed{version};
+		let status := _latest_status(
+			installed_version,
+			metadata{version},
+		);
+
+		return {
+			ok: true,
+			module_name: module,
+			status: status,
+			can_upgrade: status eq "outdated",
+			installed_version: installed_version,
+			remote_version: metadata{version},
+			remote_distribution: metadata{name},
+			remote_status: metadata{status},
+			url: url,
+			remote_url: remote_url,
+			installed: installed,
+			remote_metadata: metadata,
+		};
+	}
+
+	method can_upgrade ( module_name, options? ) {
+		return self.latest( module_name, options );
+	}
+
+	method fetch_source ( target, options? ) {
+		let value := "" _ target;
+		let file := new Path(value);
+		if ( file.exists() and file.is_file() ) {
+			_progress( options, "using local archive " _ file.to_String() );
+			let source := {
+				type: "file",
+				value: value,
+				path: file.to_String(),
+				path_obj: file,
+			};
+			_check_expected_source_sha(
+				source,
+				_opt( options, "expected_sha256", null ),
+			);
+			return source;
+		}
+
+		let source_type := _is_url(value) ? "url" : "module";
+		let url := value;
+		if ( source_type eq "module" ) {
+			let base := _trim_right_slash(
+				"" _ _opt( options, "base_url", base_url ),
+			);
+			url := base _ "/module/" _ value;
+		}
+
+		let cache_dir := _opt( options, "cache_dir", null );
+		if ( not( cache_dir instanceof Null ) ) {
+			let paths := _cache_paths( cache_dir, url );
+			let cached := _validate_cache_entry(paths);
+			if ( cached ) {
+				_progress(
+					options,
+					"using cached archive for " _ value _ " from " _
+						paths{archive}.to_String(),
+				);
+				let source := {
+					type: source_type,
+					value: value,
+					url: url,
+					resolved_url: cached{resolved_url},
+					path: paths{archive}.to_String(),
+					path_obj: paths{archive},
+					cache_hit: true,
+					cache_sidecar: paths{sidecar}.to_String(),
+				};
+				_check_expected_source_sha(
+					source,
+					_opt( options, "expected_sha256", null ),
+				);
+				return source;
+			}
+			_delete_cache_entry(paths);
+		}
+
+		let temp_dir := _new_temp_dir( options, "zuzuzoo-source-" );
+		let temp_path := temp_dir.child("source.archive");
+		let ua := _opt( options, "user_agent", self._user_agent() );
+		let req := ua.build_request( "GET", url )
+			.download_to( temp_path.to_String() );
+		_progress( options, "downloading " _ value _ " from " _ url );
+		let response := ua.send(req);
+
+		let download_url := url;
+		if ( not _response_success(response) and source_type eq "module" ) {
+			_progress(
+				options,
+				"module archive download failed from " _ url _ " (" _
+					_response_status_text(response) _
+					"); checking latest metadata",
+			);
+			_cleanup_path(temp_path);
+
+			let latest_info := self.latest( value, options );
+			let archive_url := _archive_url_from_latest(latest_info);
+			req := ua.build_request( "GET", archive_url )
+				.download_to( temp_path.to_String() );
+			_progress(
+				options,
+				"downloading " _ value _ " from " _ archive_url,
+			);
+			response := ua.send(req);
+			download_url := archive_url;
+		}
+
+		if ( not _response_success(response) ) {
+			_cleanup_path(temp_dir);
+			die(
+				"Source download failed (target=" _ value _
+				", source_type=" _ source_type _
+				", url=" _ download_url _
+				"): HTTP request failed (" _
+					_response_status_text(response) _ ")"
+			);
+		}
+
+		let resolved_url := download_url;
+		if ( response can "url" ) {
+			resolved_url := response.url();
+		}
+		_progress(
+			options,
+			"downloaded " _ value _ " from " _ resolved_url _ " to " _
+				temp_path.to_String(),
+		);
+
+		let source := {
+			type: source_type,
+			value: value,
+			url: url,
+			resolved_url: resolved_url,
+			path: temp_path.to_String(),
+			path_obj: temp_path,
+			temp_dir: temp_dir,
+		};
+		_check_expected_source_sha(
+			source,
+			_opt( options, "expected_sha256", null ),
+		);
+
+		if ( not( cache_dir instanceof Null ) ) {
+			let paths := _cache_paths( cache_dir, url );
+			try {
+				let sidecar := _write_cache_entry(
+					paths,
+					source,
+					temp_path,
+				);
+				source{path} := paths{archive}.to_String();
+				source{path_obj} := paths{archive};
+				source{cache_hit} := false;
+				source{cache_sidecar} := paths{sidecar}.to_String();
+				source{cache_metadata} := sidecar;
+				_progress(
+					options,
+					"cached " _ value _ " at " _
+						paths{archive}.to_String(),
+				);
+				_cleanup_path(temp_dir);
+			}
+			catch ( Exception e ) {
+				_cleanup_path(temp_dir);
+				die _corrupt_archive_error( source, e );
+			}
+		}
+
+		return source;
+	}
+
+	method load_distribution ( target, options? ) {
+		let source := null;
+		let work_dir := null;
+		try {
+			source := self.fetch_source( target, options );
+			let source_path := new Path( source{path} );
+			let archive := null;
+			try {
+				archive := Archive.decode( source_path.slurp() );
+			}
+			catch ( Exception e ) {
+				die _corrupt_archive_error( source, e );
+			}
+			let root_name := _safe_archive_root( archive, source{path} );
+			work_dir := _new_temp_dir( options, "zuzuzoo-work-" );
+			let root_dir := work_dir.child(root_name);
+			root_dir.mkdir();
+			_progress(
+				options,
+				"extracting " _ source{path} _ " to " _
+					work_dir.to_String(),
+			);
+			_extract_archive( archive, root_name, root_dir );
+
+			let metadata_file := root_dir.child("zuzu-distribution.json");
+			if ( not metadata_file.exists() ) {
+				die(
+					`Invalid archive ${source{path}}: ` _
+					"missing zuzu-distribution.json"
+				);
+			}
+			let codec := new JSON( pairlists: true );
+			let metadata := _validate_source_metadata(
+				codec.load(metadata_file),
+				metadata_file.to_String(),
+			);
+
+			let expected_root := metadata{name} _ "-" _ metadata{version};
+			if ( root_name ne expected_root ) {
+				die(
+					`Invalid archive ${source{path}}: root ${root_name} ` _
+					`does not match ${expected_root}`
+				);
+			}
+
+			let build_result := null;
+			let build_file := root_dir.child("Build.zzs");
+			if ( build_file.exists() and build_file.is_file() ) {
+				_progress(
+					options,
+					"building " _ metadata{name} _ " " _
+						metadata{version} _ " with Build.zzs",
+				);
+				build_result := Proc.run(
+					_opt( options, "zuzu_command", zuzu_command ),
+					[ "Build.zzs" ],
+					{
+						cwd: root_dir.to_String(),
+						capture_stdout: true,
+						capture_stderr: true,
+					},
+				);
+				if ( not Proc.is_success(build_result) ) {
+					die(
+						"Build.zzs failed: " _
+						Proc.status_text(build_result)
+					);
+				}
+				metadata := _validate_source_metadata(
+					codec.load(metadata_file),
+					metadata_file.to_String(),
+				);
+				let post_build_root := metadata{name} _ "-" _
+					metadata{version};
+				if ( root_name ne post_build_root ) {
+					die(
+						`Invalid archive ${source{path}}: root ${root_name} ` _
+						`does not match ${post_build_root}`
+					);
+				}
+			}
+
+			let module_sources := _discover_files(
+				root_dir,
+				"modules",
+				".zzm",
+			);
+			let script_sources := _discover_scripts(root_dir);
+			let tests := _discover_files( root_dir, "tests", ".zzs" );
+			let modules := module_sources.map( function ( source ) {
+				return {
+					source: source,
+					install_as: _module_install_name(source),
+				};
+			} );
+			let scripts := script_sources.map( function ( source ) {
+				return {
+					source: source,
+					install_as: _script_install_name(source),
+				};
+			} );
+
+			let loaded := {
+				source: source,
+				archive: archive,
+				work_dir: work_dir.to_String(),
+				root: root_dir.to_String(),
+				work_dir_obj: work_dir,
+				root_obj: root_dir,
+				root_name: root_name,
+				metadata: metadata,
+				modules: modules,
+				scripts: scripts,
+				tests: tests,
+				build: build_result,
+			};
+			if ( not _opt( options, "keep_work_dirs", false ) ) {
+				_cleanup_source( source, options );
+				_cleanup_path(work_dir);
+			}
+			return loaded;
+		}
+		catch ( Exception e ) {
+			_cleanup_source( source, options );
+			_cleanup_path(work_dir)
+				if not _opt( options, "keep_work_dirs", false );
+			throw e;
+		}
+	}
+
+	method dependency_roots ( options? ) {
+		let cfg := self.config();
+		let target := _root_from_config( "target", "target", cfg );
+		let roots := [];
+		let seen := {};
+		_add_root( roots, seen, target );
+
+		if ( not cfg{global} and not cfg{windows} ) {
+			let global_override := _opt(
+				options,
+				"global_root",
+				global_root,
+			);
+			let global_dependency_root := null;
+			if ( not( global_override instanceof Null ) ) {
+				global_dependency_root := _root_override(
+					global_override,
+					"global",
+					"global",
+					"global",
+				);
+			}
+			else {
+				let global_cfg := new Zuzuzoo(
+					global: true,
+					windows: false,
+					home: home,
+					userprofile: userprofile,
+				).config();
+				global_dependency_root := _root_from_config(
+					"global",
+					"global",
+					global_cfg,
+				);
+			}
+			_add_root(
+				roots,
+				seen,
+				global_dependency_root,
+			);
+		}
+
+		let user_cfg := new Zuzuzoo(
+			global: false,
+			windows: cfg{windows},
+			home: home,
+			userprofile: userprofile,
+		).config();
+		_add_root(
+			roots,
+			seen,
+			_root_from_config( "user", "user", user_cfg ),
+		);
+
+		let ctor_roots := dependency_roots instanceof Null
+			? []
+			: dependency_roots;
+		for ( let root in ctor_roots ) {
+			let where := (
+				root instanceof Dict and root.exists("name")
+			)
+				? root{name}
+				: "constructor";
+			_add_root(
+				roots,
+				seen,
+				_custom_root( root, where ),
+			);
+		}
+
+		let option_roots := _opt( options, "dependency_roots", [] );
+		for ( let root in option_roots ) {
+			let where := (
+				root instanceof Dict and root.exists("name")
+			)
+				? root{name}
+				: "options";
+			_add_root(
+				roots,
+				seen,
+				_custom_root( root, where ),
+			);
+		}
+
+		return roots;
+	}
+
+	method find_dependency ( module_name, min_version?, options? ) {
+		let planned := _opt( options, "planned_installs", [] );
+		return _find_dependency_for_plan(
+			planned,
+			self.dependency_roots(options),
+			module_name,
+			min_version instanceof Null ? "0" : min_version,
+		);
+	}
+
+	method _add_removal ( removals, removal_seen, dist, root, reason ) {
+		let key := dist{metadata_file};
+		if ( removal_seen.exists(key) ) {
+			removal_seen.get(key){reasons}.push(reason);
+			return false;
+		}
+		let removal := {
+			name: dist{name},
+			version: dist{version},
+			metadata_file: dist{metadata_file},
+			root: root,
+			reasons: [ reason ],
+			distribution: dist,
+		};
+		removal_seen.add( key, removal );
+		removals.push(removal);
+		return true;
+	}
+
+	method _plan_target_root_removals (
+		plan,
+		target_installed,
+		target_root
+	) {
+		let removal_seen := {};
+			for ( let install_action in plan{installs} ) {
+				for ( let dist in target_installed ) {
+					if ( dist{name} eq install_action{metadata}{name} ) {
+						let reason := dist{version} eq install_action{metadata}{version}
+							? "reinstall"
+							: "prior-version";
+					self._add_removal(
+						plan{removals},
+						removal_seen,
+						dist,
+						target_root,
+						reason,
+					);
+				}
+			}
+		}
+
+			for ( let install_action in plan{installs} ) {
+				for ( let module in install_action{modules} ) {
+					let destination := _path_join(
+						target_root{lib_dir},
+					module{install_as},
+					target_root{windows},
+				);
+				for ( let dist in target_installed ) {
+					for ( let owned in dist{installed}{modules} ) {
+						if ( owned{install_as} eq module{install_as} ) {
+							plan{ownership_conflicts}.push(
+									{
+										kind: "module",
+										install_as: module{install_as},
+										destination: destination,
+										planned_distribution: install_action{metadata}{name},
+										planned_version: install_action{metadata}{version},
+										owner_distribution: dist{name},
+									owner_version: dist{version},
+									owner_metadata_file: dist{metadata_file},
+									root: target_root,
+								},
+							);
+							self._add_removal(
+								plan{removals},
+								removal_seen,
+								dist,
+								target_root,
+								"owner-conflict",
+							);
+						}
+					}
+				}
+			}
+
+				for ( let script in install_action{scripts} ) {
+					let destination := _path_join(
+					target_root{bin_dir},
+					script{install_as},
+					target_root{windows},
+				);
+				for ( let dist in target_installed ) {
+					for ( let owned in dist{installed}{scripts} ) {
+						if ( owned{install_as} eq script{install_as} ) {
+							plan{ownership_conflicts}.push(
+									{
+										kind: "script",
+										install_as: script{install_as},
+										destination: destination,
+										planned_distribution: install_action{metadata}{name},
+										planned_version: install_action{metadata}{version},
+										owner_distribution: dist{name},
+									owner_version: dist{version},
+									owner_metadata_file: dist{metadata_file},
+									root: target_root,
+								},
+							);
+							self._add_removal(
+								plan{removals},
+								removal_seen,
+								dist,
+								target_root,
+								"owner-conflict",
+							);
+						}
+					}
+				}
+			}
+		}
+		return plan;
+	}
+
+	method _module_remove_matches ( installed, module_name ) {
+		let wanted := _module_key(module_name);
+		let matches := [];
+		for ( let dist in installed ) {
+			for ( let module in dist{installed}{modules} ) {
+				if ( _module_key( module{install_as} ) eq wanted ) {
+					matches.push(dist);
+					last;
+				}
+			}
+		}
+		return matches;
+	}
+
+	method _distribution_remove_matches ( installed, distribution_name ) {
+		let wanted := "" _ distribution_name;
+		let matches := [];
+		for ( let dist in installed ) {
+			matches.push(dist) if dist{name} eq wanted;
+		}
+		return matches;
+	}
+
+	method _remove_owner_map ( installed, target_root ) {
+		let by_path := {};
+		for ( let dist in installed ) {
+			let owner := _owner_record(dist);
+			for ( let module in dist{installed}{modules} ) {
+				_add_owner_for_path(
+					by_path,
+					_path_join(
+						target_root{lib_dir},
+						module{install_as},
+						target_root{windows},
+					),
+					owner,
+				);
+			}
+			for ( let script in dist{installed}{scripts} ) {
+				_add_owner_for_path(
+					by_path,
+					_path_join(
+						target_root{bin_dir},
+						script{install_as},
+						target_root{windows},
+					),
+					owner,
+				);
+				for ( let wrapper in script.get( "wrappers", [] ) ) {
+					_add_owner_for_path(
+						by_path,
+						_path_join(
+							target_root{bin_dir},
+							wrapper,
+							target_root{windows},
+						),
+						owner,
+					);
+				}
+			}
+		}
+		return by_path;
+	}
+
+	method _add_remove_file (
+		plan,
+		file_seen,
+		owner_map,
+		planned_metadata,
+		kind,
+		path,
+		dist,
+		install_as
+	) {
+		return false if file_seen.exists(path);
+		file_seen.add( path, true );
+
+		let owners := kind eq "metadata"
+			? [ _owner_record(dist) ]
+			: owner_map.get( path, [ _owner_record(dist) ] );
+		let planned_owners := [];
+		let kept_owners := [];
+		for ( let owner in owners ) {
+			if ( planned_metadata.exists(owner{metadata_file}) ) {
+				planned_owners.push(owner);
+			}
+			else {
+				kept_owners.push(owner);
+			}
+		}
+
+		let blocked := kind ne "metadata" and kept_owners.length() > 0;
+		let file := {
+			kind: kind,
+			path: path,
+			exists: ( new Path(path) ).exists(),
+			owners: owners,
+			planned_owners: planned_owners,
+			kept_owners: kept_owners,
+			blocked: blocked,
+		};
+		file{install_as} := install_as if not( install_as instanceof Null );
+		plan{files}.push(file);
+
+		if ( blocked ) {
+			let conflict := {
+				kind: kind,
+				path: path,
+				install_as: install_as,
+				owners: owners,
+				planned_owners: planned_owners,
+				kept_owners: kept_owners,
+			};
+			plan{shared_file_conflicts}.push(conflict);
+			plan{errors}.push(
+				{
+					code: "shared-file-conflict",
+					message: "file is also owned by a kept distribution",
+					path: path,
+					owners: owners,
+					kept_owners: kept_owners,
+				},
+			);
+		}
+		return true;
+	}
+
+	method _build_remove_files ( plan, installed, target_root ) {
+		let owner_map := self._remove_owner_map( installed, target_root );
+		let planned_metadata := {};
+		for ( let removal in plan{removals} ) {
+			planned_metadata.add( removal{metadata_file}, true );
+		}
+
+		let file_seen := {};
+		for ( let removal in plan{removals} ) {
+			let dist := removal{distribution};
+			for ( let module in dist{installed}{modules} ) {
+				self._add_remove_file(
+					plan,
+					file_seen,
+					owner_map,
+					planned_metadata,
+					"module",
+					_path_join(
+						target_root{lib_dir},
+						module{install_as},
+						target_root{windows},
+					),
+					dist,
+					module{install_as},
+				);
+			}
+			for ( let script in dist{installed}{scripts} ) {
+				self._add_remove_file(
+					plan,
+					file_seen,
+					owner_map,
+					planned_metadata,
+					"script",
+					_path_join(
+						target_root{bin_dir},
+						script{install_as},
+						target_root{windows},
+					),
+					dist,
+					script{install_as},
+				);
+				for ( let wrapper in script.get( "wrappers", [] ) ) {
+					self._add_remove_file(
+						plan,
+						file_seen,
+						owner_map,
+						planned_metadata,
+						"wrapper",
+						_path_join(
+							target_root{bin_dir},
+							wrapper,
+							target_root{windows},
+						),
+						dist,
+						wrapper,
+					);
+				}
+			}
+		}
+
+		for ( let removal in plan{removals} ) {
+			self._add_remove_file(
+				plan,
+				file_seen,
+				owner_map,
+				planned_metadata,
+				"metadata",
+				removal{metadata_file},
+				removal{distribution},
+				null,
+			);
+		}
+
+		plan{files} := plan{files}.sort(_remove_file_cmp);
+		plan{shared_file_conflicts} :=
+			plan{shared_file_conflicts}.sort(
+				fn ( a, b ) -> a{path} cmp b{path},
+			);
+		return plan;
+	}
+
+	method plan_remove ( targets, options? ) {
+		let roots := self.dependency_roots(options);
+		let target_root := roots[0];
+		let installed := _list_installed_in_root(target_root);
+		let plan := {
+			ok: true,
+			target_root: target_root,
+			targets: [],
+			removals: [],
+			files: [],
+			shared_file_conflicts: [],
+			skipped_duplicates: [],
+			errors: [],
+		};
+
+		let removal_seen := {};
+		for ( let target in _target_list(targets) ) {
+			let record := _remove_target_record( target, options );
+			if ( record{type} eq "dist" ) {
+				record{type} := "distribution";
+			}
+			record{matches} := [];
+			plan{targets}.push(record);
+
+			if (
+				(
+					record{type} ne "module" and
+					record{type} ne "distribution"
+				) or
+				record{value} eq ""
+			) {
+				plan{errors}.push(
+					{
+						code: "invalid-target",
+						target: record,
+						message: "remove target must be a module or distribution",
+					},
+				);
+				next;
+			}
+
+			let matches := record{type} eq "module"
+				? self._module_remove_matches(
+					installed,
+					record{value},
+				)
+				: self._distribution_remove_matches(
+					installed,
+					record{value},
+				);
+			for ( let match in matches ) {
+				record{matches}.push(
+					{
+						name: match{name},
+						version: match{version},
+						metadata_file: match{metadata_file},
+					},
+				);
+			}
+
+			if ( matches.length() == 0 ) {
+				plan{errors}.push(
+					{
+						code: "missing-target",
+						target: record,
+						message: "remove target is not installed",
+					},
+				);
+				next;
+			}
+			if ( record{type} eq "module" and matches.length() > 1 ) {
+				plan{errors}.push(
+					{
+						code: "ambiguous-target",
+						target: record,
+						message: "module target has multiple owners",
+						matches: record{matches},
+					},
+				);
+				next;
+			}
+
+			for ( let dist in matches ) {
+				let added := self._add_removal(
+					plan{removals},
+					removal_seen,
+					dist,
+					target_root,
+					record{type} eq "module"
+						? "requested-module"
+						: "requested-distribution",
+				);
+				if ( not added ) {
+					plan{skipped_duplicates}.push(
+						{
+							target: record,
+							name: dist{name},
+							version: dist{version},
+							metadata_file: dist{metadata_file},
+						},
+					);
+				}
+			}
+		}
+
+		plan{removals} := plan{removals}.sort(_removal_cmp);
+		self._build_remove_files( plan, installed, target_root );
+		plan{ok} := (
+			plan{errors}.length() == 0 and
+			plan{shared_file_conflicts}.length() == 0
+		);
+		return plan;
+	}
+
+	method plan_install ( targets, options? ) {
+		let roots := self.dependency_roots(options);
+		let target_root := roots[0];
+		let plan := {
+			target_root: target_root,
+			dependency_roots: roots,
+			installs: [],
+			removals: [],
+			satisfied_dependencies: [],
+			dependency_graph: {
+				nodes: [],
+				edges: [],
+			},
+			ownership_conflicts: [],
+		};
+
+		let planned := [];
+		let planned_by_name := {};
+		let status_by_name := {};
+		let seen_targets := {};
+		let loaded_work := [];
+
+		function resolve ( target, requested, dependency_of, min_version, stack ) {
+			let target_text := "" _ target;
+			if ( requested ) {
+				return null if seen_targets.exists(target_text);
+				seen_targets.add( target_text, true );
+			}
+			else {
+				let found := _find_dependency_for_plan(
+					planned,
+					roots,
+					target_text,
+					min_version,
+				);
+				if ( not( found instanceof Null ) ) {
+					if (
+						found{source} eq "planned" and
+						status_by_name.get(found{distribution}, "") eq "visiting"
+					) {
+						die "Dependency cycle detected: " _
+							_cycle_path( stack, target_text );
+					}
+					let satisfied := found;
+					satisfied{requested_by} := dependency_of instanceof Null
+						? null
+						: dependency_of{metadata}{name};
+					plan{satisfied_dependencies}.push(satisfied);
+					return null;
+				}
+				if ( _stack_contains( stack, target_text ) ) {
+					die "Dependency cycle detected: " _
+						_cycle_path( stack, target_text );
+				}
+			}
+
+			let dist := self.load_distribution(
+				target_text,
+				_copy_options_with( options, "keep_work_dirs", true ),
+			);
+			loaded_work.push(dist);
+			if (
+				dist{source}{type} eq "module" and
+				dist{metadata}.exists("status") and
+				dist{metadata}{status} eq "trial"
+			) {
+				die(
+					"Trial distributions are not available through " _
+					"module-name endpoints"
+				);
+			}
+			if (
+				not requested and
+				not _loaded_distribution_provides(
+					dist,
+					target_text,
+					min_version,
+				)
+			) {
+				let dep := {
+					module_name: target_text,
+					min_version: min_version,
+				};
+				_cleanup_source( dist{source}, options );
+				_cleanup_path(dist{work_dir_obj})
+					if not _opt( options, "keep_work_dirs", false );
+				die _dependency_conflict_message(
+					dep,
+					dependency_of,
+					stack,
+					null,
+					dist,
+				);
+			}
+
+			let dist_name := dist{metadata}{name};
+			if ( planned_by_name.exists(dist_name) ) {
+				let existing := planned_by_name.get(dist_name);
+				if (
+					existing{metadata}{version} ne
+					dist{metadata}{version}
+				) {
+					_cleanup_source( dist{source}, options );
+					_cleanup_path(dist{work_dir_obj})
+						if not _opt( options, "keep_work_dirs", false );
+					if ( requested ) {
+						die _planned_version_conflict_message(
+							dist_name,
+							existing,
+							dist,
+							target_text,
+						);
+					}
+					let dep := {
+						module_name: target_text,
+						min_version: min_version,
+					};
+					die _dependency_conflict_message(
+						dep,
+						dependency_of,
+						stack,
+						existing,
+						dist,
+					);
+				}
+				_cleanup_source( dist{source}, options );
+				_cleanup_path(dist{work_dir_obj})
+					if not _opt( options, "keep_work_dirs", false );
+				return existing;
+			}
+
+			let dependencies := _dependency_entries(dist{metadata});
+			let install_action := {
+				action: "install",
+				target: target_text,
+				requested: requested ? true : false,
+				dependency_of: dependency_of instanceof Null
+					? null
+					: dependency_of{metadata}{name},
+				source: dist{source},
+				metadata: dist{metadata},
+				modules: dist{modules},
+				scripts: dist{scripts},
+				tests: dist{tests},
+				dependencies: dependencies,
+				target_root: target_root,
+				root: dist{root},
+				work_dir: dist{work_dir},
+				root_obj: dist{root_obj},
+				work_dir_obj: dist{work_dir_obj},
+			};
+			planned.push(install_action);
+			planned_by_name.add( dist_name, install_action );
+			status_by_name.add( dist_name, "visiting" );
+			plan{dependency_graph}{nodes}.push(
+				{
+					name: dist_name,
+					version: dist{metadata}{version},
+					target: target_text,
+					requested: requested ? true : false,
+				},
+			);
+
+			let next_stack := stack;
+			if ( dist{source}{type} eq "module" ) {
+				next_stack := [];
+				for ( let item in stack ) {
+					next_stack.push(item);
+				}
+				next_stack.push(target_text);
+			}
+
+			for ( let dep in dependencies ) {
+				let found := _find_dependency_for_plan(
+					planned,
+					roots,
+					dep{module_name},
+					dep{min_version},
+				);
+				if ( not( found instanceof Null ) ) {
+					if (
+						found{source} eq "planned" and
+						status_by_name.get(found{distribution}, "") eq "visiting"
+					) {
+						die "Dependency cycle detected: " _
+							_cycle_path( next_stack, dep{module_name} );
+					}
+					let satisfied := found;
+					satisfied{requested_by} := dist_name;
+					plan{satisfied_dependencies}.push(satisfied);
+					plan{dependency_graph}{edges}.push(
+						{
+							from: dist_name,
+							module_name: dep{module_name},
+							min_version: dep{min_version},
+							status: found{source} eq "planned"
+								? "planned"
+								: "satisfied",
+							to: found{distribution},
+							root: found.exists("root") ? found{root} : null,
+						},
+					);
+				}
+				else {
+					let dep_install := resolve(
+						dep{module_name},
+						false,
+						install_action,
+						dep{min_version},
+						next_stack,
+					);
+					plan{dependency_graph}{edges}.push(
+						{
+							from: dist_name,
+							module_name: dep{module_name},
+							min_version: dep{min_version},
+							status: "planned",
+							to: dep_install instanceof Null
+								? null
+								: dep_install{metadata}{name},
+							root: target_root,
+						},
+					);
+				}
+			}
+
+			status_by_name.set( dist_name, "done" );
+			plan{installs}.push(install_action);
+			return install_action;
+		}
+
+		try {
+			for ( let target in _target_list(targets) ) {
+				resolve( target, true, null, "0", [] );
+			}
+		}
+		catch ( Exception e ) {
+			_cleanup_loaded_work_dirs(loaded_work, options);
+			throw e;
+		}
+
+		self._plan_target_root_removals(
+			plan,
+			_list_installed_in_root(target_root),
+			target_root,
+		);
+
+		return plan;
+	}
+
+	method run_distribution_tests ( install_action, options? ) {
+		let results := [];
+		let include_dirs := [];
+		let seen_include_dirs := {};
+		let own_modules := _path_child( install_action{root}, "modules" );
+		_push_unique_string(
+			include_dirs,
+			seen_include_dirs,
+			own_modules.to_String(),
+		) if own_modules.exists() and own_modules.is_dir();
+		for ( let include_dir in _opt( options, "test_include_dirs", [] ) ) {
+			_push_unique_string(
+				include_dirs,
+				seen_include_dirs,
+				include_dir,
+			);
+		}
+
+		for ( let test in install_action{tests} ) {
+			_progress(
+				options,
+				"testing " _ install_action{metadata}{name} _ " " _
+					install_action{metadata}{version} _ ": " _ test,
+			);
+			let argv := include_dirs.map( fn d -> "-I" _ d );
+			argv.push(test);
+			let run_result := Proc.run(
+				_opt( options, "zuzu_command", zuzu_command ),
+				argv,
+				{
+					cwd: install_action{root},
+					capture_stdout: true,
+					capture_stderr: true,
+				},
+			);
+			let parsed := parse_tap(run_result{stdout});
+			results.push(
+				{
+					test: test,
+					ok: _test_ok( parsed, run_result ),
+					status: Proc.status_text(run_result),
+					result: run_result,
+					tap: parsed,
+					stdout: run_result{stdout},
+					stderr: run_result{stderr},
+				},
+			);
+		}
+		let ok := true;
+		for ( let result in results ) {
+			ok := false if not result{ok};
+		}
+		return {
+			ok: ok,
+			tests: results,
+			distribution: install_action{metadata}{name},
+			version: install_action{metadata}{version},
+		};
+	}
+
+	method execute_removal ( removal_action, options? ) {
+		_progress(
+			options,
+			"removing " _ removal_action{name} _ " " _
+				removal_action{version},
+		);
+		let warnings := [];
+		let removed := [];
+		let dist := removal_action{distribution};
+		let root := removal_action{root};
+
+		function remove_file ( path, kind ) {
+			if ( path.exists() ) {
+				path.remove();
+				removed.push(
+					{
+						kind: kind,
+						path: path.to_String(),
+					},
+				);
+			}
+			else {
+				warnings.push(
+					{
+						kind: kind,
+						path: path.to_String(),
+						message: "missing file",
+					},
+				);
+			}
+		}
+
+		for ( let module in dist{installed}{modules} ) {
+			remove_file(
+				_path_child( root{lib_dir}, module{install_as} ),
+				"module",
+			);
+		}
+		for ( let script in dist{installed}{scripts} ) {
+			remove_file(
+				_path_child( root{bin_dir}, script{install_as} ),
+				"script",
+			);
+			for ( let wrapper in script.get( "wrappers", [] ) ) {
+				remove_file(
+					_path_child( root{bin_dir}, wrapper ),
+					"wrapper",
+				);
+			}
+		}
+		remove_file( new Path( removal_action{metadata_file} ), "metadata" );
+
+		return {
+			ok: true,
+			name: removal_action{name},
+			version: removal_action{version},
+			removed: removed,
+			warnings: warnings,
+		};
+	}
+
+	method _install_action ( install_action, installed_at, options? ) {
+		let root := install_action{target_root};
+		let module_records := [];
+		let script_records := [];
+
+		for ( let module in install_action{modules} ) {
+			let source := _path_child(
+				install_action{root},
+				module{source},
+			);
+			let destination := _path_child(
+				root{lib_dir},
+				module{install_as},
+			);
+			_progress(
+				options,
+				"installing module " _ module{install_as} _ " to " _
+					destination.to_String(),
+			);
+			let written := _copy_file_atomic(source, destination, null);
+			module_records.push(
+				{
+					source: module{source},
+					install_as: module{install_as},
+					sha256: written{sha256},
+					size: written{size},
+				},
+			);
+		}
+
+		for ( let script in install_action{scripts} ) {
+			let source := _path_child(
+				install_action{root},
+				script{source},
+			);
+			let destination := _path_child(
+				root{bin_dir},
+				script{install_as},
+			);
+			_progress(
+				options,
+				"installing script " _ script{install_as} _ " to " _
+					destination.to_String(),
+			);
+			let written := _copy_file_atomic(
+				source,
+				destination,
+				root{windows} ? null : 493,
+			);
+
+			let wrappers := [];
+			if ( root{windows} ) {
+				let wrapper_name := _replace_script_suffix(
+					script{install_as},
+					".cmd",
+				);
+				let wrapper := _path_child( root{bin_dir}, wrapper_name );
+				let script_base := _relative_basename(script{install_as});
+				_progress(
+					options,
+					"installing command wrapper " _ wrapper_name _
+						" to " _ wrapper.to_String(),
+				);
+				_spew_utf8_atomic(
+					wrapper,
+					"@echo off\r\n" _
+					"zuzu \"%~dp0" _ script_base _ "\" %*\r\n",
+				);
+				wrappers.push(wrapper_name);
+			}
+
+			script_records.push(
+				{
+					source: script{source},
+					install_as: script{install_as},
+					sha256: written{sha256},
+					size: written{size},
+					wrappers: wrappers,
+				},
+			);
+		}
+
+		let metadata := _copy_source_metadata(install_action{metadata});
+		metadata{installed} := {
+			zdf: "ZDF-1",
+			lib_dir: root{lib_dir},
+			bin_dir: root{bin_dir},
+			meta_dir: root{meta_dir},
+			installed_at: installed_at,
+			source: _copy_source_record(install_action{source}),
+			modules: module_records,
+			scripts: script_records,
+		};
+
+		let metadata_file := _path_child(
+			root{meta_dir},
+			metadata{name} _ "-" _ metadata{version} _ ".json",
+		);
+		_progress(
+			options,
+			"writing metadata for " _ metadata{name} _ " " _
+				metadata{version} _ " to " _ metadata_file.to_String(),
+		);
+		_atomic_json_write( metadata_file, metadata );
+
+		return {
+			name: metadata{name},
+			version: metadata{version},
+			metadata_file: metadata_file.to_String(),
+			modules: module_records,
+			scripts: script_records,
+			metadata: metadata,
+		};
+	}
+
+	method format_install_plan ( plan ) {
+		let lines := [
+			"Install target:",
+			"  lib: " _ plan{target_root}{lib_dir},
+			"  bin: " _ plan{target_root}{bin_dir},
+			"  meta: " _ plan{target_root}{meta_dir},
+			"",
+			"Removals:",
+		];
+
+		let removal_lines := [];
+		for ( let removal in plan{removals} ) {
+			removal_lines.push(
+				"  - " _ removal{name} _ " " _ removal{version} _
+				" [" _ join(
+					", ",
+					removal{reasons}.sort( fn ( a, b ) -> a cmp b ),
+				) _ "]"
+			);
+		}
+		removal_lines := removal_lines.sort( fn ( a, b ) -> a cmp b );
+		if ( removal_lines.length() == 0 ) {
+			lines.push("  none");
+		}
+		else {
+			for ( let line in removal_lines ) {
+				lines.push(line);
+			}
+		}
+
+			lines.push("");
+			lines.push("Installs:");
+			let install_lines := [];
+			for ( let install_action in plan{installs} ) {
+				install_lines.push(
+					"  - " _ install_action{metadata}{name} _ " " _
+					install_action{metadata}{version}
+				);
+				for ( let module in install_action{modules} ) {
+					install_lines.push(
+						"    module " _ module{install_as} _ " -> " _
+					_path_join(
+						plan{target_root}{lib_dir},
+						module{install_as},
+						plan{target_root}{windows},
+					)
+					);
+				}
+				for ( let script in install_action{scripts} ) {
+					install_lines.push(
+						"    script " _ script{install_as} _ " -> " _
+					_path_join(
+						plan{target_root}{bin_dir},
+						script{install_as},
+						plan{target_root}{windows},
+					)
+				);
+			}
+		}
+		if ( install_lines.length() == 0 ) {
+			lines.push("  none");
+		}
+		else {
+			for ( let line in install_lines ) {
+				lines.push(line);
+			}
+		}
+
+		lines.push("");
+		lines.push("Conflicts:");
+		let conflict_lines := [];
+		for ( let conflict in plan{ownership_conflicts} ) {
+			conflict_lines.push(
+				"  - " _ conflict{kind} _ " " _
+				conflict{install_as} _ " owned by " _
+				conflict{owner_distribution} _ " " _
+				conflict{owner_version} _ "; replacing with " _
+				conflict{planned_distribution} _ " " _
+				conflict{planned_version} _ "; destination " _
+				conflict{destination} _ "; owner metadata " _
+				conflict{owner_metadata_file}
+			);
+		}
+		conflict_lines := conflict_lines.sort( fn ( a, b ) -> a cmp b );
+		if ( conflict_lines.length() == 0 ) {
+			lines.push("  none");
+		}
+		else {
+			for ( let line in conflict_lines ) {
+				lines.push(line);
+			}
+		}
+
+		return join( "\n", lines ) _ "\n";
+	}
+
+	method format_remove_plan ( plan ) {
+		let lines := [
+			"Remove target:",
+			"  lib: " _ plan{target_root}{lib_dir},
+			"  bin: " _ plan{target_root}{bin_dir},
+			"  meta: " _ plan{target_root}{meta_dir},
+			"",
+			"Removals:",
+		];
+
+		if ( plan{removals}.length() == 0 ) {
+			lines.push("  none");
+		}
+		else {
+			for ( let removal in plan{removals} ) {
+				lines.push(
+					"  - " _ removal{name} _ " " _
+					removal{version}
+				);
+			}
+		}
+
+		lines.push("");
+		lines.push("Files:");
+		if ( plan{files}.length() == 0 ) {
+			lines.push("  none");
+		}
+		else {
+			for ( let file in plan{files} ) {
+				let status := file{blocked}
+					? "blocked"
+					: ( file{exists} ? "exists" : "missing" );
+				lines.push(
+					"  - " _ file{kind} _ " " _
+					file{path} _ " [" _ status _ "]"
+				);
+			}
+		}
+
+		lines.push("");
+		lines.push("Shared file conflicts:");
+		if ( plan{shared_file_conflicts}.length() == 0 ) {
+			lines.push("  none");
+		}
+		else {
+			for ( let conflict in plan{shared_file_conflicts} ) {
+				let kept := conflict{kept_owners}.map(
+					fn o -> o{name} _ " " _ o{version},
+				).sort( fn ( a, b ) -> a cmp b );
+				lines.push(
+					"  - " _ conflict{path} _
+					" kept by " _ join( ", ", kept )
+				);
+			}
+		}
+
+		lines.push("");
+		lines.push("Errors:");
+		if ( plan{errors}.length() == 0 ) {
+			lines.push("  none");
+		}
+		else {
+			for ( let error in plan{errors} ) {
+				lines.push(
+					"  - " _ error{code} _ ": " _
+					error{message}
+				);
+			}
+		}
+
+		return join( "\n", lines ) _ "\n";
+	}
+
+	method _install_unlocked ( targets, options? ) {
+		_progress(
+			options,
+			"planning install for " _ join( ", ", _target_list(targets) ),
+		);
+		let plan := self.plan_install( targets, options );
+		let plan_text := self.format_install_plan(plan);
+		STDOUT.print(plan_text) if _opt( options, "print_plan", false );
+
+		if ( _opt( options, "dry_run", false ) ) {
+			_cleanup_plan_work_dirs(plan, options);
+			return {
+				ok: true,
+				dry_run: true,
+				plan: plan,
+				plan_text: plan_text,
+				tests: [],
+				removals: [],
+				installs: [],
+				warnings: [],
+			};
+		}
+
+		let test_results := [];
+		let tests_ok := true;
+		if ( not _opt( options, "no_test", false ) ) {
+			let test_include_dirs := [];
+			let seen_test_include_dirs := {};
+			for ( let install_action in plan{installs} ) {
+				let modules_dir := _path_child(
+					install_action{root},
+					"modules",
+				);
+				_push_unique_string(
+					test_include_dirs,
+					seen_test_include_dirs,
+					modules_dir.to_String(),
+				) if modules_dir.exists() and modules_dir.is_dir();
+			}
+			for ( let include_dir in _runtime_include_dirs() ) {
+				_push_unique_string(
+					test_include_dirs,
+					seen_test_include_dirs,
+					include_dir,
+				);
+			}
+			for ( let root in self.dependency_roots(options) ) {
+				_push_unique_string(
+					test_include_dirs,
+					seen_test_include_dirs,
+					root{lib_dir},
+				) if root{lib_dir} ne "";
+			}
+			let test_options := _copy_options_with(
+				options,
+				"test_include_dirs",
+				test_include_dirs,
+			);
+			for ( let install_action in plan{installs} ) {
+				let test_result := self.run_distribution_tests(
+					install_action,
+					test_options,
+				);
+				test_results.push(test_result);
+				tests_ok := false if not test_result{ok};
+			}
+		}
+
+		if ( not tests_ok and not _opt( options, "force", false ) ) {
+			_cleanup_plan_work_dirs(plan, options);
+			return {
+				ok: false,
+				error: "distribution tests failed",
+				dry_run: false,
+				plan: plan,
+				plan_text: plan_text,
+				tests: test_results,
+				removals: [],
+				installs: [],
+				warnings: [],
+			};
+		}
+
+		try {
+			let removals := [];
+			let warnings := [];
+			for ( let removal in plan{removals} ) {
+				let result := self.execute_removal( removal, options );
+				removals.push(result);
+				for ( let warning in result{warnings} ) {
+					warnings.push(warning);
+				}
+			}
+
+			let installs := [];
+			let installed_at := _installed_at();
+			for ( let install_action in plan{installs} ) {
+				installs.push( self._install_action(
+					install_action,
+					installed_at,
+					options,
+				) );
+			}
+
+			_cleanup_plan_work_dirs(plan, options);
+			return {
+				ok: true,
+				dry_run: false,
+				forced: not tests_ok and _opt( options, "force", false ),
+				plan: plan,
+				plan_text: plan_text,
+				tests: test_results,
+				removals: removals,
+				installs: installs,
+				warnings: warnings,
+			};
+		}
+		catch ( Exception e ) {
+			_cleanup_plan_work_dirs(plan, options);
+			throw e;
+		}
+	}
+
+	method install ( targets, options? ) {
+		let lock := self.acquire_lock( "install", options );
+		try {
+			let result := self._install_unlocked( targets, options );
+			lock.release();
+			return result;
+		}
+		catch ( Exception e ) {
+			lock.release();
+			throw e;
+		}
+	}
+
+	method _remove_unlocked ( targets, options? ) {
+		let plan := self.plan_remove( targets, options );
+		let plan_text := self.format_remove_plan(plan);
+		STDOUT.print(plan_text) if _opt( options, "print_plan", false );
+
+		if ( not plan{ok} ) {
+			return {
+				ok: false,
+				dry_run: false,
+				plan: plan,
+				plan_text: plan_text,
+				removed: [],
+				warnings: [],
+				errors: plan{errors},
+			};
+		}
+
+		if ( _opt( options, "dry_run", false ) ) {
+			return {
+				ok: true,
+				dry_run: true,
+				plan: plan,
+				plan_text: plan_text,
+				removed: [],
+				warnings: [],
+				errors: [],
+			};
+		}
+
+		let removed := [];
+		let warnings := [];
+		for ( let file in plan{files} ) {
+			let path := new Path(file{path});
+			if ( path.exists() ) {
+				path.remove();
+				removed.push(
+					{
+						kind: file{kind},
+						path: file{path},
+					},
+				);
+			}
+			else {
+				warnings.push(
+					{
+						kind: file{kind},
+						path: file{path},
+						message: "missing file",
+					},
+				);
+			}
+		}
+
+		return {
+			ok: true,
+			dry_run: false,
+			plan: plan,
+			plan_text: plan_text,
+			removed: removed,
+			warnings: warnings,
+			errors: [],
+		};
+	}
+
+	method remove ( targets, options? ) {
+		let lock := self.acquire_lock( "remove", options );
+		try {
+			let result := self._remove_unlocked( targets, options );
+			lock.release();
+			return result;
+		}
+		catch ( Exception e ) {
+			lock.release();
+			throw e;
+		}
+	}
+}
+
+function _zoo ( options? ) {
+	return new Zuzuzoo(
+		lib_dir: _opt( options, "lib_dir", null ),
+		bin_dir: _opt( options, "bin_dir", null ),
+		meta_dir: _opt( options, "meta_dir", null ),
+		global: _opt( options, "global", false ),
+		windows: _opt( options, "windows", null ),
+		home: _opt( options, "home", null ),
+		userprofile: _opt( options, "userprofile", null ),
+		base_url: _opt( options, "base_url", "https://zuzulang.org" ),
+		user_agent: _opt( options, "user_agent", null ),
+		zuzu_command: _opt( options, "zuzu_command", "zuzu" ),
+		dependency_roots: _opt( options, "dependency_roots", [] ),
+		global_root: _opt( options, "global_root", null ),
+	);
+}
+
+function list_installed ( options? ) {
+	return _zoo(options).list_installed(options);
+}
+
+function query ( module_name, options? ) {
+	return _zoo(options).query( module_name, options );
+}
+
+function query_distribution ( distribution_name, options? ) {
+	return _zoo(options).query_distribution( distribution_name, options );
+}
+
+function is_installed ( module_name, min_version?, options? ) {
+	return _zoo(options).is_installed( module_name, min_version );
+}
+
+function installed_version ( module_name, options? ) {
+	return _zoo(options).installed_version(module_name);
+}
+
+function pretty_json ( value, options? ) {
+	return _zoo(options).pretty_json(value);
+}
+
+function format_json ( value, options? ) {
+	return _zoo(options).format_json( value, options );
+}
+
+function fetch_source ( target, options? ) {
+	return _zoo(options).fetch_source( target, options );
+}
+
+function load_distribution ( target, options? ) {
+	return _zoo(options).load_distribution( target, options );
+}
+
+function dependency_roots ( options? ) {
+	return _zoo(options).dependency_roots(options);
+}
+
+function find_dependency ( module_name, min_version?, options? ) {
+	return _zoo(options).find_dependency(
+		module_name,
+		min_version,
+		options,
+	);
+}
+
+function plan_install ( targets, options? ) {
+	return _zoo(options).plan_install( targets, options );
+}
+
+function plan_remove ( targets, options? ) {
+	return _zoo(options).plan_remove( targets, options );
+}
+
+function verify ( targets, options? ) {
+	return _zoo(options).verify( targets, options );
+}
+
+function latest ( module_name, options? ) {
+	return _zoo(options).latest( module_name, options );
+}
+
+function can_upgrade ( module_name, options? ) {
+	return _zoo(options).can_upgrade( module_name, options );
+}
+
+function install ( targets, options? ) {
+	return _zoo(options).install( targets, options );
+}
+
+function remove ( targets, options? ) {
+	return _zoo(options).remove( targets, options );
+}
+
+function run_distribution_tests ( install_action, options? ) {
+	return _zoo(options).run_distribution_tests( install_action, options );
+}
+
+function execute_removal ( removal_action, options? ) {
+	return _zoo(options).execute_removal( removal_action, options );
+}
+
+function format_install_plan ( plan, options? ) {
+	return _zoo(options).format_install_plan(plan);
+}
+
+function format_remove_plan ( plan, options? ) {
+	return _zoo(options).format_remove_plan(plan);
+}