holocubic-cli-python 0.1.0a1__tar.gz

holocubic_cli_python-0.1.0a1/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+coverage/
+*.tgz
+.DS_Store
+Thumbs.db
+.cubic-test/
+.venv/
+__pycache__/
+.pytest_cache/
+target/

holocubic_cli_python-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim-1e
+
+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.

holocubic_cli_python-0.1.0a1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: holocubic-cli-python
+Version: 0.1.0a1
+Summary: Python CLI for HoloCubic DevTools file and app workflows
+Project-URL: Repository, https://github.com/Tim-1e/holocubic-cli
+Project-URL: Issues, https://github.com/Tim-1e/holocubic-cli/issues
+Author: Tim-1e
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,devtools,esp32,holocubic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# HoloCubic CLI — Python
+
+`cubic-py` is the Python implementation of the shared HoloCubic CLI v1
+contract. It supports the same device configuration, SD-card filesystem,
+recursive transfer, DevRun, and app workflows as the Node.js reference.
+
+The package requires Python 3.10 or newer. It is source-ready but has not been
+published to PyPI yet.
+
+## Installation from source
+
+```sh
+python -m venv .venv
+python -m pip install --editable .
+cubic-py --version
+```
+
+Activate `.venv` first if you want `cubic-py` available only inside the virtual
+environment. Connect and inspect a device with:
+
+```sh
+cubic-py device add desk 192.168.3.26
+cubic-py info
+cubic-py ls /sd/apps
+cubic-py push ./my-app /sd/apps/my-app
+```
+
+## Command overview
+
+```text
+cubic-py device add|list|use|remove
+cubic-py ping|info
+cubic-py ls|stat|cat|mkdir|mv|rm
+cubic-py push|upload
+cubic-py pull|download
+cubic-py devrun read|save|run
+cubic-py app list|install|remove
+```
+
+Use `--host` for one-off access, `--json` for scripts, and `--help` on a command
+for its transfer limits and safety options.
+
+## Development checks
+
+```sh
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m unittest discover -s tests -v
+python -m build
+python -m pip install .
+cubic-py --version
+```
+
+The API and CLI contracts live in [`../../spec`](../../spec).

holocubic_cli_python-0.1.0a1/README.md

@@ -0,0 +1,54 @@
+# HoloCubic CLI — Python
+
+`cubic-py` is the Python implementation of the shared HoloCubic CLI v1
+contract. It supports the same device configuration, SD-card filesystem,
+recursive transfer, DevRun, and app workflows as the Node.js reference.
+
+The package requires Python 3.10 or newer. It is source-ready but has not been
+published to PyPI yet.
+
+## Installation from source
+
+```sh
+python -m venv .venv
+python -m pip install --editable .
+cubic-py --version
+```
+
+Activate `.venv` first if you want `cubic-py` available only inside the virtual
+environment. Connect and inspect a device with:
+
+```sh
+cubic-py device add desk 192.168.3.26
+cubic-py info
+cubic-py ls /sd/apps
+cubic-py push ./my-app /sd/apps/my-app
+```
+
+## Command overview
+
+```text
+cubic-py device add|list|use|remove
+cubic-py ping|info
+cubic-py ls|stat|cat|mkdir|mv|rm
+cubic-py push|upload
+cubic-py pull|download
+cubic-py devrun read|save|run
+cubic-py app list|install|remove
+```
+
+Use `--host` for one-off access, `--json` for scripts, and `--help` on a command
+for its transfer limits and safety options.
+
+## Development checks
+
+```sh
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m unittest discover -s tests -v
+python -m build
+python -m pip install .
+cubic-py --version
+```
+
+The API and CLI contracts live in [`../../spec`](../../spec).

holocubic_cli_python-0.1.0a1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling>=1.26,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "holocubic-cli-python"
+version = "0.1.0a1"
+description = "Python CLI for HoloCubic DevTools file and app workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Tim-1e" }]
+keywords = ["holocubic", "esp32", "cli", "devtools"]
+dependencies = []
+
+[project.scripts]
+cubic-py = "holocubic_cli_python.cli:main"
+
+[project.urls]
+Repository = "https://github.com/Tim-1e/holocubic-cli"
+Issues = "https://github.com/Tim-1e/holocubic-cli/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/holocubic_cli_python"]

holocubic_cli_python-0.1.0a1/src/holocubic_cli_python/__init__.py

@@ -0,0 +1,3 @@
+"""Python implementation of the HoloCubic CLI."""
+
+__version__ = "0.1.0a1"

holocubic_cli_python-0.1.0a1/src/holocubic_cli_python/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

holocubic_cli_python-0.1.0a1/src/holocubic_cli_python/app.py

@@ -0,0 +1,85 @@
+"""Local HoloCubic app validation."""
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from .errors import CubicError, UsageError
+from .remote_path import remote_join
+
+
+@dataclass(frozen=True)
+class ValidatedApp:
+    source: Path
+    id: str
+    destination: str
+    entry: str
+
+    def public(self) -> dict[str, str]:
+        return {
+            "source": str(self.source),
+            "id": self.id,
+            "destination": self.destination,
+            "entry": self.entry,
+        }
+
+
+def validate_app_id(value: str) -> str:
+    app_id = value.strip()
+    if (
+        not app_id
+        or app_id in {".", ".."}
+        or app_id.startswith(".cubic-")
+        or "/" in app_id
+        or "\\" in app_id
+        or any(ord(character) < 32 for character in app_id)
+    ):
+        raise UsageError(f"Invalid app id: {value}")
+    remote_join("/sd/apps", app_id)
+    return app_id
+
+
+def _require_file(file_path: Path, label: str) -> None:
+    try:
+        if file_path.is_symlink() or not file_path.is_file():
+            raise OSError("not a regular file")
+    except OSError as error:
+        raise CubicError(
+            f"App {label} is missing or is not a regular file: {file_path}",
+            code="INVALID_APP",
+        ) from error
+
+
+def validate_app_directory(
+    directory: str | Path, requested_id: str | None = None
+) -> ValidatedApp:
+    source = Path(os.path.abspath(os.fspath(directory)))
+    if source.is_symlink() or not source.is_dir():
+        raise CubicError(
+            f"App source is not a regular directory: {source}", code="INVALID_APP"
+        )
+    info_path = source / "app.info"
+    _require_file(info_path, "metadata")
+    try:
+        info = info_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as error:
+        raise CubicError(
+            f"Unable to read app metadata: {info_path}", code="INVALID_APP"
+        ) from error
+    match = re.search(r"^\s*entry\s*=\s*(.+?)\s*$", info, flags=re.MULTILINE)
+    entry = match.group(1).strip() if match else "main.lua"
+    pure_entry = PurePosixPath(entry)
+    if (
+        not entry
+        or pure_entry.is_absolute()
+        or ".." in pure_entry.parts
+        or "\\" in entry
+    ):
+        raise CubicError(
+            f"app.info declares an unsafe entry: {entry}", code="INVALID_APP"
+        )
+    _require_file(source.joinpath(*pure_entry.parts), "entry")
+    _require_file(source / "main.lua", "main.lua")
+    app_id = validate_app_id(requested_id if requested_id is not None else source.name)
+    return ValidatedApp(source, app_id, remote_join("/sd/apps", app_id), entry)