ydderd-momentum-cli 0.5.0__tar.gz

ydderd_momentum_cli-0.5.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/

ydderd_momentum_cli-0.5.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: ydderd-momentum-cli
+Version: 0.5.0
+Summary: Momentum customer CLI + experiment-logging SDK — authenticate, upload field data, and report training runs to your workspace.
+Project-URL: Homepage, https://withflywheel.com
+Project-URL: Repository, https://github.com/ydderd/flywheel
+Author: Momentum
+License: Apache-2.0
+Keywords: cli,ingest,momentum,upload
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flywheel-cli
+
+The Momentum customer CLI + experiment-logging SDK: authenticate and bulk-upload field data
+straight to your workspace's storage bucket, and report training/eval runs from your own compute
+into your workspace's experiment tracker.
+
+PyPI distribution: `ydderd-momentum-cli` · Homebrew formula: `momentum-cli` · command: `momentum`.
+(The clean `momentum-cli` PyPI name was taken, so the distribution carries the `ydderd-` prefix;
+the import package `momentum_cli`, the `momentum` command, and the brew name are unaffected.)
+
+## Why this is a separate package
+
+The CLI talks to the Momentum API purely over HTTP (and to R2 over S3). It shares **no Python
+code** with the backend, so it ships with a tiny dependency set — `httpx` + `boto3` — instead of
+the full server stack (torch, opencv, fastapi, …). That keeps the install small and avoids
+shipping the backend's AGPL detector to customers.
+
+## Install
+
+```bash
+brew install ydderd/flywheel/flywheel-cli
+# or:
+pipx install ydderd-momentum-cli
+flywheel --help
+```
+
+## Usage
+
+```bash
+momentum auth login                       # opens a browser; a workspace admin approves
+momentum auth whoami                      # confirm tenant
+momentum upload ./your-data --scan        # bulk upload + trigger ingest
+flywheel ingest status                    # ingest ledger stats
+momentum eval submit --model hf://lab/pi05-fast --benchmark bench_roboarena@3  # open an eval run, print URL
+flywheel trials log --policy hf://lab/pi05-fast --n 20 --successes 14 --calibration-set pcsk-…
+flywheel trials log --csv trials.csv      # bulk floor tallies (per-row partial success)
+flywheel secrets set lab-bucket           # store a secret (value from stdin); prints its creds_ref
+flywheel secrets list                     # secret names + configured (never values)
+```
+
+`upload` always writes to your workspace's one raw prefix — there's no target to choose. Whether
+what you uploaded is raw drone video (needs extraction) or already-extracted frames is classified
+server-side once it lands, not by the client beforehand.
+
+For headless/CI use, skip the browser with a token minted by a workspace admin:
+`momentum auth login --token <fw_cli_…>`.
+
+Config is stored at `~/.flywheel/config.json`. Auth precedence: `MOMENTUM_CLI_TOKEN` env >
+config file.
+
+## Experiment-logging SDK
+
+Training and eval runs executed on your own compute (Modal, Brev, a lab box) report themselves
+into your workspace's experiment tracker — W&B-style, and safe to leave in production training
+code (a logging failure never raises into the train):
+
+```python
+import momentum_cli as momentum
+
+run = momentum.init(name="my_sft_run", tags=["sft"], config={"iters": 800, "lr": 2e-4},
+                    provider="modal")
+run.log({"train/loss": 0.42}, step=100)
+run.finish(status="succeeded", checkpoint_ref="r2://bucket/ckpt", cost_usd=295.26)
+
+# later — scoring results and billed cost arrive after the train, so annotation
+# works on finished runs:
+momentum.annotate(run.id, results={"auroc": {"value": 0.61, "ci": [0.55, 0.67]}})
+```
+
+### Eval runs (policy context — the CI-integration path)
+
+An eval process (a lab rig, Modal, the robot) evaluates `model × benchmark@version` and streams its
+rollouts back. Same never-raise/heartbeat/reattach posture as training runs; rollouts buffer and flush
+in batches, each with a client-generated id so a re-sent batch is idempotent:
+
+```python
+ev = momentum.eval_run(benchmark="bench_roboarena@3", model="hf://lab/pi05-fast", seeds=3)
+ev.log_rollout(scenario="scn_pick", seed=0, status="success",
+               scorer={"success": True, "task_progress": 1.0}, latency_p50=61.0)
+ev.log_rollout(scenario="scn_pick", seed=1, status="fail", scorer={"success": False})
+ev.finish()                                   # flushes any buffered rollouts first
+ev.annotate(results={"headline": {"value": 0.5, "ci": [0.31, 0.69]}})   # post-hoc scoring
+```
+
+`eval_run()` prints the run URL on create; `eval_run(run_id=…)` (or `MOMENTUM_EVAL_RUN_ID`) reattaches
+after a preemption. Runs land in the UI under **Eval runs**.
+
+### Real trials (floor tallies → calibration audit)
+
+Report real-robot trials of a policy; landing trials that ground a calibration set recomputes that world
+model's τ/ρ trust:
+
+```python
+momentum.real_trials.log(policy="hf://lab/pi05-fast", scenario="scn_pick",
+                         n=20, successes=14, operator="alice", calibration_set="pcsk-…")
+
+report = momentum.real_trials.log_csv("trials.csv")   # a path or raw CSV text; per-row partial success
+print(report["accepted"], report["rejected"])
+```
+
+### Secrets & referenced episodes
+
+Register an episode that lives in your own bucket by first storing its credentials in the tenant secret
+store (Fernet-encrypted at rest; the value is never returned by a read), then passing the returned
+`creds_ref`:
+
+```python
+ref = momentum.secrets.set("lab-bucket", '{"access_key": "…", "secret_key": "…"}')  # → "secret://lab-bucket"
+momentum.episodes.register("s3://lab-corpus/session_042", creds_ref=ref)
+momentum.secrets.list()      # {name: {configured: bool}}, incl. provider keys under provider:<name>
+```
+
+Auth: `MOMENTUM_API_KEY` env (a `fw_cli_…` token — inject it as a secret in your training
+environment), falling back to the token saved by `momentum auth login`. `MOMENTUM_API_URL`
+overrides the API endpoint. `with momentum.init(...) as run:` (and `momentum.eval_run(...)`) marks the
+run failed (with the exception) if the block raises. Runs land in the workspace UI under
+**Experiments** / **Eval runs**.
+
+Release/consumption mechanics (PyPI, git-ref installs, versioning): see `PUBLISHING.md`.
+
+## Developer notes
+
+These knobs exist for Momentum developers and are intentionally hidden from customer-facing
+help and docs:
+
+- **`--api-url <url>` on `momentum auth login`** — persist a non-production API base URL to the
+  config (e.g. a local API). Hidden via `argparse.SUPPRESS`.
+- **`MOMENTUM_API_URL` env** — override the API base per-invocation. Takes precedence over the
+  config file.
+
+Precedence for the API base URL: `MOMENTUM_API_URL` env > `api_url` in config > default
+(`https://flywheeling.fly.dev/api` — swap to a custom domain once one is live).
+
+Point the CLI at a local backend during development:
+
+```bash
+MOMENTUM_API_URL=http://localhost:8000 momentum auth whoami
+# or persist it:
+momentum auth login --token <fw_cli_…> --api-url http://localhost:8000
+```
+
+### Local development
+
+```bash
+cd cli
+uv sync
+uv run flywheel --help
+uv run pytest
+```
+
+## Releasing (PyPI + Homebrew)
+
+PyPI is the source of truth; the Homebrew formula wraps the published PyPI sdist.
+
+### 1. Publish to PyPI — via GitHub Actions (Trusted Publishing, no token)
+
+The `.github/workflows/publish-cli.yml` workflow builds and publishes over OIDC. Cut a release
+by pushing a namespaced tag from the monorepo default branch:
+
+```bash
+git tag cli-v0.1.0 && git push origin cli-v0.1.0
+```
+
+The PyPI project is `ydderd-momentum-cli`, published from `ydderd/flywheel` via the `pypi`
+environment. (First publish activates the "pending" Trusted Publisher and creates the project.)
+
+### 2. Update the Homebrew tap formula
+
+After the PyPI release exists, point `release.sh` at your tap checkout — with `SKIP_PUBLISH=1`
+it skips the upload and only fetches the published sdist's `url`/`sha256`, rewrites the formula,
+and regenerates its Python `resource` blocks:
+
+```bash
+SKIP_PUBLISH=1 \
+FORMULA_PATH=/path/to/homebrew-momentum/Formula/flywheel-cli.rb \
+  cli/scripts/release.sh
+```
+
+Then commit + push the tap. Customers install with:
+
+```bash
+brew install ydderd/flywheel/flywheel-cli
+```
+
+> `release.sh` can also publish to PyPI itself (`UV_PUBLISH_TOKEN=pypi-… cli/scripts/release.sh`)
+> if you prefer a token-based local release over the GitHub Action.
+
+Bumping a release: change `version` in `pyproject.toml`, push a new `cli-v*` tag, then re-run
+step 2.
+

