@jondotsoy/envs 0.0.3 → 0.0.4
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.
- package/README.md +86 -0
- package/SECURITY.md +46 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# @jondotsoy/envs
|
|
2
|
+
|
|
3
|
+
CLI para mantener en un solo archivo (`.envs/values.yml`) los valores del `.env` de cada worktree de git. Edita todos los valores juntos y distribúyelos a cada worktree, o recógelos desde los `.env` existentes.
|
|
4
|
+
|
|
5
|
+
Requiere [Bun](https://bun.com) y git.
|
|
6
|
+
|
|
7
|
+
## Instalación
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
bun add -g @jondotsoy/envs
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
O sin instalar:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
bunx @jondotsoy/envs help
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Uso
|
|
20
|
+
|
|
21
|
+
Ejecuta los comandos dentro del repo o de cualquiera de sus worktrees. Dentro de un worktree, `.envs/` siempre vive en el repo principal.
|
|
22
|
+
|
|
23
|
+
| Comando | Qué hace |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `envs init` | Crea `.envs/`, `.envs/.gitignore` (con `*`) y un `.envs/values.yml` vacío. No sobrescribe archivos existentes. |
|
|
26
|
+
| `envs pull` | Lee el `.env` del repo principal y de cada worktree y lo escribe en `values.yml`. Las variables que ya no están en un `.env` se quitan de `values.yml` para ese worktree. |
|
|
27
|
+
| `envs push` | Escribe `values.yml` en el `.env` de cada worktree. Actualiza las variables existentes en su línea, agrega las nuevas al final y conserva comentarios y variables que no están en `values.yml`. |
|
|
28
|
+
| `envs edit` | Ejecuta `pull`, abre `values.yml` con `code -w` y, al cerrar el editor, ejecuta `push`. Si el editor falla, no hace `push`. |
|
|
29
|
+
| `envs help` | Muestra la ayuda. |
|
|
30
|
+
|
|
31
|
+
Los worktrees se identifican por el nombre de su rama (o el nombre de su carpeta si están en HEAD desacoplado). El repo principal usa el nombre de su rama, por ejemplo `main`.
|
|
32
|
+
|
|
33
|
+
## Formato de `values.yml`
|
|
34
|
+
|
|
35
|
+
```yaml
|
|
36
|
+
defaults:
|
|
37
|
+
LOG_LEVEL: info
|
|
38
|
+
|
|
39
|
+
envs:
|
|
40
|
+
DATABASE_URL:
|
|
41
|
+
main: postgres://localhost/main
|
|
42
|
+
feature-x: postgres://localhost/feature_x
|
|
43
|
+
PORT:
|
|
44
|
+
main: "3000"
|
|
45
|
+
feature-x: "3001"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- `defaults`: valor por defecto de cada variable. `push` lo escribe en el `.env` de todos los worktrees.
|
|
49
|
+
- `envs.<VARIABLE>.<worktree>`: valor de la variable en ese worktree. Sobrescribe al valor de `defaults`.
|
|
50
|
+
- Todos los valores son strings, así que los números van entre comillas (`"3000"`).
|
|
51
|
+
|
|
52
|
+
El schema (JSON Schema) está en [`schema/values.schema.json`](schema/values.schema.json). Para que VS Code valide el archivo con la extensión YAML, agrega al inicio de `values.yml`:
|
|
53
|
+
|
|
54
|
+
```yaml
|
|
55
|
+
# yaml-language-server: $schema=../schema/values.schema.json
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Desarrollo
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
bun install
|
|
62
|
+
bun test # ejecuta los tests
|
|
63
|
+
bun test --coverage # con cobertura
|
|
64
|
+
bun run build # genera dist/ (envs.js y package.json)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- `src/envs.ts`: lógica de los comandos. `src/bin/envs.ts`: punto de entrada del CLI.
|
|
68
|
+
- `test/fixtures/workspace.ts`: fixture `createWorkspace({ main, worktrees, files })`, que crea un repo git temporal con worktrees, cada uno en su propia carpeta temporal.
|
|
69
|
+
|
|
70
|
+
## Publicación
|
|
71
|
+
|
|
72
|
+
El workflow **Publish** (Actions → Publish → Run workflow) sube la versión, hace el build y publica `dist/` en npm por OIDC (trusted publishing). Inputs:
|
|
73
|
+
|
|
74
|
+
- `bump`: `major`, `minor`, `patch` o `prerelease`.
|
|
75
|
+
- `tag`: dist-tag de npm (`latest`, `default`, `alpha` o `demo`). Con un tag distinto de `latest` la versión es una prerelease (`0.0.2-alpha.0`).
|
|
76
|
+
- `provenance`: publica con provenance. npm solo lo acepta si el repositorio es público.
|
|
77
|
+
|
|
78
|
+
Luego del publish crea el commit y el tag de la versión, y un release en GitHub con el enlace a la versión en npm.
|
|
79
|
+
|
|
80
|
+
## Seguridad
|
|
81
|
+
|
|
82
|
+
Para reportar una vulnerabilidad, mira [SECURITY.md](SECURITY.md).
|
|
83
|
+
|
|
84
|
+
## Licencia
|
|
85
|
+
|
|
86
|
+
[MIT](LICENSE)
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Política de seguridad
|
|
2
|
+
|
|
3
|
+
## Versiones soportadas
|
|
4
|
+
|
|
5
|
+
Solo se mantiene la última versión publicada en npm de `@jondotsoy/envs`. Las correcciones de seguridad se publican en una versión nueva.
|
|
6
|
+
|
|
7
|
+
## Reportar una vulnerabilidad
|
|
8
|
+
|
|
9
|
+
No abras un issue público para reportar una vulnerabilidad. Repórtala de forma privada por uno de estos medios:
|
|
10
|
+
|
|
11
|
+
- Con el reporte privado de vulnerabilidades de GitHub: pestaña **Security** del repositorio, **Report a vulnerability**.
|
|
12
|
+
- Por correo a [hi@jon.soy](mailto:hi@jon.soy).
|
|
13
|
+
|
|
14
|
+
Incluye, si puedes:
|
|
15
|
+
|
|
16
|
+
- la versión de `@jondotsoy/envs` y de Bun que usas;
|
|
17
|
+
- una descripción del problema y su impacto;
|
|
18
|
+
- los pasos para reproducirlo.
|
|
19
|
+
|
|
20
|
+
Te responderé lo antes posible y coordinaremos la corrección y la divulgación del problema.
|
|
21
|
+
|
|
22
|
+
## Archivos que modifica
|
|
23
|
+
|
|
24
|
+
`envs` solo lee y escribe los archivos de esta tabla. `<raíz>` es el repo principal (dentro de un worktree, el repo padre) y `<worktree>` es la carpeta de cada worktree que lista `git worktree list`, incluido el repo principal, aunque esté fuera de `<raíz>`.
|
|
25
|
+
|
|
26
|
+
| Comando | Lee | Escribe |
|
|
27
|
+
| --- | --- | --- |
|
|
28
|
+
| `envs init` | — | Crea `<raíz>/.envs/`, `<raíz>/.envs/.gitignore` y `<raíz>/.envs/values.yml`, solo si no existen. Nunca sobrescribe. |
|
|
29
|
+
| `envs pull` | `<worktree>/.env` de cada worktree | Reescribe `<raíz>/.envs/values.yml`. El archivo se serializa de nuevo, así que se pierden los comentarios del YAML. |
|
|
30
|
+
| `envs push` | `<raíz>/.envs/values.yml` | Crea o actualiza `<worktree>/.env` de cada worktree que tenga valores. Actualiza las variables existentes en su línea, agrega las nuevas al final y conserva el resto del archivo. Si hay `defaults`, esto incluye a todos los worktrees. |
|
|
31
|
+
| `envs edit` | Lo mismo que `pull` y `push` | Lo mismo que `pull` y `push`. Además ejecuta `code -w <raíz>/.envs/values.yml`. |
|
|
32
|
+
|
|
33
|
+
Además:
|
|
34
|
+
|
|
35
|
+
- Ejecuta `git rev-parse` y `git worktree list` para ubicar la raíz y los worktrees. Son comandos de solo lectura.
|
|
36
|
+
- `envs edit` ejecuta el programa `code` que encuentre en el `PATH`.
|
|
37
|
+
- No hace conexiones de red ni modifica otros archivos del proyecto, ni siquiera el `.gitignore` de tu proyecto.
|
|
38
|
+
|
|
39
|
+
## Manejo de secretos
|
|
40
|
+
|
|
41
|
+
`envs` trabaja con valores que suelen ser secretos:
|
|
42
|
+
|
|
43
|
+
- `.envs/values.yml` guarda los valores de todos los worktrees en texto plano.
|
|
44
|
+
- `envs init` crea `.envs/.gitignore` con `*`, para que la carpeta `.envs/` no se suba a git. No quites ese archivo.
|
|
45
|
+
- `envs push` escribe los valores en los archivos `.env` de cada worktree. Asegúrate de que `.env` esté en el `.gitignore` de tu proyecto.
|
|
46
|
+
- No compartas `values.yml` ni lo pegues en issues o logs.
|