@cldmv/git-embedded 1.0.0

package/src/api/git.mjs

@@ -0,0 +1,59 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+function run(args, opts = {}) {
+	const res = context.spawnSync("git", args, { encoding: "utf8", ...opts });
+	return { code: res.status ?? 1, stdout: (res.stdout || "").trim(), stderr: (res.stderr || "").trim() };
+}
+
+/**
+ * Git inspection helpers — config lookup at each scope, repo-root / git-dir
+ * discovery, effective core.hooksPath resolution. All read-only.
+ *
+ * @namespace api.git
+ */
+
+export function getConfig(key, scope) {
+	const args = ["config"];
+	if (scope) args.push(`--${scope}`);
+	args.push("--get", key);
+	const res = run(args);
+	return res.code === 0 ? res.stdout : null;
+}
+
+export function getRepoRoot(cwd = process.cwd()) {
+	const res = run(["rev-parse", "--show-toplevel"], { cwd });
+	return res.code === 0 ? res.stdout : null;
+}
+
+export function getGitDir(cwd = process.cwd()) {
+	const res = run(["rev-parse", "--absolute-git-dir"], { cwd });
+	return res.code === 0 ? res.stdout : null;
+}
+
+export function getEffectiveHooksPath(cwd = process.cwd()) {
+	const { path, os } = context;
+	const res = context.spawnSync("git", ["config", "--get", "core.hooksPath"], { cwd, encoding: "utf8" });
+	if (res.status !== 0) return null;
+	const raw = (res.stdout || "").trim();
+	if (!raw) return null;
+	const expanded = raw.startsWith("~") ? path.join(os.homedir(), raw.slice(1)) : raw;
+	if (path.isAbsolute(expanded)) return expanded;
+	const root = getRepoRoot(cwd);
+	return root ? path.resolve(root, expanded) : path.resolve(cwd, expanded);
+}
+
+export function getAllHooksPathScopes(cwd = process.cwd()) {
+	void cwd;
+	return {
+		system: getConfig("core.hooksPath", "system"),
+		global: getConfig("core.hooksPath", "global"),
+		local: getConfig("core.hooksPath", "local")
+	};
+}
+
+export function getInitTemplateDir() {
+	const raw = getConfig("init.templateDir", "global");
+	if (!raw) return null;
+	const { path, os } = context;
+	return raw.startsWith("~") ? path.join(os.homedir(), raw.slice(1)) : raw;
+}

package/src/api/install/dispatcher.mjs

@@ -0,0 +1,51 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+import { STANDARD_HOOK_NAMES } from "../detect/dispatcher.mjs";
+
+/**
+ * Install or heal a canonical dispatcher.
+ *
+ * `op === "bootstrap"` writes `hooks/_dispatch.template` into the target
+ * directory and links every standard hook name to it. `op === "heal"` only
+ * adds missing entries, leaving the existing dispatcher script alone.
+ *
+ * @param {"bootstrap"|"heal"} op
+ * @param {object} target
+ * @param {string} [target.dir] destination directory (for bootstrap)
+ * @param {string} [target.dispatcherPath] existing dispatcher path (for heal)
+ * @param {string[]} [target.missing] hook names to add (for heal)
+ * @param {object} [opts]
+ * @param {boolean} [opts.noSymlinks]
+ * @param {string[]} [opts.hookNames] override for bootstrap (defaults to all standard hook names)
+ */
+export default function dispatcher(op, target, opts = {}) {
+	if (op === "bootstrap") return bootstrap(target.dir, opts);
+	if (op === "heal") return heal(target.dispatcherPath, target.missing, opts);
+	throw new Error(`install.dispatcher: unknown op "${op}" (expected "bootstrap" or "heal")`);
+}
+
+function bootstrap(dir, { noSymlinks = false, hookNames = STANDARD_HOOK_NAMES } = {}) {
+	const { fs, path } = context;
+	fs.mkdirSync(dir, { recursive: true });
+	const source = path.join(self.paths.hooksSourceDir(), "_dispatch.template");
+	const dest = path.join(dir, "_dispatch");
+	self.link.copyExecutable(source, dest, { overwrite: true });
+	self.log.append({ op: "install-dispatcher", path: dest });
+
+	const sources = hookNames.map((n) => path.join(dir, n));
+	const result = self.link.batch(dest, sources, { noSymlinks, overwrite: true });
+	for (const entry of result.created) {
+		self.log.append({ op: "install-dispatcher-link", path: entry.source, mechanism: entry.mechanism, target: dest });
+	}
+	return { dispatcherPath: dest, created: result.created, fallbackToCopy: result.fallbackToCopy };
+}
+
+function heal(dispatcherPath, missing, { noSymlinks = false } = {}) {
+	const { path } = context;
+	const dir = path.dirname(dispatcherPath);
+	const sources = (missing || []).map((n) => path.join(dir, n));
+	const result = self.link.batch(dispatcherPath, sources, { noSymlinks, overwrite: false });
+	for (const entry of result.created) {
+		self.log.append({ op: "heal-dispatcher-link", path: entry.source, mechanism: entry.mechanism, target: dispatcherPath });
+	}
+	return result;
+}

