@icebreakers/monorepo-templates 2.0.7 → 2.2.0

package/dist/index.mjs

@@ -1,9 +1,14 @@
-import { a as isGitignoreFile, c as toWorkspaceGitignorePath, d as packageDir, f as skeletonDir, h as getAssetTargets$1, i as shouldSkipTemplatePath, l as templateChoices$1, m as assetTargets$1, n as sanitizePublishedWorkspaceContent, o as toPublishGitignorePath, p as templatesDir, r as createTemplateCopyFilter, s as toWorkspaceAssetPath, t as prepareAssets, u as assetsDir } from "./prepare-BapI8ioj.mjs";
+import { a as isGitignoreFile, c as toWorkspaceGitignorePath, d as packageDir, f as skeletonDir, h as getAssetTargets$1, i as shouldSkipTemplatePath, l as templateChoices$1, m as assetTargets$1, n as sanitizePublishedWorkspaceContent, o as toPublishGitignorePath, p as templatesDir, r as createTemplateCopyFilter, s as toWorkspaceAssetPath, t as prepareAssets, u as assetsDir } from "./prepare-BYNSxvoB.mjs";
 import path from "node:path";
 import fs, { access, open, readFile, rm } from "node:fs/promises";
+import { Buffer } from "node:buffer";
+import { createHash, randomUUID } from "node:crypto";
+import process from "node:process";
 import exec from "nanoexec";
+import { isDeepStrictEqual } from "node:util";
 import checkbox from "@inquirer/checkbox";
 import input from "@inquirer/input";
+import password from "@inquirer/password";
 import select from "@inquirer/select";
 import { Command, program } from "commander";
 //#region src/package-manager/read.ts
@@ -38,11 +43,12 @@ async function acquireLock(lockPath) {
 		throw error;
 	}
 }
