samai-openbox 0.1.0__tar.gz

samai_openbox-0.1.0/LICENSE

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

samai_openbox-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: samai-openbox
+Version: 0.1.0
+Summary: CLI archive skill for AI agents — compress and extract zip, tar, tar.gz, 7z, rar, iso from one stable command. Part of the OpenBox project.
+Author-email: SamAI Group <dev@samai.cc>
+License: MIT
+Project-URL: Homepage, https://openbox.samai.cc
+Project-URL: Documentation, https://openbox.samai.cc/ai-agent.html
+Project-URL: Source, https://github.com/samaidev/openbox
+Project-URL: Issues, https://github.com/samaidev/openbox/issues
+Project-URL: OpenBox desktop app, https://openbox.samai.cc/download.html
+Keywords: openbox,archiver,compression,extraction,ai-agent,cli,llm,agent,skill,zip,tar,tar.gz,7z,rar,iso,samai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Topic :: Utilities
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# samai-openbox
+
+> CLI archive skill for AI agents — one stable command to compress and extract every common archive format.
+
+[![PyPI version](https://img.shields.io/pypi/v/samai-openbox.svg)](https://pypi.org/project/samai-openbox/)
+[![Python 3.8+](https://img.shields.io/pypi/pyversions/samai-openbox.svg)](https://pypi.org/project/samai-openbox/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/samaidev/openbox/blob/main/LICENSE)
+
+**samai-openbox** is a tiny, dependency-light Python package that exposes the
+[OpenBox](https://openbox.samai.cc) archiver engine as a single CLI command —
+`samai-openbox` — so any LLM agent with shell access can compress and extract
+archives without remembering six different flag syntaxes.
+
+## Why does this exist?
+
+LLM agents are great at writing shell commands, but they consistently get
+archive syntax wrong. One stable CLI fixes that:
+
+- `tar -czvf` vs `tar -xzvf` vs `7z a` vs `7z x` vs `zip -r` vs `unzip` — agents hallucinate.
+- Path-traversal protection varies by tool. OpenBox blocks `../../etc/passwd`-style entries at extraction time.
+- JSON output mode lets agents parse archive contents in their reasoning loop.
+
+## Install
+
+```bash
+# Standard
+pip install samai-openbox
+
+# Or with pipx (recommended for isolated CLI tools)
+pipx install samai-openbox
+
+# Verify
+samai-openbox --version
+samai-openbox --help
+```
+
+Works on Python 3.8+. Pure-Python implementation using stdlib `zipfile` and
+`tarfile`; shells out to the system `7z` / `7zz` / `7za` for 7z, and `unrar`
+for rar (only if those formats are actually used).
+
+## The CLI in 60 seconds
+
+Five verbs cover everything an agent needs to do with archives.
+
+### Compress files into an archive
+
+```bash
+# Auto-detects format from output extension: .zip .tar .tar.gz .7z
+samai-openbox compress report.pdf photos/ -o backup.zip
+
+# Force compression level (0-9, default 6)
+samai-openbox compress src/ -o release.tar.gz --level 9
+
+# 7z compression (requires 7z/7zz/7za on PATH)
+samai-openbox compress bigfile.bin -o archive.7z
+```
+
+### Extract an archive
+
+```bash
+# Auto-creates destination if missing
+samai-openbox extract backup.zip -d ./restored
+
+# Works for every supported format
+samai-openbox extract legacy.rar -d ./legacy
+samai-openbox extract cd-image.iso -d ./cd-contents
+```
+
+### List archive contents
+
+```bash
+# Human-readable
+samai-openbox list backup.zip
+
+# Machine-readable JSON — perfect for agent reasoning
+samai-openbox list backup.zip --json
+```
+
+Example JSON output:
+
+```json
+{
+  "archive": "backup.zip",
+  "format": "zip",
+  "entries": [
+    {"name": "report.pdf",   "size": 2516582, "modified": "2024-08-15T10:23:00Z"},
+    {"name": "photos/",      "size": 0,       "modified": "2024-08-15T10:24:00Z", "is_dir": true},
+    {"name": "photos/01.jpg", "size": 4409111, "modified": "2024-08-14T18:11:00Z"}
+  ]
+}
+```
+
+### Test archive integrity
+
+```bash
+# Verifies CRCs without extracting — exits non-zero on corruption
+samai-openbox test backup.zip
+```
+
+### Show version & supported formats
+
+```bash
+samai-openbox --version
+samai-openbox formats
+```
+
+## Format support matrix
+
+| Format  | Compress  | Extract  | Notes                                   |
+|---------|:---------:|:--------:|-----------------------------------------|
+| zip     | ✓         | ✓        | stdlib `zipfile`, deflate or store       |
+| tar     | ✓         | ✓        | stdlib `tarfile`                         |
+| tar.gz  | ✓         | ✓        | `tarfile` + gzip, 5 levels               |
+| 7z      | ✓*        | ✓*       | requires `7z` / `7zz` / `7za` on PATH    |
+| rar     | —         | ✓*       | requires `unrar` on PATH                 |
+| iso     | —         | ✓*       | requires `7z` (handles ISO 9660)         |
+
+`*` = via external CLI. Install with:
+- 7-Zip: <https://www.7-zip.org/download.html> (Windows) · `brew install 7zip` (macOS) · `sudo apt install p7zip-full` (Linux)
+- unrar: <https://www.rarlab.com/rar_add.htm> (Windows) · `brew install unrar` (macOS) · `sudo apt install unrar` (Linux)
+
+## Path-traversal safety
+
+`extract` blocks any archive entry whose absolute path would escape the
+target directory. So an archive containing `../../etc/passwd` extracts the
+file into `<target>/etc/passwd` instead of `/etc/passwd`. Safe to point at
+untrusted downloads.
+
+## ClawHub skill spec
+
+Drop this into your agent's skill catalog so it knows when and how to call OpenBox:
+
+```yaml
+# skill.yaml
+name: openbox-archive
+version: 0.1.0
+description: Compress and extract archives (zip, tar, tar.gz, 7z, rar, iso)
+command: samai-openbox
+install: pip install samai-openbox
+verbs:
+  - name: compress
+    usage: samai-openbox compress <files...> -o <archive> [--level 0-9]
+    formats_out: [zip, tar, tar.gz, 7z]
+  - name: extract
+    usage: samai-openbox extract <archive> -d <dir>
+    formats_in: [zip, tar, tar.gz, 7z, rar, iso]
+  - name: list
+    usage: samai-openbox list <archive> [--json]
+  - name: test
+    usage: samai-openbox test <archive>
+safety:
+  - Extraction blocks path-traversal entries (../../etc/passwd)
+  - No network calls · no telemetry · no auto-update
+  - Exits non-zero on any error — safe to chain with &&
+```
+
+## Use as a Python module
+
+```python
+from samai_openbox import compress, extract, list_archive, test_archive
+
+# Compress
+compress(["report.pdf", "photos/"], "backup.zip", level=6)
+
+# Extract (path-traversal safe)
+extract("backup.zip", "./restored")
+
+# List (returns a list of dicts)
+entries = list_archive("backup.zip")
+for e in entries:
+    print(e["name"], e["size"], e.get("modified"))
+
+# Verify integrity
+ok = test_archive("backup.zip")
+```
+
+## Agent conversation example
+
+> **User:** Pack the `reports/` folder into a `.zip` for email, but skip anything larger than 10 MB. Then list what's in the archive so I can sanity-check.
+>
+> **Agent (using samai-openbox):**
+> ```bash
+> # 1. Find files under 10 MB in reports/
+> find reports/ -type f -size -10M -print0 | \
+>   xargs -0 samai-openbox compress -o reports-email.zip
+>
+> # 2. List the result as JSON for verification
+> samai-openbox list reports-email.zip --json
+> ```
+> Done. `reports-email.zip` contains 23 files totalling 47.2 MB (after compression from 89.4 MB). Three files over 10 MB were excluded: `reports/q3-raw-data.csv`, `reports/audit-full.pdf`, and `reports/appendix-exhibits.pptx`. Want me to send them separately as a `.tar.gz`?
+
+## License
+
+MIT — same as the OpenBox desktop app. See [LICENSE](https://github.com/samaidev/openbox/blob/main/LICENSE).
+
+## See also
+
+- **OpenBox desktop app** — graphical archiver for Windows / macOS / Linux: <https://openbox.samai.cc>
+- **Source code** — <https://github.com/samaidev/openbox>
+- **SamAI Group public-welfare projects** — <https://samai.cc#public-welfare>
+
+OpenBox is a SamAI Group public-welfare open-source project. Free, forever.

samai_openbox-0.1.0/README.md

@@ -0,0 +1,202 @@
+# samai-openbox
+
+> CLI archive skill for AI agents — one stable command to compress and extract every common archive format.
+
+[![PyPI version](https://img.shields.io/pypi/v/samai-openbox.svg)](https://pypi.org/project/samai-openbox/)
+[![Python 3.8+](https://img.shields.io/pypi/pyversions/samai-openbox.svg)](https://pypi.org/project/samai-openbox/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/samaidev/openbox/blob/main/LICENSE)
+
+**samai-openbox** is a tiny, dependency-light Python package that exposes the
+[OpenBox](https://openbox.samai.cc) archiver engine as a single CLI command —
+`samai-openbox` — so any LLM agent with shell access can compress and extract
+archives without remembering six different flag syntaxes.
+
+## Why does this exist?
+
+LLM agents are great at writing shell commands, but they consistently get
+archive syntax wrong. One stable CLI fixes that:
+
+- `tar -czvf` vs `tar -xzvf` vs `7z a` vs `7z x` vs `zip -r` vs `unzip` — agents hallucinate.
+- Path-traversal protection varies by tool. OpenBox blocks `../../etc/passwd`-style entries at extraction time.
+- JSON output mode lets agents parse archive contents in their reasoning loop.
+
+## Install
+
+```bash
+# Standard
+pip install samai-openbox
+
+# Or with pipx (recommended for isolated CLI tools)
+pipx install samai-openbox
+
+# Verify
+samai-openbox --version
+samai-openbox --help
+```
+
+Works on Python 3.8+. Pure-Python implementation using stdlib `zipfile` and
+`tarfile`; shells out to the system `7z` / `7zz` / `7za` for 7z, and `unrar`
+for rar (only if those formats are actually used).
+
+## The CLI in 60 seconds
+
+Five verbs cover everything an agent needs to do with archives.
+
+### Compress files into an archive
+
+```bash
+# Auto-detects format from output extension: .zip .tar .tar.gz .7z
+samai-openbox compress report.pdf photos/ -o backup.zip
+
+# Force compression level (0-9, default 6)
+samai-openbox compress src/ -o release.tar.gz --level 9
+
+# 7z compression (requires 7z/7zz/7za on PATH)
+samai-openbox compress bigfile.bin -o archive.7z
+```
+
+### Extract an archive
+
+```bash
+# Auto-creates destination if missing
+samai-openbox extract backup.zip -d ./restored
+
+# Works for every supported format
+samai-openbox extract legacy.rar -d ./legacy
+samai-openbox extract cd-image.iso -d ./cd-contents
+```
+
+### List archive contents
+
+```bash
+# Human-readable
+samai-openbox list backup.zip
+
+# Machine-readable JSON — perfect for agent reasoning
+samai-openbox list backup.zip --json
+```
+
+Example JSON output:
+
+```json
+{
+  "archive": "backup.zip",
+  "format": "zip",
+  "entries": [
+    {"name": "report.pdf",   "size": 2516582, "modified": "2024-08-15T10:23:00Z"},
+    {"name": "photos/",      "size": 0,       "modified": "2024-08-15T10:24:00Z", "is_dir": true},
+    {"name": "photos/01.jpg", "size": 4409111, "modified": "2024-08-14T18:11:00Z"}
+  ]
+}
+```
+
+### Test archive integrity
+
+```bash
+# Verifies CRCs without extracting — exits non-zero on corruption
+samai-openbox test backup.zip
+```
+
+### Show version & supported formats
+
+```bash
+samai-openbox --version
+samai-openbox formats
+```
+
+## Format support matrix
+
+| Format  | Compress  | Extract  | Notes                                   |
+|---------|:---------:|:--------:|-----------------------------------------|
+| zip     | ✓         | ✓        | stdlib `zipfile`, deflate or store       |
+| tar     | ✓         | ✓        | stdlib `tarfile`                         |
+| tar.gz  | ✓         | ✓        | `tarfile` + gzip, 5 levels               |
+| 7z      | ✓*        | ✓*       | requires `7z` / `7zz` / `7za` on PATH    |
+| rar     | —         | ✓*       | requires `unrar` on PATH                 |
+| iso     | —         | ✓*       | requires `7z` (handles ISO 9660)         |
+
+`*` = via external CLI. Install with:
+- 7-Zip: <https://www.7-zip.org/download.html> (Windows) · `brew install 7zip` (macOS) · `sudo apt install p7zip-full` (Linux)
+- unrar: <https://www.rarlab.com/rar_add.htm> (Windows) · `brew install unrar` (macOS) · `sudo apt install unrar` (Linux)
+
+## Path-traversal safety
+
+`extract` blocks any archive entry whose absolute path would escape the
+target directory. So an archive containing `../../etc/passwd` extracts the
+file into `<target>/etc/passwd` instead of `/etc/passwd`. Safe to point at
+untrusted downloads.
+
+## ClawHub skill spec
+
+Drop this into your agent's skill catalog so it knows when and how to call OpenBox:
+
+```yaml
+# skill.yaml
+name: openbox-archive
+version: 0.1.0
+description: Compress and extract archives (zip, tar, tar.gz, 7z, rar, iso)
+command: samai-openbox
+install: pip install samai-openbox
+verbs:
+  - name: compress
+    usage: samai-openbox compress <files...> -o <archive> [--level 0-9]
+    formats_out: [zip, tar, tar.gz, 7z]
+  - name: extract
+    usage: samai-openbox extract <archive> -d <dir>
+    formats_in: [zip, tar, tar.gz, 7z, rar, iso]
+  - name: list
+    usage: samai-openbox list <archive> [--json]
+  - name: test
+    usage: samai-openbox test <archive>
+safety:
+  - Extraction blocks path-traversal entries (../../etc/passwd)
+  - No network calls · no telemetry · no auto-update
+  - Exits non-zero on any error — safe to chain with &&
+```
+
+## Use as a Python module
+
+```python
+from samai_openbox import compress, extract, list_archive, test_archive
+
+# Compress
+compress(["report.pdf", "photos/"], "backup.zip", level=6)
+
+# Extract (path-traversal safe)
+extract("backup.zip", "./restored")
+
+# List (returns a list of dicts)
+entries = list_archive("backup.zip")
+for e in entries:
+    print(e["name"], e["size"], e.get("modified"))
+
+# Verify integrity
+ok = test_archive("backup.zip")
+```
+
+## Agent conversation example
+
+> **User:** Pack the `reports/` folder into a `.zip` for email, but skip anything larger than 10 MB. Then list what's in the archive so I can sanity-check.
+>
+> **Agent (using samai-openbox):**
+> ```bash
+> # 1. Find files under 10 MB in reports/
+> find reports/ -type f -size -10M -print0 | \
+>   xargs -0 samai-openbox compress -o reports-email.zip
+>
+> # 2. List the result as JSON for verification
+> samai-openbox list reports-email.zip --json
+> ```
+> Done. `reports-email.zip` contains 23 files totalling 47.2 MB (after compression from 89.4 MB). Three files over 10 MB were excluded: `reports/q3-raw-data.csv`, `reports/audit-full.pdf`, and `reports/appendix-exhibits.pptx`. Want me to send them separately as a `.tar.gz`?
+
+## License
+
+MIT — same as the OpenBox desktop app. See [LICENSE](https://github.com/samaidev/openbox/blob/main/LICENSE).
+
+## See also
+
+- **OpenBox desktop app** — graphical archiver for Windows / macOS / Linux: <https://openbox.samai.cc>
+- **Source code** — <https://github.com/samaidev/openbox>
+- **SamAI Group public-welfare projects** — <https://samai.cc#public-welfare>
+
+OpenBox is a SamAI Group public-welfare open-source project. Free, forever.

samai_openbox-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "samai-openbox"
+version = "0.1.0"
+description = "CLI archive skill for AI agents — compress and extract zip, tar, tar.gz, 7z, rar, iso from one stable command. Part of the OpenBox project."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "SamAI Group", email = "dev@samai.cc"}
+]
+requires-python = ">=3.8"
+keywords = [
+    "openbox",
+    "archiver",
+    "compression",
+    "extraction",
+    "ai-agent",
+    "cli",
+    "llm",
+    "agent",
+    "skill",
+    "zip",
+    "tar",
+    "tar.gz",
+    "7z",
+    "rar",
+    "iso",
+    "samai"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Archiving",
+    "Topic :: System :: Archiving :: Compression",
+    "Topic :: Utilities",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[project.urls]
+Homepage = "https://openbox.samai.cc"
+Documentation = "https://openbox.samai.cc/ai-agent.html"
+Source = "https://github.com/samaidev/openbox"
+Issues = "https://github.com/samaidev/openbox/issues"
+"OpenBox desktop app" = "https://openbox.samai.cc/download.html"
+
+[project.scripts]
+samai-openbox = "samai_openbox.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+samai_openbox = ["py.typed"]

samai_openbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

samai_openbox-0.1.0/src/samai_openbox/__init__.py

@@ -0,0 +1,23 @@
+"""samai-openbox — CLI archive skill for AI agents.
+
+One stable command to compress and extract every common archive format.
+Pure-Python implementation using stdlib zipfile/tarfile; shells out to the
+system 7z/7zz/7za for 7z and ISO, and unrar for rar.
+
+See https://openbox.samai.cc/ai-agent.html for the full agent guide.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["compress", "extract", "list_archive", "test_archive", "formats"]
+
+from .core import (
+    compress,
+    extract,
+    list_archive,
+    test_archive,
+    formats,
+    OpenBoxError,
+)
+
+# CLI version string mirrors the desktop app versioning scheme.
+CLI_VERSION = f"samai-openbox {__version__} (pure-python)"

samai_openbox-0.1.0/src/samai_openbox/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m samai_openbox ...` as an alias for `samai-openbox ...`."""
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())