@cldmv/git-embedded 1.0.0 → 1.1.1

package/hooks/reference-transaction

@@ -1,54 +1,155 @@
 #!/usr/bin/env bash
 # reference-transaction
 #
-# Refuses HEAD-moving git operations if any embedded git repo in the parent's
-# tree has uncommitted changes. Without this, a `git checkout B` in the parent
-# would silently leave the child stale (with the post-checkout updater unable
-# to update over dirty state), producing a confusing inconsistent state.
+# Guards HEAD-moving git operations against harming embedded child repos.
+# The companion update-embedded-repos hook (post-checkout/-merge/-rewrite)
+# force-syncs every child to the pin recorded in the parent's new HEAD; this
+# hook refuses, up-front, the moves where that sync (or the move itself)
+# would confuse or destroy in-flight child work.
 #
-# Requires git 2.28+ (released July 2020, when reference-transaction was
-# introduced).
+# IMPORTANT PLUMBING FACT: a plain `git commit` moves the ref HEAD points to,
+# reported in the reference transaction as HEAD (git <=2.43) or as the branch
+# ref refs/heads/<branch> (git 2.54+) — the guard watches BOTH. Either way,
+# "HEAD moved" alone cannot distinguish a commit from a checkout, so the mode
+# logic below reasons about what the move would actually DO to each child, and
+# classifies append-vs-jump by commit parentage where it matters.
 #
-# Phases (passed as $1 by git):
-#   - prepared:  updates queued, not yet applied. Exiting non-zero ABORTS the
-#                transaction. This is the only phase we act on.
-#   - committed: updates already applied (informational; we ignore).
-#   - aborted:   updates rejected by some other handler (informational).
+# Mode (git config embedded.guard — local overrides global; default precise):
+#   precise  Block only when a DIRTY child's HEAD differs from the pin in the
+#            NEW commit — i.e. exactly when update-embedded-repos would try to
+#            move a child that has uncommitted changes. Clean children, and
+#            dirty children whose pin already equals their HEAD (the sync
+#            no-ops), never block.
+#   strict   The everything-synced policy. Any dirty child blocks any HEAD
+#            move. Additionally, on APPENDS (commit/merge/cherry-pick — the
+#            new commit lists the old HEAD among its parents) every child's
+#            pin in the new commit must equal that child's current HEAD, so a
+#            parent commit can never ship stale pins. Jumps (checkout/reset)
+#            only require all-clean: their pins are EXPECTED to differ, and
+#            the post-hook sync moves the (clean) children afterwards.
+#   off      No guarding.
 #
-# The hook reads proposed ref updates from stdin, one per line:
-#   <old_sha> <new_sha> <ref-name>
+# One-shot override:  git -c embedded.guard=<mode> <command>
 #
-# We filter to HEAD updates with old != new (an actual HEAD move). Other ref
-# updates (branch fast-forwards from fetch, stash refs, tag creation, etc.)
-# don't touch the working tree and shouldn't be guarded.
-
-# Only the 'prepared' phase can reject the transaction.
+# Requires git 2.28+ (reference-transaction hook).
+#
+# Phases (passed as $1 by git): only 'prepared' can reject the transaction.
 [ "$1" = "prepared" ] || exit 0
 
