reforge-build 0.1.0__tar.gz

reforge_build-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.reforge/

reforge_build-0.1.0/LICENSE

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

reforge_build-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: reforge-build
+Version: 0.1.0
+Summary: Explicit, cached subprocess.run for ad-hoc build pipelines.
+Project-URL: Homepage, https://github.com/winstonewert/reforge
+Project-URL: Issues, https://github.com/winstonewert/reforge/issues
+Author-email: Winston Ewert <winstonewert@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: build,cache,make,pipeline,subprocess
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# reforge
+
+An explicit, cached `subprocess.run` for ad-hoc build pipelines.
+
+Reforge is a tiny build helper: you write your pipeline as a plain Python
+script that calls `run(...)` for each step, and reforge skips steps whose
+declared inputs haven't changed. No DAG, no rules file, no DSL — just
+`subprocess.run` with a content-addressed cache.
+
+## Install
+
+```sh
+pip install reforge-build
+# or
+uv add reforge-build
+```
+
+The PyPI distribution name is `reforge-build` (the bare `reforge` name was
+already taken on PyPI). The import name is still `reforge`.
+
+## Usage
+
+```python
+from reforge import input, output, run
+
+# Inputs and outputs must be declared explicitly.
+run(
+    "pandoc",
+    input("docs/index.md"),
+    "-o",
+    output("build/index.html"),
+)
+
+# stdout/stderr can be captured to declared outputs.
+run(
+    "python",
+    input("scripts/list_things.py"),
+    stdout=output("build/things.tsv"),
+)
+
+# When an output is a directory containing a known sentinel file,
+# pass the sentinel as the second argument so reforge can check it.
+run(
+    "iqtree2",
+    "-s", input("data/aln.fasta"),
+    "--prefix", output("build/iqtree/output", ".log"),
+)
+```
+
+### Rules
+
+- `run(...)` executes immediately.
+- Inputs must be wrapped with `input(...)`; missing inputs raise `FileNotFoundError`.
+- Outputs must be wrapped with `output(...)`; their parent directories are auto-created.
+- A step is skipped only when **all** declared outputs exist *and* the fingerprint
+  (command + content hash of every input) matches the cached fingerprint.
+- A step with **no inputs always runs** — there is no way to fingerprint it safely.
+- Commands run in a fresh temporary working directory, so they can't accidentally
+  read or write relative paths in your tree.
+- Cache metadata lives in `.reforge/` at the current working directory.
+
+### Note on `input`
+
+The module exports `input` and `output`, which shadow the Python builtin
+`input()` when star-imported. If you need the builtin, import it explicitly:
+
+```python
+from reforge import input as rf_input, output, run
+```
+
+## License
+
+MIT

reforge_build-0.1.0/README.md

@@ -0,0 +1,73 @@
+# reforge
+
+An explicit, cached `subprocess.run` for ad-hoc build pipelines.
+
+Reforge is a tiny build helper: you write your pipeline as a plain Python
+script that calls `run(...)` for each step, and reforge skips steps whose
+declared inputs haven't changed. No DAG, no rules file, no DSL — just
+`subprocess.run` with a content-addressed cache.
+
+## Install
+
+```sh
+pip install reforge-build
+# or
+uv add reforge-build
+```
+
+The PyPI distribution name is `reforge-build` (the bare `reforge` name was
+already taken on PyPI). The import name is still `reforge`.
+
+## Usage
+
+```python
+from reforge import input, output, run
+
+# Inputs and outputs must be declared explicitly.
+run(
+    "pandoc",
+    input("docs/index.md"),
+    "-o",
+    output("build/index.html"),
+)
+
+# stdout/stderr can be captured to declared outputs.
+run(
+    "python",
+    input("scripts/list_things.py"),
+    stdout=output("build/things.tsv"),
+)
+
+# When an output is a directory containing a known sentinel file,
+# pass the sentinel as the second argument so reforge can check it.
+run(
+    "iqtree2",
+    "-s", input("data/aln.fasta"),
+    "--prefix", output("build/iqtree/output", ".log"),
+)
+```
+
+### Rules
+
+- `run(...)` executes immediately.
+- Inputs must be wrapped with `input(...)`; missing inputs raise `FileNotFoundError`.
+- Outputs must be wrapped with `output(...)`; their parent directories are auto-created.
+- A step is skipped only when **all** declared outputs exist *and* the fingerprint
+  (command + content hash of every input) matches the cached fingerprint.
+- A step with **no inputs always runs** — there is no way to fingerprint it safely.
+- Commands run in a fresh temporary working directory, so they can't accidentally
+  read or write relative paths in your tree.
+- Cache metadata lives in `.reforge/` at the current working directory.
+
+### Note on `input`
+
+The module exports `input` and `output`, which shadow the Python builtin
+`input()` when star-imported. If you need the builtin, import it explicitly:
+
+```python
+from reforge import input as rf_input, output, run
+```
+
+## License
+
+MIT

