treestamp 0.1.0__tar.gz

treestamp-0.1.0/.gitignore

@@ -0,0 +1,145 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.venv/
+venv/
+ENV/
+env/
+pip-log.txt
+pip-delete-this-directory.txt
+
+# TypeScript
+*.tsbuildinfo
+.tsc-cache/
+
+# Testing
+coverage/
+.nyc_output/
+.pytest_cache/
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# IDEs and editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+*.sublime-project
+
+# OS files
+.DS_Store
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Build outputs
+dist/
+build/
+out/
+.next/
+.nuxt/
+.cache/
+.parcel-cache/
+
+# Temporary files
+.tmp/
+.temp/
+tmp/
+temp/
+
+# Package files
+*.tgz
+*.tar.gz
+*.zip
+
+# Database
+*.sqlite
+*.sqlite3
+*.db
+
+# Miscellaneous
+.eslintcache
+.stylelintcache
+*.bak
+*.orig
+
+# PERSONAL
+
+INTERNAL
+
+sync-from-*
+
+# Treestamp tooling and local working material
+.stamps/
+.mypy_cache/
+.ruff_cache/
+.playwright-cli/
+output/
+__INTERNAL__/

treestamp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,51 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        exclude: ^assets/TREESTAMP_BANNER\.png$
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (project environment)
+        entry: make typecheck
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: web-typecheck
+        name: mypy (hosted preview)
+        entry: make web-typecheck
+        language: system
+        files: ^web/
+        types: [python]
+        pass_filenames: false
+      - id: pytest
+        name: pytest (package, changed files)
+        entry: venv/bin/python scripts/changed_tests.py package
+        language: system
+        files: ^(src/|tests/|pyproject\.toml|Makefile)
+        pass_filenames: true
+      - id: web-test
+        name: pytest (hosted preview, changed files)
+        entry: venv/bin/python scripts/changed_tests.py web
+        language: system
+        files: ^(web/src/|web/tests/|web/pyproject\.toml|src/)
+        pass_filenames: true
+      - id: treestamp-check
+        name: treestamp check (this repository's README)
+        entry: make integration-check
+        language: system
+        pass_filenames: false
+        always_run: true

treestamp-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,14 @@
+- id: treestamp
+  name: treestamp update
+  description: Maintain the README tree from staged Git paths
+  entry: treestamp update
+  language: python
+  pass_filenames: false
+  always_run: true
+- id: treestamp-check
+  name: treestamp check
+  description: Fail if the README tree needs maintenance
+  entry: treestamp check
+  language: python
+  pass_filenames: false
+  always_run: true

treestamp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

treestamp-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 (2026-10-22)
+
+
+### Features
+
+* import treestamp public source tree ([764f4e9](https://github.com/reponomics/treestamp/commit/764f4e9bd9e9630d628c86e90f4d813902a85e6e))
+* prepare release and production deployment automation ([#1](https://github.com/reponomics/treestamp/issues/1)) ([25722b8](https://github.com/reponomics/treestamp/commit/25722b884e29dd8a4ff65e22c782f4e11ea98922))
+
+## 0.1.0 (Unreleased)
+
+- Create and curate README directory trees in the terminal or web editor.
+- Preserve expanded directories, hidden paths, and single-line annotations when updating a tree.
+- Check and update documents from the Git index or a locally available commit, with pre-commit hooks for automation.
+- Export Unicode, ASCII, or Markdown list trees with optional child counts.
+- Edit public GitHub repository snapshots in the hosted editor and copy the result into your project.

treestamp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reponomics
+
+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.

treestamp-0.1.0/MAINTENANCE.md

@@ -0,0 +1,146 @@
+# Maintenance
+
+These procedures require a full Git checkout, including the hosted application in `web/`. Use the environment and contributor setup in [CONTRIBUTING](https://github.com/reponomics/treestamp/blob/main/.github/CONTRIBUTING.md). Run `make help` for available commands. Stage source changes before updating the README tree because Treestamp reads the Git index.
+
+## Validate and build
+
+```bash
+make ci web-ci docs-check
+make web-browser-test
+make build metadata-check distribution-check
+make integration-check
+```
+
+Browser checks require the separate browser dependencies described in [the web README](https://github.com/reponomics/treestamp/blob/main/web/README.md). `metadata-check` validates both distributions against the approved file set and reports their hashes. `distribution-check` installs the wheel and source archive into fresh environments and exercises headless commands and the terminal editor. After committing a candidate, `make hook-check` checks the public pre-commit hooks from that exact HEAD.
+
+Build release artifacts from a clean, reviewed revision. Inspect the archive contents before publication; internal notes and unrelated products do not belong in either distribution. Remove or archive older files from `dist/` before a release build so checks and uploads cannot select stale artifacts.
+
+## Dependency and installer maintenance
+
+The core and hosted projects share `uv.lock`. `make install` installs locked dependencies and build tools into `venv`, then builds the local editable packages without isolated dependency resolution. `make build` synchronizes that locked toolchain before building. Docker selects only the hosted runtime dependencies and operational TLS tools from the same lock, builds both local wheels with the locked build group, and installs those wheels offline. Third-party dependencies must have compatible wheels; the controlled install fails rather than resolving unpinned build dependencies for a source archive.
+
+The uv version is pinned in `.tool-versions`, checked by the Makefile, and read by CI. Docker uses the matching version and image digest. Update those together, including when Dependabot proposes an update to the Docker image; Dependabot does not maintain the `.tool-versions` pin. Keep pip at least `26.2.2`, certifi at least `2026.10.19`, and uv at least `0.13.4` for the eMudhra certificate incident. Continue updating the pinned Python base image and checking its system certificate store; the Python dependency lock does not manage operating-system certificates.
+
+Dependabot proposes uv dependency updates. Review lock changes with their declarations, run the quality gates and container checks, and commit both together. Release Please also updates the two local package versions in the lock. The clean-distribution checks intentionally use pip to resolve the published dependency ranges outside the workspace; they test consumer compatibility separately from the locked development environment. Revert a dependency change by reverting its declarations and lock together, then synchronizing the environment again.
+
+## Repository and release setup
+
+Use `main` as the default branch and require pull requests and signed commits. After the checks have run in the repository, select these required PR check names:
+
+- `Regression suite (Linux, Python 3.11)`
+- `Regression suite (Linux, Python 3.12)`
+- `Regression suite (Windows, Python 3.11)`
+- `Regression suite (Windows, Python 3.12)`
+- `Hosted editor (Linux, Python 3.11)`
+- `README tree freshness`
+- `Validate PR title`
+
+Production deployment, Release Please, and PyPI publication do not run on ordinary PRs and should not be required PR checks. Enable immutable GitHub Releases before the first release. CodeQL uses GitHub's default setup with the extended query suite for Python, JavaScript/TypeScript, and GitHub Actions, managed in the repository's code scanning settings. Do not enable an advanced CodeQL workflow alongside default setup: GitHub rejects its analysis uploads. Scorecard runs only when the repository is public; OSV scans resolved Python dependencies while private, retaining its report in Actions without uploading it to code scanning.
+
+Release Please manages the core and hosted versions together, updates `CHANGELOG.md`, and creates version tags and GitHub Releases after its release PR is merged. The published-release event runs the PyPI workflow, which validates the tag, versions, and commit on `main`, builds and tests fresh distributions, and publishes them with attestations through Trusted Publishing. Website deployment has its own trigger and does not wait for a package release.
+
+Configure these GitHub settings before enabling publication or production deployment:
+
+| Setting | Location | Purpose |
+| --- | --- | --- |
+| `RELEASE_APP_CLIENT_ID` | Repository variable | GitHub App used by Release Please |
+| `RELEASE_APP_PRIVATE_KEY` | Repository secret | Private key for that App |
+| `PYPI_PUBLISH_ENABLED=true` | Repository variable | Enables PyPI publication once the repository is public |
+| `pypi` | GitHub environment | Publication approvals and PyPI's trusted identity |
+| `FLY_DEPLOY_ENABLED=true` | Repository variable | Enables independent production deployment on pushes to `main` |
+| `FLY_API_TOKEN` | Secret in the `production` environment | Deploy token scoped to the production Fly app |
+
+Install the release App on the selected `reponomics/treestamp` repository with write access to contents, issues, and pull requests. Its token lets release PRs trigger CI and GitHub Releases trigger publication. The App does not need organization-wide repository access. The `pypi` environment exists; review its protections and those of `production` against the maintainers' approval policy. Publication runs from release tags, while deployment runs from `main`.
+
+In PyPI, configure a [pending Trusted Publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) for project `treestamp`, GitHub owner `reponomics`, repository `treestamp`, workflow filename `publish.yml`, and environment `pypi`. No long-lived PyPI upload token is needed. A pending publisher does not reserve the package name.
+
+## First release and subsequent releases
+
+The first release is configured as `0.1.0`. Complete these steps in order:
+
+1. Merge the automation setup to `main`, configure the release App, enable immutable releases, and configure the `pypi` environment and Trusted Publisher.
+2. Finish the public-content review, make the repository public, enable private vulnerability reporting, and set `PYPI_PUBLISH_ENABLED=true`.
+3. Review Release Please's first release PR. Confirm that both project versions and its manifest say `0.1.0`. Consolidate the existing `0.1.0 (Unreleased)` notes into the generated dated release section so the changelog describes the release once.
+4. After its required checks pass, merge that release PR. Release Please creates the tag and GitHub Release; the publication workflow validates and uploads the package. Verify the PyPI files, installation, and attestations.
+
+Do not merge the first release PR before publication is ready: a release created while the repository is private or publication is disabled will not publish automatically when those settings change later. Subsequent releases follow the same release-PR process. Explain changes requiring user action in the changelog, including format changes before `1.0`.
+
+Published versions are immutable. Correct a released package through a later release; do not move its tag, delete and recreate its release, or upload changed files under the same version. If a publication run fails, inspect which artifacts reached PyPI before retrying it.
+
+## Production deployment
+
+[`web/fly.toml`](https://github.com/reponomics/treestamp/blob/main/web/fly.toml) promotes the existing `treestamp-preview` Fly app to production at `https://treestamp.reponomics.org`. Future previews use the separate `reponomics-treestamp-preview` app. Leave `FLY_DEPLOY_ENABLED` unset until production deployment, session routing, and custom-domain checks succeed.
+
+Keep the production app's GitHub API credentials in Fly secrets: either `GITHUB_TOKEN` or `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_INSTALLATION_ID`, and `GITHUB_APP_PRIVATE_KEY`. To install or rotate the App credentials, `make fly-secrets` accepts `FLY_CONFIG=web/fly.toml` and reads the key from `GITHUB_APP_PRIVATE_KEY_FILE`. These service credentials are separate from the App used by Release Please.
+
+Deploy a clean, reviewed commit on `main` manually for the initial setup:
+
+```bash
+make fly-production-deploy FLY_DEPLOY_FLAGS=--remote-only
+make fly-status FLY_CONFIG=web/fly.toml
+```
+
+Production keeps two Machines running; the production target enables Fly's high-availability provisioning. Rolling deployment replaces at most one Machine at a time and checks `/healthz` during rollout. A build failure stops before rollout. A failed health check can halt rollout, but it is not a guarantee against application bugs or interrupted editing sessions. With `FLY_SESSION_ROUTING=true`, a browser-session cookie uses Fly's `FLY_MACHINE_ID` to route an active editing session to its cached snapshot. Sessions are temporary. A Machine failure, restart, or deployment can require a fresh URL load; the existing browser draft stays copyable and is replaced only after a successful load. Snapshots and quotas remain process-local, so changing the Machine count changes aggregate capacity and limits.
+
+The custom domain is attached to `treestamp-preview` in Fly. These records are saved in Cloudflare for the `reponomics.org` zone, with proxying disabled. Fly reports the certificate as Ready, with active RSA and ECDSA certificates and successful validations:
+
+| Type | Name | Value | Cloudflare proxy |
+| --- | --- | --- | --- |
+| CNAME | `treestamp` | `8w9r381.treestamp-preview.fly.dev` | DNS only; enable after the reviewed production deployment |
+| TXT | `_fly-ownership.treestamp` | `app-8w9r381` | Not applicable |
+| CNAME | `_acme-challenge.treestamp` | `treestamp.reponomics.org.8w9r381.flydns.net` | DNS only |
+
+Recheck the records with `fly certs setup treestamp.reponomics.org --app treestamp-preview` if the app changes, and check certificate status with `fly certs check treestamp.reponomics.org --app treestamp-preview`. Keep proxying disabled until a reviewed `main` deployment includes Cloudflare peer validation; then enable it with Full (strict) TLS and complete the checks below. See [Fly's custom-domain instructions](https://docs.fly.io/networking/custom-domain) and [Cloudflare guidance](https://docs.fly.io/networking/understanding-cloudflare).
+
+Keep HTML, API, and `/healthz` responses out of Cloudflare's edge cache; do not apply a Cache Everything rule to this hostname. The application accepts `CF-Connecting-IP` only when Fly's peer address belongs to the configured Cloudflare ranges. Worker subrequests and invalid visitor headers fall back conservatively to the peer for rate limiting. Review `CLOUDFLARE_PROXY_CIDRS` against [Cloudflare's published ranges](https://www.cloudflare.com/ips/) when maintaining this configuration, and keep the service behind Fly ingress.
+
+Check `/healthz` through the custom domain and confirm that `build_commit` matches the deployed commit. Exercise loading, editing, copying, and draft preservation after failed loads in a browser, then run a public-repository smoke test with a matching local checkout:
+
+```bash
+make fly-smoke SMOKE_URL=https://treestamp.reponomics.org \
+    SMOKE_REPO=OWNER/REPOSITORY SMOKE_CHECKOUT=/path/to/checkout
+```
+
+Store an app-scoped Fly deploy token as `FLY_API_TOKEN` in the GitHub `production` environment, then enable `FLY_DEPLOY_ENABLED`. The separate [`deploy.yml`](https://github.com/reponomics/treestamp/blob/main/.github/workflows/deploy.yml) workflow deploys pushes to `main`, including merged PRs. Required PR checks are the merge gate; deployment does not wait for post-merge CI, and a failure in the separate CI workflow does not cancel it. Deployment never runs on PR events. No repository connection or auto-deploy setting in Fly is needed; leave Fly-native auto-deployment disabled to avoid duplicate rollouts. Cloudflare supplies DNS and proxying, while GitHub Actions invokes Fly to build and deploy the application.
+
+Deployments are serialized without cancelling an active rollout. A queued run skips an obsolete commit if a newer commit is already on `main`. The build receives the pushed commit identifier, and the final health probe verifies that the public domain serves that commit. A failed final probe reports deployment failure; it does not automatically roll back. No separate release command or blue-green deployment is configured.
+
+For rollback, prefer a reviewed revert on `main` through the same checks. An urgent manual rollback should use a previously verified image with current certificate stores; verify its build identifier and smoke test afterward, and reconcile `main` before the next automatic deployment.
+
+## Preview deployment
+
+The separate `web/fly.preview.toml` targets `reponomics-treestamp-preview`. Here, preview means a test deployment of the web editor. This app has been created but has not been deployed. Install its GitHub API credentials separately before its first deployment, using `make fly-secrets FLY_CONFIG=web/fly.preview.toml` if using a GitHub App. Preview deployment is manual and defaults to one Machine that may stop when idle:
+
+```bash
+make web-image
+make fly-preview-deploy
+make fly-status FLY_CONFIG=web/fly.preview.toml
+```
+
+Deploy a clean, committed candidate so that identifier describes the deployed files. The Docker build checks certificate stores; `make tls-check` performs the corresponding check in the local Python environment. Credentials belong in the host's secret store, not in Git.
+
+After deploying, check `https://reponomics-treestamp-preview.fly.dev/healthz`, then run the public-repository smoke test with a matching local checkout:
+
+```bash
+make fly-smoke SMOKE_URL=https://reponomics-treestamp-preview.fly.dev \
+    SMOKE_REPO=OWNER/REPOSITORY SMOKE_CHECKOUT=/path/to/checkout
+```
+
+The repository must be public, and the local checkout must contain the commit used by the hosted session. Verify loading, editing, copying, and draft preservation after failed loads in a browser. For rollback, redeploy a previously verified image with up-to-date certificate stores and recheck the build identifier and smoke test.
+
+## Product page
+
+The product information page and selected demos belong in the separate `reponomics-web` repository, using its static assets and website deployment. They are not deployed by this repository. Add the product-page link after that page is published.
+
+## External setup checklist
+
+- [ ] Configure `main` protections, required checks, signed commits, and immutable releases.
+- [ ] Install the release App on this repository and configure its variable and secret.
+- [ ] Finish the pending Trusted Publisher and review `pypi` environment protections; complete public review and enable publication before merging the first release PR.
+- [ ] Enable private vulnerability reporting when the repository becomes public.
+- [ ] Deploy the production configuration to `treestamp-preview` and verify two-Machine session routing and draft recovery.
+- [x] Save the three Cloudflare DNS records without proxying and validate the Fly certificate.
+- [ ] After the reviewed production deployment, enable Cloudflare proxying with Full (strict) TLS, verify cache behavior, and complete domain and smoke checks.
+- [ ] Configure the `production` environment and app-scoped deploy token, then enable deployment from `main`.
+- [ ] Configure credentials and deploy the new `reponomics-treestamp-preview` app before using it for previews.
+- [ ] Publish the product page and demos from `reponomics-web` when ready.

treestamp-0.1.0/Makefile

@@ -0,0 +1,116 @@
+.DEFAULT_GOAL := help
+VENV ?= venv
+PYTHON ?= python3
+UV ?= uv
+UV_VERSION := $(shell awk '$$1 == "uv" {print $$2}' .tool-versions)
+NODE ?= node
+FLY ?= fly
+ACTIONLINT ?= actionlint
+PY := $(VENV)/bin/python
+PIP := $(VENV)/bin/pip
+CLI := $(VENV)/bin/treestamp
+
+.PHONY: help venv install format format-check lint typecheck test cov ci build distribution-check integration-check hook-check pre-commit-check tui clean web-install web-lint web-typecheck web-test web-cov web-ci web-fake web-serve web-image web-js-test web-browser-test fly-secrets fly-deploy fly-status fly-logs fly-smoke docs-check metadata-check
+GITHUB_API_URL ?= http://127.0.0.1:8100
+FAKE_PORT ?= 8100
+FAKE_FLAGS ?=
+FLY_CONFIG ?= web/fly.toml
+FLY_PRODUCTION_CONFIG ?= web/fly.toml
+FLY_PREVIEW_CONFIG ?= web/fly.preview.toml
+FLY_DEPLOY_FLAGS ?=
+FLY_HA ?= true
+BUILD_COMMIT ?= $(shell git rev-parse HEAD)
+SMOKE_REPO ?= reponomics/treestamp
+SMOKE_URL ?= https://treestamp.reponomics.org
+SMOKE_CHECKOUT ?= .
+WEB_VENV := $(abspath $(VENV))
+.PHONY: tls-check fly-production-deploy fly-preview-deploy workflow-check lock-check lock-update web-browser-install uv-check
+export UV_PROJECT_ENVIRONMENT := $(abspath $(VENV))
+help: ## Show available targets
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "%-22s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+uv-check: ## Check that uv matches the pinned development tool version
+	@test "$$($(UV) --version | awk '{print $$2}')" = "$(UV_VERSION)" || \
+	  { echo "Install uv $(UV_VERSION), as pinned in .tool-versions."; exit 1; }
+venv: uv-check ## Create the virtual environment
+	@test -d "$(VENV)" || $(UV) venv --python $(PYTHON) $(VENV)
+lock-check: uv-check ## Reject dependency declarations that differ from the lock
+	$(UV) lock --check
+lock-update: uv-check ## Resolve intentional dependency upgrades into uv.lock
+	$(UV) lock --upgrade
+install: uv-check ## Sync locked core, hosted, build, and test dependencies into venv
+	$(UV) sync --locked --all-packages --all-extras --no-install-workspace --no-build
+	$(UV) sync --locked --all-packages --all-extras --no-build-isolation
+format: ## Format Python code
+	$(VENV)/bin/ruff format .
+format-check: ## Check Python formatting
+	$(VENV)/bin/ruff format --check .
+lint: ## Lint Python code
+	$(VENV)/bin/ruff check .
+typecheck: ## Check strict Python types
+	$(VENV)/bin/mypy
+test: ## Run the regression suite, including headless TUI journeys
+	$(PY) -m pytest
+cov: ## Run tests with branch coverage
+	$(PY) -m pytest --cov --cov-report=term-missing --cov-fail-under=90
+ci: format-check lint typecheck cov ## Run all local quality gates
+docs-check: ## Check retained local documentation links and packaged README URLs
+	$(PY) scripts/check_docs.py
+metadata-check: ## Check built metadata, README rendering, package contents, and hashes
+	$(PY) -m twine check --strict dist/*.whl dist/*.tar.gz
+	$(PY) scripts/release_check.py
+build: install ## Sync locked build tools and build wheel and sdist without isolation
+	$(PY) -m build --no-isolation
+distribution-check: ## Verify clean wheel/sdist headless commands and editor workflows
+	$(PY) scripts/distribution_check.py
+integration-check: ## Verify the repository's treestamped README
+	$(CLI) check README.md
+workflow-check: ## Validate GitHub Actions workflows (requires actionlint)
+	$(ACTIONLINT)
+hook-check: ## Exercise installed repository hooks at HEAD
+	$(PY) scripts/hook_check.py
+pre-commit-check: ## Run the repository development hooks
+	$(VENV)/bin/pre-commit run --all-files
+tui: ## Open the editor
+	$(CLI)
+clean: ## Remove generated build and coverage artifacts
+	rm -rf dist/ build/ .coverage htmlcov/
+web-install: install ## Sync the locked workspace, including hosted development dependencies
+web-browser-install: install ## Sync the locked browser test dependencies (install Chromium separately)
+web-lint: ## Lint the web editor project
+	$(VENV)/bin/ruff check web && $(VENV)/bin/ruff format --check web
+web-typecheck: ## Check strict types for the web editor project
+	cd web && $(WEB_VENV)/bin/mypy
+web-test: ## Run the web editor tests
+	cd web && $(WEB_VENV)/bin/python -m pytest
+web-cov: ## Run the web editor tests with branch coverage
+	cd web && $(WEB_VENV)/bin/python -m pytest --cov --cov-report=term-missing --cov-fail-under=90
+web-ci: web-lint web-typecheck web-cov web-js-test ## Run all web editor quality gates
+web-js-test: ## Run the page's pure-logic tests with Node's test runner
+	$(NODE) --test web/tests/js/*.test.mjs
+web-browser-test: ## Drive the page in a browser (needs make install and a browser)
+	cd web && $(WEB_VENV)/bin/python -m pytest -q -o addopts="" -m browser tests/browser $(BROWSER_FLAGS)
+web-fake: ## Serve this checkout as a fake GitHub API on FAKE_PORT (FAKE_FLAGS adds failure modes)
+	$(PY) web/scripts/fake_github.py --repo . --port $(FAKE_PORT) $(FAKE_FLAGS)
+web-serve: ## Run the web editor locally against GITHUB_API_URL
+	GITHUB_API_URL=$(GITHUB_API_URL) GITHUB_RATE_RESERVE=0 $(VENV)/bin/uvicorn --factory treestamp_web.app:create_app --host 127.0.0.1 --port 8000 --reload
+tls-check: ## Check Python TLS package versions and certificate trust stores
+	$(PY) web/scripts/check_tls.py
+web-image: ## Build the web editor container image
+	docker build -f web/Dockerfile --build-arg BUILD_COMMIT="$(BUILD_COMMIT)" -t treestamp-web:local .
+fly-secrets: ## Set the GitHub App secrets on Fly (GITHUB_APP_CLIENT_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY_FILE)
+	@test -n "$(GITHUB_APP_CLIENT_ID)" -a -n "$(GITHUB_APP_INSTALLATION_ID)" -a -n "$(GITHUB_APP_PRIVATE_KEY_FILE)" || \
+	  { echo "usage: make fly-secrets GITHUB_APP_CLIENT_ID=... GITHUB_APP_INSTALLATION_ID=... GITHUB_APP_PRIVATE_KEY_FILE=path.pem"; exit 2; }
+	$(FLY) secrets set --config $(FLY_CONFIG) GITHUB_APP_CLIENT_ID="$(GITHUB_APP_CLIENT_ID)" \
+	  GITHUB_APP_INSTALLATION_ID="$(GITHUB_APP_INSTALLATION_ID)" GITHUB_APP_PRIVATE_KEY="$$(cat $(GITHUB_APP_PRIVATE_KEY_FILE))"
+fly-deploy: ## Build and deploy the app selected by FLY_CONFIG (defaults to production)
+	$(FLY) deploy --config $(FLY_CONFIG) --dockerfile web/Dockerfile --build-arg BUILD_COMMIT="$(BUILD_COMMIT)" --ha=$(FLY_HA) $(FLY_DEPLOY_FLAGS)
+fly-production-deploy: ## Build and deploy the production editor
+	$(MAKE) fly-deploy FLY_CONFIG=$(FLY_PRODUCTION_CONFIG) FLY_HA=true
+fly-preview-deploy: ## Build and deploy the separate test editor
+	$(MAKE) fly-deploy FLY_CONFIG=$(FLY_PREVIEW_CONFIG) FLY_HA=false
+fly-status: ## Show the app's machines and health
+	$(FLY) status --config $(FLY_CONFIG)
+fly-logs: ## Stream the service's log lines from Fly
+	$(FLY) logs --config $(FLY_CONFIG)
+fly-smoke: ## Run the smoke script against the deployed app (SMOKE_REPO, SMOKE_CHECKOUT)
+	$(PY) web/scripts/smoke.py $(SMOKE_URL) --repo $(SMOKE_REPO) --checkout $(SMOKE_CHECKOUT)