stackhelx 1.1.3__tar.gz → 1.1.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. {stackhelx-1.1.3 → stackhelx-1.1.4}/CHANGELOG.md +21 -0
  2. {stackhelx-1.1.3 → stackhelx-1.1.4}/PKG-INFO +1 -1
  3. {stackhelx-1.1.3 → stackhelx-1.1.4}/README.es.md +8 -8
  4. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/deteccion.md +17 -0
  5. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/es/comandos.md +5 -5
  6. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/es/deteccion.md +17 -1
  7. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/es/interfaz.md +15 -3
  8. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/es/stack-yaml.md +4 -4
  9. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/interfaz.md +10 -0
  10. stackhelx-1.1.4/stackhelx/__init__.py +2 -0
  11. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/cli.py +1 -1
  12. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/docker.py +31 -0
  13. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/ports.py +55 -24
  14. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/registry.py +49 -1
  15. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/runner.py +30 -1
  16. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/server.py +103 -14
  17. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/web/app.css +145 -50
  18. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/web/app.js +213 -94
  19. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/web/index.html +59 -22
  20. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/web/tokens.css +0 -1
  21. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_ports.py +63 -0
  22. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_registry.py +68 -0
  23. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_runner.py +30 -0
  24. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_server.py +124 -2
  25. {stackhelx-1.1.3 → stackhelx-1.1.4}/uv.lock +59 -33
  26. stackhelx-1.1.3/stackhelx/__init__.py +0 -2
  27. {stackhelx-1.1.3 → stackhelx-1.1.4}/.github/workflows/ci.yml +0 -0
  28. {stackhelx-1.1.3 → stackhelx-1.1.4}/.github/workflows/release.yml +0 -0
  29. {stackhelx-1.1.3 → stackhelx-1.1.4}/.gitignore +0 -0
  30. {stackhelx-1.1.3 → stackhelx-1.1.4}/AGENTS.md +0 -0
  31. {stackhelx-1.1.3 → stackhelx-1.1.4}/CLAUDE.md +0 -0
  32. {stackhelx-1.1.3 → stackhelx-1.1.4}/LICENSE +0 -0
  33. {stackhelx-1.1.3 → stackhelx-1.1.4}/README.md +0 -0
  34. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/comandos.md +0 -0
  35. {stackhelx-1.1.3 → stackhelx-1.1.4}/docs/stack-yaml.md +0 -0
  36. {stackhelx-1.1.3 → stackhelx-1.1.4}/pyproject.toml +0 -0
  37. {stackhelx-1.1.3 → stackhelx-1.1.4}/scripts/check_docs.py +0 -0
  38. {stackhelx-1.1.3 → stackhelx-1.1.4}/scripts/check_metadata.py +0 -0
  39. {stackhelx-1.1.3 → stackhelx-1.1.4}/stack.example.yaml +0 -0
  40. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/__main__.py +0 -0
  41. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/browse.py +0 -0
  42. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/config.py +0 -0
  43. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/detect.py +0 -0
  44. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/doctor.py +0 -0
  45. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/guardrails.py +0 -0
  46. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/history.py +0 -0
  47. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/mcp.py +0 -0
  48. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/scripts.py +0 -0
  49. {stackhelx-1.1.3 → stackhelx-1.1.4}/stackhelx/tunnel.py +0 -0
  50. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/conftest.py +0 -0
  51. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_browse.py +0 -0
  52. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_cli.py +0 -0
  53. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_config.py +0 -0
  54. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_conftest.py +0 -0
  55. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_detect.py +0 -0
  56. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_guardrails.py +0 -0
  57. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_history.py +0 -0
  58. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_mcp.py +0 -0
  59. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_scripts.py +0 -0
  60. {stackhelx-1.1.3 → stackhelx-1.1.4}/tests/test_tunnel.py +0 -0
