stackhelx 1.0.0__py3-none-any.whl

stackhelx-1.0.0.dist-info/METADATA

@@ -0,0 +1,323 @@
+Metadata-Version: 2.5
+Name: stackhelx
+Version: 1.0.0
+Summary: Orquestador de entornos de desarrollo locales: puertos, Docker, backend y frontend con un solo comando
+Project-URL: Homepage, https://github.com/TicoraX/StackHelx
+Project-URL: Repository, https://github.com/TicoraX/StackHelx
+Project-URL: Issues, https://github.com/TicoraX/StackHelx/issues
+Author: TicoraX
+License: MIT License
+        
+        Copyright (c) 2026 TicoraX
+        
+        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.
+License-File: LICENSE
+Keywords: cli,devtools,docker,dx,orchestration,ports,stackhelx
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: psutil>=6.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-xdist>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# StackHelx
+
+[![pypi](https://img.shields.io/pypi/v/stackhelx)](https://pypi.org/project/stackhelx/)
+[![tests](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+Orquestador de entornos de desarrollo locales. Un archivo en la raíz del
+proyecto, un comando, y el stack entero arriba: puertos libres, Docker,
+backend y frontend, sin cuatro terminales abiertas.
+
+## Instalación
+
+```bash
+uv tool install stackhelx
+# o
+pipx install stackhelx
+```
+
+Requiere Python 3.10 o superior. Funciona en Windows, macOS y Linux.
+
+## Comandos
+
+| Comando | Qué hace |
+|---|---|
+| `stackhelx up` | Levanta el stack entero: libera puertos, arranca en orden y sigue los logs |
+| `stackhelx down` | Baja lo que sobrevive a la terminal, o sea contenedores |
+| `stackhelx serve` | Abre la interfaz web en `http://127.0.0.1:7666` |
+| `stackhelx doctor` | Revisa qué puede impedir el arranque, sin arrancar nada |
+| `stackhelx ports` | Estado de los puertos declarados |
+| `stackhelx free 3000` | Cierra el proceso que ocupa un puerto, preguntando antes |
+| `stackhelx free --all` | Lo mismo para todos los puertos de todos los proyectos registrados |
+| `stackhelx switch fitness` | Baja los proyectos que le pisan los puertos a este, y lo levanta |
+| `stackhelx open` | Abre en el navegador el primer servicio que conteste HTTP |
+| `stackhelx init` | Congela lo detectado en un `stack.yaml` editable |
+| `stackhelx add .` | Registra el proyecto para que aparezca en la interfaz |
+| `stackhelx list` | Lista los proyectos registrados (alias: `ls`) |
+| `stackhelx remove .` | Des-registra un proyecto (alias: `rm`) |
+| `stackhelx run [tarea]` | Ejecuta scripts o pipelines de tareas del proyecto |
+| `stackhelx share [target]` | Expone un servicio local a internet mediante un túnel seguro |
+| `stackhelx clean` | Limpia Docker por categorías: contenedores parados, imágenes sin tag, redes sin usar y caché de build. Los volúmenes van aparte, con `--volumes`. Pregunta antes |
+| `stackhelx mcp` | Inicia el servidor Model Context Protocol (MCP) sobre stdio para IA |
+| `stackhelx test-stack` | Valida el `stack.yaml` sin arrancar nada: orden, dependencias y puertos |
+| `stackhelx history` | Últimos arranques del proyecto, con duración y resultado |
+| `stackhelx logs` | Logs del proyecto que corre en `serve`, con `--follow` para seguirlos |
+| `stackhelx stats` | CPU y memoria de los servicios que corren en `serve` (alias: `top`) |
+| `stackhelx version` | Versión instalada (también `--version`) |
+
+`logs` y `stats` consultan al `stackhelx serve` que ya tengas abierto, así que
+necesitan que esté corriendo. `history` y `test-stack` leen del disco y no.
+
+Cada uno con `--help`.
+
+## Arrancar un stack
+
+```bash
+stackhelx up
+stackhelx up --profile backend    # solo un subconjunto
+stackhelx up --no-free            # no tocar los puertos ocupados
+stackhelx up --env-file .env.qa   # carga ese .env antes de arrancar
+```
+
+`--env-file` no reemplaza al `env_file:` de `stack.yaml`, se suma: carga el
+archivo en el entorno del proceso antes de resolver el stack, así que lo ven
+todos los servicios. Es para la corrida puntual contra otro entorno, sin editar
+el archivo. A diferencia de `env_file:`, acepta rutas fuera de la raíz del
+proyecto, porque acá la ruta la escribiste vos en la terminal y no viene de un
+archivo de un repo ajeno.
+
+Antes de arrancar libera los puertos declarados que tenga otro proceso, y
+pregunta antes de cerrar cada uno. Los que ya publica Docker los saltea: ahí
+no hay nada que liberar, el contenedor ya está arriba.
+
+```
+demo  stack.yaml
+db  | $ docker compose up -d postgres
+db  | listo (5432)
+api | $ npm run dev
+api | escuchando en 8080
+api | listo (8080)
+web | $ npm run dev
+web | listo (3000)
+Todo listo. Ctrl-C para apagar.
+api | GET /health 200
+web | ready in 412 ms
+```
+
+Antes de arrancar nada revisa los puertos declarados. Si alguno está tomado
+por un proceso huérfano, muestra cuál es y pregunta si cerrarlo. `Ctrl-C`
+apaga los servicios en orden inverso, árbol de procesos incluido.
+
+## Sin stack.yaml
+
+`stack.yaml` es opcional. Si no hay uno, StackHelx mira la raíz del proyecto:
+
+| Encuentra | Arranca |
+|---|---|
+| `compose.yaml`, `compose.yml`, `docker-compose.yml`, `docker-compose.yaml` | un servicio por contenedor: `docker compose up -d <nombre>` |
+| `manage.py` | `python manage.py runserver` |
+| `fastapi` o `uvicorn` declarados, con un módulo que defina `app` | `uvicorn <módulo>:app --reload` |
+| `package.json` con un script que sirva (`dev`, `start:dev`, `serve`, `start`) | `npm run dev`, con `pnpm`/`yarn`/`bun` según el lockfile o el campo `packageManager` |
+
+```
+mi-app  A:\Proyectos\mi-app
+Sin stack.yaml. Detectado:
+  docker  docker compose up -d        5433
+  web     pnpm run dev                al arrancar
+Para congelarlo en un archivo editable: stackhelx init
+Arrancar? [Y/n]
+```
+
+Arranca en ese orden y encadena las dependencias: el frontend espera al
+backend, el backend a los contenedores.
+
+`stackhelx init` escribe lo detectado como `stack.yaml` para editarlo a mano.
+No sobreescribe uno existente.
+
+Dónde busca cada lenguaje y por qué reconoce eso y no otra cosa, en
+[`docs/deteccion.md`](docs/deteccion.md).
+
+## stack.yaml
+
+En la raíz del proyecto. StackHelx lo busca hacia arriba, así que podés correr
+los comandos desde cualquier subdirectorio.
+
+```yaml
+name: mi-proyecto
+
+services:
+  db:
+    command: docker compose up -d postgres
+    port: 5432
+    detached: true       # el comando termina, el servicio sigue vivo
+
+  api:
+    command: npm run dev
+    cwd: backend
+    port: 8080
+    needs: [db]
+    env:
+      DATABASE_URL: postgres://localhost:5432/app
+
+  web:
+    command: npm run dev
+    cwd: frontend
+    port: 3000
+    needs: [api]
+
+profiles:
+  backend: [api]         # arrastra db, que es su dependencia
+```
+
+`command` es el único obligatorio. La referencia de todos los campos, los
+healthchecks de `ready` y los perfiles heredados de un compose están en
+[`docs/stack-yaml.md`](docs/stack-yaml.md).
+
+## Interfaz web
+
+Cuando tenés varios proyectos, el CLI se queda corto: trabaja sobre el
+directorio actual. La interfaz los muestra todos a la vez.
+
+```bash
+stackhelx serve        # abre http://127.0.0.1:7666
+```
+
+Viene con la instalación, no hace falta nada más. Registrar proyectos se puede
+desde la propia interfaz con `Explorar…`, o desde la terminal con
+`stackhelx add .`.
+
+Estado de cada servicio, arrancar y apagar stacks, liberar puertos tomados por
+procesos ajenos, y logs en vivo por proyecto.
+
+El detalle de cada control, y el modelo de seguridad del servidor local, en
+[`docs/interfaz.md`](docs/interfaz.md).
+
+## Puertos
+
+Revisar el estado de los puertos sin arrancar nada:
+
+```bash
+stackhelx ports              # los declarados en stack.yaml
+stackhelx ports 3000 8080    # o los que le pases
+```
+
+```
+PUERTO  ESTADO   PID    PROCESO   COMANDO
+3000    ocupado  24188  node.exe  node C:\proj\frontend\node_modules\.bin\vite
+8080    libre    -      -         -
+5432    ocupado  9012   com.docker.backend.exe
+```
+
+Liberar un puerto tomado por un proceso zombie:
+
+```bash
+stackhelx free 3000
+```
+
+Muestra qué proceso lo ocupa y pide confirmación antes de cerrarlo. Si decís
+que no, sugiere el siguiente puerto disponible.
+
+Opciones: `--yes` salta la confirmación (para scripts), `--force` aplica
+`kill()` cuando el proceso ignora la señal de terminación.
+
+Después de un crash o un cambio de rama suele quedar más de uno colgado:
+
+```bash
+stackhelx free --all
+```
+
+Recorre los puertos declarados por todos los proyectos registrados, lista lo
+que encuentre ocupado y pide una sola confirmación. Sale con código 1 si no
+pudo cerrar alguno.
+
+El CLI no sabe qué arrancaste vos: si tenés un stack levantado en otra
+terminal, sus servicios aparecen en esa lista y también se cierran. Por eso la
+muestra entera antes de tocar nada, y por eso la confirmación viene con "no"
+por defecto. La interfaz web sí lo sabe, y ahí el botón "Liberar todos"
+descarta lo que arrancó ella.
+
+## Qué no hace el kill switch
+
+Estas reglas están en el código, no en la documentación:
+
+- Nunca cierra PID 0, PID 4, el propio StackHelx ni un proceso padre suyo.
+  Matar tu propia terminal no es una función.
+- Revalida la hora de creación del proceso entre el escaneo y el cierre. Los
+  PID se reciclan; sin ese chequeo terminás matando algo al azar.
+- Manda `terminate()` y espera 5 segundos. `kill()` solo con `--force`
+  explícito, porque un `npm run dev` matado a lo bruto deja hijos huérfanos.
+- Sin permisos, lo dice y corta. No reintenta escalando privilegios.
+- Nunca cierra el proxy de Docker o de WSL. Un puerto publicado por un
+  contenedor no lo escucha el contenedor: lo escucha un proceso compartido por
+  todos, y cerrarlo apaga el motor entero. En vez de eso te dice qué contenedor
+  parar.
+
+## Otros comandos
+
+`down`, `switch`, `doctor` y `open`, con qué revisa cada uno y por qué, en
+[`docs/comandos.md`](docs/comandos.md).
+
+## Modelo de confianza
+
+`stack.yaml` ejecuta comandos arbitrarios, igual que `package.json` o un
+`Makefile`. StackHelx no lo sandboxea: sería teatro. Tratá un `stack.yaml`
+de un repo ajeno con el mismo cuidado que sus scripts de build.
+
+Sin `stack.yaml`, los comandos salen de la detección, y `scripts.dev` de un
+`package.json` ajeno es igual de arbitrario. Por eso `up` muestra qué va a
+ejecutar y pregunta antes, y `-y` es tuyo para saltarlo cuando ya lo leíste.
+
+## Desarrollo
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"    # .venv\Scripts\pip en Windows
+pytest
+```
+
+Los tests levantan sockets y procesos reales, sin mocks. Es lo único que
+prueba de verdad un módulo cuyo trabajo es hablar con el sistema operativo.
+
+## Licencia
+
+MIT

stackhelx-1.0.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+stackhelx/__init__.py,sha256=uyfGiipFnhOCQlqywx7wsgp6d-SYnqPqsPQd_xePZl8,23
+stackhelx/__main__.py,sha256=Qd-f8z2Q2vpiEP2x6PBFsJrpACWDVxFKQk820MhFmHo,59
+stackhelx/browse.py,sha256=y3vhu8HOofme4tCkh-NU-qgpTjX_YWnvalwBgYpM8iE,5796
+stackhelx/cli.py,sha256=A7FujJGcFqux2aDix5wTdj_MI025lTKhhqCpF8MK4us,41525
+stackhelx/config.py,sha256=tMN1prZVux3A7qZHw0K29yHxrZJbZvxMr-dol1DhND4,17012
+stackhelx/detect.py,sha256=5-DJfO5MM1T37hDD3_x8GU14fMOGjKCfl9EebQHsOnU,39132
+stackhelx/docker.py,sha256=mEbKU2pUhDoYwk9NeuZ7bvEWjyEdeQV7VE4wk4JdsRg,7743
+stackhelx/doctor.py,sha256=qr3qQuDeHJIiGNkKbkGniCJxjkvPtt1XkNeqX5ynz0g,11673
+stackhelx/guardrails.py,sha256=gwJKMzFEw5jsCtp9uF4MXZEokEbB6NMt5rb1-Yqo1Y0,1683
+stackhelx/history.py,sha256=loJrfP3YJHGXXlGqYLyYB99Lq_JDzmHoq6CeDOHOpPs,2531
+stackhelx/mcp.py,sha256=iQ_tKvYriWeUyPZ4xjQB3rV1L4q8RAXVUShjaoRgR9w,19077
+stackhelx/ports.py,sha256=F2sx6d--89poqqjQN7DEk5sVhX8K9IprGpRW_HfBOJ4,14293
+stackhelx/registry.py,sha256=5tlZiJ1zghxpp4KWf-zOjmCAzH1huhRoeEHC9vTmg9M,13349
+stackhelx/runner.py,sha256=Imjw45tadn0SNyK05KooC5qQ61N7V9CXhjezVw8ZqvY,36244
+stackhelx/scripts.py,sha256=-aFQwjIAu4xDnwT0VoxxGF_JsAWN38J9Kai13AoASRo,4634
+stackhelx/server.py,sha256=BShuSGHeNlCsQVwUgIFkd5Pdg_ZvifyfQBxNFnRhBEg,75144
+stackhelx/tunnel.py,sha256=wiUmrsdgsrR3bqOUUeBZnY4vEpXoOp4-tHdm7cMCM5k,7879
+stackhelx/web/app.css,sha256=yg-rJcIh_xTvLfAaYZBXWT1Qeac8gFojpO2r4i9GKg8,39558
+stackhelx/web/app.js,sha256=wBlAyeZvXaLYIz8QIgNEu_D02QvAS8ROHxMXhAv6x7Y,87233
+stackhelx/web/index.html,sha256=OCKyYk2SO7-ZMcgpgMUPZQFoz969CVCjIhjCBVos2o4,17871
+stackhelx/web/tokens.css,sha256=s8gNd0cI9ZM_zFUUp2_kRKwN45ppv8wJBwdA98sLa7o,3593
+stackhelx-1.0.0.dist-info/METADATA,sha256=PF1X2aUem4Ju9E5DdaK3WJCfrybkoF8awYheLmajLf0,12728
+stackhelx-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+stackhelx-1.0.0.dist-info/entry_points.txt,sha256=l1LQJHvHwCB7Xr8vn3PMfBcB4GCVU-tqYEYRTOm5AyI,72
+stackhelx-1.0.0.dist-info/licenses/LICENSE,sha256=J-YF-HS26LOhmzHOeCUGqOGgMZ_cZg0m_Y4L_ox8bcI,1064
+stackhelx-1.0.0.dist-info/RECORD,,

stackhelx-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stackhelx-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+shx = stackhelx.cli:app
+stackhelx = stackhelx.cli:app

stackhelx-1.0.0.dist-info/licenses/LICENSE

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