-# Detect whether any update in this transaction moves HEAD.
-moving_head=0
+guard_mode=$(git config --get embedded.guard 2>/dev/null)
+case "$guard_mode" in
+off) exit 0 ;;
+strict | precise) ;;
+*) guard_mode="precise" ;;
+esac
+
+# Anchor every git command we run INSIDE a child to the child's own repo:
+# GIT_CEILING_DIRECTORIES stops repo discovery from walking UP into this parent,
+# so a child with a broken/corrupt .git fails cleanly here (empty HEAD, no
+# symref) instead of silently resolving the PARENT repo's HEAD.
+parent_root=$(pwd)
+child_git() (
+    cd "$1" 2>/dev/null || return 1
+    shift
+    GIT_CEILING_DIRECTORIES="$parent_root" git "$@"
+)
+
+# Detect a HEAD move and capture its endpoints. Stdin lines:
+#   <old_sha> <new_sha> <ref-name>
+# Other ref updates (fetch fast-forwards, stash refs, tags) don't touch the
+# working tree and aren't guarded.
+zeros="0000000000000000000000000000000000000000"
+# The ref a working-tree HEAD move touches is either literal HEAD (a detached
+# checkout, or a commit on a detached HEAD) or — when HEAD is on a branch — the
+# BRANCH ref HEAD points to. git <=2.43 emitted a redundant HEAD line for a
+# commit, so matching "HEAD" alone sufficed; git 2.54 emits ONLY the branch ref
+# (refs/heads/<branch>) for a commit, so without also matching the current
+# branch every commit slips past the guard. Resolve HEAD's branch and watch both.
+head_ref=$(git symbolic-ref --quiet HEAD 2>/dev/null)
+moving=0
+old_head=""
+new_head=""
 while read old_sha new_sha ref; do
-    [ "$ref" = "HEAD" ] || continue
+    [ "$ref" = "HEAD" ] || { [ -n "$head_ref" ] && [ "$ref" = "$head_ref" ]; } || continue
     [ "$old_sha" = "$new_sha" ] && continue
-    moving_head=1
+    moving=1
+    old_head=$old_sha
+    new_head=$new_sha
 done
+[ "$moving" = "1" ] || exit 0
+[ -n "$new_head" ] && [ "$new_head" != "$zeros" ] || exit 0
 
-# Nothing to check if HEAD is not moving.
-[ "$moving_head" = "1" ] || exit 0
+# Append vs jump (strict mode only cares): an append's new commit lists the
+# CURRENT (pre-move) HEAD among its parents — commit, merge, cherry-pick step.
+# The pre-move HEAD is resolved directly rather than trusting the transaction
+# line's old value: a checkout-to-SHA (detach) reports its HEAD line with the
+# null SHA on the old side, which must NOT read as "initial commit". An unborn
+# HEAD (the real initial commit) counts as an append. Known edge: switching to
+# a branch whose tip is a direct child of the current HEAD is indistinguishable
+# from a commit by parentage and is treated as an append; in strict mode use
+# `git -c embedded.guard=precise checkout …` if that blocks a legitimate move.
+is_append=0
+current_head=$(git rev-parse -q --verify "HEAD^{commit}" 2>/dev/null)
+if [ -z "$current_head" ]; then
+    is_append=1
+else
+    for parent in $(git rev-list --parents -n 1 "$new_head" 2>/dev/null | cut -d' ' -f2-); do
+        [ "$parent" = "$current_head" ] && is_append=1
+    done
+fi
 
-# Walk every gitlink in the current HEAD and check for dirty state.
-# A gitlink is a tree entry with type 'commit' (mode 160000). The path is
-# the directory in the parent's working tree that holds the embedded repo.
-while read mode type sha path; do
-    [ "$type" = "commit" ] || continue
+# Walk every gitlink in the NEW commit — those pins are what the post-hook
+# sync will enforce after the move. Tree entries from `git ls-tree -r`:
+#   <mode> SP <type> SP <sha> TAB <path>
+block=0
+# Split ls-tree output on the TAB so a child path containing spaces stays intact
+# (the meta side, `<mode> <type> <sha>`, is space-separated and re-split below).
+while IFS=$'\t' read -r meta path; do
+    set -- $meta
+    entry_type=$2
+    pin=$3
+    [ "$entry_type" = "commit" ] || continue
     [ -d "$path/.git" ] || [ -f "$path/.git" ] || continue
 
