@agimon-ai/po 0.0.0-alpha.0

package/dist/src/composition/layerPackageInstaller/index.mjs

@@ -0,0 +1,637 @@
+import { poPackageRoot } from "../../builders/cli/entryResolution.mjs";
+import { createLayerResolvers } from "../../../builders/cli/extensionAssembler/index.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileAtomic } from "@agimon-ai/po-core/runtimeJson";
+import os from "node:os";
+import { isLocalPackageSpecifier } from "@agimon-ai/po-config/majorModes";
+import { consumerPackageEntry, splitPackageSpecifier } from "@agimon-ai/po-core/moduleResolution";
+import crypto from "node:crypto";
+import zlib from "node:zlib";
+import { installRuntimePackages, resolveNewest } from "@agimon-ai/po-core/runtimePackages";
+import { poHomeDirectory, poRuntimeDirectory } from "@agimon-ai/po-core/runtimePiSettings";
+//#region src/composition/layerPackageInstaller/index.ts
+const NPM_SOURCE_PREFIX = "npm:";
+const FILE_SPECIFIER_PREFIX = "file:";
+const WORKSPACE_SPECIFIER_PREFIX = "workspace:";
+/** Root target of a staged catalogue archive: always the staged workspace, never the registry. */
+const CATALOG_WORKSPACE_TARGET = "workspace:*";
+/** Where catalogue archives are unpacked inside the runtime, one directory per archive hash. */
+const CATALOG_STAGING_DIRECTORY = "catalog";
+const RUNTIME_PACKAGE_NAME = "po-runtime";
+const UNPINNED_PACKAGE_RANGE = "*";
+const PACKAGE_MANIFEST = "package.json";
+const NODE_MODULES = "node_modules";
+const PACKAGE_CATALOG_ENV = "PO_PACKAGE_CATALOG";
+/** The registry catalogue a release writes into the CLI package: `<package root>/dist/catalog/index.json`. */
+const BUNDLED_CATALOG_SEGMENTS = [
+	"dist",
+	"catalog",
+	"index.json"
+];
+/** upm error codes that mean the registry could not be reached, so the store may still answer. */
+const NETWORK_FAILURE_CODES = /* @__PURE__ */ new Set([
+	"ENETWORK",
+	"ETIMEDOUT",
+	"EREGISTRY"
+]);
+function overridePackageName(selector) {
+	const separatorIndex = selector.indexOf("@", selector.startsWith("@") ? 1 : 0);
+	return separatorIndex === -1 ? selector : selector.slice(0, separatorIndex);
+}
+/**
+* Same-major patches for transitive versions pinned by the current foundation packages.
+* Package managers only honor overrides from the install root, so published extensions
+* cannot carry these fixes in their own manifests.
+*/
+const SAFE_TRANSITIVE_OVERRIDES = {
+	"@hono/node-server@2.0.0 - 2.0.9": "^2.0.10",
+	"@opentelemetry/core@2.0.0 - 2.7.999": "2.8.0",
+	"brace-expansion@1.0.0 - 1.1.20": "^1.1.21",
+	"brace-expansion@5.0.0 - 5.0.11": "^5.0.12",
+	"hono@4.0.0 - 4.13.7": "4.13.8",
+	"js-yaml@4.0.0 - 4.3.1": "^4.3.2",
+	"js-yaml@5.0.0 - 5.2.1": "^5.2.2",
+	"liquidjs@10.0.0 - 10.27.1": "^10.27.2",
+	"protobufjs@8.0.0 - 8.7.1": "^8.7.2",
+	"undici@7.0.0 - 7.29.0": "^7.29.1"
+};
+const SAFE_TRANSITIVE_PACKAGE_NAMES = new Set(Object.keys(SAFE_TRANSITIVE_OVERRIDES).map(overridePackageName));
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function recordValue(value) {
+	return isRecord$1(value) ? { ...value } : {};
+}
+function withoutConflictingTransitiveOverrides(value) {
+	const overrides = recordValue(value);
+	for (const [selector, replacement] of Object.entries(overrides)) if (SAFE_TRANSITIVE_PACKAGE_NAMES.has(overridePackageName(selector))) delete overrides[selector];
+	else if (isRecord$1(replacement)) overrides[selector] = withoutConflictingTransitiveOverrides(replacement);
+	return overrides;
+}
+/** Earlier versions overrode catalog packages with relative `file:` targets; any other override is not Po's. */
+function withoutCatalogOverrides(overrides) {
+	return Object.fromEntries(Object.entries(overrides).filter(([, replacement]) => !(typeof replacement === "string" && replacement.startsWith(FILE_SPECIFIER_PREFIX))));
+}
+/** The published (non-local, required) package specifiers the default and the given layers name. */
+function configuredPackageSpecifiers(config, layers) {
+	const specifiers = /* @__PURE__ */ new Set();
+	const selectedDefinitions = [...config.default ? [config.default] : [], ...layers.map((layerName) => {
+		const layer = config.layers[layerName];
+		if (!layer) throw new Error(`Unknown layer: ${layerName}`);
+		return layer;
+	})];
+	for (const layer of selectedDefinitions) for (const configured of layer.packages ?? []) {
+		const specifier = typeof configured === "string" ? configured : configured.name;
+		if (!(typeof configured !== "string" && configured.optional === true) && !isLocalPackageSpecifier(specifier)) specifiers.add(specifier);
+	}
+	return [...specifiers];
+}
+function resolvePackageEntries(resolvers, specifier) {
+	const entries = resolvers.optionalPackageEntries?.(specifier);
+	if (entries !== void 0) return entries;
+	const entry = resolvers.optionalPackageEntry(specifier);
+	return entry ? [entry] : void 0;
+}
+function readRuntimeManifest(manifestPath) {
+	const current = fs.existsSync(manifestPath) ? fs.readFileSync(manifestPath, "utf8") : void 0;
+	if (current === void 0) return {
+		current,
+		manifest: {
+			name: RUNTIME_PACKAGE_NAME,
+			private: true
+		}
+	};
+	const parsed = JSON.parse(current);
+	if (!isRecord$1(parsed)) throw new Error(`Po runtime package manifest at ${manifestPath} must be a JSON object.`);
+	return {
+		current,
+		manifest: parsed
+	};
+}
+/** Names the runtime manifest already declares: what earlier runs, from any root, installed there. */
+function declaredRuntimePackages(runtimeDirectory) {
+	const manifestPath = path.join(runtimeDirectory, PACKAGE_MANIFEST);
+	if (!fs.existsSync(manifestPath)) return /* @__PURE__ */ new Set();
+	return new Set(Object.keys(recordValue(readRuntimeManifest(manifestPath).manifest.dependencies)));
+}
+/**
+* Adds a package set and the patched transitive policy to the shared runtime manifest.
+*
+* `targets` pins names to exact versions or `workspace:*`. `catalogWorkspaces` maps each
+* staged catalogue archive's name to its directory relative to the runtime; the manifest
+* lists exactly those directories as its `workspaces`, so a catalogue package's dependency
+* on another one links the staged copy instead of reaching the registry. Both `overrides` and
+* `pnpm.overrides` are written; upm reads both.
+* With `exact`, declared names outside `sources` are dropped instead of kept.
+*/
+function ensureManagedPackageManifest(runtimeDirectory, sources, targets = /* @__PURE__ */ new Map(), catalogWorkspaces = {}, exact = false) {
+	const manifestPath = path.join(runtimeDirectory, PACKAGE_MANIFEST);
+	const { current, manifest } = readRuntimeManifest(manifestPath);
+	const declared = recordValue(manifest.dependencies);
+	const sourceNames = new Set(sources.map(packageName));
+	const dependencies = exact ? Object.fromEntries(Object.entries(declared).filter(([name]) => sourceNames.has(name))) : declared;
+	for (const [name, declared] of Object.entries(dependencies)) if (Object.hasOwn(catalogWorkspaces, name)) dependencies[name] = CATALOG_WORKSPACE_TARGET;
+	else if (typeof declared === "string" && (declared.startsWith(FILE_SPECIFIER_PREFIX) || declared.startsWith(WORKSPACE_SPECIFIER_PREFIX))) dependencies[name] = UNPINNED_PACKAGE_RANGE;
+	for (const source of sources) {
+		const name = packageName(source);
+		const target = targets.get(name);
+		if (target !== void 0) dependencies[name] = target;
+		else if (!Object.hasOwn(dependencies, name)) dependencies[name] = UNPINNED_PACKAGE_RANGE;
+	}
+	manifest.dependencies = dependencies;
+	const workspaces = Object.values(catalogWorkspaces).sort();
+	if (workspaces.length > 0) manifest.workspaces = workspaces;
+	else delete manifest.workspaces;
+	manifest.overrides = {
+		...withoutCatalogOverrides(withoutConflictingTransitiveOverrides(manifest.overrides)),
+		...SAFE_TRANSITIVE_OVERRIDES
+	};
+	const pnpm = recordValue(manifest.pnpm);
+	pnpm.overrides = {
+		...withoutCatalogOverrides(withoutConflictingTransitiveOverrides(pnpm.overrides)),
+		...SAFE_TRANSITIVE_OVERRIDES
+	};
+	manifest.pnpm = pnpm;
+	const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
+	if (serialized === current) return false;
+	fs.mkdirSync(runtimeDirectory, { recursive: true });
+	writeFileAtomic(manifestPath, serialized);
+	return true;
+}
+/** Finds required npm packages selected by defaults and active layers that Po cannot resolve. */
+function missingLayerPackageSpecifiers(config, layers, resolvers) {
+	return configuredPackageSpecifiers(config, layers).filter((specifier) => resolvePackageEntries(resolvers, specifier) === void 0);
+}
+/** Whether `root`'s own node_modules chain holds the package, walked the way Node looks it up from `root`. */
+function ownsPackage(name, root) {
+	for (let directory = path.resolve(root);; directory = path.dirname(directory)) {
+		if (fs.existsSync(path.join(directory, NODE_MODULES, name, PACKAGE_MANIFEST))) return true;
+		if (path.dirname(directory) === directory) return false;
+	}
+}
+/**
+* The required npm packages the default and the given layers name that `root` does not get
+* from its own node_modules chain: what the shared runtime provides for it, whether it does so
+* already or not yet. Sync declares exactly these, over every root, in the runtime manifest; a
+* name the runtime already provides still counts, or the next exact manifest would drop it.
+*/
+function runtimeLayerPackageSpecifiers(config, layers, root) {
+	return configuredPackageSpecifiers(config, layers).filter((specifier) => !ownsPackage(splitPackageSpecifier(specifier).name, root));
+}
+function packageName(source) {
+	const specifier = source.startsWith(NPM_SOURCE_PREFIX) ? source.slice(4) : source;
+	if (specifier.startsWith("@")) {
+		const slash = specifier.indexOf("/");
+		const version = slash === -1 ? -1 : specifier.indexOf("@", slash);
+		return version === -1 ? specifier : specifier.slice(0, version);
+	}
+	const version = specifier.indexOf("@");
+	return version === -1 ? specifier : specifier.slice(0, version);
+}
+const EMPTY_CATALOG = {
+	packages: /* @__PURE__ */ new Map(),
+	install: []
+};
+function stringList(value) {
+	if (!Array.isArray(value)) return void 0;
+	const strings = value.filter((item) => typeof item === "string");
+	return strings.length === value.length ? strings : void 0;
+}
+function defaultBundledCatalogPath() {
+	try {
+		return path.join(poPackageRoot(), ...BUNDLED_CATALOG_SEGMENTS);
+	} catch {
+		return;
+	}
+}
+/**
+* The first catalogue present: `PO_PACKAGE_CATALOG` (desktop's archives), then the one
+* a release bundles into the CLI. With neither, the runtime installs only what roots name.
+*/
+function packageCatalogPath(environment) {
+	const configured = environment[PACKAGE_CATALOG_ENV]?.trim();
+	if (configured) return configured;
+	const bundledCatalogPath = defaultBundledCatalogPath();
+	return bundledCatalogPath !== void 0 && fs.existsSync(bundledCatalogPath) ? bundledCatalogPath : void 0;
+}
+function readPackageCatalog(manifestPath) {
+	if (!manifestPath) return EMPTY_CATALOG;
+	const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+	if (!isRecord$1(parsed) || parsed.version !== 1 || !isRecord$1(parsed.packages)) throw new Error(`Unsupported Po package catalog: ${manifestPath}`);
+	const packages = /* @__PURE__ */ new Map();
+	for (const [name, value] of Object.entries(parsed.packages)) {
+		if (!isRecord$1(value) || !Array.isArray(value.dependencies) || value.archive !== void 0 && typeof value.archive !== "string" || value.version !== void 0 && typeof value.version !== "string" || value.archive === void 0 && value.version === void 0) throw new Error(`Invalid package entry for ${name} in ${manifestPath}`);
+		const dependencies = stringList(value.dependencies);
+		if (!dependencies) throw new Error(`Invalid dependencies for ${name} in ${manifestPath}`);
+		const version = typeof value.version === "string" ? value.version : void 0;
+		if (typeof value.archive !== "string") {
+			packages.set(name, {
+				version,
+				dependencies
+			});
+			continue;
+		}
+		const archive = path.resolve(path.dirname(manifestPath), value.archive);
+		if (!fs.existsSync(archive)) throw new Error(`Po package catalog archive is missing: ${archive}`);
+		packages.set(name, {
+			archive,
+			version,
+			dependencies
+		});
+	}
+	const install = parsed.install === void 0 ? [] : stringList(parsed.install);
+	if (!install) throw new Error(`Invalid install list in ${manifestPath}`);
+	const unknown = install.filter((name) => !packages.has(name));
+	if (unknown.length > 0) throw new Error(`Po package catalog installs unlisted package(s): ${unknown.join(", ")}`);
+	return {
+		packages,
+		install
+	};
+}
+/**
+* The catalogue's `install` list as exact `name@version` specifiers for
+* `EnsureLayerPackagesOptions.specifiers`; empty when no catalogue is present.
+*/
+function catalogInstallSpecifiers(environment = process.env) {
+	const catalog = readPackageCatalog(packageCatalogPath(environment));
+	return catalog.install.map((name) => {
+		const version = catalog.packages.get(name)?.version;
+		return version ? `${name}@${version}` : name;
+	});
+}
+/**
+* The installed package roots of the catalogue's `install` list, resolved the way a root
+* resolves a bare name (its own node_modules, then the shared runtime). The global web build
+* covers them, so every first-party plugin has a slot; a name not installed yet is left out.
+*/
+function catalogPackageRoots(globalRoot, environment = process.env) {
+	const roots = [];
+	for (const name of readPackageCatalog(packageCatalogPath(environment)).install) {
+		const manifest = consumerPackageEntry(`${name}/${PACKAGE_MANIFEST}`, globalRoot, environment);
+		if (manifest !== void 0) roots.push(path.dirname(fs.realpathSync(manifest)));
+	}
+	return roots;
+}
+/** SHA-256 of the catalogue file in use, or `none` when no catalogue is present. */
+function packageCatalogHash(environment = process.env) {
+	const catalogPath = packageCatalogPath(environment);
+	if (!catalogPath) return "none";
+	return crypto.createHash("sha256").update(fs.readFileSync(catalogPath)).digest("hex");
+}
+/** Exact target per catalogue name: its staged workspace for an archive, else its registry version. */
+function catalogTargets(catalog) {
+	return new Map([...catalog.packages].flatMap(([name, entry]) => {
+		if (entry.archive !== void 0) return [[name, CATALOG_WORKSPACE_TARGET]];
+		return entry.version !== void 0 ? [[name, entry.version]] : [];
+	}));
+}
+const TAR_BLOCK_SIZE = 512;
+const TAR_EXECUTABLE_BITS = 73;
+function tarString(block, start, length) {
+	const field = block.subarray(start, start + length);
+	const end = field.indexOf(0);
+	return field.subarray(0, end === -1 ? field.length : end).toString("utf8");
+}
+function tarNumber(block, start, length) {
+	const field = block.subarray(start, start + length);
+	if ((field[0] & 128) !== 0) return field.subarray(1).reduce((value, byte) => value * 256 + byte, field[0] & 127);
+	const text = tarString(block, start, length).trim();
+	return text === "" ? 0 : Number.parseInt(text, 8);
+}
+/** The `path` record of a pax extended header, if it has one. */
+function paxPath(data) {
+	let found;
+	let offset = 0;
+	while (offset < data.length) {
+		const space = data.indexOf(32, offset);
+		if (space === -1) break;
+		const length = Number.parseInt(data.subarray(offset, space).toString("utf8"), 10);
+		if (!Number.isFinite(length) || length <= 0) break;
+		const record = data.subarray(space + 1, offset + length - 1).toString("utf8");
+		const separator = record.indexOf("=");
+		if (record.slice(0, separator) === "path") found = record.slice(separator + 1);
+		offset += length;
+	}
+	return found;
+}
+/**
+* Unpacks a gzipped npm package archive into `destination`, dropping the archive's top
+* directory (`package/`) as npm does. Only files and directories are written: npm package
+* archives carry no links, and an entry that would land outside `destination` is refused.
+*/
+function extractPackageArchive(archive, destination) {
+	const data = zlib.gunzipSync(fs.readFileSync(archive));
+	let offset = 0;
+	let nextPath;
+	while (offset + TAR_BLOCK_SIZE <= data.length) {
+		const header = data.subarray(offset, offset + TAR_BLOCK_SIZE);
+		if (header.every((byte) => byte === 0)) break;
+		const size = tarNumber(header, 124, 12);
+		const type = String.fromCharCode(header[156]);
+		const body = data.subarray(offset + TAR_BLOCK_SIZE, offset + TAR_BLOCK_SIZE + size);
+		offset += TAR_BLOCK_SIZE + Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+		if (type === "x" || type === "L") {
+			nextPath = type === "x" ? paxPath(body) ?? nextPath : tarString(body, 0, body.length);
+			continue;
+		}
+		if (type === "g") continue;
+		const prefix = tarString(header, 345, 155);
+		const name = nextPath ?? (prefix ? `${prefix}/${tarString(header, 0, 100)}` : tarString(header, 0, 100));
+		nextPath = void 0;
+		if (type !== "0" && type !== "\0" && type !== "5") continue;
+		const relative = name.split("/").slice(1).join("/");
+		if (relative === "") continue;
+		const target = path.resolve(destination, relative);
+		if (!target.startsWith(`${destination}${path.sep}`)) throw new Error(`Po package catalog archive ${archive} has an entry outside the package: ${name}`);
+		if (type === "5") {
+			fs.mkdirSync(target, { recursive: true });
+			continue;
+		}
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		const executable = (tarNumber(header, 100, 8) & TAR_EXECUTABLE_BITS) !== 0;
+		fs.writeFileSync(target, body, { mode: executable ? 493 : 420 });
+	}
+}
+/** Dependency fields of a staged manifest that may name another catalogue package. */
+const STAGED_DEPENDENCY_FIELDS = [
+	"dependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+/**
+* Unpacks one catalogue archive into `<runtime>/catalog/<hash>` and returns that directory
+* relative to the runtime, with the catalogue names its manifest depends on.
+*
+* upm only installs a package from a directory as a workspace: a `file:` archive takes its own
+* dependencies from the registry, so one catalogue archive could not depend on another. In the
+* staged manifest every dependency on another catalogue archive becomes `workspace:*`, so the
+* catalogue's copy wins whatever range the package declared, and `devDependencies`, which a
+* workspace would otherwise install, are dropped. The hash covers the archive bytes and the
+* catalogue's archive names, everything that rewrite reads, so a staged directory is reused.
+*/
+function stageCatalogArchive(runtimeDirectory, archive, archiveNames) {
+	const hash = crypto.createHash("sha256").update(fs.readFileSync(archive)).update(`\0${[...archiveNames].sort().join("\n")}`).digest("hex");
+	const relative = `${CATALOG_STAGING_DIRECTORY}/${hash}`;
+	const directory = path.join(runtimeDirectory, CATALOG_STAGING_DIRECTORY, hash);
+	const stagedManifest = path.join(directory, PACKAGE_MANIFEST);
+	if (!fs.existsSync(stagedManifest)) {
+		const temporary = `${directory}.${String(process.pid)}.${crypto.randomUUID()}.tmp`;
+		try {
+			extractPackageArchive(archive, temporary);
+			const manifestPath = path.join(temporary, PACKAGE_MANIFEST);
+			if (!fs.existsSync(manifestPath)) throw new Error(`Po package catalog archive has no package.json: ${archive}`);
+			const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+			if (!isRecord$1(manifest)) throw new Error(`Po package catalog archive has an invalid package.json: ${archive}`);
+			delete manifest.devDependencies;
+			for (const field of STAGED_DEPENDENCY_FIELDS) {
+				if (!isRecord$1(manifest[field])) continue;
+				const declared = { ...manifest[field] };
+				for (const name of Object.keys(declared)) if (archiveNames.has(name)) declared[name] = CATALOG_WORKSPACE_TARGET;
+				manifest[field] = declared;
+			}
+			fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+			try {
+				fs.renameSync(temporary, directory);
+			} catch (error) {
+				if (!fs.existsSync(stagedManifest)) throw error;
+			}
+		} finally {
+			fs.rmSync(temporary, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+	const staged = recordValue(JSON.parse(fs.readFileSync(stagedManifest, "utf8")));
+	return {
+		relative,
+		dependencies: STAGED_DEPENDENCY_FIELDS.flatMap((field) => Object.keys(recordValue(staged[field]))).filter((name) => archiveNames.has(name))
+	};
+}
+/**
+* Stages the archive of every named catalogue package and of every catalogue package those
+* name in turn, since a staged manifest's `workspace:*` needs that workspace present. The
+* result, name to staged directory, feeds `ensureManagedPackageManifest`.
+*/
+function stageCatalogArchives(runtimeDirectory, catalog, names) {
+	const archiveNames = new Set([...catalog.packages].flatMap(([name, entry]) => entry.archive === void 0 ? [] : [name]));
+	const staged = {};
+	const pending = [...names].filter((name) => archiveNames.has(name));
+	while (pending.length > 0) {
+		const name = pending.shift();
+		if (Object.hasOwn(staged, name)) continue;
+		const { relative, dependencies } = stageCatalogArchive(runtimeDirectory, catalog.packages.get(name).archive, archiveNames);
+		staged[name] = relative;
+		pending.push(...dependencies);
+	}
+	return staged;
+}
+/**
+* Removes staged archives the runtime manifest no longer lists as workspaces, and returns their
+* folder names. An install never calls this: a running server imports from these folders (its
+* `.po-snapshots` live there), so sync prunes them under the same gate as the runtime store.
+*/
+function pruneStagedCatalogArchives(runtimeDirectory) {
+	const stagingDirectory = path.join(runtimeDirectory, CATALOG_STAGING_DIRECTORY);
+	if (!fs.existsSync(stagingDirectory)) return [];
+	const { manifest } = readRuntimeManifest(path.join(runtimeDirectory, PACKAGE_MANIFEST));
+	const kept = new Set((stringList(manifest.workspaces) ?? []).map((relative) => path.basename(relative)));
+	return fs.readdirSync(stagingDirectory).filter((entry) => !kept.has(entry)).map((entry) => {
+		fs.rmSync(path.join(stagingDirectory, entry), {
+			recursive: true,
+			force: true
+		});
+		return entry;
+	});
+}
+/** Splits `name@version` (scoped or not); the version is absent for a bare name or subpath. */
+function splitVersionedSpecifier(specifier) {
+	const separator = specifier.indexOf("@", specifier.startsWith("@") ? 1 : 0);
+	if (separator === -1) return { name: splitPackageSpecifier(specifier).name };
+	return {
+		name: specifier.slice(0, separator),
+		version: specifier.slice(separator + 1)
+	};
+}
+function npmSources(specifiers, catalog, targets, includeCatalogDependencies = false) {
+	const names = [...new Set(specifiers.map((specifier) => splitPackageSpecifier(specifier).name))];
+	if (includeCatalogDependencies) {
+		for (let index = 0; index < names.length; index += 1) for (const dependency of catalog.packages.get(names[index])?.dependencies ?? []) if (!names.includes(dependency)) names.push(dependency);
+	}
+	return names.map((name) => {
+		const target = targets.get(name);
+		return `${NPM_SOURCE_PREFIX}${name}${target ? `@${target}` : ""}`;
+	});
+}
+function pluralize(count, noun) {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+/** Version of a package inside the shared runtime, absent when Po did not install it there. */
+function managedPackageVersion(runtimeDirectory, name) {
+	const manifestPath = path.join(runtimeDirectory, NODE_MODULES, name, PACKAGE_MANIFEST);
+	if (!fs.existsSync(manifestPath)) return void 0;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+		return isRecord$1(parsed) && typeof parsed.version === "string" ? parsed.version : void 0;
+	} catch {
+		return;
+	}
+}
+function errorCode(error) {
+	return typeof error === "object" && error !== null ? error.code : void 0;
+}
+/**
+* Installs the runtime, and when the registry cannot be reached installs it again offline:
+* an unchanged lockfile whose packages the store already holds needs no network.
+*/
+async function installWithOfflineRetry(install, options, onProgress) {
+	try {
+		await install(options);
+	} catch (error) {
+		const code = errorCode(error);
+		if (typeof code !== "string" || !NETWORK_FAILURE_CODES.has(code)) throw error;
+		onProgress?.(`the registry is unreachable (${code}); installing offline from the store`);
+		try {
+			await install({
+				...options,
+				preferOffline: false,
+				offline: true
+			});
+		} catch {
+			throw error;
+		}
+	}
+}
+/**
+* Compares every package sync installed against the registry.
+*
+* Only the shared runtime is consulted: a package that resolves from the
+* repository's own modules is not sync's to move, and a package that is not
+* installed yet is already covered by the missing-package path.
+*/
+async function resolveUpdates(runtimeDirectory, sources, publishedVersion, onProgress) {
+	const managed = sources.map((source) => ({
+		name: packageName(source),
+		from: managedPackageVersion(runtimeDirectory, packageName(source))
+	})).filter((entry) => entry.from !== void 0);
+	const checked = await Promise.all(managed.map(async (entry) => {
+		try {
+			return {
+				...entry,
+				to: await publishedVersion(entry.name)
+			};
+		} catch (error) {
+			return {
+				...entry,
+				failure: (error instanceof Error ? error.message : String(error)).split("\n")[0]
+			};
+		}
+	}));
+	const updated = [];
+	const unchecked = [];
+	for (const entry of checked) {
+		if (entry.to === void 0) {
+			unchecked.push(entry.name);
+			onProgress?.(`kept ${entry.name} ${entry.from}: ${entry.failure ?? "no published version"}`);
+			continue;
+		}
+		if (entry.to === entry.from) continue;
+		updated.push({
+			name: entry.name,
+			from: entry.from,
+			to: entry.to
+		});
+		onProgress?.(`${entry.name} ${entry.from} -> ${entry.to}`);
+	}
+	return {
+		updated,
+		unchecked
+	};
+}
+/**
+* Installs the selected layer packages a root cannot resolve into the shared runtime,
+* `<po home>/runtime`, and verifies they now resolve.
+*
+* The runtime manifest is the union of what every root asked for. A root adds the
+* packages it is missing; a package it already resolves from its own node_modules stays
+* out unless an earlier run put it there. One name has one version: an exact target
+* (a sync update, a catalog archive or registry pin) replaces the declared range, last
+* writer wins, and a plain `*` never replaces a range already declared.
+*
+* `specifiers` and `exactManifest` only add behaviour: without them, and without a
+* catalogue, a run behaves as it always has.
+*/
+async function ensureLayerPackages(options, dependencies = {}) {
+	const environment = options.environment ?? process.env;
+	const homeDirectory = environment.HOME ?? os.homedir();
+	const poHome = poHomeDirectory(homeDirectory, environment);
+	const runtimeDirectory = poRuntimeDirectory(homeDirectory, environment);
+	const resolvers = dependencies.resolvers ?? createLayerResolvers(options.repoRoot, environment);
+	const configured = configuredPackageSpecifiers(options.config, options.layers);
+	const missing = configured.filter((specifier) => resolvePackageEntries(resolvers, specifier) === void 0);
+	const declared = declaredRuntimePackages(runtimeDirectory);
+	const managed = configured.filter((specifier) => missing.includes(specifier) || declared.has(splitPackageSpecifier(specifier).name));
+	const requested = (options.specifiers ?? []).map(splitVersionedSpecifier);
+	if (managed.length === 0 && requested.length === 0 && options.exactManifest !== true) return {
+		installed: [],
+		updated: [],
+		unchecked: []
+	};
+	const catalog = readPackageCatalog(packageCatalogPath(environment));
+	const pins = catalogTargets(catalog);
+	for (const { name, version } of requested) if (version !== void 0 && catalog.packages.get(name)?.archive === void 0) pins.set(name, version);
+	const requestedMissing = requested.filter(({ name, version }) => {
+		const installed = managedPackageVersion(runtimeDirectory, name);
+		const entry = catalog.packages.get(name);
+		const expected = entry?.archive === void 0 ? version : entry.version;
+		return installed === void 0 || expected !== void 0 && installed !== expected;
+	}).map(({ name }) => name);
+	const missingSources = npmSources([...missing, ...requestedMissing], catalog, pins);
+	const sources = npmSources([...managed, ...requested.map(({ name }) => name)], catalog, pins, true);
+	const missingCount = missing.length + requestedMissing.length;
+	const fixedNames = /* @__PURE__ */ new Set([...catalog.packages.keys(), ...requested.filter(({ version }) => version !== void 0).map(({ name }) => name)]);
+	const registrySources = sources.filter((source) => !fixedNames.has(packageName(source)));
+	const { updated, unchecked } = options.refresh ? await resolveUpdates(runtimeDirectory, registrySources, dependencies.publishedVersion ?? ((name) => resolveNewest(name, {
+		dir: runtimeDirectory,
+		poHome
+	})), options.onProgress) : {
+		updated: [],
+		unchecked: []
+	};
+	const targets = new Map(sources.flatMap((source) => {
+		const target = pins.get(packageName(source));
+		return target ? [[packageName(source), target]] : [];
+	}));
+	for (const update of updated) targets.set(update.name, update.to);
+	const manifestChanged = ensureManagedPackageManifest(runtimeDirectory, sources, targets, stageCatalogArchives(runtimeDirectory, catalog, /* @__PURE__ */ new Set([...sources.map(packageName), ...options.exactManifest === true ? [] : declared])), options.exactManifest === true);
+	if (missingCount === 0 && !manifestChanged) return {
+		installed: [],
+		updated: [],
+		unchecked
+	};
+	options.onProgress?.(`installing ${updated.length > 0 ? pluralize(updated.length, "update") : missingCount > 0 ? pluralize(missingCount, "missing package") : "the package manifest"}`);
+	try {
+		await installWithOfflineRetry(dependencies.install ?? installRuntimePackages, {
+			dir: runtimeDirectory,
+			poHome,
+			preferOffline: options.refresh !== true,
+			log: (message, level) => {
+				if (level === "warn") options.onProgress?.(message);
+			}
+		}, options.onProgress);
+	} catch (error) {
+		throw new Error(`Failed to reconcile Po layer package(s): ${(manifestChanged ? sources : missingSources).join(", ")}`, { cause: error });
+	}
+	const unresolved = missing.filter((specifier) => !resolvePackageEntries(resolvers, specifier)?.length);
+	if (unresolved.length > 0) throw new Error(`Installed Po layer package(s) did not expose the configured Pi extension: ${unresolved.join(", ")}`);
+	return {
+		installed: missingSources,
+		updated,
+		unchecked
+	};
+}
+//#endregion
+export { SAFE_TRANSITIVE_OVERRIDES, catalogInstallSpecifiers, catalogPackageRoots, ensureLayerPackages, ensureManagedPackageManifest, missingLayerPackageSpecifiers, packageCatalogHash, pruneStagedCatalogArchives, runtimeLayerPackageSpecifiers };
+
+//# sourceMappingURL=index.mjs.map