ydderd_momentum_cli-0.5.0/PUBLISHING.md

@@ -0,0 +1,74 @@
+# Publishing the CLI + SDK
+
+One distribution ships both surfaces: **`ydderd-momentum-cli`** on PyPI provides the `momentum`
+command (auth, upload, ingest) and the experiment-logging SDK (`import momentum_cli as momentum`).
+They share a package because they share everything that matters — token resolution, the API base,
+and the constraint that the client is pure HTTP with no backend imports (see the dependency note
+in `pyproject.toml`). The SDK landed in **0.3.0**.
+
+## Consuming without PyPI (git ref)
+
+Any environment that can reach the repo can install straight from git — this is how Sentinel
+consumes the SDK until a PyPI release with these changes exists:
+
+```bash
+# pin a sha (preferred for training images — reproducible)
+uv add "ydderd-momentum-cli @ git+https://github.com/ydderd/flywheel@<sha>#subdirectory=cli"
+
+# or with pip, e.g. inside a Modal image definition
+pip install "ydderd-momentum-cli @ git+https://github.com/ydderd/flywheel@main#subdirectory=cli"
+```
+
+Pin a sha or tag, not a branch, in anything that builds a training image: an image rebuild should
+not silently pick up a different SDK.
+
+## Publishing to PyPI
+
+The primary path is **GitHub Actions Trusted Publishing** (no token on any laptop) — see the
+"Releasing" section of `README.md` for the full detail. The short version:
+
+1. **Bump the version** in `cli/pyproject.toml` (single source of truth — the release tooling
+   greps it; keep `__init__.py.__version__` in sync by hand). Merge to the default branch.
+2. **Push the namespaced tag** from the default branch:
+
+   ```bash
+   git tag cli-v0.3.0 && git push origin cli-v0.3.0
+   ```
+
+   `.github/workflows/publish-cli.yml` builds and publishes to PyPI over OIDC.
+3. **Update the Homebrew formula** once the PyPI release exists:
+
+   ```bash
+   SKIP_PUBLISH=1 cli/scripts/release.sh          # rewrites the in-repo formula
+   # or FORMULA_PATH=/path/to/homebrew-momentum/Formula/flywheel-cli.rb for the tap checkout
+   ```
+
+4. **Verify:** `pip install "ydderd-momentum-cli==<version>"` in a scratch venv, then
+   `python -c "import momentum_cli as fw; print(fw.__version__)"` and `momentum --help`.
+
+(`UV_PUBLISH_TOKEN=... cli/scripts/release.sh` still works as a manual fallback that does
+build + publish + formula in one go, but the tag → Actions path is the normal one.)
+
+## Versioning
+
+- **Minor bump** for new SDK/CLI surface (0.2.x → 0.3.0 added the SDK).
+- **Patch bump** for fixes.
+- The SDK's wire contract is the `/cli/training-runs*` API; the server treats unknown body fields
+  as errors (pydantic), so adding SDK parameters generally means a server release first, then the
+  SDK release. Old SDKs against a newer server always work — the API only adds optional fields.
+
+## The `import flywheel` question (deferred)
+
+Instrumentation reads `import momentum_cli as momentum`. Shipping a bare top-level `momentum`
+module was deliberately skipped: the name collides with the backend's internal package (breaks any
+env that installs both, e.g. e2e), and the `momentum` name on PyPI is taken regardless. Revisit
+only if the SDK becomes a customer-facing product in its own right — the options then are a
+separate `momentum-sdk` distribution or negotiating the PyPI name, neither of which changes the
+wire contract or this package's code.
+
+## If the dependency set ever bloats
+
+The SDK itself needs only `httpx`. `boto3` is here for the CLI's upload path. If a future CLI
+feature drags in anything heavier, split the SDK out as its own minimal distribution at that
+point — not before; two packages to release and version is a real cost and the current set is two
+small deps.

