Upstream Merge Automation by catrielmuller · Pull Request #102 · Kilo-Org/kilo

catrielmuller · 2026-02-03T22:56:19Z

Context

Kilo CLI is a fork of opencode, and we regularly merge upstream changes to stay in sync. Previously, this was a painful manual process involving many merge conflicts due to branding differences (OpenCode vs Kilo).

This PR introduces a comprehensive automation toolset in script/upstream/ that transforms upstream code before merging, drastically reducing conflicts and streamlining the sync process.

Implementation

Architecture Overview

The automation follows an 8-step process:

Environment Validation - Checks for upstream remote and clean working directory
Fetch Upstream - Gets latest tags and commits from upstream
Version Selection - Determines target version (specific or latest)
Conflict Analysis - Pre-analyzes which files will conflict and categorizes them
Branch Creation - Creates backup, Kilo merge, and transformed upstream branches
Pre-Merge Transformations - Applies ALL branding transforms to upstream BEFORE merging
Merge & Auto-Resolution - Merges transformed upstream; remaining conflicts are actual code differences
Lock File Regeneration - Regenerates bun.lock, Cargo.lock after merge

Key Insight: Pre-Merge Transformation

The critical innovation is applying branding transforms before the merge:

Previously: Git saw "OpenCode" vs "Kilo" as conflicts
Now: Upstream is transformed to "Kilo" branding first, so Git sees no conflict for branding-only files

The only remaining conflicts are files with actual code differences (files with kilocode_change markers).

Components

Main Scripts (`script/upstream/`)

Script	Purpose
`merge.ts`	Full orchestration - validates, transforms, merges, reports
`analyze.ts`	Dry-run analysis without merging
`list-versions.ts`	Lists available upstream versions

Transform Pipeline (`transforms/`)

Transform	Handles
`package-names.ts`	`opencode-ai` -> `@kilocode/cli` in all files
`preserve-versions.ts`	Keeps Kilo's version numbers in package.json
`transform-i18n.ts`	Branding in translation files (OpenCode -> Kilo)
`transform-take-theirs.ts`	UI components with branding-only differences
`transform-tauri.ts`	Desktop app configs (identifiers, names)
`transform-package-json.ts`	package.json with Kilo dependency injection
`transform-scripts.ts`	GitHub API references (anomalyco -> Kilo-Org)
`transform-extensions.ts`	Zed and other extension files
`transform-web.ts`	Documentation/web files (.mdx)
`keep-ours.ts`	Files to never take from upstream (README, workflows)
`skip-files.ts`	Files to remove (translated READMEs, STATS.md)
`lock-files.ts`	Accept ours & regenerate after merge

AST-Based Codemods (`codemods/`)

Codemod	Purpose
`transform-imports.ts`	Transform import statements using ts-morph
`transform-strings.ts`	Transform string literals with full AST analysis

Utilities (`utils/`)

Utility	Purpose
`config.ts`	Centralized configuration (patterns, mappings, keepOurs list)
`git.ts`	Git operations (checkout, merge, branch management)
`logger.ts`	Consistent logging with progress indicators
`report.ts`	Conflict analysis and markdown report generation
`version.ts`	Version detection and comparison

Configuration Highlights

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

// Files that never take upstream changes
keepOurs: [
  "README.md",
  ".github/workflows/publish.yml",
  "AGENTS.md",
  // ...
]

// Files removed during merge
skipFiles: [
  "README.*.md", // Translated READMEs
  "STATS.md",
  // ...
]

// Kilo-specific directories (always preserved)
kiloDirectories: ["packages/opencode/src/kilocode", "packages/kilo-gateway", "script/upstream"]

Tradeoffs & Decisions

Pre-merge vs post-merge transforms: We chose pre-merge to minimize conflicts. The tradeoff is that the upstream branch is modified, but this is isolated to a feature branch.
String-based vs AST-based transforms: Most transforms use regex for speed. AST-based codemods (ts-morph) are reserved for complex cases where context matters.
Lock file handling: We accept "ours" and regenerate rather than attempting 3-way merge. Lock files are not meant to be manually merged.
Manual review for kilocode_change files: Files with actual code differences still require manual review, which is intentional - these contain Kilo-specific logic that needs human judgment.

Screenshots

before	after
Manual merge with 50+ conflicts	Automated merge with 0-5 conflicts
Hours of conflict resolution	Minutes of verification

How to Test

# Navigate to upstream scripts
cd script/upstream
bun install

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

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

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

# Full merge (creates branches, doesn't push by default with --no-push)
bun run merge.ts --version v1.1.49 --no-push

