ggraft 1.0.0__tar.gz

ggraft-1.0.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

ggraft-1.0.0/.github/workflows/cd.yml

@@ -0,0 +1,60 @@
+name: Build and Publish to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  build_dist:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build --wheel --sdist --outdir dist
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: [build_dist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

ggraft-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+build/
+dist/
+.ggraft/

ggraft-1.0.0/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/*.egg-info/": true,
+    }
+}

ggraft-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: ggraft
+Version: 1.0.0
+Summary: GLSL Graft - declarative injection patches for vanilla Minecraft shaders
+Author: Neylz
+License-Expression: MIT
+Keywords: minecraft,glsl,shaders,resourcepack,patching
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+
+# ggraft
+
+**GLSL Graft** is a cli tool allowing declarative injection patches for vanilla Minecraft shaders.
+
+Overriding a core shader means copying Mojang's file and changing one line. Do that across twenty shaders and every Minecraft update becomes twenty manual re-copies, with no record of what you actually changed. ggraft keeps the *edit* under version control instead of the result: you declare which line to change, and it re-derives the overrides from any version on demand.
+
+## Terminology
+
+| Concept | Name |
+| --- | --- |
+| The vanilla GLSL going in | **base** |
+| A file declaring edits | **patch** |
+| Which shader it's for | **target** |
+| Where in the source | **injection point** (or **anchor**) |
+| One edit inside a patch | **injection** |
+| What it does | **operation**: `insert`, `replace`, `wrap`, `declare` |
+| Anchor didn't match | **unresolved injection** |
+| Anchor matched N times | **ambiguous injection** |
+| GLSL coming out | **patched shader** |
+
+## Install
+
+### From PyPI
+
+```bash
+pip install ggraft
+```
+
+### From source
+
+Needs Python 3.11+ and [Click](https://click.palletsprojects.com/).
+Everything else is standard library.
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```bash
+ggraft init 26.3      # write ggraft.toml
+ggraft pull           # fetch bases from misode/mcmeta
+ggraft build          # apply patches -> patched shaders
+```
+
+## Project configuration
+
+`ggraft.toml`, found by walking up from the working directory. Paths resolve relative to it.
+
+```toml
+[base]
+version = "26.3"                      # Minecraft version to pull
+dir     = ".ggraft/base"              # where bases land (gitignore this)
+source  = "assets/minecraft/shaders"  # subtree to pull, stripped from local paths
+repo    = "misode/mcmeta"             # optional
+
+[patches]
+dir = "patches"
+
+[output]
+dir    = "assets/minecraft/shaders"   # required
+header = true                         # stamp a provenance comment
+```
+
+Targets are relative to `base.source`: `core/terrain.vsh` reads from `.ggraft/base/core/terrain.vsh` and writes to `<output.dir>/core/terrain.vsh`.
+
+## Patches
+
+```toml
+name    = "iso-world"
+targets = ["core/terrain.vsh", "core/rendertype_*.vsh"]
+exclude = ["core/rendertype_lines.vsh"]
+
+[[injection]]
+op      = "declare"
+include = "foo:iso.glsl"
+
+[[injection]]
+op   = "replace"
+at   = "gl_Position = ProjMat * ModelViewMat * vec4({expr}, 1.0);"
+with = "gl_Position = iso_position(ProjMat, ModelViewMat, vec4({expr}, 1.0));"
+```
+
+Injections apply in order, to every matching target. Patches stack in filename order.
+
+### Anchors
+
+`at` is literal text, not a regex. `{name}` captures what sits in that position, `{match}` is the whole match; both are available in the replacement.
+
+| Key | Meaning |
+| --- | --- |
+| `at` | the anchor pattern |
+| `regex = true` | treat `at` as a regex, with named groups |
+| `multiline = true` | let one `{name}` (or a regex `.`) span lines (false by default) |
+| `occurrence = N` | take the Nth match (1-based) |
+| `every = true` | apply to all matches |
+
+
+No match is an **unresolved injection**; more than one without `occurrence` or `every` is an **ambiguous injection**. Both fail the build, naming the patch, injection index, target and line numbers.
+
+### Operations
+
+| Operation | Keys | Effect |
+| --- | --- | --- |
+| `replace` | `with` | swap the anchored text |
+| `insert` | `text`, `where` (`before`/`after`) | add text beside it |
+| `wrap` | `prefix`, `suffix` | surround it, keeping it |
+| `declare` | `include` or `text` | add a top-level declaration; no anchor |
+
+`declare` inserts after the last `#include` at conditional-nesting depth zero, falling back to `#extension` then `#version`, and is idempotent. Appending after the *last* `#include` in the file would strand it inside an `#ifdef` branch that some shader variants skip.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `ggraft pull [version]` | fetch bases; `--force` refetches, `-j` sets parallelism. Pulling another version replaces the base |
+| `ggraft build` | apply patches; `--check` dry run, `-t` filters by glob |
+| `ggraft targets` | show which patches hit which targets |
+| `ggraft init [version]` | write a starter config; `--force` overwrites |
+
+`-h`/`--help` works on the group and every command, `-V`/`--version` prints the version, and `-c`/`--config` points at a specific `ggraft.toml` instead of searching upwards. `pull --token` also reads `GITHUB_TOKEN`.
+
+### Build guarantees
+
+- `--check` dry run without output writes.
+- A target pattern matching no base file fails the build. What a patch orphaned by a Minecraft update looks like.
+- A patch applying to nothing fails the build, so a mistake in `targets` or `exclude` cannot disable a patch silently.
+- Stale output is pruned. Shaders ggraft wrote are recorded in `.ggraft/manifest.json`, and a target dropped from a patch has its override deleted on the next build. Only manifest entries are ever deleted; `-t` disables pruning, since a partial build cannot tell what is stale.
+
+## Bases
+
+Uses [misode/mcmeta](https://github.com/misode/mcmeta).
+Tree walk might be rate limited. Set `GITHUB_TOKEN` or pass `--token` to bypass the limit.
+
+A pull downloads into a sibling `.partial` directory and swaps it in, so an interrupted pull leaves the existing base untouched and a completed one leaves nothing of it behind: `base.dir` is replaced wholesale, never merged into.
+
+What the directory holds — version, repo and source — is recorded in `.ggraft/base.json`. Pulling a different version, repo or source therefore refetches instead of reporting the base as already present, and files from the old version cannot linger as targets for the next build. A base ggraft did not record is treated as stale and refetched too. `--force` refetches regardless.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests   # everything
+python -m unittest tests.test_cli      # one module
+```
+
+One module per layer: `test_structure`, `test_glsl`, `test_anchor`, `test_operations`, `test_engine`, `test_sources`, `test_cli`. Shared shaders, project files and a network-free mcmeta client live in `tests/fixtures.py`.
+
+## Planned Features
+- [ ] functions injections
+- [ ] python module API
+

ggraft-1.0.0/README.md

@@ -0,0 +1,151 @@
+# ggraft
+
+**GLSL Graft** is a cli tool allowing declarative injection patches for vanilla Minecraft shaders.
+
+Overriding a core shader means copying Mojang's file and changing one line. Do that across twenty shaders and every Minecraft update becomes twenty manual re-copies, with no record of what you actually changed. ggraft keeps the *edit* under version control instead of the result: you declare which line to change, and it re-derives the overrides from any version on demand.
+
+## Terminology
+
+| Concept | Name |
+| --- | --- |
+| The vanilla GLSL going in | **base** |
+| A file declaring edits | **patch** |
+| Which shader it's for | **target** |
+| Where in the source | **injection point** (or **anchor**) |
+| One edit inside a patch | **injection** |
+| What it does | **operation**: `insert`, `replace`, `wrap`, `declare` |
+| Anchor didn't match | **unresolved injection** |
+| Anchor matched N times | **ambiguous injection** |
+| GLSL coming out | **patched shader** |
+
+## Install
+
+### From PyPI
+
+```bash
+pip install ggraft
+```
+
+### From source
+
+Needs Python 3.11+ and [Click](https://click.palletsprojects.com/).
+Everything else is standard library.
+
+```bash
+pip install -e .
+```
+
+## Quick start
+
+```bash
+ggraft init 26.3      # write ggraft.toml
+ggraft pull           # fetch bases from misode/mcmeta
+ggraft build          # apply patches -> patched shaders
+```
+
+## Project configuration
+
+`ggraft.toml`, found by walking up from the working directory. Paths resolve relative to it.
+
+```toml
+[base]
+version = "26.3"                      # Minecraft version to pull
+dir     = ".ggraft/base"              # where bases land (gitignore this)
+source  = "assets/minecraft/shaders"  # subtree to pull, stripped from local paths
+repo    = "misode/mcmeta"             # optional
+
+[patches]
+dir = "patches"
+
+[output]
+dir    = "assets/minecraft/shaders"   # required
+header = true                         # stamp a provenance comment
+```
+
+Targets are relative to `base.source`: `core/terrain.vsh` reads from `.ggraft/base/core/terrain.vsh` and writes to `<output.dir>/core/terrain.vsh`.
+
+## Patches
+
+```toml
+name    = "iso-world"
+targets = ["core/terrain.vsh", "core/rendertype_*.vsh"]
+exclude = ["core/rendertype_lines.vsh"]
+
+[[injection]]
+op      = "declare"
+include = "foo:iso.glsl"
+
+[[injection]]
+op   = "replace"
+at   = "gl_Position = ProjMat * ModelViewMat * vec4({expr}, 1.0);"
+with = "gl_Position = iso_position(ProjMat, ModelViewMat, vec4({expr}, 1.0));"
+```
+
+Injections apply in order, to every matching target. Patches stack in filename order.
+
+### Anchors
+
+`at` is literal text, not a regex. `{name}` captures what sits in that position, `{match}` is the whole match; both are available in the replacement.
+
+| Key | Meaning |
+| --- | --- |
+| `at` | the anchor pattern |
+| `regex = true` | treat `at` as a regex, with named groups |
+| `multiline = true` | let one `{name}` (or a regex `.`) span lines (false by default) |
+| `occurrence = N` | take the Nth match (1-based) |
+| `every = true` | apply to all matches |
+
+
+No match is an **unresolved injection**; more than one without `occurrence` or `every` is an **ambiguous injection**. Both fail the build, naming the patch, injection index, target and line numbers.
+
+### Operations
+
+| Operation | Keys | Effect |
+| --- | --- | --- |
+| `replace` | `with` | swap the anchored text |
+| `insert` | `text`, `where` (`before`/`after`) | add text beside it |
+| `wrap` | `prefix`, `suffix` | surround it, keeping it |
+| `declare` | `include` or `text` | add a top-level declaration; no anchor |
+
+`declare` inserts after the last `#include` at conditional-nesting depth zero, falling back to `#extension` then `#version`, and is idempotent. Appending after the *last* `#include` in the file would strand it inside an `#ifdef` branch that some shader variants skip.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `ggraft pull [version]` | fetch bases; `--force` refetches, `-j` sets parallelism. Pulling another version replaces the base |
+| `ggraft build` | apply patches; `--check` dry run, `-t` filters by glob |
+| `ggraft targets` | show which patches hit which targets |
+| `ggraft init [version]` | write a starter config; `--force` overwrites |
+
+`-h`/`--help` works on the group and every command, `-V`/`--version` prints the version, and `-c`/`--config` points at a specific `ggraft.toml` instead of searching upwards. `pull --token` also reads `GITHUB_TOKEN`.
+
+### Build guarantees
+
+- `--check` dry run without output writes.
+- A target pattern matching no base file fails the build. What a patch orphaned by a Minecraft update looks like.
+- A patch applying to nothing fails the build, so a mistake in `targets` or `exclude` cannot disable a patch silently.
+- Stale output is pruned. Shaders ggraft wrote are recorded in `.ggraft/manifest.json`, and a target dropped from a patch has its override deleted on the next build. Only manifest entries are ever deleted; `-t` disables pruning, since a partial build cannot tell what is stale.
+
+## Bases
+
+Uses [misode/mcmeta](https://github.com/misode/mcmeta).
+Tree walk might be rate limited. Set `GITHUB_TOKEN` or pass `--token` to bypass the limit.
+
+A pull downloads into a sibling `.partial` directory and swaps it in, so an interrupted pull leaves the existing base untouched and a completed one leaves nothing of it behind: `base.dir` is replaced wholesale, never merged into.
+
+What the directory holds — version, repo and source — is recorded in `.ggraft/base.json`. Pulling a different version, repo or source therefore refetches instead of reporting the base as already present, and files from the old version cannot linger as targets for the next build. A base ggraft did not record is treated as stale and refetched too. `--force` refetches regardless.
+
+## Tests
+
+```bash
+python -m unittest discover -s tests   # everything
+python -m unittest tests.test_cli      # one module
+```
+
+One module per layer: `test_structure`, `test_glsl`, `test_anchor`, `test_operations`, `test_engine`, `test_sources`, `test_cli`. Shared shaders, project files and a network-free mcmeta client live in `tests/fixtures.py`.
+
+## Planned Features
+- [ ] functions injections
+- [ ] python module API
+

ggraft-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=69", "setuptools-scm[toml]>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ggraft"
+description = "GLSL Graft - declarative injection patches for vanilla Minecraft shaders"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Neylz" }]
+keywords = ["minecraft", "glsl", "shaders", "resourcepack", "patching"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = ["click>=8.1"]
+
+dynamic = ["version"]
+
+[project.scripts]
+ggraft = "ggraft.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+tag_regex = "^(?P<version>\\d+\\.\\d+\\.\\d+)$"
+version_scheme = "no-guess-dev"
+local_scheme = "no-local-version"
+fallback_version = "0.0.0"

ggraft-1.0.0/setup.cfg

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

ggraft-1.0.0/src/ggraft/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ggraft")
+except PackageNotFoundError:   # a source tree that was never installed
+    __version__ = "0.0.0"

ggraft-1.0.0/src/ggraft/__main__.py

@@ -0,0 +1,4 @@
+from ggraft.cli import main
+
+if __name__ == "__main__":
+    main()

ggraft-1.0.0/src/ggraft/cli/__init__.py

@@ -0,0 +1,3 @@
+from ggraft.cli.main import cli, main
+
+__all__ = ["cli", "main"]

ggraft-1.0.0/src/ggraft/cli/commands/__init__.py

@@ -0,0 +1,14 @@
+from ggraft.cli.commands.build import build
+from ggraft.cli.commands.init import init
+from ggraft.cli.commands.pull import pull
+from ggraft.cli.commands.targets import targets
+
+COMMANDS = [init, pull, build, targets]
+
+__all__ = [
+    "COMMANDS",
+    "build",
+    "init",
+    "pull",
+    "targets"
+]

ggraft-1.0.0/src/ggraft/cli/commands/build.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import click
+
+from ggraft.cli.commands.common import load_config
+from ggraft.errors import TargetError
+from ggraft.patching import engine, patch as patch_module
+
+
+@click.command()
+@click.option("-t", "--target", "targets", multiple=True, metavar="GLOB",
+              help="only build targets matching this glob (repeatable)")
+@click.option("--check", is_flag=True,
+              help="do not write; exit non-zero if output would change")
+@click.pass_obj
+def build(config_path: str | None, targets: tuple[str, ...], check: bool) -> None:
+    """Apply patches to the base."""
+    cfg = load_config(config_path)
+    patches = patch_module.load_all(cfg.patch_dir)
+    plans = engine.plan(cfg, patches, only=list(targets) or None)
+    if not plans:
+        raise TargetError("no targets matched any patch")
+
+    # A filtered build cannot tell what is stale, so it never prunes.
+    report = engine.run(cfg, plans, write=not check, prune=not targets)
+    changed = [r for r in report.results if r.changed]
+
+    for result in report.results:
+        mark = "*" if result.changed else " "
+        click.echo(f" {mark} {result.target:<38} {result.injections:>2} injection(s)"
+                   f"  [{', '.join(result.patches)}]")
+    for target in report.pruned:
+        click.echo(f" - {target:<38} removed (no longer targeted)")
+
+    verb = "would patch" if check else "patched"
+    summary = f"{verb} {len(report.results)} shader(s), {len(changed)} changed"
+    if report.pruned:
+        summary += f", {len(report.pruned)} pruned"
+    click.echo("\n" + summary)
+
+    if check and changed:
+        raise SystemExit(1)

ggraft-1.0.0/src/ggraft/cli/commands/common.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ggraft import config as config_module
+from ggraft.config import Config
+
+
+def load_config(config_path: str | None) -> Config:
+    return config_module.load(Path(config_path).resolve() if config_path else None)

ggraft-1.0.0/src/ggraft/cli/commands/init.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ggraft.config import CONFIG_NAME
+
+STARTER = '''# ggraft project configuration
+[base]
+version = "{version}"
+dir     = ".ggraft/base"
+source  = "assets/minecraft/shaders"
+
+[patches]
+dir = "patches"
+
+[output]
+dir    = "assets/minecraft/shaders"
+header = true
+'''
+
+
+@click.command()
+@click.argument("version", required=False)
+@click.option("--force", is_flag=True, help="overwrite an existing file")
+def init(version: str | None, force: bool) -> None:
+    """Write a starter ggraft.toml.
+
+    VERSION is recorded as base.version.
+    """
+    destination = Path.cwd() / CONFIG_NAME
+    if destination.exists() and not force:
+        raise click.ClickException(
+            f"{CONFIG_NAME} already exists here (use --force to overwrite)"
+        )
+    destination.write_text(STARTER.format(version=version or "26.3"), encoding="utf-8")
+    click.echo(f"wrote {destination}")

ggraft-1.0.0/src/ggraft/cli/commands/pull.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from ggraft.cli.commands.common import load_config
+from ggraft.config import Config
+from ggraft.sources import McMeta
+
+
+def _stamp(config: Config, version: str) -> dict[str, str]:
+    return {"version": version, "repo": config.repo, "source": config.source}
+
+
+def _read_stamp(path: Path) -> dict[str, str] | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None   # unknown contents are stale contents
+    return data if isinstance(data, dict) else None
+
+
+def _write_stamp(path: Path, stamp: dict[str, str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(stamp, indent=2) + "\n", encoding="utf-8")
+
+
+@click.command()
+@click.argument("version", required=False)
+@click.option("--force", is_flag=True, help="refetch even if a base exists")
+@click.option("--token", envvar="GITHUB_TOKEN", help="GitHub token [env: GITHUB_TOKEN]")
+@click.option("-j", "--jobs", type=click.IntRange(min=1), default=8,
+              show_default=True, help="parallel downloads")
+@click.pass_obj
+def pull(config_path: str | None, version: str | None, force: bool,
+         token: str | None, jobs: int) -> None:
+    """Fetch vanilla bases from mcmeta.
+
+    VERSION defaults to base.version in ggraft.toml.
+    """
+    cfg = load_config(config_path)
+    version = version or cfg.require_version()
+    client = McMeta(cfg.repo, token=token)
+    tag = client.tag_for(version)
+
+    wanted = _stamp(cfg, version)
+    held = _read_stamp(cfg.base_state)
+    present = cfg.base_dir.is_dir() and any(cfg.base_dir.iterdir())
+
+    if present and held == wanted and not force:
+        click.echo(f"base already present at {cfg.base_dir} (use --force to refetch)")
+        return
+    if present and held != wanted:
+        was = held.get("version") if held else None
+        click.echo(f"{cfg.base_dir} holds {was or 'an unrecorded base'}; replacing it")
+
+    click.echo(f"listing {cfg.source} at {tag} ...")
+    blobs = client.list_blobs(tag, cfg.source)
+    click.echo(f"fetching {len(blobs)} file(s) into {cfg.base_dir} ...")
+
+    client.download(tag, cfg.source, blobs, cfg.base_dir, workers=jobs)
+    _write_stamp(cfg.base_state, wanted)
+    click.echo(f"pulled {len(blobs)} file(s) from {cfg.repo}@{tag}")

ggraft-1.0.0/src/ggraft/cli/commands/targets.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import click
+
+from ggraft.cli.commands.common import load_config
+from ggraft.patching import engine, patch as patch_module
+
+
+@click.command()
+@click.option("-t", "--target", "filters", multiple=True, metavar="GLOB",
+              help="filter by glob (repeatable)")
+@click.pass_obj
+def targets(config_path: str | None, filters: tuple[str, ...]) -> None:
+    """Show which patches hit which targets."""
+    cfg = load_config(config_path)
+    patches = patch_module.load_all(cfg.patch_dir)
+
+    click.echo(f"{len(patches)} patch(es) in {cfg.patch_dir}:")
+    for item in patches:
+        click.echo(f"  {item.name:<24} {len(item.injections)} injection(s)"
+                   f"  <- {item.path.name}")
+    click.echo()
+    for item in engine.plan(cfg, patches, only=list(filters) or None):
+        click.echo(f"  {item.target:<38} {', '.join(item.patch_names)}")