tamagoarc 1.0.0__tar.gz

tamagoarc-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Hatch
+        run: pip install hatch
+      - name: Build
+        run: hatch build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tamagoarc-1.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Virtual environments
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+*.so
+dist/
+build/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local settings
+local.toml
+
+# frida-server, for local dev
+frida-server.exe
+
+# Nonfree test samples (real game data, not distributable)
+src/tamago/tests/*/nonfree/

tamagoarc-1.0.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 1.0.0 — 2026-04-14
+
+Initial release.
+
+### Features
+
+- Unified CLI (`tamago`) with `extract`, `create`, and `identify` commands
+- Auto-detection of archive formats by magic bytes
+- Python API for reading and writing archives
+- Plugin system for format handlers and XP3 encryption schemes
+
+### Supported formats
+
+- **XP3** ([KiriKiri](https://github.com/kenkyuuka/research-vault/blob/main/engines/KiriKiri.md)) — extract and create, with encryption support
+- **DET** ([μ-GameOperationSystem](https://github.com/kenkyuuka/research-vault/blob/main/engines/%CE%BC-GameOperationSystem.md)) — extract and create, ATM and AT2 index formats
+- **GSP** ([AGSD](https://github.com/kenkyuuka/research-vault/blob/main/engines/AGSD.md)) — extract and create
+- **ARC** (AdvHD / WillPlus V2) — extract and create, with script decryption and LZSS decompression
+
+### XP3 encryption
+
+- Automatic encryption detection (TPM hash lookup, XP3 structure hash, probing)
+- Built-in schemes: hash-xor, fixed-xor, null, poringsoft, cxcrypt, pinpoint
+- Known-game database (`encryption_library.toml`)
+
+### Images
+
+- TLG image decoding (TLG5, TLG6) with optional Pillow integration

tamagoarc-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Kenkyuuka <kenkyuuka@proton.me>
+
+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.

tamagoarc-1.0.0/Makefile

@@ -0,0 +1,13 @@
+.PHONY: test
+test:
+	hatch run test
+
+.PHONY: reinstall
+reinstall:
+	hatch env prune && hatch env create
+
+.PHONY: help
+help:                ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk -F ':.*## ' '{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help

tamagoarc-1.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: tamagoarc
+Version: 1.0.0
+Summary: Multi-format game archive tool
+Project-URL: Homepage, https://github.com/kenkyuuka/tamago
+Project-URL: Issues, https://github.com/kenkyuuka/tamago/issues
+Project-URL: Source, https://github.com/kenkyuuka/tamago
+Author-email: Kenkyuuka <kenkyuuka@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: construct>=2.10
+Provides-Extra: images
+Requires-Dist: pillow>=9.0; extra == 'images'

tamagoarc-1.0.0/README.md

@@ -0,0 +1,114 @@
+# tamago
+
+Multi-format game archive toolkit.
+
+Requires Python 3.10 or later.
+
+## Supported formats
+
+| Format | Engine | Extract | Create |
+|--------|--------|:-------:|:------:|
+| XP3    | [KiriKiri](https://github.com/kenkyuuka/research-vault/blob/main/engines/KiriKiri.md) | yes | yes |
+| DET    | [μ-GameOperationSystem](https://github.com/kenkyuuka/research-vault/blob/main/engines/%CE%BC-GameOperationSystem.md) | yes | yes |
+| GSP    | [AGSD](https://github.com/kenkyuuka/research-vault/blob/main/engines/AGSD.md) | yes | yes |
+| ARC    | AdvHD (WillPlus V2) | yes | yes |
+
+## Installation
+
+```console
+pip install tamagoarc
+```
+
+To enable TLG image conversion, install with the `images` extra:
+
+```console
+pip install tamagoarc[images]
+```
+
+## Usage
+
+### tamago CLI
+
+tamago auto-detects archive formats by magic bytes and, for XP3 archives, automatically identifies the correct encryption scheme.
+
+```console
+# Identify an archive's format
+tamago identify data.xp3
+
+# Extract an archive (auto-detects format and encryption)
+tamago extract data.xp3 output_dir
+
+# Use format subcommands for format-specific options
+tamago xp3 extract data.xp3 output_dir --encryption hash-xor --key 3
+tamago det create source_dir output.det --index-format atm
+
+# Create an archive (format must be specified)
+tamago create --format xp3 source_dir output.xp3
+```
+
+### Python API
+
+```python
+from tamago.formats.xp3 import XP3File
+
+# Extract an archive
+with XP3File("data.xp3") as xp3:
+    xp3.extract_all("output_dir")
+
+# Extract with explicit encryption
+from tamago.formats.xp3.encryption import HashXorEncryption
+
+enc = HashXorEncryption(shift=3)
+with XP3File("data.xp3", encryption=enc) as xp3:
+    xp3.extract_all("output_dir")
+
+# Auto-detect encryption
+from tamago.formats.xp3.detect import auto_detect
+
+enc = auto_detect("data.xp3")
+with XP3File("data.xp3", encryption=enc) as xp3:
+    xp3.extract_all("output_dir")
+
+# Create an archive
+from pathlib import Path
+
+with XP3File("output.xp3", "x") as xp3:
+    xp3.write_all(Path("source_dir"))
+```
+
+## XP3 Encryption
+
+XP3 archives used by KiriKiri games are often encrypted with a game-specific scheme implemented in a `.tpm` plugin. tamago supports the encryption used by several games (including automatic detection of the encryption).
+
+If the game you are interested in is not supported, please raise an issue, including a VNDB link to the game.
+
+## Development
+
+This project uses [Hatch](https://hatch.pypa.io/) as the build system.
+
+### Setup
+
+```console
+pip install hatch
+```
+
+### Running tests
+
+```console
+hatch run test                    # run all tests
+hatch run test -k test_name       # run a single test by name
+hatch run cov                     # tests + coverage report
+```
+
+### Linting and formatting
+
+```console
+hatch run lint:style     # check style (ruff + black)
+hatch run lint:typing    # type checking (mypy)
+hatch run lint:fmt       # auto-format (black + ruff --fix)
+hatch run lint:all       # style + typing
+```
+
+## License
+
+tamago is distributed under the terms of the [MIT license](LICENSE).

tamagoarc-1.0.0/hatch_build.py

@@ -0,0 +1,36 @@
+"""Custom hatch build hook to compile the TLG C accelerator extension."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sysconfig
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    PLUGIN_NAME = 'custom'
+
+    def initialize(self, version, build_data):
+        src = os.path.join(self.root, 'src', 'tamago', 'formats', 'xp3', '_tlg_accel.c')
+        if not os.path.exists(src):
+            return
+
+        ext_suffix = sysconfig.get_config_var('EXT_SUFFIX') or '.so'
+        out_name = f'_tlg_accel{ext_suffix}'
+        out_path = os.path.join(self.root, 'src', 'tamago', 'formats', 'xp3', out_name)
+        include = sysconfig.get_path('include')
+
+        try:
+            subprocess.check_call(
+                ['gcc', '-O2', '-shared', '-fPIC', f'-I{include}', '-o', out_path, src],
+                stderr=subprocess.PIPE,
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            # C compilation failed; pure-Python fallback will be used at runtime.
+            return
+
+        # Include the compiled .so in the wheel.
+        rel_path = os.path.join('tamago', 'formats', 'xp3', out_name)
+        build_data['force_include'][out_path] = rel_path

tamagoarc-1.0.0/local.toml.example

@@ -0,0 +1,3 @@
+[paths]
+# Directory containing installed KiriKiri games (used by scripts/survey_installed_games.py)
+# scan_dir = "/path/to/installed/games"

tamagoarc-1.0.0/pyproject.toml

@@ -0,0 +1,218 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tamagoarc"
+dynamic = ["version"]
+description = "Multi-format game archive tool"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = []
+authors = [
+  { name = "Kenkyuuka", email = "kenkyuuka@proton.me" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = ["construct>=2.10"]
+
+[project.urls]
+Homepage = "https://github.com/kenkyuuka/tamago"
+Issues = "https://github.com/kenkyuuka/tamago/issues"
+Source = "https://github.com/kenkyuuka/tamago"
+
+[project.optional-dependencies]
+images = ["Pillow>=9.0"]
+
+[project.scripts]
+tamago = "tamago.cli:main"
+
+[project.entry-points."tamago.formats"]
+xp3 = "tamago.formats.xp3.handler:XP3Handler"
+det = "tamago.formats.det.handler:DETHandler"
+gsp = "tamago.formats.gsp.handler:GSPHandler"
+advhd = "tamago.formats.advhd.handler:ARCHandler"
+
+[project.entry-points."tamago.formats.xp3.encryption"]
+fixed-xor = "tamago.formats.xp3.encryption.fixed_xor:FixedXorEncryption"
+hash-xor = "tamago.formats.xp3.encryption.hash_xor:HashXorEncryption"
+null = "tamago.formats.xp3.encryption.null:NullEncryption"
+poringsoft = "tamago.formats.xp3.encryption.hash_derived:PoringSoftEncryption"
+cxcrypt = "tamago.formats.xp3.encryption.cxcrypt:CxEncryption"
+pinpoint = "tamago.formats.xp3.encryption.pinpoint:PinPointEncryption"
+
+[tool.hatch.build.hooks.custom]
+
+[tool.hatch.version]
+path = "src/tamago/__about__.py"
+
+[tool.hatch.envs.default]
+dependencies = [
+  "coverage[toml]>=6.5",
+  "pytest",
+  "pytest-xdist",
+  "frida-tools",
+  "Pillow>=9.0",
+]
+
+[tool.hatch.envs.default.scripts]
+test = "pytest -n auto --maxprocesses 8 src/tamago/tests {args}"
+test-xp3 = "pytest -n auto --maxprocesses 8 src/tamago/tests/xp3 {args}"
+test-det = "pytest -n auto --maxprocesses 8 src/tamago/tests/det {args}"
+test-gsp = "pytest -n auto --maxprocesses 8 src/tamago/tests/gsp {args}"
+test-advhd = "pytest -n auto --maxprocesses 8 src/tamago/tests/advhd {args}"
+test-tamago = "pytest -n auto --maxprocesses 8 src/tamago/tests/test_cli.py {args}"
+test-nonfree = "pytest -n auto --maxprocesses 8 src/tamago/tests -m nonfree {args}"
+test-cov = "coverage run -m pytest -n auto --maxprocesses 8 src/tamago/tests {args}"
+
+cov-report = [
+  "- coverage combine",
+  "coverage report",
+]
+cov = [
+  "test-cov",
+  "cov-report",
+]
+
+[tool.hatch.envs.hatch-test]
+extra-dependencies = [
+  "Pillow>=9.0",
+]
+
+[[tool.hatch.envs.all.matrix]]
+python = ["3.10", "3.11", "3.12"]
+
+[tool.hatch.envs.lint]
+dependencies = [
+  "black>=23.1.0",
+  "mypy>=1.0.0",
+  "pytest",
+  "ruff>=0.0.243",
+]
+[tool.hatch.envs.lint.scripts]
+typing = "mypy --install-types --non-interactive {args:src/tamago}"
+style = [
+  "ruff check {args:.}",
+  "black --check --diff {args:.}",
+]
+fmt = [
+  "black {args:.}",
+  "ruff check --fix {args:.}",
+  "style",
+]
+all = [
+  "style",
+  "typing",
+]
+
+[tool.black]
+target-version = ["py310"]
+line-length = 120
+skip-string-normalization = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+extend-exclude = ["scripts", "packages"]
+[tool.ruff.lint]
+select = [
+  "A",
+  "ARG",
+  "B",
+  "C",
+  "DTZ",
+  "E",
+  "EM",
+  "F",
+  "FBT",
+  "I",
+  "ICN",
+  "ISC",
+  "N",
+  "PLC",
+  "PLE",
+  "PLR",
+  "PLW",
+  "Q",
+  "RUF",
+  "S",
+  "T",
+  "TID",
+  "UP",
+  "W",
+  "YTT",
+]
+ignore = [
+  # Allow non-abstract empty methods in abstract base classes
+  "B027",
+  # Allow boolean positional values in function calls, like `dict.get(... True)`
+  "FBT002", "FBT003",
+  # Ignore checks for possible passwords
+  "S105", "S106", "S107",
+  # Ignore complexity
+  "C901", "PLR0911", "PLR0912", "PLR0913", "PLR0915",
+  # Quote style managed by black (skip-string-normalization = true)
+  "Q000",
+  # Allow string/f-string literals in exceptions
+  "EM101", "EM102",
+  # Allow implicit string concatenation on one line
+  "ISC001",
+  # Allow print() in CLI and diagnostic code
+  "T201",
+  # Allow conditional/lazy imports not at top level
+  "PLC0415",
+  # Allow raise without from in except blocks
+  "B904",
+]
+unfixable = [
+  # Don't touch unused imports
+  "F401",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["tamago"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests can use magic values, assertions, and relative imports
+"**/tests/**/*" = ["ARG002", "F401", "PLR2004", "RUF059", "S101", "TID252"]
+"**/src/**/*" = ["A002", "ARG002", "RUF023", "S101", "TID252"]
+
+[tool.mypy]
+[[tool.mypy.overrides]]
+module = "identify_encryption"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: pure logic tests with no filesystem or external dependencies",
+    "integration: tests that read/write XP3 files or use the detection pipeline",
+    "nonfree: tests that require real game data in nonfree/ directories",
+]
+
+[tool.coverage.run]
+source_pkgs = ["tamago"]
+branch = true
+parallel = true
+omit = [
+  "src/tamago/__about__.py",
+]
+
+[tool.coverage.paths]
+tamago = ["src/tamago", "*/tamago/src/tamago"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]