package/src/api/install/hooks.mjs

@@ -0,0 +1,80 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+export const PACKAGE_HOOK_MAP = {
+	"post-checkout": "update-embedded-repos",
+	"post-merge": "update-embedded-repos",
+	"post-rewrite": "update-embedded-repos",
+	"reference-transaction": "reference-transaction"
+};
+
+/**
+ * Install or uninstall the package's per-repo hook scripts.
+ *
+ * `op === "install"` copies the four hooks; `op === "uninstall"` removes only
+ * the ones recognizably owned by git-embedded (any file whose content includes
+ * the string "git-embedded").
+ *
+ * @param {"install"|"uninstall"} op
+ * @param {string} gitDir
+ * @param {object} [opts]
+ * @param {boolean} [opts.force]
+ */
+export default function hooks(op, gitDir, opts = {}) {
+	if (op === "install") return doInstall(gitDir, opts);
+	if (op === "uninstall") return doUninstall(gitDir);
+	throw new Error(`install.hooks: unknown op "${op}" (expected "install" or "uninstall")`);
+}
+
+function doInstall(gitDir, { force = false } = {}) {
+	const { fs, path } = context;
+	const hooksDir = path.join(gitDir, "hooks");
+	fs.mkdirSync(hooksDir, { recursive: true });
+	const sourceDir = self.paths.hooksSourceDir();
+	const installed = [];
+	const skipped = [];
+	for (const [hookName, sourceName] of Object.entries(PACKAGE_HOOK_MAP)) {
+		const dest = path.join(hooksDir, hookName);
+		const source = path.join(sourceDir, sourceName);
+		if (!force && fs.existsSync(dest)) {
+			let existing;
+			try {
+				existing = fs.readFileSync(dest, "utf8");
+			} catch {
+				existing = "";
+			}
+			if (!existing.includes("git-embedded")) {
+				skipped.push({ name: hookName, reason: "existing hook is not owned by git-embedded; pass --force to overwrite" });
+				continue;
+			}
+		}
+		self.link.copyExecutable(source, dest, { overwrite: true });
+		installed.push(hookName);
+		self.log.append({ op: "install-repo-hook", path: dest, source });
+	}
+	return { installed, skipped };
+}
+
+function doUninstall(gitDir) {
+	const { fs, path } = context;
+	const hooksDir = path.join(gitDir, "hooks");
+	const removed = [];
+	const kept = [];
+	for (const hookName of Object.keys(PACKAGE_HOOK_MAP)) {
+		const dest = path.join(hooksDir, hookName);
+		if (!fs.existsSync(dest)) continue;
+		let body;
+		try {
+			body = fs.readFileSync(dest, "utf8");
+		} catch {
+			body = "";
+		}
+		if (body.includes("git-embedded")) {
+			fs.unlinkSync(dest);
+			removed.push(hookName);
+			self.log.append({ op: "uninstall-repo-hook", path: dest });
+		} else {
+			kept.push({ name: hookName, reason: "file is not owned by git-embedded" });
+		}
+	}
+	return { removed, kept };
+}

package/src/api/install/template.mjs

@@ -0,0 +1,15 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+/**
+ * Install the package's hook scripts into a `git init.templateDir/hooks`
+ * directory so new repos start with them.
+ *
+ * @param {string} templateDir
+ * @param {object} [opts]
+ * @param {boolean} [opts.force]
+ */
+export default function template(templateDir, opts = {}) {
+	const { fs, path } = context;
+	fs.mkdirSync(path.join(templateDir, "hooks"), { recursive: true });
+	return self.install.hooks("install", templateDir, opts);
+}