-    # Refuse if there are uncommitted changes inside the embedded repo.
-    if ! (cd "$path" && git diff-index --quiet HEAD --) 2>/dev/null; then
-        echo "git-embedded: ✗ $path has uncommitted changes" >&2
-        echo "  commit or stash inside $path/ before moving HEAD here" >&2
-        exit 1
+    # --verify: fail cleanly with EMPTY stdout when HEAD can't resolve (plain
+    # `rev-parse HEAD` echoes the literal "HEAD" on an unborn branch, which would
+    # slip past the emptiness check below and be misread as a dirty child).
+    child_head=$(child_git "$path" rev-parse --verify HEAD 2>/dev/null)
+    if [ -z "$child_head" ]; then
+        # HEAD is unreadable. Distinguish a legitimately UNBORN child (fresh
+        # `git init`, no commits yet — HEAD is still a valid symref to a branch)
+        # from a genuinely broken/corrupt repo (neither a commit nor a symref
+        # resolves). An unborn child has nothing to guard, so skip it. In strict
+        # mode, fail closed on a broken one rather than silently waving it through;
+        # precise stays lenient and skips either way.
+        if [ "$guard_mode" = "strict" ] && ! child_git "$path" symbolic-ref --quiet HEAD >/dev/null 2>&1; then
+            echo "git-embedded: ✗ $path — cannot read HEAD (missing or corrupt repo?) (embedded.guard=strict)" >&2
+            echo "  fix or re-restore the child at '$path'/, or bypass once with -c embedded.guard=off" >&2
+            block=1
+        fi
+        continue
+    fi
+    dirty=0
+    child_git "$path" diff-index --quiet HEAD -- 2>/dev/null || dirty=1
+
+    if [ "$guard_mode" = "strict" ]; then
+        if [ "$dirty" = "1" ]; then
+            echo "git-embedded: ✗ $path has uncommitted changes (embedded.guard=strict)" >&2
+            echo "  commit or stash inside '$path'/ before moving HEAD here" >&2
+            block=1
+        elif [ "$is_append" = "1" ] && [ "$child_head" != "$pin" ]; then
+            echo "git-embedded: ✗ $path is not synced: pin ${pin:0:12} != child HEAD ${child_head:0:12} (embedded.guard=strict)" >&2
+            echo "  record the child's current commit (git add -- '$path') or move the child to the pin before committing the parent" >&2
+            block=1
+        fi
+    else # precise
+        if [ "$dirty" = "1" ] && [ "$child_head" != "$pin" ]; then
+            echo "git-embedded: ✗ $path has uncommitted changes and this move would re-pin it (${child_head:0:12} → ${pin:0:12})" >&2
+            echo "  commit or stash inside '$path'/ before moving HEAD here" >&2
+            block=1
+        fi
     fi
-done < <(git ls-tree -r HEAD 2>/dev/null)
+done < <(git ls-tree -r "$new_head" 2>/dev/null)
 
+[ "$block" = "1" ] && exit 1
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/git-embedded",
-	"version": "1.0.0",
+	"version": "1.1.1",
 	"description": "Manage embedded git repositories (anonymous gitlinks) without .gitmodules. Provides hooks that restore standard git-command ergonomics for embedded children while keeping the child's origin URL out of the public parent repo.",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -67,9 +67,11 @@
 	},
 	"scripts": {
 		"start": "node bin/git-embedded.mjs",
-		"test": "vitest run --config .configs/vitest.config.mjs",
+		"build:ci": "echo '✓ no build step'",
+		"test": "node tests/run-vitest.mjs",
 		"test:watch": "vitest --config .configs/vitest.config.mjs",
-		"coverage": "vitest run --coverage --config .configs/vitest.config.mjs",
+		"coverage": "node tests/run-vitest.mjs --coverage-quiet",
+		"ci:coverage": "npm run coverage",
 		"lint": "eslint --config .configs/eslint.config.mjs .",
 		"lint:fix": "eslint --config .configs/eslint.config.mjs . --fix",
 		"format": "prettier --config .configs/.prettierrc --write .",
@@ -84,13 +86,14 @@
 		"marked-terminal": "^7.3.0"
 	},
 	"devDependencies": {
+		"@cldmv/vitest-runner": "^1.2.0",
 		"@eslint/js": "^9.18.0",
 		"@eslint/json": "^0.10.0",
 		"@eslint/markdown": "^6.2.2",
-		"@vitest/coverage-v8": "^2.1.9",
+		"@vitest/coverage-v8": "^4.1.10",
 		"eslint": "^9.18.0",
 		"globals": "^15.14.0",
 		"prettier": "^3.4.2",
-		"vitest": "^2.1.9"
+		"vitest": "^4.1.10"
 	}
 }