ydderd_momentum_cli-0.5.0/README.md

@@ -0,0 +1,190 @@
+# flywheel-cli
+
+The Momentum customer CLI + experiment-logging SDK: authenticate and bulk-upload field data
+straight to your workspace's storage bucket, and report training/eval runs from your own compute
+into your workspace's experiment tracker.
+
+PyPI distribution: `ydderd-momentum-cli` · Homebrew formula: `momentum-cli` · command: `momentum`.
+(The clean `momentum-cli` PyPI name was taken, so the distribution carries the `ydderd-` prefix;
+the import package `momentum_cli`, the `momentum` command, and the brew name are unaffected.)
+
+## Why this is a separate package
+
+The CLI talks to the Momentum API purely over HTTP (and to R2 over S3). It shares **no Python
+code** with the backend, so it ships with a tiny dependency set — `httpx` + `boto3` — instead of
+the full server stack (torch, opencv, fastapi, …). That keeps the install small and avoids
+shipping the backend's AGPL detector to customers.
+
+## Install
+
+```bash
+brew install ydderd/flywheel/flywheel-cli
+# or:
+pipx install ydderd-momentum-cli
+flywheel --help
+```
+
+## Usage
+
+```bash
+momentum auth login                       # opens a browser; a workspace admin approves
+momentum auth whoami                      # confirm tenant
+momentum upload ./your-data --scan        # bulk upload + trigger ingest
+flywheel ingest status                    # ingest ledger stats
+momentum eval submit --model hf://lab/pi05-fast --benchmark bench_roboarena@3  # open an eval run, print URL
+flywheel trials log --policy hf://lab/pi05-fast --n 20 --successes 14 --calibration-set pcsk-…
+flywheel trials log --csv trials.csv      # bulk floor tallies (per-row partial success)
+flywheel secrets set lab-bucket           # store a secret (value from stdin); prints its creds_ref
+flywheel secrets list                     # secret names + configured (never values)
+```
+
+`upload` always writes to your workspace's one raw prefix — there's no target to choose. Whether
+what you uploaded is raw drone video (needs extraction) or already-extracted frames is classified
+server-side once it lands, not by the client beforehand.
+
+For headless/CI use, skip the browser with a token minted by a workspace admin:
+`momentum auth login --token <fw_cli_…>`.
+
+Config is stored at `~/.flywheel/config.json`. Auth precedence: `MOMENTUM_CLI_TOKEN` env >
+config file.
+
+## Experiment-logging SDK
+
+Training and eval runs executed on your own compute (Modal, Brev, a lab box) report themselves
+into your workspace's experiment tracker — W&B-style, and safe to leave in production training
+code (a logging failure never raises into the train):
+
+```python
+import momentum_cli as momentum
+
+run = momentum.init(name="my_sft_run", tags=["sft"], config={"iters": 800, "lr": 2e-4},
+                    provider="modal")
+run.log({"train/loss": 0.42}, step=100)
+run.finish(status="succeeded", checkpoint_ref="r2://bucket/ckpt", cost_usd=295.26)
+
+# later — scoring results and billed cost arrive after the train, so annotation
+# works on finished runs:
+momentum.annotate(run.id, results={"auroc": {"value": 0.61, "ci": [0.55, 0.67]}})
+```
+
+### Eval runs (policy context — the CI-integration path)
+
+An eval process (a lab rig, Modal, the robot) evaluates `model × benchmark@version` and streams its
+rollouts back. Same never-raise/heartbeat/reattach posture as training runs; rollouts buffer and flush
+in batches, each with a client-generated id so a re-sent batch is idempotent:
+
+```python
+ev = momentum.eval_run(benchmark="bench_roboarena@3", model="hf://lab/pi05-fast", seeds=3)
+ev.log_rollout(scenario="scn_pick", seed=0, status="success",
+               scorer={"success": True, "task_progress": 1.0}, latency_p50=61.0)
+ev.log_rollout(scenario="scn_pick", seed=1, status="fail", scorer={"success": False})
+ev.finish()                                   # flushes any buffered rollouts first
+ev.annotate(results={"headline": {"value": 0.5, "ci": [0.31, 0.69]}})   # post-hoc scoring
+```
+
+`eval_run()` prints the run URL on create; `eval_run(run_id=…)` (or `MOMENTUM_EVAL_RUN_ID`) reattaches
+after a preemption. Runs land in the UI under **Eval runs**.
+
+### Real trials (floor tallies → calibration audit)
+
+Report real-robot trials of a policy; landing trials that ground a calibration set recomputes that world
+model's τ/ρ trust:
+
+```python
+momentum.real_trials.log(policy="hf://lab/pi05-fast", scenario="scn_pick",
+                         n=20, successes=14, operator="alice", calibration_set="pcsk-…")
+
+report = momentum.real_trials.log_csv("trials.csv")   # a path or raw CSV text; per-row partial success
+print(report["accepted"], report["rejected"])
+```
+
+### Secrets & referenced episodes
+
+Register an episode that lives in your own bucket by first storing its credentials in the tenant secret
+store (Fernet-encrypted at rest; the value is never returned by a read), then passing the returned
+`creds_ref`:
+
+```python
+ref = momentum.secrets.set("lab-bucket", '{"access_key": "…", "secret_key": "…"}')  # → "secret://lab-bucket"
+momentum.episodes.register("s3://lab-corpus/session_042", creds_ref=ref)
+momentum.secrets.list()      # {name: {configured: bool}}, incl. provider keys under provider:<name>
+```
+
+Auth: `MOMENTUM_API_KEY` env (a `fw_cli_…` token — inject it as a secret in your training
+environment), falling back to the token saved by `momentum auth login`. `MOMENTUM_API_URL`
+overrides the API endpoint. `with momentum.init(...) as run:` (and `momentum.eval_run(...)`) marks the
+run failed (with the exception) if the block raises. Runs land in the workspace UI under
+**Experiments** / **Eval runs**.
+
+Release/consumption mechanics (PyPI, git-ref installs, versioning): see `PUBLISHING.md`.
+
+## Developer notes
+
+These knobs exist for Momentum developers and are intentionally hidden from customer-facing
+help and docs:
+
+- **`--api-url <url>` on `momentum auth login`** — persist a non-production API base URL to the
+  config (e.g. a local API). Hidden via `argparse.SUPPRESS`.
+- **`MOMENTUM_API_URL` env** — override the API base per-invocation. Takes precedence over the
+  config file.
+
+Precedence for the API base URL: `MOMENTUM_API_URL` env > `api_url` in config > default
+(`https://flywheeling.fly.dev/api` — swap to a custom domain once one is live).
+
+Point the CLI at a local backend during development:
+
+```bash
+MOMENTUM_API_URL=http://localhost:8000 momentum auth whoami
+# or persist it:
+momentum auth login --token <fw_cli_…> --api-url http://localhost:8000
+```
+
+### Local development
+
+```bash
+cd cli
+uv sync
+uv run flywheel --help
+uv run pytest
+```
+
+## Releasing (PyPI + Homebrew)
+
+PyPI is the source of truth; the Homebrew formula wraps the published PyPI sdist.
+
+### 1. Publish to PyPI — via GitHub Actions (Trusted Publishing, no token)
+
+The `.github/workflows/publish-cli.yml` workflow builds and publishes over OIDC. Cut a release
+by pushing a namespaced tag from the monorepo default branch:
+
+```bash
+git tag cli-v0.1.0 && git push origin cli-v0.1.0
+```
+
+The PyPI project is `ydderd-momentum-cli`, published from `ydderd/flywheel` via the `pypi`
+environment. (First publish activates the "pending" Trusted Publisher and creates the project.)
+
+### 2. Update the Homebrew tap formula
+
+After the PyPI release exists, point `release.sh` at your tap checkout — with `SKIP_PUBLISH=1`
+it skips the upload and only fetches the published sdist's `url`/`sha256`, rewrites the formula,
+and regenerates its Python `resource` blocks:
+
+```bash
+SKIP_PUBLISH=1 \
+FORMULA_PATH=/path/to/homebrew-momentum/Formula/flywheel-cli.rb \
+  cli/scripts/release.sh
+```
+
+Then commit + push the tap. Customers install with:
+
+```bash
+brew install ydderd/flywheel/flywheel-cli
+```
+
+> `release.sh` can also publish to PyPI itself (`UV_PUBLISH_TOKEN=pypi-… cli/scripts/release.sh`)
+> if you prefer a token-based local release over the GitHub Action.
+
+Bumping a release: change `version` in `pyproject.toml`, push a new `cli-v*` tag, then re-run
+step 2.
+

