stackhelx 1.1.1__tar.gz → 1.1.2__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 (70) hide show
  1. {stackhelx-1.1.1 → stackhelx-1.1.2}/.gitignore +1 -0
  2. {stackhelx-1.1.1 → stackhelx-1.1.2}/CHANGELOG.md +7 -0
  3. stackhelx-1.1.2/PKG-INFO +336 -0
  4. stackhelx-1.1.1/README.md → stackhelx-1.1.2/README.es.md +6 -4
  5. stackhelx-1.1.2/README.md +277 -0
  6. stackhelx-1.1.2/docs/comandos.md +277 -0
  7. stackhelx-1.1.2/docs/deteccion.md +102 -0
  8. {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/comandos.md +3 -1
  9. {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/deteccion.md +3 -1
  10. {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/interfaz.md +3 -1
  11. {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/stack-yaml.md +4 -2
  12. stackhelx-1.1.2/docs/interfaz.md +81 -0
  13. stackhelx-1.1.2/docs/stack-yaml.md +195 -0
  14. {stackhelx-1.1.1 → stackhelx-1.1.2}/pyproject.toml +1 -1
  15. stackhelx-1.1.2/stack.example.yaml +78 -0
  16. stackhelx-1.1.2/stackhelx/__init__.py +2 -0
  17. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/ports.py +41 -2
  18. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/server.py +28 -0
  19. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/app.css +28 -0
  20. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/app.js +80 -0
  21. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/index.html +6 -2
  22. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_ports.py +24 -0
  23. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_server.py +12 -0
  24. stackhelx-1.1.1/PKG-INFO +0 -330
  25. stackhelx-1.1.1/docs/pendientes.md +0 -117
  26. stackhelx-1.1.1/docs/plan-expansion.md +0 -97
  27. stackhelx-1.1.1/docs/plan-lenguajes.md +0 -388
  28. stackhelx-1.1.1/docs/plan-siguiente.md +0 -323
  29. stackhelx-1.1.1/docs/superpowers/plans/2026-08-08-partir-readme.md +0 -377
  30. stackhelx-1.1.1/docs/superpowers/plans/2026-08-08-release-1-0-1.md +0 -378
  31. stackhelx-1.1.1/docs/superpowers/plans/2026-08-18-campo-url.md +0 -222
  32. stackhelx-1.1.1/docs/superpowers/specs/2026-07-29-autodeteccion-design.md +0 -70
  33. stackhelx-1.1.1/stack.example.yaml +0 -76
  34. stackhelx-1.1.1/stackhelx/__init__.py +0 -2
  35. {stackhelx-1.1.1 → stackhelx-1.1.2}/.github/workflows/ci.yml +0 -0
  36. {stackhelx-1.1.1 → stackhelx-1.1.2}/.github/workflows/release.yml +0 -0
  37. {stackhelx-1.1.1 → stackhelx-1.1.2}/AGENTS.md +0 -0
  38. {stackhelx-1.1.1 → stackhelx-1.1.2}/CLAUDE.md +0 -0
  39. {stackhelx-1.1.1 → stackhelx-1.1.2}/LICENSE +0 -0
  40. {stackhelx-1.1.1 → stackhelx-1.1.2}/scripts/check_docs.py +0 -0
  41. {stackhelx-1.1.1 → stackhelx-1.1.2}/scripts/check_metadata.py +0 -0
  42. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/__main__.py +0 -0
  43. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/browse.py +0 -0
  44. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/cli.py +0 -0
  45. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/config.py +0 -0
  46. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/detect.py +0 -0
  47. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/docker.py +0 -0
  48. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/doctor.py +0 -0
  49. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/guardrails.py +0 -0
  50. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/history.py +0 -0
  51. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/mcp.py +0 -0
  52. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/registry.py +0 -0
  53. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/runner.py +0 -0
  54. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/scripts.py +0 -0
  55. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/tunnel.py +0 -0
  56. {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/tokens.css +0 -0
  57. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/conftest.py +0 -0
  58. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_browse.py +0 -0
  59. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_cli.py +0 -0
  60. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_config.py +0 -0
  61. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_conftest.py +0 -0
  62. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_detect.py +0 -0
  63. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_guardrails.py +0 -0
  64. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_history.py +0 -0
  65. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_mcp.py +0 -0
  66. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_registry.py +0 -0
  67. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_runner.py +0 -0
  68. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_scripts.py +0 -0
  69. {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_tunnel.py +0 -0
  70. {stackhelx-1.1.1 → stackhelx-1.1.2}/uv.lock +0 -0
@@ -11,3 +11,4 @@ venv/
11
11
  # Grafo de codigo, 4 MB generados. Se rehace con `graphify update .`
12
12
  graphify-out/
13
13
  scratch/
14
+ .archive/
@@ -4,6 +4,13 @@ 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.2] - 2026-10-06
8
+
9
+ ### Añadido y Mejorado
10
+
11
+ - **Documentación Bilingüe (Inglés / Español):** `README.md`, `stack.example.yaml`, `pyproject.toml` y la documentación técnica en `docs/` pasan al inglés como idioma principal para PyPI y GitHub, preservando la documentación completa en español en `README.es.md` y `docs/es/` con navegación recíproca y cero impacto en el runtime.
12
+ - **Detección de Puertos del Sistema y Soporte IPv6 Dual-Stack (`ports.py`, `server.py`, `web/`):** Escaneo completo de puertos TCP en escucha del sistema operativo (`/api/ports/system`) y soporte dual-stack IPv4/IPv6 en las sondas de disponibilidad y cierre seguro de puertos.
13
+
7
14
  ## [1.1.1] - 2026-09-24
8
15
 
9
16
  ### Corregido y Mejorado
@@ -0,0 +1,336 @@
1
+ Metadata-Version: 2.5
2
+ Name: stackhelx
3
+ Version: 1.1.2
4
+ Summary: Local development environment orchestrator: ports, Docker, backend, and frontend with a single command
5
+ Project-URL: Homepage, https://github.com/TicoraX/StackHelx
6
+ Project-URL: Repository, https://github.com/TicoraX/StackHelx
7
+ Project-URL: Issues, https://github.com/TicoraX/StackHelx/issues
8
+ Author: TicoraX
9
+ License: MIT License
10
+
11
+ Copyright (c) 2026 TicoraX
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a copy
14
+ of this software and associated documentation files (the "Software"), to deal
15
+ in the Software without restriction, including without limitation the rights
16
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
17
+ copies of the Software, and to permit persons to whom the Software is
18
+ furnished to do so, subject to the following conditions:
19
+
20
+ The above copyright notice and this permission notice shall be included in all
21
+ copies or substantial portions of the Software.
22
+
23
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
28
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29
+ SOFTWARE.
30
+ License-File: LICENSE
31
+ Keywords: cli,devtools,docker,dx,orchestration,ports,stackhelx
32
+ Classifier: Development Status :: 5 - Production/Stable
33
+ Classifier: Environment :: Console
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: License :: OSI Approved :: MIT License
36
+ Classifier: Operating System :: OS Independent
37
+ Classifier: Programming Language :: Python :: 3
38
+ Classifier: Programming Language :: Python :: 3.10
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Programming Language :: Python :: 3.13
42
+ Classifier: Topic :: Software Development
43
+ Classifier: Topic :: System :: Systems Administration
44
+ Classifier: Topic :: Utilities
45
+ Requires-Python: >=3.10
46
+ Requires-Dist: fastapi>=0.115
47
+ Requires-Dist: psutil>=6.0
48
+ Requires-Dist: pyyaml>=6.0
49
+ Requires-Dist: rich>=13
50
+ Requires-Dist: tomli>=2.0; python_version < '3.11'
51
+ Requires-Dist: typer>=0.12
52
+ Requires-Dist: uvicorn>=0.30
53
+ Provides-Extra: dev
54
+ Requires-Dist: httpx>=0.27; extra == 'dev'
55
+ Requires-Dist: pytest-xdist>=3; extra == 'dev'
56
+ Requires-Dist: pytest>=8; extra == 'dev'
57
+ Requires-Dist: ruff>=0.6; extra == 'dev'
58
+ Description-Content-Type: text/markdown
59
+
60
+ # StackHelx
61
+
62
+ [![pypi](https://img.shields.io/pypi/v/stackhelx?logo=pypi&logoColor=white)](https://pypi.org/project/stackhelx/)
63
+ [![tests](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml/badge.svg?branch=main&cache=none)](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml)
64
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
65
+ [![python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
66
+
67
+ **English** · [Español](README.es.md)
68
+
69
+ Local development environment orchestrator. One file at the project root, one
70
+ command, and your entire stack is up: free ports, Docker, backend, and frontend,
71
+ without juggling four open terminals.
72
+
73
+ ## Installation
74
+
75
+ ```bash
76
+ uv tool install stackhelx
77
+ # or
78
+ pipx install stackhelx
79
+ ```
80
+
81
+ Installing registers two identical executables on your system: the full command
82
+ **`stackhelx`** and its short alias **`shx`**.
83
+
84
+ Requires Python 3.10 or later. Runs on Windows, macOS, and Linux.
85
+
86
+ ## Commands
87
+
88
+ Every command runs as `stackhelx <command>` or via its official short alias
89
+ **`shx <command>`** (e.g. `shx up`, `shx down`, `shx doctor`, `shx ports`):
90
+
91
+ | Command (`stackhelx` / `shx`) | What it does |
92
+ |---|---|
93
+ | `stackhelx up` | Boots the entire stack: frees ports, starts services in topological order, and tails logs |
94
+ | `stackhelx down` | Stops services that outlive the terminal, such as containers |
95
+ | `stackhelx serve` | Opens the web dashboard at `http://127.0.0.1:7666` |
96
+ | `stackhelx doctor` | Checks what could block startup without starting anything |
97
+ | `stackhelx ports` | Shows the status of declared ports |
98
+ | `stackhelx free 3000` | Terminates the process holding a port, asking first |
99
+ | `stackhelx free --all` | Frees all occupied ports across all registered projects |
100
+ | `stackhelx switch fitness` | Stops registered projects that collide on ports with the target, then boots it |
101
+ | `stackhelx open` | Opens the first service that answers HTTP in your browser |
102
+ | `stackhelx init` | Freezes auto-detected services into an editable `stack.yaml` |
103
+ | `stackhelx add .` | Registers the project so it appears in the web dashboard |
104
+ | `stackhelx list` | Lists registered projects (alias: `ls`) |
105
+ | `stackhelx remove .` | Unregisters a project (alias: `rm`) |
106
+ | `stackhelx run [task]` | Runs project scripts or sequential task pipelines |
107
+ | `stackhelx share [target]` | Exposes a local service to the internet over an ephemeral tunnel |
108
+ | `stackhelx clean` | Cleans Docker resources by category: stopped containers, untagged images, unused networks, and build cache. Volumes are separate via `--volumes`. Prompts before deleting |
109
+ | `stackhelx mcp` | Starts the Model Context Protocol (MCP) server over stdio for AI agents |
110
+ | `stackhelx test-stack` | Validates `stack.yaml` without starting anything: topological order, dependencies, and ports |
111
+ | `stackhelx history` | Shows recent stack runs with duration and final state |
112
+ | `stackhelx logs` | Reads logs from a project running in `serve` (`--follow` to stream) |
113
+ | `stackhelx stats` | Displays real-time CPU and memory usage for services running in `serve` (alias: `top`) |
114
+ | `stackhelx version` | Prints the installed version (also `--version`) |
115
+
116
+ `logs` and `stats` query a running `stackhelx serve` instance, so `serve` must
117
+ be active. `history` and `test-stack` read directly from disk.
118
+
119
+ Pass `--help` to any command for full flag details.
120
+
121
+ ## Starting a stack
122
+
123
+ ```bash
124
+ shx up
125
+ # or
126
+ stackhelx up
127
+
128
+ shx up --profile backend # start only a subset
129
+ shx up --no-free # leave occupied ports untouched
130
+ shx up --env-file .env.qa # load this .env file before booting
131
+ ```
132
+
133
+ `--env-file` adds to `env_file:` in `stack.yaml` rather than replacing it: it
134
+ loads the file into the process environment before resolving the stack, making
135
+ variables visible to all services. Use it for one-off runs against another
136
+ environment without editing `stack.yaml`. Unlike `env_file:`, it accepts paths
137
+ outside the project root because you type the path yourself at the terminal
138
+ instead of inheriting it from an untrusted repository.
139
+
140
+ Before starting, StackHelx checks every declared port and prompts before
141
+ terminating any stray process holding one. Ports already published by Docker are
142
+ skipped automatically because the container is already up.
143
+
144
+ ```
145
+ demo stack.yaml
146
+ db | $ docker compose up -d postgres
147
+ db | listo (5432)
148
+ api | $ npm run dev
149
+ api | escuchando en 8080
150
+ api | listo (8080)
151
+ web | $ npm run dev
152
+ web | listo (3000)
153
+ Todo listo. Ctrl-C para apagar.
154
+ api | GET /health 200
155
+ web | ready in 412 ms
156
+ ```
157
+
158
+ Pressing `Ctrl-C` shuts down services in reverse topological order, killing the
159
+ entire process tree of each service.
160
+
161
+ ## Without stack.yaml
162
+
163
+ `stack.yaml` is optional. When none is present, StackHelx inspects the project
164
+ root:
165
+
166
+ | Finds | Starts |
167
+ |---|---|
168
+ | `compose.yaml`, `compose.yml`, `docker-compose.yml`, `docker-compose.yaml` | One service per container: `docker compose up -d <name>` |
169
+ | `manage.py` | `python manage.py runserver` |
170
+ | `fastapi` or `uvicorn` declared, with a module defining `app` | `uvicorn <module>:app --reload` |
171
+ | `package.json` with a server script (`dev`, `start:dev`, `serve`, `start`) | `npm run dev`, switching to `pnpm`/`yarn`/`bun` based on lockfile or `packageManager` |
172
+
173
+ ```
174
+ mi-app A:\Proyectos\mi-app
175
+ Sin stack.yaml. Detectado:
176
+ docker docker compose up -d 5433
177
+ web pnpm run dev al arrancar
178
+ Para congelarlo en un archivo editable: stackhelx init
179
+ Arrancar? [Y/n]
180
+ ```
181
+
182
+ Services start in that order and chain dependencies automatically: frontend
183
+ waits for backend, and backend waits for containers.
184
+
185
+ `stackhelx init` writes the detected configuration to `stack.yaml` so you can
186
+ edit it by hand. It never overwrites an existing file.
187
+
188
+ Where StackHelx searches for each language and why it matches specific signals
189
+ is documented in [`docs/deteccion.md`](docs/deteccion.md).
190
+
191
+ ## stack.yaml
192
+
193
+ Place `stack.yaml` at the project root. StackHelx searches upward from your
194
+ current working directory, so you can run commands from any subdirectory.
195
+
196
+ ```yaml
197
+ name: my-project
198
+
199
+ services:
200
+ db:
201
+ command: docker compose up -d postgres
202
+ port: 5432
203
+ detached: true # command exits while the container stays alive
204
+
205
+ api:
206
+ command: npm run dev
207
+ cwd: backend
208
+ port: 8080
209
+ needs: [db]
210
+ env:
211
+ DATABASE_URL: postgres://localhost:5432/app
212
+
213
+ web:
214
+ command: npm run dev
215
+ cwd: frontend
216
+ port: 3000
217
+ needs: [api]
218
+
219
+ profiles:
220
+ backend: [api] # pulls in db automatically via its dependency chain
221
+ ```
222
+
223
+ `command` is the only required field. The complete field reference, `ready`
224
+ healthcheck modes, and inherited Compose profiles live in
225
+ [`docs/stack-yaml.md`](docs/stack-yaml.md).
226
+
227
+ ## Web dashboard
228
+
229
+ When you work across multiple projects, the CLI only sees the current directory.
230
+ The web dashboard shows all registered projects at once.
231
+
232
+ ```bash
233
+ stackhelx serve # opens http://127.0.0.1:7666
234
+ ```
235
+
236
+ Included out of the box with no extra dependencies. Register projects directly
237
+ from the browser via `Explorar…` or from the terminal with `stackhelx add .`.
238
+
239
+ Monitor service states, start and stop stacks, free ports held by stray
240
+ processes, inspect system-wide listening ports, and stream live logs per project.
241
+
242
+ Control details and the local server security model are covered in
243
+ [`docs/interfaz.md`](docs/interfaz.md).
244
+
245
+ ## Ports
246
+
247
+ Inspect port status without starting anything:
248
+
249
+ ```bash
250
+ stackhelx ports # ports declared in stack.yaml
251
+ stackhelx ports 3000 8080 # specific ports
252
+ ```
253
+
254
+ ```
255
+ PUERTO ESTADO PID PROCESO COMANDO
256
+ 3000 ocupado 24188 node.exe node C:\proj\frontend\node_modules\.bin\vite
257
+ 8080 libre - - -
258
+ 5432 ocupado 9012 com.docker.backend.exe
259
+ ```
260
+
261
+ Free a port held by a zombie process:
262
+
263
+ ```bash
264
+ stackhelx free 3000
265
+ ```
266
+
267
+ Shows the owning process and asks for confirmation before terminating it. If you
268
+ decline, it suggests the next available port.
269
+
270
+ Flags: `--yes` skips confirmation (for scripts), `--force` escalates to `kill()`
271
+ when the process ignores graceful termination.
272
+
273
+ After a crash or branch switch, multiple ports may stay occupied:
274
+
275
+ ```bash
276
+ stackhelx free --all
277
+ ```
278
+
279
+ Scans every port declared across all registered projects, lists what is occupied,
280
+ and asks for a single confirmation. Exits with code 1 if any port could not be
281
+ freed.
282
+
283
+ The CLI does not track which processes you started in other terminals: if another
284
+ stack is running in a separate shell, its services appear in that list too. That
285
+ is why the CLI prints the full list before touching anything and defaults the
286
+ prompt to "no". The web dashboard tracks its own active sessions and excludes
287
+ them automatically when clicking "Liberar todos".
288
+
289
+ ## What the kill switch refuses to do
290
+
291
+ These guardrails are enforced in code:
292
+
293
+ - Never terminates PID 0, PID 4, StackHelx itself, or any of its parent
294
+ processes. Killing your own terminal is not a feature.
295
+ - Revalidates process creation time (`create_time`) between scanning and
296
+ signaling. OS PIDs recycle quickly; without this check, you risk killing an
297
+ unrelated process.
298
+ - Sends `terminate()` and waits 5 seconds. Escalates to `kill()` only with
299
+ explicit `--force`, because force-killing an `npm run dev` wrapper leaves
300
+ orphaned child processes behind.
301
+ - Fails fast when permissions are insufficient instead of attempting privilege
302
+ escalation.
303
+ - Never kills the Docker or WSL proxy process. A port published by a container
304
+ is bound by a shared host proxy process; killing it takes down the entire
305
+ Docker engine. Instead, StackHelx tells you which container to stop.
306
+
307
+ ## Other commands
308
+
309
+ `down`, `switch`, `doctor`, `open`, `run`, `share`, `clean`, and `mcp` are
310
+ detailed in [`docs/comandos.md`](docs/comandos.md).
311
+
312
+ ## Trust model
313
+
314
+ `stack.yaml` runs arbitrary commands, just like `package.json` or a `Makefile`.
315
+ StackHelx does not sandbox them. Treat a `stack.yaml` from an untrusted
316
+ repository with the same caution you give its build scripts.
317
+
318
+ Without `stack.yaml`, commands come from auto-detection, and `scripts.dev` in an
319
+ untrusted `package.json` is equally arbitrary. That is why `up` prints the exact
320
+ commands it detected and asks for confirmation before executing anything, while
321
+ `-y` lets you skip the prompt once you trust the project.
322
+
323
+ ## Development
324
+
325
+ ```bash
326
+ python -m venv .venv
327
+ .venv/bin/pip install -e ".[dev]" # .venv\Scripts\pip on Windows
328
+ pytest -q -n auto
329
+ ```
330
+
331
+ Tests run against real OS sockets and processes with zero mocks. That is the
332
+ only way to verify software whose job is talking to the operating system.
333
+
334
+ ## License
335
+
336
+ MIT
@@ -5,6 +5,8 @@
5
5
  [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
6
  [![python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
7
7
 
8
+ [English](README.md) · **Español**
9
+
8
10
  Orquestador de entornos de desarrollo locales. Un archivo en la raíz del
9
11
  proyecto, un comando, y el stack entero arriba: puertos libres, Docker,
10
12
  backend y frontend, sin cuatro terminales abiertas.
@@ -123,7 +125,7 @@ backend, el backend a los contenedores.
123
125
  No sobreescribe uno existente.
124
126
 
125
127
  Dónde busca cada lenguaje y por qué reconoce eso y no otra cosa, en
126
- [`docs/deteccion.md`](docs/deteccion.md).
128
+ [`docs/es/deteccion.md`](docs/es/deteccion.md).
127
129
 
128
130
  ## stack.yaml
129
131
 
@@ -159,7 +161,7 @@ profiles:
159
161
 
160
162
  `command` es el único obligatorio. La referencia de todos los campos, los
161
163
  healthchecks de `ready` y los perfiles heredados de un compose están en
162
- [`docs/stack-yaml.md`](docs/stack-yaml.md).
164
+ [`docs/es/stack-yaml.md`](docs/es/stack-yaml.md).
163
165
 
164
166
  ## Interfaz web
165
167
 
@@ -178,7 +180,7 @@ Estado de cada servicio, arrancar y apagar stacks, liberar puertos tomados por
178
180
  procesos ajenos, y logs en vivo por proyecto.
179
181
 
180
182
  El detalle de cada control, y el modelo de seguridad del servidor local, en
181
- [`docs/interfaz.md`](docs/interfaz.md).
183
+ [`docs/es/interfaz.md`](docs/es/interfaz.md).
182
184
 
183
185
  ## Puertos
184
186
 
@@ -243,7 +245,7 @@ Estas reglas están en el código, no en la documentación:
243
245
  ## Otros comandos
244
246
 
245
247
  `down`, `switch`, `doctor` y `open`, con qué revisa cada uno y por qué, en
246
- [`docs/comandos.md`](docs/comandos.md).
248
+ [`docs/es/comandos.md`](docs/es/comandos.md).
247
249
 
248
250
  ## Modelo de confianza
249
251
 
@@ -0,0 +1,277 @@
1
+ # StackHelx
2
+
3
+ [![pypi](https://img.shields.io/pypi/v/stackhelx?logo=pypi&logoColor=white)](https://pypi.org/project/stackhelx/)
4
+ [![tests](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml/badge.svg?branch=main&cache=none)](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml)
5
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+ [![python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
7
+
8
+ **English** · [Español](README.es.md)
9
+
10
+ Local development environment orchestrator. One file at the project root, one
11
+ command, and your entire stack is up: free ports, Docker, backend, and frontend,
12
+ without juggling four open terminals.
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ uv tool install stackhelx
18
+ # or
19
+ pipx install stackhelx
20
+ ```
21
+
22
+ Installing registers two identical executables on your system: the full command
23
+ **`stackhelx`** and its short alias **`shx`**.
24
+
25
+ Requires Python 3.10 or later. Runs on Windows, macOS, and Linux.
26
+
27
+ ## Commands
28
+
29
+ Every command runs as `stackhelx <command>` or via its official short alias
30
+ **`shx <command>`** (e.g. `shx up`, `shx down`, `shx doctor`, `shx ports`):
31
+
32
+ | Command (`stackhelx` / `shx`) | What it does |
33
+ |---|---|
34
+ | `stackhelx up` | Boots the entire stack: frees ports, starts services in topological order, and tails logs |
35
+ | `stackhelx down` | Stops services that outlive the terminal, such as containers |
36
+ | `stackhelx serve` | Opens the web dashboard at `http://127.0.0.1:7666` |
37
+ | `stackhelx doctor` | Checks what could block startup without starting anything |
38
+ | `stackhelx ports` | Shows the status of declared ports |
39
+ | `stackhelx free 3000` | Terminates the process holding a port, asking first |
40
+ | `stackhelx free --all` | Frees all occupied ports across all registered projects |
41
+ | `stackhelx switch fitness` | Stops registered projects that collide on ports with the target, then boots it |
42
+ | `stackhelx open` | Opens the first service that answers HTTP in your browser |
43
+ | `stackhelx init` | Freezes auto-detected services into an editable `stack.yaml` |
44
+ | `stackhelx add .` | Registers the project so it appears in the web dashboard |
45
+ | `stackhelx list` | Lists registered projects (alias: `ls`) |
46
+ | `stackhelx remove .` | Unregisters a project (alias: `rm`) |
47
+ | `stackhelx run [task]` | Runs project scripts or sequential task pipelines |
48
+ | `stackhelx share [target]` | Exposes a local service to the internet over an ephemeral tunnel |
49
+ | `stackhelx clean` | Cleans Docker resources by category: stopped containers, untagged images, unused networks, and build cache. Volumes are separate via `--volumes`. Prompts before deleting |
50
+ | `stackhelx mcp` | Starts the Model Context Protocol (MCP) server over stdio for AI agents |
51
+ | `stackhelx test-stack` | Validates `stack.yaml` without starting anything: topological order, dependencies, and ports |
52
+ | `stackhelx history` | Shows recent stack runs with duration and final state |
53
+ | `stackhelx logs` | Reads logs from a project running in `serve` (`--follow` to stream) |
54
+ | `stackhelx stats` | Displays real-time CPU and memory usage for services running in `serve` (alias: `top`) |
55
+ | `stackhelx version` | Prints the installed version (also `--version`) |
56
+
57
+ `logs` and `stats` query a running `stackhelx serve` instance, so `serve` must
58
+ be active. `history` and `test-stack` read directly from disk.
59
+
60
+ Pass `--help` to any command for full flag details.
61
+
62
+ ## Starting a stack
63
+
64
+ ```bash
65
+ shx up
66
+ # or
67
+ stackhelx up
68
+
69
+ shx up --profile backend # start only a subset
70
+ shx up --no-free # leave occupied ports untouched
71
+ shx up --env-file .env.qa # load this .env file before booting
72
+ ```
73
+
74
+ `--env-file` adds to `env_file:` in `stack.yaml` rather than replacing it: it
75
+ loads the file into the process environment before resolving the stack, making
76
+ variables visible to all services. Use it for one-off runs against another
77
+ environment without editing `stack.yaml`. Unlike `env_file:`, it accepts paths
78
+ outside the project root because you type the path yourself at the terminal
79
+ instead of inheriting it from an untrusted repository.
80
+
81
+ Before starting, StackHelx checks every declared port and prompts before
82
+ terminating any stray process holding one. Ports already published by Docker are
83
+ skipped automatically because the container is already up.
84
+
85
+ ```
86
+ demo stack.yaml
87
+ db | $ docker compose up -d postgres
88
+ db | listo (5432)
89
+ api | $ npm run dev
90
+ api | escuchando en 8080
91
+ api | listo (8080)
92
+ web | $ npm run dev
93
+ web | listo (3000)
94
+ Todo listo. Ctrl-C para apagar.
95
+ api | GET /health 200
96
+ web | ready in 412 ms
97
+ ```
98
+
99
+ Pressing `Ctrl-C` shuts down services in reverse topological order, killing the
100
+ entire process tree of each service.
101
+
102
+ ## Without stack.yaml
103
+
104
+ `stack.yaml` is optional. When none is present, StackHelx inspects the project
105
+ root:
106
+
107
+ | Finds | Starts |
108
+ |---|---|
109
+ | `compose.yaml`, `compose.yml`, `docker-compose.yml`, `docker-compose.yaml` | One service per container: `docker compose up -d <name>` |
110
+ | `manage.py` | `python manage.py runserver` |
111
+ | `fastapi` or `uvicorn` declared, with a module defining `app` | `uvicorn <module>:app --reload` |
112
+ | `package.json` with a server script (`dev`, `start:dev`, `serve`, `start`) | `npm run dev`, switching to `pnpm`/`yarn`/`bun` based on lockfile or `packageManager` |
113
+
114
+ ```
115
+ mi-app A:\Proyectos\mi-app
116
+ Sin stack.yaml. Detectado:
117
+ docker docker compose up -d 5433
118
+ web pnpm run dev al arrancar
119
+ Para congelarlo en un archivo editable: stackhelx init
120
+ Arrancar? [Y/n]
121
+ ```
122
+
123
+ Services start in that order and chain dependencies automatically: frontend
124
+ waits for backend, and backend waits for containers.
125
+
126
+ `stackhelx init` writes the detected configuration to `stack.yaml` so you can
127
+ edit it by hand. It never overwrites an existing file.
128
+
129
+ Where StackHelx searches for each language and why it matches specific signals
130
+ is documented in [`docs/deteccion.md`](docs/deteccion.md).
131
+
132
+ ## stack.yaml
133
+
134
+ Place `stack.yaml` at the project root. StackHelx searches upward from your
135
+ current working directory, so you can run commands from any subdirectory.
136
+
137
+ ```yaml
138
+ name: my-project
139
+
140
+ services:
141
+ db:
142
+ command: docker compose up -d postgres
143
+ port: 5432
144
+ detached: true # command exits while the container stays alive
145
+
146
+ api:
147
+ command: npm run dev
148
+ cwd: backend
149
+ port: 8080
150
+ needs: [db]
151
+ env:
152
+ DATABASE_URL: postgres://localhost:5432/app
153
+
154
+ web:
155
+ command: npm run dev
156
+ cwd: frontend
157
+ port: 3000
158
+ needs: [api]
159
+
160
+ profiles:
161
+ backend: [api] # pulls in db automatically via its dependency chain
162
+ ```
163
+
164
+ `command` is the only required field. The complete field reference, `ready`
165
+ healthcheck modes, and inherited Compose profiles live in
166
+ [`docs/stack-yaml.md`](docs/stack-yaml.md).
167
+
168
+ ## Web dashboard
169
+
170
+ When you work across multiple projects, the CLI only sees the current directory.
171
+ The web dashboard shows all registered projects at once.
172
+
173
+ ```bash
174
+ stackhelx serve # opens http://127.0.0.1:7666
175
+ ```
176
+
177
+ Included out of the box with no extra dependencies. Register projects directly
178
+ from the browser via `Explorar…` or from the terminal with `stackhelx add .`.
179
+
180
+ Monitor service states, start and stop stacks, free ports held by stray
181
+ processes, inspect system-wide listening ports, and stream live logs per project.
182
+
183
+ Control details and the local server security model are covered in
184
+ [`docs/interfaz.md`](docs/interfaz.md).
185
+
186
+ ## Ports
187
+
188
+ Inspect port status without starting anything:
189
+
190
+ ```bash
191
+ stackhelx ports # ports declared in stack.yaml
192
+ stackhelx ports 3000 8080 # specific ports
193
+ ```
194
+
195
+ ```
196
+ PUERTO ESTADO PID PROCESO COMANDO
197
+ 3000 ocupado 24188 node.exe node C:\proj\frontend\node_modules\.bin\vite
198
+ 8080 libre - - -
199
+ 5432 ocupado 9012 com.docker.backend.exe
200
+ ```
201
+
202
+ Free a port held by a zombie process:
203
+
204
+ ```bash
205
+ stackhelx free 3000
206
+ ```
207
+
208
+ Shows the owning process and asks for confirmation before terminating it. If you
209
+ decline, it suggests the next available port.
210
+
211
+ Flags: `--yes` skips confirmation (for scripts), `--force` escalates to `kill()`
212
+ when the process ignores graceful termination.
213
+
214
+ After a crash or branch switch, multiple ports may stay occupied:
215
+
216
+ ```bash
217
+ stackhelx free --all
218
+ ```
219
+
220
+ Scans every port declared across all registered projects, lists what is occupied,
221
+ and asks for a single confirmation. Exits with code 1 if any port could not be
222
+ freed.
223
+
224
+ The CLI does not track which processes you started in other terminals: if another
225
+ stack is running in a separate shell, its services appear in that list too. That
226
+ is why the CLI prints the full list before touching anything and defaults the
227
+ prompt to "no". The web dashboard tracks its own active sessions and excludes
228
+ them automatically when clicking "Liberar todos".
229
+
230
+ ## What the kill switch refuses to do
231
+
232
+ These guardrails are enforced in code:
233
+
234
+ - Never terminates PID 0, PID 4, StackHelx itself, or any of its parent
235
+ processes. Killing your own terminal is not a feature.
236
+ - Revalidates process creation time (`create_time`) between scanning and
237
+ signaling. OS PIDs recycle quickly; without this check, you risk killing an
238
+ unrelated process.
239
+ - Sends `terminate()` and waits 5 seconds. Escalates to `kill()` only with
240
+ explicit `--force`, because force-killing an `npm run dev` wrapper leaves
241
+ orphaned child processes behind.
242
+ - Fails fast when permissions are insufficient instead of attempting privilege
243
+ escalation.
244
+ - Never kills the Docker or WSL proxy process. A port published by a container
245
+ is bound by a shared host proxy process; killing it takes down the entire
246
+ Docker engine. Instead, StackHelx tells you which container to stop.
247
+
248
+ ## Other commands
249
+
250
+ `down`, `switch`, `doctor`, `open`, `run`, `share`, `clean`, and `mcp` are
251
+ detailed in [`docs/comandos.md`](docs/comandos.md).
252
+
253
+ ## Trust model
254
+
255
+ `stack.yaml` runs arbitrary commands, just like `package.json` or a `Makefile`.
256
+ StackHelx does not sandbox them. Treat a `stack.yaml` from an untrusted
257
+ repository with the same caution you give its build scripts.
258
+
259
+ Without `stack.yaml`, commands come from auto-detection, and `scripts.dev` in an
260
+ untrusted `package.json` is equally arbitrary. That is why `up` prints the exact
261
+ commands it detected and asks for confirmation before executing anything, while
262
+ `-y` lets you skip the prompt once you trust the project.
263
+
264
+ ## Development
265
+
266
+ ```bash
267
+ python -m venv .venv
268
+ .venv/bin/pip install -e ".[dev]" # .venv\Scripts\pip on Windows
269
+ pytest -q -n auto
270
+ ```
271
+
272
+ Tests run against real OS sockets and processes with zero mocks. That is the
273
+ only way to verify software whose job is talking to the operating system.
274
+
275
+ ## License
276
+
277
+ MIT