Skip to content

feat: bootstrap scaffold sync base from Cella-Base trailer with tree-similarity fallback#4

Merged
flipvh merged 2 commits into
mainfrom
feat/scaffold-base-trailer
Jul 6, 2026
Merged

feat: bootstrap scaffold sync base from Cella-Base trailer with tree-similarity fallback#4
flipvh merged 2 commits into
mainfrom
feat/scaffold-base-trailer

Conversation

@flipvh

@flipvh flipvh commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Summary

A fresh create-cella scaffold shares no git history with upstream, so the first cella sync had no merge-base and failed with "no common ancestor" unless the user manually seeded refs/cella/last-sync. The old mechanism for this — a committed .cella/base file written by create-cella — was never read by this CLI.

ensureSyncBase now resolves the bootstrap base with one uniform rule: try each source in order; the first one whose commit actually exists after the upstream fetch wins.

  1. refs/cella/last-sync (sync-point record, unchanged)
  2. cella.manifest.json committed at HEAD, then the worktree copy
  3. New: the root commit's Cella-Base: <sha> trailer, stamped by create-cella (see companion PR feat: stamp scaffold provenance as a Cella-Base trailer, drop .cella/base create-cella#12)
  4. New: tree-similarity inference — score the fork's root snapshot against recent upstream commits (diff-tree --name-only, up to 400 candidates no newer than the root commit) and take the closest match, rejected when >30% of paths differ

The trailer travels with push/clone (unlike a local ref) and needs no worktree file. Inference reseeds scaffolds whose trailer is absent or stale: local-template scaffolds, amended/squashed root commits, upstream history rewrites. Whichever source wins is persisted (ref immediately, manifest on the first applied sync), so this runs at most once per fork lifetime.

Behavior change: a recorded base that is missing after the fetch (stale manifest, foreign upstream) now falls through to the next source instead of hard-failing.

Tests

  • New e2e suite tests/e2e/ensure-sync-base.test.ts builds scaffold-shaped fixture repos (snapshot + template-cleaner-style edits + unrelated history) and covers: exact inference with newer upstream commits and fork-local work present, tie-breaking toward the newest candidate, trailer priority over inference, fall-through on a bogus trailer SHA, and rejection of a non-scaffold repo.
  • Full suite: 124 tests pass; verified end-to-end against a real scaffold of the actual template (~2000 files, bootstrap in well under 6s).

🤖 Generated with Claude Code

…similarity fallback

A fresh create-cella scaffold shares no git history with upstream, so the
first sync had no merge-base and failed unless the user manually seeded
refs/cella/last-sync. ensureSyncBase now resolves the base from ordered
sources where the first commit that actually exists after the upstream
fetch wins:

1. refs/cella/last-sync (sync-point record, unchanged)
2. cella.manifest.json committed at HEAD, then the worktree copy
3. the root commit's `Cella-Base: <sha>` trailer stamped by create-cella
4. tree-similarity inference: score the root snapshot against recent
   upstream commits with diff-tree and take the closest match, guarded
   by a confidence threshold

The trailer travels with push/clone (unlike a local ref) and needs no
worktree file; inference reseeds scaffolds whose trailer is absent or
stale (local-template scaffolds, amended root commits, upstream history
squashes). A stale recorded base now falls through to the next source
instead of hard-failing.

Replaces the never-read `.cella/base` file that create-cella used to write.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@flipvh flipvh merged commit fb492d1 into main Jul 6, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant