feat: restore/record/export provisioning commands (the "planned CLI")

.gitignore

@@ -6,6 +6,7 @@ node_modules/
 dist/
 coverage/
 reference/
+tmp/
 .idea/
 .vscode/
 *.tsbuildinfo

README.md

@@ -97,6 +97,88 @@ 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.
 
+`link` clones into a missing **or empty** target directory (a fresh clone of a parent materializes each gitlink as an empty dir, so `link` works to fill one in); it refuses anything else — a non-empty directory, a file, a symlink (even to an empty dir), or an unreadable path. After staging, it also records the child's URL and branch into this clone's local registry (see below).
+
+## Restoring embedded children (machine-B bootstrap)
+
+The parent commits only anonymous gitlinks — a path and a pinned SHA, never a URL. So a fresh clone of the parent materializes each embedded child as an _empty directory_: git knows the pin but has nowhere to fetch it from. `git embedded restore` fills those directories in.
+
+```bash
+git clone <parent-url> myproject
+cd myproject
+git embedded restore          # clone every embedded child and check out its pinned SHA
+```
+
+`restore` resolves each child's clone URL from up to four **optional** sources, strictest first, stopping at the first that yields a URL:
+
+1. **Local config registry** — `embedded.<path>.url` (and `embedded.<path>.branch`, see below) in _this clone's_ `.git/config`. Per-clone, never committed. Written automatically after a successful restore, and by `record` / `link`.
+2. **Manifest file** (`--from <file>`) — a JSON transfer file carried out-of-band (never committed). See `export` below.
+3. **`--base <url-base>`** — derives `<url-base>/<basename>.git` for each child.
+4. **Convention** (zero state) — the child is a sibling of wherever the parent was cloned from: the parent's origin with its last path segment replaced by `<basename>.git`. A URL- or path-style origin splits on the final `/` (`https://host/org/parent.git` → `https://host/org/tests.git`); a scp-style origin whose repo sits at the path root has no `/`, so the sibling is taken after the last `:` instead (`git@host:parent.git` → `git@host:tests.git`). No configuration, but it only resolves when the child's repository is actually named after the gitlink path and sits beside the parent. A convention guess can only ever name strings already derivable from the committed tree, so it discloses nothing new.
+
+Every clone is **SHA-verified**: the parent's pinned commit must exist in the freshly cloned child (a `git fetch` is attempted first). If it doesn't — e.g. a convention guess resolved to the wrong repository — the clone `restore` created is removed and the child is reported `pinned-mismatch`. A wrong guess fails closed; it never plants the wrong code.
+
+Per-child outcomes are `restored`, `already-present`, `unresolved`, `pinned-mismatch`, or `skipped`, and `restore` exits non-zero if any child ends `unresolved` or `pinned-mismatch`. Use `--dry-run` to report resolution without cloning.
+
+### Branch-aware checkout
+
+A restored child does not have to end up detached. `restore` resolves a **branch** for each child with the same layering as the URL — `embedded.<path>.branch` in the local registry, then the manifest — and when neither supplies one, it infers the branch from the pin: if exactly **one** `origin` branch contains the pinned commit, that branch is used. With a branch, the child ends ON it at the pin (`checkout -B`), with upstream tracking set to `origin/<branch>` when it exists, and the branch is auto-registered like the URL. An ambiguous pin (on several branches) or an unmatchable one keeps today's detached checkout — inference never guesses.
+
+**Partial restore is the normal case.** A public contributor without access to a private child simply skips it:
+
+```bash
+git embedded restore --skip tests            # comma-separate several: --skip tests,vendor/foo
+```
+
+### Obscured children
+
+A child whose repository name does not match its gitlink path — the intended state for a hidden private child — is deliberately _not_ convention-resolvable. Provide its URL once (via `link` into the empty gitlink dir, or `record` if it is already cloned) and this clone's registry remembers it for every later restore:
+
+```bash
+git embedded link tests git@example.com:org/private-tests.git
+# ...or, if the child is already present on disk:
+git embedded record
+```
+
+### Sharing URLs between machines: `export` / `record`
+
+`record` writes the origin URL (and current branch) of every present child into the local registry. `export` serializes that registry to a manifest another machine can consume:
+
+```bash
+git embedded export --scan -o children.json   # record present children, then write the manifest
+```
+
+On the other machine:
+
+```bash
+git clone <parent-url> myproject && cd myproject
+git embedded restore --from children.json
+```
+
+> **Never commit the manifest.** It contains the very URLs the anonymous-gitlink design keeps out of the tree. When `export -o` writes inside the worktree it appends the filename to `.git/info/exclude` as a courtesy, but keeping the manifest out-of-band is your responsibility.
+
+## Day-2: syncing pins
+
+When the parent pulls commits that move gitlink pins, the children on disk are still at the old SHAs. `git embedded sync` moves them — and only them; sync never touches the parent, so pulling the parent first is your step:
+
+```bash
+git pull
+git embedded sync
+```
+
+Per child, sync is deliberately conservative — a clean child follows the pin, anything that looks like your work is reported and left alone:
+
+- **already at the pin** — nothing to do (`in-sync`).
+- **uncommitted changes** — left alone (`dirty`).
+- **on the registered branch** (`embedded.<path>.branch`), clean — the branch is moved to the pin **fast-forward only**: the child's HEAD must be an ancestor of the pin. Commits beyond the pin are your work (`ahead`, left alone).
+- **on any other branch** — left alone (`unregistered-branch`).
+- **detached**, clean — snapped to the pin, staying detached (`synced`).
+- **pin not present locally** — one `git fetch origin` inside the child; if the pin still cannot be found the child is reported `pin-unavailable` and sync exits non-zero.
+
+Only `pin-unavailable` (and an unexpected checkout failure) fail the run — the left-alone outcomes protect in-progress work and exit zero. `sync` takes the same `[paths…]`, `--skip`, and `--dry-run` surface as `restore`.
+
+If the hooks from this package are installed, most parent operations already update the children automatically (detached, like standard submodules). `sync` covers the rest: hook-less clones, the `git reset --hard` gap, and keeping a child _on its branch_ as pins advance.
+
 ## Manual install (no CLI)
 
 If you'd rather wire things up by hand: