peridot-cli 0.4.1__tar.gz

peridot_cli-0.4.1/LICENSE

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

peridot_cli-0.4.1/PKG-INFO

@@ -0,0 +1,417 @@
+Metadata-Version: 2.4
+Name: peridot-cli
+Version: 0.4.1
+Summary: Visual CLI for portable configuration bundles
+Author: Francisco Puga Lojo
+Project-URL: Homepage, https://github.com/pugafran/peridot
+Project-URL: Repository, https://github.com/pugafran/peridot
+Project-URL: Issues, https://github.com/pugafran/peridot/issues
+Project-URL: Changelog, https://github.com/pugafran/peridot/blob/main/CHANGELOG.md
+Keywords: dotfiles,backup,cli,config,portable,terminal
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography<46.0.0,>=42.0.0
+Requires-Dist: questionary<3.0.0,>=2.1.0
+Requires-Dist: rich<15.0.0,>=13.7.0
+Requires-Dist: zstandard<1.0.0,>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+![Showcase](misc/showcase.png)
+
+# Peridot
+
+![CI](https://github.com/pugafran/peridot/actions/workflows/ci.yml/badge.svg)
+
+Current release: `0.4.1`. See `CHANGELOG.md` for release notes.
+
+Peridot es una herramienta de terminal para empaquetar configuraciones en bundles `.peridot`, inspeccionarlos antes de aplicar nada y restaurarlos en otra maquina con una UX visual cuidada.
+
+La idea es simple:
+
+- creas un bundle con tus dotfiles o carpetas de config
+- el bundle lleva una ficha visible con metadata, plataforma objetivo y listado de archivos
+- el contenido va comprimido y cifrado, pero el `manifest.json` queda accesible para poder revisar el paquete antes de aplicarlo
+- todo ocurre en terminal; no hay dashboard web ni dependencia de frontend externo
+
+Peridot comprime y luego cifra cada fichero. Eso reduce tamaño, pero puede hacer `pack` mas lento. Por defecto ahora usa compresion rapida (`compression_level = 1`) para priorizar velocidad. El codec principal es `zstd`; si la dependencia no esta disponible en ese Python, cae automaticamente a `gzip`. El contenedor `.peridot` exterior no recomprime payloads ya cifrados, asi que `pack` es mas rapido que antes.
+
+## Que es un `.peridot`
+
+Un archivo `.peridot` es un ZIP con esta estructura:
+
+```text
+my-setup.peridot
+├── manifest.json
+└── payloads/
+    ├── 0001-....bin
+    ├── 0002-....bin
+    └── ...
+```
+
+`manifest.json` contiene la ficha del bundle:
+
+- nombre y descripcion
+- sistema objetivo: `macos`, `linux`, `windows` o `any`
+- shell o runtime principal: `fish`, `zsh`, `bash`, `powershell`, etc.
+- arquitectura objetivo
+- tags
+- host y usuario que generaron el bundle
+- numero de archivos y peso total
+- lista de archivos con `path`, `mode`, `sha256` y payload asociado
+
+Los payloads contienen el contenido real de cada fichero, comprimido con `zstd` cuando compensa y con fallback a `gzip` si ese Python no tiene `zstandard`, y cifrado con `AES-GCM`.
+
+## Instalacion
+
+### Windows (recomendado): pipx
+
+Nota: el nombre en PyPI será **peridot-cli** ("peridot" ya está ocupado).
+
+`pipx` instala CLIs de Python en un entorno aislado y te deja el comando en PATH.
+
+1) Instala **Python 3.11+** (desde python.org o Microsoft Store) y asegúrate de que está en PATH.
+2) Instala `pipx`:
+
+```powershell
+python -m pip install --user pipx
+python -m pipx ensurepath
+```
+
+Cierra y vuelve a abrir la terminal.
+
+3) Instala Peridot:
+
+Si está publicado en PyPI:
+
+```powershell
+pipx install peridot-cli
+peridot --version
+```
+
+Si quieres instalarlo desde GitHub:
+
+```powershell
+pipx install "git+https://github.com/pugafran/peridot.git"
+peridot --version
+```
+
+### macOS / Linux
+
+Recomendado (modo dev, con tests):
+
+```bash
+./install.sh
+# opcional: instala dependencias de desarrollo (pytest, etc.)
+PERIDOT_INSTALL_DEV=1 ./install.sh
+
+peridot --version
+```
+
+Con `pip`:
+
+```bash
+python3 -m pip install .
+```
+
+Durante desarrollo:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+```
+
+Tests:
+
+```bash
+. .venv/bin/activate
+pytest -q
+```
+
+Instalacion automatica del repo:
+
+```bash
+./install.sh
+```
+
+Eso crea una `.venv`, instala Peridot en modo editable y deja el comando `peridot` enlazado en `~/.local/bin/peridot`.
+
+## Quickstart (3 comandos)
+
+```bash
+peridot init
+peridot pack "Mi bundle" --output mi-bundle.peridot ~/.config
+peridot apply mi-bundle.peridot --dry-run
+```
+
+Notas:
+- Si ejecutas `pack` sin TTY (scripts/CI) y no pasas nombre, Peridot genera uno por defecto.
+- Recomendación: prueba siempre primero con `--dry-run`.
+
+Si quieres incluir tambien dependencias de desarrollo (por ejemplo `pytest`):
+
+```bash
+PERIDOT_INSTALL_DEV=1 ./install.sh
+```
+
+## Flujo principal
+
+Generar o comprobar la clave:
+
+```bash
+peridot keygen
+```
+
+Abrir el modo visual:
+
+```bash
+peridot ui
+```
+
+`peridot ui` abre un command center en terminal con:
+
+- tabla de bundles `.peridot` detectados en el directorio actual
+- catalogo clasificado de configuraciones detectables
+- hub visual de acciones
+- tabla de presets de dotfiles
+- editor de settings persistentes
+- asistente de empaquetado
+- inspeccion guiada
+- aplicacion guiada con `dry-run`, target y backups
+
+Empaquetar tu setup actual:
+
+```bash
+peridot pack "MacBook Fish Setup" \
+  --description "Dotfiles personales para macOS + fish" \
+  --platform macos \
+  --shell fish \
+  --tag work \
+  --tag terminal \
+  --output macbook-fish.peridot \
+  ~/.config/fish ~/.gitconfig ~/.zshrc
+```
+
+Si quieres priorizar velocidad:
+
+```bash
+peridot pack --compression-level 0 --jobs 8
+```
+
+Si quieres priorizar tamaño:
+
+```bash
+peridot pack --compression-level 9
+```
+
+Si quieres fijar defaults persistentes:
+
+```bash
+peridot settings
+peridot settings --show
+peridot settings --set compression_level=0 --set jobs=8
+```
+
+El editor `settings` muestra una barra textual del nivel de compresion y deja claro el tradeoff:
+
+- `0` = mas rapido, bundles mas grandes
+- `1-2` = rapido
+- `3-6` = equilibrado
+- `7-9` = mas pequeño, mas lento
+
+`jobs` controla cuantos workers usa `pack` en paralelo. En general, subirlo ayuda cuando hay muchos archivos y CPU libre.
+
+Peridot intenta ademas autorregular `pack` si detecta poca memoria disponible: puede arrancar con menos concurrencia, bajar trabajos en vuelo por mitades hasta `1` si hace falta, y volver a subirlos gradualmente hasta el maximo pedido cuando la memoria se recupera. Antes del empaquetado veras tambien una fase explicita de `Scanning files`, que suele ser la parte lenta antes de que aparezcan los avisos de sensibles.
+
+Si ejecutas simplemente:
+
+```bash
+peridot pack
+```
+
+Peridot entra en modo asistido y te va preguntando:
+
+- nombre del bundle
+- descripcion
+- plataforma objetivo
+- shell principal
+- arquitectura
+- tags
+- grupos clasificados de configuracion con toggles tipo checkbox
+- edicion visual de rutas sugeridas con checkboxes en terminal
+- rutas manuales solo como fallback
+- nombre del archivo de salida
+
+Puedes ver ese catalogo sin empezar un bundle:
+
+```bash
+peridot catalog
+```
+
+Tambien puedes arrancar desde un preset de dotfiles:
+
+```bash
+peridot pack --preset macos-fish
+peridot pack --preset linux-zsh
+peridot pack --preset windows-powershell
+peridot pack --preset custom
+```
+
+Presets disponibles:
+
+- `macos-fish`
+- `macos-zsh`
+- `linux-zsh`
+- `linux-bash`
+- `windows-powershell`
+
+Inspeccionar la ficha antes de tocar nada:
+
+```bash
+peridot inspect macbook-fish.peridot --files
+```
+
+Previsualizar una aplicacion sin escribir:
+
+```bash
+peridot apply macbook-fish.peridot --dry-run
+```
+
+Aplicar el bundle con backups previos:
+
+```bash
+peridot apply macbook-fish.peridot \
+  --backup-dir ~/.peridot-backups \
+  --target ~
+```
+
+Comparar un bundle con tu sistema antes de aplicar:
+
+```bash
+peridot diff macbook-fish.peridot --target ~
+```
+
+Verificar integridad:
+
+```bash
+peridot verify macbook-fish.peridot
+peridot verify macbook-fish.peridot --deep
+```
+
+Guardar un perfil reutilizable:
+
+```bash
+peridot profile save work-macos \
+  --preset macos-fish \
+  --platform macos \
+  --shell fish \
+  --path ~/.config/fish \
+  --exclude '.ssh/*'
+```
+
+Usar un perfil:
+
+```bash
+peridot pack --profile work-macos
+```
+
+Rotar clave y migrar bundles:
+
+```bash
+peridot rekey --all-local
+```
+
+Exportar ficha CLI-friendly:
+
+```bash
+peridot share macbook-fish.peridot --format md
+peridot share macbook-fish.peridot --format json
+```
+
+Fusionar y partir bundles:
+
+```bash
+peridot merge a.peridot b.peridot --output merged.peridot --name "Merged"
+peridot split merged.peridot --prefix .config/fish --output fish-only.peridot --name "Fish Only"
+```
+
+Ver el manifest crudo:
+
+```bash
+peridot manifest macbook-fish.peridot
+```
+
+## Plataformas
+
+Peridot no se limita a dotfiles Unix. Puedes generar bundles para distintos entornos:
+
+- `macos`: `.zshrc`, `.config/fish`, `.gitconfig`, `Library/Application Support/...`
+- `linux`: `.bashrc`, `.config`, `.local/share`, configuraciones de WM/terminal
+- `windows`: `.gitconfig`, `.wslconfig`, `AppData/Roaming`, perfiles de PowerShell, Windows Terminal
+
+El bundle guarda `platform.os`, `platform.shell` y `platform.arch`, y `peridot apply` comprueba compatibilidad antes de restaurar. Si quieres saltarte esa comprobacion, usa `--ignore-platform`.
+
+## Comandos
+
+- `peridot keygen`: crea o muestra la clave activa
+- `peridot doctor`: diagnostica el entorno local
+- `peridot ui`: abre el command center visual
+- `peridot catalog`: enseña grupos clasificados detectables por plataforma
+- `peridot pack`: crea un bundle `.peridot`
+- `peridot inspect`: muestra la ficha visual del bundle
+- `peridot apply`: restaura el bundle
+- `peridot diff`: compara el bundle con un destino
+- `peridot verify`: valida estructura e integridad
+- `peridot share`: exporta una ficha en `md` o `json`
+- `peridot history`: lista snapshots de un bundle
+- `peridot manifest`: imprime el `manifest.json`
+- `peridot rekey`: genera una nueva clave y migra paquetes existentes
+- `peridot delete`: elimina paquetes `.peridot`
+- `peridot profile`: guarda/lista/muestra/elimina perfiles reutilizables
+- `peridot merge`: fusiona bundles
+- `peridot split`: parte un bundle en otro
+
+Tambien existen alias para la nomenclatura antigua:
+
+- `peridot export` -> `peridot pack`
+- `peridot import` -> `peridot apply`
+
+## Filosofia del formato
+
+Peridot intenta equilibrar tres cosas:
+
+1. Portabilidad real. El bundle es un archivo unico, facil de subir, compartir o versionar.
+2. Inspeccion previa. Puedes abrir el `manifest.json` sin descifrar el contenido.
+3. Seguridad razonable. El payload va comprimido y cifrado; la clave se gestiona aparte.
+
+Importante:
+
+- sin la clave puedes inspeccionar el `manifest.json`, pero no leer ni aplicar los payloads cifrados
+- si rotas la clave, usa `peridot rekey` para migrar los paquetes existentes a la nueva clave
+- `pack` puede avisarte de rutas sensibles y aceptar exclusiones por glob
+
+## Limitaciones actuales
+
+- Los symlinks no se empaquetan todavia.
+- No hay merge inteligente entre configuraciones; `apply` restaura ficheros completos.
+- El cifrado depende de una clave local `AES-GCM`, que tienes que conservar junto al bundle si quieres moverlo a otra maquina.
+
+## Roadmap natural
+
+- soporte de symlinks
+- perfiles declarativos por plataforma
+- filtros de inclusion/exclusion por glob
+- plugin system para apps concretas
+- diff visual antes de sobrescribir archivos