theme-update

Theme Update — Weaverse Pilot

Safely upgrade a Weaverse Pilot theme from its current version to a newer release. This skill walks through detection, planning, execution, and verification — never overwriting user customizations without explicit approval.

Source

• Theme repo: https://github.com/Weaverse/pilot
• Releases: https://github.com/Weaverse/pilot/releases
• Package name: @weaverse/pilot
• Versioning: YYYY.M.D (e.g., 2026.4.7). Older: semver (v8.1.0)

Quick Check

node skills/theme-update/scripts/check_pilot_updates.mjs
node skills/theme-update/scripts/check_pilot_updates.mjs --target v2026.4.7

Procedure

Follow these phases in order. Do NOT skip steps.

Phase 1 — Detection

1. Read package.json → get version field
2. If name is not @weaverse/pilot, ask the user to confirm this is a Pilot-based project
3. Fetch releases:

curl -s "https://api.github.com/repos/Weaverse/pilot/releases?per_page=50"

4. Identify all releases between current version and latest (or user-specified target)
5. Present to user:
   • Current version
   • Target version (latest unless specified)
   • Number of intermediate releases
   • Summary of key changes (features, fixes, breaking changes)

If already on latest → stop here and tell the user.

Phase 2 — Branch

git

Always work on a branch. Never update on main directly.

Phase 3 — Plan

For each release in the update range (oldest to newest):

1. Fetch the diff between consecutive versions:

2. Download the target version's source (for reference files):

3. Categorize every changed file into three buckets:

Auto-merge (safe to apply without asking)

• package.json version bump, dependencies
• Lock files (package-lock.json, bun.lockb, pnpm-lock.yaml)
• tsconfig.json, vite.config.ts, tailwind.config.ts — ONLY if user hasn't customized them
• New files that don't exist in user's project (additive only)
• .github/, CHANGELOG.md, LICENSE

Needs review (show diff, get approval)

• app/components/ — UI components user may have customized
• app/routes/ — route files user may have modified
• app/lib/ — utility modules
• app/root.tsx, app/entry.client.tsx, app/entry.server.tsx
• app/styles/ — CSS/Tailwind changes
• Any file where the user has local changes (git diff shows modifications from Pilot base)

Skip (mention but don't touch)

• Files the user deleted (they removed the feature intentionally)
• Files in directories the user reorganized
• .env, .env.example — never overwrite environment files

4. Present the plan in a clear table:

Wait for user confirmation before proceeding. Ask:

"Review the plan above. Approve to continue, or tell me which files to handle differently."

Phase 4 — Execute

Apply changes in order, one release at a time if multi-version jump:

4a. Auto-merge files

After each auto-merge, verify with git diff --stat.

4b. Needs-review files

For each file:

1. Show a three-way comparison:

   • Pilot at user's version (baseline)
   • Pilot at target version (their changes)
   • User's current file (local modifications)

2. Identify what the user changed vs what Pilot changed:

   • User-only changes → preserve
   • Pilot-only changes → apply
   • Overlapping changes → flag conflict

3. For conflicts, present options:

   • Accept Pilot's version (lose user customization)
   • Keep user's version (skip Pilot improvement)
   • Manual merge (show both, let user edit)
   • Smart merge (try to combine both — only if non-overlapping regions)

4. Wait for user decision on each conflict before proceeding.

4c. Commit per release

If doing multi-version jump, repeat for each intermediate release.

Phase 5 — Verify

After all changes applied:

If build fails:

1. List the errors
2. Analyze root cause (dependency mismatch? breaking change missed?)
3. Propose fixes
4. Apply fixes with user approval
5. Re-run build

If build succeeds:

1. Run bun run dev briefly to check no runtime errors
2. Summarize all changes made
3. List any manual follow-up steps:
   • New features that need configuration
   • Breaking changes requiring code updates in customized files
   • Deprecated patterns to migrate later

Phase 6 — Finalize

1. Present final summary:

2. Ask user: "Ready to merge into main?"

Safety Rules

1. Always branch first — never update on main directly
2. Never overwrite without asking — every file that could have user changes needs review
3. Commit per release — easy to bisect if something breaks
4. Build must pass — don't declare success until typecheck + build both pass
5. Offer rollback — always tell user how to undo the whole update
6. Respect user deletions — if they removed a file, don't re-add it without asking

Common Pitfalls

• Version format: package.json has no v prefix (2026.4.7), GitHub tags have v prefix (v2026.4.7). Always normalize.
• Lock files: After updating package.json, MUST run the correct package manager (check which lockfile exists)
• Custom components: User components not in original Pilot are always preserved — never delete or move them
• Route structure: If user reorganized routes, don't force Pilot's structure — apply route logic changes to user's structure instead
• CSS conflicts: Pilot may change Tailwind classes or base styles — these need careful merge to avoid breaking user styling

SDK-Only Bumps (@weaverse/hydrogen)

Sometimes the ask is only "update the Weaverse SDK", not a full theme update. Verified procedure (used for a 5.5.0 → 5.15.1 client jump):

1. Baseline before bumping. Run npx react-router typegen && npm run typecheck on the CURRENT version and record every error (client forks usually have pre-existing failures). After the bump, diff against this baseline — you only own the delta. Without the baseline you'll chase errors that were always there.
2. Peer check first: npm view @weaverse/hydrogen@<target> peerDependencies. 5.15.x/5.16.x need @shopify/hydrogen >=2025.5, react 19, react-router 7, @shopify/remix-oxygen 3. react-error-boundary and @weaverse/schema arrive transitively — their absence in the theme's package.json is fine.
3. Known break at 5.15: errorComponent is typed FC<{ error: unknown }> (was an Error-like object). Port upstream Pilot's GenericError, which narrows at runtime (error && typeof error === "object" && "message" in error).
4. Finish with full shopify hydrogen build --codegen — typecheck alone misses bundler-level issues.

Weaverse-Internal: Pilot Lock & Demo Deploy

• Pilot lives inside the Weaverse pnpm monorepo but ships an npm lockfile. Refresh it with npm i --package-lock-only --workspaces=false; plain npm i fails on the monorepo's catalog: protocol.
• Deploying pilot.weaverse.dev: merge to Weaverse/pilot main, then gh repo sync Weaverse/pilot-demo --source Weaverse/pilot — the fork carries the Oxygen deploy action and ships on sync (~1 min).