aube-bump

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bumping vendored aube to a new upstream

## Mental model

`vendor/aube/**` is plain tracked files in nub's history — no submodule, no pin. An aube change is an ordinary nub PR touching `vendor/aube/**`. Everything lives in the nub repo; you do not need a clone of `nubjs/aube` and you do not touch the `nub-fork` branch.

| Thing | Where |
| --- | --- |
| Source of truth | `vendor/aube/**` on nub `main` |
| Upstream | `jdx/aube`, as the `aube-upstream` remote |
| The base we're on | `vendor/aube/UPSTREAM` (commit + tag) |
| Merge venue | built on demand, thrown away |

**The venue is derived, not stored.** A 3-way merge needs a commit whose tree is the vendored state and whose ancestry contains the upstream base — both already in nub's object store. Deriving it at bump time means it cannot drift, and `rerere`'s cache lives in nub and persists across bumps.

## The core: two machine-generated conflict lists

You never hand-review the upstream diff.

1. **Textual conflicts** — `git merge` gives every place both sides edited the same lines. One merge, one complete list, resolved once. This is what a merge buys over a rebase.
2. **Semantic conflicts** — `cargo check --workspace --all-targets` gives every place both sides edited *different* lines in ways that don't compose (upstream adds a required param, nub's caller keeps the old arity; upstream renames a field under a nub-added method). Git merges text, not meaning, so these produce **zero conflict markers and a perfectly clean merge**.

"All conflicts resolved" is worthless as a correctness signal — the compiler is the second half of the merge. List 2 is layered: each fix lets the compiler reach further, so iterate to a clean exit.

**The biggest lever is merge-base correctness.** Conflict count is a function of the base, not of how far upstream moved: a stale base re-presents changes you already have as conflicts (once, 72 files / 205 hunks instead of 23 / 48). `vendor/aube/UPSTREAM` exists so this is a fact you read — keep it accurate.

## Recipe

Work in a nub worktree off latest `origin/main` (see the `worktree` skill). Never touch the shared tree.

### 1. Read the base and fetch upstream

```sh
cat vendor/aube/UPSTREAM                       # commit + tag this tree derives from
git remote add aube-upstream https://github.com/jdx/aube 2>/dev/null
git fetch aube-upstream main
git log --oneline <base-sha>..aube-upstream/main | wc -l    # size of the bump
```

Sanity-check the marker before trusting it — the delta should look like *nub delta only*, not half of upstream:

```sh
grep -m1 '^version' vendor/aube/Cargo.toml            # e.g. 1.25.1
git log --oneline aube-upstream/main | grep 'release v1.25.1'
git diff --name-only <base-sha>^{tree} origin/main:vendor/aube | wc -l   # should be ~nub delta size
```

Already done? `git merge-base --is-ancestor aube-upstream/main <venue>` → nothing to do.

### 2. Build the ephemeral venue and merge

```sh
git config rerere.enabled true       # BEFORE resolving — resolve each conflict once, ever
VENUE=$(git commit-tree origin/main:vendor/aube -p <base-sha> -m "venue: vendored aube @ <base-tag>")
git merge-base $VENUE aube-upstream/main    # MUST print <base-sha>

git worktree add -b _aube_venue /tmp/aube-venue "$VENUE"
cd /tmp/aube-venue                           # this worktree's ROOT is aube's tree
git merge aube-upstream/main --no-ff --no-commit

git diff --name-only --diff-filter=U > /tmp/conflicts.txt
while read -r f; do printf "%3s %s\n" "$(grep -c '^<<<<<<<' "$f")" "$f"; done < /tmp/conflicts.txt | sort -rn
```

**Merge, never rebase** — a rebase re-surfaces the same conflict once per nub-delta commit.

### 3. Resolve list 1, in one shot, in parallel

Partition conflicted files by crate/area and dispatch one Opus agent per partition — they edit disjoint files in one working tree, which is safe. A workable split:

- `crates/aube/src/commands/**` (install, add, dlx, script settings)
- `crates/aube-lockfile/**` (pnpm/npm/yarn readers + writers)
- `crates/aube-linker/**`, `aube-scripts`, `aube-util`, `aube-registry`

Every dispatch prompt must carry the **doctrine below verbatim** (agents inherit nothing) and must say: *do not run `cargo check` — siblings are mid-edit and the tree will not compile; the orchestrator owns the build gate*, and *do not run mutating git commands*.

### 4. Resolve list 2 (the compiler), iterating to clean

```sh
cd /tmp/aube-venue && git add -A
export CARGO_TARGET_DIR=~/.cache/nub/aube-venue-target
cargo check --workspace --all-targets --message-format short   # iterate until exit 0
cargo clippy --workspace --all-targets --all-features -- -D warnings
REAL_HOME="$HOME"; mkdir -p /tmp/clean-aube-home
env HOME=/tmp/clean-aube-home RUSTUP_HOME="$REAL_HOME/.rustup" CARGO_HOME="$REAL_HOME/.cargo" \
  cargo test --workspace                # registry/config tests read ~/.npmrc
```

- **`--workspace` with NO `--lib` — that is what CI runs** (`aube-parity.yml`, `working-directory: vendor/aube`). `--lib` skips `crates/*/tests/**` entirely, including the fork-discipline integration tests that pin default-preservation — exactly what a bump is most likely to break.
- **Run aube's suite from inside `vendor/aube` (or the venue), never via `--manifest-path` from the nub root.** Cargo reads `.cargo/config.toml` from the invocation directory, and aube's sets `RUST_TEST_THREADS = "1"` because `aube-util`'s `concurrency` and `http::ticket_cache` tests mutate process env. From the nub root that is silently dropped and those tests flake, which reads exactly like a regression your merge caused.
- For each error ask: **is this symbol nub delta or upstream?** Then apply the doctrine. Never paper over with `.unwrap()`/`.expect()` or by deleting a capability.
- **Check exit codes, not piped output** — `cargo check … | tail` reports `tail`'s status.

### 5. Bring the result into `vendor/aube`

```sh
cd /tmp/aube-venue && git commit                       # keep the merge commit for reference
rsync -a --delete --exclude '.git/' /tmp/aube-venue/ <worktree>/vendor/aube/
diff -rq /tmp/aube-venue <worktree>/vendor/aube --exclude .git    # MUST be identical
```

Update `vendor/aube/UPSTREAM` to the new upstream commit + tag **in the same commit**.

Check open PRs touching `vendor/aube/**` first (`gh pr list --json number,title,files`). Where they overlap the upstream delta the in-tree version wins and whoever merges second resolves — say so in the PR body.

### 6. nub-side gates (do not skip — see the feature-gating section)

```sh
cd <worktree>
scripts/rust-build.sh check -p nub-cli --all-targets
mkdir -p runtime/addons && printf 'placeholder-addon' > runtime/addons/nub-native.node  # clippy ONLY
# `--all-features` also requires the vendored runtime node_modules. A lint ships nothing, so
# grant the opt-out (as CI's clippy job does) instead of vendoring them — see `rust-build`.
NUB_ALLOW_INCOMPLETE_RUNTIME=1 scripts/rust-build.sh clippy --all-targets --all-features -- -D warnings
cargo fmt --check
rm -f runtime/addons/nub-native.node && make addon-fast    # REQUIRED before any test run
```

Then open an ordinary nub PR with the `vendor/aube/**` diff: summarize behavior-affecting upstream changes, and flag anything touching a default or security posture for maintainer sign-off.

From nubjs/nub, MIT.

More from nubjs/nub