Now I have enough information to create a comprehensive plan. Let me summarize the key findings:
1. **packages/sessions** - Completely custom, needs to move to packages/cloudsession
2. **SST** - Need to remove sst.config.ts and mock any types that depend on it
3. **Env variables** - User wants to use upstream env var names where possible
4. **GitHub** - Already removed by user
5. **Wrangler configs** - Need to add to .gitignore
6. **Docs** - User wants to collect them and move out of repo
Let me now formulate the complete plan.
Now I have all the information needed. Here's the comprehensive plan:
Comprehensive Fork Merge Plan
Phase 1: Pre-Merge Preparation
1.1 Create a Worktree for Safe Experimentation
# Create a worktree for the merge work
git worktree add ../opencode-merge main
cd ../opencode-merge
git config rerere.enabled true
1.2 Enable Git Rerere Globally (you should run this yourself)
git config rerere.enabled true
git config rerere.autoupdate true
Phase 2: Rename packages/sessions → packages/cloudsession
Risk: Low - this is entirely your custom code with no upstream equivalent
Steps:
- Rename directory:
packages/sessions → packages/cloudsession
- Update any internal imports/references
- Update workspace configuration if needed
- Test:
bun run typecheck
Phase 3: Remove SST Configuration
Risk: Medium - need to mock types for typechecker
Steps:
- Delete
sst.config.ts
- Check for any remaining SST references in code
- If TypeScript complains about missing SST types, create minimal type stubs:
- Create
types/sst-stub.d.ts with minimal sst module declarations
- Or add
// @ts-ignore comments where necessary (temporary)
- Update
.gitignore to keep .sst ignored (already present)
Phase 4: Environment Variable Consolidation
Strategy: Use upstream names where they exist, keep fork-specific as fallback
Your current .env.example:
OPENCODE_API=https://api.opencode.j9xym.com
OIDC_BASE_URL=https://api.opencode.j9xym.com
WEB_DOMAIN=opencode.j9xym.com
API_DOMAIN=api.opencode.j9xym.com
Upstream likely uses different variable names. Need to:
- Search upstream for env var patterns (check their
.env.example and code)
- Map your fork's vars to upstream equivalents if they exist
- Keep fork-specific vars that don't have upstream equivalents
Phase 5: Gitignore Wrangler/Env Files
Files to add to .gitignore:
# Cloudflare worker secrets (local-only)
packages/*/wrangler.jsonc
packages/*/.env
# Keep .env.example tracked
!packages/*/.env.example
Current state: Your .gitignore already has:
.env (line 5) - good- Wrangler files NOT ignored for packages - needs adding
Phase 6: Collect and Preserve Docs
Your custom docs in packages/docs/:
packages/docs/quickstart.mdxpackages/docs/index.mdxpackages/docs/development.mdxpackages/docs/essentials/*packages/docs/ai-tools/*
Action: Copy to .opencode/docs-backup/ or a location you specify, then they can be removed from the main repo (unless you want to keep them)
Phase 7: The Merge
cd ../opencode-merge
# Fetch latest upstream
git fetch upstream
# Merge (not rebase - preserves your history)
git merge upstream/dev
# Handle conflicts using rerere + manual resolution:
# - For "deleted by us": git rm the file (rerere remembers)
# - For your custom code: keep yours
# - For upstream additions: accept theirs
# After conflicts resolved:
git add .
git commit -m "Merge upstream/dev - handle fork divergences"
Conflict Resolution Strategy
| Conflict Type |
Resolution |
Your custom code (packages/cloudsession/*) |
Keep yours |
| Files you deleted upstream keeps |
git rm + rerere remembers |
| SST-related (now removed) |
Accept upstream (or delete) |
| GitHub integration files |
Accept upstream (they're adding, you're removing) |
| Env var changes |
Check if upstream has equivalent, otherwise keep yours |
| SDK/session types |
May need manual alignment |
Phase 8: Verify
# Typecheck the result
bun run typecheck
# If typecheck fails on SST-related imports:
# - Create minimal type stubs
# - Or mark as @ts-expect-error temporarily
Questions Before Implementation
Docs location: Where do you want to move your custom docs? .opencode/docs-backup/ or external location?
SST stub types: Should I create minimal type stubs for SST, or use @ts-expect-error comments for a cleaner approach?
Merge commit message: Any preference for the merge commit message format?
Should I create the worktree now and proceed with the changes?
Once you confirm, I'll execute this plan in the worktree.