package/src/api/link/batch.mjs

@@ -0,0 +1,130 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+const WIN_PRIV_NOT_HELD = "EPERM";
+
+export class CancelledByUser extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CancelledByUser";
+	}
+}
+
+function removeIfExists(p) {
+	const { fs } = context;
+	try {
+		fs.lstatSync(p);
+	} catch {
+		return false;
+	}
+	fs.unlinkSync(p);
+	return true;
+}
+
+function isPrivilegeError(err) {
+	if (!err) return false;
+	if (err.code === WIN_PRIV_NOT_HELD || err.code === "EACCES") return true;
+	if (typeof err.errno === "number" && err.errno === -4048) return true;
+	return false;
+}
+
+function trySymlink(source, target) {
+	try {
+		context.fs.symlinkSync(target, source, "file");
+		return { ok: true };
+	} catch (err) {
+		return { ok: false, error: err };
+	}
+}
+
+function tryHardlink(source, target) {
+	try {
+		context.fs.linkSync(target, source);
+		return { ok: true };
+	} catch (err) {
+		return { ok: false, error: err };
+	}
+}
+
+function tryCopy(source, target) {
+	const { fs } = context;
+	try {
+		fs.copyFileSync(target, source);
+		if (process.platform !== "win32") {
+			try {
+				const st = fs.statSync(source);
+				fs.chmodSync(source, st.mode | 0o111);
+			} catch {
+				// best-effort
+			}
+		}
+		return { ok: true };
+	} catch (err) {
+		return { ok: false, error: err };
+	}
+}
+
+/**
+ * Create links from many sources to one target. Default mechanism is symlink;
+ * `opts.noSymlinks` switches to hardlink (falling back to copy on cross-volume
+ * or non-NTFS). On Windows, missing symlink privilege triggers a single UAC
+ * batch via `self.link.elevateWindows`.
+ *
+ * @param {string} target absolute path of the file being linked-to
+ * @param {string[]} sources absolute paths of the new links to create
+ * @param {object} [opts]
+ * @param {boolean} [opts.noSymlinks]
+ * @param {boolean} [opts.overwrite]
+ */
+export default function batch(target, sources, opts = {}) {
+	const { noSymlinks = false, overwrite = false } = opts;
+	const { fs, path } = context;
+	const created = [];
+	const fallbackToCopy = [];
+
+	const ensureDir = (p) => fs.mkdirSync(path.dirname(p), { recursive: true });
+
+	if (noSymlinks) {
+		for (const source of sources) {
+			ensureDir(source);
+			if (overwrite) removeIfExists(source);
+			const hl = tryHardlink(source, target);
+			if (hl.ok) {
+				created.push({ source, mechanism: "hardlink" });
+				continue;
+			}
+			const cp = tryCopy(source, target);
+			if (!cp.ok) throw cp.error;
+			created.push({ source, mechanism: "copy" });
+			fallbackToCopy.push(source);
+		}
+		return { created, fallbackToCopy };
+	}
+
+	const deferred = [];
+	for (const source of sources) {
+		ensureDir(source);
+		if (overwrite) removeIfExists(source);
+		const ln = trySymlink(source, target);
+		if (ln.ok) {
+			created.push({ source, mechanism: "symlink" });
+			continue;
+		}
+		if (process.platform === "win32" && isPrivilegeError(ln.error)) {
+			deferred.push(source);
+			continue;
+		}
+		const cp = tryCopy(source, target);
+		if (!cp.ok) throw ln.error;
+		created.push({ source, mechanism: "copy" });
+		fallbackToCopy.push(source);
+	}
+
+	if (deferred.length > 0) {
+		const result = self.link.elevateWindows(deferred.map((source) => ({ source, target })));
+		if (result.cancelled) throw new CancelledByUser(result.message || "UAC elevation cancelled");
+		if (!result.ok) throw new Error(result.message || `elevated symlink batch failed (exit ${result.exitCode})`);
+		for (const source of deferred) created.push({ source, mechanism: "symlink-elevated" });
+	}
+
+	return { created, fallbackToCopy };
+}

package/src/api/link/copy-executable.mjs