-async function isPrepared() {
+/** Inspect asset readiness without acquiring locks or writing generated files. */
+async function areTemplateAssetsPrepared() {
 	const checks = [
 		path.join(assetsDir, "AGENTS.md"),
 		path.join(assetsDir, "LICENSE"),
-		path.join(templatesDir, "tsdown")
+		...templateChoices$1.map((template) => path.join(templatesDir, template.source))
 	];
 	if (!(await Promise.all(checks.map(pathExists))).every(Boolean)) return false;
 	const sourceRoot = path.resolve(packageDir, "..", "..");
@@ -97,13 +103,13 @@ async function isPrepared() {
 async function waitForPrepared() {
 	const deadline = Date.now() + lockTimeoutMs;
 	while (Date.now() < deadline) {
-		if (await isPrepared()) return true;
+		if (await areTemplateAssetsPrepared()) return true;
 		await new Promise((resolve) => setTimeout(resolve, lockPollIntervalMs));
 	}
 	return false;
 }
 async function runEnsure() {
-	if (await isPrepared()) return;
+	if (await areTemplateAssetsPrepared()) return;
 	const lockPath = path.join(packageDir, lockFileName);
 	let lockHandle = await acquireLock(lockPath);
 	if (!lockHandle) {
@@ -134,91 +140,373 @@ async function getWorkspacePackageManager() {
 	return readPackageManagerFromManifest(path.join(assetsDir, "package.json"));
 }
 //#endregion
-//#region src/scaffold.ts
-async function isEmptyDir(dir) {
+//#region src/instances/paths.ts
+const templateRegistryPath = ".repoctl/template-instances.json";
+const templateBaselineDirectory = ".repoctl/template-baselines";
+function portableRelativePath(value) {
+	if (!value || value.includes("\\") || value.includes("\0") || path.isAbsolute(value) || /^[a-z]:/iu.test(value) || value.split("/").some((part) => !part || part === "." || part === "..")) throw new Error(`Unsafe template instance path: ${value}`);
+	return value;
+}
+/** Reject links in every existing ancestor, including a missing leaf's parents. */
+async function safeInstancePath(workspaceDir, relativePath) {
+	const relative = portableRelativePath(relativePath);
+	let current = await fs.realpath(workspaceDir);
+	for (const part of relative.split("/")) {
+		current = path.join(current, part);
+		try {
+			if ((await fs.lstat(current)).isSymbolicLink()) throw new Error(`Symlinks are not supported in template instance paths: ${relative}`);
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+	}
+	return current;
+}
+function instanceRelativePath(workspaceDir, targetDir) {
+	const relative = path.relative(path.resolve(workspaceDir), path.resolve(targetDir)).split(path.sep).join("/");
+	portableRelativePath(relative);
+	if (relative === ".repoctl" || relative.startsWith(".repoctl/")) throw new Error("Template instances cannot own the workspace metadata directory.");
+	return relative;
+}
+async function exists(file) {
 	try {
-		return (await fs.readdir(dir)).length === 0;
+		await fs.lstat(file);
+		return true;
 	} catch (error) {
-		if (error && error.code === "ENOENT") return true;
+		if (error.code === "ENOENT") return false;
 		throw error;
 	}
 }
-async function prepareTargetDir(dir, options = {}) {
-	if (await isEmptyDir(dir)) {
-		await fs.mkdir(dir, { recursive: true });
-		return;
+//#endregion
+//#region src/parameters/schema.ts
+const parameterName = /^[a-z]\w*$/u;
+const isParameterRecord = (value) => value !== null && typeof value === "object" && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+function parameterError(path, reason) {
+	throw new Error(`Template parameter ${path}: ${reason}`);
+}
+function parameterValueMatches(definition, value) {
+	return definition.type === "boolean" ? typeof value === "boolean" : typeof value === "string" && value.length <= 65536 && (definition.type !== "enum" || definition.options.includes(value));
+}
+function validateTemplateParameterSchema(value) {
+	if (!isParameterRecord(value) || Object.keys(value).length > 64) parameterError("parameters", "expected an object containing at most 64 definitions");
+	for (const [name, item] of Object.entries(value)) {
+		const field = `parameters.${name}`;
+		if (!parameterName.test(name) || [
+			"constructor",
+			"prototype",
+			"__proto__"
+		].includes(name)) parameterError(field, "use a portable parameter name");
+		if (!isParameterRecord(item) || ![
+			"string",
+			"boolean",
+			"enum"
+		].includes(String(item["type"]))) parameterError(field, "expected a string, boolean or enum definition");
+		const allowed = [
+			"type",
+			"description",
+			"required",
+			"sensitive",
+			"default",
+			...item["type"] === "enum" ? ["options"] : []
+		];
+		if (Object.keys(item).some((key) => !allowed.includes(key))) parameterError(field, "unsupported definition field");
+		if (item["description"] !== void 0 && typeof item["description"] !== "string" || item["required"] !== void 0 && typeof item["required"] !== "boolean" || item["sensitive"] !== void 0 && typeof item["sensitive"] !== "boolean") parameterError(field, "invalid description, required or sensitive declaration");
+		if (item["sensitive"] === true && (item["type"] !== "string" || Object.hasOwn(item, "default"))) parameterError(field, "sensitive inputs must be strings without stored defaults");
+		if (item["type"] === "enum" && (!Array.isArray(item["options"]) || !item["options"].length || item["options"].length > 100 || item["options"].some((option) => typeof option !== "string" || !option.length || option.length > 1024) || new Set(item["options"]).size !== item["options"].length)) parameterError(field, "enum options must be unique nonempty strings");
+		if (Object.hasOwn(item, "default") && !parameterValueMatches(item, item["default"])) parameterError(`${field}.default`, "default does not satisfy its declared type");
 	}
-	if (!options.force) throw new Error(`Target directory ${dir} is not empty. Pass --force to overwrite.`);
-	await fs.rm(dir, {
-		recursive: true,
-		force: true
-	});
-	await fs.mkdir(dir, { recursive: true });
 }
-async function copyDirContents(sourceDir, targetDir, options = {}) {
-	const rootDir = options.rootDir ?? sourceDir;
-	const filter = options.filter ?? ((src) => !shouldSkipTemplatePath(rootDir, src));
-	const renameEntry = options.renameEntry ?? toWorkspaceGitignorePath;
-	const skipRoot = new Set(options.skipRootBasenames ?? []);
-	await fs.mkdir(targetDir, { recursive: true });
-	const entries = await fs.readdir(sourceDir, { withFileTypes: true });
-	for (const entry of entries) {
-		if (sourceDir === rootDir && skipRoot.has(entry.name)) continue;
-		const from = path.join(sourceDir, entry.name);
-		if (!filter(from)) continue;
-		const targetName = renameEntry(entry.name);
-		const to = path.join(targetDir, targetName);
-		if (entry.isDirectory()) {
-			const nestedOptions = {
-				rootDir,
-				filter,
-				renameEntry
-			};
-			if (options.skipRootBasenames) nestedOptions.skipRootBasenames = options.skipRootBasenames;
-			await copyDirContents(from, to, { ...nestedOptions });
-			continue;
+//#endregion
+//#region src/instances/remote.ts
+/** Registry identities contain reproducible public coordinates, never authentication settings. */
+function validateRemoteInstanceSource(source, exactVersion) {
+	const remote = source.remote;
+	if (source.kind !== "remote") {
+		if (remote !== void 0) throw new Error("Only remote template sources can contain remote coordinates.");
+		return;
+	}
+	if (!remote || !/^[a-f0-9]{64}$/u.test(source.digest ?? "") || typeof remote.integrity !== "string" || !/^(?:sha512|sha384|sha256|sha1)-[A-Za-z0-9+/]+={0,2}(?:\s+(?:sha512|sha384|sha256|sha1)-[A-Za-z0-9+/]+={0,2})*$/u.test(remote.integrity)) throw new Error("Remote template identity needs content digest and archive integrity.");
+	const fields = remote.kind === "npm" ? [
+		"kind",
+		"packageName",
+		"requestedVersion",
+		"version",
+		"registry",
+		"integrity"
+	] : [
+		"kind",
+		"repository",
+		"requestedRef",
+		"commit",
+		"integrity"
+	];
+	if (Object.keys(remote).some((field) => !fields.includes(field))) throw new Error("Remote template identity contains unsupported metadata.");
+	try {
+		if (remote.kind === "npm") {
+			const registry = new URL(remote.registry);
+			if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u.test(remote.packageName) || !exactVersion.test(remote.version) || remote.requestedVersion !== remote.version || !["https:", "http:"].includes(registry.protocol) || registry.username || registry.password || registry.search || registry.hash) throw new Error("Invalid npm identity.");
+			return;
 		}
-		if (entry.isSymbolicLink()) {
-			const link = await fs.readlink(from);
-			await fs.symlink(link, to);
-			continue;
+		if (remote.kind === "git") {
+			const repository = new URL(remote.repository);
+			if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(remote.commit) || !remote.requestedRef || /\s/u.test(remote.requestedRef) || ![
+				"https:",
+				"ssh:",
+				"file:"
+			].includes(repository.protocol) || repository.password || repository.username && !(repository.protocol === "ssh:" && repository.username === "git") || repository.search || repository.hash) throw new Error("Invalid Git identity.");
+			return;
 		}
-		await fs.cp(from, to);
+	} catch {
+		throw new Error("Remote template coordinates must identify an exact version or commit without credentials.");
 	}
+	throw new Error("Unknown remote template identity kind.");
 }
-function isDefaultTemplatesPath(sourceDir) {
-	const resolvedSource = path.resolve(sourceDir);
-	const resolvedTemplatesRoot = path.resolve(templatesDir);
-	return resolvedSource === resolvedTemplatesRoot || resolvedSource.startsWith(`${resolvedTemplatesRoot}${path.sep}`);
+//#endregion
+//#region src/instances/schema.ts
+const digestPattern = /^[a-f0-9]{64}$/u;
+const numericIdentifier = "(?:0|[1-9]\\d*)";
+const prereleaseIdentifier = "(?:0|[1-9]\\d*|\\d*[a-z-][\\da-z-]*)";
+const exactVersionPattern = new RegExp(`^${numericIdentifier}\\.${numericIdentifier}\\.${numericIdentifier}(?:-${prereleaseIdentifier}(?:\\.${prereleaseIdentifier})*)?(?:\\+[\\da-z-]+(?:\\.[\\da-z-]+)*)?$`, "iu");
+function isExactTemplateVersion(value) {
+	return exactVersionPattern.test(value);
 }
-async function scaffoldTemplate(options) {
-	const { sourceDir, targetDir, ensureTargetDir = true, filter, renameEntry, skipRootBasenames } = options;
-	if (isDefaultTemplatesPath(sourceDir)) await ensureTemplateAssetsPrepared();
-	if (ensureTargetDir) await fs.mkdir(targetDir, { recursive: true });
-	const copyOptions = { rootDir: sourceDir };
-	if (filter) copyOptions.filter = filter;
-	if (renameEntry) copyOptions.renameEntry = renameEntry;
-	if (skipRootBasenames) copyOptions.skipRootBasenames = skipRootBasenames;
-	await copyDirContents(sourceDir, targetDir, copyOptions);
+function normalizeTemplateExclusions(values) {
+	if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) throw new Error("Template exclusions must be relative file or directory paths.");
+	const result = [];
+	for (const input of values.map((value) => value.endsWith("/**") ? value.slice(0, -3) : value).sort()) {
+		portableRelativePath(input);
+		if (/[*?[\]{}]/u.test(input)) throw new Error("Template exclusions support exact files or directories, not arbitrary glob patterns.");
+		if (!result.some((parent) => input === parent || input.startsWith(`${parent}/`))) result.push(input);
+	}
+	return result;
 }
-async function scaffoldWorkspace(options) {
-	const { targetDir, templateKeys = [], assetsDir: assetsDir$1 = assetsDir, templatesDir: templatesDir$1 = templatesDir, includeAssets = true, targetMode = "prepare", force = false } = options;
-	if (includeAssets && path.resolve(assetsDir$1) === path.resolve(assetsDir) || templateKeys.length > 0 && path.resolve(templatesDir$1) === path.resolve(templatesDir)) await ensureTemplateAssetsPrepared();
-	if (targetMode === "prepare") await prepareTargetDir(targetDir, { force });
-	else if (targetMode === "ensure") await fs.mkdir(targetDir, { recursive: true });
-	if (includeAssets) await copyDirContents(assetsDir$1, targetDir, {
-		rootDir: assetsDir$1,
-		renameEntry: toWorkspaceAssetPath
+function onlyFields(value, fields) {
+	if (!value || typeof value !== "object" || Object.keys(value).some((key) => !fields.includes(key))) throw new Error("Unsupported fields in template instance metadata; arbitrary user data is not stored.");
+}
+function generationParameters(input = {}) {
+	if (Object.keys(input).some((key) => ![
+		"packageName",
+		"renameJson",
+		"templateValues",
+		"sensitiveParameters"
+	].includes(key)) || input.packageName !== void 0 && (typeof input.packageName !== "string" || !/^[@\w./-]+$/u.test(input.packageName)) || input.renameJson !== void 0 && typeof input.renameJson !== "boolean") throw new Error("Unsupported or invalid non-secret generation parameters.");
+	if (input.templateValues !== void 0 && (!isParameterRecord(input.templateValues) || Object.entries(input.templateValues).some(([key, value]) => !parameterName.test(key) || [
+		"constructor",
+		"prototype",
+		"__proto__"
+	].includes(key) || !["string", "boolean"].includes(typeof value)))) throw new Error("Template generation values must be validated non-secret strings or booleans.");
+	if (input.sensitiveParameters !== void 0 && (!Array.isArray(input.sensitiveParameters) || input.sensitiveParameters.some((key) => typeof key !== "string" || !parameterName.test(key) || Object.hasOwn(input.templateValues ?? {}, key)) || new Set(input.sensitiveParameters).size !== input.sensitiveParameters.length)) throw new Error("Sensitive generation parameters retain unique names only, never values.");
+	return {
+		...input.templateValues !== void 0 ? { templateValues: { ...input.templateValues } } : {},
+		...input.sensitiveParameters !== void 0 ? { sensitiveParameters: [...input.sensitiveParameters].sort() } : {},
+		...input.packageName !== void 0 ? { packageName: input.packageName } : {},
+		...input.renameJson !== void 0 ? { renameJson: input.renameJson } : {}
+	};
+}
+function validateInstance(instance) {
+	onlyFields(instance, [
+		"id",
+		"target",
+		"template",
+		"provenance",
+		"source",
+		"generator",
+		"parameters",
+		"baseline",
+		"excludedPaths"
+	]);
+	onlyFields(instance.generator, ["profile", "version"]);
+	onlyFields(instance.parameters, [
+		"packageName",
+		"renameJson",
+		"templateValues",
+		"sensitiveParameters"
+	]);
+	onlyFields(instance.source, [
+		"kind",
+		"templatePath",
+		"packageName",
+		"version",
+		"digest",
+		"remote"
+	]);
+	onlyFields(instance.baseline, [
+		"status",
+		"original",
+		"rendered",
+		"reason"
+	]);
+	if (!instance || !/^[a-f0-9]{24}$/u.test(instance.id) || typeof instance.template !== "string" || !instance.template || !["created", "linked"].includes(instance.provenance) || ![
+		"workspace-copy-v1",
+		"repo-new-v1",
+		"repo-new-parameters-v1"
+	].includes(instance.generator?.profile) || !exactVersionPattern.test(instance.generator.version)) throw new Error("Invalid template instance identity or generator.");
+	portableRelativePath(instance.target);
+	if (instance.target === ".repoctl" || instance.target.startsWith(".repoctl/")) throw new Error("Template instances cannot own metadata paths.");
+	generationParameters(instance.parameters);
+	if (instance.excludedPaths !== void 0 && JSON.stringify(normalizeTemplateExclusions(instance.excludedPaths)) !== JSON.stringify(instance.excludedPaths)) throw new Error("Template exclusions must use sorted, canonical non-overlapping paths.");
+	const source = instance.source;
+	if (source.kind !== "remote" || source.templatePath !== ".") portableRelativePath(source.templatePath);
+	validateRemoteInstanceSource(source, exactVersionPattern);
+	if (![
+		"package",
+		"snapshot",
+		"remote"
+	].includes(source.kind) || source.kind === "package" && (source.packageName !== "@icebreakers/monorepo-templates" || !exactVersionPattern.test(source.version ?? "")) || source.digest !== void 0 && !digestPattern.test(source.digest)) throw new Error("Template source must use an exact package version or immutable snapshot.");
+	if (instance.baseline.status === "available") {
+		if (!digestPattern.test(instance.baseline.original) || !digestPattern.test(instance.baseline.rendered) || source.digest !== instance.baseline.original) throw new Error("Invalid template instance baseline digests.");
+	} else if (instance.baseline.status !== "unverified" || instance.baseline.reason !== "source-unavailable") throw new Error("Invalid template instance baseline status.");
+}
+function parseRegistry(content) {
+	const registry = JSON.parse(content);
+	onlyFields(registry, ["schemaVersion", "instances"]);
+	if (registry?.schemaVersion !== 1 || !Array.isArray(registry.instances)) throw new Error("Unsupported template instance registry schema.");
+	const ids = /* @__PURE__ */ new Set();
+	const targets = /* @__PURE__ */ new Set();
+	for (const instance of registry.instances) {
+		validateInstance(instance);
+		if (ids.has(instance.id) || targets.has(instance.target)) throw new Error("Duplicate template instance identity or target in registry.");
+		if ([...targets].some((target) => target.startsWith(`${instance.target}/`) || instance.target.startsWith(`${target}/`))) throw new Error("Overlapping template instance targets in registry.");
+		ids.add(instance.id);
+		targets.add(instance.target);
+	}
+	return registry;
+}
+//#endregion
+//#region src/instances/snapshot.ts
+const ignoredDirectories = /* @__PURE__ */ new Set([".git", ".repoctl"]);
+function snapshotDigest(snapshot) {
+	return createHash("sha256").update(JSON.stringify(snapshot)).digest("hex");
+}
+function validateSnapshot(value) {
+	const snapshot = value;
+	if (snapshot?.schemaVersion !== 1 || !Array.isArray(snapshot.files) || !Array.isArray(snapshot.directories)) throw new Error("Invalid template baseline snapshot.");
+	const seen = /* @__PURE__ */ new Set();
+	let previous = "";
+	for (const directory of snapshot.directories) {
+		portableRelativePath(directory);
+		if (seen.has(directory) || directory < previous) throw new Error("Invalid or non-canonical template baseline directories.");
+		seen.add(directory);
+		previous = directory;
+	}
+	previous = "";
+	let bytes = 0;
+	for (const file of snapshot.files) {
+		portableRelativePath(file.path);
+		if (typeof file.content !== "string" || typeof file.executable !== "boolean" || Buffer.from(file.content, "base64").toString("base64") !== file.content || seen.has(file.path) || file.path < previous) throw new Error("Invalid or non-canonical template baseline files.");
+		seen.add(file.path);
+		previous = file.path;
+		bytes += Buffer.byteLength(file.content, "base64");
+		if (bytes > 33554432) throw new Error("Template baseline exceeds the supported snapshot size.");
+	}
+}
+/** Capture only template deliverables; never follow symbolic links or collect repository credentials. */
+async function captureTemplateSnapshot(directory) {
+	const rootStat = await fs.lstat(directory);
+	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error(`Template source must be a real directory: ${directory}`);
+	const snapshot = {
+		schemaVersion: 1,
+		files: [],
+		directories: []
+	};
+	let bytes = 0;
+	const visit = async (current) => {
+		for (const entry of await fs.readdir(current, { withFileTypes: true })) {
+			const file = path.join(current, entry.name);
+			if (ignoredDirectories.has(entry.name) || shouldSkipTemplatePath(directory, file)) continue;
+			if (entry.isSymbolicLink() || !entry.isDirectory() && !entry.isFile()) throw new Error(`Unsupported link or special file in template: ${path.relative(directory, file)}`);
+			if (entry.isDirectory()) {
+				snapshot.directories.push(portableRelativePath(path.relative(directory, file).split(path.sep).join("/")));
+				if (snapshot.directories.length >= 1e4) throw new Error("Template baseline exceeds the supported directory count.");
+				await visit(file);
+			} else {
+				const content = await fs.readFile(file);
+				bytes += content.byteLength;
+				if (bytes > 33554432 || snapshot.files.length >= 1e4) throw new Error("Template baseline exceeds the supported snapshot size.");
+				const relative = path.relative(directory, file).split(path.sep).join("/");
+				snapshot.files.push({
+					path: portableRelativePath(relative),
+					content: content.toString("base64"),
+					executable: ((await fs.stat(file)).mode & 73) !== 0
+				});
+			}
+		}
+	};
+	await visit(directory);
+	snapshot.files.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+	snapshot.directories.sort();
+	return snapshot;
+}
+function compareTemplateSnapshots(baseline, current) {
+	const entries = (snapshot) => new Map([...snapshot.files.map((file) => [file.path, JSON.stringify([file.content, file.executable])]), ...snapshot.directories.map((directory) => [directory, "directory"])]);
+	const before = entries(baseline);
+	const after = entries(current);
+	return [.../* @__PURE__ */ new Set([...before.keys(), ...after.keys()])].sort().flatMap((file) => {
+		if (before.get(file) === after.get(file)) return [];
+		return [{
+			path: file,
+			status: !before.has(file) ? "added" : !after.has(file) ? "deleted" : "modified"
+		}];
 	});
-	if (!templateKeys.length) return;
-	const selections = new Set(templateKeys);
-	for (const template of templateChoices$1) {
-		if (!selections.has(template.key)) continue;
-		await scaffoldTemplate({
-			sourceDir: path.join(templatesDir$1, template.source),
-			targetDir: path.join(targetDir, template.target)
+}
+async function writeTemplateSnapshot(snapshot, targetDir) {
+	validateSnapshot(snapshot);
+	await fs.mkdir(targetDir);
+	try {
+		for (const directory of snapshot.directories) await fs.mkdir(path.join(targetDir, ...directory.split("/")), { recursive: true });
+		for (const file of snapshot.files) {
+			const target = path.join(targetDir, ...file.path.split("/"));
+			await fs.mkdir(path.dirname(target), { recursive: true });
+			await fs.writeFile(target, Buffer.from(file.content, "base64"), {
+				flag: "wx",
+				mode: file.executable ? 493 : 420
+			});
+		}
+	} catch (error) {
+		await fs.rm(targetDir, {
+			recursive: true,
+			force: true
 		});
+		throw error;
+	}
+}
+//#endregion
+//#region src/instances/source.ts
+async function readTemplatePackageVersion(sourcePackageDir = packageDir) {
+	const stat = await fs.lstat(sourcePackageDir);
+	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Historical template package root must be a real directory, not a link.");
+	const manifestPath = await safeInstancePath(sourcePackageDir, "package.json");
+	const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+	if (manifest.name !== "@icebreakers/monorepo-templates" || !exactVersionPattern.test(manifest.version ?? "")) throw new Error("Historical source must be an extracted @icebreakers/monorepo-templates package with an exact version.");
+	return manifest.version;
+}
+async function prepareTemplateInstanceSource(sourceDir, historicalPackageDir) {
+	const sourcePackageDir = historicalPackageDir ?? packageDir;
+	if (historicalPackageDir) {
+		await readTemplatePackageVersion(historicalPackageDir);
+		const root = await fs.realpath(historicalPackageDir);
+		const lexical = path.resolve(sourceDir).startsWith(`${path.resolve(historicalPackageDir)}${path.sep}`) ? path.resolve(historicalPackageDir) : root;
+		sourceDir = await safeInstancePath(historicalPackageDir, path.relative(lexical, path.resolve(sourceDir)).split(path.sep).join("/"));
 	}
+	if (!historicalPackageDir && path.resolve(sourceDir).startsWith(`${path.resolve(templatesDir)}${path.sep}`)) await ensureTemplateAssetsPrepared();
+	const relative = path.relative(await fs.realpath(sourcePackageDir), await fs.realpath(sourceDir)).split(path.sep).join("/");
+	const packaged = relative.startsWith("templates/") && !relative.includes("../");
+	if (historicalPackageDir && !packaged) throw new Error("Historical template source escapes the selected package.");
+	if (packaged) await safeInstancePath(sourcePackageDir, relative);
+	const snapshot = await captureTemplateSnapshot(sourceDir);
+	return {
+		source: packaged ? {
+			kind: "package",
+			packageName: "@icebreakers/monorepo-templates",
+			version: await readTemplatePackageVersion(sourcePackageDir),
+			templatePath: relative,
+			digest: snapshotDigest(snapshot)
+		} : {
+			kind: "snapshot",
+			templatePath: "template",
+			digest: snapshotDigest(snapshot)
+		},
+		snapshot
+	};
 }
 //#endregion
 //#region src/templates.ts
@@ -299,6 +587,453 @@ function suggestTemplateKey(key, options = {}) {
 	return best.key;
 }
 //#endregion
+//#region src/instances/store.ts
+var TemplateRegistryCleanupError = class extends AggregateError {
+	paths;
+	constructor(paths, errors) {
+		super(errors, `Template registry cleanup failed; inspect retained metadata: ${paths.join(", ")}`);
+		this.paths = paths;
+	}
+};
+async function removeOwnedLock(lockPath, token) {
+	try {
+		if ((await fs.lstat(lockPath)).isFile() && await fs.readFile(lockPath, "utf8") === token) await fs.rm(lockPath);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+}
+async function removeOwnedTemporary(filename, owner) {
+	if (!owner) return;
+	try {
+		const stat = await fs.lstat(filename, { bigint: true });
+		if (stat.isFile() && stat.dev === owner.dev && stat.ino === owner.ino) await fs.rm(filename);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+}
+async function loadTemplateInstanceRegistry(workspaceDir) {
+	const file = await safeInstancePath(workspaceDir, templateRegistryPath);
+	return await exists(file) ? parseRegistry(await fs.readFile(file, "utf8")) : {
+		schemaVersion: 1,
+		instances: []
+	};
+}
+async function loadTemplateBaseline(workspaceDir, digest) {
+	if (!digestPattern.test(digest)) throw new Error("Invalid template baseline digest.");
+	const file = await safeInstancePath(workspaceDir, `${templateBaselineDirectory}/${digest}.json`);
+	const snapshot = JSON.parse(await fs.readFile(file, "utf8"));
+	validateSnapshot(snapshot);
+	if (snapshotDigest(snapshot) !== digest) throw new Error(`Template baseline integrity check failed: ${digest}`);
+	return snapshot;
+}
+async function mutateTemplateRegistry(workspaceDir, mutate, hooks) {
+	const file = await safeInstancePath(workspaceDir, templateRegistryPath);
+	const lockPath = await safeInstancePath(workspaceDir, ".repoctl/template-instances.lock");
+	await fs.mkdir(path.dirname(file), { recursive: true });
+	let lock;
+	try {
+		lock = await fs.open(lockPath, "wx");
+	} catch (error) {
+		if (error.code === "EEXIST") throw new Error(`Template registry is locked: ${lockPath}. If its operation crashed, verify that no writer is active before removing this lock.`);
+		throw error;
+	}
+	const written = [];
+	const temporary = `${file}.${randomUUID()}.tmp`;
+	let temporaryOwner;
+	const lockToken = `${process.pid}:${randomUUID()}\n`;
+	let committed = false;
+	let result;
+	let failure;
+	try {
+		await lock.writeFile(lockToken);
+		const registry = await loadTemplateInstanceRegistry(workspaceDir);
+		const previous = JSON.stringify(registry);
+		const mutation = await mutate(registry);
+		result = mutation.result;
+		const snapshots = mutation.snapshots ?? {};
+		registry.instances.sort((a, b) => a.target < b.target ? -1 : a.target > b.target ? 1 : 0);
+		parseRegistry(JSON.stringify(registry));
+		if (JSON.stringify(registry) !== previous) {
+			for (const [digest, snapshot] of Object.entries(snapshots)) {
+				validateSnapshot(snapshot);
+				if (!digestPattern.test(digest) || snapshotDigest(snapshot) !== digest) throw new Error("Template snapshot digest does not match its content.");
+				const target = await safeInstancePath(workspaceDir, `${templateBaselineDirectory}/${digest}.json`);
+				if (await exists(target)) {
+					await loadTemplateBaseline(workspaceDir, digest);
+					continue;
+				}
+				await fs.mkdir(path.dirname(target), { recursive: true });
+				const handle = await fs.open(target, "wx");
+				written.push(target);
+				try {
+					await handle.writeFile(`${JSON.stringify(snapshot)}\n`);
+				} finally {
+					await handle.close();
+				}
+			}
+			const handle = await fs.open(temporary, "wx");
+			try {
+				temporaryOwner = await handle.stat({ bigint: true });
+				await handle.writeFile(`${JSON.stringify(registry, null, 2)}\n`);
+			} finally {
+				await handle.close();
+			}
+			await fs.rename(temporary, file);
+		}
+		committed = true;
+		await hooks?.committed?.();
+	} catch (error) {
+		failure = { error };
+		if (!committed) try {
+			await hooks?.rollback?.();
+		} catch (recoveryError) {
+			failure = { error: new AggregateError([error, recoveryError], `Template registry transaction failed and file recovery needs attention: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}. Preserve the pending recovery record.`) };
+		}
+	}
+	const paths = [];
+	const errors = [];
+	const cleanup = async (filename, operation) => {
+		try {
+			await operation();
+		} catch (error) {
+			paths.push(filename);
+			errors.push(error);
+		}
+	};
+	await cleanup(temporary, async () => await removeOwnedTemporary(temporary, temporaryOwner));
+	if (!committed) await Promise.all(written.map((target) => cleanup(target, async () => await fs.rm(target, { force: true }))));
+	await cleanup(lockPath, async () => await lock.close());
+	await cleanup(lockPath, async () => await removeOwnedLock(lockPath, lockToken));
+	if (paths.length) {
+		const cleanupError = new TemplateRegistryCleanupError([...new Set(paths)].sort(), errors);
+		failure = { error: failure ? new AggregateError([failure.error, cleanupError], `${failure.error instanceof Error ? failure.error.message : "Template registry transaction failed"}. ${cleanupError.message}`) : cleanupError };
+	}
+	if (failure) throw failure.error;
+	return result;
+}
+function canVerifyTemplateInstance(existing, next) {
+	const identity = (instance) => JSON.stringify({
+		target: instance.target,
+		template: instance.template,
+		profile: instance.generator.profile,
+		parameters: instance.parameters,
+		source: {
+			kind: instance.source.kind,
+			packageName: instance.source.packageName,
+			version: instance.source.version,
+			templatePath: instance.source.templatePath,
+			remote: instance.source.remote
+		}
+	});
+	return existing.baseline.status === "unverified" && next.baseline.status === "available" && identity(existing) === identity(next);
+}
+/** Generated IDs can opt into collision allocation under the lock; retries retain the existing target identity. */
+async function registerTemplateInstances(workspaceDir, drafts, precondition, options = {}) {
+	return mutateTemplateRegistry(workspaceDir, async (registry) => {
+		await precondition?.(registry);
+		const registered = [];
+		const snapshots = {};
+		for (const draft of drafts) {
+			validateInstance(draft.instance);
+			const target = await safeInstancePath(workspaceDir, draft.instance.target);
+			const canonicalTarget = instanceRelativePath(await fs.realpath(workspaceDir), await fs.realpath(target));
+			if (canonicalTarget !== draft.instance.target) throw new Error(`Template instance target must use its canonical filesystem path: ${canonicalTarget}`);
+			const existing = registry.instances.find((instance) => instance.target === draft.instance.target);
+			if (existing) {
+				if (canVerifyTemplateInstance(existing, draft.instance)) {
+					Object.assign(existing, {
+						...draft.instance,
+						id: existing.id,
+						provenance: existing.provenance
+					});
+					Object.assign(snapshots, draft.snapshots);
+					registered.push(existing);
+					continue;
+				}
+				if (JSON.stringify({
+					...existing,
+					id: "",
+					provenance: ""
+				}) !== JSON.stringify({
+					...draft.instance,
+					id: "",
+					provenance: ""
+				})) throw new Error(`Template target is already registered with different provenance: ${draft.instance.target}`);
+				registered.push(existing);
+				continue;
+			}
+			if (registry.instances.some((instance) => instance.target.startsWith(`${draft.instance.target}/`) || draft.instance.target.startsWith(`${instance.target}/`))) throw new Error(`Template target overlaps an existing instance: ${draft.instance.target}`);
+			let id = draft.instance.id;
+			if (!options.allocateIdOnConflict && registry.instances.some((instance) => instance.id === id)) throw new Error(`Template instance identity is already registered at a different target: ${id}`);
+			for (let attempt = 1; registry.instances.some((instance) => instance.id === id); attempt++) id = createHash("sha256").update(JSON.stringify([
+				draft.instance.id,
+				draft.instance.target,
+				attempt
+			])).digest("hex").slice(0, 24);
+			const instance = {
+				...draft.instance,
+				id
+			};
+			registry.instances.push(instance);
+			Object.assign(snapshots, draft.snapshots);
+			registered.push(instance);
+		}
+		for (const instance of registered) if (instance.baseline.status === "available") {
+			for (const digest of [instance.baseline.original, instance.baseline.rendered]) if (!snapshots[digest]) await loadTemplateBaseline(workspaceDir, digest);
+		}
+		return {
+			result: registered,
+			snapshots
+		};
+	}, options);
+}
+//#endregion
+//#region src/instances/operations.ts
+function excludeSnapshotPaths(snapshot, excludedPaths) {
+	const excluded = (file) => excludedPaths.some((item) => file === item || file.startsWith(`${item}/`));
+	return {
+		...snapshot,
+		files: snapshot.files.filter((file) => !excluded(file.path)),
+		directories: snapshot.directories.filter((directory) => !excluded(directory))
+	};
+}
+function templateInstanceId(target, template) {
+	return createHash("sha256").update(JSON.stringify([target, template])).digest("hex").slice(0, 24);
+}
+/** Reserve a new directory only when no existing instance owns its path. */
+async function createTemplateInstanceTarget(workspaceDir, relative) {
+	const target = await safeInstancePath(workspaceDir, relative);
+	const owner = (await loadTemplateInstanceRegistry(workspaceDir)).instances.find((instance) => instance.target === relative || instance.target.startsWith(`${relative}/`) || relative.startsWith(`${instance.target}/`));
+	if (owner) throw new Error(`Template target is already owned by retained instance ${owner.id} at ${owner.target}: ${relative}. Inspect it with repo templates instances ${owner.id} --json. Removing a directory retains its provenance and baselines. Restore the original project from version control or a backup, explicitly relocate a verified moved instance, or choose a different unowned path for a new project.`);
+	await fs.mkdir(path.dirname(target), { recursive: true });
+	await fs.mkdir(target);
+	return target;
+}
+async function prepareGeneratedTemplateInstance(options) {
+	const requested = instanceRelativePath(options.workspaceDir, options.targetDir);
+	const safeTarget = await safeInstancePath(options.workspaceDir, requested);
+	const target = instanceRelativePath(await fs.realpath(options.workspaceDir), await fs.realpath(safeTarget));
+	const excludedPaths = normalizeTemplateExclusions(options.excludedPaths ?? []);
+	const rendered = excludeSnapshotPaths(await captureTemplateSnapshot(safeTarget), excludedPaths);
+	const originalDigest = snapshotDigest(options.preparedSource.snapshot);
+	const renderedDigest = snapshotDigest(rendered);
+	return {
+		instance: {
+			id: templateInstanceId(target, options.template),
+			target,
+			template: options.template,
+			provenance: "created",
+			source: options.preparedSource.source,
+			generator: {
+				profile: options.profile,
+				version: options.generatorVersion ?? await readTemplatePackageVersion()
+			},
+			parameters: generationParameters(options.parameters),
+			baseline: {
+				status: "available",
+				original: originalDigest,
+				rendered: renderedDigest
+			},
+			...excludedPaths.length ? { excludedPaths } : {}
+		},
+		snapshots: {
+			[originalDigest]: options.preparedSource.snapshot,
+			[renderedDigest]: rendered
+		}
+	};
+}
+async function recordGeneratedTemplateInstance(options) {
+	const draft = await prepareGeneratedTemplateInstance(options);
+	return (await registerTemplateInstances(options.workspaceDir, [draft], void 0, { allocateIdOnConflict: true }))[0];
+}
+async function listTemplateInstances(workspaceDir) {
+	const registry = await loadTemplateInstanceRegistry(workspaceDir);
+	return Promise.all(registry.instances.map(async (instance) => {
+		let targetStatus = "unsafe";
+		try {
+			const target = await safeInstancePath(workspaceDir, instance.target);
+			targetStatus = await exists(target) ? (await fs.lstat(target)).isDirectory() ? "present" : "unsafe" : "missing";
+		} catch {}
+		let baselineStatus = instance.baseline.status;
+		if (instance.baseline.status === "available") try {
+			await loadTemplateBaseline(workspaceDir, instance.baseline.original);
+			await loadTemplateBaseline(workspaceDir, instance.baseline.rendered);
+		} catch {
+			baselineStatus = "unavailable";
+		}
+		return {
+			instance,
+			targetStatus,
+			baselineStatus
+		};
+	}));
+}
+async function rebuildTemplateInstanceBaseline(workspaceDir, id, targetDir, layer = "rendered") {
+	const instance = (await loadTemplateInstanceRegistry(workspaceDir)).instances.find((item) => item.id === id || item.target === id);
+	if (!instance) throw new Error(`Unknown template instance: ${id}`);
+	if (instance.baseline.status !== "available") throw new Error(`Template instance ${instance.target} has no verified baseline; reliable upgrades are unavailable.`);
+	await writeTemplateSnapshot(await loadTemplateBaseline(workspaceDir, instance.baseline[layer]), targetDir);
+	return instance;
+}
+/** Relocation never guesses based on a package name; all retained baseline files must identify the instance. */
+async function relocateTemplateInstance(workspaceDir, id, target, apply = false) {
+	const destination = await safeInstancePath(workspaceDir, target);
+	target = instanceRelativePath(await fs.realpath(workspaceDir), await fs.realpath(destination));
+	const inspect = async () => {
+		const registry = await loadTemplateInstanceRegistry(workspaceDir);
+		const instance = registry.instances.find((item) => item.id === id || item.target === id);
+		if (!instance) throw new Error(`Unknown template instance: ${id}`);
+		if (instance.target === target) return {
+			instance,
+			target,
+			changed: false
+		};
+		if (await exists(await safeInstancePath(workspaceDir, instance.target))) throw new Error("The registered target still exists; relocation requires a missing original target.");
+		if (instance.baseline.status !== "available") throw new Error("Cannot verify relocation without an available baseline.");
+		const baseline = excludeSnapshotPaths(await loadTemplateBaseline(workspaceDir, instance.baseline.rendered), instance.excludedPaths ?? []);
+		if (snapshotDigest(excludeSnapshotPaths(await captureTemplateSnapshot(await safeInstancePath(workspaceDir, target)), instance.excludedPaths ?? [])) !== snapshotDigest(baseline)) throw new Error("Relocation cannot verify this destination as the same instance: its files differ from the retained baseline.");
+		if (registry.instances.some((item) => item.id !== instance.id && (item.target === target || item.target.startsWith(`${target}/`) || target.startsWith(`${item.target}/`)))) throw new Error("Relocation target overlaps a registered instance.");
+		return {
+			instance,
+			target,
+			changed: true
+		};
+	};
+	if (!apply) return {
+		...await inspect(),
+		applied: false
+	};
+	return mutateTemplateRegistry(workspaceDir, async (registry) => {
+		const result = await inspect();
+		if (result.changed) registry.instances.find((item) => item.id === result.instance.id).target = target;
+		return { result: {
+			...result,
+			applied: true
+		} };
+	});
+}
+//#endregion
+//#region src/instances/workspace.ts
+/** Call after all scaffold and root-manifest transformations have succeeded. */
+async function recordWorkspaceTemplateInstances(workspaceDir, templateKeys, templatesDir$2 = templatesDir, originals) {
+	try {
+		const selected = new Set(templateKeys);
+		const drafts = [];
+		for (const template of getTemplateChoices()) {
+			if (!selected.has(template.key)) continue;
+			const preparedSource = await prepareTemplateInstanceSource(path.join(templatesDir$2, template.source));
+			if (originals?.has(template.key) && snapshotDigest(originals.get(template.key).snapshot) !== snapshotDigest(preparedSource.snapshot)) throw new Error(`Template source changed during creation: ${template.key}. Generated files remain at ${workspaceDir}; no successful registration was written.`);
+			drafts.push(await prepareGeneratedTemplateInstance({
+				workspaceDir,
+				targetDir: path.join(workspaceDir, template.target),
+				template: template.key,
+				preparedSource,
+				profile: "workspace-copy-v1"
+			}));
+		}
+		if (!drafts.length) return [];
+		return await registerTemplateInstances(workspaceDir, drafts, void 0, { allocateIdOnConflict: true });
+	} catch (error) {
+		throw new Error(`Scaffolded files remain at ${workspaceDir}, but template registration did not complete. Registry recovery path: ${path.join(workspaceDir, ".repoctl/template-instances.json")}. Inspect the error and use repo templates link for each generated target.`, { cause: error });
+	}
+}
+//#endregion
+//#region src/scaffold.ts
+async function isEmptyDir(dir) {
+	try {
+		return (await fs.readdir(dir)).length === 0;
+	} catch (error) {
+		if (error && error.code === "ENOENT") return true;
+		throw error;
+	}
+}
+async function prepareTargetDir(dir, options = {}) {
+	if (await isEmptyDir(dir)) {
+		await fs.mkdir(dir, { recursive: true });
+		return;
+	}
+	if (!options.force) throw new Error(`Target directory ${dir} is not empty. Pass --force to overwrite.`);
+	await fs.rm(dir, {
+		recursive: true,
+		force: true
+	});
+	await fs.mkdir(dir, { recursive: true });
+}
+async function copyDirContents(sourceDir, targetDir, options = {}) {
+	const rootDir = options.rootDir ?? sourceDir;
+	const filter = options.filter ?? ((src) => !shouldSkipTemplatePath(rootDir, src));
+	const renameEntry = options.renameEntry ?? toWorkspaceGitignorePath;
+	const skipRoot = new Set(options.skipRootBasenames ?? []);
+	await fs.mkdir(targetDir, { recursive: true });
+	const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (sourceDir === rootDir && skipRoot.has(entry.name)) continue;
+		const from = path.join(sourceDir, entry.name);
+		if (!filter(from)) continue;
+		const targetName = renameEntry(entry.name);
+		const to = path.join(targetDir, targetName);
+		if (entry.isDirectory()) {
+			const nestedOptions = {
+				rootDir,
+				filter,
+				renameEntry
+			};
+			if (options.skipRootBasenames) nestedOptions.skipRootBasenames = options.skipRootBasenames;
+			await copyDirContents(from, to, { ...nestedOptions });
+			continue;
+		}
+		if (entry.isSymbolicLink()) {
+			const link = await fs.readlink(from);
+			await fs.symlink(link, to);
+			continue;
+		}
+		await fs.cp(from, to);
+	}
+}
+function isDefaultTemplatesPath(sourceDir) {
+	const resolvedSource = path.resolve(sourceDir);
+	const resolvedTemplatesRoot = path.resolve(templatesDir);
+	return resolvedSource === resolvedTemplatesRoot || resolvedSource.startsWith(`${resolvedTemplatesRoot}${path.sep}`);
+}
+async function scaffoldTemplate(options) {
+	const { sourceDir, targetDir, ensureTargetDir = true, filter, renameEntry, skipRootBasenames } = options;
+	if (isDefaultTemplatesPath(sourceDir)) await ensureTemplateAssetsPrepared();
+	if (ensureTargetDir) await fs.mkdir(targetDir, { recursive: true });
+	const copyOptions = { rootDir: sourceDir };
+	if (filter) copyOptions.filter = filter;
+	if (renameEntry) copyOptions.renameEntry = renameEntry;
+	if (skipRootBasenames) copyOptions.skipRootBasenames = skipRootBasenames;
+	await copyDirContents(sourceDir, targetDir, copyOptions);
+}
+async function scaffoldWorkspace(options) {
+	const { targetDir, templateKeys = [], assetsDir: assetsDir$1 = assetsDir, templatesDir: templatesDir$1 = templatesDir, includeAssets = true, targetMode = "prepare", force = false } = options;
+	if (includeAssets && path.resolve(assetsDir$1) === path.resolve(assetsDir) || templateKeys.length > 0 && path.resolve(templatesDir$1) === path.resolve(templatesDir)) await ensureTemplateAssetsPrepared();
+	if (targetMode === "prepare") await prepareTargetDir(targetDir, { force });
+	else if (targetMode === "ensure") await fs.mkdir(targetDir, { recursive: true });
+	if (includeAssets) await copyDirContents(assetsDir$1, targetDir, {
+		rootDir: assetsDir$1,
+		renameEntry: toWorkspaceAssetPath
+	});
+	if (!templateKeys.length) {
+		await options.afterScaffold?.();
+		return;
+	}
+	const selections = new Set(templateKeys);
+	const originals = /* @__PURE__ */ new Map();
+	for (const template of templateChoices$1) {
+		if (!selections.has(template.key)) continue;
+		const from = path.join(templatesDir$1, template.source);
+		const to = path.join(targetDir, template.target);
+		originals.set(template.key, await prepareTemplateInstanceSource(from));
+		await scaffoldTemplate({
+			sourceDir: from,
+			targetDir: to
+		});
+	}
+	await options.afterScaffold?.();
+	await recordWorkspaceTemplateInstances(targetDir, templateKeys, templatesDir$1, originals);
+}
+//#endregion
 //#region src/utils/command.ts
 async function runCommand(command, args, options = {}) {
 	const result = await exec(command, args, {
@@ -318,6 +1053,334 @@ async function execaCommand(command, options = {}) {
 	return { exitCode: result.code };
 }
 //#endregion
+//#region src/instances/move.ts
+function fingerprint(registry) {
+	const instances = [...registry.instances].sort((a, b) => a.target < b.target ? -1 : a.target > b.target ? 1 : 0);
+	return createHash("sha256").update(JSON.stringify({
+		...registry,
+		instances
+	})).digest("hex");
+}
+function inside(target, parent) {
+	return target === parent || target.startsWith(`${parent}/`);
+}
+function inspectMove(registry, from, to) {
+	portableRelativePath(from);
+	portableRelativePath(to);
+	const owner = registry.instances.find((instance) => instance.target !== from && inside(from.toLowerCase(), instance.target.toLowerCase()));
+	if (owner) throw new Error(`Workspace ${from} belongs to parent template instance ${owner.id} (${owner.target}); moving only part of an instance requires an explicit ownership review.`);
+	if (registry.instances.some((instance) => !inside(instance.target, from) && (inside(to.toLowerCase(), instance.target.toLowerCase()) || inside(instance.target.toLowerCase(), to.toLowerCase())))) throw new Error(`Template move destination overlaps a registered instance, including retained missing records: ${to}`);
+	const relocations = registry.instances.filter((instance) => inside(instance.target, from)).map((instance) => ({
+		id: instance.id,
+		from: instance.target,
+		to: to + instance.target.slice(from.length)
+	})).sort((a, b) => a.id.localeCompare(b.id));
+	const after = {
+		...registry,
+		instances: registry.instances.map((instance) => ({
+			...instance,
+			target: relocations.find((item) => item.id === instance.id)?.to ?? instance.target
+		}))
+	};
+	parseRegistry(JSON.stringify(after));
+	for (const relocation of relocations) if (after.instances.some((instance) => instance.id !== relocation.id && (inside(instance.target.toLowerCase(), relocation.to.toLowerCase()) || inside(relocation.to.toLowerCase(), instance.target.toLowerCase())))) throw new Error(`Template move destination overlaps a registered instance, including retained missing records: ${relocation.to}`);
+	return {
+		from,
+		to,
+		beforeHash: fingerprint(registry),
+		afterHash: fingerprint(after),
+		relocations
+	};
+}
+function reversePlan(plan) {
+	return {
+		from: plan.to,
+		to: plan.from,
+		beforeHash: plan.afterHash,
+		afterHash: plan.beforeHash,
+		relocations: plan.relocations.map((item) => ({
+			id: item.id,
+			from: item.to,
+			to: item.from
+		}))
+	};
+}
+/** Preview target changes without treating business edits as a new template baseline. */
+async function planTemplateInstanceMove(workspaceDir, from, to) {
+	const plan = inspectMove(await loadTemplateInstanceRegistry(workspaceDir), from, to);
+	for (const relocation of plan.relocations) await safeInstancePath(workspaceDir, relocation.to);
+	return plan;
+}
+/** Hold the registry lock through file mutation, registry commit and any rollback, including moves with no registered instances. */
+async function moveTemplateInstances(workspaceDir, plan, hooks, replay = false) {
+	let committed = false;
+	try {
+		await mutateTemplateRegistry(workspaceDir, async (registry) => {
+			const expected = replay ? plan.afterHash : plan.beforeHash;
+			if (fingerprint(registry) !== expected) throw new Error("Template instance registry changed before the workspace move; preview again.");
+			const current = replay ? reversePlan(inspectMove(registry, plan.to, plan.from)) : inspectMove(registry, plan.from, plan.to);
+			if (!isDeepStrictEqual(current, plan)) throw new Error("Template instance move plan changed or is invalid; preview again.");
+			for (const relocation of plan.relocations) await safeInstancePath(workspaceDir, relocation.to);
+			await hooks.apply();
+			if (!replay) for (const relocation of plan.relocations) registry.instances.find((instance) => instance.id === relocation.id).target = relocation.to;
+			if (fingerprint(registry) !== plan.afterHash) throw new Error("Template instance registry does not match the reviewed move result.");
+			return { result: void 0 };
+		}, {
+			rollback: hooks.rollback,
+			committed: async () => {
+				committed = true;
+				await hooks.committed();
+			}
+		});
+		return [];
+	} catch (error) {
+		if (committed && error instanceof TemplateRegistryCleanupError) return error.paths;
+		throw error;
+	}
+}
+//#endregion
+//#region src/instances/replace.ts
+/** Replace exactly one instance, rolling file mutations back before releasing the registry lock on failure. */
+async function replaceTemplateInstance(workspaceDir, before, draft, hooks) {
+	validateInstance(draft.instance);
+	const identity = (instance) => JSON.stringify([
+		instance.id,
+		instance.target,
+		instance.template,
+		instance.provenance,
+		instance.generator.profile
+	]);
+	if (identity(before) !== identity(draft.instance) || draft.instance.baseline.status !== "available") throw new Error("An instance upgrade must preserve its identity and provide a reliable target baseline.");
+	for (const [digest, snapshot] of Object.entries(draft.snapshots)) {
+		validateSnapshot(snapshot);
+		if (snapshotDigest(snapshot) !== digest) throw new Error("Replacement baseline digest does not match its content.");
+	}
+	return mutateTemplateRegistry(workspaceDir, async (registry) => {
+		const index = registry.instances.findIndex((instance) => instance.id === before.id);
+		if (index < 0 || JSON.stringify(registry.instances[index]) !== JSON.stringify(before)) throw new Error("Template instance changed before the transaction; preview again.");
+		if (draft.instance.baseline.status === "available") {
+			for (const digest of [draft.instance.baseline.original, draft.instance.baseline.rendered]) if (!draft.snapshots[digest]) await loadTemplateBaseline(workspaceDir, digest);
+		}
+		await hooks.apply();
+		registry.instances[index] = draft.instance;
+		return {
+			result: draft.instance,
+			snapshots: draft.snapshots
+		};
+	}, hooks);
+}
+//#endregion
+//#region src/parameters/manifest.ts
+const templateParameterManifestName = "repoctl.template.json";
+const packageSections = [
+	"scripts",
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+function paths(input, field) {
+	if (!Array.isArray(input) || input.length > 1e3 || input.some((item) => typeof item !== "string") || new Set(input).size !== input.length) parameterError(field, "expected unique relative paths");
+	for (const item of input) {
+		portableRelativePath(item);
+		if (/[*?{}[\]]/u.test(item) || item === "repoctl.template.json" || item === "package.json") parameterError(field, "use exact asset paths; package entries belong in conditions.package");
+	}
+}
+function parseTemplateParameterManifest(value) {
+	if (!isParameterRecord(value) || value["schemaVersion"] !== 1 || Object.keys(value).some((key) => ![
+		"schemaVersion",
+		"parameters",
+		"interpolate",
+		"conditions"
+	].includes(key))) parameterError("manifest", "expected schemaVersion 1 and supported declarative fields");
+	validateTemplateParameterSchema(value["parameters"]);
+	if (value["interpolate"] !== void 0) paths(value["interpolate"], "interpolate");
+	if (value["conditions"] !== void 0) {
+		if (!Array.isArray(value["conditions"]) || value["conditions"].length > 100) parameterError("conditions", "expected at most 100 conditions");
+		for (const [index, item] of value["conditions"].entries()) {
+			const field = `conditions[${index}]`;
+			if (!isParameterRecord(item) || Object.keys(item).some((key) => ![
+				"when",
+				"files",
+				"package"
+			].includes(key)) || !isParameterRecord(item["when"]) || Object.keys(item["when"]).some((key) => !["parameter", "equals"].includes(key)) || typeof item["when"]["parameter"] !== "string") parameterError(field, "expected a parameter equality condition");
+			const definition = Object.hasOwn(value["parameters"], item["when"]["parameter"]) ? value["parameters"][item["when"]["parameter"]] : void 0;
+			if (!definition || definition.sensitive || !parameterValueMatches(definition, item["when"]["equals"])) parameterError(`${field}.when`, "condition must compare a declared nonsensitive parameter with a value of its type");
+			if (item["files"] !== void 0) paths(item["files"], `${field}.files`);
+			if (item["package"] !== void 0) {
+				if (!isParameterRecord(item["package"]) || Object.keys(item["package"]).some((key) => !packageSections.includes(key))) parameterError(`${field}.package`, "only scripts and dependency maps are supported");
+				for (const [section, entries] of Object.entries(item["package"])) if (!isParameterRecord(entries) || Object.entries(entries).some(([key, value]) => !key || [
+					"__proto__",
+					"constructor",
+					"prototype"
+				].includes(key) || typeof value !== "string")) parameterError(`${field}.package.${section}`, "expected a map of string entries");
+			}
+			if (item["files"] === void 0 && item["package"] === void 0) parameterError(field, "declare files or package entries");
+		}
+	}
+	return value;
+}
+function readTemplateParameterManifest(snapshot) {
+	const file = snapshot.files.find((file) => file.path === templateParameterManifestName);
+	if (!file) return;
+	let value;
+	try {
+		value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(file.content, "base64")));
+	} catch {
+		parameterError("manifest", "repoctl.template.json must contain UTF-8 JSON");
+	}
+	return parseTemplateParameterManifest(value);
+}
+//#endregion
+//#region src/parameters/render.ts
+/** Expand declared text only. Binary files and all undeclared files remain byte-for-byte identical. */
+function renderTemplateParameters(source, manifest, parameters) {
+	validateSnapshot(source);
+	const result = {
+		snapshot: {
+			schemaVersion: 1,
+			files: [],
+			directories: []
+		},
+		sensitivePaths: [],
+		files: [],
+		package: []
+	};
+	const entries = /* @__PURE__ */ new Set([...source.files.map((file) => file.path), ...source.directories]);
+	const omitted = /* @__PURE__ */ new Set();
+	const within = (file, directory) => file === directory || file.startsWith(`${directory}/`);
+	for (const file of manifest.interpolate ?? []) if (!source.files.some((entry) => entry.path === file)) parameterError("interpolate", `declared file does not exist: ${file}`);
+	for (const condition of manifest.conditions ?? []) for (const file of condition.files ?? []) {
+		if (!entries.has(file)) parameterError("conditions.files", `declared path does not exist: ${file}`);
+		if (parameters.values[condition.when.parameter] !== condition.when.equals) omitted.add(file);
+	}
+	let outputBytes = source.files.filter((file) => file.path !== "repoctl.template.json" && ![...omitted].some((item) => within(file.path, item))).reduce((total, file) => total + Buffer.byteLength(file.content, "base64"), 0);
+	function checkSize() {
+		if (outputBytes > 33554432) parameterError("output", "rendered snapshot exceeds 32 MiB");
+	}
+	function interpolate(text, file, allowSensitive) {
+		if (!allowSensitive) {
+			outputBytes += Buffer.byteLength(text);
+			checkSize();
+		}
+		return text.replace(/\{\{repoctl(-json)?:([a-z]\w*)\}\}/gu, (token, json, name) => {
+			if (!Object.hasOwn(parameters.values, name)) parameterError(`values.${name}`, "an interpolated parameter is missing");
+			if (parameters.sensitive.includes(name)) {
+				if (!allowSensitive) parameterError(`values.${name}`, "sensitive inputs cannot enter package metadata");
+				result.sensitivePaths.push(file);
+			}
+			const replacement = json ? JSON.stringify(parameters.values[name]) : String(parameters.values[name]);
+			outputBytes += Buffer.byteLength(replacement) - Buffer.byteLength(token);
+			checkSize();
+			return replacement;
+		});
+	}
+	for (const file of source.files) {
+		if (file.path === "repoctl.template.json") continue;
+		if ([...omitted].some((item) => within(file.path, item))) {
+			result.files.push({
+				path: file.path,
+				status: "omit",
+				sensitive: false
+			});
+			continue;
+		}
+		let content = Buffer.from(file.content, "base64");
+		if (manifest.interpolate?.includes(file.path) && !content.includes(0)) {
+			let text;
+			try {
+				text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+			} catch {}
+			if (text !== void 0) content = Buffer.from(interpolate(text, file.path, true));
+		}
+		result.snapshot.files.push({
+			...file,
+			content: content.toString("base64")
+		});
+		result.files.push({
+			path: file.path,
+			status: "include",
+			sensitive: result.sensitivePaths.includes(file.path)
+		});
+	}
+	result.snapshot.directories = source.directories.filter((directory) => ![...omitted].some((item) => within(directory, item)));
+	const packageFile = result.snapshot.files.find((file) => file.path === "package.json");
+	if (manifest.conditions?.some((condition) => condition.package)) {
+		if (!packageFile) parameterError("conditions.package", "a package.json file is required");
+		let pkg;
+		try {
+			const value = JSON.parse(Buffer.from(packageFile.content, "base64").toString("utf8"));
+			if (!isParameterRecord(value)) throw new Error("invalid");
+			pkg = value;
+		} catch {
+			parameterError("conditions.package", "package.json must be a JSON object");
+		}
+		const reserved = /* @__PURE__ */ new Set();
+		for (const condition of manifest.conditions ?? []) for (const section of packageSections) for (const [name, template] of Object.entries(condition.package?.[section] ?? {})) {
+			const identity = `${section}.${name}`;
+			if (reserved.has(identity) || isParameterRecord(pkg[section]) && Object.hasOwn(pkg[section], name)) parameterError(`conditions.package.${identity}`, "conditional entries must have one owner and be absent from the base manifest");
+			reserved.add(identity);
+			const include = parameters.values[condition.when.parameter] === condition.when.equals;
+			result.package.push({
+				section,
+				name,
+				status: include ? "include" : "omit"
+			});
+			if (include) {
+				if (pkg[section] !== void 0 && !isParameterRecord(pkg[section])) parameterError(`conditions.package.${section}`, "base manifest section must be an object");
+				const values = pkg[section] ?? {};
+				values[name] = interpolate(template, "package.json", false);
+				pkg[section] = Object.fromEntries(Object.entries(values).sort(([a], [b]) => a.localeCompare(b)));
+			}
+		}
+		packageFile.content = Buffer.from(`${JSON.stringify(pkg, null, 2)}\n`).toString("base64");
+	}
+	result.sensitivePaths = [...new Set(result.sensitivePaths)].sort();
+	validateSnapshot(result.snapshot);
+	return result;
+}
+//#endregion
+//#region src/parameters/resolve.ts
+/** The same strict, synchronous resolver serves prompts, JSON input and local generators. */
+function resolveTemplateParameters(schema, input = {}) {
+	validateTemplateParameterSchema(schema);
+	if (!isParameterRecord(input)) parameterError("values", "expected an object");
+	for (const name of Object.keys(input)) if (!Object.hasOwn(schema, name)) parameterError(`values.${name}`, "unknown parameter");
+	const result = {
+		values: {},
+		report: {},
+		retained: {},
+		sensitive: []
+	};
+	for (const [name, definition] of Object.entries(schema)) {
+		const value = Object.hasOwn(input, name) ? input[name] : definition.default;
+		if (value === void 0) {
+			if (definition.required) parameterError(`values.${name}`, "required parameter is missing");
+			continue;
+		}
+		if (!parameterValueMatches(definition, value) || definition.required && value === "") parameterError(`values.${name}`, `expected ${definition.type}${definition.type === "enum" ? " option" : ""}`);
+		result.values[name] = value;
+		result.report[name] = definition.sensitive ? "[redacted]" : value;
+		if (definition.sensitive) result.sensitive.push(name);
+		else result.retained[name] = value;
+	}
+	return result;
+}
+/** Prompts only omitted inputs; supplied inputs are validated before any question is asked. */
+async function promptTemplateParameters(schema, input, prompt) {
+	validateTemplateParameterSchema(schema);
+	resolveTemplateParameters(Object.fromEntries(Object.entries(schema).map(([name, definition]) => [name, {
+		...definition,
+		required: false
+	}])), input);
+	const values = { ...input };
+	for (const [name, definition] of Object.entries(schema)) if (!Object.hasOwn(values, name)) {
+		const value = await prompt(name, definition);
+		if (value !== void 0) values[name] = value;
+	}
+	return resolveTemplateParameters(schema, values);
+}
+//#endregion
 //#region src/index.ts
 const templateChoices = getTemplateChoices();
 const assetTargets = assetTargets$1;
@@ -326,4 +1389,4 @@ const templateSourceMap = Object.fromEntries(templateChoices.map((item) => [item
 const templateTargetMap = Object.fromEntries(templateChoices.map((item) => [item.key, item.target]));
 const templateMap = templateSourceMap;
 //#endregion
-export { Command, assetTargets, assetsDir, checkbox, createTemplateCopyFilter, ensureTemplateAssetsPrepared, execaCommand, getAssetTargets, getTemplateChoice, getTemplateChoices, getTemplateDefinition, getTemplateKeys, getTemplateSource, getTemplateTarget, getWorkspacePackageManager, input, isGitignoreFile, isTemplateCategory, isTemplateKey, packageDir, prepareAssets, program, runCommand, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, suggestTemplateKey, templateCategories, templateChoices, templateMap, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceAssetPath, toWorkspaceGitignorePath };
+export { Command, areTemplateAssetsPrepared, assetTargets, assetsDir, canVerifyTemplateInstance, captureTemplateSnapshot, checkbox, compareTemplateSnapshots, createTemplateCopyFilter, createTemplateInstanceTarget, ensureTemplateAssetsPrepared, execaCommand, generationParameters, getAssetTargets, getTemplateChoice, getTemplateChoices, getTemplateDefinition, getTemplateKeys, getTemplateSource, getTemplateTarget, getWorkspacePackageManager, input, instanceRelativePath, isExactTemplateVersion, isGitignoreFile, isTemplateCategory, isTemplateKey, listTemplateInstances, loadTemplateBaseline, loadTemplateInstanceRegistry, moveTemplateInstances, normalizeTemplateExclusions, packageDir, parseTemplateParameterManifest, password, planTemplateInstanceMove, prepareAssets, prepareGeneratedTemplateInstance, prepareTemplateInstanceSource, program, promptTemplateParameters, readTemplatePackageVersion, readTemplateParameterManifest, rebuildTemplateInstanceBaseline, recordGeneratedTemplateInstance, recordWorkspaceTemplateInstances, registerTemplateInstances, relocateTemplateInstance, renderTemplateParameters, replaceTemplateInstance, resolveTemplateParameters, runCommand, safeInstancePath, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, snapshotDigest, suggestTemplateKey, templateBaselineDirectory, templateCategories, templateChoices, templateInstanceId, templateMap, templateParameterManifestName, templateRegistryPath, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceAssetPath, toWorkspaceGitignorePath, validateTemplateParameterSchema, writeTemplateSnapshot };