cuhkit 1.0.0__py3-none-any.whl

cuhkit/__init__.py

@@ -0,0 +1,40 @@
+"""
+----------------------------------------------
+cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).
+https://github.com/cuhHub/cuhkit
+----------------------------------------------
+
+Copyright (C) 2026 cuhHub
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# // Main
+import sys
+from pathlib import Path
+
+__VERSION__ = "1.0.0"
+CUHKIT_DATA_PATH = Path.home() / ".cuhkit"
+CUHKIT_PACKAGE_PATH = Path(__file__).parent
+
+if getattr(sys, "frozen", False): # pyinstaller context
+    CUHKIT_PACKAGE_PATH = Path(sys._MEIPASS) / "cuhkit"
+
+from . import exceptions
+from . import log
+from . import libs
+from . import projects
+from . import credentials
+
+from . import cli_context
+from .cli import cli

cuhkit/__main__.py

@@ -0,0 +1,27 @@
+"""
+----------------------------------------------
+cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).
+https://github.com/cuhHub/cuhkit
+----------------------------------------------
+
+Copyright (C) 2026 cuhHub
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# // Imports
+from . import cli
+
+# // Main
+if __name__ == "__main__":
+    cli()

cuhkit/cli.py

@@ -0,0 +1,243 @@
+"""
+----------------------------------------------
+cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).
+https://github.com/cuhHub/cuhkit
+----------------------------------------------
+
+Copyright (C) 2026 cuhHub
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# // Imports
+import click
+from pathlib import Path
+from functools import wraps
+from typing import Callable
+
+from cuhkit import __VERSION__
+from cuhkit import projects
+from cuhkit import cli_context
+from cuhkit.log import set_logging_verbose, logger
+from cuhkit.exceptions import CredentialsException
+from cuhkit.projects import POSITION_PERSISTENT_DATA_KEY
+
+# // Main
+def requires_project(project_types: list[projects.ProjectType] | None = None):
+    """
+    Decorator for click commands that require a cuhkit project.
+    
+    Args:
+        project_type (projects.ProjectType | None): The type of project required, or None to allow any.
+    """
+
+    def decorator(function: Callable):
+        @wraps(function)
+        def wrapper(*args, **kwargs):
+            context = cli_context.get_context()
+
+            if context.project is None:
+                logger.error("No cuhkit project found in current directory, this command must be run in a cuhkit project directory.")
+                return
+            
+            if project_types is not None and context.project.project_type not in project_types:
+                logger.error(f"This command is not compatible with this cuhkit project. Current cuhkit project is not any of required types {project_types}, got {context.project.project_type}.")
+                return
+
+            return function(*args, **kwargs, project = context.project)
+        
+        return wrapper
+    
+    return decorator
+
+@click.group()
+@click.version_option(__VERSION__)
+@click.help_option()
+@click.pass_context
+@click.option("verbose", "--verbose", "-v", is_flag = True, help = "Enables verbose output.")
+def cli(context: click.Context, verbose: bool):
+    """
+    Main CLI entry point.
+    """
+    
+    logger.info("cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).")
+    
+    cli_context.setup_context(context)
+
+    if verbose:
+        set_logging_verbose(verbose)
+
+@cli.command()
+@click.argument(
+    "name",
+    type = str,
+    required = True
+)
+@click.option(
+    "--path", "-p",
+    type = click.Path(exists = True, file_okay = False, dir_okay = True, resolve_path = True, path_type = Path),
+    default = ".",
+    help = "The directory to create the project in."
+)
+@click.option(
+    "--type", "-t", "project_type",
+    type = click.Choice(projects.ProjectType, case_sensitive = False),
+    required = True,
+    help = "The type of the project to create."
+)
+def new(name: str, path: Path, project_type: projects.ProjectType):
+    """
+    Create a new cuhkit project.
+    """
+    
+    if projects.does_project_exist_at_path(path):
+        logger.error(f"A cuhkit project already exists at {path}.")
+        return
+
+    if project_type == projects.ProjectType.ADDON:
+        project = projects.create_addon_project(name, path)
+    elif project_type == projects.ProjectType.MOD:
+        project = projects.create_mod_project(name, path)
+
+    project.first_time_setup() 
+
+    logger.info(f"Created cuhkit project at {path}.")
+
+@cli.command()
+@cli_context.pass_context
+@requires_project()
+@click.confirmation_option(prompt = "Are you sure you want to delete this cuhkit project? Only the project file will be deleted. Any files you created will remain.")
+def delete(context: cli_context.CLIContext, project: projects.Project):
+    """
+    Deletes a cuhkit project.
+    """
+
+    project.delete()
+    logger.info("Deleted cuhkit project.")
+
+@cli.command()
+@cli_context.pass_context
+@requires_project([projects.ProjectType.ADDON, projects.ProjectType.MOD])
+def build(context: cli_context.CLIContext, project: projects.AddonProject | projects.ModProject):
+    """
+    Builds and syncs a cuhkit project.
+    """
+
+    project.build()
+    project.sync()
+    logger.info("Build complete.")
+    
+@cli.command()
+@cli_context.pass_context
+@requires_project([projects.ProjectType.ADDON, projects.ProjectType.MOD])
+def sync(context: cli_context.CLIContext, project: projects.AddonProject | projects.ModProject):
+    """
+    Sync a cuhkit project to Stormworks.
+    Note that the 'build' command also does this, but builds beforehand.
+    """
+
+    project.sync()
+    logger.info("Sync complete.")
+    
+@cli.command()
+@cli_context.pass_context
+@requires_project([projects.ProjectType.ADDON])
+def get_position(context: cli_context.CLIContext, project: projects.AddonProject):
+    """
+    Returns the last saved in-game position.
+    To use this, save a formatted matrix position to `_debug_pos` (key might be outdated, see source code) via cuhHub persistent data service.
+    """
+
+    position = project.get_position()
+    
+    if position is None:
+        logger.error(f"No position found. Save a formatted position to '{POSITION_PERSISTENT_DATA_KEY}' to cuhHub persistent data service via an addon.")
+        return
+    
+    logger.info(f"Position: {position} (copied to clipboard)")
+    
+@cli.command()
+@cli_context.pass_context
+@requires_project([projects.ProjectType.ADDON])
+def setup(context: cli_context.CLIContext, project: projects.AddonProject):
+    """
+    Sets up a cuhkit addon project for the first time.
+    Should only really be used after cloning an existing addon project.
+    """
+
+    project.setup()
+    logger.info("Addon project setup complete.")
+
+@cli.command()
+@cli_context.pass_context
+@requires_project([projects.ProjectType.ADDON, projects.ProjectType.MOD])
+@click.option(
+    "--server", "-s", "server_id",
+    type = int,
+    required = True,
+    help = "The ID of the server to publish to, or -1 for all servers."
+)
+@click.option(
+    "--dev", "-d", "is_dev",
+    is_flag = True,
+    help = "Whether or not to publish as a development build."
+)
+@click.confirmation_option(prompt = "Are you sure you want to publish this cuhkit project?")
+def publish(context: cli_context.CLIContext, project: projects.AddonProject | projects.ModProject, server_id: int, is_dev: bool):
+    """
+    Publish a cuhkit project to cuhHub.
+    """
+    
+    if isinstance(project, projects.AddonProject):
+        try:
+            project.publish(server_id, is_dev)
+            logger.info("Published cuhkit addon project.")
+        except CredentialsException:
+            logger.error("No API token found in credentials. Please set one using the `set-api-token` command.")
+        except FileNotFoundError:
+            logger.error("Missing `playlist.xml` file in addon project directory. Try building the addon or running first-time setup. If neither work, please manually create one.")
+    elif isinstance(project, projects.ModProject):
+        try:
+            project.publish(server_id, is_dev)
+            logger.info("Published cuhkit mod project.")
+        except CredentialsException:
+            logger.error("No API token found in credentials. Please set one using the `set-api-token` command.")
+
+@cli.command()
+@cli_context.pass_context
+@click.argument(
+    "api_token",
+    type = click.UUID,
+    required = True
+)
+def set_api_token(context: cli_context.CLIContext, api_token: str):
+    """
+    Sets the cuhHub API token in credentials.
+    """
+
+    context.credentials.api_token = api_token
+    context.credentials.save()
+    
+@cli.command()
+@cli_context.pass_context
+@click.confirmation_option(prompt = "Are you sure you want to delete your cuhkit credentials (API token, etc.)?")
+def delete_credentials(context: cli_context.CLIContext):
+    """
+    Deletes cuhkit credentials.
+    """
+
+    context.credentials.remove()
+    logger.info("Deleted cuhkit credentials.")
+    
+if __name__ == "__main__":
+    cli()

cuhkit/cli_context.py

@@ -0,0 +1,83 @@
+"""
+----------------------------------------------
+cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).
+https://github.com/cuhHub/cuhkit
+----------------------------------------------
+
+Copyright (C) 2026 cuhHub
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# // Imports
+import click
+from dataclasses import dataclass
+from typing import Callable
+from functools import wraps
+from pathlib import Path
+
+from cuhkit import projects
+
+from cuhkit.credentials import (
+    credentials,
+    Credentials
+)
+
+# // Main
+def pass_context(function: Callable):
+    """
+    Decorator to pass CLI context to functions.
+
+    Args:
+        function (Callable): The function to decorate.
+    """
+
+    @wraps(function)
+    def wrapper(*args, **kwargs):
+        return function(*args, **kwargs, context = get_context())
+    
+    return wrapper
+
+@dataclass
+class CLIContext:
+    """
+    Context object for the cuhkit CLI.
+    """
+
+    project: projects.AddonProject | projects.ModProject | None
+    credentials: Credentials
+
+def setup_context(context: click.Context):
+    """
+    Sets up the click context.
+
+    Args:
+        context (click.Context): The click context.
+    """
+
+    context.ensure_object(dict)
+
+    context.obj["context"] = CLIContext(
+        project = projects.load_project_at_path(Path.cwd()) if projects.does_project_exist_at_path(Path.cwd()) else None,
+        credentials = credentials
+    )
+    
+def get_context() -> CLIContext:
+    """
+    Returns the CLI context.
+
+    Returns:
+        CLIContext: The CLI context.
+    """
+
+    return click.get_current_context().obj["context"]

