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.
- {stackhelx-1.1.1 → stackhelx-1.1.2}/.gitignore +1 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/CHANGELOG.md +7 -0
- stackhelx-1.1.2/PKG-INFO +336 -0
- stackhelx-1.1.1/README.md → stackhelx-1.1.2/README.es.md +6 -4
- stackhelx-1.1.2/README.md +277 -0
- stackhelx-1.1.2/docs/comandos.md +277 -0
- stackhelx-1.1.2/docs/deteccion.md +102 -0
- {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/comandos.md +3 -1
- {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/deteccion.md +3 -1
- {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/interfaz.md +3 -1
- {stackhelx-1.1.1/docs → stackhelx-1.1.2/docs/es}/stack-yaml.md +4 -2
- stackhelx-1.1.2/docs/interfaz.md +81 -0
- stackhelx-1.1.2/docs/stack-yaml.md +195 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/pyproject.toml +1 -1
- stackhelx-1.1.2/stack.example.yaml +78 -0
- stackhelx-1.1.2/stackhelx/__init__.py +2 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/ports.py +41 -2
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/server.py +28 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/app.css +28 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/app.js +80 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/index.html +6 -2
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_ports.py +24 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_server.py +12 -0
- stackhelx-1.1.1/PKG-INFO +0 -330
- stackhelx-1.1.1/docs/pendientes.md +0 -117
- stackhelx-1.1.1/docs/plan-expansion.md +0 -97
- stackhelx-1.1.1/docs/plan-lenguajes.md +0 -388
- stackhelx-1.1.1/docs/plan-siguiente.md +0 -323
- stackhelx-1.1.1/docs/superpowers/plans/2026-08-08-partir-readme.md +0 -377
- stackhelx-1.1.1/docs/superpowers/plans/2026-08-08-release-1-0-1.md +0 -378
- stackhelx-1.1.1/docs/superpowers/plans/2026-08-18-campo-url.md +0 -222
- stackhelx-1.1.1/docs/superpowers/specs/2026-07-29-autodeteccion-design.md +0 -70
- stackhelx-1.1.1/stack.example.yaml +0 -76
- stackhelx-1.1.1/stackhelx/__init__.py +0 -2
- {stackhelx-1.1.1 → stackhelx-1.1.2}/.github/workflows/ci.yml +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/.github/workflows/release.yml +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/AGENTS.md +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/CLAUDE.md +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/LICENSE +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/scripts/check_docs.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/scripts/check_metadata.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/__main__.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/browse.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/cli.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/config.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/detect.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/docker.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/doctor.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/guardrails.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/history.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/mcp.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/registry.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/runner.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/scripts.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/tunnel.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/stackhelx/web/tokens.css +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/conftest.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_browse.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_cli.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_config.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_conftest.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_detect.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_guardrails.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_history.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_mcp.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_registry.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_runner.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_scripts.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/tests/test_tunnel.py +0 -0
- {stackhelx-1.1.1 → stackhelx-1.1.2}/uv.lock +0 -0
|
@@ -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
|
stackhelx-1.1.2/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/stackhelx/)
|
|
63
|
+
[](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml)
|
|
64
|
+
[](LICENSE)
|
|
65
|
+
[](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)
|
|
6
6
|
[](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
|
+
[](https://pypi.org/project/stackhelx/)
|
|
4
|
+
[](https://github.com/TicoraX/StackHelx/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](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
|