@savvy-web/silk-effects 5.4.0 → 5.5.1

package/repos/services/manager.js

@@ -3,8 +3,8 @@ import { GitSubmoduleError, NoteNotFoundError, RepoNotFoundError, ReposConfigErr
 import { RepoName } from "../schemas/manifest.js";
 import { ReposConfigStore } from "./config-store.js";
 import { ReposLockdown, resolveModuleDir } from "./lockdown.js";
-import { Clock, Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
-import { Git } from "@effected/git";
+import { Clock, Context, Effect, Exit, FileSystem, Layer, Option, Path, Result, Schema } from "effect";
+import { Git, GitConfig, Gitmodules, LsRemoteEntry } from "@effected/git";
 import { createHash } from "node:crypto";
 
 //#region src/repos/services/manager.ts
@@ -30,7 +30,9 @@ const STALE_LOCK_MAX_AGE_MS = 6e5;
 * Drives the vendored `.repos/` submodules over git: reports status
 * (presence, dirtiness, stale notes), reconciles the working tree with the
 * manifest, vendors new entries (`add`), re-pins existing entries to a new
-* ref (`pin`), and adds, removes, or promotes agent notes (`note`).
+* ref (`pin`), adds/removes/promotes agent notes (`note`), unvendors
+* (`remove`), renames (`rename`), and explicitly hard-resets dirty
+* checkouts back to their pinned commit (`restore`).
 * @public
 */
 var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/ReposManager") {
@@ -58,12 +60,25 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 			reason: error.message
 		});
 		const isPresent = (repoPath) => fs.readDirectory(repoPath).pipe(Effect.map((files) => files.length > 0), Effect.orElseSucceed(() => false));
+		/**
+		* `Object.hasOwn`-guarded membership read for the manifest's `repos`
+		* map. A bare bracket read (`repos[name]`) resolves an INHERITED
+		* `Object.prototype` member for a name like `"constructor"` or
+		* `"toString"` instead of reporting absence, letting a crafted repo
+		* name read back a function rather than fail typed as
+		* `RepoNotFoundError` (the same prototype-pollution-read hazard
+		* `ReleasePlanner` guards against for changelog module ids).
+		*/
+		const getRepoEntry = (repos, name) => Object.hasOwn(repos, name) ? repos[name] : void 0;
 		const status = (root) => Effect.gen(function* () {
 			const manifest = yield* configStore.read(root);
 			const repos = yield* Effect.forEach(Object.entries(manifest.repos), ([name, entry]) => Effect.gen(function* () {
 				const repoPath = path.join(root, REPOS_DIR, name);
+				const repoPathRel = `${REPOS_DIR}/${name}`;
 				const present = yield* isPresent(repoPath);
-				const commit = (yield* git.lsTree(root, "HEAD", { pathspec: [`${".repos"}/${name}`] }).pipe(Effect.mapError(asSubmoduleError(`git ls-tree HEAD -- ${".repos"}/${name}`, root))))[0]?.oid ?? null;
+				const committedCommit = (yield* git.lsTree(root, "HEAD", { pathspec: [repoPathRel] }).pipe(Effect.mapError(asSubmoduleError(`git ls-tree HEAD -- ${repoPathRel}`, root))))[0]?.oid;
+				const stagedCommit = (yield* git.lsFiles(root, { pathspec: [repoPathRel] }).pipe(Effect.mapError(asSubmoduleError(`git ls-files --stage -- ${repoPathRel}`, root)))).find((lsFilesEntry) => lsFilesEntry.mode === "160000")?.oid;
+				const checkedOutCommit = present ? yield* git.revParse(repoPath, "HEAD").pipe(Effect.catchTag("NotARepositoryError", () => Effect.succeed(void 0)), Effect.mapError(asSubmoduleError("git rev-parse HEAD", repoPath))) : void 0;
 				let dirty = false;
 				if (present) dirty = (yield* git.status(repoPath).pipe(Effect.mapError(asSubmoduleError("git status --porcelain", repoPath)))).length > 0;
 				const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== entry.ref).map((note) => note.id);
@@ -72,7 +87,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					ref: entry.ref,
 					purpose: entry.purpose,
 					present,
-					commit,
+					commit: stagedCommit ?? null,
+					...stagedCommit !== void 0 ? { stagedCommit } : {},
+					...committedCommit !== void 0 ? { committedCommit } : {},
+					...checkedOutCommit !== void 0 ? { checkedOutCommit } : {},
 					dirty,
 					staleNoteIds
 				};
@@ -88,8 +106,12 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 			const sparseApplied = [];
 			const upToDate = [];
 			const clearedLocks = [];
+			const urlSynced = [];
+			const registered = [];
+			const gitmodulesPath = path.join(root, ".gitmodules");
 			for (const [name, entry] of Object.entries(manifest.repos)) {
 				const repoPath = path.join(root, REPOS_DIR, name);
+				const repoPathRel = `${REPOS_DIR}/${name}`;
 				const moduleDir = yield* resolveModuleDir(fs, path, root, name);
 				yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
 					let clearedAnyLock = false;
@@ -106,12 +128,38 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 						}))) clearedAnyLock = true;
 					}
 					if (clearedAnyLock) clearedLocks.push(name);
