@cldmv/git-embedded 1.0.0

package/messages/setup-simple-git-hooks.md

@@ -0,0 +1,40 @@
+## simple-git-hooks detected
+
+This repo uses [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks) for git hook management. Signal: `"simple-git-hooks"` key in `package.json`.
+
+simple-git-hooks writes hook scripts directly into `.git/hooks/` from the `package.json` config. Running `npx simple-git-hooks` regenerates those files from the config. `git-embedded` cannot install into `.git/hooks/` without risk of being overwritten on the next regeneration.
+
+## Why the CLI will not auto-integrate
+
+`package.json` is the source of truth for simple-git-hooks. Editing `.git/hooks/<name>` directly is undone the next time the user runs `npx simple-git-hooks`. Modifying `package.json` is the correct integration path, but unattended JSON edits to a shared file (where developers may have local changes) is risky enough to avoid automating.
+
+## Manual integration
+
+Edit `package.json` to add `git-embedded`'s invocations to the `simple-git-hooks` block. Each entry is a shell command; chain ours with `&&` after any existing command:
+
+```json
+{
+  "simple-git-hooks": {
+    "post-checkout": "npx git-embedded run-hook post-checkout \"$@\"",
+    "post-merge":    "npx git-embedded run-hook post-merge \"$@\"",
+    "post-rewrite":  "npx git-embedded run-hook post-rewrite \"$@\"",
+    "reference-transaction": "npx git-embedded run-hook reference-transaction \"$@\""
+  }
+}
+```
+
+If you have existing entries for these hooks, chain them:
+
+```json
+"post-checkout": "your-existing-command && npx git-embedded run-hook post-checkout \"$@\""
+```
+
+After editing, run `npx simple-git-hooks` to regenerate `.git/hooks/`. Run `git embedded doctor` to confirm.
+
+## Caveat about reference-transaction
+
+simple-git-hooks may not support `reference-transaction` as a hook event in all versions. If `npx simple-git-hooks` ignores the entry, install that one hook outside simple-git-hooks (directly into `.git/hooks/reference-transaction`) — it lives at a separate hook name from the others, so simple-git-hooks won't touch it.
+
+## Bring-your-own mode
+
+`git embedded print-hook-script <name>` outputs the script body. You can use it via the `npx` indirection above, or inline its contents into the `package.json` command if you want to avoid the indirect call.

package/messages/setup-system-hookspath.md