# Full merge with push
bun run merge.ts --version v1.1.49

After running, you should see:

A backup branch created: backup/dev-<timestamp>
A Kilo merge branch: <author>/kilo-opencode-<version>
A transformed upstream branch: <author>/opencode-<version>
A detailed report: upstream-merge-report-<version>.md

Rollback

If something goes wrong:

git checkout dev
git reset --hard backup/dev-<timestamp>

kiloconnect · 2026-02-03T22:57:37Z

script/upstream/transforms/transform-web.ts

+ * by transforming OpenCode references to Kilo.
+ */
+
+import { $ } from "bun"


WARNING: Unused import {$}

In script/upstream/transforms/transform-web.ts, import { $ } from "bun" is only used by transformWebFile() when options.dryRun is false, but options.dryRun currently returns early before the git checkout --theirs step (so $ is never used in dry-run). However in the non-dry-run path, $ is used; so the import is used.

(If the intent is to allow dry-run without requiring git operations, consider keeping as-is; otherwise, if this script should always do git checkout before transforming, move the dry-run early return to after the checkout stage.)

kiloconnect · 2026-02-03T22:57:37Z

script/upstream/utils/git.ts

+  }
+}
+
+export async function commit(message: string): Promise<void> {


CRITICAL: commit() only commits tracked changes

commit() uses git commit -am, which does not include newly added files. In this PR, the upstream-merge tool adds new files under script/upstream/, so the transformation commit in merge.ts may miss those additions unless they were already tracked.

Safer pattern for automation is git commit -m after an explicit git add -A (which merge.ts already does via stageAll()).

kiloconnect · 2026-02-03T22:57:37Z

script/upstream/utils/version.ts

+ */
+
+import { $ } from "bun"
+import { getUpstreamTags, getCommitMessage, getTagsForCommit } from "./git"


SUGGESTION: Unused import getUpstreamTags

getUpstreamTags is imported but not used in this file. Consider removing it to avoid lint/tsc warnings.

kiloconnect · 2026-02-03T22:57:56Z

Code Review Summary

Status: 1 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
`script/upstream/transforms/transform-take-theirs.ts`	137	Preserve patterns computed but not enforced; `.opencode/` and `opencode.json` may be rewritten

Fix these issues in Kilo Cloud

Files Reviewed (25 files)

script/upstream/transforms/transform-take-theirs.ts - 1 issue
script/upstream/transforms/transform-web.ts - 0 issues
script/upstream/transforms/transform-tauri.ts - 0 issues
script/upstream/transforms/transform-package-json.ts - 0 issues
script/upstream/transforms/transform-scripts.ts - 0 issues
script/upstream/transforms/transform-extensions.ts - 0 issues
script/upstream/transforms/transform-i18n.ts - 0 issues
script/upstream/transforms/skip-files.ts - 0 issues
script/upstream/transforms/keep-ours.ts - 0 issues
script/upstream/transforms/lock-files.ts - 0 issues
script/upstream/transforms/package-names.ts - 0 issues
script/upstream/transforms/preserve-versions.ts - 0 issues
script/upstream/utils/config.ts - 0 issues
script/upstream/utils/git.ts - 0 issues
script/upstream/utils/logger.ts - 0 issues
script/upstream/utils/report.ts - 0 issues
script/upstream/utils/version.ts - 0 issues
script/upstream/analyze.ts - 0 issues
script/upstream/merge.ts - 0 issues
script/upstream/index.ts - 0 issues
script/upstream/list-versions.ts - 0 issues
script/upstream/README.md - 0 issues
script/upstream/package.json - 0 issues
.opencode/tool/github-pr-search.ts - 0 issues
.opencode/tool/github-triage.ts - 0 issues

marius-kilocode · 2026-02-04T10:13:39Z

@catrielmuller how fragile do you judge this script? It's a lot to maintain.

kiloconnect · 2026-02-04T14:36:41Z

script/upstream/transforms/transform-web.ts

+ * by transforming OpenCode references to Kilo.
+ */
+
+import { $ } from "bun"


WARNING: Unused import {$}

$ is imported but never referenced in this file. Keeping unused imports can hide intended-but-missing behavior (e.g., forgetting to stage via git).

kiloconnect · 2026-02-04T15:26:53Z

script/upstream/utils/version.ts

+  for (const line of output.trim().split("\n")) {
+    // Match lines like: abc123... refs/tags/v1.1.49
+    // Skip annotated tag references (those ending with ^{})
+    const match = line.match(/^([a-f0-9]+)\s+refs\/tags\/([^\^]+)$/)


WARNING: Annotated upstream tags may resolve to the tag object hash, not the commit

git ls-remote --tags returns both refs/tags/<tag> (often the tag object for annotated tags) and refs/tags/<tag>^{} (the peeled commit). The current regex explicitly ignores the ^{} line (per comment) but then uses the remaining hash as commit, which can be incorrect for annotated tags and break downstream checkout/analysis. Prefer collecting both and using the peeled ^{} hash when present (or at least skipping non-peeled hashes when a peeled one exists).

kiloconnect · 2026-02-04T15:26:53Z

script/upstream/transforms/transform-web.ts

+
+  try {
+    // Take upstream's version first
+    await $`git checkout --theirs ${file}`.quiet().nothrow()


WARNING: git checkout --theirs / git add failures can be silently ignored

These commands use .nothrow() and their exit codes aren’t checked. If git checkout --theirs fails (e.g., file not in conflict / path issues), the script will continue and report success, potentially transforming/staging the wrong content. Consider checking exitCode and throwing on non-zero (like fetchUpstream() does) so failures are surfaced reliably.

kiloconnect · 2026-02-04T16:21:21Z

.opencode/tool/github-pr-search.ts

@@ -1,5 +1,5 @@
 /// <reference path="../env.d.ts" />
-import { tool } from "@kilocode/plugin" // kilocode_change
+import { tool } from "@kilocode/plugin"


SUGGESTION: Preserve kilocode_change markers for fork-maintained files

This file is not in a kilocode/ path, so removing the // kilocode_change marker makes future upstream merges harder to audit and increases conflict risk. Consider restoring the marker on Kilo-specific deltas (per AGENTS.md).

kiloconnect · 2026-02-04T16:21:21Z

.opencode/tool/github-triage.ts

 /// <reference path="../env.d.ts" />
 // import { Octokit } from "@octokit/rest"
-import { tool } from "@kilocode/plugin" // kilocode_change
+import { tool } from "@kilocode/plugin"


SUGGESTION: Preserve kilocode_change markers for fork-maintained files

Same as above: if this is intended to be a Kilo-only deviation from upstream, keeping the marker helps keep merge diffs minimal and reviewable.

kiloconnect · 2026-02-04T16:21:21Z

script/upstream/transforms/transform-web.ts

+export async function transformWebFile(file: string, options: WebTransformOptions = {}): Promise<WebTransformResult> {
+  if (options.dryRun) {
+    info(`[DRY-RUN] Would transform web file: ${file}`)
+    return { file, action: "transformed", replacements: 0, dryRun: true }


WARNING: --dry-run currently reports action: "transformed"

In dry-run mode, transformWebFile() returns action: "transformed" and will be counted as transformed by the CLI summary, even though no changes are applied. This can mislead automation/logs.

Suggested change

return { file, action: "transformed", replacements: 0, dryRun: true }

return { file, action: "skipped", replacements: 0, dryRun: true }

kiloconnect · 2026-02-04T16:21:22Z

script/upstream/utils/version.ts

+ */
+export async function getCurrentKiloVersion(): Promise<string> {
+  // Resolve path relative to repo root (script is in script/upstream/)
+  const path = new URL("../../../packages/opencode/package.json", import.meta.url).pathname


WARNING: new URL(...).pathname can break on Windows paths

Using .pathname on a file: URL can produce POSIX-style paths (e.g. /C:/...) on Windows. If these scripts are expected to run cross-platform, prefer passing the URL directly to Bun.file() (if supported) or use fileURLToPath() from node:url to convert safely.

kiloconnect · 2026-02-04T16:51:45Z

script/upstream/analyze.ts

+  info("Analyzing changes...")
+
+  // Use commit hash directly since we may not have the tag fetched locally
+  const conflicts = await report.analyzeConflicts(target.commit, config.baseBranch, config.keepOurs)


WARNING: analyzeConflicts() isn’t passed skipFiles, so skip-only upstream artifacts won’t be flagged

merge.ts passes config.skipFiles, but script/upstream/analyze.ts currently doesn’t. This makes the analysis report less accurate (it may recommend manual work for files that the merge flow would auto-remove).

Suggested change

const conflicts = await report.analyzeConflicts(target.commit, config.baseBranch, config.keepOurs)

const conflicts = await report.analyzeConflicts(target.commit, config.baseBranch, config.keepOurs, config.skipFiles)

kiloconnect · 2026-02-04T16:51:45Z

script/upstream/codemods/transform-strings.ts

+    let modified = false
+
+    for (const { pattern, replacement } of STRING_REPLACEMENTS) {
+      if (pattern.test(value)) {


WARNING: Global RegExp + test() without resetting lastIndex can make replacements flaky

In transformStrings(), STRING_REPLACEMENTS uses /g regexes. Calling pattern.test(value) repeatedly across many literals without pattern.lastIndex = 0 can cause false negatives after the first match, leading to skipped transformations depending on iteration order. Consider resetting lastIndex before each test() (or avoid test() and rely on replace() + comparison).

kiloconnect · 2026-02-04T16:51:45Z

script/upstream/codemods/transform-strings.ts

+    }
+
+    if (headModified) {
+      // Template head replacement is complex, skip for now


WARNING: TemplateExpression path increments changes without applying any edit

At script/upstream/codemods/transform-strings.ts, headModified results in changes++, but the AST/text is intentionally left unchanged. That can over-report transformations and may cause no-op saves/commits to be treated as real edits. If template-head handling is intentionally unsupported, consider not incrementing changes here (or implement the replacement).

kiloconnect · 2026-02-04T19:48:01Z

script/upstream/merge.ts

+  // Step 2: Fetch upstream
+  logger.step(2, 8, "Fetching upstream...")
+
+  if (!options.dryRun) {


CRITICAL: --dry-run skips fetching upstream, but later analysis diffs against an upstream commit

In script/upstream/merge.ts, dry-run avoids git fetch upstream, but the script still calls report.analyzeConflicts() using an upstream commit hash from git ls-remote. Without fetching that commit object locally, git diff ${base}...${commit} can fail, breaking dry-run/report generation. Consider fetching upstream even in dry-run (network-only, no working tree changes) or adjusting analysis to use available refs.

kiloconnect · 2026-02-04T19:48:01Z

script/upstream/utils/report.ts

+  }
+
+  // Check if file should always keep ours
+  if (keepOurs.some((pattern) => path.includes(pattern) || path === pattern)) {


WARNING: keepOurs matching via path.includes(...) can unintentionally match unrelated files

In getRecommendation(), keepOurs.some((pattern) => path.includes(pattern) || path === pattern) will treat any path containing e.g. README.md as keep-ours (like packages/app/README.md). That can incorrectly discard upstream changes. Prefer exact path matching or proper glob/minimatch semantics.

kiloconnect · 2026-02-04T19:48:01Z

script/upstream/utils/report.ts

+ * Check if a file should be skipped (not added from upstream)
+ */
+function shouldSkipFile(path: string, skipPatterns: string[]): boolean {
+  return skipPatterns.some((pattern) => path === pattern || path.includes(pattern))


WARNING: skipFiles matching via substring (includes) may skip unintended paths

shouldSkipFile() returns true when path.includes(pattern). With filename-like patterns (e.g. README.de.md), this can match files in unexpected directories and remove them during merge. Prefer exact match or glob matching, consistent with how other file patterns are treated.

kiloconnect · 2026-02-05T12:52:50Z

script/upstream/transforms/keep-ours.ts

+      return regex.test(filePath)
+    }
+    // Contains match
+    return filePath.includes(pattern)


WARNING: shouldKeepOurs() uses substring matching for non-glob patterns

In shouldKeepOurs(), non-glob patterns fall back to filePath.includes(pattern), which can over-match (e.g. a pattern like README.md will also match packages/app/README.md). In an automated merge/conflict resolver, this can silently discard upstream changes for unrelated files.

Consider restricting non-glob patterns to exact path matches (or using a consistent glob matcher) to avoid accidental matches.

kiloconnect · 2026-02-05T12:52:50Z

script/upstream/transforms/transform-take-theirs.ts

+
+  try {
+    // Take upstream's version
+    await $`git checkout --theirs ${file}`.quiet().nothrow()


WARNING: git checkout --theirs / git add failures are ignored

$git checkout --theirs ....quiet().nothrow() will not throw on failure, and the code doesn’t check exitCode before continuing. If checkout/add fails (path missing, not in conflict, git error), the transform may proceed using the wrong content and still report action: "transformed", which can leave the repo in a misleading state.

Recommend checking exitCode for these commands (and returning failed / throwing) so callers can reliably detect and stop on git failures.

kiloconnect · 2026-02-05T14:50:32Z

script/upstream/transforms/transform-web.ts

+    }
+
+    // If line has preserve patterns, skip transformation
+    if (hasPreserve) {


WARNING: PRESERVE_PATTERNS skips the entire line, which can leave other OpenCode references untransformed

In applyWebTransforms(), any line containing e.g. .opencode/ or opencode.json is pushed unchanged and the loop continues. That means other replacements on the same line (like opencode.ai → kilo.ai or OpenCode → Kilo) won't run, leaving partially-branded docs.

Consider preserving only the matched substrings (mask/restore) instead of skipping the full line.

…am/tag ref

kiloconnect · 2026-02-05T17:04:51Z

script/upstream/transforms/transform-take-theirs.ts

+      continue
+    }
+
+    // Check if line has preserve patterns


WARNING: Preserve patterns detected but not enforced

In applyBrandingTransforms(), hasPreserve is computed but never used to skip transformations, so PRESERVE_PATTERNS (e.g. .opencode/, opencode.json) won’t actually be preserved and may be rewritten. Consider short-circuiting when a line matches a preserve pattern (similar to applyWebTransforms()).

catrielmuller requested a review from marius-kilocode February 3, 2026 22:56

kiloconnect bot reviewed Feb 3, 2026

View reviewed changes

catrielmuller mentioned this pull request Feb 3, 2026

OpenCode v1.1.43 #103

Merged

catrielmuller force-pushed the catrielmuller/upstream-scripts branch from 5c4625d to e305491 Compare February 4, 2026 14:35

kiloconnect bot reviewed Feb 4, 2026

View reviewed changes

catrielmuller force-pushed the catrielmuller/upstream-scripts branch 2 times, most recently from a5798ae to 294685f Compare February 4, 2026 16:36

kiloconnect bot reviewed Feb 4, 2026

View reviewed changes

catrielmuller force-pushed the catrielmuller/upstream-scripts branch from 1886e3f to a2e1a37 Compare February 4, 2026 19:40

kiloconnect bot reviewed Feb 4, 2026

View reviewed changes

catrielmuller force-pushed the catrielmuller/upstream-scripts branch from a2e1a37 to a05a66b Compare February 5, 2026 12:44

kiloconnect bot reviewed Feb 5, 2026

View reviewed changes

catrielmuller force-pushed the catrielmuller/upstream-scripts branch from a05a66b to 45a4b24 Compare February 5, 2026 14:42

kiloconnect bot reviewed Feb 5, 2026

View reviewed changes

catrielmuller added 12 commits February 5, 2026 13:31

feat: upstream script wip

b79517a

feat: upstream script wip

bd73c02

refactor: remove kilocode marker from workspace package imports

71b8515

refactor: improve README and i18n translations

c543e4b

fix: use commit hash directly for conflict analysis instead of upstre…

6352beb

…am/tag ref

refactor: improve upstream script

0960e6a

refactor: improve premerge transforms

0334905

refactor: improve branch backup

947b8a9

refactor: not push if there is conflicts

13e37b7

refactor: improve lock files resolution

1e18ea4

refactor: improve nix hashes resolution

345dd87

refactor: improve package import transformations

d90e3b4

catrielmuller added 5 commits February 5, 2026 13:31

refactor: improve Zen service naming

b715b4f

feat: add support for base branch

85ffa66

feat: preserve kilo-i18n

da1f793

refactor: update bun

22118b7

feat: improve package.json deps and overrides

e5f92bc

catrielmuller force-pushed the catrielmuller/upstream-scripts branch from 45a4b24 to e5f92bc Compare February 5, 2026 17:02

kiloconnect bot reviewed Feb 5, 2026

View reviewed changes

marius-kilocode approved these changes Feb 5, 2026

View reviewed changes

catrielmuller merged commit 6eb9796 into dev Feb 5, 2026
5 checks passed

	return { file, action: "transformed", replacements: 0, dryRun: true }
	return { file, action: "skipped", replacements: 0, dryRun: true }

	const conflicts = await report.analyzeConflicts(target.commit, config.baseBranch, config.keepOurs)
	const conflicts = await report.analyzeConflicts(target.commit, config.baseBranch, config.keepOurs, config.skipFiles)

Conversation

catrielmuller commented Feb 3, 2026

Context

Implementation

Architecture Overview

Key Insight: Pre-Merge Transformation

Components

Main Scripts (script/upstream/)

Transform Pipeline (transforms/)

AST-Based Codemods (codemods/)

Utilities (utils/)

Configuration Highlights

Tradeoffs & Decisions

Screenshots

How to Test

Rollback

Uh oh!

kiloconnect bot Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review Summary

Overview

WARNING

Uh oh!

marius-kilocode commented Feb 4, 2026

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

kiloconnect bot Feb 5, 2026

Main Scripts (`script/upstream/`)

Transform Pipeline (`transforms/`)

AST-Based Codemods (`codemods/`)

Utilities (`utils/`)

kiloconnect bot commented Feb 3, 2026 •

edited

Loading