Kilo-Org_kilo/script/upstream

Upstream Merge Automation

Scripts for automating the merge of upstream opencode changes into Kilo.

Quick Start

# Install dependencies (from script/upstream directory)
cd script/upstream
bun install

# List available upstream versions
bun run list-versions.ts

# Analyze changes for a specific version (without merging)
bun run analyze.ts --version v1.1.49

# Run the full merge process
bun run merge.ts --version v1.1.49

# Dry-run to preview what would happen
bun run merge.ts --version v1.1.49 --dry-run

Scripts

Main Scripts

Script	Description
merge.ts	Main orchestration script for upstream merges
list-versions.ts	List available upstream versions
analyze.ts	Analyze changes without merging

Transform Scripts

Script	Description
transforms/package-names.ts	Transform opencode package names to kilo
transforms/preserve-versions.ts	Preserve Kilo's package versions
transforms/keep-ours.ts	Keep Kilo's version of specific files

Codemods (AST-based)

Script	Description
codemods/transform-imports.ts	Transform import statements using ts-morph
codemods/transform-strings.ts	Transform string literals

Merge Process

The merge automation follows this process:

1. Validate environment

   • Check for upstream remote
   • Ensure working directory is clean

2. Fetch upstream and determine target version

3. Generate conflict report analyzing which files will conflict

4. Create branches

   • backup/<branch>-<timestamp> - Backup of current state
   • <author>/kilo-opencode-<version> - Merge target branch
   • <author>/opencode-<version> - Transformed upstream branch

5. Apply transformations to upstream branch:

   • Transform package names (opencode-ai -> @kilocode/cli)
   • Preserve Kilo's versions
   • Reset Kilo-specific files

6. Merge transformed upstream into Kilo branch

7. Auto-resolve known conflicts (markdown, Kilo-specific files)

8. Push and generate final report

Configuration

Configuration is defined in utils/config.ts:

{
  // Package name mappings
  packageMappings: [
    { from: "opencode-ai", to: "@kilocode/cli" },
    { from: "@opencode-ai/cli", to: "@kilocode/cli" },
    // ...
  ],

  // Files to always keep Kilo's version
  keepOurs: [
    "README.md",
    "CONTRIBUTING.md",
    "AGENTS.md",
    // ...
  ],

  // Kilo-specific directories
  kiloDirectories: [
    "packages/opencode/src/kilocode",
    "packages/kilo-gateway",
    // ...
  ],
}

CLI Options

merge.ts

Options:
  --version <version>  Target upstream version (e.g., v1.1.49)
  --commit <hash>      Target upstream commit hash
  --dry-run            Preview changes without applying them
  --no-push            Don't push branches to remote
  --report-only        Only generate conflict report
  --verbose            Enable verbose logging
  --author <name>      Author name for branch prefix

analyze.ts

Options:
  --version <version>  Target upstream version
  --commit <hash>      Target commit hash
  --output <file>      Output file for report

Manual Conflict Resolution

After running the merge script, you may have remaining conflicts. To resolve:

1. Open each conflicted file
2. Look for kilocode_change markers to identify Kilo-specific code
3. Resolve conflicts, keeping Kilo-specific changes
4. Stage and commit:

   git add -A
   git commit -m "resolve merge conflicts"
   

Rollback

If something goes wrong:

# Find your backup branch
git branch | grep backup

# Reset to backup
git checkout dev
git reset --hard backup/dev-<timestamp>

Adding New Transformations

String-based (simple)

Edit transforms/package-names.ts and add patterns to PACKAGE_PATTERNS.

AST-based (robust)

1. Create a new file in codemods/
2. Use ts-morph for TypeScript AST manipulation
3. Export transform functions
4. Add to the merge orchestration if needed

Troubleshooting

"No upstream remote found"

git remote add upstream git@github.com:anomalyco/opencode.git

"Working directory has uncommitted changes"

git stash
# or
git commit -am "WIP"

Merge conflicts after auto-resolution

Some files require manual review. Check the generated report for guidance.