@jondotsoy/envs 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,103 @@
+# @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.
+
+Requiere [Bun](https://bun.com) y git.
+
+## Instalación
+
+```bash
+bun add -g @jondotsoy/envs
+```
+
+O sin instalar:
+
+```bash
+bunx @jondotsoy/envs help
+```
+
+## Uso
+
+Ejecuta los comandos dentro del repo o de cualquiera de sus worktrees. Dentro de un worktree, `.envs/` siempre vive en el repo principal.
+
+| Comando | Qué hace |
+| --- | --- |
+| `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. |
+
+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`.
+
+### `envs lint`
+
+Nunca imprime los valores, solo la variable y su ubicación (`envs.DB_PASSWORD.main`).
+
+| Regla | Detecta |
+| --- | --- |
+| `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`
+
+```yaml
+defaults:
+  LOG_LEVEL: info
+
+envs:
+  DATABASE_URL:
+    main: postgres://localhost/main
+    feature-x: postgres://localhost/feature_x
+  PORT:
+    main: "3000"
+    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.
+
+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`:
+
+```yaml
+# yaml-language-server: $schema=../schema/values.schema.json
+```
+
+## Desarrollo
+
+```bash
+bun install
+bun test              # ejecuta los tests
+bun test --coverage   # con cobertura
+bun run build         # genera dist/ (envs.js y 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.
+
+## Publicación
+
+El workflow **Publish** (Actions → Publish → Run workflow) sube la versión, hace el build y publica `dist/` en npm por 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.
+
+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.
+
+## Seguridad
+
+Para reportar una vulnerabilidad, mira [SECURITY.md](SECURITY.md).
+
+## Licencia
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,46 @@
+# Política de seguridad
+
+## Versiones soportadas
+
+Solo se mantiene la última versión publicada en npm de `@jondotsoy/envs`. Las correcciones de seguridad se publican en una versión nueva.
+
+## Reportar una vulnerabilidad
+
+No abras un issue público para reportar una vulnerabilidad. Repórtala de forma privada por uno de estos medios:
+
+- 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).
+
+Incluye, si puedes:
+
+- la versión de `@jondotsoy/envs` y de Bun que usas;
+- una descripción del problema y su impacto;
+- los pasos para reproducirlo.
+
+Te responderé lo antes posible y coordinaremos la corrección y la divulgación del problema.
+
+## Archivos que modifica
+
+`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>`.
+
+| Comando | Lee | Escribe |
+| --- | --- | --- |
+| `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`. |
+
+Además:
+
+- 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.
+
+## Manejo de secretos
+
+`envs` trabaja con valores que suelen ser secretos:
+
+- `.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.

package/envs.js

@@ -4,13 +4,228 @@
 // src/envs.ts
 import { mkdir } from "fs/promises";
 import { basename, dirname, join } from "path";
+import { stat } from "fs/promises";
 var {$ } = globalThis.Bun;
+
+// src/lint-rules.ts
+var SENSITIVE_KEY = /(^|_)(SECRET|PASSWORD|PASSWD|PWD|TOKEN|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY|CREDENTIALS?|AUTH|SALT|SIGNING)(_|$)/i;
+var WEAK_VALUES = new Set([
+  "",
+  "changeme",
+  "change-me",
+  "change_me",
+  "password",
+  "passw0rd",
+  "secret",
+  "admin",
+  "root",
+  "test",
+  "default",
+  "example",
+  "123456",
+  "12345678",
+  "qwerty",
+  "todo",
+  "xxx"
+]);
+var SECRET_PATTERNS = [
+  [/AKIA[0-9A-Z]{16}/, "an AWS access key id"],
+  [/gh[pousr]_[A-Za-z0-9]{36,}/, "a GitHub token"],
+  [/sk-[A-Za-z0-9_-]{20,}/, "an API secret key"],
+  [/xox[abprs]-[A-Za-z0-9-]{10,}/, "a Slack token"],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, "a private key"]
+];
+function isSensitiveKey(key) {
+  return SENSITIVE_KEY.test(key);
+}
+function entries({ values }) {
+  const result = [];
+  for (const [key, value] of Object.entries(values.defaults ?? {})) {
+    result.push({ key, text: String(value), location: `defaults.${key}`, shared: true });
+  }
+  for (const [key, byWorktree] of Object.entries(values.envs ?? {})) {
+    for (const [worktree, value] of Object.entries(byWorktree ?? {})) {
+      result.push({
+        key,
+        text: String(value),
+        location: `envs.${key}.${worktree}`,
+        shared: false
+      });
+    }
+  }
+  return result;
+}
+function parseUrl(text) {
+  const match = text.match(/^([a-z][a-z0-9+.-]*):\/\/([^/\s]*)/i);
+  if (!match)
+    return;
+  const scheme = match[1].toLowerCase();
+  const authority = match[2];
+  const hostname = authority.slice(authority.lastIndexOf("@") + 1).replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+  return {
+    scheme,
+    hasPassword: /^[^@]*:[^@]+@/.test(authority),
+    local: /^(localhost|127\.\d+\.\d+\.\d+|::1|0\.0\.0\.0)$/.test(hostname)
+  };
+}
+var valuesFile = ".envs/values.yml";
+function envFiles(ctx) {
+  return [
+    { location: valuesFile, mode: ctx.valuesMode },
+    ...ctx.dotenvs.map((d) => ({ location: `${d.name}/.env`, mode: d.mode }))
+  ];
+}
+var rules = [
+  {
+    id: "tracked-values",
+    description: "values.yml is tracked by git.",
+    async check(ctx) {
+      if (!await ctx.isTracked(ctx.root, valuesFile))
+        return [];
+      return [
+        {
+          location: valuesFile,
+          message: "values.yml is tracked by git, so its secrets are in the history. Run `git rm --cached .envs/values.yml`."
+        }
+      ];
+    }
+  },
+  {
+    id: "unignored-values",
+    description: "values.yml is neither tracked nor ignored by git.",
+    async check(ctx) {
+      if (await ctx.isTracked(ctx.root, valuesFile))
+        return [];
+      if (await ctx.isIgnored(ctx.root, valuesFile))
+        return [];
+      return [
+        {
+          location: valuesFile,
+          message: "values.yml is not ignored by git and could be committed by accident. Add `*` to .envs/.gitignore."
+        }
+      ];
+    }
+  },
+  {
+    id: "open-permissions",
+    description: "values.yml is readable by other users.",
+    check({ valuesMode }) {
+      if (valuesMode === undefined || (valuesMode & 63) === 0)
+        return [];
+      return [
+        {
+          location: valuesFile,
+          message: `values.yml is readable by other users (mode ${(valuesMode & 511).toString(8)}). Run \`chmod 600 .envs/values.yml\`.`
+        }
+      ];
+    }
+  },
+  {
+    id: "executable-files",
+    description: "values.yml or a worktree's .env has execute permission.",
+    check: (ctx) => envFiles(ctx).filter((f) => f.mode !== undefined && (f.mode & 73) !== 0).map((f) => ({
+      location: f.location,
+      message: `The file is executable (mode ${(f.mode & 511).toString(8)}); env files are data and must not be. Run \`chmod -x\` on it.`
+    }))
+  },
+  {
+    id: "writable-files",
+    description: "values.yml or a worktree's .env is writable by other users.",
+    check: (ctx) => envFiles(ctx).filter((f) => f.mode !== undefined && (f.mode & 18) !== 0).map((f) => ({
+      location: f.location,
+      message: `The file is writable by group or other users (mode ${(f.mode & 511).toString(8)}), who could change your environment. Run \`chmod go-w\` on it.`
+    }))
+  },
+  {
+    id: "tracked-dotenv",
+    description: "A worktree's .env is tracked by git.",
+    async check(ctx) {
+      const found = [];
+      for (const { name, path } of ctx.dotenvs) {
+        if (!await ctx.isTracked(path, ".env"))
+          continue;
+        found.push({
+          location: `${name}/.env`,
+          message: "The .env is tracked by git. Run `git rm --cached .env` and add it to .gitignore."
+        });
+      }
+      return found;
+    }
+  },
+  {
+    id: "unignored-dotenv",
+    description: "A worktree's .env is neither tracked nor ignored by git.",
+    async check(ctx) {
+      const found = [];
+      for (const { name, path } of ctx.dotenvs) {
+        if (await ctx.isTracked(path, ".env"))
+          continue;
+        if (await ctx.isIgnored(path, ".env"))
+          continue;
+        found.push({
+          location: `${name}/.env`,
+          message: "The .env is not ignored by git. Add `.env` to .gitignore."
+        });
+      }
+      return found;
+    }
+  },
+  {
+    id: "weak-secret",
+    description: "A sensitive variable is empty or has an easily guessed value.",
+    check: (ctx) => entries(ctx).filter((e) => isSensitiveKey(e.key) && WEAK_VALUES.has(e.text.trim().toLowerCase())).map((e) => ({
+      location: e.location,
+      message: `${e.key} has an empty or easily guessed value.`
+    }))
+  },
+  {
+    id: "shared-secret",
+    description: "A sensitive variable is in defaults, so it goes to every worktree.",
+    check: (ctx) => entries(ctx).filter((e) => e.shared && isSensitiveKey(e.key)).map((e) => ({
+      location: e.location,
+      message: `${e.key} looks sensitive but is written to every worktree; set it per worktree under envs instead.`
+    }))
+  },
+  {
+    id: "secret-pattern",
+    description: "A value has the format of a well-known secret.",
+    check: (ctx) => entries(ctx).flatMap((e) => SECRET_PATTERNS.filter(([pattern]) => pattern.test(e.text)).map(([, name]) => ({
+      location: e.location,
+      message: `${e.key} looks like ${name}.`
+    })))
+  },
+  {
+    id: "url-credentials",
+    description: "A remote URL embeds a password.",
+    check: (ctx) => entries(ctx).filter((e) => {
+      const url = parseUrl(e.text);
+      return url?.hasPassword && !url.local;
+    }).map((e) => ({
+      location: e.location,
+      message: `${e.key} embeds a password in its URL.`
+    }))
+  },
+  {
+    id: "insecure-url",
+    description: "A remote URL uses an unencrypted protocol.",
+    check: (ctx) => entries(ctx).filter((e) => {
+      const url = parseUrl(e.text);
+      return url && !url.local && ["http", "ws", "ftp"].includes(url.scheme);
+    }).map((e) => ({
+      location: e.location,
+      message: `${e.key} uses ${parseUrl(e.text).scheme}:// instead of an encrypted protocol.`
+    }))
+  }
+];
+
+// src/envs.ts
 var HELP = `Usage: envs <command>
 
 Commands:
   init    Create the .envs/ directory (.gitignore, values.yml)
   pull    Read each worktree's .env and write it into .envs/values.yml
   push    Write defaults and .envs/values.yml into the .env of each worktree
+  lint    Warn about insecure values and unprotected secret files
   edit    Pull, open .envs/values.yml in VS Code (code -w), then push
   help    Show this help message
 `;
