feat: initial public release of drift

Fast, interactive file comparison tool with a terminal UI.

Compare directories, archives (IPA, APK, JAR, tar), Mach-O binaries,
plists, and text files — with structured JSON output for CI pipelines.

Architecture:
- compare/ — pure-Go comparison engine (tree, binary, plist, text modes)
- tui/ — Bubbletea-based interactive terminal UI with split-pane layout
- cmd/drift/ — CLI entry point with kong

Cross-platform: macOS, Linux, Windows. Binary analysis and plist
conversion degrade gracefully when platform tools are unavailable.

Author: luispadron

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,31 +1,21 @@
 ---
-name: 🐛 Bug Report
-about: Thank you for taking the time, please report a reproducible bug
-title: "[Bug] <Bug Title Here>"
+name: Bug Report
+about: Report a bug with drift
 labels: bug
-assignees: add codeowner's @name here 
-
+assignees: luispadron
 ---
 
-**Describe the bug**
-*A clear and concise description of what the bug is.*
+**What happened?**
 
-**To Reproduce:**
-*Steps to reproduce the behavior:*
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+**Command run:**
+```
+drift ...
+```
 
 **Expected behavior:**
-*A clear and concise description of what you expected to happen.*
-
-**Supporting Material**
-*If applicable, add screenshots, output log and/or other documentation to help explain your problem.*
 
-**Environment (please complete the following information):**
- - OS: [ex: iOS]
- - Version 
+**Environment:**
+- OS:
+- drift version (`drift --version`):
 
 **Additional context**
-Add any other context that you feel is relevant about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1 @@
-contact_links:
-    - name: ❓ Questions and Help 🤔
-      url: https://discord.gg/block-opensource (/add your discord channel if applicable)
-      about: This issue tracker is not for support questions. Please refer to the community for more help. 
+blank_issues_enabled: false

.github/assets/drift_logo.png

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Build
+        run: go build -o drift ./cmd/drift
+
+      - name: Test
+        run: go test ./...
+
+      - name: Vet
+        run: go vet ./...

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. 0.1.0, without 'v' prefix)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Create and push tag
+        run: |
+          git tag "v${{ inputs.version }}"
+          git push origin "v${{ inputs.version }}"
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v7
+        with:
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,3 @@
+/drift
+.agents/
+.DS_Store

.gitignore

@@ -0,0 +1,26 @@
+version: 2
+
+builds:
+  - main: ./cmd/drift
+    binary: drift
+    ldflags:
+      - -s -w -X main.Version={{.Version}}
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
+
+archives:
+  - name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    format_overrides:
+      - goos: windows
+        formats: ["zip"]
+
+checksum:
+  name_template: "checksums.txt"
+
+changelog:
+  sort: asc

.goreleaser.yaml

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+## Build & Test
+
+- **Build:** `go build -o drift ./cmd/drift`
+- **Test:** `go test ./...` or `go test ./compare -run TestName`
+- **Vet:** `go vet ./...`
+
+## Architecture
+
+`drift` is a two-layer tool: a comparison engine and an interactive TUI.
+
+### Compare engine (`compare/`)
+
+Pure-Go diffing logic. `Compare(pathA, pathB, mode)` returns a `*Result` with a tree of `Node`s representing the comparison. `Detail(result, node)` produces the detailed diff for a single node.
+
+Supported modes: tree (directories/archives), binary (Mach-O), plist, text. Mode is auto-detected from inputs.
+
+Key files:
+- `compare.go` — entry point, mode detection, tree comparison
+- `directory.go` — directory walking and tree building
+- `archive.go` — archive extraction (zip, tar, tar.gz, tar.bz2)
+- `binary.go` — Mach-O analysis via nm/size/otool
+- `plist.go` — plist conversion via plutil
+- `text.go` — line-by-line unified diff
+- `types.go` — `Result`, `Node`, `DetailResult` types
+- `hash.go` — content hashing for change detection
+
+### TUI (`tui/`)
+
+Bubbletea-based interactive terminal UI. Three-tier component model:
+
+1. **App** (`app.go`) — root model, layout, keyboard dispatch
+2. **Components** (`tree.go`, `detail.go`, `search.go`, `overlay.go`, `alert.go`) — stateful sub-models
+3. **Views** (`view_*.go`, `summary.go`, `render.go`) — pure render functions, no state
+
+- `styles.go` — all lipgloss styles
+- `help.go` — keybinding definitions
+- `components.go` — detail content builder
+
+### Entry point
+
+- `cmd/drift/main.go` — CLI struct, kong parser, `run()` method
+
+## Code style
+
+- Views are pure functions: `func renderX(width int, data T) string`
+- Components own state and implement `Update`/`View`
+- Use lipgloss for all styling — no raw ANSI

CLAUDE.md

@@ -1,24 +1,4 @@
 # This CODEOWNERS file denotes the project leads
 # and encodes their responsibilities for code review.
 
-# Instructions: At a minimum, replace the '@GITHUB_USER_NAME_GOES_HERE'
-# here with at least one project lead.
-
-# Lines starting with '#' are comments.
-# Each line is a file pattern followed by one or more owners.
-# The format is described: https://github.blog/2017-07-06-introducing-code-owners/
-
-# These owners will be the default owners for everything in the repo.
 *       @luispadron
-
-
-# -----------------------------------------------
-# BELOW THIS LINE ARE TEMPLATES, UNUSED
-# -----------------------------------------------
-# Order is important. The last matching pattern has the most precedence.
-# So if a pull request only touches javascript files, only these owners
-# will be requested to review.
-# *.js    @octocat @github/js
-
-# You can also use email addresses if you prefer.
-# docs/*  [email protected]

