v1.1.0 - Evaluate & Edit Approach

Breaking Changes

• Removed merge/rebase/cherry-pick workflow. Claude now applies upstream changes by editing files directly.
• upstream-diff.js and upstream-status.js output field mergeBase renamed to baseCommit.
• .upstream-sync.json is now committed to git (previously gitignored).

New Features

• Direct file editing workflow — Instead of merging upstream commits, Claude extracts diffs, evaluates each change against local code, and applies them via Edit/Write tools. Full control over what gets applied and how.
• upstream-diff.js — New script that extracts per-file diffs from upstream since last sync. Supports --file, --commit, --files-only, --context filters. Outputs diff content, upstream file content, and local file content for evaluation.
• sync-state.js — New script for managing sync state tracking (show, save, reset). Tracks which upstream commit was last synced so subsequent syncs only show new changes.
• Sync state tracking — .upstream-sync.json stores the last synced upstream commit hash. Committed to git so sync state persists across machines and clones.
• Incremental syncs — First sync uses git merge-base as starting point. After saving state, subsequent syncs only show changes since the last sync point.
• Sync report — Claude now presents a structured report after every sync: applied changes, new files, skipped changes, deleted files, and notes.

Improvements

• upstream-status.js — Now uses sync state as baseline instead of HEAD..remote/branch, enabling accurate incremental commit listing.
• git-utils.js — Added loadSyncState(), saveSyncState(), getBaseCommit() functions with remote/branch validation to prevent cross-remote state mismatch.
• Reference docs rewritten — sync-workflow.md (7 phases), review-guide.md (evaluation methodology), conflict-resolution.md (manual application guide) all updated for the new approach.
• README rewritten — Practical usage guide with Claude Code, real-world scenarios, comparison table vs git merge.

Bug Fixes

• Fixed getBaseCommit not validating remote/branch match — multi-remote users would silently get wrong diffs.
• Fixed saveSyncState unreachable dead code in fallback branch.
• Fixed sync-state.js hardcoding filename instead of using SYNC_STATE_FILE constant.

Tests

• 52 tests total (was 26), all passing.
• New: 16 tests for upstream-diff.js, 6 tests for sync-state.js, 4 tests for sync state in git-utils.js.

Files Changed

New files (4):

• scripts/upstream-diff.js — Per-file diff extraction
• scripts/sync-state.js — Sync state management
• scripts/__tests__/upstream-diff.test.js — Tests for upstream-diff
• scripts/__tests__/sync-state.test.js — Tests for sync-state
• release-note.md — This file

Modified files (10):

• SKILL.md — New 6-step workflow with sync state and report
• README.md — Complete rewrite
• references/sync-workflow.md — 7-phase evaluate & edit workflow
• references/review-guide.md — Evaluation methodology for direct editing
• references/conflict-resolution.md — Manual change application guide
• scripts/git-utils.js — Sync state functions, getBaseCommit
• scripts/upstream-status.js — Uses sync state baseline
• scripts/__tests__/git-utils.test.js — Sync state tests
• scripts/package.json — New test files added

v1.0.2 — Auto Remote Setup & Security Hardening

Highlights

Scripts now auto-configure the upstream remote when UPSTREAM_URL is set in .env — no manual git remote add needed. Security audit fixed shell injection and incomplete input validation.

New Features

Auto Remote Setup

• New ensureRemote() in git-utils.js — automatically runs git remote add upstream <url> if remote doesn't exist and UPSTREAM_URL is configured
• Both upstream-status.js and conflict-preview.js use it before any operation
• If neither remote nor URL is configured, provides clear guidance on what to set up
• Does not touch origin — git push still goes to your fork

Cherry-pick Conflict Preview

• New previewCherryPickConflicts() analyzes a specific commit against locally modified files
• Usage: node conflict-preview.js --strategy cherry-pick --commit <hash>
• Reports which files in the target commit overlap with local changes

Security Fixes

• Shell injection eliminated — execSync replaced with execFileSync + args array across all git calls
• Input validation — validateArg() regex on all user-facing args (remote, branch, commit, since)
• NaN guard — --limit falls back to default on invalid input

Bug Fixes

• Truncated merge-base regression — previewRebaseConflicts now uses full hash internally, truncates only for display
• Silent fetch failures — fetchRemote() returns boolean, callers surface warnings in both text and JSON output
• Missing test in npm test — git-utils.test.js added to package.json test script
• fetchWarning in JSON — conflict-preview.js now includes fetchWarning in JSON output (matching upstream-status.js)

Configuration

New .env variable:

# URL of the original repo (auto-creates remote if not configured)
UPSTREAM_URL=https://github.com/original-author/original-repo.git

Setup flow:

origin   → your fork (unchanged, git push still works)
upstream → original repo (auto-created from UPSTREAM_URL)

Tests

• 26 tests, all passing (was 25)
• Added cherry-pick strategy test with real git repos

---

v1.0.0 — Upstream Sync Skill for Claude Code

What's New

A Claude Code agent skill that automates syncing forked/cloned open source repositories with upstream changes.

Core Scripts

• upstream-status.js — Detects upstream remote, fetches latest commits, lists new changes with diffstat and ahead/behind counts
• conflict-preview.js — Dry-run merge/rebase conflict detection with file-level risk categorization (HIGH/LOW) and actionable recommendations (SAFE_TO_MERGE, MERGE_WITH_MANUAL_RESOLUTION, CONSIDER_CHERRY_PICK)
• git-utils.js — Shared utilities with git wrapper, .env cascade loading

Integration Strategies

• Merge — Full branch integration with conflict analysis
• Rebase — Linear history with local commit replay count estimation

Reference Guides

• 5-phase sync workflow (setup, review, analyze, integrate, verify)
• Upstream commit review methodology with decision matrix
• Conflict resolution strategies prioritized by dependency order

Quality

• 25 integration tests using real temporary git repos (zero mocks)
• Zero runtime dependencies — Node.js >= 18 only
• Cross-platform support (Linux/macOS/Windows)

Documentation

• Full README with installation (copy/symlink), CLI usage examples, sample outputs, and real-world scenarios

v1.0.1 — Upstream Sync Skill for Claude Code

What's New

A Claude Code agent skill that automates syncing forked/cloned open source repositories with upstream changes.

Core Scripts

• upstream-status.js — Detects upstream remote, fetches latest commits, lists new changes with diffstat and ahead/behind counts
• conflict-preview.js — Dry-run merge/rebase/cherry-pick conflict detection with file-level risk categorization (HIGH/LOW) and actionable recommendations (SAFE_TO_MERGE, MERGE_WITH_MANUAL_RESOLUTION, CONSIDER_CHERRY_PICK)
• git-utils.js — Shared utilities with execFileSync-based git wrapper (no shell injection), .env cascade loading, input validation

Integration Strategies

• Merge — Full branch integration with conflict analysis
• Rebase — Linear history with local commit replay count estimation
• Cherry-pick — Per-commit conflict preview against locally modified files

Reference Guides

• 5-phase sync workflow (setup, review, analyze, integrate, verify)
• Upstream commit review methodology with decision matrix
• Conflict resolution strategies prioritized by dependency order

Quality

• 26 integration tests using real temporary git repos (zero mocks)
• Zero runtime dependencies — Node.js >= 18 only
• Input validation on all user-facing args (remote, branch, commit, since)
• Cross-platform support (Linux/macOS/Windows)

Documentation

• Full README with installation (copy/symlink), CLI usage examples, sample outputs, and real-world scenarios

v1.0.0

Full Changelog: https://github.com/dris1153/upstream-sync/commits/v1.0.0