stackhelx 1.1.1__tar.gz → 1.1.3__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 (71) hide show
  1. {stackhelx-1.1.1 → stackhelx-1.1.3}/.gitignore +1 -0
  2. {stackhelx-1.1.1 → stackhelx-1.1.3}/CHANGELOG.md +15 -0
  3. stackhelx-1.1.3/PKG-INFO +338 -0
  4. stackhelx-1.1.1/README.md → stackhelx-1.1.3/README.es.md +9 -6
  5. stackhelx-1.1.3/README.md +279 -0
  6. stackhelx-1.1.3/docs/comandos.md +277 -0
  7. stackhelx-1.1.3/docs/deteccion.md +102 -0
  8. {stackhelx-1.1.1/docs → stackhelx-1.1.3/docs/es}/comandos.md +3 -1
  9. {stackhelx-1.1.1/docs → stackhelx-1.1.3/docs/es}/deteccion.md +3 -1
  10. {stackhelx-1.1.1/docs → stackhelx-1.1.3/docs/es}/interfaz.md +10 -1
  11. {stackhelx-1.1.1/docs → stackhelx-1.1.3/docs/es}/stack-yaml.md +4 -2
  12. stackhelx-1.1.3/docs/interfaz.md +88 -0
  13. stackhelx-1.1.3/docs/stack-yaml.md +195 -0
  14. {stackhelx-1.1.1 → stackhelx-1.1.3}/pyproject.toml +1 -1
  15. stackhelx-1.1.3/stack.example.yaml +78 -0
  16. stackhelx-1.1.3/stackhelx/__init__.py +2 -0
  17. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/cli.py +228 -290
  18. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/ports.py +41 -2
  19. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/server.py +28 -0
  20. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/web/app.css +63 -0
  21. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/web/app.js +619 -339
  22. stackhelx-1.1.3/stackhelx/web/index.html +542 -0
  23. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/conftest.py +10 -1
  24. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_cli.py +19 -19
  25. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_ports.py +24 -0
  26. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_server.py +32 -0
  27. stackhelx-1.1.1/PKG-INFO +0 -330
  28. stackhelx-1.1.1/docs/pendientes.md +0 -117
  29. stackhelx-1.1.1/docs/plan-expansion.md +0 -97
  30. stackhelx-1.1.1/docs/plan-lenguajes.md +0 -388
  31. stackhelx-1.1.1/docs/plan-siguiente.md +0 -323
  32. stackhelx-1.1.1/docs/superpowers/plans/2026-08-08-partir-readme.md +0 -377
  33. stackhelx-1.1.1/docs/superpowers/plans/2026-08-08-release-1-0-1.md +0 -378
  34. stackhelx-1.1.1/docs/superpowers/plans/2026-08-18-campo-url.md +0 -222
  35. stackhelx-1.1.1/docs/superpowers/specs/2026-07-29-autodeteccion-design.md +0 -70
  36. stackhelx-1.1.1/stack.example.yaml +0 -76
  37. stackhelx-1.1.1/stackhelx/__init__.py +0 -2
  38. stackhelx-1.1.1/stackhelx/web/index.html +0 -411
  39. {stackhelx-1.1.1 → stackhelx-1.1.3}/.github/workflows/ci.yml +0 -0
  40. {stackhelx-1.1.1 → stackhelx-1.1.3}/.github/workflows/release.yml +0 -0
  41. {stackhelx-1.1.1 → stackhelx-1.1.3}/AGENTS.md +0 -0
  42. {stackhelx-1.1.1 → stackhelx-1.1.3}/CLAUDE.md +0 -0
  43. {stackhelx-1.1.1 → stackhelx-1.1.3}/LICENSE +0 -0
  44. {stackhelx-1.1.1 → stackhelx-1.1.3}/scripts/check_docs.py +0 -0
  45. {stackhelx-1.1.1 → stackhelx-1.1.3}/scripts/check_metadata.py +0 -0
  46. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/__main__.py +0 -0
  47. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/browse.py +0 -0
  48. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/config.py +0 -0
  49. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/detect.py +0 -0
  50. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/docker.py +0 -0
  51. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/doctor.py +0 -0
  52. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/guardrails.py +0 -0
  53. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/history.py +0 -0
  54. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/mcp.py +0 -0
  55. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/registry.py +0 -0
  56. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/runner.py +0 -0
  57. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/scripts.py +0 -0
  58. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/tunnel.py +0 -0
  59. {stackhelx-1.1.1 → stackhelx-1.1.3}/stackhelx/web/tokens.css +0 -0
  60. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_browse.py +0 -0
  61. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_config.py +0 -0
  62. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_conftest.py +0 -0
  63. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_detect.py +0 -0
  64. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_guardrails.py +0 -0
  65. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_history.py +0 -0
  66. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_mcp.py +0 -0
  67. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_registry.py +0 -0
  68. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_runner.py +0 -0
  69. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_scripts.py +0 -0
  70. {stackhelx-1.1.1 → stackhelx-1.1.3}/tests/test_tunnel.py +0 -0
  71. {stackhelx-1.1.1 → stackhelx-1.1.3}/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,21 @@ 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.3] - 2026-10-09
