llming-stage 0.1.1__tar.gz

llming_stage-0.1.1/LICENSE

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

llming_stage-0.1.1/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: llming-stage
+Version: 0.1.1
+Summary: Shared frontend foundation and SPA app shell for the llming ecosystem — vendor JS, fonts, icons, and a lazy-loading client-side router
+License: MIT
+Keywords: spa,frontend,assets,vue,quasar,starlette,lazy-loading
+Author: Michael Ikemann
+Requires-Python: >=3.14,<4
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: llming-com (>=0.1.5,<0.2)
+Requires-Dist: starlette (>=0.27)
+Requires-Dist: uvicorn[standard] (>=0.27)
+Project-URL: Author, https://github.com/Alyxion
+Project-URL: Homepage, https://github.com/Alyxion/llming-stage
+Project-URL: Repository, https://github.com/Alyxion/llming-stage
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://raw.githubusercontent.com/Alyxion/llming-stage/main/media/logo-small.png" alt="LLMing Stage" width="400"></p>
+
+# llming-stage
+
+[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Alyxion/llming-stage/blob/main/LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/llming-stage.svg)](https://pypi.org/project/llming-stage/)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-purple.svg)](https://github.com/astral-sh/ruff)
+
+### Build Vue + Quasar UIs that AI can build, drive, and debug.
+
+`llming-stage` is the SPA foundation for AI-assisted frontend work. You write a real Vue + Quasar app, not a Python shim. Reactive traffic and sessions flow through [`llming-com`](https://github.com/Alyxion/llming-com), and that's the same channel an AI assistant uses to inspect state, invoke commands, and push events into the running page.
+
+```mermaid
+flowchart LR
+    User(["👤 User"]) --> Browser
+    AI(["🤖 AI assistant"]) <--> Com
+    Browser["<b>Browser</b><br/>Vue + Quasar SPA<br/>(llming-stage shell)"]
+    Com["<b>Python server</b><br/>llming-com<br/>sessions · auth · commands<br/>HTTP / MCP debug API"]
+    Browser <-->|"per-user WebSocket<br/>reactive commands · server pushes"| Com
+
+    classDef live fill:#1976d2,stroke:#1565c0,color:#fff,stroke-width:1.5px
+    classDef ai fill:#a855f7,stroke:#7c3aed,color:#fff,stroke-width:1.5px
+    class Browser,Com live
+    class AI ai
+```
+
+`llming-com` ships the sessions, auth, command dispatcher, and the debug surface — without it, the AI side of the picture goes away. When you eventually deploy and the app no longer needs server reactivity, the same shell + view modules can ship as a static bundle to any CDN.
+
+---
+
+### What you get
+
+- **An AI-debuggable runtime** — every reactive command, session, and event is browseable, invokable, and observable through one HTTP / MCP surface.
+- **FastAPI-native app mounting** — create your own `FastAPI()` app and attach `Stage(app)`, or let `Stage()` create the default FastAPI app for compact demos. The internal `/_stage` routes and development reload are ensured once; server startup stays normal FastAPI/ASGI (`uvicorn main:app --reload`, deployment servers, etc.).
+- **Modern frontend, zero boilerplate** — Vue 3 + Quasar 2 + bundled Tailwind utilities with a lazy-load orchestrator and an SPA router that keeps the WebSocket and view state alive across navigations.
+- **Per-user sessions out of the box** — `llming-com` runs the wire and the auth; you write JS views and Python handlers.
+- **Static-deployable** — when there's no server-side reactivity at runtime, the same code ships to GitHub Pages, S3, or any CDN.
+- **No third-party network** — every asset is vendored. A page loaded from an `llming-stage` app makes zero requests to Google Fonts, jsDelivr, or any other external host. Privacy/GDPR-friendly by default; enforced by static and runtime tests.
+
+---
+
+### See it in action
+
+```bash
+poetry install
+./samples/run.sh        # opens a web gallery at http://localhost:8000
+```
+
+Fourteen sample apps — from a tiny static app to generated decorator views, llming-com reactive loops, a Three.js particle tornado, an 8-chart ECharts dashboard, Plotly full-bundle charts, a core component workbench, and an optional-extension workbench — with dark/light theme, hot reload, and AI-debug control.
+
+---
+
+### Minimal app
+
+```python
+from llming_stage import Stage
+
+if __name__ == "__main__":
+    Stage(title="Hello world").add_view("/", "hello.vue").run()
+```
+
+```vue
+<template>
+  <main class="min-h-screen grid place-items-center p-8">
+    <h1 class="text-5xl font-bold">Hello llming-stage</h1>
+  </main>
+</template>
+```
+
+For a purely static app, no Python file is needed:
+
+```bash
+llming-stage serve hello.vue
+```
+
+`Stage()` mounts the bundled assets, the Vue + Quasar shell, the SPA
+router, bundled Tailwind utilities, and content-hash development reload
+by default.
+
+`stage.run()` is a thin local-development wrapper around `uvicorn.run`.
+If you need workers, custom logging, TLS, or deployment process
+management, run the same app directly with normal ASGI tooling.
+
+Reactive apps add a typed session router and let Stage mount the
+conventional session routes:
+
+```python
+from fastapi import FastAPI
+from llming_stage import Stage
+
+app = FastAPI()
+stage = Stage(app)
+sessions = stage.session()
+counter = sessions.add_router("counter")
+
+@counter.handler("inc")
+async def inc(session, by: int = 1):
+    value = int(session.state.get("count", 0)) + by
+    session.state["count"] = value
+    await session.call("home.setCounter", value)
+    return {"ok": True}
+
+stage.add_view("/", "home.vue")
+```
+
+The browser gets a real Vue + Quasar SPA from `.vue` view files.
+`llming-com` carries the wire, the sessions, and the debug surface the
+AI uses.
+
+---
+
+### Learn more
+
+Full docs in [`docs/content/`](docs/content):
+
+- [Quick start](docs/content/installation.md) · [Stage apps](docs/content/stage.md) · [App shell](docs/content/shell.md) · [Communication model](docs/content/communication-model.md)
+- [llming-com integration](docs/content/llming-com.md) · [Assets & lazy loading](docs/content/lazy-loading.md)
+- [Security](docs/content/security.md) · [API reference](docs/content/api.md)
+
+---
+
+MIT licensed. © 2026 [Michael Ikemann](https://github.com/Alyxion). Bundled third-party files are listed in [`THIRD_PARTY.md`](THIRD_PARTY.md); no AGPL/GPL/LGPL is ever permitted.
+

llming_stage-0.1.1/README.md

@@ -0,0 +1,123 @@
+<p align="center"><img src="https://raw.githubusercontent.com/Alyxion/llming-stage/main/media/logo-small.png" alt="LLMing Stage" width="400"></p>
+
+# llming-stage
+
+[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/Alyxion/llming-stage/blob/main/LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/llming-stage.svg)](https://pypi.org/project/llming-stage/)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-purple.svg)](https://github.com/astral-sh/ruff)
+
+### Build Vue + Quasar UIs that AI can build, drive, and debug.
+
+`llming-stage` is the SPA foundation for AI-assisted frontend work. You write a real Vue + Quasar app, not a Python shim. Reactive traffic and sessions flow through [`llming-com`](https://github.com/Alyxion/llming-com), and that's the same channel an AI assistant uses to inspect state, invoke commands, and push events into the running page.
+
+```mermaid
+flowchart LR
+    User(["👤 User"]) --> Browser
+    AI(["🤖 AI assistant"]) <--> Com
+    Browser["<b>Browser</b><br/>Vue + Quasar SPA<br/>(llming-stage shell)"]
+    Com["<b>Python server</b><br/>llming-com<br/>sessions · auth · commands<br/>HTTP / MCP debug API"]
+    Browser <-->|"per-user WebSocket<br/>reactive commands · server pushes"| Com
+
+    classDef live fill:#1976d2,stroke:#1565c0,color:#fff,stroke-width:1.5px
+    classDef ai fill:#a855f7,stroke:#7c3aed,color:#fff,stroke-width:1.5px
+    class Browser,Com live
+    class AI ai
+```
+
+`llming-com` ships the sessions, auth, command dispatcher, and the debug surface — without it, the AI side of the picture goes away. When you eventually deploy and the app no longer needs server reactivity, the same shell + view modules can ship as a static bundle to any CDN.
+
+---
+
+### What you get
+
+- **An AI-debuggable runtime** — every reactive command, session, and event is browseable, invokable, and observable through one HTTP / MCP surface.
+- **FastAPI-native app mounting** — create your own `FastAPI()` app and attach `Stage(app)`, or let `Stage()` create the default FastAPI app for compact demos. The internal `/_stage` routes and development reload are ensured once; server startup stays normal FastAPI/ASGI (`uvicorn main:app --reload`, deployment servers, etc.).
+- **Modern frontend, zero boilerplate** — Vue 3 + Quasar 2 + bundled Tailwind utilities with a lazy-load orchestrator and an SPA router that keeps the WebSocket and view state alive across navigations.
+- **Per-user sessions out of the box** — `llming-com` runs the wire and the auth; you write JS views and Python handlers.
+- **Static-deployable** — when there's no server-side reactivity at runtime, the same code ships to GitHub Pages, S3, or any CDN.
+- **No third-party network** — every asset is vendored. A page loaded from an `llming-stage` app makes zero requests to Google Fonts, jsDelivr, or any other external host. Privacy/GDPR-friendly by default; enforced by static and runtime tests.
+
+---
+
+### See it in action
+
+```bash
+poetry install
+./samples/run.sh        # opens a web gallery at http://localhost:8000
+```
+
+Fourteen sample apps — from a tiny static app to generated decorator views, llming-com reactive loops, a Three.js particle tornado, an 8-chart ECharts dashboard, Plotly full-bundle charts, a core component workbench, and an optional-extension workbench — with dark/light theme, hot reload, and AI-debug control.
+
+---
+
+### Minimal app
+
+```python
+from llming_stage import Stage
+
+if __name__ == "__main__":
+    Stage(title="Hello world").add_view("/", "hello.vue").run()
+```
+
+```vue
+<template>
+  <main class="min-h-screen grid place-items-center p-8">
+    <h1 class="text-5xl font-bold">Hello llming-stage</h1>
+  </main>
+</template>
+```
+
+For a purely static app, no Python file is needed:
+
+```bash
+llming-stage serve hello.vue
+```
+
+`Stage()` mounts the bundled assets, the Vue + Quasar shell, the SPA
+router, bundled Tailwind utilities, and content-hash development reload
+by default.
+
+`stage.run()` is a thin local-development wrapper around `uvicorn.run`.
+If you need workers, custom logging, TLS, or deployment process
+management, run the same app directly with normal ASGI tooling.
+
+Reactive apps add a typed session router and let Stage mount the
+conventional session routes:
+
+```python
+from fastapi import FastAPI
+from llming_stage import Stage
+
+app = FastAPI()
+stage = Stage(app)
+sessions = stage.session()
+counter = sessions.add_router("counter")
+
+@counter.handler("inc")
+async def inc(session, by: int = 1):
+    value = int(session.state.get("count", 0)) + by
+    session.state["count"] = value
+    await session.call("home.setCounter", value)
+    return {"ok": True}
+
+stage.add_view("/", "home.vue")
+```
+
+The browser gets a real Vue + Quasar SPA from `.vue` view files.
+`llming-com` carries the wire, the sessions, and the debug surface the
+AI uses.
+
+---
+
+### Learn more
+
+Full docs in [`docs/content/`](docs/content):
+
+- [Quick start](docs/content/installation.md) · [Stage apps](docs/content/stage.md) · [App shell](docs/content/shell.md) · [Communication model](docs/content/communication-model.md)
+- [llming-com integration](docs/content/llming-com.md) · [Assets & lazy loading](docs/content/lazy-loading.md)
+- [Security](docs/content/security.md) · [API reference](docs/content/api.md)
+
+---
+
+MIT licensed. © 2026 [Michael Ikemann](https://github.com/Alyxion). Bundled third-party files are listed in [`THIRD_PARTY.md`](THIRD_PARTY.md); no AGPL/GPL/LGPL is ever permitted.

llming_stage-0.1.1/THIRD_PARTY.md

@@ -0,0 +1,50 @@
+# Third-Party Resources
+
+All bundled third-party resources and their licenses. This file MUST be updated
+whenever a vendored file or asset is added, removed, or upgraded.
+
+No AGPL, GPL, or LGPL resource is ever permitted in this repository.
+
+## Vendor Libraries (`llming_stage/vendor/`)
+
+| Resource | Version | License | Source | Purpose |
+|----------|---------|---------|--------|---------|
+| Vue.js | 3.x | MIT | https://github.com/vuejs/core | Reactive UI framework |
+| Quasar Framework | 2.x | MIT | https://github.com/quasarframework/quasar | UI component library |
+| Tailwind CSS browser bundle | 4.2.4 | MIT | https://registry.npmjs.org/@tailwindcss/browser/-/browser-4.2.4.tgz (sha1 `e43e14e347d7b68a6c3afc7d77d8c18a335e98c3`) | Utility CSS runtime. The shell imports theme + utilities only, not preflight, to avoid global resets. |
+| Three.js | 0.184.0 | MIT | https://registry.npmjs.org/three/-/three-0.184.0.tgz (sha1 `5bca0a3851eea5345e4c205567b40dfa49b791b5`) | 3D rendering. Ships as two files — `three.module.min.js` re-exports from the co-located `three.core.min.js`; both are required. |
+| Three.js OrbitControls | 0.184.0 | MIT | `examples/jsm/controls/OrbitControls.js` from the same Three.js tarball | Mouse / touch / wheel camera controls (vendored as `three-orbit-controls.module.js`). |
+| Apache ECharts | 6.0.0 | Apache 2.0 | https://registry.npmjs.org/echarts/-/echarts-6.0.0.tgz (sha1 `2935aa7751c282d1abbbf7d719d397199a15b9e7`) | Chart library — line, bar, pie, gauge, radar, heatmap, scatter, candlestick. |
+| Plotly.js (basic) | 2.x | MIT | https://github.com/plotly/plotly.js | Charts and data visualization (lighter bundle — scatter, bar, pie). |
+| Plotly.js (full) | 3.5.0 | MIT | https://registry.npmjs.org/plotly.js-dist-min/-/plotly.js-dist-min-3.5.0.tgz (sha1 `d81d1c77dd93c927de2f84cdcd3f8697fb47583b`) | Full Plotly bundle — every chart type incl. heatmap, candlestick, choropleth. Loaded only when an app calls `__stage.load('plotly/full')`. |
+| KaTeX | 0.16.45 | MIT | https://registry.npmjs.org/katex/-/katex-0.16.45.tgz (sha1 `ba60d39c54746b6b8d39ce0e7f6eace07143149c`) | LaTeX math rendering. Ships `katex.min.{js,css}` plus 20 woff2 font files under `fonts/katex/` (CSS rewritten to `url(../fonts/katex/…)` so every font ends up under the unified `/_stage/fonts/` URL tree). |
+| Mermaid | 11.14.0 | MIT | https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz (sha1 `ce81b22bc10f3117ef7737406ef2d10ee1741769`) | Diagram rendering — UMD bundle (`mermaid.min.js`) so a single fetch covers every diagram type. |
+| marked | 18.0.2 | MIT | https://registry.npmjs.org/marked/-/marked-18.0.2.tgz (sha1 `180cb158a2d2dc377821cfb088a10ca1b5630ef0`) | Markdown parser (UMD). |
+| DOMPurify | 3.x | Apache 2.0 / MPL 2.0 | https://github.com/cure53/DOMPurify | HTML sanitization |
+| xterm.js | 6.0.0 | MIT | https://registry.npmjs.org/@xterm/xterm/-/xterm-6.0.0.tgz (sha1 `93637b0f2ee3a70718b5746a27c9c506af16745b`) | Terminal emulator. |
+| xterm.js fit addon | 0.11.0 | MIT | https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.11.0.tgz (sha1 `ba4778b69fcc9044a060c2176bbe077657d7b37e`) | Terminal autosize. |
+| xterm.js web-links addon | 0.12.0 | MIT | https://registry.npmjs.org/@xterm/addon-web-links/-/addon-web-links-0.12.0.tgz (sha1 `bc34ae46f4c12012256d451ac2b9be791c0b6bfa`) | Click-through URL detection. |
+| xterm.js webgl addon | 0.19.0 | MIT | https://registry.npmjs.org/@xterm/addon-webgl/-/addon-webgl-0.19.0.tgz (sha1 `02533c3f7c0af3ac9a44bbb095cbd47d48e90c25`) | GPU-accelerated terminal renderer. |
+| Drawflow | 0.0.60 | MIT | https://registry.npmjs.org/drawflow/-/drawflow-0.0.60.tgz (sha1 `313eadb43190a04ebba16d2cb49d1c9516030a15`) | Visual node-graph editor. |
+| CodeMirror 5 | 5.65.21 | MIT | https://registry.npmjs.org/codemirror/-/codemirror-5.65.21.tgz (sha1 `cacf320606c5450ad3b3da34bb9c666afec21068`) | In-browser code editor. Vendored files: `codemirror.{js,css}`, `codemirror-mode-javascript.js`, `codemirror-addon-matchbrackets.js`, `codemirror-addon-closebrackets.js`. |
+
+## Fonts (`llming_stage/fonts/`)
+
+| Resource | Version | License | Source | Purpose |
+|----------|---------|---------|--------|---------|
+| Roboto | 3.x | Apache 2.0 | https://github.com/googlefonts/roboto | Default UI font |
+| Material Icons | 4.x | Apache 2.0 | https://github.com/google/material-design-icons | UI icons (filled, outlined, round, sharp) |
+| Material Symbols | 1.x | Apache 2.0 | https://github.com/google/material-design-icons | UI icons (outlined, rounded, sharp) |
+
+## Icon & Emoji Sets (`llming_stage/assets/*.zip`)
+
+| Resource | Version | License | Source | Purpose |
+|----------|---------|---------|--------|---------|
+| Phosphor Icons | 2.x | MIT | https://github.com/phosphor-icons/core | UI icons (6 weights: bold, duotone, fill, light, regular, thin) |
+| Noto Emoji | 15.x | SIL OFL 1.1 / Apache 2.0 | https://github.com/googlefonts/noto-emoji | Emoji rendering |
+| Tabler Icons | 3.41.1 | MIT | https://registry.npmjs.org/@tabler/icons/-/icons-3.41.1.tgz (sha1 `dff9c77af287c73c2fcab4074cfa9f2069f9b7ee`) | UI icons (~6 000 SVGs, outline + filled). Served via `tabler-icons.zip` at `/_stage/tabler/<style>/<name>.svg`. |
+
+## Quasar Locale Packs (`llming_stage/lang/`)
+
+Bundled with Quasar — MIT licensed, sourced from the Quasar distribution
+(https://github.com/quasarframework/quasar).

llming_stage-0.1.1/llming_stage/__init__.py

@@ -0,0 +1,34 @@
+"""llming-stage — shared frontend foundation and SPA app shell.
+
+Public API:
+    - :func:`mount_assets` — attach path-hardened asset routes to any
+      Starlette/FastAPI app.
+    - :func:`mount_shell` — serve the SPA shell HTML document.
+    - :func:`mount_dev_reload` — attach development-only reload routes.
+    - :class:`Stage` — OOP helper for FastAPI-native stage apps.
+    - :class:`StageSession` — Stage-owned llming-com session wiring.
+    - :class:`VueResponse` — response type for generated Vue views.
+    - :class:`ShellConfig` — configuration dataclass for the shell.
+    - :func:`render_shell` — render the shell HTML (for custom wiring).
+"""
+
+from __future__ import annotations
+
+from .dev_reload import DevReloadConfig, dev_reload_head, mount_dev_reload
+from .shell import ShellConfig, mount_assets, mount_shell, render_shell
+from .stage import Stage, StageSession, VueResponse
+
+__all__ = [
+    "DevReloadConfig",
+    "Stage",
+    "StageSession",
+    "ShellConfig",
+    "VueResponse",
+    "dev_reload_head",
+    "mount_assets",
+    "mount_dev_reload",
+    "mount_shell",
+    "render_shell",
+]
+
+__version__ = "0.1.0"

llming_stage-0.1.1/llming_stage/asset_server.py

@@ -0,0 +1,131 @@
+"""Path-hardened static asset serving.
+
+Each asset group (vendor, fonts, lang) is a separate whitelist-scoped
+handler. No generic file serving, no catch-all static mount.
+
+Security guarantees
+-------------------
+1. **Whitelist-only routing** — each route maps to one fixed root directory.
+2. **Path canonicalization** — requested paths are resolved against the root;
+   requests that escape the root (via ``..``, absolute paths, or symlinks)
+   return 403/404.
+3. **Dangerous pattern rejection** — ``..``, backslashes, null bytes, and
+   non-ASCII control characters are rejected before the filesystem is touched.
+4. **Extension whitelist** — only ``.js``, ``.css``, ``.woff2``, ``.svg``,
+   ``.json``, ``.mjs`` are served. Anything else is 404.
+5. **No directory listing** — directory requests return 404.
+6. **Symlink rejection** — any path component that is a symlink pointing
+   outside the root is rejected.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+from pathlib import Path
+
+from starlette.requests import Request
+from starlette.responses import FileResponse, Response
+
+ALLOWED_EXTENSIONS: frozenset[str] = frozenset(
+    {".js", ".mjs", ".css", ".woff2", ".svg", ".json"}
+)
+
+_MIME_OVERRIDES: dict[str, str] = {
+    ".js": "application/javascript; charset=utf-8",
+    ".mjs": "application/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".woff2": "font/woff2",
+    ".svg": "image/svg+xml; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+}
+
+_FORBIDDEN_SUBSTRINGS: tuple[str, ...] = ("..", "\\", "\x00")
+
+
+def validate_relative_path(path: str) -> str | None:
+    """Return the cleaned path, or ``None`` if the input is unsafe.
+
+    Applies only textual checks — the caller must still resolve against a
+    root and verify containment (see :func:`resolve_under_root`).
+    """
+    if not path:
+        return None
+    if path.startswith("/"):
+        return None
+    for bad in _FORBIDDEN_SUBSTRINGS:
+        if bad in path:
+            return None
+    for ch in path:
+        code = ord(ch)
+        if code < 0x20 or code == 0x7F:
+            return None
+    for segment in path.split("/"):
+        if not segment or segment in (".", ".."):
+            return None
+    return path
+
+
+def resolve_under_root(root: Path, rel: str) -> Path | None:
+    """Resolve *rel* against *root*, ensuring the result stays inside.
+
+    Returns ``None`` if containment cannot be verified, if any component
+    is a symlink pointing outside *root*, or if the resolved path does not
+    exist as a regular file.
+    """
+    root_resolved = root.resolve(strict=True)
+    candidate = (root_resolved / rel).resolve(strict=False)
+    try:
+        candidate.relative_to(root_resolved)
+    except ValueError:
+        return None
+    if not candidate.exists():
+        return None
+    if not candidate.is_file():
+        return None
+    current = root_resolved
+    for part in Path(rel).parts:
+        current = current / part
+        try:
+            if current.is_symlink():
+                real = current.resolve(strict=True)
+                real.relative_to(root_resolved)
+        except (OSError, ValueError):
+            return None
+    return candidate
+
+
+def _media_type_for(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix in _MIME_OVERRIDES:
+        return _MIME_OVERRIDES[suffix]
+    guessed, _ = mimetypes.guess_type(path.name)
+    return guessed or "application/octet-stream"
+
+
+def make_dir_handler(root: Path, cache_max_age: int = 31536000):
+    """Build an async Starlette handler that serves files under *root*.
+
+    The handler reads the relative path from the ``path`` route parameter,
+    validates it, resolves it under *root*, and returns the file — or 404
+    on any failure. Never returns 403: "not found" is the single observable
+    outcome for every rejection path, to avoid leaking structure.
+    """
+    root = root.resolve(strict=True)
+    cache_control = f"public, max-age={cache_max_age}, immutable"
+
+    async def handler(request: Request) -> Response:
+        rel = validate_relative_path(request.path_params.get("path", ""))
+        if rel is None:
+            return Response(status_code=404)
+        if Path(rel).suffix.lower() not in ALLOWED_EXTENSIONS:
+            return Response(status_code=404)
+        resolved = resolve_under_root(root, rel)
+        if resolved is None:
+            return Response(status_code=404)
+        return FileResponse(
+            resolved,
+            media_type=_media_type_for(resolved),
+            headers={"Cache-Control": cache_control},
+        )
+
+    return handler

llming_stage-0.1.1/llming_stage/cli.py

@@ -0,0 +1,76 @@
+"""Command line tools for no-Python llming-stage apps."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .stage import Stage
+
+_VIEW_EXTENSIONS = {".vue", ".html", ".htm", ".js"}
+
+def build_app(root: Path, *, dev: bool = True):
+    title = _title_for_root(root)
+    if root.is_file():
+        stage = Stage(root=root.parent, title=title, dev=dev)
+        stage.add_view("/", root)
+        return stage.app
+
+    views = root / "views"
+    stage = Stage(root=root, title=title, dev=dev)
+    if views.is_dir():
+        stage.discover(views)
+        return stage.app
+
+    view_files = sorted(
+        path
+        for path in root.rglob("*")
+        if path.is_file() and path.suffix.lower() in _VIEW_EXTENSIONS
+    )
+    if len(view_files) == 1:
+        stage.add_view("/", view_files[0])
+    else:
+        stage.discover(root)
+    return stage.app
+
+
+def _title_for_root(root: Path) -> str:
+    raw = root.stem if root.is_file() else root.name
+    text = raw.replace("_", " ").replace("-", " ").strip()
+    return text[:1].upper() + text[1:] if text else "llming"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="llming-stage")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    serve = sub.add_parser("serve", help="serve a no-Python stage app")
+    serve.add_argument("root", nargs="?", default=".")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8765)
+
+    build = sub.add_parser("build", help="build a static no-Python stage app")
+    build.add_argument("root", nargs="?", default=".")
+    build.add_argument("--out", default="dist")
+
+    args = parser.parse_args(argv)
+    root = Path(args.root).resolve()
+
+    if args.cmd == "serve":
+        try:
+            import uvicorn
+        except ImportError as exc:
+            raise SystemExit(
+                "llming-stage serve requires uvicorn. Install it with `pip install uvicorn`."
+            ) from exc
+        uvicorn.run(build_app(root, dev=True), host=args.host, port=args.port)
+        return 0
+
+    app = build_app(root, dev=False)
+    stage = getattr(app.state, "llming_stage_instance")
+    stage.build(Path(args.out))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())