scivetra 0.1.0a1__tar.gz

scivetra-0.1.0a1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: scivetra
+Version: 0.1.0a1
+Summary: Deterministic, read-only inventory of local PDF files
+Author: tvquynh
+Project-URL: Source, https://github.com/tvquynh/scivetra
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SciVetra bootstrap
+
+SciVetra 0.1.0a1 provides a small, standard-library-only local PDF inventory utility.
+It lists relative filenames, byte sizes, and SHA-256 digests as deterministic JSON.
+It does not parse or execute PDFs, contact a network service, or upload files.
+
+```console
+scivetra --version
+scivetra pdf-inventory ./my-local-fixtures
+scivetra pdf-inventory ./my-local-fixtures --output inventory.json
+```
+
+Choose only a local directory you are authorized to inspect. No location is scanned
+by default. Keep the selected tree stable while scanning. Symlinks and Windows
+reparse points are skipped; linked directory ancestors and Windows network drives
+are rejected. On POSIX, use a local filesystem, not a mounted network filesystem.
+Limits: 100,000 filesystem entries, 1 GB per PDF and 10 GB total PDF bytes.
+Unchanged trees produce the same filename-sorted JSON. Errors exit with status 2;
+no incomplete JSON is emitted. Output files must be new `.json` files; existing
+files are never overwritten. This utility is not a sandbox against adversarial
+concurrent filesystem changes.
+
+This independent bootstrap does not implement SLR, RAG, AI, Crossref integration,
+PDF downloading, or the future SciVetra research framework. Framework architecture
+and subsequent implementation remain with the primary implementation engineer.
+No software license has been selected or asserted for this bootstrap.
+
+## Development
+
+```console
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+## One-time initial publication
+
+The manual `publish.yml` workflow accepts exactly `scivetra==0.1.0a1` as its
+confirmation and runs only on `main`. Tests, wheel/sdist build, metadata validation,
+and a fresh wheel CLI smoke test must pass before a separate OIDC publishing job.
+Configure the GitHub `pypi` environment with required reviewer `tvquynh` and only
+`main` allowed to deploy. PyPI's pending GitHub publisher must match owner
+`tvquynh`, repository `scivetra`, workflow `publish.yml`, environment `pypi`.
+Use no API token. Do not rerun an uncertain upload: check production PyPI and
+Actions first. A pending publisher does not reserve the name.
+
+First run the workflow with Publish unchecked (checks only). After inspecting the
+successful checks, run once with Publish checked and the exact confirmation, then
+approve the protected pypi deployment. A separate clean environment verifies the
+production installation after upload. If upload succeeds but verification fails,
+do not publish again; investigate the existing production release.

scivetra-0.1.0a1/README.md

@@ -0,0 +1,53 @@
+# SciVetra bootstrap
+
+SciVetra 0.1.0a1 provides a small, standard-library-only local PDF inventory utility.
+It lists relative filenames, byte sizes, and SHA-256 digests as deterministic JSON.
+It does not parse or execute PDFs, contact a network service, or upload files.
+
+```console
+scivetra --version
+scivetra pdf-inventory ./my-local-fixtures
+scivetra pdf-inventory ./my-local-fixtures --output inventory.json
+```
+
+Choose only a local directory you are authorized to inspect. No location is scanned
+by default. Keep the selected tree stable while scanning. Symlinks and Windows
+reparse points are skipped; linked directory ancestors and Windows network drives
+are rejected. On POSIX, use a local filesystem, not a mounted network filesystem.
+Limits: 100,000 filesystem entries, 1 GB per PDF and 10 GB total PDF bytes.
+Unchanged trees produce the same filename-sorted JSON. Errors exit with status 2;
+no incomplete JSON is emitted. Output files must be new `.json` files; existing
+files are never overwritten. This utility is not a sandbox against adversarial
+concurrent filesystem changes.
+
+This independent bootstrap does not implement SLR, RAG, AI, Crossref integration,
+PDF downloading, or the future SciVetra research framework. Framework architecture
+and subsequent implementation remain with the primary implementation engineer.
+No software license has been selected or asserted for this bootstrap.
+
+## Development
+
+```console
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+## One-time initial publication
+
+The manual `publish.yml` workflow accepts exactly `scivetra==0.1.0a1` as its
+confirmation and runs only on `main`. Tests, wheel/sdist build, metadata validation,
+and a fresh wheel CLI smoke test must pass before a separate OIDC publishing job.
+Configure the GitHub `pypi` environment with required reviewer `tvquynh` and only
+`main` allowed to deploy. PyPI's pending GitHub publisher must match owner
+`tvquynh`, repository `scivetra`, workflow `publish.yml`, environment `pypi`.
+Use no API token. Do not rerun an uncertain upload: check production PyPI and
+Actions first. A pending publisher does not reserve the name.
+
+First run the workflow with Publish unchecked (checks only). After inspecting the
+successful checks, run once with Publish checked and the exact confirmation, then
+approve the protected pypi deployment. A separate clean environment verifies the
+production installation after upload. If upload succeeds but verification fails,
+do not publish again; investigate the existing production release.