-					if (!(yield* isPresent(repoPath))) {
+					const present = yield* isPresent(repoPath);
+					const gitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.option);
+					let gitmodulesEntry;
+					if (Option.isSome(gitmodulesText)) gitmodulesEntry = (yield* Gitmodules.parse(gitmodulesText.value).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)))).entries.find((candidate) => candidate.path === repoPathRel);
+					if (present && gitmodulesEntry) {
+						const currentUrl = yield* git.configGet(repoPath, "remote.origin.url").pipe(Effect.mapError(asSubmoduleError("git config --get remote.origin.url", repoPath)));
+						if (Option.isSome(currentUrl) && currentUrl.value !== entry.url) {
+							const configResult = GitConfig.parseResult(Option.getOrThrow(gitmodulesText));
+							if (Result.isFailure(configResult)) return yield* Effect.fail(asSubmoduleError("parse .gitmodules", gitmodulesPath)(configResult.failure));
+							const setResult = Gitmodules.setUrl(configResult.success, gitmodulesEntry.name, entry.url);
+							if (Result.isFailure(setResult)) return yield* Effect.fail(asSubmoduleError(`gitmodules set-url ${gitmodulesEntry.name}`, gitmodulesPath)(setResult.failure));
+							yield* fs.writeFileString(gitmodulesPath, setResult.success.stringify()).pipe(Effect.mapError(asSubmoduleError("write .gitmodules", gitmodulesPath)));
+							yield* git.submoduleSync(root, { paths: [repoPathRel] }).pipe(Effect.mapError(asSubmoduleError(`git submodule sync -- ${repoPathRel}`, root)));
+							urlSynced.push(name);
+						} else upToDate.push(name);
+					} else if (!present && !gitmodulesEntry) {
+						yield* git.submoduleAdd(root, {
+							url: entry.url,
+							path: repoPathRel,
+							depth: 1
+						}).pipe(Effect.mapError(asSubmoduleError(`git submodule add --depth 1 ${entry.url} ${repoPathRel}`, root)));
+						yield* git.configSet(root, `submodule.${repoPathRel}.shallow`, "true", { file: ".gitmodules" }).pipe(Effect.mapError(asSubmoduleError(`git config -f .gitmodules submodule.${repoPathRel}.shallow true`, root)));
+						yield* fetchRef(repoPath, entry.ref);
+						yield* git.checkout(repoPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", repoPath)));
+						yield* git.add(root, [".gitmodules", repoPathRel]).pipe(Effect.mapError(asSubmoduleError(`git add .gitmodules ${repoPathRel}`, root)));
+						registered.push(name);
+					} else if (!present) {
 						yield* git.submoduleUpdate(root, {
 							init: true,
 							depth: 1,
-							paths: [`${REPOS_DIR}/${name}`]
-						}).pipe(Effect.mapError(asSubmoduleError(`git submodule update --init --depth 1 -- ${REPOS_DIR}/${name}`, root)));
+							paths: [repoPathRel]
+						}).pipe(Effect.mapError(asSubmoduleError(`git submodule update --init --depth 1 -- ${repoPathRel}`, root)));
 						initialized.push(name);
 					} else upToDate.push(name);
 					if (entry.sparse && entry.sparse.length > 0) {
@@ -124,7 +172,9 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				initialized,
 				sparseApplied,
 				upToDate,
-				clearedLocks
+				clearedLocks,
+				urlSynced,
+				registered
 			};
 		});
 		/** Last path segment of a repo URL, with a trailing `.git` stripped. */
