Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 120 additions & 0 deletions .agents/skills/upstream-sync/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
name: upstream-sync
description: Bring upstream pingdotgg/t3code into this fork's dev_vm in three gated stages, a scout report, the merge, then a Forgejo release. Use when asked to sync, merge, or pull upstream changes.
---

# Sync upstream into dev_vm

Three stages. The scout ends at a report and an **approval gate**: the merge and
release start only after Andrei approves that report. Each stage's criterion
says when it is done.

The scratch worktree lives outside the repository (`/tmp/t3-merge-scout`), so
the main checkout stays clean on `dev_vm` until the merge is approved. Every
command names `dev_vm` rather than `HEAD`, since the skill may run from another
branch. Shell variables do not survive the approval gate, so recompute `MB`
when a later stage needs it.

## 1. Scout

```bash
git fetch upstream && git fetch origin # local dev_vm must equal origin/dev_vm
MB=$(git merge-base dev_vm upstream/main)
git worktree add --detach /tmp/t3-merge-scout dev_vm
cd /tmp/t3-merge-scout && git merge --no-ff --no-commit upstream/main
```

Gather, in the scratch worktree:

- **What's new**: `git log --no-merges $MB..upstream/main`, with commit types
counted and every `feat`/`perf` read. Highlight changes that touch fork
features, migrations, updating, or the mobile native build.
- **Conflicts**: resolve each one in the scratch tree, keeping the fork's intent
on upstream's new structure. Use `resolving-merge-conflicts` for anything
non-trivial.
- **Overlap**: files changed on both sides,
`comm -12 <(git diff --name-only $MB dev_vm | sort) <(git diff --name-only $MB upstream/main | sort)`.
Comment on lines +35 to +36

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Recompute the scout merge base in each shell

Fresh evidence after the earlier merge-stage fix is that the scout bullets still consume $MB after the setup command has returned. When these steps run in separate terminal calls, $MB is empty, so this first diff compares the in-progress merge worktree against dev_vm instead of enumerating fork changes since the merge base; fork-only packages and tests can consequently be omitted from validation. Recompute the merge base inline or persist it across calls.

AGENTS.md reference: AGENTS.md:L98-L101

Useful? React with πŸ‘Β / πŸ‘Ž.

A clean textual merge can still break a fork feature, so read the upstream
commits behind each overlapping file.
- **Redundant fork patches**: for each fork feature or fix
(`git log --no-merges upstream/main..dev_vm`), check whether upstream now does
the same thing. If it does, propose dropping the fork's version.
- **Migration ledger**: list upstream's new migrations, and read the live ledger
read-only:
`sqlite3 "file:$HOME/.local/share/t3code/userdata/statev2.sqlite?mode=ro" "select * from effect_sql_migrations order by migration_id"`.
Every recorded id must carry upstream's name. The fork never adds rows to this
ledger; fork schema goes in its own table.
- **Build health**: install dependencies, then typecheck each package that
holds a file from `git diff --name-only $MB dev_vm`. Upstream CI covers the
rest. Then run these tests (see Gotchas): the fork's
(`git diff --name-only $MB dev_vm -- '*.test.ts' '*.test.tsx'`), the tests for
overlapping files, and every test upstream added or changed in a directory
that holds a fork-changed file. New upstream tests there can assert behavior
the fork deliberately changed.

Done when the report covers: what's new, every conflict and its resolution, each
adaptation that the typecheck or tests forced, redundant fork patches, semantic
gaps found in the overlap (each with a recommendation: fix now or follow up),
the migration ledger, and typecheck and test results. Present the report, then
stop and wait for approval.

## 2. Merge

1. Fetch again. If `upstream/main` moved, copy the resolved files out, stage
everything, `git merge --abort`, and merge the new tip. Restore a saved
resolution only for a file that
`git diff --name-only <old tip> upstream/main` does not list. Resolve the
listed files again, since a copy would discard upstream's newer content.
Then rerun typecheck and tests.
2. Commit in the scratch worktree as
`merge(upstream): integrate <Month D> updates with fork compatibility`. The
body names each adaptation and why, with no list of upstream features.
3. The pre-commit hook formats staged files, so check that the result still
differs from upstream only in fork files. This must print nothing:
`comm -23 <(git diff --name-only upstream/main HEAD | sort) <(git diff --name-only $(git merge-base dev_vm upstream/main) dev_vm | sort)`
(run before the fast-forward, while `dev_vm` is still the pre-merge tip).
4. In the main checkout, `git merge --ff-only <merge commit>`, then
`git push origin dev_vm`.

Done when `dev_vm` on origin is the verified merge commit.

## 3. Release

Follow [Forgejo package operations](../../../docs/operations/forgejo-packages.md),
but run its stages one at a time instead of `npm run release:forgejo`, which
starts Android straight after the WSL desktop build:

1. `node scripts/t3code-forgejo.mjs publish --output /tmp/t3-release-artifact`.
Read the version and commit from its `build.json`.
Comment on lines +87 to +88

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Allocate a fresh release artifact directory

After one successful release, /tmp/t3-release-artifact is retained for the hash comparison and never removed, so the next sync cannot publish: the invoked builder explicitly refuses an output containing either package.tgz or build.json (scripts/t3code-build:158-159). Use a uniquely created directory for each release, while retaining that path through the verification step.

Useful? React with πŸ‘Β / πŸ‘Ž.

2. `scripts/t3code-desktop-release --version V --ref C`.
3. Before Android, confirm WSL is idle and the Windows host has room for this
VM to grow to about 18 GB. A starved Android build freezes the VM. WSL's own
`uptime` and `free` should show it idle, and the host's free memory should
cover the VM's growth (18 GB minus `free -g` total here):
`ssh wsl_worker '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -NoProfile -Command "(Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory/1MB"'`.
Then run `scripts/t3code-android-release --version V --ref C`, and keep an
eye on swap here while it builds.
4. Download the published server package
(`node scripts/t3code-forgejo.mjs download --version V --output DIR`) and
compare its hash with the built artifact.

Done when the report gives the version, the commit, the hash match, and each
client build's outcome. A failed client build is retried on its own, never by
releasing again. Releasing does not install anything or restart a service.

Finish with `git worktree remove --force /tmp/t3-merge-scout`.

## Gotchas

- `scripts/setup-worktree.ts` needs `T3CODE_PROJECT_ROOT`, and Volta cannot
find `vp` in a worktree that has no `node_modules` yet. Install with the main
checkout's binary:
`/home/menshikov/projects/t3code/node_modules/.bin/vp i -- --yes`.
- Typecheck a package with `/tmp/t3-merge-scout/node_modules/.bin/tsc-rs --noEmit`
run from its directory. It prints hundreds of Effect suggestions; only lines
matching `: error TS` count.
Comment on lines +113 to +115

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Invoke each package's declared typecheck

When a fork-changed package does not use the standard TypeScript check, this command runs the wrong validator. For example, apps/marketing/package.json:11 declares astro check; running bare tsc-rs --noEmit there does not validate .astro templates, so an overlapping marketing regression can pass the required scout gate. Run the selected package's typecheck script instead.

AGENTS.md reference: AGENTS.md:L98-L101

Useful? React with πŸ‘Β / πŸ‘Ž.

- Run tests from the scratch root with `./node_modules/.bin/vp test run <files>`.
- `git merge --abort` refuses while edits are unstaged. Stage them first.
- New upstream tests can assert upstream behavior that the fork deliberately
changed (security headers, version comparison). Update the test to the fork's
behavior, and name it in the merge commit body.
Loading