@@ -67,6 +282,18 @@ function parseDotenv(text) {
   }
   return result;
 }
+function parseValue(value) {
+  if (value === "true")
+    return true;
+  if (value === "false")
+    return false;
+  if (/^-?\d+(\.\d+)?$/.test(value)) {
+    const number = Number(value);
+    if (String(number) === value)
+      return number;
+  }
+  return value;
+}
 function formatDotenvValue(value) {
   if (value !== "" && !/[\s#"'\\$]/.test(value))
     return value;
@@ -155,7 +382,7 @@ async function pull(ctx) {
         delete byWorktree[name];
     }
     for (const [key, value] of Object.entries(parsed)) {
-      (envs[key] ??= {})[name] = value;
+      (envs[key] ??= {})[name] = parseValue(value);
     }
     ctx.log(`Pulled ${name}`);
   }
@@ -166,6 +393,51 @@ async function pull(ctx) {
   await Bun.write(valuesPath, Bun.YAML.stringify(values, null, 2));
   return 0;
 }
+async function isIgnored(dir, file) {
+  const result = await $`git check-ignore -q ${file}`.cwd(dir).nothrow().quiet();
+  return result.exitCode === 0;
+}
+async function isTracked(dir, file) {
+  const result = await $`git ls-files --error-unmatch ${file}`.cwd(dir).nothrow().quiet();
+  return result.exitCode === 0;
+}
+async function lint(ctx) {
+  const read = await readValues(ctx);
+  if (!read)
+    return 1;
+  const root = await findRoot(ctx.cwd);
+  const worktrees = await listWorktrees(ctx.cwd);
+  const modeOf = async (path) => process.platform === "win32" ? undefined : (await stat(path)).mode;
+  const dotenvs = [];
+  for (const worktree of worktrees) {
+    const path = join(worktree.path, ".env");
+    if (await Bun.file(path).exists()) {
+      dotenvs.push({ ...worktree, mode: await modeOf(path) });
+    }
+  }
+  const lintContext = {
+    values: read.values,
+    root,
+    valuesMode: await modeOf(read.path),
+    dotenvs,
+    isTracked,
+    isIgnored
+  };
+  let count = 0;
+  for (const rule of rules) {
+    for (const { location, message } of await rule.check(lintContext)) {
+      ctx.error(`warning [${rule.id}] ${location}: ${message}`);
+      count++;
+    }
+  }
+  if (count === 0) {
+    ctx.log("No security problems found.");
+    return 0;
+  }
+  ctx.error(`
+${count} warning(s) found.`);
+  return 1;
+}
 async function edit(ctx) {
   const pulled = await pull(ctx);
   if (pulled !== 0)
@@ -190,6 +462,8 @@ async function run(args, ctx = defaultContext()) {
       return await push(ctx);
     case "pull":
       return await pull(ctx);
+    case "lint":
+      return await lint(ctx);
     case "edit":
       return await edit(ctx);
     default:

package/package.json

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