Sync Template

Sync a project with tsu-stack

Integrate relevant changes from https://github.com/tsu-moe/tsu-stack into the current project without replacing project-specific work.

For a comparison request, inspect and report only. For a sync request, prepare a reviewable change on a dedicated branch or isolated worktree. A sync request does not by itself authorize pushing, opening a pull request, publishing packages, deploying, or running production migrations.

Establish local state

• Read the project AGENTS.md, relevant domain guidance, package scripts, environment schema, and any existing docs/upstream-sync.md record.
• Record the starting commit, current branch, staged and unstaged changes, and untracked files. Do not silently stash, commit, discard, or copy secret-bearing files.
• If the checkout is dirty, use an isolated worktree from the relevant committed state unless the requested update depends on uncommitted work. Preserve unrelated changes.
• Stop and identify the purpose of any existing merge, rebase, cherry-pick, or revert before changing it.
• Establish relevant baseline checks when practical so pre-existing failures are distinguishable from regressions.

Resolve template provenance

The CLI writes .tsu-stack.jsonc with immutable creation provenance:

{
  "source": {
    "repository": "tsu-moe/tsu-stack",
    "branch": "variant/merged-cloudflare",
    "commit": "<40-character SHA>",
    "requestedRef": "variant/merged-cloudflare"
  },
  "variant": "cloudflare"
}

Resolve the comparison base in this order, keeping command output compact:

1. Read .tsu-stack.jsonc in the working tree. Treat source.commit as the creation base and source.branch as the default upstream branch.

2. If the file was deleted, inspect its history rather than guessing:

   git log --all --format=%H -- .tsu-stack.jsonc
   git show <newest-revision-that-still-contains-the-file>:.tsu-stack.jsonc

   Walk revisions from newest to oldest until git show <revision>:.tsu-stack.jsonc succeeds. Use the recovered source.commit, branch, repository, and variant.

3. If no metadata revision exists, use a verified previous sync record or a real merge base. Check for shallow history before concluding that ancestry is absent.

4. For GitHub-template projects or old projects that never committed metadata, identify the initial project commit with git rev-list --max-parents=0 HEAD. Infer the likely variant from the generated tree, then use the initial commit timestamp only to bound a small search of the matching upstream branch. Compare compact tree/diff statistics and representative invariant files to validate the candidate.

Creation time is a search hint, not proof. If more than one branch or commit remains plausible, report each candidate, its SHA, and the evidence, then require user confirmation before applying upstream changes. Do not invent a base from dependency versions or a similar date.

The supported CLI branch mapping is:

Resolve the upstream target

• Use https://github.com/tsu-moe/tsu-stack.git as the canonical source. Do not assume a remote named upstream is correct and do not repoint origin.
• Fetch the metadata branch unless the user explicitly names another branch, tag, or commit. Resolve the fetched ref to an immutable SHA immediately; do not rely on a moving branch name.
• Verify that the base is an ancestor of the selected target when they are expected to share history. If the target is older than the base, explain that it represents a rollback and require an explicit rollback request.
• If the network or remote cannot be verified, label local revisions as cached and do not claim they are the latest upstream state.