package/src/api/cli/export.mjs

@@ -0,0 +1,71 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "export",
+	description:
+		"Serialize the local-config registry to a manifest JSON (stdout by default). The manifest is a TRANSFER FILE — carry it out-of-band and NEVER commit it; committing child URLs defeats anonymous gitlinks.",
+	options: [
+		["-o <file>", "Write the manifest to <file> instead of stdout"],
+		["--scan", "Record every present child (like 'record') before exporting"]
+	],
+	examples: ["$ git-embedded export", "$ git-embedded export -o children.json", "$ git-embedded export --scan -o children.json"]
+};
+
+/**
+ * Append `relPath` to the repo's `.git/info/exclude` if not already listed, so a
+ * manifest written inside the worktree is not accidentally staged.
+ * @param {string} gitDir absolute git dir
+ * @param {string} relPath worktree-relative path to exclude
+ * @returns {boolean} true when a new line was added
+ */
+function addToExclude(gitDir, relPath) {
+	const { fs, path } = context;
+	const exclude = path.join(gitDir, "info", "exclude");
+	let body = "";
+	try {
+		body = fs.readFileSync(exclude, "utf8");
+	} catch {
+		body = "";
+	}
+	const lines = body.split(/\r?\n/).map((l) => l.trim());
+	if (lines.includes(relPath) || lines.includes(`/${relPath}`)) return false;
+	fs.mkdirSync(path.dirname(exclude), { recursive: true });
+	const prefix = body.length === 0 || body.endsWith("\n") ? "" : "\n";
+	fs.appendFileSync(exclude, `${prefix}${relPath}\n`);
+	return true;
+}
+
+export function run(opts = {}) {
+	const { fs, path } = context;
+	const cwd = process.cwd();
+	const root = self.git.getRepoRoot(cwd) || cwd;
+
+	if (opts.scan) self.embedded.record({ cwd });
+
+	const entries = self.embedded.registry.entries(root);
+	const manifest = self.embedded.manifest.build(entries);
+	const text = self.embedded.manifest.serialize(manifest);
+
+	const outFile = opts.o;
+	if (!outFile) {
+		process.stdout.write(text);
+		return;
+	}
+
+	const abs = path.isAbsolute(outFile) ? outFile : path.resolve(cwd, outFile);
+	fs.mkdirSync(path.dirname(abs), { recursive: true });
+	fs.writeFileSync(abs, text);
+	self.report.success(`Wrote manifest to ${abs} (${Object.keys(manifest.children).length} children).`);
+	self.report.warn("This manifest contains child URLs — do NOT commit it. Carry it out-of-band.");
+
+	const rel = path.relative(root, abs);
+	const insideWorktree = rel && !rel.startsWith("..") && !path.isAbsolute(rel);
+	if (insideWorktree) {
+		const gitDir = self.git.getGitDir(cwd);
+		if (gitDir && addToExclude(gitDir, rel.split(path.sep).join("/"))) {
+			self.report.plain(`  (added ${rel} to .git/info/exclude as a courtesy)`);
+		}
+	}
+}
+
+export default { spec, run };

package/src/api/cli/init.mjs

@@ -19,6 +19,7 @@ export async function run(opts = {}) {
 	if (cfg.status === 0) {
 		self.report.success("Silenced 'embedded git repository' advice (git config advice.addEmbeddedRepo=false).");
 	} else {
+		/* v8 ignore next -- git normally writes config failures to stderr; the `|| stdout` fallback covers an empty-stderr failure (e.g. signal kill) — real, just not reproducible in the suite */
 		self.report.warn(`Could not set git config advice.addEmbeddedRepo: ${cfg.stderr || cfg.stdout}`);
 	}
 }

