curvature 0.1.0__tar.gz

curvature-0.1.0/LICENSE

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

curvature-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: curvature
+Version: 0.1.0
+Summary: A web framework for code that agents maintain. The right path is free fall.
+Keywords: web,framework,agents,progressive-enhancement,server-rendered,htmx-alternative
+Author: Robert Sharp
+Author-email: Robert Sharp <webmaster@sharpdesigndigital.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: pydantic>=2.11
+Requires-Dist: starlette>=0.47
+Requires-Dist: fastapi>=0.115 ; extra == 'fastapi'
+Requires-Dist: python-multipart>=0.0.20 ; extra == 'fastapi'
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/siliconsociety/Curvature
+Project-URL: Issues, https://github.com/siliconsociety/Curvature/issues
+Project-URL: Repository, https://github.com/siliconsociety/Curvature
+Provides-Extra: fastapi
+Description-Content-Type: text/markdown
+
+# Curvature
+
+*The right path is free fall.*
+
+A web framework for code that agents maintain. Server-rendered Python,
+components as typed functions, real links and real forms, one small
+boost script for the single-page feel — and a gate that makes the
+maintainable path the only path that builds.
+
+Curvature's design center is the maintainer nobody watches: the coding
+agent in its forty-third session, at 2 a.m., doing whatever the shape of
+the code suggests. Frameworks built for humans enforce their discipline
+through culture. Curvature's discipline is machine-checked — every
+invariant in [SPEC.md](https://github.com/siliconsociety/Curvature/blob/main/SPEC.md) names the check that enforces it, and
+violations are reported by `curvature check` as **anomalies** — regions where the geometry failed to steer.
+The canonical documentation is [AGENTS.md](https://github.com/siliconsociety/Curvature/blob/main/AGENTS.md); this README is
+the courtesy translation. The argument for all of it is the
+[MANIFESTO](https://github.com/siliconsociety/Curvature/blob/main/MANIFESTO.md).
+
+## The shape of it
+
+```python
+from curvature import Element, Props, redirect, respond
+from curvature import html as h
+
+
+class LapProps(Props):
+    title: str
+    done: bool
+
+
+def lap(props: LapProps) -> Element:
+    return h.li(props.title, class_="lap done" if props.done else "lap", id="lap")
+```
+
+- **Components** are functions of frozen, closed pydantic props. The UI
+  is just Python: typed by pyright, measured by coverage, tested by
+  pytest without a browser in sight.
+- **The app works with JavaScript off.** Reads render full pages; writes
+  are POST → redirect → GET through real forms. Your test suite drives
+  it with httpx — which executes no JS — so the degraded path is the
+  tested path, permanently.
+- **curvature.js** (the only script, held under a 150-line ratcheted ceiling) boosts working links and
+  forms into fragment swaps. Same route, same render, one header of
+  difference. Every failure path is real navigation.
+- **The ratchet only tightens.** File ceilings fall, the coverage floor
+  rises, and `curvature ratchet` is the only hand on the mechanism. The
+  10,000-line file is never written because week two's gate refuses the
+  sediment while the split is still cheap.
+
+## Start from nothing
+
+```bash
+uvx curvature new app pitstop     # no install, no venv, no Python even — uv brings it
+cd pitstop
+./gate.sh                      # green before you write a line
+./run.sh                       # http://127.0.0.1:8000
+```
+
+Only have pip? `pip install curvature && python -m curvature new app pitstop`
+— the `python -m` form dodges PATH entirely; the poured README carries
+the rest of the old ritual. 
+
+Onboarding an agent takes zero steps: the scaffold poured AGENTS.md,
+the gate, and one example component as the pattern. Point your agent at
+the directory and ask for a feature — the repo is the prompt.
+
+## The demo
+
+PyPI ships the framework; the repo ships Pit Board, the demo:
+
+```bash
+git clone https://github.com/siliconsociety/Curvature && cd Curvature
+uv sync && ./gate.sh
+uv run uvicorn demo.app:app --reload   # Pit Board
+```
+
+Then turn JavaScript off and use it again. Nothing changes. That is the
+whole point.
+
+## Status
+
+Day one (2026-07-11). The contract, runtime, gate, and demo are real and
+self-hosting — this repo passes its own gate. The spec is versioned and
+arguable; argue by issue.
+
+MIT. Built by Robert Sharp, with Claude Fable 5 on its last day on the
+subscription — read the manifesto and you'll see why that detail
+belongs in a README.

curvature-0.1.0/README.md

@@ -0,0 +1,89 @@
+# Curvature
+
+*The right path is free fall.*
+
+A web framework for code that agents maintain. Server-rendered Python,
+components as typed functions, real links and real forms, one small
+boost script for the single-page feel — and a gate that makes the
+maintainable path the only path that builds.
+
+Curvature's design center is the maintainer nobody watches: the coding
+agent in its forty-third session, at 2 a.m., doing whatever the shape of
+the code suggests. Frameworks built for humans enforce their discipline
+through culture. Curvature's discipline is machine-checked — every
+invariant in [SPEC.md](https://github.com/siliconsociety/Curvature/blob/main/SPEC.md) names the check that enforces it, and
+violations are reported by `curvature check` as **anomalies** — regions where the geometry failed to steer.
+The canonical documentation is [AGENTS.md](https://github.com/siliconsociety/Curvature/blob/main/AGENTS.md); this README is
+the courtesy translation. The argument for all of it is the
+[MANIFESTO](https://github.com/siliconsociety/Curvature/blob/main/MANIFESTO.md).
+
+## The shape of it
+
+```python
+from curvature import Element, Props, redirect, respond
+from curvature import html as h
+
+
+class LapProps(Props):
+    title: str
+    done: bool
+
+
+def lap(props: LapProps) -> Element:
+    return h.li(props.title, class_="lap done" if props.done else "lap", id="lap")
+```
+
+- **Components** are functions of frozen, closed pydantic props. The UI
+  is just Python: typed by pyright, measured by coverage, tested by
+  pytest without a browser in sight.
+- **The app works with JavaScript off.** Reads render full pages; writes
+  are POST → redirect → GET through real forms. Your test suite drives
+  it with httpx — which executes no JS — so the degraded path is the
+  tested path, permanently.
+- **curvature.js** (the only script, held under a 150-line ratcheted ceiling) boosts working links and
+  forms into fragment swaps. Same route, same render, one header of
+  difference. Every failure path is real navigation.
+- **The ratchet only tightens.** File ceilings fall, the coverage floor
+  rises, and `curvature ratchet` is the only hand on the mechanism. The
+  10,000-line file is never written because week two's gate refuses the
+  sediment while the split is still cheap.
+
+## Start from nothing
+
+```bash
+uvx curvature new app pitstop     # no install, no venv, no Python even — uv brings it
+cd pitstop
+./gate.sh                      # green before you write a line
+./run.sh                       # http://127.0.0.1:8000
+```
+
+Only have pip? `pip install curvature && python -m curvature new app pitstop`
+— the `python -m` form dodges PATH entirely; the poured README carries
+the rest of the old ritual. 
+
+Onboarding an agent takes zero steps: the scaffold poured AGENTS.md,
+the gate, and one example component as the pattern. Point your agent at
+the directory and ask for a feature — the repo is the prompt.
+
+## The demo
+
+PyPI ships the framework; the repo ships Pit Board, the demo:
+
+```bash
+git clone https://github.com/siliconsociety/Curvature && cd Curvature
+uv sync && ./gate.sh
+uv run uvicorn demo.app:app --reload   # Pit Board
+```
+
+Then turn JavaScript off and use it again. Nothing changes. That is the
+whole point.
+
+## Status
+
+Day one (2026-07-11). The contract, runtime, gate, and demo are real and
+self-hosting — this repo passes its own gate. The spec is versioned and
+arguable; argue by issue.
+
+MIT. Built by Robert Sharp, with Claude Fable 5 on its last day on the
+subscription — read the manifesto and you'll see why that detail
+belongs in a README.

curvature-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "curvature"
+version = "0.1.0"
+description = "A web framework for code that agents maintain. The right path is free fall."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Robert Sharp", email = "webmaster@sharpdesigndigital.com" },
+]
+requires-python = ">=3.14"
+keywords = ["web", "framework", "agents", "progressive-enhancement", "server-rendered", "htmx-alternative"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    "pydantic>=2.11",
+    "starlette>=0.47",
+]
+
+[project.urls]
+Homepage = "https://github.com/siliconsociety/Curvature"
+Repository = "https://github.com/siliconsociety/Curvature"
+Issues = "https://github.com/siliconsociety/Curvature/issues"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.115", "python-multipart>=0.0.20"]
+
+[project.scripts]
+curvature = "curvature.gate.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "pytest-cov>=7.0",
+    "ruff>=0.14",
+    "fastapi>=0.115",
+    "python-multipart>=0.0.20",
+    "httpx>=0.28",
+    "uvicorn>=0.35",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.11,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.coverage.run]
+source = ["src/curvature"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true

curvature-0.1.0/src/curvature/__init__.py

@@ -0,0 +1,24 @@
+"""Curvature — a web framework for code that agents maintain.
+
+The contract pieces live here. The HTML vocabulary is deliberately a
+separate import (`from curvature import html as h`) so markup reads as
+markup at every call site.
+"""
+
+from curvature.component import Props
+from curvature.errors import Anomaly
+from curvature.fragments import BOOST_HEADER, is_boosted, redirect, respond
+from curvature.html import Element, element, raw, render
+
+__all__ = [
+    "BOOST_HEADER",
+    "Element",
+    "Anomaly",
+    "Props",
+    "element",
+    "is_boosted",
+    "raw",
+    "redirect",
+    "render",
+    "respond",
+]

curvature-0.1.0/src/curvature/__main__.py

@@ -0,0 +1,7 @@
+"""python -m curvature — the PATH-proof front door."""
+
+import sys
+
+from curvature.gate.cli import main
+
+sys.exit(main())

curvature-0.1.0/src/curvature/component.py

@@ -0,0 +1,21 @@
+"""Components are functions of props (C-100, C-101).
+
+A component is a plain function: it takes one Props subclass and returns
+an Element. No base class to extend, no registry to join, no decorator to
+remember. The contract is the signature, and the gate reads signatures.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Props(BaseModel):
+    """The explicit interface of a component.
+
+    Frozen: a component cannot mutate its inputs. Closed: a typo'd or
+    surplus prop fails loudly at the call site (C-101). Both are
+    inherited; subclasses just declare fields.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")

curvature-0.1.0/src/curvature/errors.py

@@ -0,0 +1,7 @@
+class Anomaly(Exception):
+    """The construction-grade refusal (SPEC.md enforcement grade 1).
+
+    Raised when code tries to build something the contract forbids —
+    an href="#", an inline script body, a fragment root without an id.
+    The message always names the invariant so the traceback teaches.
+    """

curvature-0.1.0/src/curvature/fragments.py

@@ -0,0 +1,54 @@
+"""The boost protocol, server side (C-500, C-501, C-103).
+
+One header decides everything. A boosted request gets the identified
+subtrees; a plain request gets the full document wrapped by the shell.
+Both come from the same render, so there is nothing to drift.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, RedirectResponse
+
+from curvature.errors import Anomaly
+from curvature.html import Element, render
+
+BOOST_HEADER = "curvature-boost"
+
+
+def is_boosted(request: Request) -> bool:
+    return request.headers.get(BOOST_HEADER) == "1"
+
+
+def respond(
+    request: Request,
+    *fragments: Element,
+    shell: Callable[..., Element],
+    status_code: int = 200,
+) -> HTMLResponse:
+    """Answer a view with fragments or the full page — same tree either way.
+
+    Every fragment root must carry an id (C-501): the boost layer swaps by
+    id, and an anonymous fragment would strand the client. The shell is a
+    callable receiving the fragments and returning the full document; it
+    runs only for unboosted requests.
+    """
+    for fragment in fragments:
+        if fragment.id is None:
+            raise Anomaly(
+                f"fragment root <{fragment.tag}> has no id (C-501): the boost "
+                "layer swaps subtrees by id; give the root a stable identity"
+            )
+    headers = {"vary": "Curvature-Boost"}
+    if is_boosted(request):
+        markup = "".join(render(fragment) for fragment in fragments)
+        return HTMLResponse(markup, status_code=status_code, headers=headers)
+    return HTMLResponse(render(shell(*fragments)), status_code=status_code, headers=headers)
+
+
+def redirect(url: str, *, status_code: int = 303) -> RedirectResponse:
+    """POST -> redirect -> GET (C-201). 303 turns any verb into a GET, which
+    is exactly the promise a mutation makes about its after-state."""
+    return RedirectResponse(url, status_code=status_code)

curvature-0.1.0/src/curvature/gate/checks.py

@@ -0,0 +1,228 @@
+"""The anomaly checks. One function per rule; each returns findings.
+
+These are deliberately unclever. A check an agent cannot predict is a
+check an agent cannot steer by; boring, greppable rules are the product.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+from curvature.gate.findings import Finding, is_boost_layer, is_vendored, walk_source
+from curvature.gate.ratchet import Ratchet, loosened, previous_committed
+
+HTTP_TOKENS = ("fetch(", "XMLHttpRequest", "WebSocket(", "EventSource(")
+MUTATING_VERBS = frozenset({"post", "put", "delete", "patch"})
+JSON_ESCAPE_HATCH = "# curvature: json-endpoint"
+ALLOW_PRAGMA = "curvature-allow"
+
+
+def _allowed(line: str) -> bool:
+    """Token checks honor an explicit, greppable pragma. Enforcement code
+    and tests that exercise refusals need to spell the forbidden words;
+    the pragma is counted (see cli info lines) so it cannot hide."""
+    return ALLOW_PRAGMA in line
+
+
+def check_ceilings(root: Path, ratchet: Ratchet) -> list[Finding]:
+    """ANOM-140: no file outgrows its ceiling. Split while the split is cheap."""
+    findings = []
+    for path in walk_source(root, frozenset({".py", ".css", ".js"})):
+        if is_vendored(path):
+            continue
+        relpath = str(path.relative_to(root))
+        ceiling = ratchet.ceiling_for(path, relpath)
+        if ceiling is None:
+            continue
+        lines = len(path.read_text(errors="replace").splitlines())
+        if lines > ceiling:
+            findings.append(Finding(
+                "ANOM-140", relpath, None,
+                f"{lines} lines against a ceiling of {ceiling}; split it (C-400)",
+            ))
+    return findings
+
+
+def check_js_placement(root: Path) -> list[Finding]:
+    """ANOM-120: the only first-party script is the boost layer (C-300)."""
+    findings = []
+    for path in walk_source(root, frozenset({".js"})):
+        if is_vendored(path) or is_boost_layer(path):
+            continue
+        findings.append(Finding(
+            "ANOM-120", str(path.relative_to(root)), None,
+            "first-party JavaScript outside the boost layer (C-300); "
+            "move the behavior server-side or into native HTML",
+        ))
+    return findings
+
+
+def check_js_http(root: Path) -> list[Finding]:
+    """ANOM-121: JavaScript never speaks HTTP on its own (C-301)."""
+    findings = []
+    for path in walk_source(root, frozenset({".js"})):
+        if is_vendored(path) or is_boost_layer(path):
+            continue
+        for number, line in enumerate(path.read_text(errors="replace").splitlines(), 1):
+            if _allowed(line):
+                continue
+            for token in HTTP_TOKENS:
+                if token in line:
+                    findings.append(Finding(
+                        "ANOM-121", str(path.relative_to(root)), number,
+                        f"{token.rstrip('(')} outside the boost layer (C-301)",
+                    ))
+    return findings
+
+
+def check_dom_sins(root: Path) -> list[Finding]:
+    """ANOM-130: no click handlers in attributes, no script-scheme URLs (C-200)."""
+    findings = []
+    for path in walk_source(root, frozenset({".py", ".html"})):
+        relpath = str(path.relative_to(root))
+        for number, line in enumerate(path.read_text(errors="replace").splitlines(), 1):
+            if _allowed(line):
+                continue
+            if "onclick" in line.casefold():  # curvature-allow: enforcement
+                findings.append(Finding(
+                    "ANOM-130", relpath, number,
+                    "a click handler is a behavior with no URL (C-200); use a form",
+                ))
+            if "javascript:" in line.casefold():  # curvature-allow: enforcement
+                message = "javascript: URL (C-200)"  # curvature-allow: message
+                findings.append(Finding("ANOM-130", relpath, number, message))
+    return findings
+
+
+def _returns_element(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    match node.returns:
+        case ast.Name(id="Element"):
+            return True
+        case ast.Attribute(attr="Element"):
+            return True
+    return False
+
+
+def check_component_signatures(root: Path) -> list[Finding]:
+    """ANOM-110: in components/ trees, Element-returning functions take Props
+    first (C-100). Zero-positional combinators (shells) are composition,
+    not components, and pass."""
+    findings = []
+    for path in walk_source(root, frozenset({".py"})):
+        if "components" not in path.parts:
+            continue
+        tree = ast.parse(path.read_text(), filename=str(path))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                continue
+            if not _returns_element(node) or not node.args.args:
+                continue
+            annotation = node.args.args[0].annotation
+            name = ""
+            match annotation:
+                case ast.Name(id=id_):
+                    name = id_
+                case ast.Attribute(attr=attr):
+                    name = attr
+            if not name.endswith("Props"):
+                findings.append(Finding(
+                    "ANOM-110", str(path.relative_to(root)), node.lineno,
+                    f"component {node.name}() must take a Props model first (C-100); "
+                    f"got {name or 'no annotation'}",
+                ))
+    return findings
+
+
+def _decorator_verb(decorator: ast.expr) -> str | None:
+    match decorator:
+        case ast.Call(func=ast.Attribute(attr=attr)) if attr in MUTATING_VERBS:
+            return attr
+    return None
+
+
+def check_mutating_routes(root: Path) -> list[Finding]:
+    """ANOM-131: mutating routes redirect; they never render (C-201)."""
+    findings = []
+    for path in walk_source(root, frozenset({".py"})):
+        source = path.read_text()
+        tree = ast.parse(source, filename=str(path))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                continue
+            verb = next(
+                (v for d in node.decorator_list if (v := _decorator_verb(d))), None
+            )
+            if verb is None:
+                continue
+            segment = ast.get_source_segment(source, node) or ""
+            if JSON_ESCAPE_HATCH in segment:
+                continue
+            returns = [
+                n.value for n in ast.walk(node)
+                if isinstance(n, ast.Return) and n.value is not None
+            ]
+            redirects = sum(
+                isinstance(r, ast.Call)
+                and (
+                    (isinstance(r.func, ast.Name) and r.func.id == "redirect")
+                    or (isinstance(r.func, ast.Attribute) and r.func.attr == "redirect")
+                )
+                for r in returns
+            )
+            if redirects == 0 or redirects < len(returns):
+                findings.append(Finding(
+                    "ANOM-131", str(path.relative_to(root)), node.lineno,
+                    f"{verb.upper()} route {node.name}() must return redirect() on "
+                    f"every path (C-201), or carry '{JSON_ESCAPE_HATCH}'",
+                ))
+    return findings
+
+
+def check_coverage(root: Path, ratchet: Ratchet) -> list[Finding]:
+    """ANOM-141: the coverage floor holds (C-401)."""
+    if ratchet.coverage_floor <= 0:
+        return []
+    report = root / "coverage.json"
+    if not report.exists():
+        return [Finding(
+            "ANOM-141", "coverage.json", None,
+            f"floor is {ratchet.coverage_floor} but no coverage report exists; "
+            "run pytest --cov --cov-report=json first (C-401)",
+        )]
+    percent = json.loads(report.read_text())["totals"]["percent_covered"]
+    if percent < ratchet.coverage_floor:
+        return [Finding(
+            "ANOM-141", "coverage.json", None,
+            f"coverage {percent:.2f} is under the floor {ratchet.coverage_floor} (C-401)",
+        )]
+    return []
+
+
+def check_ratchet_integrity(root: Path, ratchet: Ratchet) -> list[Finding]:
+    """ANOM-142: nothing loosened since the last commit (C-402)."""
+    committed = previous_committed(root)
+    if committed is None:
+        return []
+    return [
+        Finding("ANOM-142", "ratchet.toml", None, f"{complaint} (C-402)")
+        for complaint in loosened(ratchet, committed)
+    ]
+
+
+def raw_census(root: Path) -> int:
+    """ANOM-122: how many places admit unescaped markup. Informational."""
+    count = 0
+    for path in walk_source(root, frozenset({".py"})):
+        count += path.read_text(errors="replace").count("raw(")
+    return count
+
+
+def pragma_census(root: Path) -> int:
+    """Every curvature-allow pragma in the project. Informational: the escape
+    hatch stays visible so it can be argued about in review."""
+    count = 0
+    for path in walk_source(root, frozenset({".py", ".js", ".html"})):
+        count += path.read_text(errors="replace").count(ALLOW_PRAGMA)
+    return count