tan-cli 0.7.0__tar.gz

tan_cli-0.7.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: tan-cli
+Version: 0.7.0
+Summary: The Alp Lab build CLI: one board.yaml to firmware, across MCU and MPU cores.
+Author: Alp Lab AB
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/alplabai/tan-cli
+Project-URL: Repository, https://github.com/alplabai/tan-cli
+Project-URL: Issues, https://github.com/alplabai/tan-cli/issues
+Keywords: embedded,firmware,zephyr,yocto,som,build
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer<0.28,>=0.26
+Requires-Dist: rich>=13
+Requires-Dist: pyyaml>=6
+Requires-Dist: jsonschema>=4.18
+Requires-Dist: click>=8.1
+Requires-Dist: truststore>=0.9
+Requires-Dist: certifi>=2024.2.2
+Requires-Dist: cbor2>=5.0
+Provides-Extra: monitor
+Requires-Dist: pyserial>=3.5; extra == "monitor"
+Provides-Extra: model-io
+Requires-Dist: tflite>=2.10; extra == "model-io"
+Requires-Dist: flatbuffers>=23.1.21; extra == "model-io"
+Provides-Extra: model-compile
+Requires-Dist: ethos-u-vela>=3.9; extra == "model-compile"
+Requires-Dist: tflite>=2.10; extra == "model-compile"
+Requires-Dist: flatbuffers>=23.1.21; extra == "model-compile"
+Provides-Extra: model
+Requires-Dist: onnxruntime>=1.30.0; extra == "model"
+Requires-Dist: onnx>=1.16.0; extra == "model"
+Requires-Dist: numpy>=1.26; extra == "model"
+Requires-Dist: sympy>=1.12; extra == "model"
+
+# tan
+
+The Alp Lab build CLI. One `board.yaml` describes a whole module — every core,
+MCU and MPU alike — and `tan` turns it into firmware.
+
+## Install
+
+Install from a checkout. `tan` is **not on PyPI yet** — the distribution has
+never been published, so a `pip install` of it answers `ERROR: No matching
+distribution found`. The decision to publish there HAS now been taken
+(tan-cli#1054: PyPI is the sole standalone install channel, and the npm shim is
+retired), and `.github/workflows/release.yml` carries a `publish_pypi` job — but
+it is opt-in and off, waiting on the repository variable `TAN_PYPI_PUBLISH` and
+a pending publisher configured on pypi.org. Until the first final tag uploads
+under that arrangement, a checkout install is the only path.
+
+On a PEP 668 host (Debian/Ubuntu, including stock `ubuntu:24.04`), installing
+straight into the system interpreter refuses with
+`error: externally-managed-environment`; install into a virtual environment
+instead. Debian/Ubuntu's `python3` package does not include `venv` either --
+`sudo apt-get install -y python3-venv` first, on those hosts:
+
+```bash
+git clone https://github.com/alplabai/tan-cli && cd tan-cli
+python3 -m venv .venv && source .venv/bin/activate   # Linux / macOS
+py -m venv .venv && .venv\Scripts\Activate.ps1        # Windows
+python3 -m pip install ./python     # Linux / macOS
+py -m pip install ./python          # Windows
+```
+
+```bash
+tan --version
+tan init            # scaffold a project (add --preview to see the plan first)
+tan doctor          # is this host able to build and flash?
+tan build           # build every core the module declares
+```
+
+Add the `monitor` extra — `pip install "./python[monitor]"` — if you want `tan
+monitor`; it needs pyserial, which a default install leaves out.
+
+**Use `-m pip`, not a bare `pip` or `pip3`.** `tan` requires Python **3.12 or
+newer**, and on a machine with several interpreters a bare `pip` can install into
+a different one than the `python3` you will actually build with — on Windows,
+`python3` is frequently the Microsoft Store stub rather than a real interpreter.
+`python3 -m pip` cannot drift from the interpreter that runs it, so the
+`requires-python = ">=3.12"` check either passes honestly or refuses that
+interpreter, instead of installing somewhere you will not find it. (An old
+`setuptools` on the wrong interpreter can fail earlier and for a different
+reason — `project.license` must be valid exactly by one definition, measured
+here on setuptools 68-era metadata handling; that is tan-cli#382, not a version
+mismatch.)
+
+**Not building from source?** Every version tag publishes a prebuilt archive per
+platform, and `install.sh` / `install.ps1` fetch and verify one for you — see
+the root [`README.md`](../README.md#install). That is the supported path for
+someone who just wants the command.
+
+`tan init` needs no alp-sdk checkout: the scaffold templates ship inside `tan`.
+Most planning/build commands do need a checkout for metadata, schemas, examples,
+and tooling; pass it with `--sdk-root` or place it beside the project.
+
+The distribution is not named `tan` because that name is already taken on PyPI
+(an unrelated code formatter); the command you run is still `tan`. Reserving a
+name is not the same as occupying it — nothing is uploaded yet under any of
+them.
+
+## What it does
+
+`tan` contains both the relocated planner and the executor. It produces a build
+plan from your `board.yaml` plus alp-sdk metadata, then drives the right tool for
+each core — `west` for Zephyr on Cortex-M, `bitbake` for Yocto on Cortex-A,
+`cmake` for bare metal. You never pick an OS or a toolchain; both are derived
+from each core's architecture.
+
+## Requirements
+
+Python 3.12 or newer — the floor Zephyr's own CMake configure enforces. Run
+`tan doctor` to check the rest of the host; it names what is missing and where
+to get it.
+
+## Licence
+
+Apache-2.0.

tan_cli-0.7.0/README.md

@@ -0,0 +1,83 @@
+# tan
+
+The Alp Lab build CLI. One `board.yaml` describes a whole module — every core,
+MCU and MPU alike — and `tan` turns it into firmware.
+
+## Install
+
+Install from a checkout. `tan` is **not on PyPI yet** — the distribution has
+never been published, so a `pip install` of it answers `ERROR: No matching
+distribution found`. The decision to publish there HAS now been taken
+(tan-cli#1054: PyPI is the sole standalone install channel, and the npm shim is
+retired), and `.github/workflows/release.yml` carries a `publish_pypi` job — but
+it is opt-in and off, waiting on the repository variable `TAN_PYPI_PUBLISH` and
+a pending publisher configured on pypi.org. Until the first final tag uploads
+under that arrangement, a checkout install is the only path.
+
+On a PEP 668 host (Debian/Ubuntu, including stock `ubuntu:24.04`), installing
+straight into the system interpreter refuses with
+`error: externally-managed-environment`; install into a virtual environment
+instead. Debian/Ubuntu's `python3` package does not include `venv` either --
+`sudo apt-get install -y python3-venv` first, on those hosts:
+
+```bash
+git clone https://github.com/alplabai/tan-cli && cd tan-cli
+python3 -m venv .venv && source .venv/bin/activate   # Linux / macOS
+py -m venv .venv && .venv\Scripts\Activate.ps1        # Windows
+python3 -m pip install ./python     # Linux / macOS
+py -m pip install ./python          # Windows
+```
+
+```bash
+tan --version
+tan init            # scaffold a project (add --preview to see the plan first)
+tan doctor          # is this host able to build and flash?
+tan build           # build every core the module declares
+```
+
+Add the `monitor` extra — `pip install "./python[monitor]"` — if you want `tan
+monitor`; it needs pyserial, which a default install leaves out.
+
+**Use `-m pip`, not a bare `pip` or `pip3`.** `tan` requires Python **3.12 or
+newer**, and on a machine with several interpreters a bare `pip` can install into
+a different one than the `python3` you will actually build with — on Windows,
+`python3` is frequently the Microsoft Store stub rather than a real interpreter.
+`python3 -m pip` cannot drift from the interpreter that runs it, so the
+`requires-python = ">=3.12"` check either passes honestly or refuses that
+interpreter, instead of installing somewhere you will not find it. (An old
+`setuptools` on the wrong interpreter can fail earlier and for a different
+reason — `project.license` must be valid exactly by one definition, measured
+here on setuptools 68-era metadata handling; that is tan-cli#382, not a version
+mismatch.)
+
+**Not building from source?** Every version tag publishes a prebuilt archive per
+platform, and `install.sh` / `install.ps1` fetch and verify one for you — see
+the root [`README.md`](../README.md#install). That is the supported path for
+someone who just wants the command.
+
+`tan init` needs no alp-sdk checkout: the scaffold templates ship inside `tan`.
+Most planning/build commands do need a checkout for metadata, schemas, examples,
+and tooling; pass it with `--sdk-root` or place it beside the project.
+
+The distribution is not named `tan` because that name is already taken on PyPI
+(an unrelated code formatter); the command you run is still `tan`. Reserving a
+name is not the same as occupying it — nothing is uploaded yet under any of
+them.
+
+## What it does
+
+`tan` contains both the relocated planner and the executor. It produces a build
+plan from your `board.yaml` plus alp-sdk metadata, then drives the right tool for
+each core — `west` for Zephyr on Cortex-M, `bitbake` for Yocto on Cortex-A,
+`cmake` for bare metal. You never pick an OS or a toolchain; both are derived
+from each core's architecture.
+
+## Requirements
+
+Python 3.12 or newer — the floor Zephyr's own CMake configure enforces. Run
+`tan doctor` to check the rest of the host; it names what is missing and where
+to get it.
+
+## Licence
+
+Apache-2.0.

tan_cli-0.7.0/pyproject.toml

@@ -0,0 +1,293 @@
+[project]
+# DISTRIBUTION name is `tan-cli`, not `tan`: the name `tan` is already taken on
+# PyPI ("The compromising code formatter", v23.7.0), so `pip install tan` would
+# fetch an unrelated package. The IMPORT package stays `tan` and the console
+# script stays `tan`, so a customer still types `tan build` -- only the install
+# line differs:
+#
+#     pip install tan-cli   ->   tan --version
+#
+# `alp-tan` was the first choice and was also free, preferred at the time
+# because the other Alp Lab artefacts are `alp-`prefixed. Reversed in
+# tan-cli#1054, before anything was ever uploaded under either name: this
+# distribution is published from `github.com/alplabai/tan-cli` and
+# authenticated by Trusted Publishing, which binds the PyPI project to that
+# exact repository. `pypi.org/project/tan-cli` <-> `github.com/alplabai/tan-cli`
+# is one name a reader can follow; `alp-tan` <-> `tan-cli` is two.
+name = "tan-cli"
+# The PEP 440 RENDERING of `python/tan/version.py`'s TAN_VERSION, which is the
+# source of truth -- never edited alone. `0.5.0-rc5.dev0` -> `0.5.0rc5.dev0`
+# (the two spellings are not interchangeable and cannot be string-compared);
+# `python/scripts/version_check.py` owns that mapping and CI runs it.
+version = "0.7.0"
+description = "The Alp Lab build CLI: one board.yaml to firmware, across MCU and MPU cores."
+readme = "README.md"
+# PEP 639 SPDX-expression form, NOT the `{ text = ... }` table -- and it is
+# COUPLED to the `setuptools>=77.0.1` floor in `[build-system]` below, which
+# exists solely to parse this line (tan-cli#382). Changing either without the
+# other is the bug: the table form is what setuptools <77 accepts and what
+# setuptools >=77 deprecates, so there is no spelling that satisfies both.
+license = "Apache-2.0"
+authors = [{ name = "Alp Lab AB" }]
+keywords = ["embedded", "firmware", "zephyr", "yocto", "som", "build"]
+# 3.12, not 3.11: the floor is what the BUILD needs, not what this package's own
+# syntax needs. Zephyr's `cmake/modules/python.cmake` sets
+# `PYTHON_MINIMUM_REQUIRED 3.12`, and `tan build` bakes the interpreter it
+# resolves into every Zephyr slice as `-DPython3_EXECUTABLE` -- so a `tan` frozen
+# against 3.11 hands Zephyr an interpreter its own configure step then rejects,
+# and the customer gets an error naming Zephyr rather than tan. Same effective
+# floor `tan doctor` enforces (`ZEPHYR_PYTHON_FLOOR`, tan/commands/doctor_cmd.py).
+requires-python = ">=3.12"
+# `pyyaml` is load-bearing, not optional: `build/system-manifest.yaml` is the ONLY
+# input `tan image` and `tan size` have, and it is YAML. Without it declared here
+# the PyInstaller build -- which installs exactly this set into a clean venv, see
+# scripts/build_binary.sh -- ships a frozen `tan` whose `size`/`image` can never
+# read a manifest. Both still degrade to a coded `*.manifest-invalid` envelope
+# rather than a traceback if it is somehow absent (`tan.core.system_manifest.
+# load_yaml_document`), but that is a safety net, not the plan. It is now doubly
+# load-bearing: the relocated planner (`tan.planner`) reads every `metadata/**`
+# YAML through it.
+#
+# `jsonschema` arrived WITH the planner and is the fourth runtime dependency.
+# The four-name ceiling (typer, rich, pytest, pyinstaller) was scoped to the
+# executor stage; the planner validates every `board.yaml` against
+# `metadata/schemas/board.schema.json` under Draft 2020-12 before it plans
+# anything (`tan/planner/loader.py`), and that schema is where invariants I-02
+# (no top-level `os:`) and I-03 (`core_entry` is closed) are actually ENFORCED.
+# Reimplementing the validator to save a dependency would move two enforced
+# invariants into hand-written code -- the opposite of consume-what-exists. The
+# planner `sys.exit`s with an install hint if it is absent and `tan build` turns
+# that into a coded `build.plan-unavailable` envelope, never a traceback.
+#
+# `click` is the fifth, and it is declared because `tan/cli.py` and
+# `tan/commands/new_som_cmd.py` IMPORT IT DIRECTLY -- `from click.testing
+# import CliRunner` is how `--help` under `--format json` is captured into one
+# envelope instead of Click printing straight to stdout and calling
+# `ctx.exit(0)` before `emit()` can run (`_emit_help_envelope`). It rode along
+# transitively for years because typer depended on click; starting at **typer
+# 0.26.0** it does not (measured: PyPI `requires_dist` for 0.25.1 still lists
+# `click>=8.2.1`; 0.26.0's does not, and its wheel gained a vendored
+# `typer/_click/` package -- typer's OWN click-alike, not a re-export of the
+# public one). So a clean `pip install tan-cli` produced `ModuleNotFoundError:
+# No module named 'click'` on first run, and every local test suite passed
+# regardless because click was present for other reasons. A package that
+# imports a module must declare it; leaning on someone else's dependency graph
+# is what broke. `tests/gates/test_declared_dependencies.py` fails if any
+# module under `tan/` imports a distribution this list omits. `click` stays
+# required even though typer no longer needs it transitively -- the two direct
+# imports above are real, not incidental.
+#
+# `typer` is capped, not just floored, and the cap is the point of this whole
+# comment. `tan/cli.py:_emit_help_envelope` drives `typer.main.get_command()`'s
+# result -- a `TyperCommand` -- through the PUBLIC `click.testing.CliRunner`.
+# Measured: `type(get_command(app)).__mro__` descends from
+# `typer._click.core.Command`, typer's PRIVATE vendored fork, not from
+# `click.core.Command` -- so this mixes two different click implementations,
+# and it only works because the vendored `UsageError.show()` still exits via
+# `SystemExit`, which `CliRunner` catches generically (see the docstring at
+# that function). That is stable across the vendored-click line -- measured
+# clean (`tests/test_cli_skeleton.py` + `tests/gates`) against both 0.26.0 and
+# 0.27.0, the only two releases of that line so far -- but it is an
+# implementation detail of typer's private fork, not a contract, so nothing
+# says a `0.28` won't change what `get_command()` returns or how its group
+# raises. Uncapped, a resolver is free to pick that day's newest typer for a
+# `pip install ./python` -- the documented path on win32/arm64 and
+# linux/arm64, the two hosts with no frozen asset -- and hand it a CLI built
+# against a private surface that may no longer exist.
+#
+# The floor moved off `>=0.12` for the same "measure, don't guess" reason:
+# `typer==0.12.0` on PyPI is a metapackage stub (`requires_dist` is just
+# `typer-slim[standard]==0.12.0` + `typer-cli==0.12.0`), not a working install
+# of the real `typer` module -- a floor including it was already claiming
+# support that cannot work. `>=0.26` also makes the floor mean something: every
+# version it admits is the SAME vendored-click behaviour this whole comment
+# and `tests/gates/test_typer_click_bound.py` are about, not two different
+# regimes (pre- and post-vendoring) blurred into one range. Pre-0.26 typer may
+# well still work -- it was not the question this port needed answered.
+#
+# `tests/gates/test_typer_click_bound.py` fails if the installed typer drifts
+# outside `<0.28`, or if the private surface this range assumes (`TyperCommand`
+# descending from `typer._click.core.Command`, and a `SystemExit`-raising
+# `UsageError`) goes away from an in-range version -- so a version bump here is
+# a decision, not a drift.
+#
+# `truststore` and `certifi` are REQUIRED, not optional, and both are new
+# (tan-cli#304): a PyInstaller `--onefile` freeze bundles its own `ssl` but no
+# CA bundle and does not fall back to the platform trust store, so a frozen
+# `tan` had ZERO trust anchors -- every `urllib` HTTPS call in `sdk_cmd.py`
+# failed `CERTIFICATE_VERIFY_FAILED` even on a host where `curl`/a browser/
+# system `python3` verified the same endpoint fine. `truststore` is preferred
+# (verifies through the OS's own trust store, so a real corporate CA installed
+# in the machine's keychain still works -- `certifi`'s fixed public-CA list
+# alone would trade that failure for a different one); `certifi`'s bundled
+# `cacert.pem` is the floor `tan/net.py` falls back to if `truststore` is
+# absent or its platform verifier fails. Both are module-scope imports inside
+# `tan/net.py`, so both must be REQUIRED per the reasoning right below this
+# comment.
+# `cbor2` arrived WITH the relocated model engine (ADR-0028 Task 2,
+# `tan/model/manifest.py`): `.alpmodel` is a CBOR container, and
+# `Manifest.to_cbor`/`from_cbor` do a module-scope `import cbor2 as _cbor2` --
+# not lazy, not guarded -- so it is REQUIRED, matching alp-sdk's own
+# classification of the same distribution in its own `pyproject.toml`
+# (`cbor2>=5.0`, alongside PyYAML/jsonschema/click, never under
+# `optional-dependencies`). `tests/gates/test_declared_dependencies.py` fails on
+# this exact shape otherwise -- an eager import of an undeclared distribution.
+dependencies = [
+  "typer>=0.26,<0.28",
+  "rich>=13",
+  "pyyaml>=6",
+  "jsonschema>=4.18",
+  "click>=8.1",
+  "truststore>=0.9",
+  "certifi>=2024.2.2",
+  "cbor2>=5.0",
+]
+
+# `pyserial` is OPTIONAL, not required: only `tan monitor` needs it, and a serial
+# console is not worth adding to every install of a build tool. `monitor_cmd`
+# imports it lazily inside the two functions that use it and refuses with an
+# actionable message when it is absent, so `tan --version` and every other
+# command still work without it. That laziness is load-bearing, not incidental --
+# a module-scope `import serial` would make the whole CLI unimportable on a clean
+# install the moment `monitor` is registered, so
+# `tests/gates/test_declared_dependencies.py` fails if an extras-only import
+# migrates to module scope.
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Embedded Systems",
+]
+
+
+# LAST of the `[project]` content on purpose. A table header ends the parent
+# table, so every bare `key = ...` after it belongs to the SUB-table, not to
+# `[project]`. Putting this above `classifiers` silently reparented it into the
+# extras group -- `optional-dependencies` grew a bogus `classifiers` extra,
+# `project.classifiers` vanished from the metadata, and `pip install ./python`
+# failed outright. Keep new `[project]` KEYS above this line and new
+# `[project.*]` TABLES below it.
+[project.optional-dependencies]
+monitor = ["pyserial>=3.5"]
+# Lightweight TFLite read/parse deps for `tan.model.tensorio.extract_io` (tensor
+# I/O extraction from a .tflite flatbuffer) -- pure-Python, no compiler toolchain.
+# `tflite` is a genuinely LAZY, guarded import (`tensorio.py`'s
+# `try: import tflite / except ImportError: return [], []`), so it stays an
+# extra rather than a required dependency -- `extract_io` degrades to "no I/O
+# metadata" rather than failing when it is absent. `flatbuffers` is not imported
+# by name anywhere under `tan/` (so `test_declared_dependencies.py` does not
+# require it), but it is `tflite`'s own declared runtime dependency (measured:
+# `pip show tflite` -> `Requires: flatbuffers, numpy`) -- pinned explicitly here,
+# not left to a transitive resolve, so `pip install tan-cli[model-io]` is a
+# working reader and not just a gate-satisfying stub. Pins mirror alp-sdk's own
+# `model-io` extra exactly (its `pyproject.toml`'s entry, due to be dropped once
+# `scripts/alp_model/` is deleted -- ADR-0028 Task 6) rather than inventing new
+# floors.
+model-io = ["tflite>=2.10", "flatbuffers>=23.1.21"]
+
+# Full host model-compile toolchain: adds the Arm Vela compiler `vela` needs
+# for `tan.model.adapters.ethos_u.VelaAdapter.compile()` (`shutil.which("vela")`
+# is the runtime gate; this extra is what puts it on PATH). NOT required for
+# `tan model build` to run -- every vendor adapter shells its compiler as an
+# external binary, never a Python import, so a bare `pip install tan-cli`
+# still works and only that one NPU backend's compile step is unavailable
+# (`is_available()` reports False; `doctor`/`check` explain why). Pins mirror
+# alp-sdk's own `model-compile` extra exactly (due to be dropped from
+# alp-sdk's `pyproject.toml` once `scripts/alp_model/` is deleted -- ADR-0028
+# Task 6) rather than inventing new floors. DEEPX's `dxcom` and DRP-AI's TVM
+# have no such extra on either side -- both are license-gated vendor
+# toolchains with no PyPI wheel to pin.
+model-compile = ["ethos-u-vela>=3.9", "tflite>=2.10", "flatbuffers>=23.1.21"]
+
+# Host-tier `tan model prep` / `run` / `ab` (tan-cli#1287): onnxruntime-based INT8
+# quantization and host reference runs. OPTIONAL and deliberately NOT in the
+# frozen release assets (`.[monitor]` only) -- onnxruntime publishes no macOS
+# x86_64 wheel and adds tens of MB for a verb most users never run. Every import
+# is lazy (`tan.model.prep`, `tan.model.measure`); `tan.core.model_host` turns a
+# missing one into the coded `model.model-extra-missing` refusal. `sympy` is
+# onnxruntime's symbolic shape-inference dependency for `quant_pre_process`.
+# Floors: `onnx>=1.16.0` is the release that fixed CVE-2024-27318 (path traversal
+# through external-data locations) -- `tan model prep` loads customer-supplied
+# models. `onnxruntime>=1.30.0` is the version the external-data and corrupt-
+# sample refusal tests were actually run against; a lower floor was not tested.
+model = ["onnxruntime>=1.30.0", "onnx>=1.16.0", "numpy>=1.26", "sympy>=1.12"]
+
+[project.urls]
+Homepage = "https://github.com/alplabai/tan-cli"
+Repository = "https://github.com/alplabai/tan-cli"
+Issues = "https://github.com/alplabai/tan-cli/issues"
+
+[project.scripts]
+tan = "tan.__main__:main"
+
+[build-system]
+# 77.0.1, measured, not guessed (tan-cli#382). `>=68` was a bound nobody had
+# ever built at: PEP 639 support -- the `license = "Apache-2.0"` string form at
+# the top of this file -- landed in the setuptools 77 line, so every version
+# `>=68` admitted below that REJECTS this file's own metadata:
+#
+#     pip install setuptools==76.1.0
+#     pip wheel --no-deps --no-build-isolation ./python
+#     configuration error: `project.license` must be valid exactly by one
+#     definition (2 matches found)  <- expected `file` or `text`
+#
+# Measured on py3.12.10: 68.1.2 FAIL, 76.1.0 FAIL (the release immediately
+# below the floor), 77.0.1 PASS. Build ISOLATION is what hid it for two years
+# -- pip then downloads the newest setuptools regardless of this line, so every
+# other install path in this repo (`pip install -e ./python` in ci.yml, the
+# venvs in release.yml / python-binaries.yml / clean-host.yml) passes no matter
+# what number is written here. Only a downstream packager pinned to a valid
+# `>=68` environment ever saw it, and they cannot build the distribution at all.
+#
+# 77.0.1 and not `>=77`: setuptools 77.0.0 and 77.0.2 have NO files on PyPI, so
+# `==77` (which PEP 440 zero-pads to 77.0.0) resolves to nothing. 77.0.1 is the
+# first release of that line a resolver can actually install, which makes this
+# bound an exact version the `wheel-floor` job in .github/workflows/ci.yml can
+# pin and build at -- that job derives its pin FROM this string, so a future
+# change here is tested at its own floor with nothing else to update.
+requires = ["setuptools>=77.0.1"]
+build-backend = "setuptools.build_meta"
+
+# Explicit, so `tests/` can never be shipped by an auto-discovery change and a
+# new subpackage is never silently omitted from the wheel.
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tan*"]
+
+# `tan init`'s scaffold trees are DATA, not code, so nothing in the import graph
+# pulls them into a wheel on its own -- and without them five of the six
+# templates fail (`init.template-unreadable`). The frozen binary needs the
+# equivalent `--add-data`, see `scripts/build_binary.sh`.
+[tool.setuptools.package-data]
+"tan.templates" = ["vendored/**/*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+# tan-cli#408. ADVISORY ONLY -- read this before believing it enforces
+# anything. No workflow under `.github/workflows/` runs ruff, so this section
+# changes exactly one thing: an editor with ruff wired in now surfaces the
+# three complexity rules while you type, instead of nothing at all.
+#
+# What actually ENFORCES the size guideline is
+# `tests/gates/test_module_size_budget.py`, a ratchet that runs inside
+# `python -- pytest across python/` -- already a required context on `main`
+# and `dev`, so it gates merges today with no branch-protection change. A new
+# required CI job would have to be added to that list to matter, and adding a
+# required context blocks every open PR until it has run on each of them.
+#
+# `ruff check python/` is red on this tree, deliberately and honestly: 23
+# modules are over 800 lines and 199 functions over 50. The gate records that
+# as a baseline and fails on GROWTH; ruff here reports the standing debt.
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+# PLR0911 too-many-return-statements, PLR0912 too-many-branches,
+# PLR0915 too-many-statements -- the three `bootstrap_cmd._run`'s lone
+# `# noqa` names, and the only `noqa: PLR` anywhere under `tan/`.
+extend-select = ["PLR0911", "PLR0912", "PLR0915"]

tan_cli-0.7.0/setup.cfg

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

tan_cli-0.7.0/tan/__main__.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The `tan` entrypoint. The command surface itself lives in `tan.cli`.
+
+This is the PROCESS BOUNDARY -- the one place both real entrypoints resolve
+to: `pyproject.toml`'s `[project.scripts]` names `tan.__main__:main` (so a
+`pip install`ed console-script calls this module's `main` attribute directly,
+never running the `if __name__ == "__main__"` guard below), and
+`scripts/build_binary.sh` points PyInstaller at this same file. A broken-pipe
+guard sprinkled into each command instead would miss both.
+"""
+import errno
+import os
+import sys
+
+from tan.cli import main as _cli_main
+
+
+def _is_broken_pipe(exc: BaseException) -> bool:
+    """Is this the OSError a reader closing tan's stdout raises?
+
+    EPIPE on POSIX. On Windows the same condition surfaces as a plain
+    `OSError` with `errno.EINVAL` instead -- CPython's Windows layer maps the
+    underlying `ERROR_NO_DATA` to EINVAL, not EPIPE, so `except
+    BrokenPipeError` alone (the POSIX-only idiom from the `signal` docs' "Note
+    on SIGPIPE") does not catch it there.
+
+    EINVAL alone is not pipe-specific on Windows -- a plain filesystem error
+    (e.g. `open("bad<n.txt")`) raises the same errno. That OSError carries a
+    `filename`; the broken-pipe OSError does not (verified against CPython's
+    Windows console-write path), so `filename is None` discriminates a closed
+    stdout from a real filesystem error without weakening the pipe guard.
+    """
+    return isinstance(exc, OSError) and (
+        exc.errno == errno.EPIPE
+        or (sys.platform == "win32" and exc.errno == errno.EINVAL and exc.filename is None)
+    )
+
+
+def _caused_by_broken_pipe(exc: BaseException) -> bool:
+    """Was this `SystemExit` raised WHILE a closed stdout was being handled?
+
+    Nothing reaches this module's `except OSError` arm on POSIX, because two
+    layers below it already convert the `BrokenPipeError` into an exit of
+    their own and neither is reachable through a public hook:
+
+    * Rich -- `Console._check_buffer` catches `BrokenPipeError` and calls
+      `Console.on_broken_pipe`, which sets `quiet` and raises `SystemExit(1)`.
+      This is the one that fires for `tan --help`, since Typer renders every
+      `--help` through Rich.
+    * Typer/Click -- `typer.core._main` (Click's `BaseCommand.main` shape)
+      has `except OSError: if e.errno == errno.EPIPE: ... sys.exit(1)`.
+
+    Both raise their exit from INSIDE the `except BrokenPipeError`/`except
+    OSError` block that caught the pipe, so CPython's implicit chaining leaves
+    the original error on `SystemExit.__context__`. Following that chain is
+    what identifies the case: `SystemExit(1)` on its own is far too broad to
+    remap -- every failed `tan build` raises it -- and the alternatives are
+    all private detail of somebody else's library (Click's
+    `PacifyFlushWrapper` swap, Rich's `console.quiet`), which an entrypoint
+    should not be importing.
+    """
+    seen: set[int] = set()
+    cause: BaseException | None = exc.__cause__ or exc.__context__
+    while cause is not None and id(cause) not in seen:
+        if _is_broken_pipe(cause):
+            return True
+        seen.add(id(cause))
+        cause = cause.__cause__ or cause.__context__
+    return False
+
+
+def _exit_quietly() -> None:
+    """Exit 0 with a stdout that can no longer raise.
+
+    Redirecting stdout to the null device before returning matters: without
+    it, the interpreter's own shutdown-time flush of the now-broken stdout
+    raises the same OSError again, straight past any exception handler, and
+    prints "Exception ignored in: ..." on stderr regardless.
+    """
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+    except OSError:
+        pass
+    sys.exit(0)
+
+
+def main() -> None:
+    """Run the real CLI, and turn a closed stdout into a quiet exit.
+
+    `tan generate --help | grep -q x` (or `| head`, any reader that stops
+    early) closes tan's stdout mid-write. The Rust oracle exits 0 with empty
+    stderr in that situation on BOTH hosts -- measured: `tan.exe generate
+    --help | head -n1` on Windows, and tan 0.4.1 linux-musl writing a
+    4327-byte `--help` into a never-read 4 KiB pipe, which is a guaranteed
+    EPIPE. This pins the port to the same observable behaviour, and it takes
+    two arms because the pipe reaches this frame in two different shapes:
+
+    * POSIX -- as a `SystemExit(1)` some library layer already raised for it
+      (see `_caused_by_broken_pipe`). Left alone, `tan --help | head -n1`
+      exited 1 here where the oracle exits 0.
+    * Windows -- as the raw `OSError`, because the errno is EINVAL and none of
+      those layers recognises it (see `_is_broken_pipe`). Left unhandled,
+      Typer's installed pretty-exception hook renders the whole stack as a
+      boxed traceback and the process exits non-zero.
+    """
+    try:
+        _cli_main()
+    except SystemExit as exc:
+        if not _caused_by_broken_pipe(exc):
+            raise
+        _exit_quietly()
+    except OSError as exc:
+        if not _is_broken_pipe(exc):
+            raise
+        _exit_quietly()
+
+
+if __name__ == "__main__":
+    main()