CODEOWNERS

@@ -1,36 +1,107 @@
-# drift README
+# drift
 
-Congrats, project leads! You got a new project to grow!
+<p align="center">
+  <img src=".github/assets/drift_logo.png" alt="Drift logo" width="700">
+</p>
 
-This stub is meant to help you form a strong community around your work. It's yours to adapt, and may 
-diverge from this initial structure. Just keep the files seeded in this repo, and the rest is yours to evolve! 
+A **fast**, **interactive** file **comparison tool**. 
 
-## Introduction
+Compare directories, archives, binaries, plists, and text files with a terminal UI or structured JSON output.
 
-Orient users to the project here. This is a good place to start with an assumption
-that the user knows very little - so start with the Big Picture and show how this
-project fits into it.
+## Installation
 
-Then maybe a dive into what this project does.
+```sh
+go install github.com/block/drift/cmd/drift@latest
+```
 
-Diagrams and other visuals are helpful here. Perhaps code snippets showing usage.
+Or [download a pre-built binary for your platform from a release](https://github.com/block/drift/releases)
 
-Project leads should complete, alongside this `README`:
+Or build from source:
 
-* [CODEOWNERS](./CODEOWNERS) - set project lead(s)
-* [CONTRIBUTING.md](./CONTRIBUTING.md) - Fill out how to: install prereqs, build, test, run, access CI, chat, discuss, file issues
-* [Bug-report.md](.github/ISSUE_TEMPLATE/bug-report.md) - Fill out `Assignees` add codeowners @names
-* [config.yml](.github/ISSUE_TEMPLATE/config.yml) - remove "(/add your discord channel..)" and replace the url with your Discord channel if applicable
+```sh
+gh repo clone block/drift
+cd drift
+go run ./cmd/drift --help
+```
 
-The other files in this template repo may be used as-is:
+## Usage
 
-* [GOVERNANCE.md](./GOVERNANCE.md)
-* [LICENSE](./LICENSE)
+```sh
+# Compare two directories
+drift path/a path/b
 
-## Project Resources
+# Compare two archives (.ipa, .apk, .aar, .jar, .tar.gz, .tar.bz2)
+drift app-v1.ipa app-v2.ipa
 
-| Resource                                   | Description                                                                    |
-| ------------------------------------------ | ------------------------------------------------------------------------------ |
-| [CODEOWNERS](./CODEOWNERS)                 | Outlines the project lead(s)                                                   |
-| [GOVERNANCE.md](./GOVERNANCE.md)           | Project governance                                                             |
-| [LICENSE](./LICENSE)                       | Apache License, Version 2.0                                                    |
+# Compare two binaries
+drift bin-v1 bin-v2
+
+# Force a specific comparison mode
+drift -m binary lib-v1.dylib lib-v2.dylib
+
+# JSON output (non-interactive, for scripting)
+drift --json path/a path/b
+```
+
+### Comparison modes
+
+drift auto-detects the comparison mode based on the inputs:
+
+| Mode | Inputs | What it shows |
+|------|--------|---------------|
+| **tree** | Directories, archives | File tree with added/removed/modified indicators, per-file diffs |
+| **binary** | Mach-O binaries | Sections, sizes, symbols, load commands. Requires `nm` and `size` |
+| **plist** | Property lists (.plist) | Structured key-value diff. Binary plists require `plutil` |
+| **text** | Everything else | Line-by-line unified diff |
+
+Use `-m <mode>` to override auto-detection.
+
+### Archives
+
+drift transparently extracts and compares the contents of:
+- `.ipa` (iOS app bundles)
+- `.apk` (Android app bundles)
+- `.aar` (Android libraries)
+- `.jar` (Java archives)
+- `.tar`, `.tar.gz` / `.tgz`, `.tar.bz2`
+
+## Interactive TUI
+
+When stdout is a terminal, drift launches an interactive Bubbletea-based TUI with a split-pane layout: file tree on the left, detail diff on the right.
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑`/`k`, `↓`/`j` | Navigate tree |
+| `→`/`enter`/`l` | Expand node |
+| `←`/`h` | Collapse node |
+| `tab` | Switch pane focus |
+| `n`/`N` | Next/previous change |
+| `f` | Cycle filter (all → added → removed → modified) |
+| `1`-`4` | Filter: all, added, removed, modified |
+| `/` | Search (fuzzy match in tree, text search in detail) |
+| `s` | Swap A ↔ B |
+| `c` | Copy detail to clipboard |
+| `pgup`/`pgdn` | Scroll detail pane |
+| `g`/`G` | Jump to top/bottom |
+| `?` | Toggle full help |
+| `q`/`ctrl+c` | Quit |
+
+## JSON output
+
+Pass `--json` to get structured JSON output suitable for scripting and CI pipelines. For tree mode, the output is the full comparison result. For single-file modes (binary, plist, text), the output includes both the summary and the detailed diff.
+
+## Platform support
+
+drift works on **macOS**, **Linux**, and **Windows**. Core features (directory/archive comparison, text diffing) work everywhere. Some features require external tools and degrade gracefully when they are unavailable:
+
+| Tool | Used for | Availability |
+| --- | --- | --- |
+| `nm`, `size` | Mach-O binary analysis | macOS (Xcode CLI Tools), Linux (binutils) |
+| `plutil` | Binary plist conversion | macOS only (XML plists work everywhere) |
+| `xclip` or `xsel` | Clipboard | Linux only (macOS and Windows work natively) |
+
+## License
+
+[Apache License 2.0](LICENSE)