package/src/api/cli/install-hooks.mjs

@@ -105,6 +105,7 @@ async function bootstrapAndInstall(result, opts) {
 		if (out.fallbackToCopy.length > 0) self.report.warn(`Filesystem fallback to copy for ${out.fallbackToCopy.length} entries`);
 		const gitConfig = context.spawnSync("git", ["config", "--global", "core.hooksPath", dir], { encoding: "utf8" });
 		if (gitConfig.status !== 0) {
+			/* v8 ignore next -- git normally writes config failures to stderr; the `|| stdout` fallback covers an empty-stderr failure (e.g. signal kill) — real, just not reproducible in the suite */
 			self.report.error(`git config --global core.hooksPath failed: ${gitConfig.stderr || gitConfig.stdout}`);
 			process.exit(1);
 		}

package/src/api/cli/link.mjs

@@ -5,7 +5,7 @@ export const spec = {
 	description:
 		"Clone a remote repo into <local-path> and stage it as an anonymous gitlink. Does NOT commit (you may want to stage other things in the same commit).",
 	args: [
-		["<local-path>", "Where to clone the child repo (created if missing)"],
+		["<local-path>", "Where to clone the child repo (created if missing; an empty gitlink dir is accepted)"],
 		["<remote-url>", "The child repo's clone URL (will NOT be recorded in .gitmodules)"]
 	],
 	examples: [
@@ -14,28 +14,75 @@ export const spec = {
 	]
 };
 
+/**
+ * Whether the target path blocks a fresh clone. A missing path is fine, and an
+ * empty REAL directory is fine (a fresh clone of the parent materializes each
+ * gitlink as an empty dir). Everything else is refused: a directory with
+ * contents, an existing repo, a file, an unreadable directory, or a SYMLINK —
+ * even one pointing at an empty dir, since cloning through it would write
+ * outside the repo. lstat so links are seen (and broken links caught), never
+ * followed.
+ * @param {string} target
+ * @returns {boolean}
+ */
+function blocksClone(target) {
+	const { fs } = context;
+	let st;
+	try {
+		st = fs.lstatSync(target);
+	} catch (err) {
+		// Only a missing path (ENOENT) is safe — git clone creates it.
+		return err.code !== "ENOENT";
+	}
+	if (st.isSymbolicLink() || !st.isDirectory()) return true;
+	try {
+		return fs.readdirSync(target).length > 0;
+	} catch {
+		return true; // unreadable directory
+	}
+}
+
 export function run(localPath, remoteUrl) {
-	const { fs, spawnSync } = context;
+	const { spawnSync, path } = context;
 
-	if (fs.existsSync(localPath)) {
-		self.report.error(`${localPath} already exists. Remove it or pick a different path before linking.`);
+	// Normalize to the repo-root-relative, slash-normalized gitlink path — the
+	// key restore/gitlinks/export all use. "./tests" or "tests/" must record as
+	// "tests", and a target outside the worktree is refused outright.
+	const root = self.git.getRepoRoot() || process.cwd();
+	const rel = path.relative(root, path.resolve(process.cwd(), localPath)).split(path.sep).join("/");
+	if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+		self.report.error(`${localPath} is outside the repository worktree — link inside the parent repo.`);
 		process.exit(2);
 	}
 
-	self.report.plain(`Cloning ${remoteUrl} into ${localPath}…`);
-	const clone = spawnSync("git", ["clone", remoteUrl, localPath], { stdio: "inherit" });
+	if (blocksClone(localPath)) {
+		self.report.error(`${localPath} exists and is not an empty directory. Remove it or pick a different path before linking.`);
+		process.exit(2);
+	}
+
+	self.report.plain(`Cloning ${remoteUrl} into ${rel}…`);
+	// `--` ends option parsing: a URL or path starting with "-" must never be
+	// interpreted as a git option (e.g. --upload-pack).
+	const clone = spawnSync("git", ["clone", "--", remoteUrl, localPath], { stdio: "inherit" });
 	if (clone.status !== 0) {
 		self.report.error(`git clone exited with status ${clone.status}`);
+		/* v8 ignore next -- spawnSync returns a null status on spawn failure (git not on PATH) or signal termination — the real case `|| 1` guards — but the suite always has git present, so it can't be reproduced here (ignored, not tested) */
 		process.exit(clone.status || 1);
 	}
 
-	const add = spawnSync("git", ["add", localPath], { stdio: "inherit" });
+	const add = spawnSync("git", ["add", "--", localPath], { stdio: "inherit" });
 	if (add.status !== 0) {
 		self.report.error(`git add ${localPath} exited with status ${add.status}`);
+		/* v8 ignore next -- spawnSync returns a null status on spawn failure (git not on PATH) or signal termination — the real case `|| 1` guards — but the suite always has git present, so it can't be reproduced here (ignored, not tested) */
 		process.exit(add.status || 1);
 	}
 
-	self.report.success(`Staged gitlink at ${localPath} (no .gitmodules entry written).`);
+	// Record the URL + branch into the parent's LOCAL config registry (never
+	// committed) so a later restore/export already knows this child — keyed by
+	// the NORMALIZED gitlink path so day-2 restore/export find it.
+	self.embedded.registry.recordOne(rel, root);
+
+	self.report.success(`Staged gitlink at ${rel} (no .gitmodules entry written).`);
 	self.report.plain("Commit when ready: git commit -m 'embed <name>'");
 }
 

package/src/api/cli/print-hook-script.mjs

@@ -6,6 +6,7 @@ const NAME_TO_SOURCE = {
 	"post-rewrite": "update-embedded-repos",
 	"reference-transaction": "reference-transaction",
 	"update-embedded-repos": "update-embedded-repos",
+	"pre-push": "pre-push",
 	_dispatch: "_dispatch.template",
 	dispatcher: "_dispatch.template"
 };

package/src/api/cli/record.mjs

@@ -0,0 +1,36 @@
+import { self } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "record",
+	description:
+		"Record the origin URL (and current branch) of each embedded child present on disk into the parent's LOCAL config registry, so a later export or re-restore does not have to re-derive it. The registry is never committed.",
+	args: [["[paths...]", "Restrict to these gitlink paths (default: every child present on disk)"]],
+	examples: ["$ git-embedded record", "$ git-embedded record tests vendor/foo"]
+};
+
+const LABEL = {
+	recorded: (r) => `${r.path} → ${r.url}${r.branch ? ` (${r.branch})` : ""}`,
+	"no-repo": (r) => `${r.path} not present on disk`,
+	"no-origin": (r) => `${r.path} has no remote.origin.url`
+};
+
+export function run(paths = []) {
+	const { results } = self.embedded.record({ cwd: process.cwd(), paths });
+
+	if (!results.length) {
+		self.report.plain("No embedded children present on disk to record.");
+		return;
+	}
+
+	for (const r of results) {
+		const line = LABEL[r.outcome] ? LABEL[r.outcome](r) : `${r.path}: ${r.outcome}`;
+		if (r.outcome === "recorded") self.report.success(line);
+		else self.report.warn(line);
+	}
+
+	const recorded = results.filter((r) => r.outcome === "recorded").length;
+	self.report.plain("");
+	self.report.success(`Recorded ${recorded} of ${results.length} into the local registry (not committed).`);
+}
+
+export default { spec, run };

package/src/api/cli/restore.mjs

@@ -0,0 +1,74 @@
+import { self } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "restore",
+	description:
+		"Clone missing embedded child repos and check out their pinned SHAs. Each child's URL is resolved strictest-first — local config, a manifest (--from), --base, then the parent's origin convention — and every clone is SHA-verified so a wrong guess fails closed. A branch from the registry/manifest (or inferred when exactly one origin branch contains the pin) puts the child ON that branch at the pin; otherwise the checkout is detached.",
+	args: [["[paths...]", "Restrict to these gitlink paths (default: every embedded gitlink)"]],
+	options: [
+		["--from <manifest>", "Read child URLs from a manifest JSON file (a transfer file; never committed)"],
+		["--base <url-base>", "Derive each child URL as <url-base>/<basename>.git"],
+		["--skip <paths>", "Comma-separated gitlink paths to skip (for a partial restore without access to a private child)"],
+		["--dry-run", "Report what would happen without cloning or writing config"]
+	],
+	examples: [
+		"$ git-embedded restore",
+		"$ git-embedded restore tests",
+		"$ git-embedded restore --from children.json",
+		"$ git-embedded restore --base git@example.com:org",
+		"$ git-embedded restore --skip tests --dry-run"
+	]
+};
+
+const LABEL = {
+	restored: (r) => `${r.dryRun ? "would restore" : "restored"} ${r.path} from ${r.source} (${r.url})${r.branch ? ` on branch ${r.branch}` : ""}`,
+	"already-present": (r) => `${r.path} already present`,
+	skipped: (r) => `${r.path} skipped`,
+	unresolved: (r) => `${r.path} unresolved${r.note ? ` — ${r.note}` : ""}`,
+	"pinned-mismatch": (r) => `${r.path} pinned-mismatch${r.note ? ` — ${r.note}` : ""}`
+};
+
+export function run(paths = [], opts = {}) {
+	const skip =
+		typeof opts.skip === "string"
+			? opts.skip
+					.split(",")
+					.map((s) => s.trim())
+					.filter(Boolean)
+			: [];
+
+	const { results, exitCode } = self.embedded.restore({
+		cwd: process.cwd(),
+		paths,
+		from: opts.from || null,
+		base: opts.base || null,
+		skip,
+		dryRun: Boolean(opts.dryRun)
+	});
+
+	if (!results.length) {
+		self.report.plain("No embedded gitlinks in HEAD.");
+		process.exit(0);
+	}
+
+	for (const r of results) {
+		const line = LABEL[r.outcome] ? LABEL[r.outcome](r) : `${r.path}: ${r.outcome}`;
+		if (r.outcome === "restored") self.report.success(line);
+		else if (r.outcome === "unresolved" || r.outcome === "pinned-mismatch") self.report.error(line);
+		else self.report.warn(line);
+	}
+
+	// Count each outcome into exactly one bucket — "unchanged" is only
+	// already-present, never a failure or a skip counted twice.
+	const restored = results.filter((r) => r.outcome === "restored").length;
+	const unchanged = results.filter((r) => r.outcome === "already-present").length;
+	const skipped = results.filter((r) => r.outcome === "skipped").length;
+	const failed = results.filter((r) => r.outcome === "unresolved" || r.outcome === "pinned-mismatch").length;
+	self.report.plain("");
+	self.report.plain(
+		`${restored} ${opts.dryRun ? "resolvable" : "restored"}, ${unchanged} unchanged${skipped ? `, ${skipped} skipped` : ""}, ${failed} failed.`
+	);
+	process.exit(exitCode);
+}
+
+export default { spec, run };

