@jondotsoy/envs 0.1.5 → 0.1.7

package/README.md

@@ -42,6 +42,7 @@ Run the commands inside the repo or any of its worktrees. Inside a worktree, `.e
 | `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 use [profile]` | Sets the profile of the current worktree (`uses.<worktree>`) and pushes that worktree. Without arguments it lists the profile of each worktree. The profile must already exist 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 help` | Shows the help (also `--help`, `-h`, or no command). |
 
@@ -87,33 +88,59 @@ It never prints values, only the variable and its location (`envs.DB_PASSWORD.ma
 | `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. |
+| `shared-secret` | Sensitive variable in `defaults`, which is written to all worktrees using that profile. |
+| `unknown-profile` | `uses` names a profile that is not in `profiles`. |
 | `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:
-  LOG_LEVEL: info
-
-envs:
-  DATABASE_URL:
-    main: postgres://localhost/main
-    feature-x: postgres://localhost/feature_x
-  PORT:
-    main: "3000"
-    feature-x: "3001"
+uses:
+  main: local
+  feature-x: dev
+profiles:
+  default:
+    defaults:
+      LOG_LEVEL: info
+    envs:
+      PORT:
+        main: 3000
+        feature-x: 3001
+  local:
+    defaults:
+      DATABASE_URL: postgres://localhost/app
+    envs: {}
+  dev:
+    defaults:
+      DATABASE_URL: postgres://dev.internal/app
+    envs:
+      PORT:
+        feature-x: 4001
 ```
 
-- `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`.
+- Every profile is written with both `defaults` and `envs` (empty when it has nothing); a profile is never `null`.
+- `profiles.<profile>.defaults`: default value of each variable for the worktrees that use the profile.
+- `profiles.<profile>.envs.<VARIABLE>.<worktree>`: value of the variable in that worktree. It overrides the profile's `defaults`.
+- `uses.<worktree>`: profile of that worktree. A worktree that is not listed uses `default`; `pull` adds it as `default`.
 - 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.
 
-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`:
+A worktree receives, from lowest to highest precedence: `default` defaults, `default` envs, its profile's defaults, its profile's envs. With the `default` profile only the first two apply.
+
+The `.env` files are the source of truth: `pull` (and `edit`) rewrites `values.yml` from them, keeping only `uses` and `profiles`.
+
+### Creating a profile
+
+Write a profile that does not exist yet in `uses.<worktree>` while running `envs edit`: when you close the editor it is created as a copy of `default` (and the worktree receives it). A profile you add by hand under `profiles`, with values or empty, keeps what you wrote (nothing is copied from `default`) and is completed with an empty `defaults`/`envs` if one is missing. `envs push` and `envs use` do not create profiles: they fail with an unknown profile error. `envs lint` reports it as `unknown-profile`.
+
+### Previous format
+
+Files with `defaults` and `envs` at the root keep working: they are read as `profiles.default.defaults` and `profiles.default.envs`, and the next `envs edit` or `envs pull` rewrites the file in the new format.
+
+The schema (JSON Schema) is at [`schema/values.schema.json`](schema/values.schema.json). It is also published at <https://jondotsoy.github.io/envs/schema.json>. `init`, `pull` and `edit` write this line at the top of `values.yml`, so VS Code validates the file with the YAML extension:
 
 ```yaml
-# yaml-language-server: $schema=../schema/values.schema.json
+# yaml-language-server: $schema=https://jondotsoy.github.io/envs/schema.json
 ```
 
 ## Development

package/envs.js

@@ -40,18 +40,24 @@ function isSensitiveKey(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
-      });
+  const collect = (prefix, section) => {
+    for (const [key, value] of Object.entries(section?.defaults ?? {})) {
+      result.push({ key, text: String(value), location: `${prefix}defaults.${key}`, shared: true });
+    }
+    for (const [key, byWorktree] of Object.entries(section?.envs ?? {})) {
+      for (const [worktree, value] of Object.entries(byWorktree ?? {})) {
+        result.push({
+          key,
+          text: String(value),
+          location: `${prefix}envs.${key}.${worktree}`,
+          shared: false
+        });
+      }
     }
+  };
+  collect("", values);
+  for (const [name, profile] of Object.entries(values.profiles ?? {})) {
+    collect(`profiles.${name}.`, profile);
   }
   return result;
 }
@@ -180,7 +186,7 @@ var rules = [
   },
   {
     id: "shared-secret",
-    description: "A sensitive variable is in defaults, so it goes to every worktree.",
+    description: "A sensitive variable is in defaults, so it goes to every worktree using that profile.",
     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.`
@@ -215,6 +221,14 @@ var rules = [
       location: e.location,
       message: `${e.key} uses ${parseUrl(e.text).scheme}:// instead of an encrypted protocol.`
     }))
