portmaster 1.0.0__tar.gz

portmaster-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: tests
+
+# Por push y no por pull_request. El evento de PR dejo de producir runs en este
+# repo el 6 de agosto: ni el push de un agente a una rama con PR abierto ni un
+# PR nuevo dispararon nada, con Actions habilitado y el workflow activo. Por
+# push cada rama corre sus tests igual, el PR muestra el check de su rama, y no
+# hay dos runs por commit como pasaria dejando los dos eventos.
+on:
+  push:
+  workflow_dispatch:
+
+# Empujar tres veces seguidas cancela las corridas viejas en vez de encolar tres
+# matrices de cuatro cuadros.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    # Uno solo: ruff lee el codigo, no el sistema operativo. Repetirlo en los
+    # cuatro cuadros de la matriz no dice nada nuevo.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check portmaster tests
+
+  test:
+    # El modulo de puertos habla directo con el SO y los tres sistemas divergen:
+    # SO_REUSEADDR en Windows, tabla de conexiones sin root en macOS. Correr en
+    # uno solo no prueba nada.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.13"]
+        include:
+          - os: ubuntu-latest
+            python: "3.10"
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

portmaster-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: release
+
+# Se dispara con el tag, no con el push a main: publicar es irreversible en PyPI
+# (un numero de version no se puede reusar ni despues de borrarlo) y merecer un
+# gesto explicito.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      # El numero sale de portmaster/__init__.py, que es la unica fuente. Si el
+      # tag no coincide, se corta antes de publicar: un v1.0.1 que sube un
+      # paquete que se llama 1.0.0 no se puede deshacer.
+      - name: El tag tiene que coincidir con la version del paquete
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(python -c "import re,pathlib; print(re.search(r'\"(.+)\"', pathlib.Path('portmaster/__init__.py').read_text()).group(1))")
+          echo "tag=$tag paquete=$pkg"
+          [ "$tag" = "$pkg" ]
+
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # El entorno permite exigir aprobacion manual desde la configuracion del
+    # repo antes de que corra este job.
+    environment: pypi
+    permissions:
+      # Trusted publishing: PyPI verifica este token de OIDC contra el publisher
+      # configurado para el repo. Sin API token en secrets, que es un secreto de
+      # larga vida que no caduca si se filtra.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

portmaster-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.env
+.gstack/
+.freebuff/

portmaster-1.0.0/AGENTS.md

@@ -0,0 +1,5 @@
+Las instrucciones del proyecto viven en [CLAUDE.md](CLAUDE.md).
+
+Este archivo existe para los agentes que buscan `AGENTS.md` por convención. Era
+una copia byte a byte de `CLAUDE.md`, y dos copias del mismo contrato divergen
+en el primer cambio.

