fix(installer): auto-flatten nested zip/git directories on install and add ISSUES.md log

This commit is contained in:
Gravitiny Team
2026-10-03 04:09:38 +03:00
parent 964e3da667
commit d8f956f007
2 changed files with 65 additions and 16 deletions
+33
View File
@@ -0,0 +1,33 @@
# Gravitiny Engineering Issues & Resolution Log
This document records architectural hurdles, bugs, investigations, and verified solutions encountered during the engineering of Gravitiny Core and its applets ecosystem.
---
## Issue #001: Nested Directory Unwrapping during Git Clone and Zip Extraction
- **Component:** `gravitiny.src.installer.AppletInstaller`
- **Severity:** High (Broken Shim Execution)
- **Status:** Resolved
### Symptom
When running `gravitiny <applet>` through the manager, the applet executed successfully because local discovery scanned both workspace and user dotfiles. However, executing direct global shims (e.g. `lex books`) failed with:
```text
C:\Users\al3ph\AppData\Local\Programs\Python\Python313\python.exe: can't open file 'C:\Users\al3ph\.gravitiny\applets\lex\main.py': [Errno 2] No such file or directory
```
### Root Cause
When Gitea generates repository archive zips (e.g. `https://git.luxhebros.com/beerslayer/lex/archive/main.zip`), the zip payload contains a top-level directory matching the repository name (`lex/`). When extracted into `~/.gravitiny/applets/lex`, this caused a nested directory structure:
`~/.gravitiny/applets/lex/lex/main.py` instead of `~/.gravitiny/applets/lex/main.py`.
Additionally, Python's `shutil.move(src, dst)` moves the source folder *inside* the destination folder if the destination folder already exists.
### Solution
1. Added `AppletInstaller._flatten_if_nested(target_dir: Path)` static helper method.
2. The method inspects the extracted destination folder. If `main.py` or `manifest.json` is missing from the root and a single nested subfolder exists, it elevates all children files/folders to the root of `target_dir` and removes the redundant nested folder.
3. Updated both `_clone_git_repo` and `_download_and_extract_zip` pipelines to invoke `_flatten_if_nested`.
### Verification
Re-ran `python main.py install lex` and `python main.py install sec`. Confirmed that `main.py` is extracted directly to `C:\Users\al3ph\.gravitiny\applets\lex\main.py`. Verified that direct shim execution `lex books` runs cleanly and instantly.
---
+32 -16
View File
@@ -24,37 +24,53 @@ class AppletInstaller:
self.registry = RegistryClient() self.registry = RegistryClient()
self.shim_gen = ShimGenerator(bin_dir=self.bin_dir) self.shim_gen = ShimGenerator(bin_dir=self.bin_dir)
@staticmethod
def _flatten_if_nested(target_dir: Path) -> None:
"""Unwraps any single nested subfolder so that manifest.json and entrypoint live directly in target_dir root."""
if not target_dir.exists() or not target_dir.is_dir():
return
if (target_dir / "manifest.json").exists() or (target_dir / "main.py").exists():
return
children = [c for c in target_dir.iterdir() if c.is_dir() and not c.name.startswith(".")]
if len(children) == 1:
nested_dir = children[0]
for item in list(nested_dir.iterdir()):
target_item = target_dir / item.name
if target_item.exists():
if target_item.is_dir():
shutil.rmtree(target_item, ignore_errors=True)
else:
target_item.unlink(missing_ok=True)
shutil.move(str(item), str(target_dir))
shutil.rmtree(nested_dir, ignore_errors=True)
def _clone_git_repo(self, git_url: str, dest_dir: Path) -> bool: def _clone_git_repo(self, git_url: str, dest_dir: Path) -> bool:
"""Clones a git repository into destination directory.""" """Clones a git repository into destination directory."""
if dest_dir.exists(): if dest_dir.exists():
shutil.rmtree(dest_dir, ignore_errors=True) shutil.rmtree(dest_dir, ignore_errors=True)
dest_dir.parent.mkdir(parents=True, exist_ok=True)
try: try:
res = subprocess.run(["git", "clone", "--depth", "1", git_url, str(dest_dir)], capture_output=True) res = subprocess.run(["git", "clone", "--depth", "1", git_url, str(dest_dir)], capture_output=True)
return res.returncode == 0 if res.returncode == 0:
self._flatten_if_nested(dest_dir)
return True
return False
except Exception: except Exception:
return False return False
def _download_and_extract_zip(self, zip_url: str, dest_dir: Path) -> bool: def _download_and_extract_zip(self, zip_url: str, dest_dir: Path) -> bool:
"""Downloads a zip archive and extracts it into destination directory.""" """Downloads a zip archive and extracts it into destination directory."""
if dest_dir.exists():
shutil.rmtree(dest_dir, ignore_errors=True)
dest_dir.mkdir(parents=True, exist_ok=True)
try: try:
resp = requests.get(zip_url, timeout=10) resp = requests.get(zip_url, timeout=10)
if resp.status_code == 200: if resp.status_code == 200:
with zipfile.ZipFile(io.BytesIO(resp.content)) as zf: with zipfile.ZipFile(io.BytesIO(resp.content)) as zf:
# Find root folder in zip if nested zf.extractall(dest_dir)
temp_extract = dest_dir.parent / f"_tmp_{dest_dir.name}" self._flatten_if_nested(dest_dir)
zf.extractall(temp_extract)
# If single subfolder exists, move contents
extracted_children = list(temp_extract.iterdir())
if len(extracted_children) == 1 and extracted_children[0].is_dir():
if dest_dir.exists():
shutil.rmtree(dest_dir, ignore_errors=True)
shutil.move(str(extracted_children[0]), str(dest_dir))
shutil.rmtree(temp_extract, ignore_errors=True)
else:
if dest_dir.exists():
shutil.rmtree(dest_dir, ignore_errors=True)
shutil.move(str(temp_extract), str(dest_dir))
return True return True
except Exception: except Exception:
pass pass