package/src/api/cli/sync.mjs

@@ -0,0 +1,70 @@
+import { self } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "sync",
+	description:
+		"Move already-present embedded children to the pins in the parent's HEAD (day-2, after pulling the parent — sync never touches the parent itself). Clean children follow the pin: the registered branch fast-forwards, a detached child snaps. Dirty children, commits beyond the pin, and unregistered branches are your work — reported and left alone.",
+	args: [["[paths...]", "Restrict to these gitlink paths (default: every embedded gitlink)"]],
+	options: [
+		["--skip <paths>", "Comma-separated gitlink paths to skip"],
+		["--dry-run", "Report what would happen without fetching or moving anything"]
+	],
+	examples: ["$ git pull && git-embedded sync", "$ git-embedded sync tests", "$ git-embedded sync --dry-run"]
+};
+
+const LABEL = {
+	synced: (r) =>
+		`${r.dryRun ? "would sync" : "synced"} ${r.path} → ${r.sha.slice(0, 12)}${r.branch ? ` (branch ${r.branch})` : " (detached)"}${r.note ? ` — ${r.note}` : ""}`,
+	"in-sync": (r) => `${r.path} already at pin`,
+	dirty: (r) => `${r.path} ${r.note}`,
+	ahead: (r) => `${r.path} ${r.note}`,
+	"unregistered-branch": (r) => `${r.path} ${r.note}`,
+	"pin-unavailable": (r) => `${r.path} pin-unavailable${r.note ? ` — ${r.note}` : ""}`,
+	"sync-failed": (r) => `${r.path} sync-failed${r.note ? ` — ${r.note}` : ""}`,
+	skipped: (r) => `${r.path} skipped`,
+	"no-repo": (r) => `${r.path} ${r.note}`
+};
+
+export function run(paths = [], opts = {}) {
+	const skip =
+		typeof opts.skip === "string"
+			? opts.skip
+					.split(",")
+					.map((s) => s.trim())
+					.filter(Boolean)
+			: [];
+
+	const { results, exitCode } = self.embedded.sync({
+		cwd: process.cwd(),
+		paths,
+		skip,
+		dryRun: Boolean(opts.dryRun)
+	});
+
+	if (!results.length) {
+		self.report.plain("No embedded children present to sync.");
+		process.exit(0);
+	}
+
+	for (const r of results) {
+		const line = LABEL[r.outcome] ? LABEL[r.outcome](r) : `${r.path}: ${r.outcome}`;
+		if (r.outcome === "synced") self.report.success(line);
+		else if (r.outcome === "pin-unavailable" || r.outcome === "sync-failed") self.report.error(line);
+		else self.report.warn(line);
+	}
+
+	// Each outcome lands in exactly one bucket; "left alone" collects the
+	// deliberate your-work outcomes, which are not failures.
+	const synced = results.filter((r) => r.outcome === "synced").length;
+	const unchanged = results.filter((r) => r.outcome === "in-sync").length;
+	const leftAlone = results.filter((r) => ["dirty", "ahead", "unregistered-branch"].includes(r.outcome)).length;
+	const skipped = results.filter((r) => ["skipped", "no-repo"].includes(r.outcome)).length;
+	const failed = results.filter((r) => r.outcome === "pin-unavailable" || r.outcome === "sync-failed").length;
+	self.report.plain("");
+	self.report.plain(
+		`${synced} ${opts.dryRun ? "syncable" : "synced"}, ${unchanged} unchanged, ${leftAlone} left alone${skipped ? `, ${skipped} skipped` : ""}, ${failed} failed.`
+	);
+	process.exit(exitCode);
+}
+
+export default { spec, run };