@@ -0,0 +1,25 @@
+## System-scope `core.hooksPath` detected
+
+`git config --system core.hooksPath` is set on this machine to the path printed above. This is unusual — typically set by a system administrator, corporate management tool, or a Linux distribution's git packaging.
+
+The contents of the system hooks path determine how this configuration affects `git-embedded`:
+
+- If the system path contains a **dispatcher** that chains to `.git/hooks/`, behavior is the same as a global canonical dispatcher (setup #2). `git-embedded` can install per-repo hooks normally; the system dispatcher chains to them.
+- If the system path contains **bare hook scripts** without a chain mechanism, anything `git-embedded` installs in `.git/hooks/` will never fire. Integration requires either modifying the system dispatcher (needs sudo / admin) or overriding `core.hooksPath` at a narrower scope (global or local).
+
+## What the CLI proposes
+
+- Print the classification of the system hooks path so you can see what's there.
+- For dispatcher-style system setups: install per-repo hooks as normal. No system change needed.
+- For non-dispatcher system setups: refuse to install and suggest one of:
+  - Override `core.hooksPath` at your user-global scope (`git config --global core.hooksPath …`) pointing at a personal dispatcher you control.
+  - Override `core.hooksPath` at the repo-local scope for just this repo.
+  - Escalate to your system administrator to convert the system dispatcher to a chaining model.
+
+## Why the CLI will not modify system config
+
+System-scope git config requires elevated privileges to change. Modifying it without explicit `--system --yes` flags risks breaking other users' workflows on shared machines. Even with such flags, blind modification of system config is the wrong default. The CLI will only ever advise.
+
+## Permission considerations
+
+If you do not have sudo or admin on this machine, the only available remediations are user-global or local overrides. Both work — the user-global override takes precedence for all your repos; the local override applies to just one repo. Pick based on whether you want this behavior in every repo you work in or just this one.

package/package.json

@@ -0,0 +1,96 @@
+{
+	"name": "@cldmv/git-embedded",
+	"version": "1.0.0",
+	"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",
+	"engines": {
+		"node": ">=20.19.0"
+	},
+	"author": {
+		"name": "Shinrai",
+		"company": "CLDMV",
+		"email": "git+npm@cldmv.net",
+		"url": "https://cldmv.net"
+	},
+	"contributors": [
+		{
+			"name": "CLDMV",
+			"url": "https://github.com/CLDMV"
+		}
+	],
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/shinrai"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/CLDMV/git-embedded.git"
+	},
+	"bugs": {
+		"url": "https://github.com/CLDMV/git-embedded/issues"
+	},
+	"homepage": "https://github.com/CLDMV/git-embedded#readme",
+	"keywords": [
+		"git",
+		"gitlink",
+		"submodule",
+		"anonymous-submodule",
+		"embedded",
+		"embedded-repo",
+		"private",
+		"hooks",
+		"hooks-installer",
+		"gitmodules-free",
+		"reference-transaction",
+		"post-checkout",
+		"post-merge",
+		"post-rewrite",
+		"dispatcher",
+		"cli"
+	],
+	"files": [
+		"bin",
+		"src",
+		"hooks",
+		"messages",
+		"docs",
+		"README.md",
+		"LICENSE"
+	],
+	"bin": {
+		"git-embedded": "./bin/git-embedded.mjs"
+	},
+	"scripts": {
+		"start": "node bin/git-embedded.mjs",
+		"test": "vitest run --config .configs/vitest.config.mjs",
+		"test:watch": "vitest --config .configs/vitest.config.mjs",
+		"coverage": "vitest run --coverage --config .configs/vitest.config.mjs",
+		"lint": "eslint --config .configs/eslint.config.mjs .",
+		"lint:fix": "eslint --config .configs/eslint.config.mjs . --fix",
+		"format": "prettier --config .configs/.prettierrc --write .",
+		"format:check": "prettier --config .configs/.prettierrc --check ."
+	},
+	"dependencies": {
+		"@cldmv/slothlet": "^3.7.0",
+		"@cldmv/wisp": "^1.0.1",
+		"chalk": "^5.4.1",
+		"commander": "^14.0.0",
+		"marked": "^15.0.12",
+		"marked-terminal": "^7.3.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.18.0",
+		"@eslint/json": "^0.10.0",
+		"@eslint/markdown": "^6.2.2",
+		"@vitest/coverage-v8": "^2.1.9",
+		"eslint": "^9.18.0",
+		"globals": "^15.14.0",
+		"prettier": "^3.4.2",
+		"vitest": "^2.1.9"
+	}
+}

package/src/api/cli/doctor.mjs

@@ -0,0 +1,15 @@
+import { self } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "doctor",
+	description: "Inspect the current environment and report what would happen on install. Takes no action.",
+	examples: ["$ git-embedded doctor"]
+};
+
+export async function run() {
+	const result = await self.detect.run(process.cwd());
+	self.report.detectionHeader(result);
+	self.report.message(result.kind);
+}
+
+export default { spec, run };

package/src/api/cli/init.mjs

@@ -0,0 +1,26 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "init",
+	description: "Set up the current repo for embedded gitlinks: run install-hooks, then silence the 'embedded git repository' advice.",
+	options: [
+		["--no-symlinks", "Forwarded to install-hooks: use hard links instead of symbolic links."],
+		["--yes", "Forwarded to install-hooks: skip confirmation prompts."],
+		["--dispatcher-dir <path>", "Forwarded to install-hooks: override the default dispatcher directory."]
+	],
+	examples: ["$ git-embedded init", "$ git-embedded init --yes"]
+};
+
+export async function run(opts = {}) {
+	await self.cli.installHooks.run(opts);
+
+	const { spawnSync } = context;
+	const cfg = spawnSync("git", ["config", "advice.addEmbeddedRepo", "false"], { encoding: "utf8" });
+	if (cfg.status === 0) {
+		self.report.success("Silenced 'embedded git repository' advice (git config advice.addEmbeddedRepo=false).");
+	} else {
+		self.report.warn(`Could not set git config advice.addEmbeddedRepo: ${cfg.stderr || cfg.stdout}`);
+	}
+}
+
+export default { spec, run };

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