8
+
9
+ ### Añadido y Mejorado
10
+
11
+ - **Selector de idioma en vivo (EN / ES) en la interfaz Web (`index.html`, `app.css`, `app.js`):** Botón selector accesible en el encabezado (`#btn-lang`) que conmuta toda la interfaz web en tiempo real sin recargar la página. Arranca en inglés por defecto y persiste la preferencia en `localStorage` (`stackhelx.lang`).
12
+ - **CLI internacionalizado a Inglés (`cli.py`):** Todos los comandos, ayudas (`shx --help`, `stackhelx <cmd> --help`), encabezados de tablas, confirmaciones y mensajes del CLI pasan a inglés.
13
+ - **Documentación y pruebas actualizadas (`README.md`, `README.es.md`, `docs/`, `tests/`):** Ejemplos de consola y referencias de interfaz actualizadas, aserciones del CLI en inglés y nueva prueba para el selector de idioma web (482/482 pruebas pasando al 100%).
14
+
15
+ ## [1.1.2] - 2026-10-06
16
+
17
+ ### Añadido y Mejorado
18
+
19
+ - **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.
20
+ - **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.
21
+
7
22
  ## [1.1.1] - 2026-09-24
8
23
 
9
24
  ### Corregido y Mejorado
@@ -0,0 +1,338 @@
1
+ Metadata-Version: 2.5
2
+ Name: stackhelx
3
+ Version: 1.1.3
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
+ my-app A:\Proyectos\my-app
175
+ No stack.yaml. Detected:
176
+ docker docker compose up -d 5433
177
+ web pnpm run dev on start
178
+ To freeze into an editable file: stackhelx init
179
+ Start? [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 `Browse…` or from the terminal with `stackhelx add .`. Use
238
+ the `EN / ES` toggle in the header to switch the interface between English and
239
+ Spanish at any time.
240
+
241
+ Monitor service states, start and stop stacks, free ports held by stray
242
+ processes, inspect system-wide listening ports, and stream live logs per project.
243
+
244
+ Control details and the local server security model are covered in
245
+ [`docs/interfaz.md`](docs/interfaz.md).
246
+
247
+ ## Ports
248
+
249
+ Inspect port status without starting anything:
250
+
251
+ ```bash
252
+ stackhelx ports # ports declared in stack.yaml
253
+ stackhelx ports 3000 8080 # specific ports
254
+ ```
255
+
256
+ ```
257
+ PORT STATUS PID PROCESS COMMAND
258
+ 3000 occupied 24188 node.exe node C:\proj\frontend\node_modules\.bin\vite
259
+ 8080 free - - -
260
+ 5432 occupied 9012 com.docker.backend.exe
261
+ ```
262
+
263
+ Free a port held by a zombie process:
264
+
265
+ ```bash
266
+ stackhelx free 3000
267
+ ```
268
+
269
+ Shows the owning process and asks for confirmation before terminating it. If you
270
+ decline, it suggests the next available port.
271
+
272
+ Flags: `--yes` skips confirmation (for scripts), `--force` escalates to `kill()`
273
+ when the process ignores graceful termination.
274
+
275
+ After a crash or branch switch, multiple ports may stay occupied:
276
+
277
+ ```bash
278
+ stackhelx free --all
279
+ ```
280
+
281
+ Scans every port declared across all registered projects, lists what is occupied,
282
+ and asks for a single confirmation. Exits with code 1 if any port could not be
283
+ freed.
284
+
285
+ The CLI does not track which processes you started in other terminals: if another
286
+ stack is running in a separate shell, its services appear in that list too. That
287
+ is why the CLI prints the full list before touching anything and defaults the
288
+ prompt to "no". The web dashboard tracks its own active sessions and excludes
289
+ them automatically when clicking "Free all".
290
+
291
+ ## What the kill switch refuses to do
292
+
293
+ These guardrails are enforced in code:
294
+
295
+ - Never terminates PID 0, PID 4, StackHelx itself, or any of its parent
296
+ processes. Killing your own terminal is not a feature.
297
+ - Revalidates process creation time (`create_time`) between scanning and
298
+ signaling. OS PIDs recycle quickly; without this check, you risk killing an
299
+ unrelated process.
300
+ - Sends `terminate()` and waits 5 seconds. Escalates to `kill()` only with
301
+ explicit `--force`, because force-killing an `npm run dev` wrapper leaves
302
+ orphaned child processes behind.
303
+ - Fails fast when permissions are insufficient instead of attempting privilege
304
+ escalation.
305
+ - Never kills the Docker or WSL proxy process. A port published by a container
306
+ is bound by a shared host proxy process; killing it takes down the entire
307
+ Docker engine. Instead, StackHelx tells you which container to stop.
308
+
309
+ ## Other commands
310
+
311
+ `down`, `switch`, `doctor`, `open`, `run`, `share`, `clean`, and `mcp` are
312
+ detailed in [`docs/comandos.md`](docs/comandos.md).
313
+
314
+ ## Trust model
315
+
316
+ `stack.yaml` runs arbitrary commands, just like `package.json` or a `Makefile`.
317
+ StackHelx does not sandbox them. Treat a `stack.yaml` from an untrusted
318
+ repository with the same caution you give its build scripts.
319
+
320
+ Without `stack.yaml`, commands come from auto-detection, and `scripts.dev` in an
321
+ untrusted `package.json` is equally arbitrary. That is why `up` prints the exact
322
+ commands it detected and asks for confirmation before executing anything, while
323
+ `-y` lets you skip the prompt once you trust the project.
324
+
325
+ ## Development
326
+
327
+ ```bash
328
+ python -m venv .venv
329
+ .venv/bin/pip install -e ".[dev]" # .venv\Scripts\pip on Windows
330
+ pytest -q -n auto
331
+ ```
332
+
333
+ Tests run against real OS sockets and processes with zero mocks. That is the
334
+ only way to verify software whose job is talking to the operating system.
335
+
336
+ ## License
337
+
338
+ 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
 
@@ -171,14 +173,15 @@ stackhelx serve # abre http://127.0.0.1:7666
171
173
  ```
172
174
 
173
175
  Viene con la instalación, no hace falta nada más. Registrar proyectos se puede
174
- desde la propia interfaz con `Explorar…`, o desde la terminal con
175
- `stackhelx add .`.
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
178
+ en vivo con el selector `EN / ES`.
176
179
 
177
180
  Estado de cada servicio, arrancar y apagar stacks, liberar puertos tomados por
178
181
  procesos ajenos, y logs en vivo por proyecto.
179
182
 
180
183
  El detalle de cada control, y el modelo de seguridad del servidor local, en
181
- [`docs/interfaz.md`](docs/interfaz.md).
184
+ [`docs/es/interfaz.md`](docs/es/interfaz.md).
182
185
 
183
186
  ## Puertos
184
187
 
@@ -243,7 +246,7 @@ Estas reglas están en el código, no en la documentación:
243
246
  ## Otros comandos
244
247
 
245
248
  `down`, `switch`, `doctor` y `open`, con qué revisa cada uno y por qué, en
246
- [`docs/comandos.md`](docs/comandos.md).
249
+ [`docs/es/comandos.md`](docs/es/comandos.md).
247
250
 
248
251
  ## Modelo de confianza
249
252