package/src/api/commander/custom-help.mjs

@@ -100,8 +100,11 @@ export function makeCustomHelp(HelpClass, deps) {
 				for (const ex of examples) {
 					const colored = ex.replace(argPattern, (match, p1, p2, p3, p4) => {
 						if (p2) return color(chalk.magenta, match);
+						/* v8 ignore else -- defensive: argPattern's two alternatives each
+						   require 1+ chars in their capture group, so a successful match
+						   always sets p2 or p4; the else has no reachable real input. */
 						if (p4) return color(chalk.yellow, match);
-						return match;
+						else return match;
 					});
 					output.push(`  ${colored}`);
 				}
@@ -197,6 +200,9 @@ function getFullCommandChain(cmd) {
 function wrapTextWithHangingIndent(text, indent, label, labelColor, width) {
 	const pad = "  ".repeat(indent);
 	const prefix = "- ";
+	/* v8 ignore next -- defensive: both call sites (Aliases/Description below)
+	   always pass a non-empty literal label, and this private helper has no
+	   other caller, so the empty-label fallback has no reachable real input. */
 	const labelStr = label ? label + ": " : "";
 	const hangingPad = pad + " ".repeat(prefix.length + labelStr.length);
 	const maxWidth = (width || process.stdout.columns || 80) - (pad.length + prefix.length + labelStr.length);