Metadata-Version: 2.4
Name: forklift-ai
Version: 0.1.0
Summary: A local AI-assisted tool for maintaining long-lived forks.
Author: Forklift Contributors
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: textual>=0.74
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# Forklift

Forklift is a local CLI/TUI for keeping long-lived forks current. It finds the
fork's current upstream base, chooses the next upstream target, rebases your
custom commits, runs your local checks, and writes a report with the exact files,
commits, checks, and branch changes.

```text
detect-upstream-base -> target discovery -> rebase-assistant -> local-test-runner
```

## Install

```bash
uv tool install forklift-ai
```

or:

```bash
pipx install forklift-ai
```

The primary command is:

```bash
forklift
```

`auto-rebase` is kept as a compatibility alias.

## Quick Start

Run these inside your forked repository:

```bash
forklift init
forklift doctor
forklift detect-base
forklift run
```

`forklift init` writes `.auto-rebase.yaml` and opens a guided setup form when the
terminal is interactive. The form auto-loads local remotes, remote-tracking
branches, tags, tag patterns, and likely test commands.

For later edits:

```bash
forklift config edit
```

## What `forklift run` Does

```text
1. refuse to start if the working tree has unrelated local changes
2. detect the fork's current upstream base
3. resolve the target upstream tag or branch
4. run baseline checks before rebasing
5. create a local backup branch
6. rebase your custom commits onto the target
7. run post-rebase checks
8. apply the successful rebase back to your original branch
9. show a run screen with the result and push decision
10. write artifacts and a final summary
```

If `use_worktree: true` is enabled, Forklift does the risky work in a temporary
worktree first. When the post-rebase checks pass, it moves your original branch
to the successful rebased HEAD and removes the temporary run branch.

The CLI prints the important result directly:

```text
Forklift run complete
- status: healthy
- branch: test_branch
- base: v1
- target: v2
- custom commits replayed: 4
- changed files: 7
- local branch updated: yes
- backup branch: auto-rebase/backup-...

Checks
- baseline/tests: passed (0)
- post_rebase/tests: passed (0)

Next step
- remote branch updated: no
- push rebased branch: git push --force-with-lease origin test_branch

status=healthy
report=.auto-rebase/artifacts/.../summary.md
```

In an interactive terminal, `forklift run` opens a TUI that shows the local result
and asks whether to push the rewritten branch. Forklift never pushes silently.
A successful rebase rewrites local commit IDs, so remote updates require an
explicit confirmation and use `--force-with-lease`.

For scripts or raw terminal output:

```bash
forklift run --plain
```

## Configuration

The generated `.auto-rebase.yaml` is intentionally small enough to review:

```yaml
project:
  name: forklift

auto_rebase:
  target_mode: latest_tag
  explicit_target: null
  max_iterations: 5

detect_upstream_base:
  upstream_remote: upstream
  upstream_branch: main
  tag_pattern: "v*"

local_test_runner:
  baseline_required: true
  checks:
    - name: tests
      run: "uv run --extra dev pytest -q"
      timeout_minutes: 20
```

`forklift init` overwrites an existing `.auto-rebase.yaml` with a clean generated
file. Use `forklift config edit` when you want to update it later.

## Artifacts

Every run writes a timestamped folder under `.auto-rebase/artifacts/`:

```text
detection/      current base, base tag, custom commits, patch
target/         selected target ref and upstream diff
measurement/    baseline and post-rebase command logs
controller/     rebase logs, conflicts, repair packets, apply logs
summary.md      branch update, commits, conflicts, files, check results
replay.sh       manual reproduction script
```

The newest run is also linked at `.auto-rebase/artifacts/latest/`.

## Safety

Forklift is local-first and conservative:

- refuses dirty working trees by default
- creates a backup branch before rebasing
- never pushes without explicit confirmation
- only updates the original branch after post-rebase checks pass
- keeps failed/conflicted worktrees available for inspection
- redacts common secret variables from logs and repair packets

## Development

```bash
uv run --extra dev pytest
uv run --extra dev ruff check .
uv build --no-sources
```

Verify a built wheel through the tool-install path:

```bash
UV_TOOL_DIR=/tmp/forklift-tool \
UV_TOOL_BIN_DIR=/tmp/forklift-tool-bin \
uv tool install dist/forklift_ai-0.1.0-py3-none-any.whl

/tmp/forklift-tool-bin/forklift init
```