@@ -154,23 +204,82 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				kind: "invalid"
 			})));
 			const manifest = yield* configStore.read(root).pipe(Effect.catchTag("ReposConfigError", (error) => error.kind === "missing" ? Effect.succeed({ repos: {} }) : Effect.fail(error)));
-			if (manifest.repos[name]) return yield* Effect.fail(new ReposConfigError({
+			if (getRepoEntry(manifest.repos, name)) return yield* Effect.fail(new ReposConfigError({
 				path: MANIFEST_PATH,
 				reason: `"${name}" is already vendored — use pin to change its ref`,
 				kind: "invalid"
 			}));
 			const repoPath = `${REPOS_DIR}/${name}`;
 			const subPath = path.join(root, repoPath);
+			const remoteRefs = yield* git.lsRemote(root, options.url, {
+				heads: true,
+				tags: true
+			}).pipe(Effect.mapError(asSubmoduleError(`git ls-remote --heads --tags ${options.url}`, root)));
+			if (!remoteRefs.some((remoteRef) => LsRemoteEntry.shortName(remoteRef.ref) === options.ref)) {
+				const suggestionNames = LsRemoteEntry.nearMatches(remoteRefs, options.ref).map((match) => LsRemoteEntry.shortName(match.ref));
+				const suggestions = [...new Set(suggestionNames)].slice(0, 5);
+				const reason = suggestions.length > 0 ? `ref "${options.ref}" not found at ${options.url}; did you mean: ${suggestions.join(", ")}?` : `ref "${options.ref}" not found at ${options.url}`;
+				return yield* Effect.fail(new GitSubmoduleError({
+					command: `git ls-remote --heads --tags ${options.url}`,
+					cwd: root,
+					reason
+				}));
+			}
+			const gitmodulesPath = path.join(root, ".gitmodules");
 			yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
-				yield* git.submoduleAdd(root, {
-					url: options.url,
-					path: repoPath,
-					depth: 1
-				}).pipe(Effect.mapError(asSubmoduleError(`git submodule add --depth 1 ${options.url} ${repoPath}`, root)));
-				yield* git.configSet(root, `submodule.${repoPath}.shallow`, "true", { file: ".gitmodules" }).pipe(Effect.mapError(asSubmoduleError(`git config -f .gitmodules submodule.${repoPath}.shallow true`, root)));
-				yield* fetchRef(subPath, options.ref);
-				yield* git.checkout(subPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", subPath)));
-				if (options.sparse && options.sparse.length > 0) yield* git.sparseCheckoutSet(subPath, options.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", subPath)));
+				const gitmodulesTextOption = yield* fs.readFileString(gitmodulesPath).pipe(Effect.option);
+				let existingGitmodulesEntry;
+				if (Option.isSome(gitmodulesTextOption)) existingGitmodulesEntry = (yield* Gitmodules.parse(gitmodulesTextOption.value).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)))).entries.find((candidate) => candidate.path === repoPath);
+				const gitlinkStaged = (yield* git.lsFiles(root, { pathspec: [repoPath] }).pipe(Effect.mapError(asSubmoduleError(`git ls-files --stage -- ${repoPath}`, root)))).some((stagedEntry) => stagedEntry.mode === "160000");
+				let resuming = false;
+				if (existingGitmodulesEntry && gitlinkStaged) {
+					if (existingGitmodulesEntry.url !== options.url) return yield* Effect.fail(new ReposConfigError({
+						path: gitmodulesPath,
+						reason: `"${name}" already has a partial submodule at ${repoPath} registered to a different url (${existingGitmodulesEntry.url}) than requested (${options.url}) — resolve the conflict manually before retrying add`,
+						kind: "invalid"
+					}));
+					resuming = true;
+				}
+				const rollbackStep = (step, effect) => effect.pipe(Effect.asVoid, Effect.catch((rollbackError) => Effect.logWarning(`repos add rollback for "${name}" — ${step} failed: ${String(rollbackError)}`)));
+				const rollback = (cause) => Effect.gen(function* () {
+					const moduleDir = yield* resolveModuleDir(fs, path, root, name);
+					yield* rollbackStep("submodule deinit", git.submoduleDeinit(root, {
+						paths: [repoPath],
+						force: true
+					}));
+					yield* rollbackStep("rm --cached", git.rm(root, [repoPath], { cached: true }));
+					yield* rollbackStep("remove worktree", fs.remove(subPath, {
+						recursive: true,
+						force: true
+					}));
+					yield* rollbackStep("remove module gitdir", fs.remove(moduleDir, {
+						recursive: true,
+						force: true
+					}));
+					const currentGitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.option);
+					if (Option.isSome(currentGitmodulesText)) {
+						const parsedForRollback = yield* Gitmodules.parse(currentGitmodulesText.value).pipe(Effect.option);
+						const section = Option.isSome(parsedForRollback) ? parsedForRollback.value.entries.find((candidate) => candidate.name === repoPath) ?? parsedForRollback.value.entries.find((candidate) => candidate.path === repoPath) : void 0;
+						if (section) {
+							const configResult = GitConfig.parseResult(currentGitmodulesText.value);
+							if (Result.isSuccess(configResult)) {
+								const removeResult = Gitmodules.remove(configResult.success, section.name);
+								if (Result.isSuccess(removeResult)) yield* rollbackStep("restore .gitmodules", fs.writeFileString(gitmodulesPath, removeResult.success.stringify()));
+							}
+						}
+					}
+				}).pipe(Effect.andThen(Effect.fail(cause)));
+				yield* Effect.gen(function* () {
+					if (!resuming) yield* git.submoduleAdd(root, {
+						url: options.url,
+						path: repoPath,
+						depth: 1
+					}).pipe(Effect.mapError(asSubmoduleError(`git submodule add --depth 1 ${options.url} ${repoPath}`, root)));
+					yield* git.configSet(root, `submodule.${repoPath}.shallow`, "true", { file: ".gitmodules" }).pipe(Effect.mapError(asSubmoduleError(`git config -f .gitmodules submodule.${repoPath}.shallow true`, root)));
+					yield* fetchRef(subPath, options.ref);
+					yield* git.checkout(subPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", subPath)));
+					if (options.sparse && options.sparse.length > 0) yield* git.sparseCheckoutSet(subPath, options.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", subPath)));
+				}).pipe(Effect.catch(rollback));
 			}));
 			const entry = {
 				url: options.url,
@@ -178,10 +287,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				purpose: options.purpose,
 				...options.sparse && options.sparse.length > 0 ? { sparse: options.sparse } : {}
 			};
