Commit Graph
3 Commits
Author SHA1 Message Date
trs-80 fe50d96acc chore(dashboard): remove unused vendored htmx (#3469)
## Description

The dashboard has loaded htmx on every page view since the UI's first
commit (`1599821c`, 2026-01-30), and vendored it locally since #2734,
but nothing in the repository has ever used it. Its interaction code is
Alpine plus native `fetch`.

A repository-wide search across all file types — `hx-*`, `data-hx-*`,
`hx_`, `htmx.on/ajax/process/trigger/config/find/swap`, and
`HX-Request`/`HX-Trigger`/`HX-Target`/`HX-Swap` — returns no hit outside
the asset itself. `settings.html` never loaded it, and no packaging file
names it.

This removes the 47,755-byte asset and its references. No replacement
library.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Delete `headroom/dashboard/static/htmx.min.js` (47,755 bytes) and its
`<script>` tag in `dashboard.html`.
- Remove the htmx stanza from `NOTICE` and the `htmx.min.js` entry from
the `ASSETS` list in `tests/test_dashboard_static_assets.py` and
`tests/test_dashboard_static_mime_types.py`.
- Update three `tailwind/htmx/alpine` prose comments to
`tailwind/alpine` (`headroom/dashboard/__init__.py`,
`headroom/proxy/server.py`, and the test module docstring).
- Strengthen `test_dashboard_only_references_served_assets`: it checked
one direction only (each `ASSETS` entry appears in the served HTML). It
now asserts set equality both ways — every `/dashboard/static/...`
reference is in `ASSETS`, and every file in `STATIC_DIR` is in `ASSETS`
— so a re-vendored library nobody loads, or a loaded file nobody
vendored, fails the suite. No new test file; the existing test already
owned this contract.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

The strengthened assertion fails against the tree without this change
and passes with it:

### Test Output

```text
$ pytest tests/test_dashboard_static_assets.py -q -k only_references   # asset restored, template tag restored
FAILED tests/test_dashboard_static_assets.py::test_dashboard_only_references_served_assets
1 failed, 8 deselected in 1.82s

$ pytest tests/test_dashboard_static_assets.py tests/test_dashboard_static_mime_types.py \
         tests/test_dashboard_accessibility.py tests/test_dashboard_agent_usage.py \
         tests/test_dashboard_token_savings.py tests/test_cli_dashboard.py \
         tests/test_proxy_dashboard_stats_cache.py \
         tests/test_dashboard_cache_lifetime_playwright.py \
         tests/test_dashboard_cache_net_playwright.py \
         tests/test_dashboard_cache_ttl_playwright.py -q
58 passed, 1 skipped in 13.23s

$ pre-commit run --files NOTICE headroom/dashboard/__init__.py \
      headroom/dashboard/templates/dashboard.html headroom/proxy/server.py \
      tests/test_dashboard_static_assets.py tests/test_dashboard_static_mime_types.py
ruff (legacy alias)......................................................Passed
ruff format..............................................................Passed
mypy.....................................................................Passed
```

`tests/test_dashboard/test_live_feed.py` fails 4 tests here, identically
with and without this change: the harness waits for `#feed-toggle`,
which is not in the template. Pre-existing and unrelated.

## Real Behavior Proof

- Environment: macOS 15.6, Python 3.13.11, Playwright 1.52.0 with
Chromium Headless Shell 136.0.7103.25, branch based on `main` @
`e67b3c8a`.
- Exact command / steps: drove a real browser through the repository's
existing accessibility harness
(`tests/test_dashboard_accessibility._open`, which serves the real
vendored assets from disk) — load `/dashboard`, switch Lifetime then
Session, toggle the theme twice, expand a request row, open the
live-feed drawer and close it with Escape, then wait one 5 s poll cycle
— recording every request, every console warning/error, every page error
and the rendered `<main>` text. Ran identically against the tree with
htmx restored and with it removed, then diffed.
- Observed result: output is identical except the two intended
differences — `GET /dashboard/static/htmx.min.js` is gone (14 requests
to 13, 47,755 fewer bytes per uncached load) and two JavaScript
stack-trace line numbers shift by one, from the deleted `<script>` line.
Same console warnings, same errors, same 2,192 characters of rendered
`<main>`. Every dashboard section still renders, which is the symptom to
watch for here: each lives inside a `<template x-if>` that renders
nothing at all if Alpine fails to load.
- Not tested: no browser latency was measured and none is claimed — the
honest result is one fewer request and 47,755 fewer bytes. Static
analysis cannot prove the absence of runtime htmx use; the evidence is
the repository-wide search plus the byte-identical browser run, not a
proof. Not exercised against a real upstream provider, and not tested on
Windows or in Edge, the environment that motivated vendoring these
assets in #2734.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. The dashboard's static assets are
not rollout-gated.
- Minimum rollout channel: N/A — no rollout-managed feature is touched.
- Stable/default behavior changed: No. The dashboard renders and behaves
identically; one script that was parsed and never used is no longer
sent.
- Kill switch / disable path: N/A — there is no flag to flip. Reverting
the commit restores the asset and the script tag.
- Unsafe override required: No.
- Qualification impact: None. No provider, proxy or optimization path is
touched.
- Rollback path: `git revert` of this commit restores `htmx.min.js`, the
`<script>` tag, the NOTICE stanza and the previous test lists in one
step. No data, schema or config migration is involved.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

None. The rendered dashboard is unchanged — verified by comparing the
rendered `<main>` text before and after, not by eye.

## Additional Notes

- Documentation change is the `NOTICE` entry: the vendored-asset
attribution list is the documentation that had to move with this.
- One environment note for anyone reproducing the browser proof: the
dashboard Playwright tests need `python -m playwright install chromium`.
Without it, seven dashboard tests fail before reaching any assertion.
- A separate pre-existing issue found while running the suites:
`tests/test_dashboard_cache_ttl_playwright.py` writes
`dashboard-cache-ttl-main.png` into the repository root on every run, so
it shows as a modified tracked file. Left alone here; it deserves its
own change.
2026-09-11 20:41:51 -07:00
Tejas Chopra 7c9b046595 fix(dashboard): serve tailwind/htmx/alpine locally instead of from CDNs (#2734)
## Description

The dashboard loaded all three of its front-end dependencies from
third-party CDNs at page load:

```html
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://unpkg.com/htmx.org@1.9.10"></script>
<script src="https://unpkg.com/alpinejs@3.13.3/dist/cdn.min.js" defer></script>
```

Microsoft Edge's Tracking Prevention classifies `unpkg.com` as a tracker
and blocks it by default on Windows; locked-down corporate proxies block
both hosts. On those machines none of the three scripts executed — no
Tailwind CSS, no htmx polling, no Alpine bindings, plus an uncaught
`ReferenceError: tailwind is not defined` from the inline
`tailwind.config` assignment at `dashboard.html:21`. The dashboard
rendered blank. Reported from a Windows user's console:

```text
Tracking Prevention blocked access to storage for https://unpkg.com/htmx.org@1.9.10.
Tracking Prevention blocked access to storage for https://unpkg.com/alpinejs@3.13.3/dist/cdn.min.js.
```

This vendors the three files and serves them from the proxy, so the
dashboard has no external network dependency at all.

Note for anyone triaging the same report: the `cdn.tailwindcss.com
should not be used in production` line in that console output is **not**
related. It is an unconditional `console.warn` in the Tailwind Play CDN
build (no hostname guard), so it fires on every load, localhost
included, and it still fires now that the bundle is self-hosted.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Vendored
`headroom/dashboard/static/{tailwind.min.js,htmx.min.js,alpine.min.js}`
— Tailwind Play CDN 3.4.17, htmx 1.9.10, Alpine 3.13.3, byte-for-byte as
published.
- `headroom/dashboard/__init__.py`: added `STATIC_DIR`.
- `headroom/proxy/server.py`: mounted `/dashboard/static`, registered
**before** `register_provider_routes`' catch-all so the asset requests
are not tunneled to the wrapped upstream provider (same ordering
constraint as the `/favicon.ico` route, GH #1787). `check_dir=False` so
a missing assets directory 404s the dashboard JS rather than aborting
proxy startup.
- `headroom/dashboard/templates/{dashboard,settings}.html`: script `src`
→ `/dashboard/static/…`.
- `NOTICE`: MIT / 0BSD attribution for the three vendored bundles.
- `tests/test_dashboard_static_assets.py`: new.

No packaging change needed — `[tool.maturin]` includes everything under
`headroom/`, so the wheel picks the assets up. Wheel grows ~498 KB (407
KB of that is the Tailwind Play bundle).

## Testing

- [x] Unit tests pass (`pytest`) — targeted, see note under *Not tested*
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ python -m pytest tests/test_dashboard_static_assets.py tests/test_proxy_settings_endpoints.py -q
tests/test_dashboard_static_assets.py ......                             [ 21%]
tests/test_proxy_settings_endpoints.py ......................            [100%]
============================== 28 passed in 4.47s ==============================

$ ruff check .
All checks passed!

$ ruff format --check headroom/proxy/server.py headroom/dashboard/__init__.py tests/test_dashboard_static_assets.py
3 files already formatted

$ mypy headroom
Success: no issues found in 509 source files
```

## Real Behavior Proof

- **Environment:** macOS 15 (Darwin 25.4.0), Python 3.12.6, headless
Chromium via Playwright, proxy served in-process with
`create_app(ProxyConfig(optimize=False, cache_enabled=False,
log_full_messages=True))` on `:8787`.
- **Exact command / steps:** loaded `/dashboard` and
`/dashboard/settings` with `wait_until="networkidle"`, then asserted the
globals exist, that Tailwind actually generated CSS (computed style of a
`px-3` element), and recorded every non-localhost request plus all
`pageerror`/`console.error` events.
- **Observed result:**

```text
/dashboard          | alpine: True | tailwind css: True | external: none | errors: none
/dashboard/settings | alpine: True | tailwind css: True | external: none | errors: none

/dashboard                        200 text/html; charset=utf-8  191549
/dashboard/static/tailwind.min.js 200 text/javascript; charset=utf-8  407279
/dashboard/static/htmx.min.js     200 text/javascript; charset=utf-8   47755
/dashboard/static/alpine.min.js   200 text/javascript; charset=utf-8   43441

feed-toggle visible: True
alpine loaded: True  htmx: True  tailwind: True
tailwind applied (px-3 padding): 12px
external hosts: none
console errors: none
```

Zero external requests on either page, so the Edge/firewall failure mode
is structurally gone rather than worked around.

- **Not tested:**
- No Windows machine available — the fix is verified as "makes zero
external requests", which is the property the Windows failure depended
on, but it has not been confirmed against Edge with Tracking Prevention
on. Worth a check by someone on Windows before release.
  - Full `pytest` suite not run (targeted runs only); CI covers it.
- `tests/test_dashboard/test_live_feed.py` still has 2 failures, both
pre-existing and unrelated: those tests need a manually started proxy on
`:8787` with `--log-messages`, and `test_live_feed_button_exists`
asserts `is_visible()` with no wait for the `/stats` poll that flips
`log_full_messages`. The other 2 in that file pass against this change,
which is itself end-to-end evidence that Alpine and htmx work from the
vendored bundles.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

- No issue number: reported directly rather than filed, so `Closes #` is
omitted. Closed #22 ("Dashboard is not working") and closed #533
(Windows cp949 `get_dashboard_html()`) are different failures.
- **Docs checklist item is N/A** — nothing user-facing changes; the
dashboard URL and behaviour are identical.
- Deliberately **not** switching to a real Tailwind CLI build. It would
cut 407 KB to ~20 KB and silence the production warning, but it puts
Node in the release path and silently leaves any class added to the
2,713-line template unstyled with no CI guard. The Play bundle behaves
exactly as it does today, just served locally. Worth revisiting if wheel
size becomes a problem (note the PyPI project-size ceiling).
- Upgrades are now manual: bumping these three means re-downloading the
files. Pinned versions are recorded in `NOTICE`.
2026-08-03 06:07:27 -07:00
chopratejas 175746cc26 Prepare for OSS release v0.2.0
This commit prepares Headroom for public open source release with
comprehensive documentation, licensing, and community infrastructure.

License & Legal:
- Add Apache 2.0 LICENSE file
- Add NOTICE file with third-party attributions
- Add SECURITY.md for vulnerability reporting

Community:
- Add CONTRIBUTING.md with contribution guidelines
- Add CODE_OF_CONDUCT.md (Contributor Covenant)
- Add GitHub issue templates (bug report, feature request)
- Add pull request template

Documentation:
- Update README.md with compelling value proposition
- Add docs/getting-started.md
- Add docs/proxy.md for proxy server documentation
- Add docs/transforms.md for transform reference
- Add docs/api.md for API reference
- Add examples/README.md

Package Infrastructure:
- Add headroom/py.typed for PEP 561 compliance
- Add headroom/cli.py for CLI entry point
- Add .github/workflows/ci.yml for CI pipeline
- Add .github/workflows/publish.yml for PyPI publishing
- Update pyproject.toml with proper metadata

New Features:
- Add multi-provider support (Google, Cohere, LiteLLM, OpenAI-compatible)
- Add universal tokenizer registry with multiple backends
- Add model registry with pricing and context limits
- Add production proxy server with caching and rate limiting

Code Quality:
- Fix 83 lint issues via ruff auto-fix
- Fix version consistency (benchmarks 0.1.0 → 0.2.0)
- Add skip decorators for optional dependency tests
2026-01-07 11:36:44 -08:00