thea-software 3.53.0__py3-none-any.whl

atlas_cli.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""The installable entry point: resolve WHICH atlas, then run the contract's own CLI against it.
+
+A SEPARATE MODULE (2.11.0) because `atlascore` fixes the root at IMPORT time: this resolves it first,
+exports it, then imports the harness. IT PRINTS THE RULE THAT DECIDED THE ROOT: an explicit flag and
+a lucky fall-through are the same answer with very different trust. A CONSUMER PINS A REF, NEVER
+`main`, in `.atlas.yaml`, so the pin is reviewed in its own diff.
+WITH NO ROOT AND NO CHECKOUT (3.53.0) it fetches its own version's release, sha256-checked; else refuses.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import re
+import shutil
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+
+import yaml
+
+CONSUMER_CONFIG = ".atlas.yaml"
+FLAG = "--atlas-root"
+RELEASES = "https://github.com/HLIntel/thea-software/releases/download"
+INSTALLED_FROM = "the checkout this entry point was installed from"
+MARKER = ".thea-release.sha256"  # written last: an unmarked cache is never used
+# REFUSE RATHER THAN INVENT (3.47.0): a key not known by name is refused at its file:line.
+SECTIONS, PIN = ("atlas", "stack_tiers", "markdown_policy"), ("ref", "root", "task", "change_class", "process")
+
+
+class ConfigError(ValueError):
+    """A root flag or consumer config this entry point refuses to guess about."""
+
+
+def _keys(path: Path, node, what: str, allowed=()) -> dict:
+    if not isinstance(node, yaml.MappingNode):
+        raise ConfigError(f"{path}:{node.start_mark.line + 1}: {what} must be a mapping")
+    out = {}
+    for key, value in node.value:
+        name, line = key.value, key.start_mark.line + 1
+        if not isinstance(name, str) or name in out or allowed and name not in allowed:
+            raise ConfigError(f"{path}:{line}: bad or repeated key {name!r} in {what}; allowed: {allowed}")
+        out[name] = value
+    return out
+
+
+def _pin(path: Path) -> dict[str, str]:
+    """The `atlas:` mapping of one config file, every key checked by name."""
+    try:
+        doc = yaml.compose(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        raise ConfigError(f"{path}:{mark.line + 1 if mark else 1}: not parseable YAML") from None
+    sections = _keys(path, doc, CONSUMER_CONFIG, SECTIONS) if doc else {}
+    pins = {name: _keys(path, node, name) for name, node in sections.items()}.get("atlas", {})
+    for name, value in pins.items():
+        if name not in PIN or value.tag != "tag:yaml.org,2002:str" or not value.value.strip():
+            raise ConfigError(f"{path}:{value.start_mark.line + 1}: atlas.{name}: want a string in {PIN}")
+    return {name: value.value for name, value in pins.items()}
+
+
+def _config(start: Path) -> tuple[dict, Path | None]:
+    """The pin of the nearest .atlas.yaml at or above `start`; ConfigError on any doubt."""
+    for path in (d / CONSUMER_CONFIG for d in [start, *start.parents]):
+        if path.exists():
+            return _pin(path), path
+    return {}, None
+
+
+def root_flag(argv: list[str]) -> tuple[str | None, int, int]:
+    """(value, index, width) of the root flag, or (None, -1, 0); refused with no value (3.47.0)."""
+    hits = [i for i, arg in enumerate(argv) if arg == FLAG or arg.startswith(FLAG + "=")]
+    if not hits:
+        return None, -1, 0
+    i, eq = hits[0], argv[hits[0]] != FLAG
+    value = argv[i].partition("=")[2] if eq else (argv[i + 1 :] or [""])[0]
+    if len(hits) > 1 or not value.strip() or value.startswith("-") and not eq:
+        raise ConfigError(f"{FLAG} needs one directory, given once; got {value!r}")
+    return value, i, 1 if eq else 2
+
+
+def resolve_root(argv: list[str], cwd: Path) -> tuple[Path, str]:
+    """The atlas this invocation runs against, and the rule that decided it. In declared order."""
+    value = root_flag(argv)[0]
+    if value is not None:
+        return Path(value).expanduser().resolve(), f"explicit {FLAG}"
+    for var in ("THEA_ROOT", "CODE_DEVELOPMENT_ROOT"):  # the second is the pre-3.0 name, still honoured
+        if os.environ.get(var):
+            return Path(os.environ[var]).resolve(), f"{var} in the environment"
+    config, where = _config(cwd)
+    if config.get("root"):
+        base = (where.parent / config["root"]).resolve()
+        return base, f"root declared in {where.name} (ref {config.get('ref', 'unpinned')})"
+    return Path(__file__).resolve().parents[1], INSTALLED_FROM
+
+
+class FetchError(RuntimeError):
+    """A release atlas refused: unreachable, unverified, or another version."""
+
+
+def _get(url: str) -> bytes:
+    import urllib.request  # noqa: PLC0415
+
+    try:
+        with urllib.request.urlopen(url, timeout=60) as r:  # noqa: S310 — a fixed https base
+            return r.read()
+    except (OSError, ValueError) as exc:
+        raise FetchError(f"cannot download {url}: {exc}") from None
+
+
+def fetch_atlas(version: str) -> Path:
+    """Release v<version>'s tree, cached or downloaded and sha256-checked; else FetchError."""
+    dest = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache", "thea", f"atlas-{version}")
+    if (dest / MARKER).is_file():
+        return dest
+    name = f"thea-v{version}.tar.gz"
+    url = f"{RELEASES}/v{version}/{name}"
+    want = re.findall(
+        rf"^([0-9a-f]{{64}}) [ *]{re.escape(name)}$", _get(url + ".sha256").decode(errors="replace"), re.M
+    )
+    blob = _get(url)
+    if len(want) != 1 or hashlib.sha256(blob).hexdigest() != want[0]:
+        raise FetchError(f"{name}: sha256 is not its release's one digest {want}")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(dir=dest.parent))
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob)) as tar:
+            tops = {m.name.split("/")[0] for m in tar}
+            tar.extractall(work, filter="data")  # refuses absolute, climbing and escaping links
+        tree = work / tops.pop()
+        if tops or (tree / "VERSION").read_text().strip() != version:
+            raise FetchError(f"{name} is not one tree of contract {version}")
+        (tree / MARKER).write_text(f"{want[0]}  {name}\n")
+        shutil.rmtree(dest, ignore_errors=True)  # an unmarked, interrupted unpack
+        os.replace(tree, dest)
+    except (tarfile.TarError, OSError, TypeError) as exc:  # TypeError: no data filter before 3.11.4
+        raise FetchError(f"{name} could not be unpacked: {exc}") from None
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    return dest
+
+
+def _resolved(argv: list[str]) -> tuple:
+    try:
+        root, rule = resolve_root(argv, Path.cwd())
+        if rule != INSTALLED_FROM or (root / "atlas.yaml").exists():
+            return root, rule
+        if os.environ.get("THEA_NO_FETCH") == "1":
+            return root, rule + "; THEA_NO_FETCH=1"
+        from importlib.metadata import version  # noqa: PLC0415
+
+        return fetch_atlas(version("thea-software")), "its own release, sha256-checked"
+    except (ConfigError, FetchError, ImportError) as exc:
+        print(f"refused: {exc}", file=sys.stderr)
+        return None, None
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    root, rule = _resolved(argv)
+    if root is None:
+        return 2
+    _, index, width = root_flag(argv)
+    del argv[index : index + width]
+    if not (root / "atlas.yaml").exists():
+        print(f"no atlas at {root} (resolved by: {rule})", file=sys.stderr)
+        print(f"point at a checkout with {FLAG}, THEA_ROOT, or `atlas: root:` in {CONSUMER_CONFIG}", file=sys.stderr)
+        return 2
+    os.environ["THEA_ROOT"] = os.environ["CODE_DEVELOPMENT_ROOT"] = str(root)
+    # THE HARNESS COMES FROM THE ATLAS, NEVER THE WHEEL (3.7.0): a bundled copy is a second implementation.
+    harness = root / "scripts"
+    if not (harness / "atlas.py").exists():
+        print(f"{root} has an atlas.yaml and no scripts/atlas.py — not a Thea checkout", file=sys.stderr)
+        return 2
+    sys.path.insert(0, str(harness))
+    if "--where" in argv:
+        print(f"atlas root: {root}")
+        print(f"resolved by: {rule}")
+        # An agent handed only an install must still find where to start: the resolved atlas's entry.
+        print(f"agent entry: {root / '.agent' / 'bootstrap.json'}  (then: thea gate <file>)")
+        return 0
+    import atlas  # noqa: PLC0415 — deliberate: the root must be exported before this import
+
+    return atlas.main(argv or ["check"])
+
+
+def mcp_main() -> int:
+    """`thea-mcp`: the same root resolution, then serve the resolved atlas's MCP route on stdio."""
+    argv = sys.argv[1:]
+    if "--where" in argv:
+        return main(argv)
+    root, rule = _resolved(argv)
+    if root is None:
+        return 2
+    if not (root / "scripts" / "thea_mcp.py").exists():
+        print(f"no Thea MCP server at {root} (resolved by: {rule})", file=sys.stderr)
+        return 2
+    os.environ["THEA_ROOT"] = os.environ["CODE_DEVELOPMENT_ROOT"] = str(root)
+    sys.path.insert(0, str(root / "scripts"))
+    import thea_mcp  # noqa: PLC0415 — deliberate: the root must be exported before this import
+
+    return thea_mcp.serve()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