@@ -0,0 +1,124 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+import { CancelledByUser } from "../link/batch.mjs";
+
+export const spec = {
+	command: "install-hooks",
+	description: "Install git-embedded's hook scripts into this repo, bootstrapping a global dispatcher if needed.",
+	options: [
+		["--no-symlinks", "Use hard links instead of symbolic links (avoids the Windows UAC prompt)."],
+		["--yes", "Skip confirmation prompts; assume yes for any modification."],
+		["--dispatcher-dir <path>", "Override the default dispatcher directory (~/.config/git/hooks)."]
+	],
+	examples: [
+		"$ git-embedded install-hooks",
+		"$ git-embedded install-hooks --no-symlinks",
+		"$ git-embedded install-hooks --yes"
+	]
+};
+
+export async function run(opts = {}) {
+	const result = await self.detect.run(process.cwd());
+	self.report.detectionHeader(result);
+	self.report.message(result.kind);
+	self.report.plain("");
+
+	switch (result.action) {
+		case "install":
+			await installRepoOnly(result);
+			return;
+		case "heal-then-install":
+			await healAndInstall(result, opts);
+			return;
+		case "suggest-dispatcher":
+			await bootstrapAndInstall(result, opts);
+			return;
+		case "refuse":
+			self.report.error(`Refusing to install over ${result.kind}. See the guidance above for manual integration paths.`);
+			process.exit(2);
+			return;
+		default:
+			self.report.error(`Unknown detection action: ${result.action}`);
+			process.exit(2);
+	}
+}
+
+async function installRepoOnly(result) {
+	const gitDir = result.paths.gitDir;
+	if (!gitDir) {
+		self.report.error("Not inside a git repository — run from inside the repo you want to install hooks for.");
+		process.exit(2);
+	}
+	const out = await self.install.hooks("install", gitDir);
+	if (out.installed.length > 0) self.report.success(`Installed per-repo hooks: ${out.installed.join(", ")}`);
+	for (const s of out.skipped) self.report.warn(`Skipped ${s.name}: ${s.reason}`);
+}
+
+async function healAndInstall(result, opts) {
+	const missing = result.dispatcher.missing;
+	self.report.plain(context.chalk.bold("Proposed heal:"));
+	self.report.plain(`  Dispatcher: ${result.dispatcher.dispatcherPath}`);
+	self.report.plain(`  Add entries: ${missing.join(", ")}`);
+	self.report.plain(`  Mechanism: ${opts.noSymlinks ? "hardlink" : "symlink (UAC on Windows when not elevated)"}`);
+	self.report.plain("");
+	const ok = await self.prompt.confirm("Add the missing entries?", { defaultYes: false, yes: opts.yes });
+	if (!ok) {
+		self.report.warn("Heal declined. Re-run after adding the entries yourself; see the message above.");
+		process.exit(2);
+	}
+	try {
+		const linkResult = await self.install.dispatcher(
+			"heal",
+			{ dispatcherPath: result.dispatcher.dispatcherPath, missing },
+			{ noSymlinks: opts.noSymlinks }
+		);
+		self.report.success(`Healed ${linkResult.created.length} entries`);
+		if (linkResult.fallbackToCopy.length > 0) self.report.warn(`Filesystem fallback to copy for ${linkResult.fallbackToCopy.length} entries`);
+	} catch (err) {
+		if (err instanceof CancelledByUser) {
+			self.report.error(err.message);
+			self.report.plain("To heal without symlinks (no UAC prompt), re-run with --no-symlinks.");
+			process.exit(2);
+		}
+		throw err;
+	}
+	await installRepoOnly(result);
+}
+
+async function bootstrapAndInstall(result, opts) {
+	const dir = opts.dispatcherDir || self.paths.defaultGlobalDispatcherDir();
+	self.report.plain(context.chalk.bold("Proposed dispatcher install:"));
+	self.report.plain(`  Directory: ${dir}`);
+	self.report.plain(`  Link mechanism: ${opts.noSymlinks ? "hardlink" : "symlink (UAC on Windows when not elevated)"}`);
+	self.report.plain(`  Global config: git config --global core.hooksPath ${dir}`);
+	self.report.plain("");
+	const ok = await self.prompt.confirm("Install the dispatcher and set global core.hooksPath?", { defaultYes: false, yes: opts.yes });
+	if (!ok) {
+		self.report.warn("Dispatcher install declined. Falling back to per-repo install.");
+		if (result.paths.gitDir) await installRepoOnly(result);
+		return;
+	}
+	try {
+		const out = await self.install.dispatcher("bootstrap", { dir }, { noSymlinks: opts.noSymlinks });
+		self.report.success(`Dispatcher installed at ${out.dispatcherPath}`);
+		const mechs = new Set(out.created.map((c) => c.mechanism));
+		self.report.plain(`  Created ${out.created.length} entries (${[...mechs].join(", ")})`);
+		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) {
+			self.report.error(`git config --global core.hooksPath failed: ${gitConfig.stderr || gitConfig.stdout}`);
+			process.exit(1);
+		}
+		self.report.success(`Set git config --global core.hooksPath ${dir}`);
+	} catch (err) {
+		if (err instanceof CancelledByUser) {
+			self.report.error(err.message);
+			self.report.plain("To install without symlinks (no UAC prompt), re-run with --no-symlinks.");
+			process.exit(2);
+		}
+		throw err;
+	}
+	if (result.paths.gitDir) await installRepoOnly(result);
+	else self.report.warn("Not inside a git repo — skipping per-repo hook install.");
+}
+
+export default { spec, run };

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