@@ -0,0 +1,27 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+/**
+ * Copy a file to a destination, preserving the +x bit on Unix.
+ *
+ * @param {string} source
+ * @param {string} dest
+ * @param {object} [opts]
+ * @param {boolean} [opts.overwrite=true]
+ */
+export default function copyExecutable(source, dest, { overwrite = true } = {}) {
+	const { fs, path } = context;
+	fs.mkdirSync(path.dirname(dest), { recursive: true });
+	if (overwrite) {
+		try {
+			fs.lstatSync(dest);
+			fs.unlinkSync(dest);
+		} catch {
+			// nothing to remove
+		}
+	}
+	fs.copyFileSync(source, dest);
+	if (process.platform !== "win32") {
+		const st = fs.statSync(dest);
+		fs.chmodSync(dest, st.mode | 0o111);
+	}
+}

package/src/api/link/elevate-windows.mjs

@@ -0,0 +1,52 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+const ERROR_CANCELLED = 1223;
+
+/**
+ * Re-launch the current Node binary as Administrator via PowerShell's
+ * `Start-Process -Verb RunAs` and have it create a batch of symlinks. Each
+ * entry is `{ source, target }` — `source` is the link to create, `target` is
+ * what it points at.
+ *
+ * Cancellation of the UAC prompt is detected via the spawned process's exit
+ * code (ERROR_CANCELLED = 1223). All other non-zero exits are surfaced as
+ * failures.
+ *
+ * @param {Array<{source:string,target:string}>} plan
+ */
+export default function elevateWindows(plan) {
+	if (process.platform !== "win32") {
+		throw new Error("link.elevateWindows is Windows-only");
+	}
+	if (!Array.isArray(plan) || plan.length === 0) {
+		return { ok: true, cancelled: false, exitCode: 0 };
+	}
+
+	const { fs, path, os, spawnSync } = context;
+	const tmpPath = path.join(os.tmpdir(), `git-embedded-symlink-batch-${process.pid}-${Date.now()}.json`);
+	fs.writeFileSync(tmpPath, JSON.stringify(plan, null, 2));
+
+	const childScript = path.join(self.paths.packageRoot(), "src", "lib", "elevate-windows-child.mjs");
+	const node = process.execPath;
+
+	const argList = [childScript, tmpPath].map((s) => `'${s.replace(/'/g, "''")}'`).join(",");
+	const psCommand = `try { $p = Start-Process -FilePath '${node.replace(/'/g, "''")}' -ArgumentList @(${argList}) -Verb RunAs -Wait -PassThru; exit $p.ExitCode } catch { if ($_.Exception.NativeErrorCode -eq ${ERROR_CANCELLED} -or $_.Exception.HResult -eq -2147467260) { exit ${ERROR_CANCELLED} } else { Write-Error $_; exit 1 } }`;
+
+	const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", psCommand], {
+		stdio: ["ignore", "pipe", "pipe"]
+	});
+
+	try {
+		fs.unlinkSync(tmpPath);
+	} catch {
+		// ignore cleanup failure
+	}
+
+	const exitCode = result.status ?? 1;
+	if (exitCode === 0) return { ok: true, cancelled: false, exitCode };
+	if (exitCode === ERROR_CANCELLED) {
+		return { ok: false, cancelled: true, exitCode, message: "UAC elevation cancelled by user" };
+	}
+	const stderr = (result.stderr || Buffer.alloc(0)).toString("utf8").trim();
+	return { ok: false, cancelled: false, exitCode, message: stderr || `elevated symlink batch exited ${exitCode}` };
+}

package/src/api/log.mjs

@@ -0,0 +1,38 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+/**
+ * Append-only JSONL transaction log. Each install/uninstall operation appends
+ * one line; uninstall replays the log to know what to remove.
+ *
+ * @namespace api.log
+ */
+
+export function append(entry) {
+	const { fs, path } = context;
+	const log = self.paths.transactionLogPath();
+	fs.mkdirSync(path.dirname(log), { recursive: true });
+	const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+	fs.appendFileSync(log, line);
+}
+
+export function read() {
+	const { fs } = context;
+	const log = self.paths.transactionLogPath();
+	if (!fs.existsSync(log)) return [];
+	return fs
+		.readFileSync(log, "utf8")
+		.split(/\r?\n/)
+		.filter(Boolean)
+		.map((line) => {
+			try {
+				return JSON.parse(line);
+			} catch {
+				return null;
+			}
+		})
+		.filter(Boolean);
+}
+
+export function path() {
+	return self.paths.transactionLogPath();
+}

