bg3-core 1.0.0b1__tar.gz

bg3_core-1.0.0b1/.gitignore

@@ -0,0 +1,58 @@
+# ==============================================================================
+# Baldur's Gate 3 Mod Studio & Mod.io Toolkit - Git Ignore Rules
+# ==============================================================================
+
+# Secrets & Environment Configurations
+.env
+*.env
+.env.*.local
+
+# Python runtime & caches
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.eggs/
+.cache/
+
+# Virtual Environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDE & Editor Files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Operating System Files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Build artifacts, logs & archives
+*.log
+*.tmp
+*.bak
+*.pak
+*.loca
+*.zip
+
+# Scratch / temporary experimental folders
+scratch/
+
+# Externalized User Content (Ignore any local studio folders or accidental spills)
+build_guides/
+mods/
+my_mods/
+BG3_Mod_Studio/
+.agents/ledgers/artifacts-ledger.md

bg3_core-1.0.0b1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: bg3-core
+Version: 1.0.0b1
+Summary: Baldur's Gate 3 Mod Studio Core Runtime, Parsers, and API Client
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# bg3-core
+
+Foundational runtime, binary parsers, cross-platform path resolution, and mod.io REST API client for the **Baldur's Gate 3 Mod Studio** workspace.
+
+---
+
+## Domain Architecture & Scope
+
+`bg3-core` serves as the foundational, leaf-level dependency package in the monorepo DAG. It is designed to be completely independent of higher-level domain packages (`bg3-authoring` and `bg3-theorycraft`), providing low-level binary engines and runtime utilities that require zero external binary tools (such as LSLib's `divine.exe`, Wine, or .NET runtimes).
+
+```mermaid
+graph TD
+    Authoring["bg3-authoring"] --> Core["bg3-core"]
+    Theorycraft["bg3-theorycraft"] --> Core["bg3-core"]
+    CLI["bg3 CLI Router"] --> Core
+```
+
+---
+
+## Core Modules & Exported Interfaces
+
+| Module | Core Responsibility | Key Exported Symbols |
+| :--- | :--- | :--- |
+| `bg3_core.larian_parsers` | Larian binary formats, version encoding, and localization | `encode_version64()`, `decode_version64()`, `parse_loca_bytes()`, `compile_xml_bytes_to_loca()`, `split_larian_items()` |
+| `bg3_core.lspk` | Pure-Python LSPK v18 archive reader, builder, and unpacker | `LspkArchive`, `build_lspk_archive()`, `lz4_block_decompress()`, `lz4_frame_or_block_decompress()`, `decompress_pak_file_data()` |
+| `bg3_core.save_inspector` | Save game metadata extraction, AST audit, and mod pruning | `extract_save_metadata()`, `audit_against_modsettings()`, `prune_missing_mods_from_save()` |
+| `bg3_core.manage_saves` | Savegame discovery, backup, retention purging, and rescue | `discover_save_games()`, `handle_clean_missing()` |
+| `bg3_core.env_paths` | Cross-platform state, cache, config, and game path detection | `get_xdg_config_home()`, `get_xdg_cache_home()`, `get_xdg_data_home()`, `detect_bg3_appdata_dirs()`, `detect_bg3_install_dir()` |
+| `bg3_core.cli_common` | Stream separation, POSIX exit codes, and JSON envelopes | `OutputEmitter`, `ConsoleColor`, `ExitCode`, `format_json_response()`, `confirm_action()` |
+| `bg3_core.modio_client` | Authenticated mod.io v1 REST client | `ModioClient`, `ModioError`, `resolve_modio_token()` |
+| `bg3_core.tools` | Dynamic CLI argument parser introspection and registry | `build_parser_ast_registry()`, `search_tools()`, `verify_registry()`, `audit_skills()` |
+| `bg3_core.cli` | Central unified router for all workspace domains | `main()`, `build_parser()`, `dispatch_command()` |
+
+---
+
+## CLI Console Entrypoint
+
+This package registers the primary console script for the entire studio:
+
+```toml
+[project.scripts]
+bg3 = "bg3_core.cli:main"
+```
+
+### Common Commands Driven by `bg3-core`:
+- `bg3 tools list` — Discover all registered tools across packages.
+- `bg3 tools search <query>` — Search tools by semantic intent.
+- `bg3 tools info <tool>` — Inspect tool arguments and schemas.
+- `bg3 tools verify --audit-skills` — Programmatic health audit of agent skills.
+- `bg3 modio search <query>` — Search remote community mods on mod.io.
+- `bg3 modio sync` — Synchronize subscribed mods and download `.pak` packages.
+- `bg3 loadorder list` — Inspect active `modsettings.lsx` load order.
+- `bg3 save inspect latest` — Inspect save metadata and audit mod requirements.
+- `bg3 save clean-missing` — Prune missing mods to rescue corrupted saves.
+
+---
+
+## Cross-Platform Storage Architecture
+
+All state directories comply strictly with the XDG Base Directory specification on Linux/macOS and APPDATA specifications on Windows:
+
+- **Configuration**: `$XDG_CONFIG_HOME/bg3/env` (or `%APPDATA%\bg3\env`)
+- **Cache**: `$XDG_CACHE_HOME/bg3/` (or `%LOCALAPPDATA%\bg3\`)
+- **User Content**: `$XDG_DOCUMENTS_DIR/BG3_Mod_Studio/Mods/`
+- **Game VFS**: Automatically detects Steam Native, Proton (`compatdata/1086940/pfx`), WSL, and Windows installations.

bg3_core-1.0.0b1/README.md

@@ -0,0 +1,65 @@
+# bg3-core
+
+Foundational runtime, binary parsers, cross-platform path resolution, and mod.io REST API client for the **Baldur's Gate 3 Mod Studio** workspace.
+
+---
+
+## Domain Architecture & Scope
+
+`bg3-core` serves as the foundational, leaf-level dependency package in the monorepo DAG. It is designed to be completely independent of higher-level domain packages (`bg3-authoring` and `bg3-theorycraft`), providing low-level binary engines and runtime utilities that require zero external binary tools (such as LSLib's `divine.exe`, Wine, or .NET runtimes).
+
+```mermaid
+graph TD
+    Authoring["bg3-authoring"] --> Core["bg3-core"]
+    Theorycraft["bg3-theorycraft"] --> Core["bg3-core"]
+    CLI["bg3 CLI Router"] --> Core
+```
+
+---
+
+## Core Modules & Exported Interfaces
+
+| Module | Core Responsibility | Key Exported Symbols |
+| :--- | :--- | :--- |
+| `bg3_core.larian_parsers` | Larian binary formats, version encoding, and localization | `encode_version64()`, `decode_version64()`, `parse_loca_bytes()`, `compile_xml_bytes_to_loca()`, `split_larian_items()` |
+| `bg3_core.lspk` | Pure-Python LSPK v18 archive reader, builder, and unpacker | `LspkArchive`, `build_lspk_archive()`, `lz4_block_decompress()`, `lz4_frame_or_block_decompress()`, `decompress_pak_file_data()` |
+| `bg3_core.save_inspector` | Save game metadata extraction, AST audit, and mod pruning | `extract_save_metadata()`, `audit_against_modsettings()`, `prune_missing_mods_from_save()` |
+| `bg3_core.manage_saves` | Savegame discovery, backup, retention purging, and rescue | `discover_save_games()`, `handle_clean_missing()` |
+| `bg3_core.env_paths` | Cross-platform state, cache, config, and game path detection | `get_xdg_config_home()`, `get_xdg_cache_home()`, `get_xdg_data_home()`, `detect_bg3_appdata_dirs()`, `detect_bg3_install_dir()` |
+| `bg3_core.cli_common` | Stream separation, POSIX exit codes, and JSON envelopes | `OutputEmitter`, `ConsoleColor`, `ExitCode`, `format_json_response()`, `confirm_action()` |
+| `bg3_core.modio_client` | Authenticated mod.io v1 REST client | `ModioClient`, `ModioError`, `resolve_modio_token()` |
+| `bg3_core.tools` | Dynamic CLI argument parser introspection and registry | `build_parser_ast_registry()`, `search_tools()`, `verify_registry()`, `audit_skills()` |
+| `bg3_core.cli` | Central unified router for all workspace domains | `main()`, `build_parser()`, `dispatch_command()` |
+
+---
+
+## CLI Console Entrypoint
+
+This package registers the primary console script for the entire studio:
+
+```toml
+[project.scripts]
+bg3 = "bg3_core.cli:main"
+```
+
+### Common Commands Driven by `bg3-core`:
+- `bg3 tools list` — Discover all registered tools across packages.
+- `bg3 tools search <query>` — Search tools by semantic intent.
+- `bg3 tools info <tool>` — Inspect tool arguments and schemas.
+- `bg3 tools verify --audit-skills` — Programmatic health audit of agent skills.
+- `bg3 modio search <query>` — Search remote community mods on mod.io.
+- `bg3 modio sync` — Synchronize subscribed mods and download `.pak` packages.
+- `bg3 loadorder list` — Inspect active `modsettings.lsx` load order.
+- `bg3 save inspect latest` — Inspect save metadata and audit mod requirements.
+- `bg3 save clean-missing` — Prune missing mods to rescue corrupted saves.
+
+---
+
+## Cross-Platform Storage Architecture
+
+All state directories comply strictly with the XDG Base Directory specification on Linux/macOS and APPDATA specifications on Windows:
+
+- **Configuration**: `$XDG_CONFIG_HOME/bg3/env` (or `%APPDATA%\bg3\env`)
+- **Cache**: `$XDG_CACHE_HOME/bg3/` (or `%LOCALAPPDATA%\bg3\`)
+- **User Content**: `$XDG_DOCUMENTS_DIR/BG3_Mod_Studio/Mods/`
+- **Game VFS**: Automatically detects Steam Native, Proton (`compatdata/1086940/pfx`), WSL, and Windows installations.

bg3_core-1.0.0b1/bg3_core/bump_mod_version.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""
+bump_mod_version.py
+-------------------
+Inspects and updates semantic version numbers and Larian Version64 integers
+atomically across `Mods/<UUID>/meta.lsx` (and legacy `Projects/<UUID>/meta.lsx`),
+and keeps `my_mods/<slug>/README.md` in sync so documentation and metadata never drift.
+
+Features:
+- Encodes and decodes 64-bit integer versions: (major << 55) | (minor << 47) | (revision << 31) | build
+- Supports semantic increments: --build, --patch, --minor, --major, or explicit --set
+- Atomic update across meta.lsx and README.md
+- Clean regex-based replacement preserving exact XML and Markdown formatting
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+from bg3_core.env_paths import MY_MODS_DIR, REPO_ROOT, resolve_mod_dir
+from bg3_core.larian_parsers import (
+    calculate_version64,
+    decode_version64,
+    format_version_tuple,
+    parse_version_str,
+)
+
+WORKSPACE_ROOT = REPO_ROOT
+
+
+def find_mod_directories(mod_query: str = "") -> List[Path]:
+    """Find mod directories in my_mods matching query or return all."""
+    if not mod_query:
+        if not MY_MODS_DIR.exists():
+            return []
+        return sorted([d for d in MY_MODS_DIR.iterdir() if d.is_dir()])
+
+    try:
+        target = resolve_mod_dir(mod_query)
+        if target and target.is_dir():
+            return [target]
+    except Exception:
+        pass
+
+    if not MY_MODS_DIR.exists():
+        return []
+
+    query_norm = mod_query.strip().lower().replace("-", "").replace("_", "")
+    matches = []
+    for d in MY_MODS_DIR.iterdir():
+        if d.is_dir():
+            name_norm = d.name.lower().replace("-", "").replace("_", "")
+            if query_norm in name_norm:
+                matches.append(d)
+    return sorted(matches)
+
+
+def get_meta_files(mod_dir: Path) -> List[Path]:
+    """Find meta.lsx files in Mods/ (and legacy Projects/ with ModuleInfo) to update Version64."""
+    files = []
+    # Always include runtime module descriptors in Mods/
+    mods_dir = mod_dir / "Mods"
+    if mods_dir.exists():
+        for p in mods_dir.glob("*/meta.lsx"):
+            files.append(p)
+
+    # Only include Projects/ if it contains ModuleInfo (legacy scaffold)
+    proj_dir = mod_dir / "Projects"
+    if proj_dir.exists():
+        for p in proj_dir.glob("*/meta.lsx"):
+            try:
+                if '<node id="ModuleInfo">' in p.read_text(encoding="utf-8"):
+                    files.append(p)
+            except Exception:
+                pass
+    return files
+
+
+def read_mod_version(meta_path: Path) -> Tuple[int, int, int, int, int]:
+    """Extract Version64 integer and decoded tuple from a meta.lsx file."""
+    content = meta_path.read_text(encoding="utf-8")
+
+    # Locate ModuleInfo node first to avoid matching dependencies or PublishVersion
+    mod_info_match = re.search(r'<node\s+id="ModuleInfo">(.*?)</node>', content, re.DOTALL)
+    if mod_info_match:
+        target_text = mod_info_match.group(1)
+    else:
+        target_text = content
+
+    ver_match = re.search(r'<attribute\s+id="Version64"\s+type="int64"\s+value="(\d+)"\s*/>', target_text)
+    if not ver_match:
+        raise ValueError(f"Could not find Version64 attribute under ModuleInfo in {meta_path}")
+
+    raw_val = int(ver_match.group(1))
+    major, minor, rev, bld = decode_version64(raw_val)
+    return major, minor, rev, bld, raw_val
+
+
+def update_meta_version(meta_path: Path, new_v64: int, dry_run: bool = False) -> bool:
+    """Updates Version64 under ModuleInfo in meta.lsx while preserving formatting."""
+    content = meta_path.read_text(encoding="utf-8")
+
+    def replacer(match: re.Match[str]) -> str:
+        node_content = match.group(0)
+        updated_node = re.sub(
+            r'(<attribute\s+id="Version64"\s+type="int64"\s+value=")\d+("\s*/>)',
+            rf"\g<1>{new_v64}\g<2>",
+            node_content,
+            count=1,
+        )
+        return updated_node
+
+    new_content, count = re.subn(
+        r'<node\s+id="ModuleInfo">.*?</node>',
+        replacer,
+        content,
+        count=1,
+        flags=re.DOTALL,
+    )
+
+    if count == 0:
+        return False
+
+    if not dry_run:
+        meta_path.write_text(new_content, encoding="utf-8")
+    return True
+
+
+def update_readme_version(mod_dir: Path, new_version_str: str, dry_run: bool = False) -> bool:
+    """Update version line in README.md if present to avoid documentation drift."""
+    readme_path = mod_dir / "README.md"
+    if not readme_path.is_file():
+        return False
+
+    content = readme_path.read_text(encoding="utf-8")
+    pattern = r'(?i)(-\s*\*\*Version:\*\*\s*[`"]?|\*{0,2}Version:?\*{0,2}\s*[:=]?\s*[`"]?)(\d+(?:\.\d+)*)([`"]?)'
+    new_content, count = re.subn(
+        pattern,
+        rf"\g<1>{new_version_str}\g<3>",
+        content,
+        count=1,
+    )
+    if count == 0 or new_content == content:
+        return False
+
+    if not dry_run:
+        readme_path.write_text(new_content, encoding="utf-8")
+    return True
+
+
+def bump_version(
+    mod_name: str,
+    action: str = "show",
+    set_value: str = "",
+    dry_run: bool = False,
+    as_json: bool = False,
+) -> dict:
+    matched = find_mod_directories(mod_name)
+    if not matched:
+        raise ValueError(f"No mod found in my_mods/ matching query '{mod_name}'.")
+
+    target_mod = matched[0]
+    meta_files = get_meta_files(target_mod)
+    if not meta_files:
+        raise ValueError(f"No meta.lsx files found in {target_mod} under Projects/ or Mods/.")
+
+    # Read current from first file
+    major, minor, rev, bld, raw_val = read_mod_version(meta_files[0])
+    old_version_str = format_version_tuple((major, minor, rev, bld))
+
+    new_major, new_minor, new_rev, new_bld = major, minor, rev, bld
+
+    if action == "build":
+        new_bld += 1
+    elif action == "patch":
+        new_rev += 1
+        new_bld = 0
+    elif action == "minor":
+        new_minor += 1
+        new_rev = 0
+        new_bld = 0
+    elif action == "major":
+        new_major += 1
+        new_minor = 0
+        new_rev = 0
+        new_bld = 0
+    elif action == "set":
+        new_major, new_minor, new_rev, new_bld = parse_version_str(set_value)
+
+    new_v64 = calculate_version64(new_major, new_minor, new_rev, new_bld)
+    new_version_str = format_version_tuple((new_major, new_minor, new_rev, new_bld))
+
+    def _rel_path(p: Path, base: Path) -> str:
+        try:
+            return str(p.relative_to(base))
+        except ValueError:
+            return str(p)
+
+    updated_files = []
+    if action != "show":
+        for mf in meta_files:
+            if update_meta_version(mf, new_v64, dry_run=dry_run):
+                updated_files.append(_rel_path(mf, WORKSPACE_ROOT))
+        if update_readme_version(target_mod, new_version_str, dry_run=dry_run):
+            updated_files.append(_rel_path(target_mod / "README.md", WORKSPACE_ROOT))
+
+    result = {
+        "mod_name": target_mod.name,
+        "mod_dir": _rel_path(target_mod, WORKSPACE_ROOT),
+        "action": action,
+        "previous_version": old_version_str,
+        "previous_version64": raw_val,
+        "new_version": new_version_str,
+        "new_version64": new_v64,
+        "updated_files": updated_files,
+        "dry_run": dry_run,
+    }
+
+    if as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        if action == "show":
+            print(f"Mod '{target_mod.name}' version: {old_version_str} (Version64: {raw_val})")
+            for mf in meta_files:
+                print(f"  └ {_rel_path(mf, WORKSPACE_ROOT)}")
+        else:
+            action_desc = "[DRY-RUN] Would update" if dry_run else "Successfully updated"
+            print(f"{action_desc} '{target_mod.name}': {old_version_str} -> {new_version_str} (Version64: {new_v64})")
+            for f in updated_files:
+                print(f"  ✓ Updated {f}")
+
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Auto-generate and bump semantic versions and Larian Version64 integers in BG3 mods."
+    )
+    parser.add_argument("--mod", required=True, help="Mod name or folder in my_mods/ (e.g. paladins-call)")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--show", action="store_true", help="Display current version without modifying")
+    group.add_argument("--build", "-b", action="store_true", help="Increment build number (+1)")
+    group.add_argument("--patch", "-p", action="store_true", help="Increment patch/revision (+1) and reset build")
+    group.add_argument("--minor", "-m", action="store_true", help="Increment minor version (+1) and reset patch/build")
+    group.add_argument("--major", action="store_true", help="Increment major version (+1) and reset minor/patch/build")
+    group.add_argument("--set", type=str, help="Explicitly set version (e.g. 1.2.0.0)")
+
+    parser.add_argument("--dry-run", action="store_true", help="Preview version changes without writing to disk")
+    parser.add_argument("--json", action="store_true", help="Output result as JSON")
+
+    args = parser.parse_args()
+
+    action = "show"
+    set_val = ""
+    if args.build:
+        action = "build"
+    elif args.patch:
+        action = "patch"
+    elif args.minor:
+        action = "minor"
+    elif args.major:
+        action = "major"
+    elif args.set:
+        action = "set"
+        set_val = args.set
+
+    try:
+        bump_version(
+            mod_name=args.mod,
+            action=action,
+            set_value=set_val,
+            dry_run=args.dry_run,
+            as_json=args.json,
+        )
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()