@@ -0,0 +1,43 @@
+import { self } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "install-template",
+	description: "Install git-embedded's hook scripts into git's init.templateDir/hooks so new repos start with them.",
+	options: [
+		["--template-dir <path>", "Override the template directory (default: git config --global init.templateDir)."],
+		["--force", "Overwrite existing hook files even if not owned by git-embedded."],
+		["--yes", "Skip confirmation prompts."]
+	],
+	examples: ["$ git-embedded install-template", "$ git-embedded install-template --template-dir ~/.config/git/template"]
+};
+
+export async function run(opts = {}) {
+	const templateDir = opts.templateDir || self.git.getInitTemplateDir();
+	if (!templateDir) {
+		self.report.error("git config --global init.templateDir is not set, and no --template-dir was provided.");
+		self.report.plain("Set one first, e.g.: git config --global init.templateDir ~/.config/git/template");
+		process.exit(2);
+	}
+
+	self.report.plain(`Template directory: ${templateDir}`);
+	self.report.plain(`Template hooks directory: ${templateDir}/hooks`);
+	self.report.plain("");
+	self.report.warn("Installing here only affects repos created or cloned AFTER this point.");
+	self.report.plain("Existing repos still need `git-embedded install-hooks` run individually.");
+	self.report.plain("");
+
+	const ok = await self.prompt.confirm(`Install git-embedded hook scripts into ${templateDir}/hooks?`, {
+		defaultYes: false,
+		yes: opts.yes
+	});
+	if (!ok) {
+		self.report.warn("Declined.");
+		return;
+	}
+
+	const out = await self.install.template(templateDir, { force: opts.force });
+	if (out.installed.length > 0) self.report.success(`Installed template hooks: ${out.installed.join(", ")}`);
+	for (const s of out.skipped) self.report.warn(`Skipped ${s.name}: ${s.reason}`);
+}
+
+export default { spec, run };

package/src/api/cli/link.mjs

