forest-cli 0.2.0__tar.gz → 1.0.0__tar.gz

{forest_cli-0.2.0 → forest_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: forest-cli
-Version: 0.2.0
+Version: 1.0.0
 Summary: git-like data management for arbitrary data trees: workspaces, checkouts, remotes, and sync
 Author-email: Troy Sincomb <troysincomb@gmail.com>
 License: MIT
@@ -12,13 +12,16 @@ Keywords: data-management,sync,cli
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0
 Requires-Dist: polars>=1.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=14.2
+Requires-Dist: rich-click>=1.9.8
+Requires-Dist: textual>=8
 Provides-Extra: observability
 Requires-Dist: sentry-sdk>=2.0; extra == "observability"
 Provides-Extra: dev
@@ -27,6 +30,7 @@ Requires-Dist: mypy>=1.14; extra == "dev"
 Requires-Dist: pre-commit>=4.0; extra == "dev"
 Requires-Dist: pylint>=3.3; extra == "dev"
 Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
 Requires-Dist: pytest-cov>=6.0; extra == "dev"
 Requires-Dist: pytest-randomly>=3.15; extra == "dev"
 Requires-Dist: pytest-rerunfailures>=15.0; extra == "dev"
@@ -36,16 +40,16 @@ Requires-Dist: types-PyYAML; extra == "dev"
 Requires-Dist: vulture>=2.14; extra == "dev"
 Dynamic: license-file
 
-# 🌲 forest <a href="#-dogfood-this-repo-runs-forest"><img align="right" width="42%" src="docs/assets/hero.svg" alt="Animated isometric forest: data trees on a workspace platform, packets syncing up a git branch to a remote cloud"></a>
+# 🌲 forest <a href="#-dogfood-this-repo-runs-forest"><img align="right" width="42%" src="https://tmsincomb.github.io/forest/assets/hero.svg" alt="Animated isometric forest: data trees on a workspace platform, packets syncing up a git branch to a remote cloud"></a>
 
 **git-like data management for arbitrary data trees.**
 
-[![CI](https://github.com/tmsincomb/forest/actions/workflows/ci.yml/badge.svg)](https://github.com/tmsincomb/forest/actions/workflows/ci.yml)
-[![Docs](https://github.com/tmsincomb/forest/actions/workflows/docs.yml/badge.svg)](https://github.com/tmsincomb/forest/actions/workflows/docs.yml)
-[![Release](https://github.com/tmsincomb/forest/actions/workflows/release.yml/badge.svg)](https://github.com/tmsincomb/forest/actions/workflows/release.yml)
+<!-- GitHub Actions workflow badges 404 outside the repo while it is private;
+     re-add CI/Docs/Release badges if the repo goes public. -->
+[![Site](https://img.shields.io/badge/site-tmsincomb.github.io%2Fforest-2d6a4f?logo=materialformkdocs&logoColor=white)](https://tmsincomb.github.io/forest/)
 [![PyPI](https://img.shields.io/pypi/v/forest-cli?logo=pypi&logoColor=white)](https://pypi.org/project/forest-cli/)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](https://github.com/tmsincomb/forest/blob/main/LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![mypy: strict](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)
 
@@ -60,6 +64,13 @@ knows nothing about what the data means, and depends on no other project. It
 moves files and tracks their sync state; it does not validate or interpret their
 contents.
 
+## Documentation
+
+Full docs live at **[tmsincomb.github.io/forest](https://tmsincomb.github.io/forest/)**.
+Start with the **[hands-on tutorial](https://tmsincomb.github.io/forest/tutorial/)** —
+seven short chapters from `forest init` to a fully synced repo, with every
+output block captured from a real session and no cloud credentials required.
+
 ## Model
 
 Fixed-depth, no arbitrary nesting:
@@ -78,12 +89,13 @@ workspace → checkout → stage → unit → files
 
 ## Install
 
-Requires [`rclone`](https://rclone.org/) on `$PATH` for transfers:
-
 ```bash
-pip install -e ./forest
+pip install forest-cli
 ```
 
+Requires [`rclone`](https://rclone.org/) on `$PATH` for transfers. For a
+development install, clone the repo and `pip install -e ".[dev]"`.
+
 ## Quick start
 
 No config files are hand-written. Onboarding is a few commands:
@@ -137,13 +149,51 @@ clone bootstraps with `bind` + `remote use` + `pull`. User-local files
 | `forest remote add/remove/list/use/show` | Manage remotes; `use` selects the active remote (optional while only one remote exists). |
 | `forest push / pull / status / diff / ls` | Sync and inspect against the active remote. Bare `push`/`pull`/`status`/`diff` cover every bound stage (unbound stages warn and skip); `--all` requires all stages bound. |
 | `forest flow` | Emit a Mermaid data-flow diagram of the active checkout. |
-| `forest migrate` | Migrate a legacy `biostore` layout in place (see below). |
+| `forest tui` (or bare `forest`) | Interactive terminal forest (Textual app): each checkout is a pixel-art tree, canopy bands are stages colored by sync status, and the mist above the treetops is data in the cloud (the active remote). Navigate with keys or the mouse; Enter (or a click) on a stage opens its unit drill-down. |
+| `forest prompt init bash\|zsh` | Print an eval-able snippet that shows the active checkout in your shell prompt. |
 
 Run any command with `-C <path>` to operate on another repo without `cd`.
 
 Forest syncs **all** files in a data unit, skipping OS junk (`.DS_Store`,
 AppleDouble `._*`, `*.tmp`). It applies no content-based include/exclude rules.
 
+## Terminal output
+
+On an interactive terminal forest renders rich output — colored status
+tables, file trees, panels, and live progress bars during `push`/`pull`
+(rclone JSON stats streamed to a bar; needs rclone ≥ 1.49, older versions
+transfer fine without a bar). When stdout is piped or redirected, output
+falls back to the plain, machine-parseable format, so scripts never see
+ANSI codes or box drawing.
+
+Overrides: `--color`/`--no-color` per invocation, `FOREST_OUTPUT=rich|plain|auto`
+in the environment, and the [`NO_COLOR`](https://no-color.org)/`FORCE_COLOR`
+conventions. Precedence: flag > `FOREST_OUTPUT` > `NO_COLOR` > `FORCE_COLOR` >
+TTY detection. `--verbose` shows rclone's raw transfer log instead of a
+progress bar; `--quiet` suppresses everything but errors.
+
+## Shell prompt
+
+Show the active checkout in your prompt (bash and zsh), the way git prompts
+show the current branch:
+
+```bash
+# ~/.bashrc
+eval "$(forest prompt init bash)"
+
+# ~/.zshrc
+eval "$(forest prompt init zsh)"
+```
+
+```text
+~/lab/G004 $                # outside a workspace: unchanged
+🌲 G004 ~/lab/G004 $        # inside a workspace with an active checkout
+```
+The snippet is pure shell — it reads `.forest/HEAD` directly and never invokes
+the forest CLI while rendering, so your prompt stays fast. Set
+`FOREST_PROMPT_ICON` to replace the 🌲.
+`FOREST_PROMPT_ICON` to replace the 🌲.
+
 ## Config reference
 
 Checkout `forest.yaml` (shared, committed):
@@ -158,6 +208,8 @@ stages:
   raw:
     remote_path: demo/raw      # optional; defaults to <checkout>/<stage>
     sync_by: subdirectory      # subdirectory | directory | file
+    direction: both            # push | pull | both; bare push/pull skip
+                               # wrong-direction stages, explicit selection errors
 ```
 
 Checkout `local.yaml` (per-machine, gitignored):
@@ -188,44 +240,54 @@ guides live in `docs/runbooks/`.
 | `FOREST_BREAKER_THRESHOLD` | `5` | Consecutive transfer failures before the circuit opens; `0` disables. |
 | `FOREST_BREAKER_RESET_SECONDS` | `60` | Cool-down before an open circuit allows a probe operation. |
 | `FOREST_FLAGS` | unset | Comma-separated feature flags; `raw-logs` disables log secret-scrubbing. |
+| `FOREST_OUTPUT` | `auto` | Terminal rendering: `rich`, `plain`, or `auto` (rich on a TTY, plain when piped). |
+| `NO_COLOR` / `FORCE_COLOR` | unset | Standard color conventions; `FOREST_OUTPUT` and `--color/--no-color` take precedence. |
 
 ## Dogfood: this repo runs forest
 
-This repository manages its own `examples/` tree with forest — a live
-demonstration that `.forest/` and `.git/` coexist without overlapping. It was
-set up with exactly the quick-start commands:
+This repository manages its own `examples/` and `tests/data/` trees with
+forest — a live demonstration that `.forest/` and `.git/` coexist without
+overlapping. It was set up with exactly the quick-start commands:
 
 ```bash
 forest init
 forest checkout demo
-forest remote add origin s3://my-forest-bucket --region us-east-2
-forest add examples ./examples
-forest push
+forest remote add origin s3://forest-cli-test --region us-east-2
+forest add examples ./examples                        # two-way stage (direction: both)
+forest add data ./tests/data --sync-by directory      # two small test files
+forest push                                           # seeds both stages
 ```
 
+After the seeding push, `data` was flipped to `direction: pull` in the
+checkout's `forest.yaml` — it is a read-only reference mirror now: a bare
+`forest push` skips it with a note, and `forest push --stage data` refuses
+with exit 1 (a new stage can start there directly with
+`forest add ... --direction pull`). The `examples` stage keeps syncing both
+ways.
+
 Inspect the result:
 
 ```bash
 git ls-files .forest        # what a clone gets: config.yaml + checkouts/demo/forest.yaml
 cat .gitignore              # forest-managed: HEAD, local.yaml, sync_state.json stay local
-forest status               # sync state of the examples stage
+forest ls                   # stage overview: data shows (directory, pull)
+forest status               # sync state of both stages
 ```
 
-A fresh clone bootstraps the local half with `forest bind examples ./examples`
-followed by `forest pull` (the single configured remote is used automatically).
-Pulling needs AWS credentials for the bucket; the layout is the demonstration.
-
-## Migrating from biostore
-
-Existing biostore repos use `.biostore/` and `biostore.yaml`. Migrate in place:
+A fresh clone bootstraps the local half (HEAD, bindings, sync state are
+gitignored) with:
 
 ```bash
-forest migrate
+forest checkout demo               # select the checkout; clones have no HEAD
+forest bind examples ./examples
+forest bind data ./tests/data
+forest pull --force                # first pull: no local sync state yet, so
+                                   # forest refuses to touch the git-tracked
+                                   # copies without it
 ```
 
-This renames `.biostore/` → `.forest/`, each `biostore.yaml` → `forest.yaml`,
-rewrites the managed `.gitignore` patterns, and verifies the registry parses. It
-refuses to run if a `.forest/` already exists.
+The single configured remote is used automatically. Pulling needs AWS
+credentials for the bucket; the layout is the demonstration.
 
 ## Notes
 

{forest_cli-0.2.0 → forest_cli-1.0.0}/README.md

@@ -1,13 +1,13 @@
-# 🌲 forest <a href="#-dogfood-this-repo-runs-forest"><img align="right" width="42%" src="docs/assets/hero.svg" alt="Animated isometric forest: data trees on a workspace platform, packets syncing up a git branch to a remote cloud"></a>
+# 🌲 forest <a href="#-dogfood-this-repo-runs-forest"><img align="right" width="42%" src="https://tmsincomb.github.io/forest/assets/hero.svg" alt="Animated isometric forest: data trees on a workspace platform, packets syncing up a git branch to a remote cloud"></a>
 
 **git-like data management for arbitrary data trees.**
 
-[![CI](https://github.com/tmsincomb/forest/actions/workflows/ci.yml/badge.svg)](https://github.com/tmsincomb/forest/actions/workflows/ci.yml)
-[![Docs](https://github.com/tmsincomb/forest/actions/workflows/docs.yml/badge.svg)](https://github.com/tmsincomb/forest/actions/workflows/docs.yml)
-[![Release](https://github.com/tmsincomb/forest/actions/workflows/release.yml/badge.svg)](https://github.com/tmsincomb/forest/actions/workflows/release.yml)
+<!-- GitHub Actions workflow badges 404 outside the repo while it is private;
+     re-add CI/Docs/Release badges if the repo goes public. -->
+[![Site](https://img.shields.io/badge/site-tmsincomb.github.io%2Fforest-2d6a4f?logo=materialformkdocs&logoColor=white)](https://tmsincomb.github.io/forest/)
 [![PyPI](https://img.shields.io/pypi/v/forest-cli?logo=pypi&logoColor=white)](https://pypi.org/project/forest-cli/)
-[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](https://github.com/tmsincomb/forest/blob/main/LICENSE)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![mypy: strict](https://img.shields.io/badge/mypy-strict-blue)](https://mypy-lang.org/)
 
@@ -22,6 +22,13 @@ knows nothing about what the data means, and depends on no other project. It
 moves files and tracks their sync state; it does not validate or interpret their
 contents.
 
+## Documentation
+
+Full docs live at **[tmsincomb.github.io/forest](https://tmsincomb.github.io/forest/)**.
+Start with the **[hands-on tutorial](https://tmsincomb.github.io/forest/tutorial/)** —
+seven short chapters from `forest init` to a fully synced repo, with every
+output block captured from a real session and no cloud credentials required.
+
 ## Model
 
 Fixed-depth, no arbitrary nesting:
@@ -40,12 +47,13 @@ workspace → checkout → stage → unit → files
 
 ## Install
 
-Requires [`rclone`](https://rclone.org/) on `$PATH` for transfers:
-
 ```bash
-pip install -e ./forest
+pip install forest-cli
 ```
 
+Requires [`rclone`](https://rclone.org/) on `$PATH` for transfers. For a
+development install, clone the repo and `pip install -e ".[dev]"`.
+
 ## Quick start
 
 No config files are hand-written. Onboarding is a few commands:
@@ -99,13 +107,51 @@ clone bootstraps with `bind` + `remote use` + `pull`. User-local files
 | `forest remote add/remove/list/use/show` | Manage remotes; `use` selects the active remote (optional while only one remote exists). |
 | `forest push / pull / status / diff / ls` | Sync and inspect against the active remote. Bare `push`/`pull`/`status`/`diff` cover every bound stage (unbound stages warn and skip); `--all` requires all stages bound. |
 | `forest flow` | Emit a Mermaid data-flow diagram of the active checkout. |
-| `forest migrate` | Migrate a legacy `biostore` layout in place (see below). |
+| `forest tui` (or bare `forest`) | Interactive terminal forest (Textual app): each checkout is a pixel-art tree, canopy bands are stages colored by sync status, and the mist above the treetops is data in the cloud (the active remote). Navigate with keys or the mouse; Enter (or a click) on a stage opens its unit drill-down. |
+| `forest prompt init bash\|zsh` | Print an eval-able snippet that shows the active checkout in your shell prompt. |
 
 Run any command with `-C <path>` to operate on another repo without `cd`.
 
 Forest syncs **all** files in a data unit, skipping OS junk (`.DS_Store`,
 AppleDouble `._*`, `*.tmp`). It applies no content-based include/exclude rules.
 
+## Terminal output
+
+On an interactive terminal forest renders rich output — colored status
+tables, file trees, panels, and live progress bars during `push`/`pull`
+(rclone JSON stats streamed to a bar; needs rclone ≥ 1.49, older versions
+transfer fine without a bar). When stdout is piped or redirected, output
+falls back to the plain, machine-parseable format, so scripts never see
+ANSI codes or box drawing.
+
+Overrides: `--color`/`--no-color` per invocation, `FOREST_OUTPUT=rich|plain|auto`
+in the environment, and the [`NO_COLOR`](https://no-color.org)/`FORCE_COLOR`
+conventions. Precedence: flag > `FOREST_OUTPUT` > `NO_COLOR` > `FORCE_COLOR` >
+TTY detection. `--verbose` shows rclone's raw transfer log instead of a
+progress bar; `--quiet` suppresses everything but errors.
+
+## Shell prompt
+
+Show the active checkout in your prompt (bash and zsh), the way git prompts
+show the current branch:
+
+```bash
+# ~/.bashrc
+eval "$(forest prompt init bash)"
+
+# ~/.zshrc
+eval "$(forest prompt init zsh)"
+```
+
+```text
+~/lab/G004 $                # outside a workspace: unchanged
+🌲 G004 ~/lab/G004 $        # inside a workspace with an active checkout
+```
+The snippet is pure shell — it reads `.forest/HEAD` directly and never invokes
+the forest CLI while rendering, so your prompt stays fast. Set
+`FOREST_PROMPT_ICON` to replace the 🌲.
+`FOREST_PROMPT_ICON` to replace the 🌲.
+
 ## Config reference
 
 Checkout `forest.yaml` (shared, committed):
@@ -120,6 +166,8 @@ stages:
   raw:
     remote_path: demo/raw      # optional; defaults to <checkout>/<stage>
     sync_by: subdirectory      # subdirectory | directory | file
+    direction: both            # push | pull | both; bare push/pull skip
+                               # wrong-direction stages, explicit selection errors
 ```
 
 Checkout `local.yaml` (per-machine, gitignored):
@@ -150,44 +198,54 @@ guides live in `docs/runbooks/`.
 | `FOREST_BREAKER_THRESHOLD` | `5` | Consecutive transfer failures before the circuit opens; `0` disables. |
 | `FOREST_BREAKER_RESET_SECONDS` | `60` | Cool-down before an open circuit allows a probe operation. |
 | `FOREST_FLAGS` | unset | Comma-separated feature flags; `raw-logs` disables log secret-scrubbing. |
+| `FOREST_OUTPUT` | `auto` | Terminal rendering: `rich`, `plain`, or `auto` (rich on a TTY, plain when piped). |
+| `NO_COLOR` / `FORCE_COLOR` | unset | Standard color conventions; `FOREST_OUTPUT` and `--color/--no-color` take precedence. |
 
 ## Dogfood: this repo runs forest
 
-This repository manages its own `examples/` tree with forest — a live
-demonstration that `.forest/` and `.git/` coexist without overlapping. It was
-set up with exactly the quick-start commands:
+This repository manages its own `examples/` and `tests/data/` trees with
+forest — a live demonstration that `.forest/` and `.git/` coexist without
+overlapping. It was set up with exactly the quick-start commands:
 
 ```bash
 forest init
 forest checkout demo
-forest remote add origin s3://my-forest-bucket --region us-east-2
-forest add examples ./examples
-forest push
+forest remote add origin s3://forest-cli-test --region us-east-2
+forest add examples ./examples                        # two-way stage (direction: both)
+forest add data ./tests/data --sync-by directory      # two small test files
+forest push                                           # seeds both stages
 ```
 
+After the seeding push, `data` was flipped to `direction: pull` in the
+checkout's `forest.yaml` — it is a read-only reference mirror now: a bare
+`forest push` skips it with a note, and `forest push --stage data` refuses
+with exit 1 (a new stage can start there directly with
+`forest add ... --direction pull`). The `examples` stage keeps syncing both
+ways.
+
 Inspect the result:
 
 ```bash
 git ls-files .forest        # what a clone gets: config.yaml + checkouts/demo/forest.yaml
 cat .gitignore              # forest-managed: HEAD, local.yaml, sync_state.json stay local
-forest status               # sync state of the examples stage
+forest ls                   # stage overview: data shows (directory, pull)
+forest status               # sync state of both stages
 ```
 
-A fresh clone bootstraps the local half with `forest bind examples ./examples`
-followed by `forest pull` (the single configured remote is used automatically).
-Pulling needs AWS credentials for the bucket; the layout is the demonstration.
-
-## Migrating from biostore
-
-Existing biostore repos use `.biostore/` and `biostore.yaml`. Migrate in place:
+A fresh clone bootstraps the local half (HEAD, bindings, sync state are
+gitignored) with:
 
 ```bash
-forest migrate
+forest checkout demo               # select the checkout; clones have no HEAD
+forest bind examples ./examples
+forest bind data ./tests/data
+forest pull --force                # first pull: no local sync state yet, so
+                                   # forest refuses to touch the git-tracked
+                                   # copies without it
 ```
 
-This renames `.biostore/` → `.forest/`, each `biostore.yaml` → `forest.yaml`,
-rewrites the managed `.gitignore` patterns, and verifies the registry parses. It
-refuses to run if a `.forest/` already exists.
+The single configured remote is used automatically. Pulling needs AWS
+credentials for the bucket; the layout is the demonstration.
 
 ## Notes
 

{forest_cli-0.2.0 → forest_cli-1.0.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "forest-cli"
-version = "0.2.0"
+version = "1.0.0"
 description = "git-like data management for arbitrary data trees: workspaces, checkouts, remotes, and sync"
 readme = "README.md"
 license = {text = "MIT"}
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
     {name = "Troy Sincomb", email = "troysincomb@gmail.com"},
 ]
@@ -23,6 +23,11 @@ dependencies = [
     "polars>=1.0",
     "pydantic>=2.0",
     "pyyaml>=6.0",
+    # rich is a textual dependency, but forest imports it directly (Text.from_ansi).
+    "rich>=14.2",
+    # rich-click 1.9.8 is the first release compatible with the click 8.4 line.
+    "rich-click>=1.9.8",
+    "textual>=8",
 ]
 
 [project.urls]
@@ -42,6 +47,7 @@ dev = [
     "pre-commit>=4.0",
     "pylint>=3.3",
     "pytest>=7.0",
+    "pytest-asyncio>=0.24",
     "pytest-cov>=6.0",
     "pytest-randomly>=3.15",
     "pytest-rerunfailures>=15.0",
@@ -51,6 +57,13 @@ dev = [
     "vulture>=2.14",
 ]
 
+[dependency-groups]
+# Docs-site toolchain (mkdocs.yml at the repo root): uv run --group docs mkdocs serve
+docs = [
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.5,<10",
+]
+
 [project.scripts]
 forest = "forest.cli:main"
 
@@ -60,6 +73,9 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
+# pytest-asyncio runs in strict mode (the default): only tests marked
+# @pytest.mark.asyncio are collected as async (the Textual app tests).
+asyncio_default_fixture_loop_scope = "function"
 addopts = [
     "--cov=forest",
     "--cov-report=term-missing",
@@ -77,7 +93,7 @@ addopts = [
 ]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 line-length = 120
 src = ["src", "tests"]
 

{forest_cli-0.2.0 → forest_cli-1.0.0}/src/forest/checkout.py

@@ -137,14 +137,6 @@ def remote_url_has_secret_material(url: str) -> bool:
     return SECRET_REMOTE_URL_RE.search(url) is not None
 
 
-def _is_relative_to(path: Path, parent: Path) -> bool:
-    try:
-        path.relative_to(parent)
-    except ValueError:
-        return False
-    return True
-
-
 def normalize_workspace_path(path: str | Path, workspace_root: str | Path, *, cwd: str | Path | None = None) -> Path:
     """Resolve a path and store inside-workspace paths relative to the workspace root."""
     workspace_root = Path(workspace_root).resolve(strict=False)
@@ -154,7 +146,7 @@ def normalize_workspace_path(path: str | Path, workspace_root: str | Path, *, cw
         candidate = base / candidate
     candidate = candidate.resolve(strict=False)
 
-    if _is_relative_to(candidate, workspace_root):
+    if candidate.is_relative_to(workspace_root):
         return candidate.relative_to(workspace_root)
     return candidate
 
@@ -167,7 +159,7 @@ def validate_workspace_data_path(path: str | Path, workspace_root: str | Path) -
         candidate = workspace_root / candidate
     candidate = candidate.resolve(strict=False)
     forest_dir = (workspace_root / ".forest").resolve(strict=False)
-    if _is_relative_to(candidate, forest_dir):
+    if candidate.is_relative_to(forest_dir):
         raise CheckoutError("Data paths must not point inside .forest metadata.")
     return candidate
 
@@ -325,7 +317,7 @@ def read_head(workspace_root: str | Path) -> str:
     except OSError as exc:
         raise CheckoutError(f"Cannot read active checkout {path}: {exc}") from None
 
-    name = raw[:-1] if raw.endswith("\n") else raw
+    name = raw.removesuffix("\n")
     if "\n" in name:
         raise CheckoutError(f"Invalid active checkout in {path}: expected exactly one checkout name line.")
     return validate_checkout_name(name)
@@ -399,11 +391,7 @@ def create_checkout(workspace_root: str | Path, checkout_name: str) -> None:
         write_head(workspace_root, checkout_name)
         ensure_workspace_gitignore(workspace_root, checkout_name)
     except Exception:
-        if target_dir.exists():
-            if target_existed:
-                _empty_directory(target_dir)
-            else:
-                shutil.rmtree(target_dir)
+        _rollback_target_dir(target_dir, existed=target_existed)
         _restore_optional_text(config_path, config_text)
         _restore_optional_text(head_path, head_text)
         _restore_optional_text(gitignore_path, gitignore_text)
@@ -476,6 +464,15 @@ def _empty_directory(path: Path) -> None:
             child.unlink()
 
 
+def _rollback_target_dir(target_dir: Path, *, existed: bool) -> None:
+    if not target_dir.exists():
+        return
+    if existed:
+        _empty_directory(target_dir)
+    else:
+        shutil.rmtree(target_dir)
+
+
 def _git_check_ignore(workspace_root: Path, rel_path: str) -> int:
     try:
         result = subprocess.run(
@@ -508,8 +505,7 @@ def _is_inside_git_worktree(workspace_root: Path) -> bool:
 
 
 def _managed_gitignore_text(original_text: str, patterns: tuple[str, ...]) -> str:
-    lines = original_text.splitlines()
-    kept = [line for line in lines if line.strip() not in FOREST_OWNED_GITIGNORE_LINES]
+    kept = [line for line in original_text.splitlines() if line.strip() not in FOREST_OWNED_GITIGNORE_LINES]
     kept.extend(patterns)
     return "\n".join(kept).rstrip("\n") + "\n"
 
@@ -567,17 +563,6 @@ def ensure_registry_gitignore(workspace_root: str | Path) -> None:
     )
 
 
-def ensure_legacy_gitignore(project_root: str | Path) -> None:
-    """Ensure legacy local state ignores while keeping root forest.yaml trackable."""
-    project_root = Path(project_root)
-    _ensure_gitignore(
-        project_root,
-        patterns=LEGACY_GITIGNORE_PATTERNS,
-        ignored_paths=LEGACY_GITIGNORE_PATTERNS,
-        tracked_paths=("forest.yaml",),
-    )
-
-
 def _start_directory(start: str | Path) -> Path:
     start_path = Path(start).resolve(strict=False)
     return start_path.parent if start_path.is_file() else start_path
@@ -708,6 +693,8 @@ def _verify_adopted_stages(
             raise CheckoutError(f"adopt verify failed: schema changed for stage '{stage_name}'.")
         if merged_stage.sync_by != legacy_stage.sync_by:
             raise CheckoutError(f"adopt verify failed: sync_by changed for stage '{stage_name}'.")
+        if merged_stage.direction != legacy_stage.direction:
+            raise CheckoutError(f"adopt verify failed: direction changed for stage '{stage_name}'.")
         if legacy_stage.remote_path is not None and merged_stage.remote_path != legacy_stage.remote_path:
             raise CheckoutError(f"adopt verify failed: remote_path changed for stage '{stage_name}'.")
         expected_path = _effective_local_stage_path(workspace_root, legacy_stage.path)
@@ -725,12 +712,7 @@ def _restore_adopt_staging(
     gitignore_text: str | None,
     legacy_texts: dict[Path, str | None],
 ) -> None:
-    target_dir = checkout_dir(workspace_root, checkout_name)
-    if target_dir.exists():
-        if target_existed:
-            _empty_directory(target_dir)
-        else:
-            shutil.rmtree(target_dir)
+    _rollback_target_dir(checkout_dir(workspace_root, checkout_name), existed=target_existed)
     _restore_optional_text(workspace_config_path(workspace_root), workspace_config_text)
     _restore_optional_text(_workspace_dir(workspace_root) / "HEAD", head_text)
     _restore_optional_text(workspace_root / ".gitignore", gitignore_text)
@@ -769,11 +751,8 @@ def adopt_checkout(start: str | Path, checkout_name: str) -> Path:
     if not local_path.exists() or not state_path.exists():
         raise CheckoutError("incomplete legacy metadata: expected .forest/local.yaml and .forest/sync_state.json.")
 
-    try:
-        legacy_config = _load_shared_config(root_config_path)
-        legacy_local = _load_checkout_local_config(local_path)
-    except CheckoutError:
-        raise
+    legacy_config = _load_shared_config(root_config_path)
+    legacy_local = _load_checkout_local_config(local_path)
 
     _validate_legacy_adopt_inputs(legacy_config, legacy_local)