ydderd_momentum_cli-0.5.0/packaging/homebrew/momentum-cli.rb

@@ -0,0 +1,36 @@
+# Homebrew formula for flywheel-cli.
+#
+# This is the starter formula. It belongs in a *tap* repo — create
+# github.com/ydderd/homebrew-momentum and place this file at Formula/flywheel-cli.rb.
+# Customers then install with:
+#
+#     brew install ydderd/flywheel/flywheel-cli
+#
+# The `url`/`sha256` below are filled in by cli/scripts/release.sh after publishing to PyPI,
+# and the `resource` blocks (httpx, boto3, and their transitive deps) are generated by:
+#
+#     brew update-python-resources Formula/flywheel-cli.rb
+#
+class MomentumCli < Formula
+  include Language::Python::Virtualenv
+
+  desc "Authenticate and bulk-upload field data to your Momentum workspace"
+  homepage "https://withflywheel.com"
+  # release.sh replaces the two PLACEHOLDER lines with the PyPI sdist URL + sha256.
+  url "PLACEHOLDER_SDIST_URL"
+  sha256 "PLACEHOLDER_SHA256"
+  license "Apache-2.0"
+
+  depends_on "python@3.12"
+
+  # BEGIN RESOURCES — populated by `brew update-python-resources`. Do not edit by hand.
+  # END RESOURCES
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  test do
+    assert_match "usage: momentum", shell_output("#{bin}/flywheel --help")
+  end
+end