-			yield* configStore.write(root, { repos: {
-				...manifest.repos,
+			yield* configStore.update(root, (fresh) => ({ repos: {
+				...fresh.repos,
 				[name]: entry
-			} });
+			} }));
 			yield* git.add(root, [
 				".gitmodules",
 				MANIFEST_PATH,
@@ -195,7 +304,7 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 		});
 		const pin = (root, name, ref) => Effect.gen(function* () {
 			const manifest = yield* configStore.read(root);
-			const entry = manifest.repos[name];
+			const entry = getRepoEntry(manifest.repos, name);
 			if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
 			const repoPath = `${REPOS_DIR}/${name}`;
 			const subPath = path.join(root, repoPath);
@@ -208,14 +317,27 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					newCommit: yield* git.revParse(subPath, "HEAD").pipe(Effect.mapError(asSubmoduleError("git rev-parse HEAD", subPath)))
 				};
 			}));
-			yield* configStore.write(root, { repos: {
-				...manifest.repos,
-				[name]: {
-					...entry,
-					ref
-				}
-			} });
-			yield* git.add(root, [MANIFEST_PATH, repoPath]).pipe(Effect.mapError(asSubmoduleError(`git add ${MANIFEST_PATH} ${repoPath}`, root)));
+			yield* configStore.update(root, (fresh) => {
+				const freshEntry = getRepoEntry(fresh.repos, name);
+				if (!freshEntry) return Effect.fail(new ReposConfigError({
+					path: path.join(root, MANIFEST_PATH),
+					reason: `pin applied to git but manifest entry "${name}" is gone; manifest and checkout now disagree`,
+					kind: "invalid"
+				}));
+				return Effect.succeed({ repos: {
+					...fresh.repos,
+					[name]: {
+						...freshEntry,
+						ref
+					}
+				} });
+			});
+			const gitmodulesChanged = (yield* git.status(root).pipe(Effect.mapError(asSubmoduleError("git status --porcelain", root)))).some((s) => s.path === ".gitmodules");
+			yield* git.add(root, gitmodulesChanged ? [
+				MANIFEST_PATH,
+				repoPath,
+				".gitmodules"
+			] : [MANIFEST_PATH, repoPath]).pipe(Effect.mapError(asSubmoduleError(gitmodulesChanged ? `git add ${MANIFEST_PATH} ${repoPath} .gitmodules` : `git add ${MANIFEST_PATH} ${repoPath}`, root)));
 			const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== ref).map((note) => note.id);
 			return {
 				name,
@@ -228,7 +350,7 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 		});
 		const note = (root, name, op) => Effect.gen(function* () {
 			const manifest = yield* configStore.read(root);
-			const entry = manifest.repos[name];
+			const entry = getRepoEntry(manifest.repos, name);
 			if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
 			const notes = entry.notes ?? [];
 			if (op.op === "add") {
@@ -269,10 +391,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					...entry,
 					notes: updatedNotes
 				};
-				yield* configStore.write(root, { repos: {
-					...manifest.repos,
+				yield* configStore.update(root, (fresh) => ({ repos: {
+					...fresh.repos,
 					[name]: updatedEntry
-				} });
+				} }));
 				return {
 					name,
 					op: "add",
@@ -291,10 +413,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					...entry,
 					notes: updatedNotes
 				};
-				yield* configStore.write(root, { repos: {
-					...manifest.repos,
+				yield* configStore.update(root, (fresh) => ({ repos: {
+					...fresh.repos,
 					[name]: updatedEntry
-				} });
+				} }));
 				return {
 					name,
 					op: "remove",
@@ -302,19 +424,21 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					noteCount: updatedNotes.length
 				};
 			}
+			const existing = entry.orientation?.[op.into];
+			const promoted = existing === void 0 ? target.note : `${existing}\n\n${target.note}`;
 			const updatedOrientation = {
 				...entry.orientation,
-				[op.into]: target.note
+				[op.into]: promoted
 			};
 			const updatedEntry = {
 				...entry,
 				orientation: updatedOrientation,
 				notes: updatedNotes
 			};
-			yield* configStore.write(root, { repos: {
-				...manifest.repos,
+			yield* configStore.update(root, (fresh) => ({ repos: {
+				...fresh.repos,
 				[name]: updatedEntry
-			} });
+			} }));
 			return {
 				name,
 				op: "promote",
@@ -322,12 +446,190 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				noteCount: updatedNotes.length
 			};
 		});
