Pullee

Problem Statement

Long-lived branches silently drift. You're working on main, dev moves ahead, and you don't notice until you hit a wall of merge conflicts or a CI pipeline fails because your branch was stale. Manually git fetch && git merge-ing on a cadence is tedious and easy to forget — and a careless merge can introduce conflicts you didn't want.

Proposed Solution

Pullee is a globally-installable CLI that watches a branch and keeps it up to date from a source branch automatically — but only when it's safe. It performs fast-forward-only merges by default (so it never creates conflicts), fires OS notifications on pulls or conflicts, and logs every attempt with statistics you can inspect.

Full Solution Details

• pullee watch main dev — continuous monitoring; periodically fetches and pulls dev into main, default every 5 min (--interval to change).
• pullee sync main dev — one-time pull and exit.
• pullee status — pull counts, success rates, timing.
• pullee history [branch] [--limit N] — recent pull events, filterable by branch.
• Safety — fast-forward merges only; requires a clean working directory; never clobbers uncommitted work.
• Notifications — OS-level alerts for successful pulls and for conflicts that need a human.

Technical Documentation

Node (≥14) + TypeScript CLI built on a clean three-layer separation: managers (single-responsibility wrappers — GitManager for git ops, ConfigManager for persistence, NotificationManager for OS notifications, LogManager for event logging), services (WatchService orchestrates the sync/watch business logic), and commands (thin CLI handlers watch/sync/status/history). Distributed on npm as a global binary. Every pull attempt is timestamped and logged, which powers the status/history analytics.

Tech Stack

TypeScript, Node.js (≥14), Commander-style CLI, git plumbing, OS notification APIs; npm global distribution.

System Design

  CLI command (watch / sync / status / history)
        │
        ▼
   WatchService (orchestration)
        │
  ┌─────┼───────────────┬──────────────────┐
  ▼     ▼               ▼                  ▼
GitManager  ConfigManager  NotificationManager  LogManager
(fetch,     (persist        (OS alerts:          (timestamped
 FF-merge)   config/state)    pull / conflict)     event log) ──► status / history
        │
   fast-forward only · requires clean working dir

Smart Architectural Decisions

• Fast-forward-only by default. The single most important decision: Pullee refuses anything that isn't a clean fast-forward, so automation can never create a merge conflict or rewrite your work. Safety is the default, not an option.
• Manager-per-concern. Git, config, notifications, and logging are isolated single-responsibility managers behind a WatchService, making each independently testable and the CLI handlers trivially thin.
• Observability built in. Logging every attempt turns the tool into its own analytics source (status, history) — you can see success rates and timing, not just fire-and-forget.
• Clean-tree precondition prevents the classic footgun of auto-pulling over uncommitted changes.

Impacts

Keeps branches continuously and safely in sync, preventing the stale-branch → conflict → failed-pipeline cycle. Estimated to save engineering teams meaningful time annually by eliminating manual sync chores and drift-induced CI failures.

Demonstrated Skills

CLI/developer-tooling design; git internals (fetch, fast-forward semantics, safety preconditions); clean layered architecture (managers/services/commands); OS-level integration (native notifications); local persistence and event-log analytics; TypeScript; npm binary packaging and distribution.