@@ -0,0 +1,42 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "link",
+	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)"],
+		["<remote-url>", "The child repo's clone URL (will NOT be recorded in .gitmodules)"]
+	],
+	examples: [
+		"$ git-embedded link tests git@example.com:org/private-tests.git",
+		"$ git-embedded link vendor/foo https://github.com/org/foo.git"
+	]
+};
+
+export function run(localPath, remoteUrl) {
+	const { fs, spawnSync } = context;
+
+	if (fs.existsSync(localPath)) {
+		self.report.error(`${localPath} already exists. Remove it or pick a different path before linking.`);
+		process.exit(2);
+	}
+
+	self.report.plain(`Cloning ${remoteUrl} into ${localPath}…`);
+	const clone = spawnSync("git", ["clone", remoteUrl, localPath], { stdio: "inherit" });
+	if (clone.status !== 0) {
+		self.report.error(`git clone exited with status ${clone.status}`);
+		process.exit(clone.status || 1);
+	}
+
+	const add = spawnSync("git", ["add", localPath], { stdio: "inherit" });
+	if (add.status !== 0) {
+		self.report.error(`git add ${localPath} exited with status ${add.status}`);
+		process.exit(add.status || 1);
+	}
+
+	self.report.success(`Staged gitlink at ${localPath} (no .gitmodules entry written).`);
+	self.report.plain("Commit when ready: git commit -m 'embed <name>'");
+}
+
+export default { spec, run };

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

@@ -0,0 +1,35 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+const NAME_TO_SOURCE = {
+	"post-checkout": "update-embedded-repos",
+	"post-merge": "update-embedded-repos",
+	"post-rewrite": "update-embedded-repos",
+	"reference-transaction": "reference-transaction",
+	"update-embedded-repos": "update-embedded-repos",
+	_dispatch: "_dispatch.template",
+	dispatcher: "_dispatch.template"
+};
+
+export const spec = {
+	command: "print-hook-script",
+	description: "Print the contents of a packaged hook script to stdout. Useful for bring-your-own integrations.",
+	args: [["<name>", "Hook name (e.g. post-checkout, reference-transaction, update-embedded-repos, _dispatch)"]],
+	examples: [
+		"$ git-embedded print-hook-script post-checkout",
+		"$ git-embedded print-hook-script reference-transaction",
+		"$ git-embedded print-hook-script _dispatch"
+	]
+};
+
+export function run(name) {
+	const sourceName = NAME_TO_SOURCE[name];
+	if (!sourceName) {
+		self.report.error(`Unknown hook script: ${name}`);
+		self.report.error(`Known names: ${Object.keys(NAME_TO_SOURCE).sort().join(", ")}`);
+		process.exit(2);
+	}
+	const source = context.path.join(self.paths.hooksSourceDir(), sourceName);
+	process.stdout.write(context.fs.readFileSync(source, "utf8"));
+}
+
+export default { spec, run };

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

@@ -0,0 +1,21 @@
+import { self } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "uninstall-hooks",
+	description: "Remove git-embedded's hook scripts from this repo's .git/hooks directory. Leaves other hooks untouched.",
+	examples: ["$ git-embedded uninstall-hooks"]
+};
+
+export async function run() {
+	const gitDir = self.git.getGitDir(process.cwd());
+	if (!gitDir) {
+		self.report.error("Not inside a git repository.");
+		process.exit(2);
+	}
+	const out = await self.install.hooks("uninstall", gitDir);
+	if (out.removed.length === 0) self.report.plain("No git-embedded hooks found in this repo.");
+	else self.report.success(`Removed per-repo hooks: ${out.removed.join(", ")}`);
+	for (const k of out.kept) self.report.warn(`Left ${k.name} in place: ${k.reason}`);
+}
+
+export default { spec, run };

package/src/api/cli/version.mjs

@@ -0,0 +1,17 @@
+import { self, context } from "@cldmv/slothlet/runtime";
+
+export const spec = {
+	command: "version",
+	aliases: ["-V", "--version"],
+	description: "Print git-embedded, node, and platform versions.",
+	examples: ["$ git-embedded version"]
+};
+
+export function run() {
+	const pkg = context.wispSync(context.path.join(self.paths.packageRoot(), "package.json"));
+	console.log(`${pkg.name} ${pkg.version}`);
+	console.log(`node ${process.version.replace(/^v/, "")}`);
+	console.log(`platform ${process.platform}`);
+}
+
+export default { spec, run };