scivetra-0.1.0a1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scivetra"
+version = "0.1.0a1"
+description = "Deterministic, read-only inventory of local PDF files"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "tvquynh"}]
+dependencies = []
+classifiers = ["Development Status :: 3 - Alpha", "Programming Language :: Python :: 3", "Operating System :: OS Independent"]
+
+[project.urls]
+Source = "https://github.com/tvquynh/scivetra"
+
+[project.scripts]
+scivetra = "scivetra.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

scivetra-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scivetra-0.1.0a1/src/scivetra/__init__.py

@@ -0,0 +1,2 @@
+"""SciVetra's independent local file inventory bootstrap."""
+__version__ = "0.1.0a1"

scivetra-0.1.0a1/src/scivetra/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

scivetra-0.1.0a1/src/scivetra/cli.py

@@ -0,0 +1,92 @@
+"""Inventory only explicitly selected, stable local directories."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import stat
+import sys
+
+from . import __version__
+
+MAX_ENTRIES = 100_000
+MAX_FILE_BYTES = 1_000_000_000
+MAX_TOTAL_BYTES = 10_000_000_000
+
+
+def linked(info):
+    return stat.S_ISLNK(info.st_mode) or bool(getattr(info, "st_file_attributes", 0) & 0x400)
+
+
+def inventory(directory):
+    root = Path(os.path.abspath(directory))
+    if str(root).startswith(("\\\\", "//")):
+        raise ValueError("Network paths are unsupported")
+    if os.name == "nt":
+        import ctypes
+        if ctypes.windll.kernel32.GetDriveTypeW(str(root.anchor)) != 3:
+            raise ValueError("Choose a local fixed drive")
+    for part in (*reversed(root.parents), root):
+        if linked(part.lstat()):
+            raise ValueError("Directory ancestors must not be symlinks or reparse points")
+    if not root.is_dir():
+        raise ValueError("Expected a directory")
+    rows, pending = [], [root]
+    entries = total = 0
+    while pending:
+        current = pending.pop()
+        with os.scandir(current) as children:
+            for child in children:
+                entries += 1
+                if entries > MAX_ENTRIES:
+                    raise ValueError("Entry limit exceeded")
+                info = os.stat(child.path, follow_symlinks=False)
+                if linked(info):
+                    continue
+                if stat.S_ISDIR(info.st_mode):
+                    pending.append(Path(child.path))
+                elif stat.S_ISREG(info.st_mode) and child.name.lower().endswith(".pdf"):
+                    if info.st_size > MAX_FILE_BYTES or total + info.st_size > MAX_TOTAL_BYTES:
+                        raise ValueError("PDF byte limit exceeded")
+                    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+                    fd = os.open(child.path, flags)
+                    with os.fdopen(fd, "rb") as stream:
+                        before = os.fstat(stream.fileno())
+                        if linked(before) or not stat.S_ISREG(before.st_mode) or (before.st_dev, before.st_ino) != (info.st_dev, info.st_ino):
+                            raise ValueError("File changed during inventory")
+                        digest = hashlib.sha256()
+                        count = 0
+                        while chunk := stream.read(1024 * 1024):
+                            count += len(chunk)
+                            if count > MAX_FILE_BYTES or total + count > MAX_TOTAL_BYTES:
+                                raise ValueError("PDF byte limit exceeded")
+                            digest.update(chunk)
+                        after = os.fstat(stream.fileno())
+                        if count != info.st_size or (after.st_size, after.st_mtime_ns) != (info.st_size, info.st_mtime_ns):
+                            raise ValueError("File changed during inventory")
+                    total += count
+                    rows.append({"filename": Path(child.path).relative_to(root).as_posix(), "size_bytes": count, "sha256": digest.hexdigest()})
+    return sorted(rows, key=lambda row: row["filename"])
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Read-only inventory of explicitly selected local PDFs; no parsing or network access.")
+    parser.add_argument("--version", action="version", version=f"scivetra {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    pdf = commands.add_parser("pdf-inventory")
+    pdf.add_argument("directory")
+    pdf.add_argument("--output", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        result = json.dumps(inventory(args.directory), ensure_ascii=True, indent=2) + "\n"
+        if args.output:
+            if args.output.suffix.lower() != ".json":
+                raise ValueError("Output must use a .json extension")
+            # Exclusive creation prevents overwriting any user file or symlink target.
+            with args.output.open("x", encoding="utf-8", newline="\n") as output:
+                output.write(result)
+        else:
+            sys.stdout.write(result)
+    except (OSError, ValueError) as error:
+        parser.exit(2, f"scivetra: {error}\n")
+    return 0

scivetra-0.1.0a1/src/scivetra.egg-info/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: scivetra
+Version: 0.1.0a1
+Summary: Deterministic, read-only inventory of local PDF files
+Author: tvquynh
+Project-URL: Source, https://github.com/tvquynh/scivetra
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SciVetra bootstrap
+
+SciVetra 0.1.0a1 provides a small, standard-library-only local PDF inventory utility.
+It lists relative filenames, byte sizes, and SHA-256 digests as deterministic JSON.
+It does not parse or execute PDFs, contact a network service, or upload files.
+
+```console
+scivetra --version
+scivetra pdf-inventory ./my-local-fixtures
+scivetra pdf-inventory ./my-local-fixtures --output inventory.json
+```
+
+Choose only a local directory you are authorized to inspect. No location is scanned
+by default. Keep the selected tree stable while scanning. Symlinks and Windows
+reparse points are skipped; linked directory ancestors and Windows network drives
+are rejected. On POSIX, use a local filesystem, not a mounted network filesystem.
+Limits: 100,000 filesystem entries, 1 GB per PDF and 10 GB total PDF bytes.
+Unchanged trees produce the same filename-sorted JSON. Errors exit with status 2;
+no incomplete JSON is emitted. Output files must be new `.json` files; existing
+files are never overwritten. This utility is not a sandbox against adversarial
+concurrent filesystem changes.
+
+This independent bootstrap does not implement SLR, RAG, AI, Crossref integration,
+PDF downloading, or the future SciVetra research framework. Framework architecture
+and subsequent implementation remain with the primary implementation engineer.
+No software license has been selected or asserted for this bootstrap.
+
+## Development
+
+```console
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m pip install build twine
+python -m build
+python -m twine check dist/*
+```
+
+## One-time initial publication
+
+The manual `publish.yml` workflow accepts exactly `scivetra==0.1.0a1` as its
+confirmation and runs only on `main`. Tests, wheel/sdist build, metadata validation,
+and a fresh wheel CLI smoke test must pass before a separate OIDC publishing job.
+Configure the GitHub `pypi` environment with required reviewer `tvquynh` and only
+`main` allowed to deploy. PyPI's pending GitHub publisher must match owner
+`tvquynh`, repository `scivetra`, workflow `publish.yml`, environment `pypi`.
+Use no API token. Do not rerun an uncertain upload: check production PyPI and
+Actions first. A pending publisher does not reserve the name.
+
+First run the workflow with Publish unchecked (checks only). After inspecting the
+successful checks, run once with Publish checked and the exact confirmation, then
+approve the protected pypi deployment. A separate clean environment verifies the
+production installation after upload. If upload succeeds but verification fails,
+do not publish again; investigate the existing production release.

scivetra-0.1.0a1/src/scivetra.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/scivetra/__init__.py
+src/scivetra/__main__.py
+src/scivetra/cli.py
+src/scivetra.egg-info/PKG-INFO
+src/scivetra.egg-info/SOURCES.txt
+src/scivetra.egg-info/dependency_links.txt
+src/scivetra.egg-info/entry_points.txt
+src/scivetra.egg-info/top_level.txt
+tests/test_inventory.py

scivetra-0.1.0a1/src/scivetra.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scivetra-0.1.0a1/src/scivetra.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scivetra = scivetra.cli:main

scivetra-0.1.0a1/src/scivetra.egg-info/top_level.txt

@@ -0,0 +1 @@
+scivetra

scivetra-0.1.0a1/tests/test_inventory.py

@@ -0,0 +1,62 @@
+import contextlib
+import hashlib
+import io
+import json
+from pathlib import Path
+import tempfile
+import unittest
+from unittest.mock import patch
+from scivetra.cli import inventory, main
+
+class InventoryTests(unittest.TestCase):
+    def test_deterministic_nested_inventory_without_parsing(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "sub").mkdir()
+            (root / "sub" / "b.PDF").write_bytes(b"not a parsed PDF")
+            (root / "a.pdf").write_bytes(b"abc")
+            (root / "ignore.txt").write_bytes(b"ignored")
+            expected = [{"filename":"a.pdf", "size_bytes":3, "sha256":hashlib.sha256(b"abc").hexdigest()}, {"filename":"sub/b.PDF", "size_bytes":16, "sha256":hashlib.sha256(b"not a parsed PDF").hexdigest()}]
+            self.assertEqual(inventory(root), expected)
+            self.assertEqual(inventory(root), expected)
+            capture = io.StringIO()
+            with contextlib.redirect_stdout(capture):
+                self.assertEqual(main(["pdf-inventory", directory]), 0)
+            self.assertEqual(json.loads(capture.getvalue()), expected)
+            output = root / "inventory.json"
+            main(["pdf-inventory", directory, "--output", str(output)])
+            original = output.read_bytes()
+            with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+                main(["pdf-inventory", directory, "--output", str(output)])
+            self.assertEqual(output.read_bytes(), original)
+            self.assertEqual((root / "a.pdf").read_bytes(), b"abc")
+
+    def test_limits_fail_closed(self):
+        with tempfile.TemporaryDirectory() as directory:
+            (Path(directory)/"a.pdf").write_bytes(b"abc")
+            with patch("scivetra.cli.MAX_FILE_BYTES", 2), self.assertRaises(ValueError):
+                inventory(directory)
+            with patch("scivetra.cli.MAX_ENTRIES", 0), self.assertRaises(ValueError):
+                inventory(directory)
+
+    def test_symlinks_are_not_followed(self):
+        with tempfile.TemporaryDirectory() as directory, tempfile.TemporaryDirectory() as outside:
+            root = Path(directory)
+            (Path(outside)/"private.pdf").write_bytes(b"outside")
+            try:
+                (root/"linked").symlink_to(outside, target_is_directory=True)
+                (root/"linked.pdf").symlink_to(Path(outside)/"private.pdf")
+            except OSError:
+                self.skipTest("Symlink creation unavailable; run this test on Linux CI")
+            self.assertEqual(inventory(root), [])
+            with self.assertRaises(ValueError):
+                inventory(root/"linked")
+
+    def test_invalid_and_empty_directories(self):
+        with tempfile.TemporaryDirectory() as directory:
+            self.assertEqual(inventory(directory), [])
+            with self.assertRaises(OSError):
+                inventory(Path(directory)/"missing")
+
+if __name__ == "__main__":
+    unittest.main()