thea_software-3.53.0.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: thea-software
+Version: 3.53.0
+Summary: Contract harness for Thea, the engineering layer for AI. The atlas is polyglot; only this harness is Python.
+Project-URL: Homepage, https://github.com/HLIntel/thea-software
+Project-URL: Documentation, https://github.com/HLIntel/thea-software/blob/main/llms.txt
+Project-URL: Issues, https://github.com/HLIntel/thea-software/issues
+Project-URL: Source, https://github.com/HLIntel/thea-software
+Project-URL: Agent entry, https://raw.githubusercontent.com/HLIntel/thea-software/main/.agent/bootstrap.json
+Project-URL: LLM instructions, https://raw.githubusercontent.com/HLIntel/thea-software/main/llms.txt
+Project-URL: Changelog, https://github.com/HLIntel/thea-software/blob/main/docs/VERSIONING.md
+Keywords: engineering-atlas,polyglot,contract-verification,ai-agents,mcp,llm,agent-harness,code-verification,developer-tools,static-analysis,supply-chain-security,claude-code,agents-md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: pyyaml<7,>=6.0.3
+Provides-Extra: quality
+Requires-Dist: ruff>=0.6; extra == "quality"
+Dynamic: license-file

thea_software-3.53.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+atlas_cli.py,sha256=bO87Q8-pwqMVa69V7Om-eTbZRHBC97ZKNJOUbaO0Yyg,9199
+thea_software-3.53.0.dist-info/licenses/LICENSE,sha256=k-Z5jRt4D0HfDG4warBoDzAKXvlsPmUVDftQNOP8lGQ,1068
+thea_software-3.53.0.dist-info/METADATA,sha256=CVb2fR-AkbOjItWTwO_Dh09ob7zSh9yHzzNimUYxnIY,1490
+thea_software-3.53.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+thea_software-3.53.0.dist-info/entry_points.txt,sha256=m668gdFB9_oPFNwUciaW9TSF8nm1y7sJ319YTHxmLjM,93
+thea_software-3.53.0.dist-info/top_level.txt,sha256=Bp6WGrJWR4VZKKynPsLldtAZknrfgG843JCdrumGazg,10
+thea_software-3.53.0.dist-info/RECORD,,

thea_software-3.53.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

thea_software-3.53.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+atlas = atlas_cli:main
+thea = atlas_cli:main
+thea-mcp = atlas_cli:mcp_main

thea_software-3.53.0.dist-info/licenses/LICENSE

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

thea_software-3.53.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+atlas_cli