package/src/api/messages/load.mjs

@@ -0,0 +1,27 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+const KIND_TO_FILE = {
+	none: "setup-none.md",
+	"dispatcher-canonical-complete": "setup-dispatcher-canonical-complete.md",
+	"dispatcher-missing-symlinks": "setup-dispatcher-missing-symlinks.md",
+	"dispatcher-non-conforming": "setup-dispatcher-non-conforming.md",
+	husky: "setup-husky.md",
+	lefthook: "setup-lefthook.md",
+	"simple-git-hooks": "setup-simple-git-hooks.md",
+	"pre-commit": "setup-pre-commit.md",
+	"bare-githooks": "setup-bare-githooks.md",
+	"system-hookspath": "setup-system-hookspath.md",
+	"init-templatedir": "setup-init-templatedir.md"
+};
+
+/**
+ * Read the markdown body for a detection classification kind, verbatim.
+ *
+ * @param {string} kind one of the keys in `KIND_TO_FILE`
+ * @returns {string}
+ */
+export default function load(kind) {
+	const file = KIND_TO_FILE[kind];
+	if (!file) throw new Error(`Unknown message kind: ${kind}`);
+	return context.fs.readFileSync(context.path.join(self.paths.messagesDir(), file), "utf8");
+}

package/src/api/paths.mjs

@@ -0,0 +1,43 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+/**
+ * Path constants and platform-aware path computations. All values are derived
+ * from the host's `context.packageRoot` (set by bin/git-embedded.mjs) and the
+ * standard XDG environment variables.
+ *
+ * @namespace api.paths
+ */
+
+export function packageRoot() {
+	return context.packageRoot;
+}
+
+export function hooksSourceDir() {
+	return context.path.join(context.packageRoot, "hooks");
+}
+
+export function messagesDir() {
+	return context.path.join(context.packageRoot, "messages");
+}
+
+export function stateDir() {
+	const { path, os } = context;
+	if (process.platform === "win32") {
+		const base = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+		return path.join(base, "git-embedded");
+	}
+	const xdg = process.env.XDG_STATE_HOME;
+	const base = xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), ".local", "state");
+	return path.join(base, "git-embedded");
+}
+
+export function transactionLogPath() {
+	return context.path.join(stateDir(), "install.log");
+}
+
+export function defaultGlobalDispatcherDir() {
+	const { path, os } = context;
+	const xdg = process.env.XDG_CONFIG_HOME;
+	const base = xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), ".config");
+	return path.join(base, "git", "hooks");
+}

package/src/api/prompt.mjs

@@ -0,0 +1,26 @@
+import { context } from "@cldmv/slothlet/runtime";
+
+/**
+ * Minimal interactive prompts. Honors `--yes` via `opts.yes` and
+ * non-TTY input by returning the default.
+ *
+ * @namespace api.prompt
+ */
+
+export function confirm(question, opts = {}) {
+	const { defaultYes = false, yes = false } = opts;
+	if (yes) return Promise.resolve(true);
+	if (!process.stdin.isTTY) return Promise.resolve(defaultYes);
+
+	const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+	const rl = context.readline.createInterface({ input: process.stdin, output: process.stdout });
+	return new Promise((resolve) => {
+		rl.question(`${question} ${suffix} `, (answer) => {
+			rl.close();
+			const trimmed = (answer || "").trim().toLowerCase();
+			if (trimmed === "") resolve(defaultYes);
+			else if (trimmed === "y" || trimmed === "yes") resolve(true);
+			else resolve(false);
+		});
+	});
+}

package/src/api/report.mjs

