@cldmv/git-embedded 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 CLDMV
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,145 @@
+# @cldmv/git-embedded
+
+[![npm version]][npm_version_url] [![npm downloads]][npm_downloads_url] [![Last commit]][last_commit_url] [![npm last update]][npm_last_update_url]
+
+[![Contributors]][contributors_url] [![Sponsor shinrai]][sponsor_url]
+
+Manage embedded git repositories (anonymous gitlinks) without `.gitmodules`. Provides hooks that restore standard git-command ergonomics for embedded child repos while keeping the child's origin URL out of the public parent repo.
+
+## What this is
+
+Git uses **gitlinks** internally to track sub-repositories: a tree entry of mode `160000` pointing at a specific commit SHA in another repository. Submodules are built on top of gitlinks, with a registry file (`.gitmodules`) that records the child's URL alongside the gitlink. The URL is what makes `git clone --recurse-submodules`, `git submodule update`, and `submodule.recurse=true` checkout-flavored automation work — but it's also what publicly advertises the child repo's existence and location.
+
+A gitlink without a `.gitmodules` entry is sometimes called an "anonymous submodule" or "embedded git repo." It's a fully supported git state: the gitlink still pins a specific child SHA, git still recognizes the child as a submodule boundary, and the parent commits a clean reference to the child's pinned version. What's missing is git's automatic update behavior, because the submodule machinery requires registration to act.
+
+This package fills that gap with two git hooks:
+
+- **`reference-transaction`** — blocks `git checkout`, `git switch`, `git reset`, `git pull`, `git merge`, `git rebase`, `git bisect`, and `git cherry-pick` when any embedded child repo has uncommitted changes. Prevents the silent inconsistent-state failure mode where the parent moves to a new commit but the child stays behind, dirty.
+- **`update-embedded-repos`** — installed as `post-checkout`, `post-merge`, and `post-rewrite`. After a HEAD-moving operation, walks every gitlink in the new HEAD and updates the embedded child to its pinned SHA, using the child's own `origin` remote to fetch missing commits.
+
+Together, the two hooks make embedded gitlinks behave like properly-registered submodules for the common workflow operations — without ever recording the child's URL in the public parent repo.
+
+## Why this matters
+
+The motivating use case is OSS repositories that want comprehensive test coverage running in CI but cannot afford to publish the full test suite. Tests are a high-fidelity behavioral specification of the code under test; modern AI tooling makes clean-room reimplementation from tests fast and effective. Hiding the tests is the most direct mitigation. See [`docs/use-case-private-tests.md`](docs/use-case-private-tests.md) for the full motivation, threat model, and licensing strategy.
+
+The mechanism is general, though. The hooks don't know or care that the embedded repo is a test suite — they work for any gitlink. Other plausible uses: private vendor directories, license-restricted dependencies, encrypted asset trees, internal tooling sub-repos.
+
+## Install
+
+```bash
+npm install -g @cldmv/git-embedded
+```
+
+That places a `git-embedded` executable in npm's global `bin` directory, which makes git's subcommand discovery surface it as `git embedded …`.
+
+## Usage
+
+Run inside the parent repo (the one that holds the embedded gitlinks):
+
+```bash
+git embedded doctor          # inspect environment; takes no action
+git embedded install-hooks   # install hooks into this repo's .git/hooks
+git embedded uninstall-hooks # remove hooks installed by this CLI
+```
+
+`install-hooks` adapts to whatever's already in place:
+
+- **Nothing configured** — offers to install a small dispatcher script at `~/.config/git/hooks/_dispatch`, link every standard hook name to it, and set `git config --global core.hooksPath` to that directory. Then drops this package's hook scripts into the repo's `.git/hooks/`. The dispatcher chains to per-repo hooks, so every other repo on the machine keeps working as before.
+- **Canonical dispatcher already present** — installs only the per-repo hook scripts; the existing dispatcher activates them.
+- **Dispatcher present but missing required entries** — offers to add the missing symlinks (with explicit confirmation), then installs per-repo hooks.
+- **Foreign hook manager detected** (Husky, lefthook, simple-git-hooks, pre-commit) — refuses to install and prints instructions for hand-integrating, since clobbering those tools' generated files would be reverted on their next run.
+- **Non-conforming dispatcher / bare `.githooks/`** — refuses and prints integration options; the CLI never rewrites someone else's dispatcher.
+
+### Flags
+
+```text
+--no-symlinks             use hard links instead of symbolic links
+                          (avoids the Windows UAC prompt; same-volume only)
+--yes                     skip confirmation prompts
+--dispatcher-dir <path>   override the default ~/.config/git/hooks
+```
+
+### Other subcommands
+
+```bash
+git embedded install-template   # install hooks into git config init.templateDir/hooks
+                                # so new repos start with them already wired
+git embedded print-hook-script <name>
+                                # emit a packaged hook script to stdout
+                                # (post-checkout / post-merge / post-rewrite /
+                                #  reference-transaction / update-embedded-repos / _dispatch)
+```
+
+## Quick start: embed a child repo
+
+After the hooks are installed:
+
+```bash
+git clone <private-child-url> embedded-child
+git add embedded-child
+git commit -m "embed child"
+
+# silence the harmless 'embedded git repository' warning if desired
+git config advice.addEmbeddedRepo false
+```
+
+The committed parent tree now contains a gitlink at `embedded-child` pinning the child's current HEAD. No `.gitmodules` is created; the child's URL never lands in the public repo.
+
+## Manual install (no CLI)
+
+If you'd rather wire things up by hand:
+
+```bash
+mkdir -p .githooks
+cp /path/to/git-embedded/hooks/reference-transaction .githooks/
+cp /path/to/git-embedded/hooks/update-embedded-repos .githooks/
+chmod +x .githooks/*
+
+ln -sf update-embedded-repos .githooks/post-checkout
+ln -sf update-embedded-repos .githooks/post-merge
+ln -sf update-embedded-repos .githooks/post-rewrite
+
+git config core.hooksPath .githooks
+```
+
+## Documentation
+
+- [`docs/design.md`](docs/design.md) — how the hooks work, coverage matrix, limitations, comparison to standard submodules.
+- [`docs/use-case-private-tests.md`](docs/use-case-private-tests.md) — the OSS-tests-in-private-repo motivation, threat model, licensing strategy, why anonymous gitlinks rather than alternatives.
+
+## Compatibility
+
+- **Git 2.28 or newer** for the `reference-transaction` hook (released July 2020). The `update-embedded-repos` hook works on older git but loses its guard.
+- **Node 20.19+** for the CLI. The hooks themselves are shell scripts with no Node dependency at hook execution time.
+- **Linux / macOS / Windows.** On Windows, symlink creation needs admin elevation (a one-shot UAC prompt the CLI requests). Pass `--no-symlinks` to use hard links instead and skip the prompt.
+
+## Links
+
+- **npm**: [@cldmv/git-embedded](https://www.npmjs.com/package/@cldmv/git-embedded)
+- **GitHub**: [CLDMV/git-embedded](https://github.com/CLDMV/git-embedded)
+- **Issues**: [GitHub Issues](https://github.com/CLDMV/git-embedded/issues)
+- **Releases**: [GitHub Releases](https://github.com/CLDMV/git-embedded/releases)
+
+## License
+
+[![GitHub license]][github_license_url] [![npm license]][npm_license_url]
+
+Apache-2.0 © Shinrai / CLDMV. See [LICENSE](LICENSE).
+
+[npm version]: https://img.shields.io/npm/v/%40cldmv%2Fgit-embedded.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm_version_url]: https://www.npmjs.com/package/@cldmv/git-embedded
+[npm downloads]: https://img.shields.io/npm/dm/%40cldmv%2Fgit-embedded.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm_downloads_url]: https://www.npmjs.com/package/@cldmv/git-embedded
+[npm last update]: https://img.shields.io/npm/last-update/%40cldmv%2Fgit-embedded?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm_last_update_url]: https://www.npmjs.com/package/@cldmv/git-embedded
+[last commit]: https://img.shields.io/github/last-commit/CLDMV/git-embedded?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
+[last_commit_url]: https://github.com/CLDMV/git-embedded/commits
+[contributors]: https://img.shields.io/github/contributors/CLDMV/git-embedded.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
+[contributors_url]: https://github.com/CLDMV/git-embedded/graphs/contributors
+[sponsor shinrai]: https://img.shields.io/github/sponsors/shinrai?style=for-the-badge&logo=githubsponsors&logoColor=white&labelColor=EA4AAA&label=Sponsor
+[sponsor_url]: https://github.com/sponsors/shinrai
+[github license]: https://img.shields.io/github/license/CLDMV/git-embedded.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
+[github_license_url]: https://github.com/CLDMV/git-embedded/blob/HEAD/LICENSE
+[npm license]: https://img.shields.io/npm/l/%40cldmv%2Fgit-embedded.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm_license_url]: https://www.npmjs.com/package/@cldmv/git-embedded

package/bin/git-embedded.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+import slothlet from "@cldmv/slothlet";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import * as readline from "node:readline";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import chalk from "chalk";
+import { Command, Help } from "commander";
+import { wisp, wispSync } from "@cldmv/wisp";
+import { marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+
+// `showSectionPrefix: false` strips `##` from headers; marked-terminal hard-codes
+// `* ` as the bullet point, so swap it back to `-` to match the source markdown.
+marked.use(markedTerminal({ showSectionPrefix: false }));
+const renderMarkdown = (md) => marked.parse(md).replace(/^(\s*)\* /gm, "$1- ");
+
+if (typeof Command.prototype.examples !== "function") {
+	Command.prototype.examples = function (arr) {
+		if (arguments.length === 0) return this._exampleList || [];
+		this._exampleList = Array.isArray(arr) ? arr : [];
+		return this;
+	};
+}
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, "..");
+const apiDir = path.join(packageRoot, "src", "api");
+
+const api = await slothlet({
+	dir: apiDir,
+	context: {
+		fs,
+		path,
+		os,
+		chalk,
+		readline,
+		spawn,
+		spawnSync,
+		fileURLToPath,
+		pathToFileURL,
+		commander: { Command, Help },
+		wisp,
+		wispSync,
+		renderMarkdown,
+		packageRoot
+	}
+});
+
+const { CustomHelp, applyCustomHelpRecursive } = api.commander.customHelp.makeCustomHelp(Help, { chalk });
+
+const program = new Command();
+program.createHelp = () => new CustomHelp();
+program
+	.name("git-embedded")
+	.description(
+		"Manage embedded git repositories (anonymous gitlinks). Installs hooks that keep embedded children in sync without writing a .gitmodules entry."
+	)
+	.configureOutput({ writeErr: () => {} })
+	.exitOverride();
+
+registerCommandsFromApi(api, program);
+
+program
+	.command("help [cmd...]")
+	.description("Show help for a command")
+	.action((cmds) => {
+		if (cmds && cmds.length) {
+			let sub = program;
+			for (const c of cmds) sub = sub.commands.find((x) => x.name() === c) || sub;
+			sub.help();
+		} else {
+			program.help();
+		}
+	});
+
+program.action(() => {
+	program.outputHelp();
+	process.exit(0);
+});
+
+applyCustomHelpRecursive(program);
+
+process.on("uncaughtException", (error) => {
+	console.error(chalk.red(`✗ unexpected error: ${error && error.message ? error.message : error}`));
+	if (process.env.DEBUG) console.error(error);
+	process.exit(1);
+});
+
+try {
+	await program.parseAsync(process.argv);
+} catch (err) {
+	if (err && (err.code === "commander.helpDisplayed" || err.code === "commander.help" || err.code === "commander.version")) {
+		process.exit(0);
+	}
+	if (err && typeof err.code === "string" && err.code.startsWith("commander.")) {
+		let helpShown = false;
+		if (err.command && typeof err.command.outputHelp === "function") {
+			err.command.outputHelp();
+			helpShown = true;
+		} else if (process.argv[2]) {
+			const sub = program.commands.find((cmd) => {
+				if (cmd.name() === process.argv[2]) return true;
+				const aliases = typeof cmd.aliases === "function" ? cmd.aliases() : cmd._aliases;
+				return Array.isArray(aliases) && aliases.includes(process.argv[2]);
+			});
+			if (sub && typeof sub.outputHelp === "function") {
+				sub.outputHelp();
+				helpShown = true;
+			}
+		}
+		if (!helpShown) program.outputHelp();
+		console.error(chalk.red(`\n${(err.message || "").trim()}`));
+		process.exit(typeof err.exitCode === "number" ? err.exitCode : 1);
+	}
+	throw err;
+}
+
+/**
+ * Build commander subcommands from every leaf under `api.cli.*` that exposes
+ * `{ spec, run }`. Third-party plugins can extend the CLI surface at runtime
+ * via `api.slothlet.api.add("cli.myCommand", "/abs/path/to/leaf-folder")`
+ * before this is called.
+ */
+function registerCommandsFromApi(rootApi, programInstance) {
+	const cli = rootApi && rootApi.cli;
+	if (!cli) return;
+	for (const key of Object.keys(cli)) {
+		const leaf = cli[key];
+		if (!leaf || typeof leaf !== "object") continue;
+		const spec = leaf.spec;
+		const run = leaf.run;
+		if (!spec || typeof run !== "function") continue;
+		registerCommand(programInstance, spec, run);
+	}
+}
+
+function registerCommand(programInstance, spec, run) {
+	const commandName = spec.command;
+	if (!commandName) return;
+	const cmd = programInstance.command(commandName);
+	const aliases = Array.isArray(spec.aliases) ? spec.aliases : asArray(spec.aliases);
+	if (aliases.length) cmd.aliases(aliases);
+	if (spec.description) cmd.description(spec.description);
+	const args = asArray(spec.args);
+	for (const rawEntry of args) {
+		const entry = asArray(rawEntry);
+		const [a, desc] = entry;
+		if (a) cmd.argument(a, desc || "");
+	}
+	const options = asArray(spec.options);
+	for (const rawEntry of options) {
+		const entry = asArray(rawEntry);
+		const [flags, desc] = entry;
+		if (flags) cmd.option(flags, desc || "");
+	}
+	const examples = Array.isArray(spec.examples) ? spec.examples : asArray(spec.examples);
+	if (examples.length) cmd.examples(examples);
+	cmd.action(async (...actionArgs) => {
+		const last = actionArgs[actionArgs.length - 1];
+		const isCmd = last && typeof last === "object" && typeof last.opts === "function";
+		const trimmed = isCmd ? actionArgs.slice(0, -1) : actionArgs;
+		await run(...trimmed);
+	});
+}
+
+/**
+ * Slothlet wraps spec arrays as Function-shaped proxies — `.length` returns
+ * `Function.prototype.length` (0), but numeric-keyed elements are intact. Walk
+ * indices until one is missing.
+ */
+function asArray(maybe) {
+	if (Array.isArray(maybe)) return maybe;
+	if (maybe == null || typeof maybe !== "object") return [];
+	const out = [];
+	let i = 0;
+	while (i in maybe) {
+		out.push(maybe[i]);
+		i++;
+	}
+	return out;
+}

package/docs/design.md

@@ -0,0 +1,122 @@
+# Design: hooks for embedded git repositories
+
+This document describes the hook system that `@cldmv/git-embedded` installs and the design choices behind it. It is intended for anyone evaluating the approach, debugging an installed hook, or working on the planned CLI.
+
+## Background: gitlinks, submodules, and the registration gap
+
+Git internally tracks embedded sub-repositories as **gitlinks**: a tree entry with mode `160000` whose "value" is a 40-character commit SHA. The gitlink is the actual pinning machinery — it records "this directory should be at commit X" in the parent's history.
+
+Submodules are layered on top of gitlinks. A submodule is a gitlink **plus** a registry entry that declares the submodule's URL and (optionally) other configuration. The registry lives in two places:
+
+- `.gitmodules` — a tracked file at the parent repo root. The committed source of truth. Contains `[submodule "name"] path = ..., url = ...` blocks.
+- `.git/config` — the local-only runtime view, populated from `.gitmodules` by `git submodule init`.
+
+Git's high-level submodule commands (`git submodule update`, `submodule.recurse=true` behavior in `checkout`/`switch`/`pull`/`bisect`, `git clone --recurse-submodules`) require an entry in the registry to operate. They do not infer submodules from the mere presence of a gitlink and an embedded `.git/` directory, even though the information needed to do so is locally available.
+
+This produces what this package calls the **registration gap**: a gitlink that has no registry entry is fully tracked at the tree level (the SHA pin travels with commits, `git status` still flags divergence between the tree and the working state, `git add` infers the new SHA from the child's HEAD), but the working-tree-update automation is silent. Standard `git checkout` moves the parent forward; the embedded child stays at whatever SHA it was at before the operation.
+
+The hooks in this package close the registration gap without requiring a registry entry. They use the gitlink SHA from the parent's tree directly (via `git ls-tree`) and the child's own `origin` remote configuration (which the child has if it was cloned normally) to do the same work `git submodule update` would do.
+
+## Why this matters: the URL is the leak
+
+For most submodule use cases, the URL in `.gitmodules` is uncontroversial — the parent is open and the child is open, the URL is just a convenience for `clone --recurse-submodules`. For a parent that wants to hide the *existence* of a private child repo, the `.gitmodules` URL is the leak. Anyone who can read the public parent can read `.gitmodules`, see the URL of the private child, and at minimum learn that a private resource exists at that location.
+
+Avoiding `.gitmodules` is the obvious fix, but doing so loses the working-tree automation. This package restores the automation while keeping the parent free of URL data.
+
+## The two hooks
+
+### `reference-transaction` (guard)
+
+**Purpose.** Refuse to apply HEAD-moving ref updates when any embedded child repo has uncommitted changes. Without this guard, a `git checkout B` in the parent silently leaves a dirty child stranded at the previous pin, producing an inconsistent state that is easy to miss.
+
+**Mechanism.** `reference-transaction` is a git hook introduced in git 2.28 (July 2020). It fires for any ref-update transaction with one of three phase arguments:
+
+- `prepared` — updates queued, not yet applied. Exiting non-zero ABORTS the transaction.
+- `committed` — updates already applied.
+- `aborted` — informational.
+
+The hook script acts only on the `prepared` phase, where rejection is possible. It reads the proposed ref updates from stdin (one `old_sha new_sha ref` per line), filters to lines where `ref` is `HEAD` and `old_sha != new_sha` (an actual HEAD move), and walks every gitlink in the current tree checking for uncommitted changes via `git diff-index --quiet HEAD --` inside each child. If any child is dirty, the hook prints a message to stderr and exits non-zero, which aborts the parent operation.
+
+**What it catches.** Every git command that ultimately moves HEAD goes through a reference transaction. That includes `git checkout <ref>`, `git switch <branch>`, `git reset` (any mode that moves HEAD), `git pull` (both fast-forward and rebase variants), `git merge`, `git rebase` (each step), `git bisect` (each step), `git cherry-pick`, and others.
+
+**What it does not catch.** Operations that don't move HEAD aren't guarded, by design: `git commit` (creates a new commit but doesn't update the gitlink without explicit staging), `git checkout -- file` (file-level checkout), `git stash` itself (records stash refs, not HEAD), and so on. These don't require child-update behavior.
+
+**Caveat about error messaging.** When the hook exits non-zero, git wraps its own message around the script's stderr output. The user sees a message like:
+
+```text
+git-embedded: ✗ embedded-child has uncommitted changes
+  commit or stash inside embedded-child/ before moving HEAD here
+fatal: reference transaction hook declined
+```
+
+The `fatal: reference transaction hook declined` line is from git, not the hook. The script's two lines above it are what the user actually needs. Hook output should remain short and unambiguous because it appears alongside git's wrapping.
+
+### `update-embedded-repos` (auto-update)
+
+**Purpose.** After a successful HEAD-moving operation in the parent, walk every gitlink in the new HEAD and update the corresponding embedded child to its pinned SHA. This is the post-condition that `git submodule update` provides for registered submodules; the hook provides the equivalent for unregistered gitlinks.
+
+**Mechanism.** A single script installed under three hook names: `post-checkout`, `post-merge`, and `post-rewrite`. Each of these fires after a different family of operations:
+
+- `post-checkout` — `git checkout`, `git switch`, `git clone` (for the initial checkout), and each step of `git bisect`. Also fires when `git pull` does a fast-forward checkout-style update.
+- `post-merge` — successful `git merge` and the merge phase of `git pull`.
+- `post-rewrite` — `git rebase`, `git commit --amend`, and any command that rewrites commits.
+
+For each gitlink path, the script:
+
+1. Reads the pinned SHA from `git ls-tree -r HEAD`.
+2. Confirms a working git repo exists at the path (`tests/.git` is a directory or file).
+3. Compares the pinned SHA to the child's current HEAD; skips if already in sync.
+4. If the pinned SHA is not in the child's local object store, runs `git fetch` inside the child (using the child's own remote config — `.gitmodules` is not consulted).
+5. Runs `git checkout --detach <sha>` inside the child.
+
+The detached-HEAD checkout matches standard submodule behavior: parents pin specific commits, not branches, so the child ends up in detached-HEAD state after each parent operation. If the child needs to be on a branch for editing, the developer attaches to one (`git -C embedded-child switch -c work` or `git -C embedded-child checkout main`) after the operation completes.
+
+**What it catches.** Together, the three hook names cover essentially every checkout-flavored parent operation. See the coverage matrix below.
+
+**What it does not catch.** Two notable gaps:
+
+- `git reset --hard <commit>` updates the index and working tree but does **not** fire `post-checkout`, `post-merge`, or `post-rewrite`. The `reference-transaction` guard catches this case at the prepared phase (because `reset` does move HEAD via a ref transaction), so a `--hard` reset with a dirty child is refused — but a `--hard` reset with a clean child completes without the children being auto-updated. The mitigation is to either accept the gap, manually re-run the script, or use a `git-foo` wrapper command.
+- `git stash pop` modifies the working tree without moving HEAD. It does not affect embedded children (stash entries are recorded in the parent's stash ref, not in the children), but anyone expecting "all working-tree-modifying commands are guarded" will not see consistency here.
+
+## Coverage matrix
+
+| Operation | `reference-transaction` (guard) | `update-embedded-repos` (update) |
+|---|---|---|
+| `git checkout <ref>` | Refuses if any child is dirty | Updates children to new pins |
+| `git switch <branch>` | Refuses if any child is dirty | Updates children to new pins |
+| `git reset --hard <commit>` | Refuses if any child is dirty | **Gap** — does not fire `post-*` hooks |
+| `git reset --soft/--mixed <commit>` | Refuses if any child is dirty (HEAD moves) | Does not fire `post-*` hooks (HEAD-only change) |
+| `git pull` (fast-forward) | Refuses if any child is dirty | Updates children |
+| `git pull --rebase` | Refuses at each rebase step | Updates children after rebase completes |
+| `git merge <commit>` | Refuses if any child is dirty | Updates children via `post-merge` |
+| `git rebase` | Refuses at each step | Updates children via `post-rewrite` |
+| `git bisect <good/bad/run>` | Refuses if any child is dirty | Updates children at each bisect step |
+| `git cherry-pick` | Refuses if any child is dirty | Updates children via `post-checkout` |
+| `git stash pop` | Not guarded (no HEAD move) | Not updated (no HEAD move; not needed) |
+| `git commit` | Not guarded (no HEAD move) | Not updated (no HEAD move; not needed) |
+| `git checkout -- file` | Not guarded (no HEAD move) | Not updated (no HEAD move; not needed) |
+
+## Comparison to standard submodules
+
+| Property | Standard submodule | Anonymous gitlink + these hooks |
+|---|---|---|
+| Child URL in parent | Yes, in `.gitmodules` | No |
+| Tree-level pin | Gitlink | Gitlink |
+| Public viewer sees | URL, path, current SHA | Just the SHA (no link to follow) |
+| `git submodule update` | Works | Not used (registry-bound; hooks replace it) |
+| `submodule.recurse=true` | Works | Not used (registry-bound; hooks replace it) |
+| `git status` divergence | Yes | Yes |
+| `git add path` infers SHA | Yes | Yes |
+| `--recurse-submodules` clone | Pulls child | No-op (no registry) |
+| Initial child clone | Automatic via registry | Manual or via the planned CLI |
+| Dirty-child guard | Default refuses on update | Hook refuses on the HEAD move itself |
+
+The most useful difference is the **guard timing**. Standard submodules let the parent operation proceed and then refuse the child update, leaving the developer in a parent-moved-child-stale state that has to be backed out. The `reference-transaction` guard refuses the whole transaction at the parent level, so the working tree never reaches the inconsistent state.
+
+## Implementation notes
+
+- The hooks are POSIX-shell scripts to avoid Node or other runtime dependencies at hook execution time. They use `git ls-tree`, `git diff-index`, `git rev-parse`, `git cat-file`, `git fetch`, and `git checkout` — all standard plumbing.
+- All hook scripts are idempotent. Running them twice in a row is harmless: the second invocation detects the children are already at the pinned SHAs and is a no-op.
+- The `update-embedded-repos` script always exits 0. A failure to update a child writes to stderr but does not signal failure to git, because the parent operation has already completed and signalling failure here would not undo it. The `reference-transaction` guard is what prevents getting into this state.
+- The hooks operate on `HEAD`'s tree, not the index. This is correct after a checkout (HEAD has been updated), correct after a merge (HEAD is the merge commit), and correct after a rewrite (HEAD is the new commit). Reading the index instead would be wrong in some merge cases.
+- Embedded children are detected by the presence of `<path>/.git` (a directory for normal clones, a file for worktrees or for child submodules that have been moved into the gitdir). The check `[ -d "$path/.git" ] || [ -f "$path/.git" ]` covers both.