reforge_build-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reforge-build"
+version = "0.1.0"
+description = "Explicit, cached subprocess.run for ad-hoc build pipelines."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Winston Ewert", email = "winstonewert@gmail.com" }]
+keywords = ["build", "cache", "subprocess", "pipeline", "make"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/winstonewert/reforge"
+Issues = "https://github.com/winstonewert/reforge/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reforge"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/reforge", "README.md", "LICENSE", "pyproject.toml"]

reforge_build-0.1.0/src/reforge/__init__.py

@@ -0,0 +1,265 @@
+"""
+Reforge - explicit and safe build tool helper.
+
+Key behavioral rules:
+- run(...) executes immediately
+- No inputs -> ALWAYS RUN (no skip)
+- Inputs must be declared Input(...)
+- Outputs must be declared Output(...)
+- Command runs in a temporary clean working dir (no accidental paths!)
+- Cache fingerprint stored only when inputs exist and fingerprints match
+"""
+
+import atexit
+import hashlib
+import json
+import os
+import subprocess
+import tempfile
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import List, Optional, Union
+
+# --------------------------
+# Artifact types
+# --------------------------
+
+__all__ = ["input", "output", "run"]
+
+
+@dataclass(frozen=True)
+class Input:
+    path: Path
+
+
+@dataclass(frozen=True)
+class Output:
+    path: Path
+    output_path: Path
+
+
+def input(path: str) -> Input:
+    return Input(project_root() / path)
+
+
+def output(path: str, subpath: str = '') -> Output:
+    return Output(project_root() / path, project_root() / (path + subpath))
+
+
+# --------------------------
+# Cache utilities
+# --------------------------
+
+CACHE_DIR_NAME = ".reforge"
+
+
+def project_root() -> Path:
+    return Path.cwd().absolute()
+
+
+def cache_dir() -> Path:
+    p = project_root() / CACHE_DIR_NAME
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+@dataclass(frozen=True)
+class Meta:
+    fingerprint: str
+    command: str
+    timestamp: float
+
+
+def _safe_meta_name(path: Path) -> str:
+    relpath = path.relative_to(project_root())
+    return str(relpath).replace(os.sep, "__") + ".meta.json"
+
+
+def _meta_path(relpath: Path) -> Path:
+    return cache_dir() / _safe_meta_name(relpath)
+
+
+# --------------------------
+# Hashing helpers
+# --------------------------
+
+
+_HASH_CACHE_FILE = "_file_hash_cache.json"
+_hash_cache: Optional[dict] = None
+_hash_cache_dirty = False
+
+
+def _load_hash_cache() -> dict:
+    global _hash_cache
+    if _hash_cache is not None:
+        return _hash_cache
+    p = cache_dir() / _HASH_CACHE_FILE
+    try:
+        _hash_cache = json.loads(p.read_text())
+        if not isinstance(_hash_cache, dict):
+            _hash_cache = {}
+    except (FileNotFoundError, json.JSONDecodeError):
+        _hash_cache = {}
+    atexit.register(_save_hash_cache)
+    return _hash_cache
+
+
+def _save_hash_cache():
+    if not _hash_cache_dirty or _hash_cache is None:
+        return
+    (cache_dir() / _HASH_CACHE_FILE).write_text(json.dumps(_hash_cache))
+
+
+def _hash_file(path: Path) -> str:
+    global _hash_cache_dirty
+    cache = _load_hash_cache()
+    st = path.stat()
+    key = str(path)
+    entry = cache.get(key)
+    if (
+        entry is not None
+        and entry.get("mtime_ns") == st.st_mtime_ns
+        and entry.get("size") == st.st_size
+    ):
+        return entry["digest"]
+
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        while chunk := f.read(1 << 16):
+            h.update(chunk)
+    digest = h.hexdigest()
+    cache[key] = {
+        "mtime_ns": st.st_mtime_ns,
+        "size": st.st_size,
+        "digest": digest,
+    }
+    _hash_cache_dirty = True
+    return digest
+
+
+# --------------------------
+# Run + caching
+# --------------------------
+
+
+def _command_id(cmd: List[str]) -> str:
+    return json.dumps(cmd)
+
+
+def _fingerprint(cmd: List[str], input_paths: List[Path]) -> str:
+    h = hashlib.sha256()
+    h.update(_command_id(cmd).encode())
+    for p in sorted(input_paths, key=lambda x: str(x)):
+        h.update(_hash_file(p).encode())
+    return h.hexdigest()
+
+
+def _load_meta(rel: Path) -> Optional[Meta]:
+    mp = _meta_path(rel)
+    if not mp.exists():
+        return None
+    try:
+        return Meta(**json.loads(mp.read_text()))
+    except Exception:
+        return None
+
+
+def _save_meta(outputs: List[Path], fingerprint: str, command_id: str):
+    now = time.time()
+    for rel in outputs:
+        _meta_path(rel).write_text(
+            json.dumps(
+                asdict(Meta(fingerprint=fingerprint, command=command_id, timestamp=now))
+            )
+        )
+
+
+def run(
+    *args: Union[str, Input, Output],
+    stdin: Optional[Input] = None,
+    stdout: Optional[Output] = None,
+    stderr: Optional[Output] = None,
+):
+
+    cmd: List[str] = []
+    inputs: List[Path] = []
+    outputs: List[Path] = []
+
+    # collect inputs and outputs from positional args
+    for a in args:
+        if isinstance(a, Input):
+            inputs.append(a.path)
+            cmd.append(str(a.path))
+        elif isinstance(a, Output):
+            outputs.append(a.output_path)
+            cmd.append(str(a.path))
+        else:
+            cmd.append(a)
+
+    # keyword stdout/stderr
+    if stdin:
+        inputs.append(stdin.path)
+    if stdout:
+        outputs.append(stdout.path)
+    if stderr:
+        outputs.append(stderr.path)
+
+    # dedupe outputs
+    outputs = list(dict.fromkeys(outputs))
+
+    # verify inputs exist
+    for p in inputs:
+        if not p.exists():
+            raise FileNotFoundError(f"Missing input: {p}")
+
+    command_id = _command_id(cmd)
+    fingerprint = _fingerprint(cmd, inputs)
+    if not inputs:
+        skip = False
+    else:
+        skip = True
+        for rel in outputs:
+            outp = project_root() / rel
+            if not outp.exists():
+                skip = False
+                break
+            meta = _load_meta(rel)
+            if not meta or meta.fingerprint != fingerprint:
+                skip = False
+                break
+
+    cmd_display = " ".join(cmd)
+
+    if skip:
+        return
+
+    print(f"RUN: {cmd_display}")
+
+    # ensure output dirs exist
+    for rel in outputs:
+        (project_root() / rel).parent.mkdir(parents=True, exist_ok=True)
+
+    # execute in isolated temp dir
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp = Path(tmp)
+
+        result = subprocess.run(
+            cmd,
+            cwd=tmp,
+            stdin=open(stdin.path, "rb") if stdin else None,
+            stdout=subprocess.PIPE if stdout else None,
+            stderr=subprocess.PIPE if stderr else None,
+            check=True,
+        )
+
+        if stdout:
+            with open(project_root() / stdout.path, "wb") as output:
+                output.write(result.stdout)
+        if stderr:
+            with open(project_root() / stderr.path, "wb") as output:
+                output.write(result.stderr)
+
+    # Only save cache metadata when inputs exist
+    if inputs:
+        _save_meta(outputs, fingerprint, command_id)