portmaster-1.0.0/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+Formato de [Keep a Changelog](https://keepachangelog.com/es/1.1.0/).
+Versionado semántico: la superficie pública son los comandos del CLI, el
+esquema de `stack.yaml` y las rutas de la API local.
+
+## [1.0.0] - 2026-08-06
+
+Primera versión publicada. Lo que sigue es el alcance completo, no un diff.
+
+### Orquestación
+
+- `portmaster up` arranca los servicios en orden topológico, con los que no
+  dependen entre sí en paralelo, healthchecks por puerto, log o comando, y
+  apagado del árbol completo de procesos al salir.
+- `portmaster down` baja un stack de compose puro, corriendo los `stop:` en
+  orden inverso.
+- `portmaster switch` baja los proyectos registrados que le pisan los puertos a
+  uno y lo levanta, sin tocar los que no compiten.
+- `stack.yaml` declara servicios, dependencias, puertos, healthchecks, perfiles
+  y variables. Sin archivo, `detect` infiere el stack de compose, Django,
+  FastAPI, Node, Go, Rust, Rails, Laravel y ASP.NET Core, en la raíz o en
+  subcarpetas.
+- `portmaster init` congela lo detectado a un `stack.yaml` editable.
+
+### Puertos
+
+- `portmaster ports` y `portmaster free` escanean, identifican al proceso dueño
+  y lo cierran con verificación de `create_time` contra el reciclado de PIDs.
+- `portmaster free --all` recorre los puertos de todos los proyectos
+  registrados y cierra lo que los ocupe, con una sola confirmación que lista
+  antes qué va a cerrar.
+- El cierre se niega sobre el proceso propio, sobre los PIDs de sistema, y
+  sobre el proxy compartido de Docker o WSL, porque cerrar ese proxy apaga el
+  motor entero con todos sus contenedores.
+- Cuando un healthcheck se agota, el error dice si el servicio abrió otro
+  puerto que el declarado, o quién tenía el declarado.
+
+### Interfaz web
+
+- `portmaster serve` levanta una interfaz local en `127.0.0.1:7666` para
+  arrancar, apagar y reiniciar servicios de varios proyectos, con logs
+  incrementales, explorador de carpetas, buscador, paginado, filtro por estado
+  y sección de procesos intrusos.
+- La tarjeta marca al lado del puerto cuando otro proyecto registrado declara
+  ese mismo puerto, y cuando el puerto ya estaba ocupado antes de arrancar.
+- "Liberar todos" cierra de una todos los procesos intrusos, en dos pasos sobre
+  el mismo botón: el segundo nombra puertos y procesos antes de hacerlo.
+- Estado de Docker en la fila de herramientas cuando algún proyecto lo usa, con
+  un botón que abre el motor si está caído y lo reinicia si está arriba.
+  Reiniciar pide confirmación: baja todos los contenedores.
+- La sección de procesos intrusos ya no desaparece cuando no hay ninguno: lo
+  dice.
+- Sin build y sin webfonts: la CSP es `default-src 'self'`.
+
+### Diagnóstico
+
+- `portmaster doctor` junta los chequeos en una salida, cada rojo con la línea
+  que lo arregla. Funciona en una carpeta que no es un proyecto conocido.
+- Compara las claves de `.env.example` contra el `.env` y avisa las que faltan
+  o quedaron vacías. Nombres, nunca valores.
+
+### Seguridad
+
+- Token de 32 bytes en `~/.portmaster/token` con permisos 0600, o
+  `PORTMASTER_TOKEN`. El servidor no arranca sin token.
+- Validación del header `Host` contra rebinding de DNS, antes de cualquier otra
+  cosa.
+- CSP, `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` y
+  `Cache-Control: no-store` en toda respuesta. Sin `Strict-Transport-Security`:
+  el servidor es http sobre loopback y el header rompería cualquier otro
+  proyecto local.
+- Rate limiting por ruta: 1800 lecturas, 60 escrituras y 30 cierres de proceso
+  por ventana.
+
+### Conocido
+
+- Con `ready: port`, un proceso ajeno que ya tenga el puerto declarado hace que
+  el servicio figure listo al instante. El arranque lo avisa, por consola y en
+  la tarjeta, y no lo impide: `docker compose up -d` sobre un contenedor que ya
+  está arriba es el mismo caso y ahí es correcto. Ver `docs/pendientes.md`.
+
+[1.0.0]: https://github.com/TicoraX/PortMaster/releases/tag/v1.0.0

portmaster-1.0.0/CLAUDE.md

@@ -0,0 +1,76 @@
+# PortMaster
+
+Herramienta de consola en Python que orquesta entornos de desarrollo locales:
+libera puertos, arranca Docker, backend y frontend en orden, y expone una
+interfaz web local para gestionar varios proyectos.
+
+## Estructura
+
+| Modulo | Responsabilidad |
+|---|---|
+| `ports.py` | Escaneo de puertos, identificacion del proceso dueno, cierre seguro |
+| `config.py` | Carga y validacion de `stack.yaml` |
+| `detect.py` | Servicios inferidos del proyecto cuando no hay `stack.yaml` |
+| `runner.py` | Arranque en orden topologico, healthchecks, apagado del arbol |
+| `registry.py` | Proyectos conocidos por la interfaz, y el token de la API |
+| `docker.py` | Arranque y reinicio de Docker Desktop. Diagnosticar si esta arriba es de `doctor.py` |
+| `server.py` | API local en FastAPI |
+| `web/` | Interfaz: HTML, CSS y JS sin build |
+| `cli.py` | Comandos Typer |
+
+El core no depende de la terminal. El CLI y el servidor son dos consumidores de
+las mismas funciones; cualquier logica nueva va en el modulo correspondiente, no
+en `cli.py` ni en `server.py`.
+
+## Desviaciones deliberadas de las reglas globales
+
+Cada una con su motivo. No revertirlas sin leerlo primero.
+
+### El token no vive en un `.env`
+
+La regla pide secretos en `.env` con validacion al arrancar. PortMaster se
+instala con `pipx` o `uv tool`: no hay repositorio donde poner un `.env`, y
+pedirle al usuario que genere y copie un token a mano garantiza que termine
+usando `token=1234`.
+
+En su lugar: `PORTMASTER_TOKEN` tiene prioridad si existe, y si no,
+`registry.token()` genera uno de 32 bytes en `~/.portmaster/token` con permisos
+0600. Se valida largo minimo de 16 en ambos casos y el servidor no arranca sin
+token. El secreto queda fuera del repo, que es lo que la regla protege.
+
+### Las cuotas de rate limit no son las de referencia
+
+La referencia es 100/15min general. La interfaz sondea `/api/state` cada 2.5s,
+que da unas 360 peticiones por ventana: con 100 se rompe el uso normal. Las
+cuotas quedaron en `QUOTA_READ = 1800`, `QUOTA_WRITE = 60`, `QUOTA_KILL = 30`.
+Las rutas que ejecutan comandos o matan procesos son las que van cortas, que es
+donde la regla importa.
+
+### Sin `Strict-Transport-Security`
+
+El servidor es http sobre loopback. Ese header le impondria https a todo
+`127.0.0.1` en el navegador del usuario y romperia cualquier otro proyecto local
+que corra en http. Los otros headers (CSP, nosniff, DENY, no-referrer) si estan.
+
+En su lugar, contra rebinding de DNS: validacion del header `Host` contra
+`127.0.0.1` y `localhost`, antes de cualquier otra cosa.
+
+### `shell=True` en los subprocesos
+
+`npm run dev` y `docker compose up -d` no son ejecutables. `stack.yaml` ya es
+codigo ejecutable por diseno, igual que `package.json` o un `Makefile`, y el
+README lo documenta. Por eso el apagado mata el arbol de procesos completo: con
+`shell=True` el hijo directo es el shell y matarlo solo a el deja huerfano al
+servidor de verdad.
+
+### La interfaz no usa webfonts
+
+La CSP es `default-src 'self'`. Una herramienta local que le pide fuentes a un
+CDN en cada carga filtra actividad y deja de funcionar sin internet. Los tres
+roles tipograficos salen de stacks del sistema.
+
+## Tests
+
+`pytest`. Todo con sockets y procesos reales, sin mocks: es la unica forma de
+probar un modulo cuyo trabajo es hablar con el sistema operativo. La CI corre en
+Linux, macOS y Windows porque los tres divergen justo ahi.

portmaster-1.0.0/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.