@@ -4,6 +4,27 @@ Formato de [Keep a Changelog](https://keepachangelog.com/es/1.1.0/).
4
4
  Versionado semántico: la superficie pública son los comandos del CLI, el
5
5
  esquema de `stack.yaml` y las rutas de la API local.
6
6
 
7
+ ## [1.1.4] - 2026-10-31
8
+
9
+ ### Corregido
10
+
11
+ - **Servidores arrancados fuera de StackHelx (`registry.py`, `server.py`):** un `astro dev` corriendo desde otra terminal no aparecía en la tarjeta ni en la pestaña "De proyectos", porque `detect` no adivina puertos y `ready: listen` solo los descubre en el árbol propio. Ahora se atribuyen al proyecto por la ruta en la línea de comandos, o por la carpeta de trabajo si el proceso es un intérprete. Un proyecto con un solo servicio sin puerto lo muestra listo y `externo`; con más, lista los puertos sin adivinar el servicio (`external_ports`).
12
+ - **Un contenedor ajeno ponía listo al servicio (`docker.py`, `server.py`):** el `postgres` de un proyecto salía listo y Apagar no hacía nada porque el 5432 lo publicaba un contenedor suelto de otro proyecto. Un servicio con contenedor solo sale listo si `docker ps` dice que el contenedor es de su compose.
13
+ - **Puertos declarados (`registry.py`):** `declared_ports` miraba solo el perfil por defecto y los intrusos todos los servicios, así que un puerto salía declarado en un lado y no en el otro. Ahora cuentan todos los servicios.
14
+ - El aviso de token inválido sale en el idioma de la interfaz; el favicon se pone verde con proyectos externos; la pastilla live de los logs y el punto listo del grafo vuelven a tener color.
15
+ - **Astro 7 se desacoplaba bajo un agente (`runner.py`):** `astro dev` detecta agentes por variables de entorno (`am-i-vibing`) y se va a segundo plano: `up` terminaba con 0 y el servidor quedaba fuera del árbol. `build_env` ya no pasa esas variables a los servicios, salvo que las declare `env.global` o el `env` del servicio.
16
+
17
+ ### Añadido
18
+
19
+ - **Vista global de puertos real (`ports.py`, `/api/ports/system`, `web/`):** un registro por protocolo, puerto y proceso (antes uno por puerto), con dirección de escucha, carpeta del proceso y proyecto atribuido. UDP opcional con `?udp=1`. El mapa abre en "Todo el sistema" con filtro, "Ocultar procesos de Windows", "Incluir UDP" y "Refrescar"; sigue siendo a pedido, sin sondeo.
20
+ - El mapa muestra el error y un botón Reintentar en vez de quedar en silencio cuando falla la lectura.
21
+ - **Acceso al mapa de puertos:** botón "Puertos" en el encabezado y "Mapa completo →" en la sección de procesos intrusos.
22
+
23
+ ### Cambiado
24
+
25
+ - **Tipografía por roles (`web/`):** serif para nombrar, sans para leer (estados y controles incluidos) y monoespaciada solo para datos que se copian o comparan. Dos pesos y seis tamaños.
26
+ - Español neutro (tuteo) en la interfaz, `README.es.md` y `docs/es/`.
27
+
7
28
  ## [1.1.3] - 2026-10-09
8
29
 
9
30
  ### Añadido y Mejorado
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: stackhelx
3
- Version: 1.1.3
3
+ Version: 1.1.4
4
4
  Summary: Local development environment orchestrator: ports, Docker, backend, and frontend with a single command
5
5
  Project-URL: Homepage, https://github.com/TicoraX/StackHelx
6
6
  Project-URL: Repository, https://github.com/TicoraX/StackHelx
@@ -73,7 +73,7 @@ shx up --env-file .env.qa # carga ese .env antes de arrancar
73
73
  archivo en el entorno del proceso antes de resolver el stack, así que lo ven
74
74
  todos los servicios. Es para la corrida puntual contra otro entorno, sin editar
75
75
  el archivo. A diferencia de `env_file:`, acepta rutas fuera de la raíz del
76
- proyecto, porque acá la ruta la escribiste vos en la terminal y no viene de un
76
+ proyecto, porque aquí la ruta la escribiste tú en la terminal y no viene de un
77
77
  archivo de un repo ajeno.
78
78
 
79
79
  Antes de arrancar libera los puertos declarados que tenga otro proceso, y
@@ -129,7 +129,7 @@ Dónde busca cada lenguaje y por qué reconoce eso y no otra cosa, en
129
129
 
130
130
  ## stack.yaml
131
131
 
132
- En la raíz del proyecto. StackHelx lo busca hacia arriba, así que podés correr
132
+ En la raíz del proyecto. StackHelx lo busca hacia arriba, así que puedes correr
133
133
  los comandos desde cualquier subdirectorio.
134
134
 
135
135
  ```yaml
@@ -165,7 +165,7 @@ healthchecks de `ready` y los perfiles heredados de un compose están en
165
165
 
166
166
  ## Interfaz web
167
167
 
168
- Cuando tenés varios proyectos, el CLI se queda corto: trabaja sobre el
168
+ Cuando tienes varios proyectos, el CLI se queda corto: trabaja sobre el
169
169
  directorio actual. La interfaz los muestra todos a la vez.
170
170
 
171
171
  ```bash
@@ -174,7 +174,7 @@ stackhelx serve # abre http://127.0.0.1:7666
174
174
 
175
175
  Viene con la instalación, no hace falta nada más. Registrar proyectos se puede
176
176
  desde la propia interfaz con `Explorar…` (`Browse…`), o desde la terminal con
177
- `stackhelx add .`. En el encabezado podés conmutar el idioma de toda la interfaz
177
+ `stackhelx add .`. En el encabezado puedes conmutar el idioma de toda la interfaz
178
178
  en vivo con el selector `EN / ES`.
179
179
 
180
180
  Estado de cada servicio, arrancar y apagar stacks, liberar puertos tomados por
@@ -205,7 +205,7 @@ Liberar un puerto tomado por un proceso zombie:
205
205
  stackhelx free 3000
206
206
  ```
207
207
 
208
- Muestra qué proceso lo ocupa y pide confirmación antes de cerrarlo. Si decís
208
+ Muestra qué proceso lo ocupa y pide confirmación antes de cerrarlo. Si dices
209
209
  que no, sugiere el siguiente puerto disponible.
210
210
 
211
211
  Opciones: `--yes` salta la confirmación (para scripts), `--force` aplica
@@ -221,7 +221,7 @@ Recorre los puertos declarados por todos los proyectos registrados, lista lo
221
221
  que encuentre ocupado y pide una sola confirmación. Sale con código 1 si no
222
222
  pudo cerrar alguno.
223
223
 
224
- El CLI no sabe qué arrancaste vos: si tenés un stack levantado en otra
224
+ El CLI no sabe qué arrancaste tú: si tienes un stack levantado en otra
225
225
  terminal, sus servicios aparecen en esa lista y también se cierran. Por eso la
226
226
  muestra entera antes de tocar nada, y por eso la confirmación viene con "no"
227
227
  por defecto. La interfaz web sí lo sabe, y ahí el botón "Liberar todos"
@@ -234,7 +234,7 @@ Estas reglas están en el código, no en la documentación:
234
234
  - Nunca cierra PID 0, PID 4, el propio StackHelx ni un proceso padre suyo.
235
235
  Matar tu propia terminal no es una función.
236
236
  - Revalida la hora de creación del proceso entre el escaneo y el cierre. Los
237
- PID se reciclan; sin ese chequeo terminás matando algo al azar.
237
+ PID se reciclan; sin ese chequeo terminas matando algo al azar.
238
238
  - Manda `terminate()` y espera 5 segundos. `kill()` solo con `--force`
239
239
  explícito, porque un `npm run dev` matado a lo bruto deja hijos huérfanos.
240
240
  - Sin permisos, lo dice y corta. No reintenta escalando privilegios.
@@ -251,7 +251,7 @@ Estas reglas están en el código, no en la documentación:
251
251
  ## Modelo de confianza
252
252
 
253
253
  `stack.yaml` ejecuta comandos arbitrarios, igual que `package.json` o un
254
- `Makefile`. StackHelx no lo sandboxea: sería teatro. Tratá un `stack.yaml`
254
+ `Makefile`. StackHelx no lo sandboxea: sería teatro. Trata un `stack.yaml`
255
255
  de un repo ajeno con el mismo cuidado que sus scripts de build.
256
256
 
257
257
  Sin `stack.yaml`, los comandos salen de la detección, y `scripts.dev` de un
@@ -98,5 +98,22 @@ even when Vite sees port 5173 occupied and shifts to 5174. The trade-off is that
98
98
  is only known after the process binds it. Compose ports are declared statically
99
99
  and freed beforehand.
100
100
 
101
+ A server started from another terminal (say, `astro dev` in the project folder)
102
+ is not in StackHelx's process tree, so its port cannot be discovered that way.
103
+ The dashboard attributes it from OS evidence instead: a project path in the
104
+ process command line, or the working directory when the process is an
105
+ interpreter (`node`, `python`, `bun`, `deno`, `java`, `dotnet`, `php`, `ruby`).
106
+ A tool binary that merely inherited the folder as its working directory, such as
107
+ an editor or an MCP server, is not attributed. If the project has exactly one
108
+ service without a declared port, that service shows as ready with the port and
109
+ an `external` mark; with two or more, the ports are listed for the project
110
+ without guessing which service owns them.
111
+
112
+ StackHelx also drops agent-identifying variables (`CLAUDECODE`, `AI_AGENT`,
113
+ `OPENCODE`, `GEMINI_CLI` and similar) from the environment it passes to services.
114
+ Astro 7 backgrounds `astro dev` as a daemon when it sees them, which would leave
115
+ the server outside the process tree with no port and no way to stop it. A
116
+ variable you set in `env.global` or in the service's `env` still applies.
117
+
101
118
  `stackhelx init` writes the detected stack to `stack.yaml` for manual editing
102
119
  and refuses to overwrite an existing file.
@@ -5,7 +5,7 @@
5
5
  > **Nota:** Todos los comandos del sistema pueden ejecutarse indistintamente con `stackhelx <cmd>` o mediante el alias corto oficial **`shx <cmd>`** (por ejemplo: `shx down`, `shx doctor`, `shx switch`, `shx run`, `shx share`).
6
6
 
7
7
  `up`, `serve`, `ports` y `free` están en el [README](../../README.es.md#comandos).
8
- Acá están los cuatro que quedan, con qué revisa cada uno y por qué.
8
+ Aquí están los cuatro que quedan, con qué revisa cada uno y por qué.
9
9
 
10
10
  ## Bajar lo que sobrevive a la terminal
11
11
 
@@ -49,7 +49,7 @@ contesta, y qué puertos declarados están ocupados y por quién. Cada chequeo e
49
49
  rojo trae la línea para arreglarlo.
50
50
 
51
51
  ```
52
- ok token C:\Users\vos\.stackhelx\token
52
+ ok token C:\Users\tu-usuario\.stackhelx\token
53
53
  ok stack detectado (3 servicios)
54
54
  ok comando docker C:\Program Files\Docker\...\docker.EXE
55
55
  FALLA daemon de docker no esta en ejecucion
@@ -102,7 +102,7 @@ stackhelx share --provider ngrok # fuerza el proveedor (cloudflared, ngrok, lt,
102
102
  ```
103
103
 
104
104
  Genera un túnel HTTPS seguro y efímero hacia el puerto local, ideal para probar webhooks,
105
- compartir vistas previas con clientes o probar en dispositivos móviles. Presioná `Ctrl-C` para
105
+ compartir vistas previas con clientes o probar en dispositivos móviles. Presiona `Ctrl-C` para
106
106
  cerrar el túnel de inmediato.
107
107
 
108
108
  **No se puede compartir el puerto de `stackhelx serve`.** Detrás de ese puerto está la API
@@ -149,7 +149,7 @@ stackhelx test-stack ../otro-proyecto
149
149
 
150
150
  Carga el `stack.yaml`, resuelve el orden topológico y mira si los puertos
151
151
  declarados están libres. No arranca nada, así que es lo más barato para saber si
152
- un archivo que acabás de editar carga bien.
152
+ un archivo que acabas de editar carga bien.
153
153
 
154
154
  ```
155
155
  Validando stack demo en C:\...\demo...
@@ -262,7 +262,7 @@ cosas están cortadas a propósito y no son las mismas que en el CLI:
262
262
  - **`stackhelx_share` solo publica puertos que el proyecto declara.** Pedir uno
263
263
  ajeno responde `El puerto 5432 no pertenece a los puertos declarados`, y el
264
264
  puerto de la propia interfaz está vetado aparte. El CLI no tiene esta
265
- restricción: ahí el puerto lo escribís vos.
265
+ restricción: ahí el puerto lo escribes tú.
266
266
  - **`stackhelx_clean` no borra volúmenes.** El flag existe en el CLI y no en el
267
267
  esquema de la herramienta.
268
268
  - **Hay un tope de 30 llamadas por minuto.** Pasado eso contesta `Límite de
@@ -4,7 +4,7 @@
4
4
 
5
5
  Cuando un proyecto no tiene `stack.yaml`, StackHelx infiere los servicios de
6
6
  lo que encuentra en el disco. La tabla de qué reconoce está en el
7
- [README](../../README.es.md#sin-stackyaml). Acá está por qué reconoce eso y no otra
7
+ [README](../../README.es.md#sin-stackyaml). Aquí está por qué reconoce eso y no otra
8
8
  cosa, que es lo que hay que leer antes de agregar un detector.
9
9
 
10
10
  La regla que ordena todo lo de abajo: solo se detecta lo que sirve en un
@@ -117,5 +117,21 @@ se le pregunta cuál quedó escuchando. Es más confiable que parsear
117
117
  antes de arrancar, porque no se saben hasta después. Los de compose sí, que
118
118
  están declarados en el archivo.
119
119
 
120
+ Un servidor arrancado desde otra terminal (por ejemplo `astro dev` en la carpeta
121
+ del proyecto) no está en el árbol de StackHelx, así que su puerto no se descubre
122
+ por ahí. La interfaz lo atribuye con evidencia del sistema: una ruta del proyecto
123
+ en la línea de comandos del proceso, o su carpeta de trabajo si el proceso es un
124
+ intérprete (`node`, `python`, `bun`, `deno`, `java`, `dotnet`, `php`, `ruby`). Un
125
+ binario que solo heredó la carpeta, como un editor o un servidor MCP, no se
126
+ atribuye. Si el proyecto tiene un solo servicio sin puerto declarado, ese
127
+ servicio sale listo, con el puerto y la marca `externo`; con dos o más, los
128
+ puertos se listan en el proyecto sin adivinar de cuál son.
129
+
130
+ StackHelx además saca del entorno de los servicios las variables que delatan a un
131
+ agente (`CLAUDECODE`, `AI_AGENT`, `OPENCODE`, `GEMINI_CLI` y parecidas). Astro 7
132
+ manda `astro dev` a segundo plano cuando las ve, y el servidor queda fuera del
133
+ árbol, sin puerto y sin forma de apagarlo. Si la declaras en `env.global` o en
134
+ el `env` del servicio, vale.
135
+
120
136
  `stackhelx init` escribe lo detectado como `stack.yaml` para editarlo a mano.
121
137
  No sobreescribe uno existente.
@@ -3,7 +3,7 @@
3
3
  [English](../interfaz.md) · **Español**
4
4
 
5
5
  Cómo se arranca y qué muestra está en el
6
- [README](../../README.es.md#interfaz-web). Acá está el detalle de cada control y por
6
+ [README](../../README.es.md#interfaz-web). Aquí está el detalle de cada control y por
7
7
  qué se comporta como se comporta.
8
8
 
9
9
  ## Selector de idioma (EN / ES)
@@ -16,7 +16,7 @@ La interfaz abre en inglés por defecto y recuerda tu elección en `localStorage
16
16
  ## Caídas y avisos
17
17
 
18
18
  Cuando un servicio se muere solo, el título de la pestaña lleva un contador y
19
- el encabezado dice cuántos hay caídos. Con `Avisarme` podés además pedir
19
+ el encabezado dice cuántos hay caídos. Con `Avisarme` puedes además pedir
20
20
  notificaciones del navegador, que solo avisan de caídas nuevas y nunca de un
21
21
  `Apagar` ni de un `Reiniciar`. El permiso se pide con ese click y nunca al
22
22
  cargar la página.
@@ -78,6 +78,18 @@ error del propio Docker. Cuando el motor termina de levantar, el botón no
78
78
  desaparece: pasa a decir `Reiniciar Docker`. Lo mueve la misma vista de estado
79
79
  que ya sondea `docker info`.
80
80
 
81
+ ## Mapa de puertos
82
+
83
+ El mapa abre en `Todo el sistema`: cada socket que el sistema reporta en escucha,
84
+ con protocolo, dirección (`0.0.0.0` o `::` sale marcado como expuesto a la red),
85
+ proceso, línea de comandos y, si se puede atribuir, el proyecto registrado al que
86
+ pertenece. Se lee al abrir el mapa o al tocar `Refrescar`, nunca en segundo
87
+ plano. `Ocultar procesos de Windows` (activo por defecto) esconde RPC, SMB y
88
+ parecidos, `Incluir UDP` suma los sockets UDP ligados, y el filtro busca por
89
+ puerto, proceso, proyecto o comando. La pestaña `De proyectos` muestra solo los
90
+ puertos de proyectos registrados, incluidos los servidores arrancados fuera de
91
+ StackHelx.
92
+
81
93
  ## Explorar carpetas
82
94
 
83
95
  Para registrar un proyecto no hace falta copiar la ruta: `Explorar…` abre un
@@ -93,4 +105,4 @@ El servidor escucha solo en loopback y exige un token que `serve` genera en
93
105
  `~/.stackhelx/token` y pasa en la URL de arranque. Ejecuta los comandos de tus
94
106
  `stack.yaml`, así que se trata como superficie sensible: rate limit en todas las
95
107
  rutas, CSP estricta, y validación del header `Host` contra rebinding de DNS.
96
- Podés fijar el token vos mismo con `STACKHELX_TOKEN`.
108
+ Puedes fijar el token tú mismo con `STACKHELX_TOKEN`.
@@ -2,7 +2,7 @@
2
2
 
3
3
  [English](../stack-yaml.md) · **Español**
4
4
 
5
- El ejemplo mínimo está en el [README](../../README.es.md#stackyaml). Acá está cada
5
+ El ejemplo mínimo está en el [README](../../README.es.md#stackyaml). Aquí está cada
6
6
  campo, con el ejemplo completo y comentado en
7
7
  [`stack.example.yaml`](../../stack.example.yaml).
8
8
 
@@ -19,8 +19,8 @@ cada nivel en lugar de la suma de todos, a cambio de que los logs de los
19
19
  primeros segundos se entreveren. Van prefijados por servicio y con un color
20
20
  propio cada uno, así que se siguen leyendo.
21
21
 
22
- `default` es opcional y lista qué arranca cuando no pedís perfil. Sin él,
23
- arranca todo, que es lo que casi siempre querés. Existe para el caso de abajo.
22
+ `default` es opcional y lista qué arranca cuando no pides perfil. Sin él,
23
+ arranca todo, que es lo que casi siempre quieres. Existe para el caso de abajo.
24
24
 
25
25
  ## Perfiles de un compose detectado
26
26
 
@@ -55,7 +55,7 @@ archivo congelado prendería lo que el compose deja apagado a propósito.
55
55
  | `none` | nada (default si no hay `port`) |
56
56
 
57
57
  `listen` es para servicios que eligen su propio puerto. Es incompatible con
58
- `port`: si lo conocés, el healthcheck es `port`.
58
+ `port`: si lo conoces, el healthcheck es `port`.
59
59
 
60
60
  `port` no distingue quién contesta. Si alguien ya escuchaba ahí antes de
61
61
  arrancar, el servicio se declara listo en el acto aunque el `listo` sea de otro
@@ -57,6 +57,16 @@ The stray processes section (`Stray processes`) follows the same principle: as
57
57
  long as at least one project is registered, the section stays visible and
58
58
  explicitly states when zero stray processes are holding your ports.
59
59
 
60
+ The port map opens on `All system`: every socket the OS reports as listening,
61
+ with protocol, bind address (`0.0.0.0` or `::` is marked as exposed to the
62
+ network), process, command line and, when it can be attributed, the registered
63
+ project it belongs to. It is read on demand when you open the map or press
64
+ `Refresh`, never polled. `Hide Windows processes` (on by default) hides RPC,
65
+ SMB and similar system listeners, `Include UDP` adds bound UDP sockets, and the
66
+ filter matches port, process, project or command line. The `Projects` tab shows
67
+ only ports tied to registered projects, including servers started outside
68
+ StackHelx.
69
+
60
70
  Restarting Docker asks for inline confirmation because it restarts every running
61
71
  container on the machine, including containers from other projects. Starting
62
72
  Docker runs immediately without confirmation.
@@ -0,0 +1,2 @@
1
+ __version__ = "1.1.4"
2
+
@@ -611,7 +611,7 @@ def serve_cmd(
611
611
 
612
612
  from . import server
613
613
  except ImportError:
614
- err.print("Missing fastapi or uvicorn. Reinstall stackhelx: pipx reinstall stackhelx")
614
+ err.print("Missing fastapi or uvicorn. Reinstall stackhelx: uv tool install --force stackhelx (or: pipx reinstall stackhelx)")
615
615
  raise typer.Exit(1)
616
616
 
617
617
  if not ports.is_free(port):
@@ -7,6 +7,7 @@ saliendo de `doctor._docker`, que es quien ya lo sabe.
7
7
 
8
8
  from __future__ import annotations
9
9
 
10
+ import re
10
11
  import subprocess
11
12
  from collections.abc import Sequence
12
13
 
@@ -105,6 +106,36 @@ def running() -> list[str]:
105
106
  return [line.strip() for line in (done.stdout or "").splitlines() if line.strip()]
106
107
 
107
108
 
109
+ def published() -> dict[int, str] | None:
110
+ """Puerto del host publicado -> carpeta del compose que levanto el contenedor.
111
+
112
+ Cadena vacia si el contenedor no es de un compose (un `docker run` suelto).
113
+ None si docker no contesta: ahi no se sabe de quien es, y no se adivina.
114
+ """
115
+ try:
116
+ done = subprocess.run(
117
+ ["docker", "ps", "--format", '{{.Ports}}\t{{.Label "com.docker.compose.project.working_dir"}}'],
118
+ capture_output=True,
119
+ text=True,
120
+ errors="replace",
121
+ timeout=TIMEOUT,
122
+ )
123
+ except (OSError, subprocess.SubprocessError):
124
+ return None
125
+ if done.returncode != 0:
126
+ return None
127
+ return _parse_published(done.stdout or "")
128
+
129
+
130
+ def _parse_published(salida: str) -> dict[int, str]:
131
+ found: dict[int, str] = {}
132
+ for line in salida.splitlines():
133
+ puertos, _, carpeta = line.partition("\t")
134
+ for port in re.findall(r":(\d+)->", puertos):
135
+ found[int(port)] = carpeta.strip()
136
+ return found
137
+
138
+
108
139
  def usage() -> str | None:
109
140
  """La tabla de `docker system df`, para que la confirmacion diga cuanto hay.
110
141
 
@@ -50,6 +50,11 @@ class PortStatus:
50
50
  name: str | None = None
51
51
  cmdline: str | None = None
52
52
  create_time: float | None = None
53
+ # Solo los llena `system_listeners`: el resto de los llamadores preguntan
54
+ # por un puerto TCP concreto y no los necesitan.
55
+ proto: str = "tcp"
56
+ addrs: tuple[str, ...] = ()
57
+ cwd: str | None = None
53
58
 
54
59
  @property
55
60
  def owner_unknown(self) -> bool:
@@ -237,42 +242,68 @@ def _listeners(wanted: set[int]) -> dict[int, int | None]:
237
242
  return found
238
243
 
239
244
 
240
- def system_listeners() -> list[PortStatus]:
241
- """Puertos TCP actualmente en LISTEN en el sistema operativo.
245
+ def system_listeners(udp: bool = False) -> list[PortStatus]:
246
+ """Sockets en escucha en el sistema operativo, uno por (protocolo, puerto, pid).
242
247
 
243
- Devuelve la lista ordenada por puerto con el estado y proceso dueno.
248
+ Indexar solo por puerto dejaba un dueno por numero: TCP y UDP, o dos
249
+ procesos en 127.0.0.1 y [::], se pisaban. Las IP del mismo dueno se juntan
250
+ en `addrs`. UDP no tiene LISTEN: con `udp=True` entra todo socket UDP ligado.
244
251
  """
245
- listeners: dict[int, int | None] = {}
252
+ kind = "inet" if udp else "tcp"
253
+ found: dict[tuple[str, int, int | None], set[str]] = {}
254
+
255
+ def add(conn, pid: int | None) -> None:
256
+ if not conn.laddr:
257
+ return
258
+ if conn.type == socket.SOCK_STREAM:
259
+ if conn.status != psutil.CONN_LISTEN:
260
+ return
261
+ proto = "tcp"
262
+ else:
263
+ proto = "udp"
264
+ found.setdefault((proto, conn.laddr.port, pid), set()).add(conn.laddr.ip)
265
+
246
266
  try:
247
- for conn in psutil.net_connections(kind="tcp"):
248
- if conn.laddr and conn.status == psutil.CONN_LISTEN:
249
- port = conn.laddr.port
250
- if port not in listeners or conn.pid:
251
- listeners[port] = conn.pid
267
+ for conn in psutil.net_connections(kind=kind):
268
+ add(conn, conn.pid)
252
269
  except (psutil.AccessDenied, PermissionError):
253
- listeners = _process_listeners_cache()
270
+ # macOS sin root niega la tabla global, pero deja leer los sockets de
271
+ # cada proceso propio: misma informacion, sin los procesos ajenos.
272
+ for proc in psutil.process_iter():
273
+ try:
274
+ for conn in proc.net_connections(kind=kind):
275
+ add(conn, proc.pid)
276
+ except (psutil.AccessDenied, psutil.NoSuchProcess):
277
+ continue
254
278
 
255
- proc_cache: dict[int, tuple[str | None, str | None, float | None]] = {}
256
- for pid in set(listeners.values()):
257
- if pid is None:
279
+ # Windows a veces reporta el mismo socket con y sin pid: si hay dueno, el
280
+ # registro sin pid sobra.
281
+ con_dueno = {(proto, port) for proto, port, pid in found if pid is not None}
282
+ for key in [k for k in found if k[2] is None and (k[0], k[1]) in con_dueno]:
283
+ del found[key]
284
+
285
+ proc_cache: dict[int, tuple[str | None, str | None, float | None, str | None]] = {}
286
+ for _, _, pid in found:
287
+ if pid is None or pid in proc_cache:
258
288
  continue
259
289
  try:
260
290
  proc = psutil.Process(pid)
261
291
  with proc.oneshot():
262
- name = _quiet(proc.name)
263
- cmdline = _quiet(lambda: " ".join(proc.cmdline()))
264
- created = _quiet(proc.create_time)
265
- proc_cache[pid] = (name, cmdline, created)
292
+ proc_cache[pid] = (
293
+ _quiet(proc.name),
294
+ _quiet(lambda: " ".join(proc.cmdline())),
295
+ _quiet(proc.create_time),
296
+ _quiet(proc.cwd),
297
+ )
266
298
  except (psutil.AccessDenied, psutil.NoSuchProcess):
267
- proc_cache[pid] = (None, None, None)
299
+ proc_cache[pid] = (None, None, None, None)
268
300
 
269
301
  statuses: list[PortStatus] = []
270
- for port, pid in sorted(listeners.items()):
271
- if pid is not None and pid in proc_cache:
272
- name, cmdline, created = proc_cache[pid]
273
- statuses.append(PortStatus(port, False, pid, name, cmdline or None, created))
274
- else:
275
- statuses.append(PortStatus(port=port, free=False, pid=pid))
302
+ for (proto, port, pid), ips in sorted(found.items(), key=lambda kv: (kv[0][1], kv[0][0], kv[0][2] or 0)):
303
+ name, cmdline, created, cwd = proc_cache.get(pid, (None, None, None, None)) if pid else (None,) * 4
304
+ statuses.append(
305
+ PortStatus(port, False, pid, name, cmdline or None, created, proto, tuple(sorted(ips)), cwd)
306
+ )
276
307
  return statuses
277
308
 
278
309
 
@@ -153,6 +153,52 @@ def declared_ports(max_age: float = 0.0) -> dict[int, list[Path]]:
153
153
  return found
154
154
 
155
155
 
156
+ # Interpretes: con el cwd en un proyecto, lo que corren es codigo del proyecto.
157
+ # Un binario propio (claude.exe, un servidor MCP) hereda el cwd de quien lo
158
+ # abrio y no dice nada del proyecto.
159
+ RUNTIMES = ("node", "bun", "deno", "java", "javaw", "dotnet", "php", "ruby")
160
+
161
+
162
+ def _is_runtime(name: str | None) -> bool:
163
+ stem = os.path.splitext((name or "").lower())[0]
164
+ return stem in RUNTIMES or stem.startswith("python")
165
+
166
+
167
+ def project_for(
168
+ cwd: str | None, cmdline: str | None, roots: list[Path], name: str | None = None
169
+ ) -> Path | None:
170
+ """Proyecto registrado al que pertenece un proceso, o None.
171
+
172
+ `detect` no adivina puertos, asi que un servidor lanzado desde otra terminal
173
+ no tiene como asociarse a su proyecto. Esto lo asocia por evidencia del
174
+ proceso: un path del proyecto en su cmdline (`node A:\\proj\\node_modules\\...`),
175
+ y si no, su `cwd`, pero solo si `name` es un interprete. Medido: el cwd solo
176
+ le atribuia al Portfolio `claude.exe` y dos servidores MCP abiertos ahi.
177
+ Gana el root mas largo, para que un proyecto anidado le gane a su carpeta
178
+ madre. Pura a proposito: el que llama le pasa los roots una vez por request.
179
+ """
180
+ by_length = sorted(roots, key=lambda r: len(str(r)), reverse=True)
181
+ if cmdline:
182
+ line = os.path.normcase(cmdline)
183
+ for root in by_length:
184
+ r = os.path.normcase(str(root)).rstrip(os.sep)
185
+ start = line.find(r)
186
+ while start != -1:
187
+ # Lo que sigue al root tiene que cerrar el componente: sin esto
188
+ # `A:\app` se atribuia `A:\app2\x.js`.
189
+ after = line[start + len(r) : start + len(r) + 1]
190
+ if after in ("", os.sep, '"', "'", " "):
191
+ return root
192
+ start = line.find(r, start + 1)
193
+ if cwd and _is_runtime(name):
194
+ here = os.path.normcase(cwd)
195
+ for root in by_length:
196
+ r = os.path.normcase(str(root))
197
+ if here == r or here.startswith(r.rstrip(os.sep) + os.sep):
198
+ return root
199
+ return None
200
+
201
+
156
202
  def name_of(path: Path, max_age: float = PORTS_TTL) -> str:
157
203
  """Como se llama un proyecto registrado, igual que en su ficha.
158
204
 
@@ -225,7 +271,9 @@ def _stack_of(path: Path) -> tuple[str, set[int]]:
225
271
  """
226
272
  try:
227
273
  stack = detect.stack_for(path)
228
- return stack.name, {s.port for s in stack.resolve() if s.port}
274
+ # Todos los servicios, no solo el default: un perfil aparte tambien
275
+ # reclama su puerto, igual que en find_orphans.
276
+ return stack.name, {s.port for s in stack.services.values() if s.port}
229
277
  except (config.ConfigError, OSError):
230
278
  return path.name, set()
231
279
 
@@ -28,16 +28,45 @@ from rich.console import Console
28
28
  from . import config, detect, ports
29
29
  from .config import Service, Stack
30
30
 
31
+ # Variables con las que `am-i-vibing` reconoce a un agente por si solas. Astro 7
32
+ # la usa en `astro dev` (dist/cli/dev/index.js:85) y, si detecta uno, arranca
33
+ # como daemon: el comando sale con 0, el servidor queda fuera de nuestro arbol y
34
+ # se pierden `ready: listen`, la tarjeta y el `down`. StackHelx es el dueno del
35
+ # ciclo de vida del servicio, lo lance una persona o un agente via MCP.
36
+ # Fuera quedan las genericas (`PAGER`, `TERM_PROGRAM`, `REPL_ID`) que el
37
+ # detector solo combina con otras. Tabla de am-i-vibing 0.4.0.
38
+ AGENT_ENV_VARS = (
39
+ "CLAUDECODE",
40
+ "AI_AGENT",
41
+ "OPENCODE",
42
+ "OPENCODE_BIN_PATH",
43
+ "OPENCODE_SERVER",
44
+ "OPENCODE_APP_INFO",
45
+ "OPENCODE_MODES",
46
+ "ANTIGRAVITY_AGENT",
47
+ "ANTIGRAVITY_PROJECT_ID",
48
+ "GEMINI_CLI",
49
+ "CODEX_THREAD_ID",
50
+ "CODEIUM_EDITOR_APP_ROOT",
51
+ "CRUSH",
52
+ "AMP_CURRENT_THREAD_ID",
53
+ "AUGMENT_AGENT",
54
+ "QWEN_CODE",
55
+ )
56
+
31
57
 
32
58
  def build_env(service: Service, extra_env: dict[str, str] | None = None) -> dict[str, str]:
33
59
  """Construye el entorno de ejecucion con precedencia clara:
34
- 1. os.environ
60
+ 1. os.environ, sin las AGENT_ENV_VARS
35
61
  2. ~/.stackhelx/env.global (o legacy ~/.portmaster/env.global si existe)
36
62
  3. service.env_file (en orden)
37
63
  4. service.env (declarado explicito)
38
64
  5. extra_env (e.g. desde --env-file en CLI)
39
65
  """
40
66
  env = dict(os.environ)
67
+ # Solo del entorno heredado: si env.global o el servicio la declaran, vale.
68
+ for name in AGENT_ENV_VARS:
69
+ env.pop(name, None)
41
70
  global_env = Path.home() / ".stackhelx" / "env.global"
42
71
  if not global_env.is_file():
43
72
  global_env = Path.home() / ".portmaster" / "env.global"