forest-cli 0.1.0__tar.gz

forest_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Troy Sincomb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forest_cli-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: forest-cli
+Version: 0.1.0
+Summary: git-like data management for arbitrary data trees: workspaces, checkouts, remotes, and sync
+Author-email: Troy Sincomb <troysincomb@gmail.com>
+License: MIT
+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
+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
+Provides-Extra: observability
+Requires-Dist: sentry-sdk>=2.0; extra == "observability"
+Provides-Extra: dev
+Requires-Dist: deptry>=0.23; extra == "dev"
+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-cov>=6.0; extra == "dev"
+Requires-Dist: pytest-randomly>=3.15; extra == "dev"
+Requires-Dist: pytest-rerunfailures>=15.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+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>
+
+**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)
+[![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)
+[![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/)
+
+Forest is the data-side parallel to git's version control. Git tracks code in
+`.git/`; forest tracks large data — local layout plus remote sync — in
+`.forest/`. It borrows git's mental model and verbs (`checkout`, `status`,
+`push`, `pull`, `remote`, a HEAD-style pointer) so your git intuition carries
+over, but the two domains never overlap and neither requires the other.
+
+Forest is **domain-agnostic and self-contained**: it manages *any* data trees,
+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.
+
+## Model
+
+Fixed-depth, no arbitrary nesting:
+
+```
+workspace → checkout → stage → unit → files
+```
+
+- **Workspace** — a per-repo `.forest/` control area (registry + active pointer).
+- **Checkout** — a named data view/focus registered in the workspace (like a git
+  branch you stay rooted in). Switching is an O(1) pointer rewrite; data never
+  moves.
+- **Stage** — a named data category inside a checkout, with a remote layout.
+- **Unit** — one addressable item within a stage (a subdirectory, a directory,
+  or a file, per the stage's `sync_by`).
+
+## Install
+
+Requires [`rclone`](https://rclone.org/) on `$PATH` for transfers:
+
+```bash
+pip install -e ./forest
+```
+
+## Quick start
+
+No config files are hand-written. Onboarding is a few commands:
+
+```bash
+forest init                      # create the nameless .forest/ workspace container
+forest checkout demo             # create if absent, register + activate 'demo'
+forest remote add origin s3://my-bucket/prefix   # allowed before any local data exists
+forest add raw ./data/raw        # register stage 'raw' and bind it to a local path
+forest push                      # sync every bound stage to the active remote
+```
+
+- `forest init` creates **only** `.forest/config.yaml` (`version: 1`,
+  `checkouts: {}`) and a managed `.gitignore`. No root config, no checkout, no
+  active pointer.
+- `forest checkout <name>` switches to the checkout, creating, registering, and
+  activating it first (with `.forest/checkouts/<name>/forest.yaml`) when the
+  name is not registered. `forest checkout create <name>` is the explicit form.
+- Remotes can be added before any local binding — useful when your data is
+  remote-only at first.
+- `forest add STAGE PATH` registers a new stage and binds it to a local path in
+  one step (use `forest bind` to rebind an existing stage).
+
+## Metadata layout
+
+Everything forest owns lives under `.forest/`; your data does not.
+
+```
+.forest/
+  config.yaml                     # workspace registry: version, checkouts{}
+  HEAD                            # active checkout name (gitignored)
+  checkouts/
+    demo/
+      forest.yaml                 # shared: stages, remotes, manifest
+      local.yaml                  # user-local: active_remote, stage_paths (gitignored)
+      sync_state.json             # user-local push/pull state (gitignored)
+```
+
+Shared metadata (`config.yaml`, each `forest.yaml`) is committed so a fresh
+clone bootstraps with `bind` + `remote use` + `pull`. User-local files
+(`HEAD`, `local.yaml`, `sync_state.json`) are gitignored.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `forest init` | Create the workspace container, or report setup status if it exists. |
+| `forest checkout create/adopt/list/current/remove <name>` | Manage checkouts; bare `forest checkout <name>` switches, creating first if needed. `remove --yes` skips the prompt for scripts. |
+| `forest add STAGE PATH [--sync-by MODE]` | Register a new stage and bind it to a local path; `--sync-by` picks unit discovery (`subdirectory`/`directory`/`file`). |
+| `forest bind [STAGE PATH]` / `forest unbind STAGE` | Manage local stage↔path bindings. |
+| `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). |
+
+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.
+
+## Config reference
+
+Checkout `forest.yaml` (shared, committed):
+
+```yaml
+project: demo
+remotes:
+  origin:
+    url: s3://my-bucket/prefix
+    region: us-east-2          # optional; also endpoint, profile, key_file, known_hosts
+stages:
+  raw:
+    remote_path: demo/raw      # optional; defaults to <checkout>/<stage>
+    sync_by: subdirectory      # subdirectory | directory | file
+```
+
+Checkout `local.yaml` (per-machine, gitignored):
+
+```yaml
+active_remote: origin
+stage_paths:
+  raw: ../data/raw             # relative resolves from the workspace root
+```
+
+## Environment variables
+
+All optional, all off by default — forest is silent and sends nothing anywhere
+unless configured. Copy `.env.example` for a commented template; operational
+guides live in `docs/runbooks/`.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `FOREST_LOG_FILE` | unset | Append structured logs (JSON lines) to this file. |
+| `FOREST_LOG_FORMAT` | `json` | `json` or `text`; set without `FOREST_LOG_FILE` to log to stderr. |
+| `FOREST_LOG_LEVEL` | `INFO` | Standard logging level name. |
+| `FOREST_METRICS_FILE` | unset | Append metric samples as JSON lines for external collectors. |
+| `FOREST_ANALYTICS_FILE` | unset | Opt-in local usage analytics (JSON lines); nothing leaves the machine. |
+| `FOREST_SENTRY_DSN` | unset | Sentry error tracking; needs `pip install "forest-cli[observability]"`. |
+| `FOREST_ALERT_WEBHOOK` | unset | POST failure alerts to this HTTPS endpoint (Slack/Mattermost compatible). |
+| `FOREST_TRANSFER_RETRIES` | `2` | Extra attempts for transient rclone failures; `0` disables. |
+| `FOREST_RETRY_BASE_DELAY` | `0.5` | Initial retry backoff in seconds; doubles per attempt. |
+| `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. |
+
+## 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:
+
+```bash
+forest init
+forest checkout demo
+forest remote add origin s3://forest-test-542222635421-us-east-2-an --region us-east-2
+forest add examples ./examples
+forest push
+```
+
+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
+```
+
+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:
+
+```bash
+forest migrate
+```
+
+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.
+
+## Notes
+
+- **Single active machine (v1).** `HEAD`/`local.yaml`/`sync_state.json` are
+  git-invisible but may be synced by a file-syncing tool; forest assumes one
+  active machine and uses atomic writes plus a per-checkout `flock` for
+  intra-machine write races.
+- **Real filenames.** Forest stores data under real paths, not a
+  content-addressed blob store.
+- See `docs/adr/` for the design decisions behind the workspace/checkout model.

forest_cli-0.1.0/README.md

@@ -0,0 +1,199 @@
+# 🌲 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>
+
+**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)
+[![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)
+[![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/)
+
+Forest is the data-side parallel to git's version control. Git tracks code in
+`.git/`; forest tracks large data — local layout plus remote sync — in
+`.forest/`. It borrows git's mental model and verbs (`checkout`, `status`,
+`push`, `pull`, `remote`, a HEAD-style pointer) so your git intuition carries
+over, but the two domains never overlap and neither requires the other.
+
+Forest is **domain-agnostic and self-contained**: it manages *any* data trees,
+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.
+
+## Model
+
+Fixed-depth, no arbitrary nesting:
+
+```
+workspace → checkout → stage → unit → files
+```
+
+- **Workspace** — a per-repo `.forest/` control area (registry + active pointer).
+- **Checkout** — a named data view/focus registered in the workspace (like a git
+  branch you stay rooted in). Switching is an O(1) pointer rewrite; data never
+  moves.
+- **Stage** — a named data category inside a checkout, with a remote layout.
+- **Unit** — one addressable item within a stage (a subdirectory, a directory,
+  or a file, per the stage's `sync_by`).
+
+## Install
+
+Requires [`rclone`](https://rclone.org/) on `$PATH` for transfers:
+
+```bash
+pip install -e ./forest
+```
+
+## Quick start
+
+No config files are hand-written. Onboarding is a few commands:
+
+```bash
+forest init                      # create the nameless .forest/ workspace container
+forest checkout demo             # create if absent, register + activate 'demo'
+forest remote add origin s3://my-bucket/prefix   # allowed before any local data exists
+forest add raw ./data/raw        # register stage 'raw' and bind it to a local path
+forest push                      # sync every bound stage to the active remote
+```
+
+- `forest init` creates **only** `.forest/config.yaml` (`version: 1`,
+  `checkouts: {}`) and a managed `.gitignore`. No root config, no checkout, no
+  active pointer.
+- `forest checkout <name>` switches to the checkout, creating, registering, and
+  activating it first (with `.forest/checkouts/<name>/forest.yaml`) when the
+  name is not registered. `forest checkout create <name>` is the explicit form.
+- Remotes can be added before any local binding — useful when your data is
+  remote-only at first.
+- `forest add STAGE PATH` registers a new stage and binds it to a local path in
+  one step (use `forest bind` to rebind an existing stage).
+
+## Metadata layout
+
+Everything forest owns lives under `.forest/`; your data does not.
+
+```
+.forest/
+  config.yaml                     # workspace registry: version, checkouts{}
+  HEAD                            # active checkout name (gitignored)
+  checkouts/
+    demo/
+      forest.yaml                 # shared: stages, remotes, manifest
+      local.yaml                  # user-local: active_remote, stage_paths (gitignored)
+      sync_state.json             # user-local push/pull state (gitignored)
+```
+
+Shared metadata (`config.yaml`, each `forest.yaml`) is committed so a fresh
+clone bootstraps with `bind` + `remote use` + `pull`. User-local files
+(`HEAD`, `local.yaml`, `sync_state.json`) are gitignored.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `forest init` | Create the workspace container, or report setup status if it exists. |
+| `forest checkout create/adopt/list/current/remove <name>` | Manage checkouts; bare `forest checkout <name>` switches, creating first if needed. `remove --yes` skips the prompt for scripts. |
+| `forest add STAGE PATH [--sync-by MODE]` | Register a new stage and bind it to a local path; `--sync-by` picks unit discovery (`subdirectory`/`directory`/`file`). |
+| `forest bind [STAGE PATH]` / `forest unbind STAGE` | Manage local stage↔path bindings. |
+| `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). |
+
+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.
+
+## Config reference
+
+Checkout `forest.yaml` (shared, committed):
+
+```yaml
+project: demo
+remotes:
+  origin:
+    url: s3://my-bucket/prefix
+    region: us-east-2          # optional; also endpoint, profile, key_file, known_hosts
+stages:
+  raw:
+    remote_path: demo/raw      # optional; defaults to <checkout>/<stage>
+    sync_by: subdirectory      # subdirectory | directory | file
+```
+
+Checkout `local.yaml` (per-machine, gitignored):
+
+```yaml
+active_remote: origin
+stage_paths:
+  raw: ../data/raw             # relative resolves from the workspace root
+```
+
+## Environment variables
+
+All optional, all off by default — forest is silent and sends nothing anywhere
+unless configured. Copy `.env.example` for a commented template; operational
+guides live in `docs/runbooks/`.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `FOREST_LOG_FILE` | unset | Append structured logs (JSON lines) to this file. |
+| `FOREST_LOG_FORMAT` | `json` | `json` or `text`; set without `FOREST_LOG_FILE` to log to stderr. |
+| `FOREST_LOG_LEVEL` | `INFO` | Standard logging level name. |
+| `FOREST_METRICS_FILE` | unset | Append metric samples as JSON lines for external collectors. |
+| `FOREST_ANALYTICS_FILE` | unset | Opt-in local usage analytics (JSON lines); nothing leaves the machine. |
+| `FOREST_SENTRY_DSN` | unset | Sentry error tracking; needs `pip install "forest-cli[observability]"`. |
+| `FOREST_ALERT_WEBHOOK` | unset | POST failure alerts to this HTTPS endpoint (Slack/Mattermost compatible). |
+| `FOREST_TRANSFER_RETRIES` | `2` | Extra attempts for transient rclone failures; `0` disables. |
+| `FOREST_RETRY_BASE_DELAY` | `0.5` | Initial retry backoff in seconds; doubles per attempt. |
+| `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. |
+
+## 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:
+
+```bash
+forest init
+forest checkout demo
+forest remote add origin s3://forest-test-542222635421-us-east-2-an --region us-east-2
+forest add examples ./examples
+forest push
+```
+
+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
+```
+
+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:
+
+```bash
+forest migrate
+```
+
+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.
+
+## Notes
+
+- **Single active machine (v1).** `HEAD`/`local.yaml`/`sync_state.json` are
+  git-invisible but may be synced by a file-syncing tool; forest assumes one
+  active machine and uses atomic writes plus a per-checkout `flock` for
+  intra-machine write races.
+- **Real filenames.** Forest stores data under real paths, not a
+  content-addressed blob store.
+- See `docs/adr/` for the design decisions behind the workspace/checkout model.

forest_cli-0.1.0/pyproject.toml

@@ -0,0 +1,122 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forest-cli"
+version = "0.1.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"
+authors = [
+    {name = "Troy Sincomb", email = "troysincomb@gmail.com"},
+]
+keywords = ["data-management", "sync", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "click>=8.0",
+    "polars>=1.0",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+# Opt-in error tracking (FOREST_SENTRY_DSN); see docs/runbooks/alerting.md.
+observability = [
+    "sentry-sdk>=2.0",
+]
+dev = [
+    "deptry>=0.23",
+    "mypy>=1.14",
+    "pre-commit>=4.0",
+    "pylint>=3.3",
+    "pytest>=7.0",
+    "pytest-cov>=6.0",
+    "pytest-randomly>=3.15",
+    "pytest-rerunfailures>=15.0",
+    "pytest-xdist>=3.6",
+    "ruff>=0.4",
+    "types-PyYAML",
+    "vulture>=2.14",
+]
+
+[project.scripts]
+forest = "forest.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
+addopts = [
+    "--cov=forest",
+    "--cov-report=term-missing",
+    "--cov-fail-under=70",
+    "--durations=15",
+    "--durations-min=0.5",
+    # Test isolation: run in parallel workers; pytest-randomly shuffles order each
+    # run so hidden inter-test dependencies surface immediately.
+    "--numprocesses=auto",
+    # Flaky-test policy: retry only transient environment errors (never assertion
+    # failures); reruns are reported in the summary so instability stays visible.
+    "--reruns=1",
+    "--reruns-delay=1",
+    "--only-rerun=(Timeout|Connection|BrokenPipe)",
+]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# N enforces pep8-naming, C90 enforces the cyclomatic complexity budget, and
+# TD/FIX police tech-debt markers: TODOs must carry an author and issue link
+# (TD002/TD003) while FIXME/XXX/HACK never land on main (FIX001/FIX003/FIX004).
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF", "C90", "TD", "FIX"]
+# FIX002 flags every TODO even when well-formed; TD rules already gate those.
+ignore = ["FIX002"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.isort]
+known-first-party = ["forest"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src/forest"]
+strict = true
+warn_unused_configs = true
+
+[tool.deptry]
+pep621_dev_dependency_groups = ["dev"]
+
+[tool.vulture]
+paths = ["src/forest"]
+min_confidence = 80
+# Pydantic validators receive `cls` per the classmethod protocol even when the
+# body never uses it.
+ignore_names = ["cls"]
+
+# Pylint is used solely as the duplicate-code (DRY) detector; ruff owns every
+# other lint concern.
+[tool.pylint.main]
+disable = ["all"]
+enable = ["duplicate-code"]
+
+[tool.pylint.similarities]
+min-similarity-lines = 5
+ignore-imports = true
+ignore-signatures = true

forest_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

forest_cli-0.1.0/src/forest/__init__.py

@@ -0,0 +1,16 @@
+"""forest — git-like data management for arbitrary data trees.
+
+Forest is a self-contained, domain-agnostic data-sync engine: workspace
+initialization, named checkouts (focus), remotes, local bindings,
+push/pull/status/ls, and sync state. It knows nothing about what the data
+means — it syncs and inspects whatever files live in a unit.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("forest")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

forest_cli-0.1.0/src/forest/analytics.py

@@ -0,0 +1,29 @@
+"""Opt-in local usage analytics for forest commands.
+
+No-op unless ``FOREST_ANALYTICS_FILE`` is set; events are appended as JSON
+lines to that local file only — nothing leaves the machine. Eager options
+(``--help``/``--version``) exit during parsing and are not recorded.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from forest import __version__
+from forest.logger import get_run_id
+from forest.metrics import append_jsonl
+
+
+def record_command(command: str, *, duration_seconds: float, status: str) -> None:
+    """Append one command-usage event. Never raises."""
+    append_jsonl(
+        "FOREST_ANALYTICS_FILE",
+        {
+            "ts": datetime.now(tz=timezone.utc).isoformat(),
+            "command": command,
+            "duration_seconds": round(duration_seconds, 3),
+            "status": status,  # "success" | "error"
+            "run_id": get_run_id(),
+            "version": __version__,
+        },
+    )