@jondotsoy/envs 0.1.1 → 0.1.3

package/README.md

@@ -1,53 +1,55 @@
 # @jondotsoy/envs
 
-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.
+CLI that keeps the `.env` values of every git worktree in a single file (`.envs/values.yml`). Edit all values together and distribute them to each worktree, or collect them from the existing `.env` files.
 
-Requiere [Bun](https://bun.com) y git.
+Requires [Bun](https://bun.com) and git.
 
-## Instalación
+![Each worktree keeps its own .env; envs edit and envs push sync the shared values across them](docs/assets/images/worktrees-sync.svg)
+
+## Installation
 
 ```bash
 bun add -g @jondotsoy/envs
 ```
 
-O sin instalar:
+Or without installing:
 
 ```bash
 bunx @jondotsoy/envs help
 ```
 
-## Uso
+## Usage
 
-Ejecuta los comandos dentro del repo o de cualquiera de sus worktrees. Dentro de un worktree, `.envs/` siempre vive en el repo principal.
+Run the commands inside the repo or any of its worktrees. Inside a worktree, `.envs/` always lives in the main repo.
 
-| Comando | Qué hace |
+| Command | What it does |
 | --- | --- |
-| `envs init` | Crea `.envs/`, `.envs/.gitignore` (con `*`) y un `.envs/values.yml` vacío. No sobrescribe archivos existentes. |
-| `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. |
-| `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`. |
-| `envs lint` | Revisa la seguridad y muestra un warning por cada problema. Termina con código 1 si hay alguno (útil en CI). Ver abajo. |
-| `envs edit` | Ejecuta `pull`, abre `values.yml` con `code -w` y, al cerrar el editor, ejecuta `push`. Si el editor falla, no hace `push`. |
-| `envs help` | Muestra la ayuda. |
+| `envs init` | Creates `.envs/`, `.envs/.gitignore` (containing `*`) and an empty `.envs/values.yml`. Does not overwrite existing files. |
+| `envs pull` | Reads the `.env` of the main repo and of each worktree and writes it to `values.yml`. Variables that are no longer in a `.env` are removed from `values.yml` for that worktree. |
+| `envs push` | Writes `values.yml` to the `.env` of each worktree. Updates existing variables in place, appends new ones at the end, and keeps comments and variables that are not in `values.yml`. |
+| `envs lint` | Checks security and prints a warning for each problem. Exits with code 1 if there is any (useful in CI). See below. |
+| `envs edit` | Runs `pull`, opens `values.yml` with `code -w` and, when the editor closes, runs `push`. If the editor fails, it does not `push`. |
+| `envs help` | Shows the help. |
 
-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`.
+Worktrees are identified by their branch name (or their folder name if they are in detached HEAD). The main repo uses its branch name, for example `main`.
 
 ### `envs lint`
 
-Nunca imprime los valores, solo la variable y su ubicación (`envs.DB_PASSWORD.main`).
+It never prints values, only the variable and its location (`envs.DB_PASSWORD.main`).
 
-| Regla | Detecta |
+| Rule | Detects |
 | --- | --- |
-| `tracked-values`, `unignored-values` | `values.yml` está versionado en git o no está ignorado. |
-| `tracked-dotenv`, `unignored-dotenv` | El `.env` de un worktree está versionado o no está ignorado. |
-| `open-permissions` | `values.yml` es legible por otros usuarios (usa `chmod 600`). |
-| `executable-files` | `values.yml` o un `.env` tiene permiso de ejecución (usa `chmod -x`). |
-| `writable-files` | `values.yml` o un `.env` es escribible por el grupo u otros usuarios (usa `chmod go-w`). |
-| `weak-secret` | Variable sensible (`PASSWORD`, `TOKEN`, `SECRET`, `API_KEY`…) vacía o con un valor típico (`changeme`, `admin`…). |
-| `shared-secret` | Variable sensible en `defaults`, que se escribe en todos los worktrees. |
-| `secret-pattern` | Valor con formato de secreto conocido (AWS, GitHub, Slack, `sk-…`, clave privada). |
-| `url-credentials`, `insecure-url` | URL remota con contraseña embebida, o con `http://`, `ws://` o `ftp://`. |
-
-## Formato de `values.yml`
+| `tracked-values`, `unignored-values` | `values.yml` is tracked by git or is not ignored. |
+| `tracked-dotenv`, `unignored-dotenv` | A worktree's `.env` is tracked or is not ignored. |
+| `open-permissions` | `values.yml` is readable by other users (use `chmod 600`). |
+| `executable-files` | `values.yml` or a `.env` has the execute permission (use `chmod -x`). |
+| `writable-files` | `values.yml` or a `.env` is writable by the group or other users (use `chmod go-w`). |
+| `weak-secret` | Sensitive variable (`PASSWORD`, `TOKEN`, `SECRET`, `API_KEY`…) that is empty or has a typical value (`changeme`, `admin`…). |
+| `shared-secret` | Sensitive variable in `defaults`, which is written to all worktrees. |
+| `secret-pattern` | Value with a known secret format (AWS, GitHub, Slack, `sk-…`, private key). |
+| `url-credentials`, `insecure-url` | Remote URL with an embedded password, or using `http://`, `ws://` or `ftp://`. |
+
+## `values.yml` format
 
 ```yaml
 defaults:
@@ -62,42 +64,42 @@ envs:
     feature-x: "3001"
 ```
 
-- `defaults`: valor por defecto de cada variable. `push` lo escribe en el `.env` de todos los worktrees.
-- `envs.<VARIABLE>.<worktree>`: valor de la variable en ese worktree. Sobrescribe al valor de `defaults`.
-- Los valores pueden ser strings, números o booleanos (`PORT: 3000`, `DEBUG: true`); `push` los escribe en el `.env` como texto (`PORT=3000`, `DEBUG=true`). `pull` convierte `true`/`false` y los números canónicos (`3000`, `0.5`) a booleanos y números; el resto (`007`, `1e3`) queda como string.
+- `defaults`: default value of each variable. `push` writes it to the `.env` of all worktrees.
+- `envs.<VARIABLE>.<worktree>`: value of the variable in that worktree. It overrides the value from `defaults`.
+- Values can be strings, numbers or booleans (`PORT: 3000`, `DEBUG: true`); `push` writes them to the `.env` as text (`PORT=3000`, `DEBUG=true`). `pull` converts `true`/`false` and canonical numbers (`3000`, `0.5`) to booleans and numbers; anything else (`007`, `1e3`) stays a string.
 
-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`:
+The schema (JSON Schema) is at [`schema/values.schema.json`](schema/values.schema.json). To have VS Code validate the file with the YAML extension, add this at the top of `values.yml`:
 
 ```yaml
 # yaml-language-server: $schema=../schema/values.schema.json
 ```
 
-## Desarrollo
+## Development
 
 ```bash
 bun install
-bun test              # ejecuta los tests
-bun test --coverage   # con cobertura
-bun run build         # genera dist/ (envs.js y package.json)
+bun test              # run the tests
+bun test --coverage   # with coverage
+bun run build         # generates dist/ (envs.js and package.json)
 ```
 
-- `src/envs.ts`: lógica de los comandos. `src/bin/envs.ts`: punto de entrada del CLI.
-- `test/fixtures/workspace.ts`: fixture `createWorkspace({ main, worktrees, files })`, que crea un repo git temporal con worktrees, cada uno en su propia carpeta temporal.
+- `src/envs.ts`: command logic. `src/bin/envs.ts`: CLI entry point.
+- `test/fixtures/workspace.ts`: `createWorkspace({ main, worktrees, files })` fixture, which creates a temporary git repo with worktrees, each in its own temporary folder.
 
-## Publicación
+## Publishing
 
-El workflow **Publish** (Actions → Publish → Run workflow) sube la versión, hace el build y publica `dist/` en npm por OIDC (trusted publishing). Inputs:
+The **Publish** workflow (Actions → Publish → Run workflow) bumps the version, builds and publishes `dist/` to npm via OIDC (trusted publishing). Inputs:
 
-- `bump`: `major`, `minor`, `patch` o `prerelease`.
-- `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`).
-- `provenance`: publica con provenance. npm solo lo acepta si el repositorio es público.
+- `bump`: `major`, `minor`, `patch` or `prerelease`.
+- `tag`: npm dist-tag (`latest`, `default`, `alpha` or `demo`). With a tag other than `latest` the version is a prerelease (`0.0.2-alpha.0`).
+- `provenance`: publish with provenance. npm only accepts it if the repository is public.
 
-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.
+After publishing, it creates the version commit and tag, and a GitHub release linking to the version on npm.
 
-## Seguridad
+## Security
 
-Para reportar una vulnerabilidad, mira [SECURITY.md](SECURITY.md).
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
 
-## Licencia
+## License
 
 [MIT](LICENSE)

package/SECURITY.md

@@ -1,46 +1,46 @@
-# Política de seguridad
+# Security Policy
 
-## Versiones soportadas
+## Supported versions
 
-Solo se mantiene la última versión publicada en npm de `@jondotsoy/envs`. Las correcciones de seguridad se publican en una versión nueva.
+Only the latest version of `@jondotsoy/envs` published on npm is maintained. Security fixes are released in a new version.
 
-## Reportar una vulnerabilidad
+## Reporting a vulnerability
 
-No abras un issue público para reportar una vulnerabilidad. Repórtala de forma privada por uno de estos medios:
+Do not open a public issue to report a vulnerability. Report it privately through one of these channels:
 
-- Con el reporte privado de vulnerabilidades de GitHub: pestaña **Security** del repositorio, **Report a vulnerability**.
-- Por correo a [hi@jon.soy](mailto:hi@jon.soy).
+- GitHub's private vulnerability reporting: the repository's **Security** tab, **Report a vulnerability**.
+- By email to [hi@jon.soy](mailto:hi@jon.soy).
 
-Incluye, si puedes:
+If you can, include:
 
-- la versión de `@jondotsoy/envs` y de Bun que usas;
-- una descripción del problema y su impacto;
-- los pasos para reproducirlo.
+- the version of `@jondotsoy/envs` and of Bun you use;
+- a description of the problem and its impact;
+- the steps to reproduce it.
 
-Te responderé lo antes posible y coordinaremos la corrección y la divulgación del problema.
+I will reply as soon as possible and we will coordinate the fix and the disclosure of the issue.
 
-## Archivos que modifica
+## Files it modifies
 
-`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>`.
+`envs` only reads and writes the files in this table. `<root>` is the main repo (inside a worktree, the parent repo) and `<worktree>` is the folder of each worktree listed by `git worktree list`, including the main repo, even if it is outside `<root>`.
 
-| Comando | Lee | Escribe |
+| Command | Reads | Writes |
 | --- | --- | --- |
-| `envs init` | — | Crea `<raíz>/.envs/`, `<raíz>/.envs/.gitignore` y `<raíz>/.envs/values.yml`, solo si no existen. Nunca sobrescribe. |
-| `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. |
-| `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. |
-| `envs edit` | Lo mismo que `pull` y `push` | Lo mismo que `pull` y `push`. Además ejecuta `code -w <raíz>/.envs/values.yml`. |
+| `envs init` | — | Creates `<root>/.envs/`, `<root>/.envs/.gitignore` and `<root>/.envs/values.yml`, only if they do not exist. Never overwrites. |
+| `envs pull` | `<worktree>/.env` of each worktree | Rewrites `<root>/.envs/values.yml`. The file is serialized again, so YAML comments are lost. |
+| `envs push` | `<root>/.envs/values.yml` | Creates or updates `<worktree>/.env` of each worktree that has values. Updates existing variables in place, appends new ones at the end and keeps the rest of the file. If there are `defaults`, this includes all worktrees. |
+| `envs edit` | Same as `pull` and `push` | Same as `pull` and `push`. It also runs `code -w <root>/.envs/values.yml`. |
 
-Además:
+Additionally:
 
-- Ejecuta `git rev-parse` y `git worktree list` para ubicar la raíz y los worktrees. Son comandos de solo lectura.
-- `envs edit` ejecuta el programa `code` que encuentre en el `PATH`.
-- No hace conexiones de red ni modifica otros archivos del proyecto, ni siquiera el `.gitignore` de tu proyecto.
+- It runs `git rev-parse` and `git worktree list` to locate the root and the worktrees. These are read-only commands.
+- `envs edit` runs the `code` program found in the `PATH`.
+- It makes no network connections and does not modify other project files, not even your project's `.gitignore`.
 
-## Manejo de secretos
+## Handling secrets
 
-`envs` trabaja con valores que suelen ser secretos:
+`envs` works with values that are often secrets:
 
-- `.envs/values.yml` guarda los valores de todos los worktrees en texto plano.
-- `envs init` crea `.envs/.gitignore` con `*`, para que la carpeta `.envs/` no se suba a git. No quites ese archivo.
-- `envs push` escribe los valores en los archivos `.env` de cada worktree. Asegúrate de que `.env` esté en el `.gitignore` de tu proyecto.
-- No compartas `values.yml` ni lo pegues en issues o logs.
+- `.envs/values.yml` stores the values of all worktrees in plain text.
+- `envs init` creates `.envs/.gitignore` with `*`, so the `.envs/` folder is not committed to git. Do not remove that file.
+- `envs push` writes the values to the `.env` files of each worktree. Make sure `.env` is in your project's `.gitignore`.
+- Do not share `values.yml` or paste it in issues or logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jondotsoy/envs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "author": {
     "name": "Jonathan Delgado",