+  },
+  {
+    id: "unknown-profile",
+    description: "A worktree uses a profile that is not defined.",
+    check: ({ values }) => Object.entries(values.uses ?? {}).filter(([, profile]) => profile !== "default" && !Object.hasOwn(values.profiles ?? {}, profile)).map(([worktree, profile]) => ({
+      location: `uses.${worktree}`,
+      message: `Profile "${profile}" is not defined under profiles; \`envs edit\` creates it from default.`
+    }))
   }
 ];
 
@@ -227,6 +241,7 @@ Commands:
   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
+  use     Select the profile of the current worktree (envs use <profile>), or list them
   help    Show this help message
 `;
 var colorsDisabled = () => Boolean(process.env.NO_COLOR);
@@ -247,6 +262,72 @@ var defaultContext = () => ({
     return await proc.exited;
   }
 });
+var DEFAULT_PROFILE = "default";
+var hasProfile = (values, name) => Object.hasOwn(values.profiles, name);
+function normalizeValues(raw) {
+  const profiles = {};
+  const add = (name, profile) => {
+    const target = profiles[name] ??= { defaults: {}, envs: {} };
+    Object.assign(target.defaults, profile?.defaults);
+    for (const [key, byWorktree] of Object.entries(profile?.envs ?? {})) {
+      Object.assign(target.envs[key] ??= {}, byWorktree);
+    }
+  };
+  add(DEFAULT_PROFILE, { defaults: raw.defaults, envs: raw.envs });
+  for (const [name, profile] of Object.entries(raw.profiles ?? {})) {
+    add(name, profile);
+  }
+  return { uses: { ...raw.uses }, profiles };
+}
+function materializeProfiles(values) {
+  const created = [];
+  for (const name of Object.values(values.uses).map(String)) {
+    if (hasProfile(values, name))
+      continue;
+    values.profiles[name] = structuredClone(values.profiles[DEFAULT_PROFILE]);
+    created.push(name);
+  }
+  return created;
+}
+function resolveEntries(values, worktree, profile, includeProfileEnvs = true) {
+  const entries = {};
+  for (const name of new Set([DEFAULT_PROFILE, profile])) {
+    const layer = values.profiles[name];
+    for (const [key, value] of Object.entries(layer.defaults)) {
+      entries[key] = String(value);
+    }
+    if (name === profile && !includeProfileEnvs)
+      continue;
+    for (const [key, byWorktree] of Object.entries(layer.envs)) {
+      if (byWorktree && worktree in byWorktree) {
+        entries[key] = String(byWorktree[worktree]);
+      }
+    }
+  }
+  return entries;
+}
+var hasCompleteProfiles = (raw) => Object.values(raw.profiles ?? {}).every((profile) => typeof profile?.defaults === "object" && profile.defaults !== null && typeof profile.envs === "object" && profile.envs !== null);
+function stringifyValues(values) {
+  const profiles = Object.fromEntries(Object.entries(values.profiles).map(([name, { defaults, envs }]) => {
+    const kept = Object.fromEntries(Object.entries(envs).filter(([, byWorktree]) => Object.keys(byWorktree).length > 0));
+    return [name, { defaults, envs: kept }];
+  }));
+  const out = Object.keys(values.uses).length > 0 ? { uses: values.uses, profiles } : { profiles };
+  return SCHEMA_COMMENT + Bun.YAML.stringify(out, null, 2);
+}
+var SCHEMA_COMMENT = `# yaml-language-server: $schema=https://jondotsoy.github.io/envs/schema.json
+`;
+function checkProfiles(ctx, values, worktrees) {
+  let ok = true;
+  for (const { name } of worktrees) {
+    const profile = values.uses[name] ?? DEFAULT_PROFILE;
+    if (hasProfile(values, profile))
+      continue;
+    ok = false;
+    ctx.error(`Unknown profile "${profile}" for worktree ${name}. Available: ${Object.keys(values.profiles).join(", ")}. Run \`envs edit\` to create it.`);
+  }
+  return ok;
+}
 async function findRoot(cwd) {
   const result = await $`git rev-parse --path-format=absolute --git-common-dir`.cwd(cwd).nothrow().quiet();
   if (result.exitCode !== 0)
@@ -336,7 +417,7 @@ async function readValues(ctx) {
 async function init(ctx) {
   const root = await findRoot(ctx.cwd);
   const files = { ".envs/.gitignore": `*
-`, ".envs/values.yml": "" };
+`, ".envs/values.yml": SCHEMA_COMMENT };
   await mkdir(join(root, ".envs"), { recursive: true });
   for (const [name, content] of Object.entries(files)) {
     const path = join(root, name);
@@ -349,23 +430,21 @@ async function init(ctx) {
   }
   return 0;
 }
-async function push(ctx) {
+async function push(ctx, only) {
   const read = await readValues(ctx);
   if (!read)
     return 1;
-  const { values } = read;
+  const values = normalizeValues(read.values);
+  const worktrees = (await listWorktrees(ctx.cwd)).filter(({ name }) => only === undefined || name === only);
+  if (!checkProfiles(ctx, values, worktrees))
+    return 1;
   const changes = new Map;
-  for (const { name, path } of await listWorktrees(ctx.cwd)) {
-    const entries = {};
-    for (const [key, value] of Object.entries(values.defaults ?? {})) {
-      entries[key] = String(value);
-    }
-    for (const [key, byWorktree] of Object.entries(values.envs ?? {})) {
-      if (name in byWorktree)
-        entries[key] = String(byWorktree[name]);
-    }
+  for (const { name, path } of worktrees) {
+    const profile = values.uses[name] ?? DEFAULT_PROFILE;
+    const entries = resolveEntries(values, name, profile);
     if (Object.keys(entries).length === 0)
       continue;
+    const label = profile === DEFAULT_PROFILE ? name : `${name} [${profile}]`;
     const dotenv = Bun.file(join(path, ".env"));
     const current = await dotenv.exists() ? await dotenv.text() : "";
     const existing = parseDotenv(current);
@@ -374,7 +453,7 @@ async function push(ctx) {
         continue;
       const shown = isMaskedKey(key) ? MASK : formatDotenvValue(value);
       const line = `${key}=${shown}`;
-      changes.set(line, [...changes.get(line) ?? [], name]);
+      changes.set(line, [...changes.get(line) ?? [], label]);
     }
     await Bun.write(dotenv, updateDotenv(current, entries));
   }
@@ -387,12 +466,13 @@ async function pull(ctx) {
   const read = await readValues(ctx);
   if (!read)
     return 1;
-  const { path: valuesPath, values } = read;
-  const envs = values.envs ??= {};
-  const defaults = values.defaults ?? {};
+  const values = normalizeValues(read.values);
+  const worktrees = await listWorktrees(ctx.cwd);
+  materializeProfiles(values);
   const pulledNames = [];
   const pulledKeys = new Set;
-  for (const { name, path } of await listWorktrees(ctx.cwd)) {
+  for (const { name, path } of worktrees) {
+    const profile = values.uses[name] ??= DEFAULT_PROFILE;
     const dotenv = Bun.file(join(path, ".env"));
     if (!await dotenv.exists())
       continue;
@@ -400,14 +480,15 @@ async function pull(ctx) {
     pulledNames.push(name);
     for (const key of Object.keys(parsed))
       pulledKeys.add(key);
+    const { envs } = values.profiles[profile];
     for (const [key, byWorktree] of Object.entries(envs)) {
       if (!(key in parsed))
         delete byWorktree[name];
     }
+    const base = resolveEntries(values, name, profile, false);
     for (const [key, value] of Object.entries(parsed)) {
       const parsedValue = parseValue(value);
-      const fromDefaults = key in defaults && String(defaults[key]) === String(parsedValue);
-      if (fromDefaults) {
+      if (key in base && base[key] === String(parsedValue)) {
         if (envs[key])
           delete envs[key][name];
       } else {
@@ -415,16 +496,40 @@ async function pull(ctx) {
       }
     }
   }
-  for (const [key, byWorktree] of Object.entries(envs)) {
-    if (Object.keys(byWorktree).length === 0)
-      delete envs[key];
-  }
-  await Bun.write(valuesPath, Bun.YAML.stringify(values, null, 2));
+  await Bun.write(read.path, stringifyValues(values));
   if (pulledNames.length > 0) {
     ctx.log(green(`\u2193 pulling ${pulledNames.join(", ")} - ${pulledKeys.size} variables`));
   }
   return 0;
 }
+async function use(ctx, profile) {
+  const read = await readValues(ctx);
+  if (!read)
+    return 1;
+  const values = normalizeValues(read.values);
+  const worktrees = await listWorktrees(ctx.cwd);
+  if (profile === undefined) {
+    for (const { name } of worktrees) {
+      ctx.log(`${name}: ${values.uses[name] ?? DEFAULT_PROFILE}`);
+    }
+    return 0;
+  }
+  if (!hasProfile(values, profile)) {
+    ctx.error(`Unknown profile "${profile}". Available: ${Object.keys(values.profiles).join(", ")}. Add it in \`envs edit\` first.`);
+    return 1;
+  }
+  const top = await $`git rev-parse --show-toplevel`.cwd(ctx.cwd).nothrow().quiet();
+  const current = worktrees.find(({ path }) => path === top.stdout.toString().trim());
+  if (!current) {
+    ctx.error("Run `envs use` inside a git worktree.");
+    return 1;
+  }
+  for (const { name } of worktrees)
+    values.uses[name] ??= DEFAULT_PROFILE;
+  values.uses[current.name] = profile;
+  await Bun.write(read.path, stringifyValues(values));
+  return await push(ctx, current.name);
+}
 async function isIgnored(dir, file) {
   const result = await $`git check-ignore -q ${file}`.cwd(dir).nothrow().quiet();
   return result.exitCode === 0;
@@ -477,11 +582,31 @@ async function edit(ctx) {
   const pulled = await pull(ctx);
   if (pulled !== 0)
     return pulled;
+  const original = await Bun.file(valuesPath).text();
+  await Bun.write(valuesPath, EDIT_NOTICE + original);
   const code = await ctx.openEditor(valuesPath);
+  const edited = await Bun.file(valuesPath).text();
+  if (edited.startsWith(EDIT_NOTICE)) {
+    await Bun.write(valuesPath, edited.slice(EDIT_NOTICE.length));
+  }
   if (code !== 0)
     return code;
+  const raw = Bun.YAML.parse(await Bun.file(valuesPath).text()) ?? {};
+  const values = normalizeValues(raw);
+  const created = materializeProfiles(values);
+  if (created.length > 0 || !hasCompleteProfiles(raw)) {
+    await Bun.write(valuesPath, stringifyValues(values));
+  }
+  if (created.length > 0) {
+    ctx.log(green(`+ created ${created.join(", ")} from ${DEFAULT_PROFILE}`));
+  }
   return await push(ctx);
 }
+var EDIT_NOTICE = `# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+# Close this file when your changes are ready, then they are pushed.
+# To cancel the edit, press Ctrl+C in the terminal and then close this file.
+# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+`;
 async function run(args, ctx = defaultContext()) {
   const [command = "help"] = args;
   switch (command) {
@@ -500,6 +625,8 @@ async function run(args, ctx = defaultContext()) {
       return await lint(ctx);
     case "edit":
       return await edit(ctx);
+    case "use":
+      return await use(ctx, args[1]);
     default:
       ctx.error(`Unknown command: ${command}
 

package/package.json

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