mcserver-cli 3.0.0__tar.gz → 4.0.0.dev0__tar.gz

{mcserver_cli-3.0.0 → mcserver_cli-4.0.0.dev0}/CHANGELOG.md

@@ -9,9 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Paper and Purpur as server software
+- New `--game-version` and `--loader` options to the `search` command
+- New `--search-sort` and `--search-limit` options to the `init` command
+- 
+
+### Changed
+
+- Better `search` info message
+- slug_index.json is now a global cache
+
+### Fixes
+
+- Typo in the `add` command help
+
+## [3.0.0] - 2026-08-18
+
+### Added
+
+- Command to stop the Minecraft server
+- Paper and Purpur server software
 - Metadata to keep information of what version of MCServer is used
-- State to keep information of a running MCServer to avoid conflict
+- State to keep information of a running MCServer to avoid conflicting command
+- Listing whitelisted players
+- Listing operator players
+
+### Changed
+
+- Uh... add, search, and show, are being worked on (they're not available for now)
+- The codebase is now bigger with small gain (for the user)
 
 ## [2.0.0] - 2026-06-14
 
@@ -187,7 +212,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Better mod conflict error
 - Faster mod resolving
 
-[unreleased]: https://github.com/Othecat35/MCServer/compare/v2.0.0...HEAD
+[unreleased]: https://github.com/Othecat35/MCServer/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/Othecat35/MCServer/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/Othecat35/MCServer/compare/v1.13.16...v2.0.0
 [1.13.16]: https://github.com/Othecat35/MCServer/compare/v1.13.15...v1.13.16
 [1.13.15]: https://github.com/Othecat35/MCServer/compare/v1.13.14...v1.13.15

mcserver_cli-4.0.0.dev0/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# License
+
+By submitting a pull request, you agree that your contribution is licensed under the MIT License.
+
+# Development
+
+- Python >= 3.14
+- Install with `pip install -e .`
+- Use `black` to reformat code

mcserver_cli-4.0.0.dev0/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Othecat35
+
+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.

{mcserver_cli-3.0.0 → mcserver_cli-4.0.0.dev0}/NOTES.txt

@@ -119,22 +119,27 @@ mod indexing, don't forget! don't remind me the... 3rd time?
 Gemini suggest adding "status" command and get ram usage info, sure but not now. oh good idea I guess
 
 Things that MCServer can touch (In theory):
+
+XDG Cache
+- mcserver
+  - slug_index.json
+
+
+Home Directory
+- .cache # Failback if XDG Cache is not set
+  - mcserver
+    - slug_index.json
+
+
 Server Root
 - .mcserver/
-  - caches/
-    - modrinth/
-      - versions/
-        - <project_id>.json
   - configs/
     - launcher.json
     - modrinth.json
     - server.json
   - modrinth/
-    - slug_index.json
-    - projects/
-      - <project_id>
-        - metadata.json
-        - relationships.json
+    - projects_records/
+      - <project_id>.json
   - tempfiles/
     - <file_hash>
     - <url_hash> #if file hash does not exist, use hash from digesting the URL
@@ -239,32 +244,99 @@ I definitely broke my promise. (oops)
 - init command could take some sort of "target dir"
 - make src/mcserver/modrinth/projects.py into a dir, ans inside it we have metadata.py and relationship.py
 - flowchart TD
-    A[Did you fix a bug?]
-    A -- Yes --> B[It's fix]
-    A -- No --> C[Did you change functionality or affect UI?]
+  A[Did you fix a bug?]
+  A -- Yes --> B[It's fix]
+
+  A -- No --> C[Did you change functionality or affect UI?]
+  C -- Yes --> D[It's feat]
+
+  C -- No --> E[Did you add or change tests?]
+  E -- Yes --> F[It's test]
 
-    C -- Yes --> D[It's feat]
-    C -- No --> E[Did you add or change tests?]
+  E -- No --> G[Did you change code style or formatting?]
+  G -- Yes --> H[It's style]
 
-    E -- Yes --> F[It's test]
-    E -- No --> G[Did you change code style or formatting?]
+  G -- No --> I[Did you make changes to documentation?]
+  I -- Yes --> J[It's docs]
 
-    G -- Yes --> H[It's style]
-    G -- No --> I[Did you make changes to documentation?]
+  I -- No --> K[Did you change things related to build or deploy operations?]
+  K -- Yes --> L[It's build]
 
-    I -- Yes --> J[It's docs]
-    I -- No --> K[Did you change things related to build or deploy operations?]
+  K -- No --> M[Did you change something related to devops, infrastructure or backups?]
+  M -- Yes --> N[It's ops]
 
-    K -- Yes --> L[It's build]
-    K -- No --> M[Did you change something related to devops, infrastructure or backups?]
+  M -- No --> O[Did you complete a maintenance task or other non-code task?]
+  O -- Yes --> P[It's chore]
 
-    M -- Yes --> N[It's ops]
-    M -- No --> O[Did you complete a maintenance task or other non-code task?]
+  O -- No --> Q[Did you rewrite or restructure code specifically for performance?]
+  Q -- Yes --> R[It's perf]
 
-    O -- Yes --> P[It's chore]
-    O -- No --> Q[Did you rewrite or restructure code specifically for performance?]
+  Q -- No --> S[It's refactor]
 
-    Q -- Yes --> R[It's perf]
-    Q -- No --> S[It's refactor]
 - commit convention reference: https://gist.github.com/qoomon/5dfcdf8eec66a051ecd85625518cfd13
-- or more "official" looking: https://www.conventionalcommits.org/en/v1.0.0/
+- or more "official" looking: https://www.conventionalcommits.org/en/v1.0.0/
+
+Othecat35's Development Setup (For anyone if wondering):
+- VSCodium
+  - Extensions:
+    Pyright
+    Python
+
+that's all lol
+
+
+so, Modrinth has new way to represent which mod go to which environment right?
+so it make the older 'server_side' and 'client_side' obselete.
+but, most of my code rely on them.
+what if, I make a 'translator' between the new 'environment' and the old '*_side'?
+"How can you do that?" said Othecat35.
+well, just convert one value into two values. like if the environment is 'client_and_server',
+then the server_side is required and server_side is required
+required = you need this mod on this side
+recommended = this mod is recommended to be installed on this side
+optional = you can have this mod in this side, or not
+unsupported = basically this side is a side effect (it works but uh...)
+incompatible = this mod may crash on this side
+unknown = the dev doesn't even know their mod, wth
+the mapping table (as for 2026-09-05, basically the time I wrote this):
+| environment                   | server side   | client side   |
+|-------------------------------|---------------|---------------|
+| client_and_server             | required      | required      |
+| client_only                   | unsupported   | required      |
+| client_only_server_optional   | optional      | required      |
+| singleplayer_only             | incompactible | required      |
+| server_only                   | required      | unsupported   |
+| server_only_client_optional   | required      | optional      |
+| dedicated_server_only         | required      | incompactible |
+| client_or_server              | optional      | optional      |
+| client_or_server_prefers_both | recommended   | recommended   |
+| unknown                       | unknown       | unknown       |
+
+todo: move src/mcserver/server to src/mcserver/minecraft/server
+because it make more sense I think
+
+the export command... ".mcserver" and ".mrpack" format.
+.mrpack is Modrinth Modpack format, I already know that.
+.mcserver? what's this? a custom format? why?
+idk, maybe it can store the actual configs of the server
+the mod relationships, the metadata, etc
+the pros is can contain more metadata of the server.
+okay. but why? idk, maybe it looks cool? yea sure.
+
+warning for those who want to interact with .properties,
+consider bring your own module and don't use my parser.
+why? its not perfect, and, basically don't. I only make it
+to work with Minecraft, properties files like server.properties
+and eula.txt.
+
+4.0.0:
+no add/remove for whitelist yet
+no grant/revoke for op yet
+no update command yet
+and actually, no import command
+
+for the remove command, I would use the resolver I already had. But it would be more complicated once we're dealing with mod that shared dependencies with other. I don't know ;-; I haven't even finished the add commad yet, but it is in incremental so don't rush me >:c
+make a visualize command to visualize installed projects that output to graphviz format seems really cool
+we should merge the metadata.json and relationships.json back into one file :o
+
+look at myterious.py, idk why yiu thought it would be a good idea to make it more fun, and dynamic even.

{mcserver_cli-3.0.0 → mcserver_cli-4.0.0.dev0}/PKG-INFO

@@ -1,15 +1,14 @@
 Metadata-Version: 2.5
 Name: mcserver-cli
-Version: 3.0.0
+Version: 4.0.0.dev0
 Summary: A CLI tool to manage Minecraft: Java Edition servers.
 Project-URL: Homepage, https://github.com/Othecat35/MCServer
 Project-URL: Repository, https://github.com/Othecat35/MCServer.git
 Project-URL: Changelog, https://github.com/Othecat35/MCServer/blob/main/CHANGELOG.md
 Author-email: Othecat35 <othecat35@gmail.com>
-Maintainer-email: Othecat35 <othecat35@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Requires-Python: >=3.14
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 
 # MCServer
@@ -22,10 +21,13 @@ Supported platforms:
 - and Termux.
 
 ## Requirements
-- Python 3.14 or newer
+- Python 3.12 or newer (Python 3.14 is recommended)
 - JRE (depends on Minecraft version)
 
 ## How to install
+- Using pip:
+1. Run `pip install mcserver-cli`
+
 - System-wide (Requires root): 
 1. Download the `mcserver` script file from GitHub releases
 2. Move the file to `/usr/local/bin`
@@ -40,24 +42,29 @@ Supported platforms:
    - Run `fish_add_path ~/bin` if you're using FISH
 
 ## Usage
-- Add mods (and its dependencies): `mcserver add <mods>`
-- Import a modpack: `mcserver import [file]`
-- Initialize the server: `mcserver init [options]`
-- Manage operator status: `mcserver op`
-- Search mods from Modrinth: `mcserver search [<query>] [options]`
-- Show mod information from Modrinth: `mcserver show <mods>`
+- Initialize a server: `mcserver init [options]`
+- List operator players: `mcserver op list`
 - Start the server: `mcserver start`
 - Stop the server: `mcserver stop`
-- Manage the whitelist: `mcserver whitelist`
+- List whitelisted players: `mcserver whitelist list`
 
 ### Example
+- Create a 1.20.1 Fabric (0.19.5) server on current directory
 ```bash
-mcserver init --mc-version=1.20.1 --loader=fabric --loader-version=0.19.3
-mcserver search --no-filter thdilos
-mcserver show thdilos-fox-origin thdilos-fox-origin-expanded
-mcserver add thdilos-fox-origin-expanded lithium tick-stasis ferrite-core krypton
+mcserver init --mc-version=1.20.1 --loader=fabric --loader-version=0.19.5
 mcserver start
 ```
 
+- List all operator and whitelisted players on current directory
+```bash
+mcserver op list
+mcserver whitelist list
+```
+- Stop (sigterm) a server on current directory
+```bash
+mcserver stop
+```
+
+
 ## Note
 This is a **Personal Project**, things may be unstable.

{mcserver_cli-3.0.0 → mcserver_cli-4.0.0.dev0}/README.md

@@ -8,10 +8,13 @@ Supported platforms:
 - and Termux.
 
 ## Requirements
-- Python 3.14 or newer
+- Python 3.12 or newer (Python 3.14 is recommended)
 - JRE (depends on Minecraft version)
 
 ## How to install
+- Using pip:
+1. Run `pip install mcserver-cli`
+
 - System-wide (Requires root): 
 1. Download the `mcserver` script file from GitHub releases
 2. Move the file to `/usr/local/bin`
@@ -26,24 +29,29 @@ Supported platforms:
    - Run `fish_add_path ~/bin` if you're using FISH
 
 ## Usage
-- Add mods (and its dependencies): `mcserver add <mods>`
-- Import a modpack: `mcserver import [file]`
-- Initialize the server: `mcserver init [options]`
-- Manage operator status: `mcserver op`
-- Search mods from Modrinth: `mcserver search [<query>] [options]`
-- Show mod information from Modrinth: `mcserver show <mods>`
+- Initialize a server: `mcserver init [options]`
+- List operator players: `mcserver op list`
 - Start the server: `mcserver start`
 - Stop the server: `mcserver stop`
-- Manage the whitelist: `mcserver whitelist`
+- List whitelisted players: `mcserver whitelist list`
 
 ### Example
+- Create a 1.20.1 Fabric (0.19.5) server on current directory
 ```bash
-mcserver init --mc-version=1.20.1 --loader=fabric --loader-version=0.19.3
-mcserver search --no-filter thdilos
-mcserver show thdilos-fox-origin thdilos-fox-origin-expanded
-mcserver add thdilos-fox-origin-expanded lithium tick-stasis ferrite-core krypton
+mcserver init --mc-version=1.20.1 --loader=fabric --loader-version=0.19.5
 mcserver start
 ```
 
+- List all operator and whitelisted players on current directory
+```bash
+mcserver op list
+mcserver whitelist list
+```
+- Stop (sigterm) a server on current directory
+```bash
+mcserver stop
+```
+
+
 ## Note
 This is a **Personal Project**, things may be unstable.

mcserver_cli-4.0.0.dev0/a.py

@@ -0,0 +1,72 @@
+from typing import (
+    Literal,
+    Optional,
+    TypeAlias,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+# ---------- Define the same Literal three ways ----------
+type EnvModern = Literal["a", "b", "c"]  # PEP 695 (what you use)
+EnvClassic: TypeAlias = Literal["a", "b", "c"]  # 3.10 style
+inline = Literal["a", "b", "c"]  # plain value, no alias
+
+
+def show(label, fn):
+    try:
+        print(f"{label:48} → {fn()!r}")
+    except Exception as e:
+        print(f"{label:48} → {type(e).__name__}: {e}")
+
+
+print("=== PEP 695 `type` alias ===")
+print(f"type(EnvModern) = {type(EnvModern)}")
+show("get_args(EnvModern)", lambda: get_args(EnvModern))
+show("EnvModern.__value__", lambda: EnvModern.__value__)
+show("get_args(EnvModern.__value__)", lambda: get_args(EnvModern.__value__))
+show("EnvModern.__value__.__args__", lambda: EnvModern.__value__.__args__)
+show("EnvModern.__args__", lambda: EnvModern.__args__)
+show("get_origin(EnvModern)", lambda: get_origin(EnvModern))
+show("get_origin(EnvModern.__value__)", lambda: get_origin(EnvModern.__value__))
+show(
+    "frozenset(get_args(EnvModern.__value__))",
+    lambda: frozenset(get_args(EnvModern.__value__)),
+)
+show("EnvModern.__parameters__", lambda: EnvModern.__parameters__)
+
+print("\n=== Traditional `TypeAlias` ===")
+print(f"type(EnvClassic) = {type(EnvClassic)}")
+show("get_args(EnvClassic)", lambda: get_args(EnvClassic))
+show("EnvClassic.__args__", lambda: EnvClassic.__args__)
+show("get_origin(EnvClassic)", lambda: get_origin(EnvClassic))
+
+print("\n=== Inline `Literal` ===")
+print(f"type(inline) = {type(inline)}")
+show("get_args(inline)", lambda: get_args(inline))
+show("inline.__args__", lambda: inline.__args__)
+
+print("\n=== Union / Optional (matters for NotRequired[X | None]) ===")
+show("get_args(EnvModern | None)", lambda: get_args(EnvModern | None))
+show("get_args(Union[EnvModern, None])", lambda: get_args(Union[EnvModern, None]))
+show("get_args(Optional[EnvModern])", lambda: get_args(Optional[EnvModern]))
+show("get_args(Union[EnvClassic, None])", lambda: get_args(Union[EnvClassic, None]))
+
+type A = Literal["x", "y"]
+type B = Literal["z"]
+show("get_args(A | B)", lambda: get_args(A | B))
+show("get_args(Union[A, B])", lambda: get_args(Union[A, B]))
+
+print("\n=== get_type_hints (indirect path) ===")
+
+
+def f(x: EnvModern) -> None: ...
+
+
+try:
+    hints = get_type_hints(f)
+    print(f"hints['x'] = {hints['x']!r}")
+    show("get_args(hints['x'])", lambda: get_args(hints["x"]))
+except Exception as e:
+    print(f"get_type_hints failed: {type(e).__name__}: {e}")

{mcserver_cli-3.0.0 → mcserver_cli-4.0.0.dev0}/pyproject.toml

@@ -6,13 +6,10 @@ build-backend = "hatchling.build"
 name = "mcserver-cli"
 dynamic = ["version"]
 dependencies = []
-requires-python = ">= 3.14"
+requires-python = ">=3.12"
 authors = [
   {name = "Othecat35", email = "othecat35@gmail.com"}
 ]
-maintainers = [
-  { name = "Othecat35", email = "othecat35@gmail.com"}
-]
 description = "A CLI tool to manage Minecraft: Java Edition servers."
 readme = "README.md"
 license = "MIT"
@@ -24,7 +21,7 @@ Repository = "https://github.com/Othecat35/MCServer.git"
 Changelog = "https://github.com/Othecat35/MCServer/blob/main/CHANGELOG.md"
 
 [project.scripts]
-mcserver = "mcserver:__main__"
+mcserver = "mcserver.app:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/mcserver"]

mcserver_cli-4.0.0.dev0/src/mcserver/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.0.0.dev0"

{mcserver_cli-3.0.0 → mcserver_cli-4.0.0.dev0}/src/mcserver/app.py

@@ -1,24 +1,28 @@
-def main() -> None:
+def main():
     import sys
 
-    if (sys.argv[1] if len(sys.argv) > 1 else "") == "cake":
-        from .mysterious import nothing_to_see_here_move_along
-
-        nothing_to_see_here_move_along()
-
-    MIN_PYTHON_VERSION: tuple[int, int] = (3, 14)
+    MIN_PYTHON_VERSION: tuple[int, int] = (3, 12)
     if sys.version_info < MIN_PYTHON_VERSION:
         sys.exit(
             f"MCServer requires Python {'.'.join(map(str, MIN_PYTHON_VERSION))} or newer."
         )
 
+    if (sys.argv[1] if len(sys.argv) > 1 else "") == "uh...":
+        from .mysterious import nothing_to_see_here_move_along
+
+        nothing_to_see_here_move_along()
+
     import logging as log
     import os
 
     from . import cli
 
     debug_mode = os.getenv("MCSERVER_DEBUG") == "1"
-    log_level = log.DEBUG if debug_mode else log.INFO
-    log.basicConfig(level=log_level, format="[%(levelname)s]: %(message)s")
+    if debug_mode:
+        log.basicConfig(
+            level=log.DEBUG, format="[%(levelname)s] [%(module)s]: %(message)s"
+        )
+    else:
+        log.basicConfig(level=log.INFO, format="[%(levelname)s]: %(message)s")
 
     sys.exit(cli.main())

mcserver_cli-4.0.0.dev0/src/mcserver/caching.py

@@ -0,0 +1,16 @@
+import os
+from pathlib import Path
+
+cache_dir = Path.home() / ".cache"
+
+xdg_cache_dir = os.getenv("XDG_CACHE_DIR")
+if xdg_cache_dir:
+    cache_dir = Path(xdg_cache_dir)
+
+mcserver_cache_dir = cache_dir / "mcserver"
+
+
+def create_file(file_name: str, file_data: bytes):
+    mcserver_cache_dir.mkdir(parents=True, exist_ok=True)
+    cache_file = mcserver_cache_dir / file_name
+    cache_file.write_bytes(file_data)