@@ -0,0 +1,83 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+const KIND_LABELS = {
+	none: "No hook setup detected",
+	"dispatcher-canonical-complete": "Canonical dispatcher (complete)",
+	"dispatcher-missing-symlinks": "Canonical dispatcher (missing required entries)",
+	"dispatcher-non-conforming": "Non-conforming dispatcher",
+	husky: "Husky",
+	lefthook: "Lefthook",
+	"simple-git-hooks": "simple-git-hooks",
+	"pre-commit": "pre-commit (Python)",
+	"bare-githooks": "Bare hooks directory",
+	"system-hookspath": "System-scope core.hooksPath",
+	"init-templatedir": "init.templateDir set globally"
+};
+
+function fmtKv(label, value) {
+	if (value == null || value === "") return null;
+	return `  ${context.chalk.bold(label)}: ${value}`;
+}
+
+/**
+ * User-facing output helpers — colorized status lines + the "Detected: …"
+ * header rendered before each message file.
+ *
+ * @namespace api.report
+ */
+
+export function detectionHeader(result) {
+	const { chalk } = context;
+	const label = KIND_LABELS[result.kind] || result.kind;
+	console.log(chalk.cyan.bold(`\nDetected: ${label}`));
+
+	const { paths, signals, dispatcher, foreign, bare, subClassification } = result;
+	const lines = [];
+	if (paths) {
+		if (paths.repoRoot) lines.push(fmtKv("Repo root", paths.repoRoot));
+		if (paths.gitDir) lines.push(fmtKv("Git dir", paths.gitDir));
+		if (paths.effectiveHooksPath) lines.push(fmtKv("Effective core.hooksPath", paths.effectiveHooksPath));
+	}
+	if (signals && signals.hooksPathScopes) {
+		const s = signals.hooksPathScopes;
+		const scope = (k, v) => (v ? `${k}=${v}` : null);
+		const parts = [scope("system", s.system), scope("global", s.global), scope("local", s.local)].filter(Boolean);
+		if (parts.length) lines.push(fmtKv("core.hooksPath scopes", parts.join("  ")));
+	}
+	if (signals && signals.initTemplateDir) lines.push(fmtKv("init.templateDir", signals.initTemplateDir));
+	if (dispatcher && dispatcher.dispatcherPath) lines.push(fmtKv("Dispatcher", dispatcher.dispatcherPath));
+	if (dispatcher && dispatcher.missing && dispatcher.missing.length) {
+		lines.push(fmtKv("Missing entries", dispatcher.missing.join(", ")));
+	}
+	if (foreign && foreign.dir) lines.push(fmtKv("Tool directory", foreign.dir));
+	if (foreign && foreign.configFile) lines.push(fmtKv("Config file", foreign.configFile));
+	if (bare && bare.dir) lines.push(fmtKv("Hooks directory", bare.dir));
+	if (subClassification && subClassification.dispatcherPath) {
+		lines.push(fmtKv("System-path dispatcher", subClassification.dispatcherPath));
+	}
+
+	for (const l of lines.filter(Boolean)) console.log(l);
+	console.log("");
+}
+
+export function message(kind) {
+	const body = self.messages.load(kind);
+	const rendered = context.renderMarkdown(body);
+	process.stdout.write(rendered.endsWith("\n") ? rendered : rendered + "\n");
+}
+
+export function success(line) {
+	console.log(context.chalk.green(`✓ ${line}`));
+}
+
+export function warn(line) {
+	console.log(context.chalk.yellow(`! ${line}`));
+}
+
+export function error(line) {
+	console.error(context.chalk.red(`✗ ${line}`));
+}
+
+export function plain(line = "") {
+	console.log(line);
+}

package/src/lib/elevate-windows-child.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+//
+// Elevated child process: reads a JSON file with an array of
+// { source, target } entries and creates symbolic links for each.
+// Spawned by elevate-windows.mjs via PowerShell's `Start-Process -Verb RunAs`.
+
+import fs from "node:fs";
+
+const planPath = process.argv[2];
+if (!planPath) {
+	console.error("elevate-windows-child: missing plan file argument");
+	process.exit(2);
+}
+
+let plan;
+try {
+	plan = JSON.parse(fs.readFileSync(planPath, "utf8"));
+} catch (err) {
+	console.error("elevate-windows-child: failed to read plan:", err.message);
+	process.exit(3);
+}
+
+let failures = 0;
+for (const entry of plan) {
+	if (!entry || !entry.source || !entry.target) {
+		failures++;
+		continue;
+	}
+	try {
+		// Remove any existing entry so the link can be (re-)created cleanly.
+		try {
+			fs.unlinkSync(entry.source);
+		} catch {
+			// ignore — most likely doesn't exist yet
+		}
+		fs.symlinkSync(entry.target, entry.source, "file");
+	} catch (err) {
+		failures++;
+		console.error(`failed to symlink ${entry.source} -> ${entry.target}: ${err.message}`);
+	}
+}
+
+process.exit(failures === 0 ? 0 : 4);