@kaynooo/env-tools 0.6.0 → 0.7.0

package/dist/ev.js

@@ -276,12 +276,27 @@ function le(i = {}) {
 var t = le();
 
 // ../kit/src/style.ts
+var MARKS = {
+  ok: { symbol: "\u2713", word: "ok:", paint: (colors) => colors.green },
+  warn: { symbol: "!", word: "warning:", paint: (colors) => colors.yellow },
+  problem: { symbol: "\u2717", word: "error:", paint: (colors) => colors.red },
+  note: { symbol: "\xB7", word: "note:", paint: (colors) => colors.dim }
+};
 function takesControlCodes(stream, env = process2.env) {
   return stream.isTTY === true && env.NO_COLOR === undefined && env.NODE_DISABLE_COLORS === undefined && env.TERM !== "dumb";
 }
 function paint(stream, env = process2.env) {
   return le({ stream: { isTTY: takesControlCodes(stream, env) }, env });
 }
+function marked(mark, text, stream, detail, env = process2.env) {
+  const colors = paint(stream, env);
+  const { symbol, word, paint: tint } = MARKS[mark];
+  const head = takesControlCodes(stream, env) ? tint(colors)(symbol) : word;
+  return `${head} ${text}${detail === undefined ? "" : ` ${colors.dim(detail)}`}`;
+}
+function ok(text, detail) {
+  console.log(marked("ok", text, process2.stdout, detail));
+}
 var STATUSES = {
   passed: { symbol: "\u2713", words: ["passed", "success", "succeeded", "ok"], paint: (colors) => colors.green },
   failed: { symbol: "\u2717", words: ["failed", "failure", "error", "errored"], paint: (colors) => colors.red },
@@ -549,6 +564,11 @@ async function readInput(path, { noStdin = "nothing is piped on stdin" } = {}) {
     fail(`no file ${path}`);
   return file.text();
 }
+// ../kit/src/progress.ts
+var ESC = String.fromCharCode(27);
+var ESCAPE_CODE = new RegExp(`${ESC}(?:\\[[\\x30-\\x3F]*[\\x20-\\x2F]*[\\x40-\\x7E]|\\][^\\u0007${ESC}]*(?:\\u0007|${ESC}\\\\))`, "y");
+var RESET_STYLE = `${ESC}[0m`;
+var CLOSE_LINK = `${ESC}]8;;${ESC}\\`;
 // ../kit/src/cli.ts
 import process5 from "process";
 var LEVEL_OPTIONS = {
@@ -755,8 +775,17 @@ async function runMain({ name, version, run, redact }, argv = process5.argv.slic
     return reportThrown(name, error, redact, wantsJson(argv));
   }
 }
+// ../kit/src/logs.ts
+var DAY_MS = 24 * 60 * 60 * 1000;
+// ../kit/src/secrets.ts
+var SECRET_PART = /token|secret|passw|credential|private|dsn|apikey|accesskey|key$/i;
+var SECRET_WORDS = new Set(["key", "pass", "pwd", "auth", "salt", "cookie", "session", "jwt", "ssn", "iban", "card", "cvv", "otp"]);
+var WORD_BREAKS = /[^a-zA-Z\d]+|(?<=[a-z\d])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/;
+function isSecretName(name) {
+  return SECRET_PART.test(name) || name.split(WORD_BREAKS).some((word) => SECRET_WORDS.has(word.toLowerCase()));
+}
 // package.json
-var version = "0.6.0";
+var version = "0.7.0";
 
 // src/commands/audit.ts
 import { stat as stat4 } from "fs/promises";
@@ -769,7 +798,7 @@ import { dirname as dirname2, join as join2 } from "path";
 var {$ } = globalThis.Bun;
 
 // src/files.ts
-import { chmod, readdir, realpath, rename, rm, stat, writeFile } from "fs/promises";
+import { chmod, chown, readdir, realpath, rename, rm, stat, writeFile } from "fs/promises";
 import { basename, dirname, join } from "path";
 
 // src/dotenv.ts
@@ -778,7 +807,9 @@ var EXPORTED = /^\s*export\s/;
 var INLINE_COMMENT = /\s+#.*$/;
 var CARRIAGE_RETURN = /\r$/;
 var ESCAPES = { n: `
-`, r: "\r", t: "\t", '"': '"', "\\": "\\" };
+`, r: "\r", t: "\t", '"': '"', "\\": "\\", $: "$" };
+var LINE_BREAK = /[\r\n]/;
+var RAW_ONLY = /["\\]/;
 var NEEDS_QUOTES = /[\s#"'\\$`]/;
 function closingQuote(text, quote) {
   for (let index = 0;index < text.length; index++) {
@@ -789,6 +820,9 @@ function closingQuote(text, quote) {
   }
   return -1;
 }
+function unescapeDollar(text) {
+  return text.replaceAll("\\$", "$");
+}
 function unescapeDouble(text) {
   let out = "";
   for (let index = 0;index < text.length; index++) {
@@ -817,7 +851,7 @@ function parseDotenv(text) {
     const start = rest.trimStart();
     const quote = start[0];
     if (quote !== '"' && quote !== "'" && quote !== "`") {
-      lines.push({ raw: line, key, value: start.replace(INLINE_COMMENT, "").trim() });
+      lines.push({ raw: line, key, value: unescapeDollar(start.replace(INLINE_COMMENT, "").trim()) });
       continue;
     }
     let body = start.slice(1);
@@ -832,7 +866,7 @@ ${physical[index] ?? ""}`;
       end = closingQuote(body, quote);
     }
     const inner = end === -1 ? body : body.slice(0, end);
-    lines.push({ raw, key, value: quote === '"' ? unescapeDouble(inner) : inner });
+    lines.push({ raw, key, value: quote === '"' ? unescapeDouble(inner) : unescapeDollar(inner) });
   }
   return { lines };
 }
@@ -851,8 +885,10 @@ function entries(file) {
 function formatAssignment(key, value) {
   if (value === "" || !NEEDS_QUOTES.test(value))
     return `${key}=${value}`;
+  if (RAW_ONLY.test(value) && !value.includes("'") && !LINE_BREAK.test(value))
+    return `${key}='${value.replaceAll("$", "\\$")}'`;
   const escaped = value.replaceAll("\\", "\\\\").replaceAll('"', "\\\"").replaceAll("\r", "\\r").replaceAll(`
-`, "\\n");
+`, "\\n").replaceAll("$", "\\$");
   return `${key}="${escaped}"`;
 }
 function setLine(file, key, value, raw) {
@@ -882,20 +918,38 @@ function lastLine(file, key) {
 }
 
 // src/mask.ts
-var MIN_KNOWN_LENGTH = 6;
-var SECRET_KEY = /TOKEN|SECRET|PASSWORD|KEY|PRIVATE|DSN/i;
-var URL_PASSWORD = /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]*:([^\s@/]+)@/dgi;
+var MIN_KNOWN_LENGTH = 4;
+var KEY_MASK = "*** private key redacted ***";
+var PLAIN_VALUE = /^(?:true|false|null|none|nil|yes|no|on|off|undefined)$/i;
+var PLACEHOLDER = /^[$%{<(*/]/;
+var URL_PASSWORD = /(?<![a-z0-9+.-])[a-z][a-z0-9+.-]{0,31}:\/\/[^\s:/@]*:([^\s'"]{1,1024})@/dgi;
+var PORT = /^\d{1,5}$/;
 var ESCAPE2 = /[.*+?^${}()|[\]\\]/g;
+function isPlaceholder(value) {
+  return PLACEHOLDER.test(value) || PLAIN_VALUE.test(value);
+}
 var TOKEN_FORMATS = [
-  ["GitHub token", /\b(?:gh[pousr]_|github_pat_)\w{20,}/g],
-  ["GitLab token", /\bglpat-[\w-]{20,}/g],
-  ["API key", /\bsk-[\w-]{20,}/g],
-  ["Slack token", /\bxox[abprs]-[\w-]{10,}/g],
-  ["JWT", /\beyJ[\w-]+\.[\w-]+\.[\w-]+/g]
+  { kind: "GitHub token", pattern: /\b(?:gh[pousr]_|github_pat_)\w{20,}/dg },
+  { kind: "GitLab token", pattern: /\bglpat-[\w-]{20,}/dg },
+  { kind: "API key", pattern: /\bsk-[\w-]{20,}/dg },
+  { kind: "Slack token", pattern: /\bx(?:ox[abprs]|app)-[\w-]{10,}/dg },
+  { kind: "JWT", pattern: /\beyJ[\w-]+\.[\w-]+\.[\w-]+/dg },
+  { kind: "AWS access key", pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/dg },
+  { kind: "npm token", pattern: /\bnpm_[A-Za-z0-9]{30,}/dg },
+  { kind: "Stripe key", pattern: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{10,}/dg },
+  { kind: "Google API key", pattern: /\bAIza[\w-]{35}/dg },
+  { kind: "SendGrid key", pattern: /\bSG\.[\w-]{16,}\.[\w-]{16,}/dg },
+  { kind: "Authorization header", pattern: /\bAuthorization["']?\s*[:=]\s*["']?(?:Bearer|Basic|Token|Digest)\s+([^\s"',;]{8,})/dgi, skip: isPlaceholder },
+  { kind: "Bearer token", pattern: /\bBearer\s+((?=[\w.~+/=-]*\d)[\w.~+/=-]{20,})/dg },
+  { kind: "password", pattern: /(?<![\w-])(?:[\w-]{0,30}[_-])?(?:password|passwd|secret|api[_-]?key)(?:[_-][\w-]{0,30})?=([^\s"'&;,]{4,})/dgi, skip: isPlaceholder },
+  { kind: "password", pattern: /(?<![\w-])["']?(?:[\w-]{0,30}[_-])?(?:password|passwd|secret|api[_-]?key)(?:[_-][\w-]{0,30})?["']?\s*[:=]\s*(["'])((?:\\.|(?!\1)[^\\\n]){4,})\1/dgi, skip: isPlaceholder }
 ];
-var URL_PARTS = /\b[a-z][a-z0-9+.-]*:\/\/([^\s/?#'"<>`]*)([^\s?#'"<>`]*)(?:\?([^\s#'"<>`]*))?/dgi;
+var PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----/;
+var PEM_END = /-----END [A-Z ]*PRIVATE KEY(?: BLOCK)?-----/;
+var PEM_BODY = /(?<=-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----)(?:(?!-----END [A-Z ]*PRIVATE KEY(?: BLOCK)?-----)[\s\S])+/dg;
+var PEM_BEGIN_ALL = /-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----/g;
+var URL_PARTS = /(?<![a-z0-9+.-])[a-z][a-z0-9+.-]{0,31}:\/\/([^\s/?#'"<>`]*)([^\s?#'"<>`]*)(?:\?([^\s#'"<>`]*))?/dgi;
 var PATH_SEGMENT = /[^/]+/g;
-var QUERY_PARAM = /([^&=]+)=([^&]*)/g;
 var SECRET_PARAM = /^(?:token|[a-z]+_token|key|api[_-]?key|access[_-]?key|secret|[a-z]+_secret|password|passwd|pwd|sig|signature|auth|authorization)$/i;
 var WEBHOOK_FORMATS = [
   ["Discord webhook", /(?:^|\.)discord(?:app)?\.com\/api\/(?:v\d+\/)?webhooks\/\d+\/([\w-]+)/di],
@@ -904,28 +958,41 @@ var WEBHOOK_FORMATS = [
   ["healthchecks.io ping URL", /^hc-ping\.com\/([\w-]+)/di]
 ];
 var OPAQUE_SEGMENT = /^(?:(?=[\w-]{20,}$)(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[\w-]+|(?=[A-Za-z\d]{32,}$)(?=.*[A-Za-z])(?=.*\d).+)$/;
-var PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
-var PEM_END = /-----END [A-Z ]*PRIVATE KEY-----/;
-function isSecretKey(key) {
-  return SECRET_KEY.test(key);
-}
 function hint(value) {
   const shown = Math.min(3, Math.floor(value.length / 4));
   return `${value.slice(0, shown)}***(${value.length})`;
 }
+function forms(value) {
+  return [...new Set([value, encodeURIComponent(value), JSON.stringify(value).slice(1, -1)])];
+}
 function knownSecrets(pairs) {
   const keys = new Map;
   for (const [key, value] of pairs) {
-    if (value.length >= MIN_KNOWN_LENGTH && !keys.has(value))
-      keys.set(value, key);
+    if (value.length < MIN_KNOWN_LENGTH || PLAIN_VALUE.test(value))
+      continue;
+    for (const form of forms(value)) {
+      if (!keys.has(form))
+        keys.set(form, key);
+    }
   }
   if (keys.size === 0)
     return { pattern: undefined, keys };
   const alternatives = [...keys.keys()].sort((a, b) => b.length - a.length).map((value) => value.replace(ESCAPE2, "\\$&"));
   return { pattern: new RegExp(`(?<!\\w)(?:${alternatives.join("|")})(?!\\w)`, "g"), keys };
 }
+function passwordSpans(text) {
+  const spans = [];
+  for (const url of text.matchAll(URL_PASSWORD)) {
+    const [start, end] = url.indices?.[1] ?? [];
+    const password = url[1] ?? "";
+    const slash = password.indexOf("/");
+    if (start !== undefined && end !== undefined && !(slash !== -1 && PORT.test(password.slice(0, slash))))
+      spans.push([start, end]);
+  }
+  return spans;
+}
 function urlPasswords(text) {
-  return [...text.matchAll(URL_PASSWORD)].flatMap((url) => url[1] ?? []);
+  return passwordSpans(text).map(([start, end]) => text.slice(start, end));
 }
 function urlTokens(line) {
   const found = [];
@@ -952,24 +1019,34 @@ function urlTokens(line) {
     }
     if (query === undefined || queryStart === undefined)
       continue;
-    for (const param of query.matchAll(QUERY_PARAM)) {
-      const [name, value] = [param[1] ?? "", param[2] ?? ""];
-      if (value !== "" && SECRET_PARAM.test(name))
-        add("URL token", queryStart + param.index + name.length + 1, value);
+    let offset = 0;
+    for (const param of query.split("&")) {
+      const equals = param.indexOf("=");
+      if (equals > 0 && equals < param.length - 1 && SECRET_PARAM.test(param.slice(0, equals)))
+        add("URL token", queryStart + offset + equals + 1, param.slice(equals + 1));
+      offset += param.length + 1;
     }
   }
   return found.filter((match) => match.end > match.start);
 }
 function findSecrets(line, known) {
   const found = [];
-  for (const url of line.matchAll(URL_PASSWORD)) {
-    const [start, end] = url.indices?.[1] ?? [];
+  for (const [start, end] of passwordSpans(line))
+    found.push({ start, end, kind: "URL password", mask: "***" });
+  for (const body of line.matchAll(PEM_BODY)) {
+    const [start, end] = body.indices?.[0] ?? [];
     if (start !== undefined && end !== undefined)
-      found.push({ start, end, kind: "URL password", mask: "***" });
+      found.push({ start, end, kind: "private key", mask: KEY_MASK });
   }
-  for (const [kind, pattern] of TOKEN_FORMATS) {
-    for (const token of line.matchAll(pattern))
-      found.push({ start: token.index, end: token.index + token[0].length, kind, mask: hint(token[0]) });
+  for (const { kind, pattern, skip } of TOKEN_FORMATS) {
+    for (const token of line.matchAll(pattern)) {
+      const [start, end] = token.indices?.at(-1) ?? [];
+      if (start === undefined || end === undefined)
+        continue;
+      const value = line.slice(start, end);
+      if (!skip?.(value))
+        found.push({ start, end, kind, mask: hint(value) });
+    }
   }
   found.push(...urlTokens(line));
   if (known?.pattern !== undefined) {
@@ -984,6 +1061,13 @@ function findSecrets(line, known) {
   }
   return kept;
 }
+function openKeyBody(line) {
+  const last = [...line.matchAll(PEM_BEGIN_ALL)].at(-1);
+  if (last === undefined)
+    return;
+  const after = line.slice(last.index + last[0].length);
+  return PEM_END.test(after) ? undefined : after.trim();
+}
 function maskLine(line, known) {
   let out = "";
   let at = 0;
@@ -993,18 +1077,38 @@ function maskLine(line, known) {
   }
   return out + line.slice(at);
 }
-function maskValue(key, value) {
+function maskValue(key, value, known) {
   if (value === "")
     return value;
-  return isSecretKey(key) || PEM_BEGIN.test(value) ? hint(value) : maskLine(value);
+  return isSecretName(key) || PEM_BEGIN.test(value) ? hint(value) : maskLine(value, known);
 }
 
 // src/files.ts
-var ENV_FILE = /^\.env(?:\..+)?$/;
+var ENV_FILE = /^(?:\.env(?:\..+)?|.+\.env|\.envrc)$/;
 var TEMPLATE = /\.(?:example|sample|template|dist|defaults)$/;
+var KNOWN_DEPTH = 3;
+var SKIPPED = new Set(["node_modules", ".git", "vendor"]);
+var LOCK_WAIT_MS = 5000;
+var LOCK_STALE_MS = 30000;
+async function isFileEntry(entry, path) {
+  if (entry.isFile())
+    return true;
+  if (!entry.isSymbolicLink())
+    return false;
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
 async function envFiles(folder = process.cwd()) {
   const found = await readdir(folder, { withFileTypes: true });
-  return found.filter((entry) => entry.isFile() && ENV_FILE.test(entry.name)).map((entry) => entry.name).sort();
+  const names = [];
+  for (const entry of found) {
+    if (ENV_FILE.test(entry.name) && await isFileEntry(entry, join(folder, entry.name)))
+      names.push(entry.name);
+  }
+  return names.sort();
 }
 async function readEnv(path) {
   const file = Bun.file(path);
@@ -1012,46 +1116,125 @@ async function readEnv(path) {
     fail(`${path} does not exist`);
   return parseDotenv(await file.text());
 }
-async function writeEnv(path, file) {
+async function writeAtomic(path, text) {
   let target = path;
   let mode = 384;
+  let owner;
   try {
     target = await realpath(path);
-    mode = (await stat(target)).mode & 511;
-  } catch {}
+    const current = await stat(target);
+    mode = current.mode & 511;
+    owner = current;
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
   const temp = join(dirname(target), `.${basename(target)}.${process.pid}.${crypto.randomUUID()}.tmp`);
   try {
-    await writeFile(temp, serializeDotenv(file), { mode: 384, flag: "wx" });
+    await writeFile(temp, text, { mode: 384, flag: "wx" });
+    if (owner !== undefined)
+      await keepOwner(temp, owner);
     await chmod(temp, mode);
     await rename(temp, target);
   } finally {
     await rm(temp, { force: true });
   }
 }
-async function loadKnown(folder = process.cwd()) {
-  const pairs = [];
-  for (const name of await envFiles(folder)) {
-    for (const [key, value] of entries(parseDotenv(await Bun.file(`${folder}/${name}`).text()))) {
-      if (isSecretKey(key))
-        pairs.push([key, value]);
-      else
-        pairs.push(...urlPasswords(value).map((password) => [key, password]));
+async function keepOwner(path, owner) {
+  try {
+    await chown(path, owner.uid, owner.gid);
+  } catch (error) {
+    if (error.code !== "EPERM")
+      throw error;
+  }
+}
+async function writeEnv(path, file) {
+  await writeAtomic(path, serializeDotenv(file));
+}
+async function withLocks(paths, fn) {
+  const held = [];
+  try {
+    for (const path of [...new Set(paths)].sort())
+      held.push(await acquire(path));
+    return await fn();
+  } finally {
+    for (const lock of held)
+      await rm(lock, { force: true });
+  }
+}
+async function acquire(path) {
+  let real = path;
+  try {
+    real = await realpath(path);
+  } catch {}
+  const lock = join(dirname(real), `.${basename(real)}.lock`);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  while (true) {
+    try {
+      await writeFile(lock, String(process.pid), { flag: "wx", mode: 384 });
+      return lock;
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
     }
+    try {
+      if (Date.now() - (await stat(lock)).mtimeMs > LOCK_STALE_MS)
+        await rm(lock, { force: true });
+    } catch {}
+    if (Date.now() > deadline)
+      fail(`${path} is locked by another ev run (${lock})`, 1);
+    await Bun.sleep(25);
+  }
+}
+function secretPairs(file) {
+  const pairs = [];
+  for (const [key, value] of entries(file)) {
+    if (isSecretName(key))
+      pairs.push([key, value]);
+    else
+      pairs.push(...urlPasswords(value).map((password) => [key, password]));
+  }
+  return pairs;
+}
+async function envFilesBelow(folder, depth = 0) {
+  const found = [];
+  let children;
+  try {
+    children = await readdir(folder, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of children) {
+    const path = join(folder, entry.name);
+    if (entry.isDirectory() && depth < KNOWN_DEPTH && !SKIPPED.has(entry.name))
+      found.push(...await envFilesBelow(path, depth + 1));
+    else if (ENV_FILE.test(entry.name) && await isFileEntry(entry, path))
+      found.push(path);
+  }
+  return found;
+}
+async function loadKnown(folder = process.cwd(), extra = []) {
+  const pairs = extra.flatMap(secretPairs);
+  for (const path of await envFilesBelow(folder)) {
+    try {
+      pairs.push(...secretPairs(parseDotenv(await Bun.file(path).text())));
+    } catch {}
   }
   return knownSecrets(pairs);
 }
 
 // src/audit.ts
 var MAX_DEPTH = 5;
-var SKIPPED = new Set(["node_modules", ".git", "vendor"]);
+var SKIPPED2 = new Set(["node_modules", ".git", "vendor"]);
 var COMPOSE_FILE = /^(?:docker-)?compose[\w.-]*\.ya?ml$/;
 var ENTRY = /^\s*(?:-\s*)?["']?([A-Z0-9_]+)["']?\s*[:=]\s*["']?([^"'\s#]+)/;
-var SECRET_NAME = /(?:PASSWORD|PASSWD|SECRET|TOKEN|KEY)$/;
+var SETTING_SUFFIX = /_(?:TTL|FILE|PATH|DIR|NAME|TIMEOUT|EXPIRY|EXPIRES|LIFETIME|LENGTH|ENABLED|ALGORITHM|HEADER|PREFIX|COUNT|MAX|MIN)$/i;
+var ACL_READER = /^(?:user|group):[^:]+:r/;
 var FLAG = /^(?:[01]|yes|no|true|false)$/i;
 function isInlineSecret(name, value) {
   if (value === "" || value.startsWith("$") || value.startsWith("/run/secrets/") || FLAG.test(value))
     return false;
-  return SECRET_NAME.test(name) || urlPasswords(value).some((password) => !password.startsWith("$"));
+  return isSecretName(name) && !SETTING_SUFFIX.test(name) || urlPasswords(value).some((password) => !password.startsWith("$"));
 }
 function inlineSecrets(compose) {
   const names = compose.split(`
@@ -1070,8 +1253,30 @@ async function openToOthers(path) {
   }
   return true;
 }
+async function sharedWith(path) {
+  const info = await stat2(path);
+  const shared = (info.mode & 32) !== 0 && info.gid !== info.uid && info.gid !== process.getgid?.();
+  if (!shared && (Bun.which("getfacl") === null || !await hasAclReader(path)))
+    return false;
+  for (let dir = dirname2(path);dir !== "/"; dir = dirname2(dir)) {
+    if (((await stat2(dir)).mode & 9) === 0)
+      return false;
+  }
+  return true;
+}
+async function hasAclReader(path) {
+  const acl = await $`getfacl --absolute-names --omit-header -- ${path}`.quiet().nothrow();
+  return acl.exitCode === 0 && acl.stdout.toString().split(`
+`).some((line) => ACL_READER.test(line));
+}
 async function tracked(path) {
-  return (await $`git ls-files --error-unmatch -- ${path}`.cwd(dirname2(path)).quiet().nothrow()).exitCode === 0;
+  const run = await $`git ls-files --error-unmatch -- ${path}`.cwd(dirname2(path)).quiet().nothrow();
+  const error = run.stderr.toString();
+  if (run.exitCode === 0)
+    return true;
+  if (run.exitCode === 1 || error.includes("not a git repository"))
+    return false;
+  throw new Error(`git could not tell whether ${path} is tracked: ${error.trim() || `exit ${run.exitCode}`}`);
 }
 async function* candidates2(root, unread, depth = 0) {
   let found;
@@ -1083,9 +1288,9 @@ async function* candidates2(root, unread, depth = 0) {
   }
   for (const entry of found) {
     const path = join2(root, entry.name);
-    if (entry.isDirectory() && depth < MAX_DEPTH && !SKIPPED.has(entry.name))
+    if (entry.isDirectory() && depth < MAX_DEPTH && !SKIPPED2.has(entry.name))
       yield* candidates2(path, unread, depth + 1);
-    else if (entry.isFile() && !TEMPLATE.test(entry.name) && (ENV_FILE.test(entry.name) || COMPOSE_FILE.test(entry.name)))
+    else if (!TEMPLATE.test(entry.name) && (ENV_FILE.test(entry.name) || COMPOSE_FILE.test(entry.name)) && await isFileEntry(entry, path))
       yield path;
   }
 }
@@ -1094,24 +1299,26 @@ async function audit(roots) {
   const unread = [];
   for (const root of roots) {
     for await (const path of candidates2(root, unread)) {
-      const readable = await openToOthers(path);
+      const others = await openToOthers(path);
+      const readable = others || await sharedWith(path);
+      const group = readable && !others ? true : undefined;
       const name = path.slice(path.lastIndexOf("/") + 1);
       if (ENV_FILE.test(name)) {
         const isTracked = await tracked(path);
         if (readable || isTracked)
-          exposed.push({ path, readable, tracked: isTracked });
+          exposed.push({ path, readable, ...group && { group }, tracked: isTracked });
         continue;
       }
       const secrets = readable ? inlineSecrets(await Bun.file(path).text()) : [];
       if (secrets.length > 0)
-        exposed.push({ path, readable, tracked: false, secrets });
+        exposed.push({ path, readable, ...group && { group }, tracked: false, secrets });
     }
   }
   return { exposed: exposed.sort((a, b) => a.path.localeCompare(b.path)), unread };
 }
 
 // src/fix.ts
-import { chmod as chmod2, chown, rm as rm2, stat as stat3, writeFile as writeFile2 } from "fs/promises";
+import { chmod as chmod2, chown as chown2, lstat, rm as rm2, stat as stat3 } from "fs/promises";
 import { dirname as dirname3, join as join3 } from "path";
 var MAP_ENTRY = /^(\s*)(["']?)([A-Z0-9_]+)\2(\s*:)(.*)$/;
 var LIST_ENTRY = /^(\s*-[ \t]*)(["']?)([A-Z0-9_]+)=(.*)$/;
@@ -1173,6 +1380,15 @@ function envLine(key, value) {
   return value.includes("'") || value.includes(`
 `) ? undefined : `${key}='${value}'`;
 }
+async function isLink(path) {
+  try {
+    return (await lstat(path)).isSymbolicLink();
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
 async function resolved(path) {
   const run = Bun.spawn(["docker", "compose", "-f", path, "config", "--format", "json"], { cwd: dirname3(path), stdout: "pipe", stderr: "ignore", stdin: "ignore" });
   const [out, code] = await Promise.all([new Response(run.stdout).text(), run.exited]);
@@ -1183,9 +1399,9 @@ function gainedBy(before, after, key) {
   const had = new Set(services(before).filter(([, service]) => service.environment?.[key] !== undefined).map(([name]) => name));
   return services(after).filter(([name, service]) => service.environment?.[key] !== undefined && !had.has(name)).map(([name]) => name);
 }
-async function shutOthersOut(path) {
+async function shutOthersOut(path, group = false) {
   try {
-    await chmod2(path, (await stat3(path)).mode & 504);
+    await chmod2(path, (await stat3(path)).mode & (group ? 448 : 504));
     return true;
   } catch (error) {
     if (error.code === "EPERM")
@@ -1193,13 +1409,14 @@ async function shutOthersOut(path) {
     throw error;
   }
 }
-async function fixCompose(path) {
+async function fixCompose(path, group = false) {
   const env = join3(dirname3(path), ".env");
   const compose = await Bun.file(path).text();
   const envBefore = await Bun.file(env).exists() ? await Bun.file(env).text() : undefined;
   const dotenv = parseDotenv(envBefore ?? "");
   const known = entries(dotenv);
   const fix = { path, env, moved: [], left: [], open: [] };
+  const linked = await isLink(env);
   const lines = compose.split(`
 `).map((line) => {
     const entry = composeEntry(line);
@@ -1210,6 +1427,10 @@ async function fixCompose(path) {
       fix.left.push({ key, why: entry.unmovable });
       return line;
     }
+    if (linked) {
+      fix.left.push({ key, why: "its .env is a symbolic link" });
+      return line;
+    }
     if (entry.value.replaceAll("$$", "").includes("$")) {
       fix.left.push({ key, why: "its value reads another variable" });
       return line;
@@ -1236,7 +1457,7 @@ async function fixCompose(path) {
     await move(fix, compose, lines.join(`
 `), envBefore, serializeDotenv(dotenv));
   for (const file of [path, env]) {
-    if (await Bun.file(file).exists() && !await shutOthersOut(file))
+    if (!(file === env && linked) && await Bun.file(file).exists() && !await shutOthersOut(file, group))
       fix.open.push(file);
   }
   return fix;
@@ -1246,15 +1467,15 @@ async function move(fix, compose, composeAfter, envBefore, envAfter) {
   const docker = Bun.which("docker") !== null;
   const before = docker ? await resolved(path) : undefined;
   if (envBefore === undefined) {
-    await writeFile2(env, envAfter, { mode: 384 });
+    await writeAtomic(env, envAfter);
     const { uid, gid } = await stat3(path);
     try {
-      await chown(env, uid, gid);
+      await chown2(env, uid, gid);
     } catch {}
   } else {
-    await writeFile2(env, envAfter);
+    await writeAtomic(env, envAfter);
   }
-  await writeFile2(path, composeAfter);
+  await writeAtomic(path, composeAfter);
   if (!docker) {
     fix.check = "no docker";
     return;
@@ -1268,11 +1489,11 @@ async function move(fix, compose, composeAfter, envBefore, envAfter) {
     fix.check = "same";
     return;
   }
-  await writeFile2(path, compose);
+  await writeAtomic(path, compose);
   if (envBefore === undefined)
     await rm2(env);
   else
-    await writeFile2(env, envBefore);
+    await writeAtomic(env, envBefore);
   fix.check = "rolled back";
   fix.left.push(...fix.moved.map((key) => {
     const gained = after === undefined ? [] : gainedBy(before, after, key);
@@ -1316,9 +1537,9 @@ function shown(path) {
 async function fixAll(exposed, json) {
   const fixed = [];
   let left = false;
-  for (const { path, readable, tracked, secrets } of exposed) {
-    const fix = secrets === undefined ? undefined : await fixCompose(path);
-    const open = fix?.open ?? (readable && !await shutOthersOut(path) ? [path] : []);
+  for (const { path, readable, group, tracked, secrets } of exposed) {
+    const fix = secrets === undefined ? undefined : await fixCompose(path, group === true);
+    const open = fix?.open ?? (readable && !await shutOthersOut(path, group === true) ? [path] : []);
     if (fix !== undefined)
       fixed.push(fix);
     left ||= tracked || open.length > 0 || (fix?.left.length ?? 0) > 0;
@@ -1328,7 +1549,7 @@ async function fixAll(exposed, json) {
       ...fix === undefined || fix.moved.length === 0 ? [] : [`moved ${fix.moved.join(", ")} into ${shown(fix.env)}`],
       ...fix?.left.map(({ key, why }) => `left ${key} in place: ${why}`) ?? [],
       ...fix?.check === undefined ? [] : [CHECKS[fix.check]],
-      ...open.map((file) => `another account owns ${file === path ? "it" : shown(file)}, so it stays readable: sudo chmod o-rwx ${quoted2(shown(file))}`),
+      ...open.map((file) => `another account owns ${file === path ? "it" : shown(file)}, so it stays readable: sudo chmod go-rwx ${quoted2(shown(file))}`),
       ...readable && !open.includes(path) ? ["now unreadable by other accounts"] : [],
       ...tracked ? [`tracked by git: git rm --cached ${quoted2(shown(path))}, then ignore it`] : []
     ];
@@ -1368,11 +1589,11 @@ async function audit2(args) {
     return 0;
   }
   const uid = process7.getuid?.();
-  for (const { path, readable, tracked, secrets } of exposed) {
+  for (const { path, readable, group, tracked, secrets } of exposed) {
     const sudo = uid !== undefined && uid !== 0 && (await stat4(path)).uid !== uid ? "sudo " : "";
     const problems = [
       ...secrets === undefined ? [] : [`writes out ${secrets.join(", ")}: ev audit --fix moves the values into a .env beside it`],
-      ...readable ? [`readable by any account: ${sudo}chmod o-rwx ${quoted2(shown(path))}`] : [],
+      ...readable ? [group === true ? `readable by its group or an ACL: ${sudo}chmod go-rwx ${quoted2(shown(path))}` : `readable by any account: ${sudo}chmod o-rwx ${quoted2(shown(path))}`] : [],
       ...tracked ? [`tracked by git: git rm --cached ${quoted2(shown(path))}, then ignore it`] : []
     ];
     console.log(`${shown(path)}
@@ -1431,6 +1652,7 @@ async function missing(args) {
 // src/commands/edit.ts
 var DEFAULT_FILE = ".env";
 var TRAILING_NEWLINE = /\r?\n$/;
+var KEY_NAME = /^[A-Z_][\w.-]*$/i;
 var setUsage = `ev set KEY [file]
 
 Sets KEY in the file (.env by default, created when missing), replacing its line in place or appending one. The value is read from stdin, or from -F <file>, so it never appears in a command line; --empty sets it to an empty value.
@@ -1457,6 +1679,10 @@ async function readValue(from) {
     fail("the value is empty, nothing was written: --empty sets an empty value");
   return input.replace(TRAILING_NEWLINE, "");
 }
+function checkKey(key) {
+  if (!KEY_NAME.test(key))
+    badUsage(`${JSON.stringify(key)} is not a valid key: letters, digits, _, . and - only, not starting with a digit`);
+}
 async function readOrEmpty(path) {
   return await Bun.file(path).exists() ? readEnv(path) : { lines: [] };
 }
@@ -1472,11 +1698,15 @@ async function set(args) {
 ${setUsage}`);
   if (parsed.values.empty === true && parsed.values.file !== undefined)
     fail("--empty and -F exclude each other");
+  checkKey(key);
   const value = parsed.values.empty === true ? "" : await readValue(parsed.values.file);
-  const file = await readOrEmpty(target);
-  setLine(file, key, value);
-  await writeEnv(target, file);
-  console.log(`${target}: ${key}=${maskValue(key, value).replaceAll(`
+  const file = await withLocks([target], async () => {
+    const current = await readOrEmpty(target);
+    setLine(current, key, value);
+    await writeEnv(target, current);
+    return current;
+  });
+  console.log(`${target}: ${key}=${maskValue(key, value, await loadKnown(process.cwd(), [file])).replaceAll(`
 `, "\\n")}`);
   return 0;
 }
@@ -1487,14 +1717,19 @@ async function unset(args) {
     fail(`missing KEY
 
 ${unsetUsage}`);
-  const file = await readEnv(target);
-  if (removeKey(file, key) === 0)
-    fail(`${key} is not set in ${target}`, 1);
-  await writeEnv(target, file);
+  await withLocks([target], async () => {
+    const file = await readEnv(target);
+    if (removeKey(file, key) === 0)
+      fail(`${key} is not set in ${target}`, 1);
+    await writeEnv(target, file);
+  });
   console.log(`${target}: removed ${key}`);
   return 0;
 }
 async function transfer(key, from, to, newKey, replace) {
+  checkKey(key);
+  if (newKey !== undefined)
+    checkKey(newKey);
   if (from === to && newKey === undefined)
     fail("--from and --to are the same file");
   const source = await readEnv(from);
@@ -1508,7 +1743,7 @@ async function transfer(key, from, to, newKey, replace) {
   const value = line.value ?? "";
   setLine(target, name, value, newKey === undefined && !entries(target).has(name) ? line.raw : undefined);
   await writeEnv(to, target);
-  return { source, value, name };
+  return { source, target, value, name };
 }
 async function mv(args) {
   const parsed = parse(args, mvUsage, {
@@ -1522,9 +1757,11 @@ async function mv(args) {
     fail(`needs KEY, --from and --to
 
 ${mvUsage}`);
-  const { source } = await transfer(key, from, to, undefined, force === true);
-  removeKey(source, key);
-  await writeEnv(from, source);
+  await withLocks([from, to], async () => {
+    const { source } = await transfer(key, from, to, undefined, force === true);
+    removeKey(source, key);
+    await writeEnv(from, source);
+  });
   console.log(`${key}: ${from} -> ${to}`);
   return 0;
 }
@@ -1540,17 +1777,261 @@ async function cp(args) {
     fail(`needs KEY, --from and --to
 
 ${cpUsage}`);
-  const { value, name } = await transfer(key, from, to, as, true);
-  console.log(`${to}: ${name}=${maskValue(name, value).replaceAll(`
+  const { source, target, value, name } = await withLocks([from, to], async () => transfer(key, from, to, as, true));
+  const known = await loadKnown(process.cwd(), [source, target]);
+  console.log(`${to}: ${name}=${maskValue(name, value, known).replaceAll(`
 `, "\\n")}`);
   return 0;
 }
 
+// src/commands/pins.ts
+import { readdir as readdir4, stat as stat5 } from "fs/promises";
+import { join as join5, resolve as resolve2 } from "path";
+
+// src/pins.ts
+import { readdir as readdir3, readFile } from "fs/promises";
+import { join as join4, relative as relative2 } from "path";
+var OPTIONAL2 = /^\s*([A-Z][A-Z0-9_]*)\s*:\s*s\.Optional\(/gm;
+var REACHING = /(?:URL|URI|TOKEN|KEY|SECRET|PASSWORD|DSN|_HOST)(?:_FILE)?$/;
+var SELF = /(?:^|_)(?:PUBLIC|SITE|BASE|APP)_URL$/;
+var RENDERS = /\b(?:testSite|proxyKeyTests)\s*\(/;
+var NOT_NEEDED = /\/\/\s*ev pins:\s*none reached\b/;
+var OVERRIDE = /\boverrideEnv\s*\(/g;
+var KEY = /(?:^|[{,])\s*([A-Z_]\w*)\s*:/gi;
+var TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
+var ENV_TEST = /^\.env\.test(?:\.local)?$/;
+var TEST_ROOTS = ["tests", "test", "__tests__", "e2e", "src"];
+var SKIPPED3 = new Set(["node_modules", ".git", ".kay", "dist", "vendor"]);
+var SCHEMA_CANDIDATES = ["src/env.ts", "env.ts", "src/env/index.ts"];
+var OPENERS = new Set(["(", "[", "{"]);
+var CLOSERS = new Set([")", "]", "}"]);
+var QUOTES = new Set(["'", '"', "`"]);
+async function exists(path) {
+  return Bun.file(path).exists();
+}
+async function walk(folder, keep) {
+  const found = [];
+  let entries = [];
+  try {
+    entries = await readdir3(folder, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (SKIPPED3.has(entry.name))
+      continue;
+    const path = join4(folder, entry.name);
+    if (entry.isDirectory())
+      found.push(...await walk(path, keep));
+    else if (entry.isFile() && keep(entry.name))
+      found.push(path);
+  }
+  return found.sort();
+}
+async function testFiles(folder) {
+  const found = [];
+  for (const root of TEST_ROOTS) {
+    found.push(...await walk(join4(folder, root), (name) => TEST_FILE.test(name)));
+  }
+  return found;
+}
+function balanced(text, open) {
+  let depth = 0;
+  let quote = "";
+  for (let index = open;index < text.length; index++) {
+    const char = text[index] ?? "";
+    if (quote !== "") {
+      if (char === "\\")
+        index++;
+      else if (char === quote)
+        quote = "";
+    } else if (QUOTES.has(char)) {
+      quote = char;
+    } else if (OPENERS.has(char)) {
+      depth++;
+    } else if (CLOSERS.has(char) && --depth === 0) {
+      return text.slice(open + 1, index);
+    }
+  }
+  return text.slice(open + 1);
+}
+function topLevel(text) {
+  let depth = 0;
+  let quote = "";
+  let out = "";
+  for (let index = 0;index < text.length; index++) {
+    const char = text[index] ?? "";
+    if (quote !== "") {
+      if (char === "\\")
+        index++;
+      else if (char === quote)
+        quote = "";
+    } else if (QUOTES.has(char)) {
+      quote = char;
+    } else if (OPENERS.has(char)) {
+      out += depth === 0 ? char : "";
+      depth++;
+    } else if (CLOSERS.has(char)) {
+      depth--;
+      out += depth === 0 ? char : "";
+    } else if (depth <= 1) {
+      out += char;
+    }
+  }
+  return out;
+}
+function overriddenNames(source) {
+  const names = new Set;
+  for (const match of source.matchAll(OVERRIDE)) {
+    const args = topLevel(balanced(source, match.index + match[0].length - 1));
+    const object = args.slice(args.indexOf(",") + 1);
+    for (const key of object.matchAll(KEY))
+      names.add(key[1] ?? "");
+  }
+  return names;
+}
+function optionalNames(source) {
+  const start = source.indexOf("defineEnv(");
+  return start === -1 ? [] : [...source.slice(start).matchAll(OPTIONAL2)].map((match) => match[1] ?? "");
+}
+function reachesOutside(name) {
+  return REACHING.test(name) && !SELF.test(name);
+}
+async function schemaFile(folder) {
+  for (const candidate of SCHEMA_CANDIDATES) {
+    const path = join4(folder, candidate);
+    if (await exists(path) && (await readFile(path, "utf8")).includes("defineEnv("))
+      return path;
+  }
+  return;
+}
+async function testEnvKeys(folder) {
+  const keys = new Set;
+  for (const entry of await readdir3(folder, { withFileTypes: true })) {
+    if (!entry.isFile() || !ENV_TEST.test(entry.name))
+      continue;
+    for (const line of parseDotenv(await readFile(join4(folder, entry.name), "utf8")).lines) {
+      if (line.key !== undefined)
+        keys.add(line.key);
+    }
+  }
+  return keys;
+}
+async function pinningPreload(folder) {
+  const path = join4(folder, "bunfig.toml");
+  if (!await exists(path))
+    return;
+  const config = Bun.TOML.parse(await readFile(path, "utf8"));
+  const preloads = [config.test?.preload, config.preload].flat().filter((entry) => typeof entry === "string" && entry.startsWith("."));
+  for (const preload of preloads) {
+    const file = join4(folder, preload);
+    if (!await exists(file))
+      continue;
+    const source = await readFile(file, "utf8");
+    if (source.includes(".env") && source.includes("process.env"))
+      return preload;
+  }
+  return;
+}
+async function checkApp(folder, except = new Set) {
+  const schema = await schemaFile(folder);
+  if (schema === undefined)
+    return;
+  const reaching = optionalNames(await readFile(schema, "utf8")).filter((name) => reachesOutside(name) && !except.has(name));
+  const preload = await pinningPreload(folder);
+  const app = { app: folder, schema: relative2(folder, schema), reaching, unpinned: [], files: [], ...preload !== undefined && { preload } };
+  if (preload !== undefined)
+    return app;
+  const fromEnv = await testEnvKeys(folder);
+  const open = reaching.filter((name) => !fromEnv.has(name));
+  const anywhere = new Set;
+  for (const path of await testFiles(folder)) {
+    const source = await readFile(path, "utf8");
+    const pinned = overriddenNames(source);
+    for (const name of pinned)
+      anywhere.add(name);
+    const unpinned = open.filter((name) => !pinned.has(name));
+    if (RENDERS.test(source) && !NOT_NEEDED.test(source) && unpinned.length > 0)
+      app.files.push({ file: relative2(folder, path), unpinned });
+  }
+  app.unpinned = open.filter((name) => !anywhere.has(name));
+  return app;
+}
+
+// src/commands/pins.ts
+var usage2 = `ev pins [dir] [--except NAME,...]
+
+Checks that an app's tests pin the env that reaches outside.
+Reads the app's env schema (the file calling defineEnv, src/env.ts) and lists its optional URL, key, token, secret, password and host variables, then the ones no \`.env.test\` entry, test-level overrideEnv or local bunfig preload dropping what .env sets pins, and each test file that calls testSite or proxyKeyTests without pinning them all.
+A file whose pages reach none of them says so with a \`// ev pins: none reached, <why>\` comment.
+The dir is an app, or a monorepo holding apps one level down (the current folder by default).
+Reads variable names only, never a value.
+Exits 0 when everything is pinned, 1 when something is not, 2 on a usage error.`;
+var options2 = {
+  json: jsonOption("each app with its reaching, unpinned variables and flagged test files"),
+  except: { type: "string", description: "comma-separated variables to leave out, as ones that only link back to the app" }
+};
+async function isFolder2(path) {
+  try {
+    return (await stat5(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function apps(dir, except) {
+  const own = await checkApp(dir, except);
+  if (own !== undefined)
+    return [own];
+  const found = [];
+  for (const entry of (await readdir4(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules")
+      continue;
+    const app = await checkApp(join5(dir, entry.name), except);
+    if (app !== undefined)
+      found.push(app);
+  }
+  return found;
+}
+function failing(app) {
+  return app.unpinned.length > 0 || app.files.length > 0;
+}
+function name(app, root) {
+  return app.app === root ? app.app.split("/").at(-1) ?? app.app : app.app.slice(root.length + 1);
+}
+async function pins(args) {
+  const parsed = parse(args, usage2, options2, { positionals: ["[dir]"] });
+  const json = parsed.values.json === true;
+  const root = resolve2(parsed.positionals[0] ?? ".");
+  const except = new Set((parsed.values.except ?? "").split(",").map((entry) => entry.trim()).filter((entry) => entry !== ""));
+  if (!await isFolder2(root))
+    fail(`${root} is not a folder`);
+  const found = await apps(root, except);
+  if (found.length === 0)
+    fail(`no env schema (a defineEnv call in src/env.ts) in ${root} or its folders`);
+  if (json) {
+    printJson(found.map((app) => ({ ...app, app: name(app, root) })));
+    return found.some(failing) ? 1 : 0;
+  }
+  for (const app of found) {
+    const label = name(app, root);
+    if (!failing(app)) {
+      ok(label, app.preload === undefined ? `${app.reaching.length} reaching variables pinned` : `every variable pinned by ${app.preload}`);
+      continue;
+    }
+    console.log(`${label}: ${app.reaching.length} optional variables reach outside`);
+    if (app.unpinned.length > 0)
+      console.log(`  unpinned by .env.test or any overrideEnv: ${app.unpinned.join(", ")}`);
+    for (const { file, unpinned } of app.files)
+      console.log(`  ${file} renders a page without pinning: ${unpinned.join(", ")}`);
+  }
+  return found.some(failing) ? 1 : 0;
+}
+
 // src/commands/read.ts
 var {$: $2 } = globalThis.Bun;
 var listUsage = `ev list [file]
 
-Prints every key of the folder's .env* files, or of one file, with secret values masked: a few leading characters and the length under a key named like TOKEN, SECRET, PASSWORD, KEY, PRIVATE or DSN, and the password and tokens of any URL.
+Prints every key of the folder's .env* files, or of one file, with secret values masked: a few leading characters and the length under a key named like TOKEN, SECRET, PASSWORD, PASS, PWD, KEY, PRIVATE, DSN, AUTH, SALT or COOKIE, any value equal to a secret of the folder's .env* files, and the password and tokens of any URL.
 
 Exits 0 when it printed them, 1 when there is no .env* file, 2 on a usage error.`;
 var getUsage = `ev get KEY [file]
@@ -1558,10 +2039,16 @@ var getUsage = `ev get KEY [file]
 Prints the masked value of one key, from every .env* file that sets it or from one file.
 
 Exits 0 when the key is set, 1 when it is not set anywhere, 2 on a usage error.`;
-function display(key, value) {
-  return maskValue(key, value).replaceAll(`
+function display(key, value, known) {
+  return maskValue(key, value, known).replaceAll(`
 `, "\\n").replaceAll("\r", "\\r");
 }
+async function readAll(names) {
+  const files = [];
+  for (const name of names)
+    files.push([name, await readEnv(name)]);
+  return { files, known: await loadKnown(process.cwd(), files.map(([, file]) => file)) };
+}
 async function list(args) {
   const parsed = parse(args, listUsage, {});
   const [file] = parsed.positionals;
@@ -1569,9 +2056,10 @@ async function list(args) {
   if (names.length === 0)
     fail("no .env* file in this folder", 1);
   const rows = [];
-  for (const name of names) {
-    for (const [key, value] of entries(await readEnv(name)))
-      rows.push([name, key, display(key, value)]);
+  const { files, known } = await readAll(names);
+  for (const [name, file] of files) {
+    for (const [key, value] of entries(file))
+      rows.push([name, key, display(key, value, known)]);
   }
   if (rows.length > 0)
     console.log(table(rows));
@@ -1586,10 +2074,11 @@ async function get(args) {
 ${getUsage}`);
   const names = file === undefined ? await envFiles() : [file];
   const rows = [];
-  for (const name of names) {
-    const value = entries(await readEnv(name)).get(key);
+  const { files, known } = await readAll(names);
+  for (const [name, file] of files) {
+    const value = entries(file).get(key);
     if (value !== undefined)
-      rows.push([name, display(key, value)]);
+      rows.push([name, display(key, value, known)]);
   }
   if (rows.length === 0)
     fail(`${key} is not set in ${file ?? "any .env* file"}`, 1);
@@ -1609,7 +2098,7 @@ Exits 0 when it printed them, 1 when git cannot show the file, 2 on a usage erro
 var REVISION = /^([^:]+):(.+)$/;
 async function grep(args) {
   const parsed = parse(args, grepUsage, { "ignore-case": { type: "boolean", short: "i", description: "match the key whatever its case" } });
-  const [source, ...files] = parsed.positionals;
+  const [source, ...given] = parsed.positionals;
   if (source === undefined)
     fail(`missing the regex
 
@@ -1620,12 +2109,13 @@ ${grepUsage}`);
   } catch (error) {
     fail(`${source} is no valid regular expression: ${error instanceof Error ? error.message : String(error)}`);
   }
-  const names = files.length === 0 ? await envFiles() : files;
+  const names = given.length === 0 ? await envFiles() : given;
   const rows = [];
-  for (const name of names) {
-    for (const [key, value] of entries(await readEnv(name))) {
+  const { files, known } = await readAll(names);
+  for (const [name, file] of files) {
+    for (const [key, value] of entries(file)) {
       if (pattern.test(key))
-        rows.push([name, key, display(key, value)]);
+        rows.push([name, key, display(key, value, known)]);
     }
   }
   if (rows.length === 0)
@@ -1641,10 +2131,14 @@ async function show(args) {
     fail(`give <rev>:<file>
 
 ${showUsage}`);
-  const shown = await $2`git show ${`${revision}:${path}`}`.quiet().nothrow();
+  if (revision.startsWith("-"))
+    fail(`${revision} is not a revision: it reads as a git option`);
+  const shown = await $2`git show --end-of-options ${`${revision}:${path}`}`.quiet().nothrow();
   if (shown.exitCode !== 0)
     fail(`git show ${revision}:${path} failed: ${shown.stderr.toString().trim()}`, 1);
-  const rows = [...entries(parseDotenv(shown.stdout.toString()))].map(([key, value]) => [key, display(key, value)]);
+  const file = parseDotenv(shown.stdout.toString());
+  const known = await loadKnown(process.cwd(), [file]);
+  const rows = [...entries(file)].map(([key, value]) => [key, display(key, value, known)]);
   if (rows.length > 0)
     console.log(table(rows));
   return 0;
@@ -1668,6 +2162,7 @@ process8.exitCode = await runCli({
     mv: { run: mv, summary: "move a key from one file to another" },
     diff: { run: diff, summary: "keys set in one file and not the other" },
     missing: { run: missing, summary: "keys of .env.example that .env lacks" },
+    pins: { run: pins, summary: "the env vars reaching outside that an app's tests leave to a developer's env" },
     audit: { run: audit2, summary: ".env files others can read or git tracks, compose files writing secrets out" }
   },
   aliases: { ls: "list" }