+		const remove = (root, name) => Effect.gen(function* () {
+			const manifest = yield* configStore.read(root);
+			const entry = getRepoEntry(manifest.repos, name);
+			if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
+			const repoPath = `${REPOS_DIR}/${name}`;
+			const subPath = path.join(root, repoPath);
+			const moduleDir = yield* resolveModuleDir(fs, path, root, name);
+			yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
+				yield* git.submoduleDeinit(root, {
+					paths: [repoPath],
+					force: true
+				}).pipe(Effect.mapError(asSubmoduleError(`git submodule deinit --force -- ${repoPath}`, root)));
+				yield* git.rm(root, [repoPath], { cached: true }).pipe(Effect.mapError(asSubmoduleError(`git rm --cached ${repoPath}`, root)));
+				yield* fs.remove(subPath, {
+					recursive: true,
+					force: true
+				}).pipe(Effect.mapError((cause) => new GitSubmoduleError({
+					command: "remove worktree",
+					cwd: subPath,
+					reason: String(cause)
+				})));
+				yield* fs.remove(moduleDir, {
+					recursive: true,
+					force: true
+				}).pipe(Effect.mapError((cause) => new GitSubmoduleError({
+					command: "remove module gitdir",
+					cwd: moduleDir,
+					reason: String(cause)
+				})));
+			}));
+			const gitmodulesPath = path.join(root, ".gitmodules");
+			const gitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.mapError(asSubmoduleError("read .gitmodules", gitmodulesPath)));
+			const parsedGitmodules = yield* Gitmodules.parse(gitmodulesText).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)));
+			const section = parsedGitmodules.entries.find((candidate) => candidate.name === repoPath) ?? parsedGitmodules.entries.find((candidate) => candidate.path === repoPath);
+			if (!section) return yield* Effect.fail(new ReposConfigError({
+				path: gitmodulesPath,
+				reason: `no .gitmodules section found for "${name}" (looked for name or path "${repoPath}")`,
+				kind: "invalid"
+			}));
+			const configResult = GitConfig.parseResult(gitmodulesText);
+			if (Result.isFailure(configResult)) return yield* Effect.fail(asSubmoduleError("parse .gitmodules", gitmodulesPath)(configResult.failure));
+			const removeResult = Gitmodules.remove(configResult.success, section.name);
+			if (Result.isFailure(removeResult)) return yield* Effect.fail(asSubmoduleError(`gitmodules remove ${section.name}`, gitmodulesPath)(removeResult.failure));
+			yield* fs.writeFileString(gitmodulesPath, removeResult.success.stringify()).pipe(Effect.mapError(asSubmoduleError("write .gitmodules", gitmodulesPath)));
+			yield* configStore.update(root, (fresh) => {
+				const { [name]: _dropped, ...rest } = fresh.repos;
+				return { repos: rest };
+			});
+			yield* git.add(root, [".gitmodules", MANIFEST_PATH]).pipe(Effect.mapError(asSubmoduleError(`git add .gitmodules ${MANIFEST_PATH}`, root)));
+			return {
+				name,
+				path: repoPath,
+				commitMessage: `chore(repos): remove ${name}`,
+				removedNotes: entry.notes ?? []
+			};
+		});
+		const rename = (root, oldName, newName) => Effect.gen(function* () {
+			const manifest = yield* configStore.read(root);
+			if (!getRepoEntry(manifest.repos, oldName)) return yield* Effect.fail(new RepoNotFoundError({ name: oldName }));
+			yield* Schema.decodeUnknownEffect(RepoName)(newName).pipe(Effect.mapError(() => new ReposConfigError({
+				path: MANIFEST_PATH,
+				reason: `invalid repo name "${newName}": must be non-empty, contain no "/" or "\\", and not be "." or ".."`,
+				kind: "invalid"
+			})));
+			if (getRepoEntry(manifest.repos, newName)) return yield* Effect.fail(new ReposConfigError({
+				path: MANIFEST_PATH,
+				reason: `"${newName}" is already vendored — choose a different name`,
+				kind: "invalid"
+			}));
+			const oldRepoPath = `${REPOS_DIR}/${oldName}`;
+			const newRepoPath = `${REPOS_DIR}/${newName}`;
+			const gitmodulesPath = path.join(root, ".gitmodules");
+			const moduleDir = yield* resolveModuleDir(fs, path, root, oldName);
+			yield* Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+				const unlockExit = yield* Effect.exit(lockdown.unlock(root, oldName));
+				let lockName = oldName;
+				const resultExit = Exit.isFailure(unlockExit) ? Exit.failCause(unlockExit.cause) : yield* Effect.exit(restore(Effect.gen(function* () {
+					yield* git.mv(root, oldRepoPath, newRepoPath).pipe(Effect.mapError(asSubmoduleError(`git mv ${oldRepoPath} ${newRepoPath}`, root)));
+					lockName = newName;
+					const absoluteNewSubPath = path.resolve(root, newRepoPath);
+					const worktreeValue = path.relative(moduleDir, absoluteNewSubPath);
+					yield* git.configSet(root, "core.worktree", worktreeValue, { file: path.join(moduleDir, "config") }).pipe(Effect.mapError(asSubmoduleError("git config core.worktree", moduleDir)));
+					const worktreeConfigPath = path.join(moduleDir, "config.worktree");
+					if (yield* fs.exists(worktreeConfigPath).pipe(Effect.orElseSucceed(() => false))) yield* git.configSet(root, "core.worktree", worktreeValue, { file: worktreeConfigPath }).pipe(Effect.mapError(asSubmoduleError("git config -f config.worktree core.worktree", moduleDir)));
+					const gitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.mapError(asSubmoduleError("read .gitmodules", gitmodulesPath)));
+					const section = (yield* Gitmodules.parse(gitmodulesText).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)))).entries.find((candidate) => candidate.path === newRepoPath);
+					if (!section) return yield* Effect.fail(new ReposConfigError({
+						path: gitmodulesPath,
+						reason: `no .gitmodules section found for "${newName}" after mv (looked for path "${newRepoPath}")`,
+						kind: "invalid"
+					}));
+					if (section.name !== newRepoPath) {
+						const oldSectionName = section.name;
+						const configResult = GitConfig.parseResult(gitmodulesText);
+						if (Result.isFailure(configResult)) return yield* Effect.fail(asSubmoduleError("parse .gitmodules", gitmodulesPath)(configResult.failure));
+						const renameResult = Gitmodules.rename(configResult.success, oldSectionName, newRepoPath);
+						if (Result.isFailure(renameResult)) return yield* Effect.fail(asSubmoduleError(`gitmodules rename ${oldSectionName} -> ${newRepoPath}`, gitmodulesPath)(renameResult.failure));
+						yield* fs.writeFileString(gitmodulesPath, renameResult.success.stringify()).pipe(Effect.mapError(asSubmoduleError("write .gitmodules", gitmodulesPath)));
+						yield* git.add(root, [".gitmodules"]).pipe(Effect.mapError(asSubmoduleError("git add .gitmodules", root)));
+						const unsetIfPresent = (key) => git.configGet(root, key).pipe(Effect.mapError(asSubmoduleError(`git config --get ${key}`, root)), Effect.flatMap((current) => Option.isSome(current) ? git.configUnset(root, key).pipe(Effect.mapError(asSubmoduleError(`git config --unset ${key}`, root))) : Effect.void));
+						yield* unsetIfPresent(`submodule.${oldSectionName}.url`);
+						yield* unsetIfPresent(`submodule.${oldSectionName}.active`);
+					}
+					yield* git.submoduleInit(root, { paths: [newRepoPath] }).pipe(Effect.mapError(asSubmoduleError(`git submodule init -- ${newRepoPath}`, root)));
+					yield* configStore.update(root, (fresh) => {
+						const renamedEntry = getRepoEntry(fresh.repos, oldName);
+						if (!renamedEntry) return Effect.fail(new ReposConfigError({
+							path: MANIFEST_PATH,
+							reason: `rename applied to git but manifest entry "${oldName}" is gone; manifest and .gitmodules now disagree`,
+							kind: "invalid"
+						}));
+						const { [oldName]: _dropped, ...rest } = fresh.repos;
+						return { repos: {
+							...rest,
+							[newName]: renamedEntry
+						} };
+					});
+					yield* git.add(root, [MANIFEST_PATH]).pipe(Effect.mapError(asSubmoduleError(`git add ${MANIFEST_PATH}`, root)));
+					yield* git.submoduleStatus(root).pipe(Effect.mapError(asSubmoduleError("git submodule status", root)));
+				})));
+				const relockExit = yield* Effect.exit(lockdown.lock(root, lockName));
+				if (Exit.isFailure(resultExit)) return yield* Exit.failCause(resultExit.cause);
+				if (Exit.isFailure(relockExit)) return yield* Exit.failCause(relockExit.cause);
+			}));
+			return {
+				oldName,
+				newName,
+				path: newRepoPath,
+				commitMessage: `chore(repos): rename ${oldName} to ${newName}`
+			};
+		});
+		const restore = (root, names) => Effect.gen(function* () {
+			const manifest = yield* configStore.read(root);
+			let targetNames;
+			let skippedClean = [];
+			if (names && names.length > 0) {
+				for (const name of names) if (!getRepoEntry(manifest.repos, name)) return yield* Effect.fail(new RepoNotFoundError({ name }));
+				targetNames = names;
+			} else {
+				const report = yield* status(root);
+				targetNames = report.repos.filter((entry) => entry.dirty).map((entry) => entry.name);
+				skippedClean = report.repos.filter((entry) => !entry.dirty).map((entry) => entry.name);
+			}
+			const restored = [];
+			for (const name of targetNames) {
+				const entry = getRepoEntry(manifest.repos, name);
+				if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
+				const repoPath = `${REPOS_DIR}/${name}`;
+				const subPath = path.join(root, repoPath);
+				const commit = yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
+					let targetCommit = (yield* git.lsFiles(root, { pathspec: [repoPath] }).pipe(Effect.mapError(asSubmoduleError(`git ls-files --stage -- ${repoPath}`, root)))).find((lsFilesEntry) => lsFilesEntry.mode === "160000")?.oid;
+					if (targetCommit === void 0) targetCommit = (yield* git.lsTree(root, "HEAD", { pathspec: [repoPath] }).pipe(Effect.mapError(asSubmoduleError(`git ls-tree HEAD -- ${repoPath}`, root))))[0]?.oid;
+					if (targetCommit === void 0) return yield* Effect.fail(new GitSubmoduleError({
+						command: "resolve restore target commit",
+						cwd: subPath,
+						reason: `no staged or committed gitlink commit found for "${name}" -- nothing to restore to`
+					}));
+					yield* git.reset(subPath, {
+						mode: "hard",
+						ref: targetCommit
+					}).pipe(Effect.mapError(asSubmoduleError(`git reset --hard ${targetCommit}`, subPath)));
+					yield* git.clean(subPath, { directories: true }).pipe(Effect.mapError(asSubmoduleError("git clean --force -d", subPath)));
+					if (entry.sparse && entry.sparse.length > 0) yield* git.sparseCheckoutSet(subPath, entry.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", subPath)));
+					return targetCommit;
+				}));
+				restored.push({
+					name,
+					commit
+				});
+			}
+			return {
+				restored,
+				skippedClean
+			};
+		});
 		return {
 			status,
 			sync,
 			add,
 			pin,
-			note
+			note,
+			remove,
+			rename,
+			restore
 		};
 	}));
 };