ydderd_momentum_cli-0.5.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+# PyPI distribution name (`momentum-cli` was taken). The import package stays `momentum_cli`
+# and the installed command stays `momentum`; the Homebrew formula keeps the clean name too.
+name = "ydderd-momentum-cli"
+version = "0.5.0"
+description = "Momentum customer CLI + experiment-logging SDK — authenticate, upload field data, and report training runs to your workspace."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Momentum" }]
+keywords = ["momentum", "cli", "upload", "ingest"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+# The CLI talks to the Momentum API purely over HTTP + S3 — it shares no code with the
+# backend, so it ships with a tiny dependency set (no torch/opencv/fastapi).
+dependencies = [
+    "httpx>=0.27",
+    "boto3>=1.34",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://withflywheel.com"
+Repository = "https://github.com/ydderd/flywheel"
+
+# Package is `momentum-cli` (brew/pypi name); the command is `momentum`.
+[project.scripts]
+momentum = "momentum_cli.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/momentum_cli"]

ydderd_momentum_cli-0.5.0/scripts/release.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# Release momentum-cli: build → publish to PyPI → update the Homebrew formula.
+#
+# Prerequisites:
+#   - uv installed
+#   - PyPI auth: UV_PUBLISH_TOKEN env (a pypi- API token) or ~/.pypirc
+#   - (optional) Homebrew, to auto-generate the formula's Python resource blocks
+#
+# Usage:
+#   cli/scripts/release.sh                # build, publish, update in-repo formula
+#   SKIP_PUBLISH=1 cli/scripts/release.sh # dry-run: build + compute hash from local sdist only
+#   FORMULA_PATH=/path/to/homebrew-momentum/Formula/momentum-cli.rb cli/scripts/release.sh
+#
+set -euo pipefail
+
+CLI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$CLI_DIR"
+
+PKG="ydderd-momentum-cli"          # PyPI distribution name
+DIST_NAME="ydderd_momentum_cli"    # build artifact stem (PEP 503 normalized: - and . → _)
+FORMULA_PATH="${FORMULA_PATH:-$CLI_DIR/packaging/homebrew/momentum-cli.rb}"
+# Grep the version (avoids a hard dependency on Python 3.11+ tomllib for this one field).
+VERSION="$(sed -n 's/^version *= *"\(.*\)".*/\1/p' pyproject.toml | head -1)"
+[ -n "$VERSION" ] || { echo "error: could not parse version from pyproject.toml" >&2; exit 1; }
+
+echo "==> Releasing $PKG $VERSION"
+
+echo "==> Building sdist + wheel"
+rm -rf dist
+uv build
+
+SDIST="dist/${DIST_NAME}-${VERSION}.tar.gz"
+[ -f "$SDIST" ] || { echo "error: expected $SDIST after build" >&2; exit 1; }
+LOCAL_SHA="$(shasum -a 256 "$SDIST" | awk '{print $1}')"
+echo "    sdist sha256: $LOCAL_SHA"
+
+if [ "${SKIP_PUBLISH:-0}" = "1" ]; then
+  echo "==> SKIP_PUBLISH=1 — not uploading to PyPI"
+  # Fall back to a canonical (non-hashed) PyPI URL so the formula is still updatable in a dry run.
+  SDIST_URL="https://files.pythonhosted.org/packages/source/${PKG:0:1}/${PKG}/${DIST_NAME}-${VERSION}.tar.gz"
+  SHA256="$LOCAL_SHA"
+else
+  echo "==> Publishing to PyPI"
+  uv publish
+
+  echo "==> Waiting for PyPI to register $PKG $VERSION"
+  for _ in $(seq 1 30); do
+    META="$(curl -fsSL "https://pypi.org/pypi/${PKG}/${VERSION}/json" 2>/dev/null || true)"
+    [ -n "$META" ] && break
+    sleep 5
+  done
+  [ -n "$META" ] || { echo "error: $PKG $VERSION did not appear on PyPI" >&2; exit 1; }
+
+  read -r SDIST_URL SHA256 <<EOF
+$(printf '%s' "$META" | python3 -c "import sys,json; d=json.load(sys.stdin); s=next(u for u in d['urls'] if u['packagetype']=='sdist'); print(s['url'], s['digests']['sha256'])")
+EOF
+  if [ "$SHA256" != "$LOCAL_SHA" ]; then
+    echo "warning: PyPI sdist sha256 ($SHA256) != local build ($LOCAL_SHA)" >&2
+  fi
+fi
+
+echo "==> Updating formula: $FORMULA_PATH"
+[ -f "$FORMULA_PATH" ] || { echo "error: formula not found at $FORMULA_PATH" >&2; exit 1; }
+# Replace the url + sha256 lines (works for both PLACEHOLDER and a prior release's values).
+python3 - "$FORMULA_PATH" "$SDIST_URL" "$SHA256" <<'PY'
+import re, sys
+path, url, sha = sys.argv[1:4]
+text = open(path).read()
+text = re.sub(r'^(\s*url\s+").*(")\s*$', rf'\g<1>{url}\g<2>', text, count=1, flags=re.M)
+text = re.sub(r'^(\s*sha256\s+").*(")\s*$', rf'\g<1>{sha}\g<2>', text, count=1, flags=re.M)
+open(path, 'w').write(text)
+PY
+
+if command -v brew >/dev/null 2>&1; then
+  echo "==> Regenerating Python resource blocks (brew update-python-resources)"
+  brew update-python-resources "$FORMULA_PATH" || \
+    echo "note: update-python-resources failed — run it manually in your tap checkout"
+else
+  echo "note: Homebrew not found — run 'brew update-python-resources $FORMULA_PATH' in your tap"
+fi
+
+echo "==> Done. Commit the updated formula to your tap (github.com/ydderd/homebrew-momentum)."
+echo "    Customers install with: brew install ydderd/momentum/${PKG}"