cuhkit/credentials.py

@@ -0,0 +1,106 @@
+"""
+----------------------------------------------
+cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).
+https://github.com/cuhHub/cuhkit
+----------------------------------------------
+
+Copyright (C) 2026 cuhHub
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# // Imports
+from pydantic import (
+    BaseModel,
+    UUID4
+)
+
+from pathlib import Path
+
+from cuhkit import CUHKIT_DATA_PATH
+from cuhkit.log import logger
+
+# // Main
+CREDENTIALS_PATH = CUHKIT_DATA_PATH / "credentials.json"
+
+class Credentials(BaseModel):
+    """
+    Base class for credentials
+    """
+    
+    api_token: UUID4 | None = None
+    path: Path
+
+    def save(self):
+        """
+        Save the credentials.
+        """
+        
+        logger.info(f"Saving credentials to {self.path}")
+        self.path.write_text(self.model_dump_json(indent = 3))
+        
+    def remove(self):
+        """
+        Remove the credentials.
+        """
+        
+        logger.info(f"Removing credentials from {self.path}")
+        self.path.unlink()
+    
+    @classmethod
+    def create_new(cls, path: Path):
+        """
+        Creates new credentials, saving it automatically.
+        
+        Args:
+            path (Path): The path to the credentials file.
+        """
+        
+        credentials = cls(path = path)
+        credentials.save()
+        
+        return credentials
+    
+    @classmethod
+    def try_load(cls, path: Path) -> Credentials:
+        """
+        Loads credentials from the file, or creating new and saving if it doesn't exist.
+        
+        Args:
+            path (Path): The path to the credentials file.
+        
+        Returns:
+            Credentials: The loaded credentials.
+        """
+        
+        if not path.exists():
+            logger.warning(f"No credentials found at {path}. Creating new.")
+            return cls.create_new(path)
+        
+        logger.debug(f"Getting credentials from: {path}")
+        
+        content = path.read_text()
+        return cls.model_validate_json(content)
+    
+def get_credentials() -> Credentials:
+    """
+    Loads credentials from a file.
+    
+    Returns:
+        Credentials: The loaded credentials.
+    """
+    
+    CREDENTIALS_PATH.parent.mkdir(parents = True, exist_ok = True)
+    return Credentials.try_load(CREDENTIALS_PATH)
+
+credentials = get_credentials()

cuhkit/exceptions.py

@@ -0,0 +1,80 @@
+"""
+----------------------------------------------
+cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).
+https://github.com/cuhHub/cuhkit
+----------------------------------------------
+
+Copyright (C) 2026 cuhHub
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# // Main
+__all__ = [
+    "CuhkitException",
+    "APIException",
+    "ProjectException",
+    "ProjectNotFoundException",
+    "ProjectLoadFailureException",
+    "ProjectAlreadyExistsException",
+    "CredentialsException"
+]
+
+class CuhkitException(Exception):
+    """
+    Base exception class for cuhkit.
+    """
+
+    pass
+
+class APIException(CuhkitException):
+    """
+    Exception class for API errors.
+    """
+
+    pass
+
+class ProjectException(CuhkitException):
+    """
+    Exception class for project errors.
+    """
+
+    pass
+
+class ProjectNotFoundException(ProjectException):
+    """
+    Exception class for when a cuhkit project is not found.
+    """
+
+    pass
+
+class ProjectLoadFailureException(ProjectException):
+    """
+    Exception class for when a cuhkit project fails to load.
+    """
+
+    pass
+
+class ProjectAlreadyExistsException(ProjectException):
+    """
+    Exception class for when a cuhkit project already exists.
+    """
+
+    pass
+
+class CredentialsException(CuhkitException):
+    """
+    Exception class for bad credentials.
+    """
+
+    pass

cuhkit/libs/__init__.py

@@ -0,0 +1,28 @@
+"""
+----------------------------------------------
+cuhkit - A CLI-oriented Python package for handling cuhHub Stormworks projects (addons/mods).
+https://github.com/cuhHub/cuhkit
+----------------------------------------------
+
+Copyright (C) 2026 cuhHub
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# // Imports
+from . import api
+from . import mod_builder
+from . import addon_builder
+from . import timeit
+from . import templates
+from . import requests